事実・推論・未知を混同しない：AIとの開発で完了報告を読む

「主要なコンテンツはすでにHTMLに含まれているので、サイトは速くなり、SEOも改善しました。」

この一文は、根拠の強さが異なる結論をつないでいます。前半は出力ファイルを読めば確認できますが、後半には速度と検索パフォーマンスの証拠が別途必要です。前半が正しくても、後半まで検証済みとはいえません。

AIと協働するときは、完了報告を一文ずつ読む価値があります。「テストは通りましたか」と聞くだけでなく、その文が実際の観察を述べているのか、判断を示しているのか、それとも未知の結果をすでに起きたこととして扱っているのかを問うほうが役に立ちます。

事実には、どこを観察したかを示す必要があります

このサイトをVueからAstroのネイティブな構成へ再構築した際、明確な要件の一つは、URLを直接開くと、返されるHTMLにそのページの主要なコンテンツが含まれていることでした。

その根拠を示すには、ビルド後のHTMLを読み、本文とタイトルが存在することを確認できます。ソースコードにコンポーネントが書かれているだけでは不十分です。この観察からいえるのは「この出力ファイルには本文がある」ということです。「すべてのページに本文がある」と述べるには、どのページまで確認したのかも確かめる必要があります。

事実には出典だけでなく、範囲も必要です。ある一ページ、今回のビルド、ローカル環境、本番サーバーは、それぞれ異なる観察対象です。範囲を省くと、もともとは正確だった報告が、過剰な保証になりかねません。

同じように、コンポーネントのファイルを見つけても、確認できるのはファイルの存在だけです。旧サイトの機能だったと述べるには、利用への導線と、実際に使われていた関係も確認する必要があります。このサイトの再構築では、技術で絞り込む操作が追加されました。後から調べると、旧サイトには関連するコンポーネントが残っていましたが、ページからは参照されていませんでした。引き継ぐべきだったのは、作品カテゴリの切り替えです。

この種の誤りは、測定を待たなくても見つけられます。「ファイルが存在する」と「その機能を提供していた」を分ければ、不足している証拠が見えてきます。

推論は残しても、そこに至った理由を説明します

「このサイトは主に読んでもらうためのものなので、本文をビルド時に生成することは、今回のコンテンツ方針に合っています。」これはアーキテクチャ上の判断です。

その判断には根拠があります。サイトには紹介、作品、記事を載せる必要があり、初期HTMLで内容を読めることも要件として明示されていました。これらの条件は静的なコンテンツを選ぶ理由になりますが、すべてのサイトが従うべき正解になるわけではありません。

推論は、信頼できない主張の言い換えではありません。設計や開発には判断が必要です。問題は、その根拠と、どのような条件で見直す必要があるかを説明しているかどうかです。

完了報告に含まれる推論は、たとえば次のように書けます。

今回は、読者がURLを直接開くだけで本文を読めるようにしたいため、ページの内容をビルド時に生成します。これは現在のコンテンツ要件に合っています。今後、ログイン後のリアルタイム操作を多く追加する場合は、それらの機能の実装方法を改めて検討する必要があります。

これは説明の書き方の例であり、新たな性能テストの結果ではありません。選択した理由を残し、判断の前提も伝えています。

未知の事項は、次に確かめる問いにつなげます

読み込み速度を測定していないからといって、サイトが必ず遅いわけではありません。検索流入のデータがないからといって、アーキテクチャに価値がないわけでもありません。いえるのは、今回の報告ではその二つを成果として扱えないということです。

未知の事項も、具体的に書けます。

まだ答えられない問い	答えが必要な場合に追加できる確認
新版は旧版より速いですか？	比較可能な条件で新旧を測定し、対象ページ、端末、ネットワーク環境を示します。
スマートフォンで快適に読めますか？	サイト所有者が実際に読み、幅、段落のリズム、内容の順序を確認します。
本番サーバーは正しいページを返しますか？	デプロイ後に実際のURLへリクエストし、ステータス、本文、リソースを照合します。
記事によって読者の作品理解は深まりますか？	読者のフィードバックや、その問いに適した観察データを補います。

これらは今後の検証の方向であり、このサイトですでに実施した測定ではありません。

「すべての状況をテストしたわけではありません」だけでは範囲が広すぎて、読者は次の行動を決められません。今回確認したのがローカル出力だけなら、本番サーバーは未確認だと直接書きます。内容と技術の確認は済んでいても、見た目は人の確認を待っているなら、見た目を未承認の項目として挙げます。制限を対象の問いに即して書くほど、作業の段取りをつけやすくなります。

混ざった主張は、個別に確認できるまで分けます

次の文は、完了報告の悪い例として意図的に組み立てたもので、実際のツール出力ではありません。

草稿は記事システムに組み込まれ、チェックも通ったので、記事は公開でき、読者もサイトを理解しやすくなるはずです。

この文は、少なくともいくつかの独立した問いに分ける必要があります。

草稿が組み込まれたかどうかは、コンテンツの読み込み元とローカルプレビューを確認します。チェックが通ったというなら、項目と結果を示す必要があります。公開できるかどうかには、内容と公開範囲についてサイト所有者の判断が必要です。読者が理解しやすくなるかどうかは、その三つでは答えられません。

より明確にするなら、次のように説明できます。

記事はローカルプレビューに組み込まれていますが、草稿のままです。技術的なチェックの結果は別途示します。内容、公開範囲、読みやすいレイアウトについては、サイト所有者が確認します。この記事には読者の理解度の測定がないため、その改善を成果として報告しません。

毎回この形式を使う必要はありませんが、一文ずつ独立して成り立つように書くべきです。接続詞では、証拠の不足を埋められません。

証拠が変わったら、まず元の結論を訂正します

仮に、完了報告で「草稿は本番出力に含まれていません」と書いた後に、草稿のURLが見つかったとします。末尾に「例外がある可能性は残ります」と付け加えるだけでは不十分です。古いビルドファイルを消し切れていなかったのか、コンテンツの状態を読み違えたのか、それとも本番用のクエリで本当にフィルタリングが漏れたのかを調べ直す必要があります。

これは仮定のトラブルシューティングであり、このサイトで新たに見つかった事故ではありません。重要なのは訂正の順序です。まず成立しなくなった結論を撤回し、原因を探し、修正後に該当する出力をもう一度読みます。「完了」という見出しを残したまま、実際には未完了であることを読者に注記から推測させてはいけません。

引き渡す前に、強い結論を一つ選んで確かめます

毎回の協働を、一語ずつ裁く場にする必要はありません。まずは「すべて完了」「漏出なし」「速くなった」「公開済み」といった、判断に影響する文を選び、根拠と範囲を問い直せます。

観察を示せるなら、その範囲内で事実として書きます。要件から導いた選択なら、推論の前提を説明します。データがなければ、具体的な未知の事項と検証の方向を残します。三者を分けることで、人はその判断を採用するか、確認を一つ追加するか、それとも公開を見送るかを決められます。

この記録の範囲

この記事は、このサイトの再構築、機能の根拠確認、コンテンツ公開ルールをもとに、完了報告の読み方を整理したものです。冒頭の引用、完了報告の悪い例、トラブルシューティングの場面はいずれも説明用であり、元のチャット、テスト記録、新たな測定ではありません。この方法によって開発効率、検索パフォーマンス、読者の理解度が改善したとは主張していません。