コードから事実検証済みマニュアルを作る3〜4段階パイプライン

使う場面

「このアプリの管理者マニュアルを作って」「引き継ぎ資料を残して」のように、既存コードベースの中身（設定値・データの流れ・使っている外部サービス）を、正確さを保ったまま人間が読めるドキュメントに変換する依頼。読者層が非エンジニア（現場スタッフ・リーダー等）の場合、専門用語を除去する追加ステップが要る。

課題

• 監督（メインの対話エージェント）が自分で全ソースを読んで一気に文章化すると、トークンを大量消費し、かつ「たぶんこうだろう」という推測が事実として紛れ込みやすい。
• 逆に下位モデルに丸投げすると、断定できない箇所まで自信満々に書いてしまう（ハルシネーション）か、逆に「ここには〇〇の説明が入ります」というプレースホルダーのまま出力を返してくることがある（指示で詳細な表を省略させたときに起きやすい）。
• 読者層に応じた文体変換（専門用語除去、敬体→体言止め等）を内容生成と同じステップでやらせると、事実が変わっていないかの検証がしづらい。

解決パターン（ステージを分離し、各段を別モデル・別チェックにする）

1. 抽出ステージ（中容量モデルのサブエージェント、例: Claude Sonnet相当）

   • 対象ソースファイルを全文読ませ、「コードから確認できる事実だけ」を構造化して書き出させる。
   • 指示に必ず入れる一文: 「推測で埋めない。確認できなかった項目は『※要確認』と明記する」。
   • 出力形式（章立て・表）をこちらで指定し、対象読者（エンジニア/非エンジニア）は最初はエンジニア寄りでよい（正確さ優先）。

2. 検証ステージ（監督が自分で行う、コストを抑えるため軽いgrep/read中心）

   • 抽出ステージが挙げた「固有の識別子・数値・関数名」を、監督自身がソースに対して独立にgrep/readして裏取りする。全部は無理でも、影響が大きい・一意性が高い項目（ID、しきい値、条件式）を優先的に当たる。
   • 一致すれば信頼度が上がり、以降のステージは安心して委譲できる。ここを省略すると、下流の平易化・文体変換ステージで誤りごと"磨かれて"しまい、誤りだと気づきにくくなる。

3. 読者層適応ステージ（必要な場合のみ・安い/速いモデルへ委譲）

   • 対象読者が非技術者なら、検証済みの技術文書を渡し「事実は一切変えない・専門用語は使わない・技術的な識別子は本文から追い出して巻末の参考情報セクションにまとめる」という指示で書き換えさせる。
   • プレースホルダー化を防ぐ: 「詳細は省いてよい」と指示すると、モデルが実際の内容の代わりに「（ここには〇〇の一覧が入ります）」という説明文だけを返すことがある。出力を人間に渡す前に、こうした自己言及的なプレースホルダー文が残っていないか監督が確認し、残っていたらその節だけ実データで埋め直す。

4. 文体統一ステージ（さらに安い/速いモデルへ委譲、内容ステージとは独立に実行）

   • 「敬体→体言止め」のような文体だけの変換は、内容と混ぜずに最後の独立したパスにする。プロンプトに「内容・数値・固有名詞は一切変えない、文末表現だけ変える」と明記。
   • 変換後、元の禁止パターン（例: 「です。」「ます。」）が残っていないかを監督がgrepで機械的に確認する。1〜2箇所の変換漏れが起きやすいので、必ずスキャンする。

補足

• 各ステージを別々の呼び出しにすることで、失敗した時にどのステージが原因か特定しやすくなる（内容の誤りか、文体変換の副作用か）。
• 安いモデルの呼び出しがリクエストサイズ上限（413エラー等）に当たることがある。フォールバック連鎖（同格程度の別プロバイダへ自動切替）を組んでおくと、単発の失敗で処理全体を止めずに済む。
• 検証ステージ・プレースホルダー確認・文体スキャンはいずれも監督が「読んで確認するだけ」の軽い作業なので、重い生成作業をモデルに渡しながらも品質担保の責任は監督側に残せる。