0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@okikusan-public(okiku)

コーディングエージェントに何を読ませ、何を残すか：Anthropic・GitHub・OpenAI の設計を突き合わせる

0
Posted at

この記事は生成AIに調査・要約してもらった内容を、自分用の備忘録として整理したものです。

TL;DR

何の話か
コーディングエージェント（Claude Code、Codex、Cursor など）に実装を任せるとき、リポジトリに置く指示書やドキュメントを何にどこまで書くべきか。Anthropic・GitHub・OpenAI が公開している設計と、国内企業の実務レポートを突き合わせて整理しました。

なぜドキュメントの話になるのか
エージェントは、実行中にコンテキストへ読み込めない情報を参照できません。Slackのスレッドや人の頭の中にある判断は、エージェントから見ると存在しないのと同じです。しかも実装だけが速くなるので、ボトルネックは計画・レビュー・デプロイへ移ります。

ところが、丁寧に書くほど良いわけではない
ETH Zurich らの研究では、AGENTS.md のようなコンテキストファイルを与えてもタスク成功率は改善せず、推論コストが平均20%以上増えました。OpenAI も大きな AGENTS.md を実際に試して破綻させ、約100行の目次に切り替えています。国内では、責務を分ける運用に変えて仕様量を84.5%削減した事例があります（既存サービスの改修20件の中央値）。

3社が別々の経路で同じ形に着地している

  1. 毎回読ませるファイルは薄くする（100行から1ページ程度）。コードを読めば分かることは書かない
  2. 情報は工程の境目でファイルとして受け渡す。チャット履歴を引き継ぎ手段にしない
  3. 現状の事実は生成し、判断の理由は人が書く
  4. 「守ってください」と書くのではなく、フックやlinterで破れない仕組みにする

結論
勝負どころは書く量ではなく、食い違ったときにどのファイルを信じるかを決めることと、古くなったことを機械的に検知する仕組みを持つことです。

1. この記事の前提

想定読者

コーディングエージェントを業務で使っているが、リポジトリに置く指示書やドキュメントを何にどこまで書くべきか決めきれていない人。特定のツールの使い方ではなく、リポジトリの情報設計の話をします。

この記事で使う言葉

用語 この記事での意味
SDLC 要件定義から設計・実装・テスト・リリース・運用までの一連の流れ
コーディングエージェント 指示を受けてコードを読み書きし、テスト実行やPR作成まで自分で進めるAI
コンテキスト エージェントが1回の作業で読み込める情報の総量。有限で、埋まるほど精度が落ちる
コンテキストファイル リポジトリ直下に置き、エージェントが毎回読む指示書。AGENTS.md（Codex、Cursor などが対応する横断標準）、CLAUDE.md（Claude Code専用。AGENTS.mdはネイティブに読まない）など
ゲート 次の工程へ進むための関門。承認・却下の権限を持つのは人で、エージェントは手前まで進めるだけ。低リスクの変更は自動通過に寄せることもある
ハーネス（harness） エージェントの周りに用意する環境一式。指示書、ドキュメント、テスト、lint、CI、権限設定まで含む
仕様駆動開発（SDD） 仕様のMarkdownを先に書き、そこから計画・タスク・実装をエージェントに導出させるやり方
ADR 設計判断とその理由を1件1ファイルで残す記録（Architecture Decision Record）
ドリフト ドキュメントと実装が時間とともに食い違っていく現象
自動評価（eval） 「この指示でこのタスクを投げたらこう振る舞ってほしい」を集めたテストセット。指示を変えたときの劣化を検出する

扱う問題

「AIにコードを書かせる」段階の話は扱いません。その手前と後ろにある、次の2つを扱います。

  1. エージェントが正しく判断するために、どの情報をどこに置くか
  2. その情報が古くなったことを、どう機械的に検知するか

記事の構成

2章で、なぜ工程よりドキュメントが問題になるのかを確認します。3章で Anthropic・GitHub・OpenAI の設計を並べます。この3つは1つの理論とその実践例という関係ではなく、同じ問題に別々に取り組んだ独立した設計です。本文に出てくる「AI-native SDLC」は Anthropic が自社のガイドに付けた名前で、GitHub や OpenAI が自分の取り組みをそう呼んでいるわけではありません。4章と5章は工程側（成果物をどの順で受け渡すか）、6章は環境側（エージェントの周囲に何を置くか）から各社の設計を見ます。7章から12章は、その環境に何を置き、どう古くならないよう保つかの整理です。13章は人の役割、14章は各社の設計への批判です。

2. なぜいまドキュメントの話なのか

コードはもうボトルネックではない

Anthropic の Applied AI チームが2026年8月に公開した「AI-native SDLC プレイブック」は、従来の SDLC が「コードを書く工程が最も高価だった時代」に最適化された設計だと指摘しています[1]。工程の順番も、レビューの粒度も、承認の置き場所も、実装が一番時間を食うという前提で決まっている。エージェントが実装を担うと、その前提が崩れます。

人が実装していた時代 エージェントが実装する時代
実装のコスト 全工程の中で最も高い 大幅に下がる
ボトルネック 実装工程 計画・レビュー・デプロイ
レビュー 全差分を人が読めた 人手では追いつかない量になる
例外の承認 定例会議で足りていた 会議の周期が律速になる

安くなったのはコードを書く行為だけで、レビューや承認のコストは下がりません。対象の量が増えるぶん総コストは上がります。実装を10倍速くしても、レビュー待ちが3日あればリードタイムは3日で止まる。セキュリティチームの人員は人間の出力量を前提に決まっているので、エージェントが出力を増やせば、レビュー待ち行列が伸びるか、レビュー不足のまま出荷されるかのどちらかになります。

エージェントに見えない情報は存在しないのと同じ

OpenAI が2026年2月に公開した記事は、この点を強い言い方で書いています。エージェントの視点では、実行中にコンテキストへ取り込めない情報は事実上存在しない。Google Docs、チャットスレッド、人の頭の中にある知識はシステムから見えない[2]。

設計判断をSlackのスレッドで決めて終わりにすると、3か月後に同じ箇所を触るエージェントはその判断を知らないまま作業します。人間なら検索するか隣の人に聞けますが、エージェントにその経路はありません。したがって、Slack・Notion・会議・チケットで生まれた判断を、最終的にリポジトリ内のファイルへ落とす経路が必要になります。

調査側の数字

DORA 2025（Google の開発生産性研究チームによる年次調査、回答者約5,000名）の結論は、AIは増幅器だというもの。高パフォーマンスな組織の強みを拡大し、うまくいっていない組織の機能不全も同じだけ拡大する。ツールの導入より、開発基盤の整備・作業の流れの明確化・チーム間の認識合わせに投資したほうがリターンが大きい、というのが示唆です。同レポートが挙げる7つの組織能力のひとつが「AIがアクセスできる内部データ」で、ドキュメントの出来より、そもそも読める場所にあるかが先だという順序になっています[3]。

State of Docs Report 2026（GitBook による調査、回答者1,131名）では、ドキュメント作成にAIを常用する割合が前年60%から76%へ上がった一方、AI利用のガイドラインを持つチームは44%にとどまります[4]。採用は済んでいて、統制が追いついていない。この記事で扱うのは、その統制側の話です。

3. 三社の設計を並べてみる

ここで扱う3つは、同じ種類のものではありません。互いを参照して作られたものでもなく、各社が同じ問題に別々に取り組んだ結果です。

Anthropic「AI-native SDLC プレイブック」＝ 処方

Anthropic の Applied AI チーム（顧客の導入支援をする部門）が公開した規範的なガイドです。工程別のプレイ（個別の実践項目）の集まりで、各プレイに「何のために」「どうやる」「何で測る」が付いています。規制業種を明確に意識していて、監査証跡や職務分離の話が全体に通っています[1]。

GitHub「Spec Kit」＝ 道具

実際にインストールできるツールです。CLIでリポジトリを初期化すると、仕様駆動開発用のテンプレートとスラッシュコマンドが配置され、複数のエージェントから使えます。3つの中で唯一、今日そのまま試せるものです[5]。

OpenAI「Harness engineering」＝ 報告

社内実験の事後報告です。Anthropic の処方を試した記録ではなく、自社のリポジトリで独立に得た経験の記録です。3人のエンジニアがCodexを駆動し、5か月で約100万行のコードベースに到達。約1,500件のPRがマージされ、手で書かれたコードは0行です。価値は失敗の記述にあります。大きな AGENTS.md に知識を集約する方法を実際に破綻させ、約100行の目次＋階層化された docs/ に移った経緯が書かれています[2]。

並べるとこうなる

Anthropic GitHub OpenAI
種類 処方（ガイド文書） 道具（インストール可能） 報告（社内実験の記録）
中心概念 工程ごとの成果物をコミットして連鎖させる 仕様を出発点にしてループを収束させる エージェントの環境を設計する
陳腐化対策 フックと自動評価、PRレビュー converge によるギャップ検出 定期実行エージェント＋CI検証
こう読むと良い 移行計画のたたき台 明日から動かす実験台 先に踏まれた地雷の記録

呼び方も種類も違いますが、共通点は3つに集約できます。

  1. 必要な情報はリポジトリ内のテキストファイルにする
  2. 工程の境目でファイルとして受け渡す（チャット履歴を引き継ぎ手段にしない）
  3. ループを閉じる（本番やコードから、上流のファイルへ戻す経路を作る）

以降、4章と5章は工程側（成果物の受け渡し順）から、6章は環境側（エージェントの周囲に置くもの）から、それぞれの設計を見ます。

4. Anthropic プレイブック：工程ごとの成果物を連鎖させる

プレイブックの中心は、工程の受け渡し方を変えるという提案です。各工程は成果物をバージョン管理にコミットして終わり、次の工程はそれを読んで始まる[1]。

実線が通常の流れ、点線が戻りの経路です。1周する円環ではなく、戻り辺を持つ有向グラフとして見るのが正確です。2本の点線は戻る深さが違い、浅い方から優先されます。実装が計画からずれただけなら plan.md の戻りで足り、要件そのものに抜けがあれば spec.md まで遡ります。intent.md まで戻すのは前提が崩れたときに限られる、最もコストの高い経路です。ループが閉じるのはMaintain工程で、本番指標が正常範囲を外れた事象を新しい intent.md として書き戻します。ただし戻ってきた意図も自動では通らず、Plan工程の同じゲートを通ります。また再入はトリガーが発火した後に始まるので、誰も気づかない劣化はループに入りません[19]。

コミットの連鎖はそのまま監査証跡になります。誰が何を求め、エージェントが何を出し、誰が承認したかが時系列に残るので、「なぜこれが入ったのか」を後から git log で組み立てられます。規制業種でなくても、障害の事後分析や引き継ぎで同じ効果が出ます。

誰が何をやり、どこで人が止めるか

工程 人がやること エージェントがやること 人のゲート
Plan 発案者が自分の言葉で目的と背景を語り、起草を修正。受理はプロダクトオーナー 対話で意図を引き出し、intent.md に起票 あり
Design プロダクトオーナーがレビュー（自分では書かない） 要件と設計を1セッションで起こし、方針との矛盾を「懸念」として提示 あり
Build 計画を詰める。触るファイル、作業順、証明するテストを名指し 計画に沿って実装。逸れたら plan.md を同じコミットで更新 あり。承認まで plan mode は編集しない
Test 何をもって完了とみなすかを決める 与えられた検証手段で自分の出力を確認してから人に見せる なし。ただしカバレッジのないコードに触る変更は高リスク扱いで人の承認が要る
Deploy 規制対象と重要コードをレビューし、承認 REVIEW.md の観点で多層レビュー。所見は出すが承認・ブロックの権限は持たない リスクで分岐。低リスクは自動承認へ寄せる
Maintain 逸脱の許容範囲と、段階ごとの権限を事前に決める 監視し、範囲を外れたら決められた権限内で調査して報告 起点にはなし。Planに戻って再合流

人のレビューを全工程に均等に置くのではなく、規制対象と重要コードに集約する設計です。バグ修正では失敗するテストを先にコミットし、修正中はテストファイルの編集をフックで禁じます。テストを書き換えて通す抜け道を塞ぐためです。

受理が次を起動する

各成果物は担当者が確認して初めて確定し、確定したことが次の工程の起動条件になります。「レビュー依頼を出したのに誰も気づかない」「承認されたのに着手を忘れる」という待ちが、構造的に発生しません。

  • intent.md の受理 → 要件・設計の工程が動く
  • spec.md の承認 → 実装前に計画を書かせるモード（Claude Code の plan mode）が動く
  • PRのマージ → CI/CDパイプラインが動く
  • 本番指標が正常範囲を外れる → 次の intent.md が書かれる

Maintain工程の異常検知はAIに判断させず、移動平均と標準偏差で正常範囲を定め、逸脱の程度でエージェントの権限を段階的に変えます。軽度ならログのみ、中程度なら読み取り専用で調査、重度でもPRか事前承認済みの手順書までで、勝手に本番を触らせません[1]。

統制は「お願い」と「強制」の二層で持つ

Claude Code の2つの仕組みが前提です。

  • スキル：方針や手順をMarkdownで書いておき、エージェントが必要に応じて読み込む。従わせる強制力はない[6]
  • フック：特定の操作の前後で必ず実行される外部コマンド。許可・ブロックに加えて「尋ねる」モードがあり、指定した人物が承認するまで操作を止める[6]

スキルが違反を稀にし、フックが不可能に近づける。例外を許さない方針には必ずフックを裏に置きます。上の表のゲートは、実際にはこのフックの「尋ねる」モードとブランチ保護で実装されます。会議体や口約束ではなく、承認が下りるまで操作が物理的に止まる形です[1]。

原則は「エージェントは本番ゲートまで自律的に進めるが、そのゲートは越えられない」。書いたエージェントに承認経路がないので、作る人と通す人が分かれます。エージェントは自分の出力を過大評価しがちなので、レビューも承認も同じエージェントに任せると、動かないコードに承認印が付いた状態が本番まで届きます。

既存ツールとの共存

Jira や要件管理ツールに監査人が受け入れている記録がある場合、成果物ごとに次のいずれかを選びます[1]。

  1. リポジトリを正式な記録にする。既存ツール側はコミット内のファイルを参照する
  2. 既存ツールを正式な記録にする。Markdownは作業用の写しで、MCP経由で結果を書き戻す
  3. 相互リンクだけを最低ラインにする。チケットにコミットSHA、MarkdownにチケットIDを持たせる移行期の妥協案

計測指標

各プレイに指標が定義されていて、すべて既存の git・PR・CI から取れます[1]。ドキュメントの本数ではなく、成果物間の時間差と手戻りを見ています。

指標 取り方 何が分かるか
意図から仕様までの時間 intent.md と spec.md のコミット時刻の差 上流の意思決定に何日かかっているか
仕様の追加コミット数 最初の plan.md 以降に spec.md が何回変わったか 要件が固まらないまま実装に入った度合い
初回パス率 実装1回目でそのままマージされた割合 低ければ計画が粗い
計画との一致 マージされた差分が plan.md と合っているか 実装が計画から逸れたまま放置されていないか

5. GitHub Spec Kit：仕様とコードの差を工程で埋める

CLI（specify）でリポジトリを初期化すると、テンプレートとスラッシュコマンド（/speckit.specify など）が配置され、Claude Code や Copilot など複数のエージェントから使えます[5]。

厳密に必須なのは plan の前の specify だけで、clarify checklist analyze は曖昧さが残るときに足す品質ゲートです。コマンドはすべてエージェントが実行しますが、人間の関与の質が工程ごとに違います[5]。

コマンド 人間がやること エージェントがやること
constitution 原則を引数で渡す 原則ファイルを作成・更新
specify 自然言語で何を作るか説明する spec.md を作成。What と Why に限定
clarify 質問に答える（最大5問） 詰まっていない箇所を質問し、回答を spec.md に反映
plan 技術スタック・構成・制約を引数で渡す 渡された技術判断を設計成果物に展開
checklist 生成物をレビューし、抜けがあれば前工程へ戻る 要件の完全性を検査するチェックリストを生成
tasks 引数なしで実行 依存順の tasks.md を生成
analyze 提示された修正案を承認 読み取り専用で仕様・計画・タスクの矛盾を検出
implement 大きな機能は範囲を絞り、段階ごとに確認 タスクを依存順に実行
converge 追記されたタスクを見て implement を再実行 実装を仕様と照合し、抜けをタスクとして追記

技術選択をするのは人間で、エージェントはそれを設計に展開する役です。clarify は逆方向で、エージェントが曖昧な箇所を突いて人間が答えます。末尾の converge は追記専用でコードを編集も削除もせず、書き込みは tasks.md へのタスク追加だけ。抜けがあれば implement と converge を収束するまで繰り返します[5]。

「仕様とコードが乖離する」問題に対して、乖離検出を工程として組み込むという答えですが、方向は一方通行です。コードを仕様に合わせる向きにしか働かないので、仕様そのものが古びた場合は直りません。仕様を実態に合わせ続けるのは人の仕事として残ります。

同系統に Kiro（requirements.md / design.md / tasks.md の3ファイル構成。受入基準に EARS 記法）や OpenSpec（変更のたびに差分で育てる仕様）があります。収束をコマンドとして持つのは Spec Kit の特徴です[7][8]。

仕様に対するテストに通っても保証されるのは仕様との一致だけで、仕様の正しさではありません。悪い仕様は精密に実装されます。小規模な改修では、仕様を書くこと自体がオーバーヘッドになります[8]。

6. OpenAI harness engineering：AGENTS.md は百科事典ではなく目次

4章と5章は、成果物をどの順で受け渡すかという工程側の設計でした。OpenAI の事例は同じ問題に環境側から入ります。工程の順序ではなく、エージェントの周囲に何を置くかの話です。

エージェントの出力が期待に届かないとき、選択肢は3つあります。モデルを替える、プロンプトを工夫する、環境を整える。前2つは効果がセッション単位で消えますが、3つ目はリポジトリに残るので全員とすべてのセッションに効き続ける。そこに投資すべきだ、というのが harness engineering の主張です。

大きな指示書は失敗した

チームは当初、大きな AGENTS.md に知識を集約しました。しかしコンテキストは有限なので、巨大なファイルが実際のタスクに使える分を押し出してしまった。現在は AGENTS.md を約100行の目次として扱い、知識は構造化された docs/ に置いています[2]。

AGENTS.md          # 約100行、目次
ARCHITECTURE.md    # ドメインとパッケージの階層マップ
docs/
├── design-docs/   # 索引つき、検証ステータスあり
├── exec-plans/    # 実装計画。使い捨てメモではなくレビューと版管理の対象
├── generated/     # コードから生成された事実（DBスキーマ等）
├── product-specs/
├── references/    # 外部ドキュメントをローカルに取り込んだもの
├── DESIGN.md
├── FRONTEND.md
├── RELIABILITY.md
└── SECURITY.md

これはCodexでの実践ですが、AGENTS.md 自体はCursorやWindsurfも対応する横断標準です。Claude Codeで使う場合だけ、12章で触れる橋渡しが要ります。

段階的に開示する

すべてを最初に渡さず、必要な情報だけを辿らせます。認証機能を修正するタスクならこう辿ります。

点線の先は、このタスクには不要なので読み込ませません。リポジトリをエージェントが探索できる知識のグラフとして設計する、という発想です。

陳腐化は機械的に検出し、制約は実行可能にする

専用の linter と CI ジョブがドキュメント群の鮮度と相互リンクを検証し、定期実行されるエージェント（doc-gardening）が実際のコードの挙動を反映していない記述を走査して修正PRを作ります[2]。

「ドメイン層からインフラ層を直接参照しない」といった依存の向きの規則は、Markdownに書くだけではエージェントに破られます。目の前のタスクを終わらせる最短経路を取るからです。OpenAI はこれをカスタム linter と構造テストで機械的に強制し、違反したコードはCIで落とします[2]。「守ってくださいとお願いする」より「破れない仕組みを作る」ほうが強い。Anthropic のスキルとフックの二層と同じ思想です。

工程の設計と環境の設計は同じものの別断面

見方 何を設計するか 具体物
工程の連鎖（ループ、有向グラフ） 成果物をどの順で受け渡すか intent.md → spec.md → plan.md → 差分 → PR → インシデント記録
環境（ハーネス） エージェントの周囲に何を置くか コンテキストファイル、docs/、スキル、フック、テスト、評価セット、生成されたFacts

別の話ではありません。グラフの辺を成立させている部品が環境側の中身です。plan.md から差分への辺は、plan modeと「逸れたら同じコミットで更新させる」フックがなければ成立しない。つまり辺の通過条件がゲートで、ゲートの実体はフックです。Anthropic は工程側から、OpenAI は環境側から入って、同じ場所に来ています。以降の7章から12章は環境側に何を置くかの話です。

7. ドキュメントを5つに分類する

以降の分類や層の切り方は公式モデルではなく、参照した各社の設計と実務記事を突き合わせた整理です。分ける理由は、種類ごとに書ける人と古くなったときの検知方法が違うためで、同じ場所に同じ扱いで置くとどれが信用できるか分からなくなります。

分類 内容 例 読み込み
Policy 開発原則・制約 AGENTS.md、原則、スキル 毎回
Decision なぜその設計にしたか ADR、用語集、ドメイン境界 関連箇所を変更するとき
Intent 何を実現したいか intent.md、spec.md、受入基準 その機能を触るとき
Execution どう実装するか plan.md、tasks.md その機能を触るとき
Facts 現在システムがどうなっているか OpenAPI、DBスキーマ、依存グラフ 必要なときだけ

4章の intent.md と spec.md は Intent、plan.md は Execution に入ります。6章の構成では AGENTS.md が Policy、design-docs/ が Decision、product-specs/ が Intent、exec-plans/ が Execution、generated/ が Facts です。呼び名は違っても、両社の置き方はこの5分類に収まります。

下ほど変わりやすく、機械的に生成・検証しやすい。毎回読ませるのは Policy だけに絞ります。ここが膨らむと実際のタスクに使えるコンテキストが減るからです（8章）。何を残すかと、どう読み込ませるかは別問題で、両方を設計する必要があります[9]。

8. コンテキストファイルは薄く保つ

AGENTS.md や CLAUDE.md に丁寧に書けば書くほど精度が上がる、と考えたくなります。反対方向の実証データがあります。

ETH Zurich と LogicStar による研究では、複数のエージェントとLLMにわたって、コンテキストファイルを与えてもタスク成功率は改善せず、推論コストが平均20%以上増加しました。エージェントが指示に忠実に従うためテストや探索が広く深くなり、その分コストが増えていた[10]。

原則 なぜ
コードから読み取れることは書かない エージェントはコードを自分で読める。書き写しても情報は増えず、消費コンテキストだけ増える
コードから推測できない約束だけ書く ビルドとテストのコマンド、命名規約、触ってはいけないパス、過去に繰り返した間違い
短く保つ プレイブックは1ページ以内を推奨。実態と合わない指示は、ないほうがまし[1][6]
同じ間違いを2回したら追記する 予防的な指示は当たるか分からないのに、コンテキストは確実に消費する[1]

OpenAI（約100行の目次）、Anthropic（1ページ以内）、実証研究（薄いほうが良い）が、別々の経路から同じ結論に着地しています。

9. Facts は生成してよい、Why は生成できない

システムの現状を記述する類のドキュメントは、コードから機械的に生成できます。ただし「生成できる」は「生成すべき」ではありません。一度きりの質問ならエージェントにその場でコードを読ませたほうが正確で、無理にパイプラインを作る必要はありません。生成する価値が出るのは、CIで差分を検知したい（10章のドリフト検知は比較対象が要る）、同じ情報を繰り返し参照する、エージェント以外の消費者がいる、のいずれかに当てはまる場合です。

もう1つ効くのが何で生成するかです。下の4つは静的解析ツール（パーサーやコード生成ツール）で機械的に組み立てられるので、LLMを呼ばず、トークンコストはかかりません。CIで毎回回しても問題になりません。逆に、設計判断の要約や複雑な振る舞いの説明のようにLLMでしか作れないものは、再生成のたびにトークンを消費します。頻繁な再生成は避け、「あれば便利」程度に留めるのが妥当です。当てはまるものを docs/generated/ に置き、静的解析が理解できることは静的解析に任せ、LLMには判断が必要な部分だけを担当させます[2]。

生成物 何から生成するか 何に使うか
OpenAPI 定義 ルーティングと型定義 外部インターフェースの把握
DBスキーマ マイグレーションファイル データ構造の把握
依存グラフ import の静的解析 変更の影響範囲の見積もり
モジュールマップ ディレクトリ構成と公開シンボル どこに何があるかの索引

逆に、なぜこの設計にしたのか、どの選択肢を検討して棄却したのかは、コードから生成できません[9]。だから ADR が効いてきます。特に検討して採用しなかった選択肢のセクションです。

## Context
トランザクション整合性が要件。

## Decision
PostgreSQL を採用する。

## Alternatives Considered
DynamoDB — JOIN とトランザクション、運用知見の観点で不採用。

## Consequences
（正・負・中立すべて）

これがないと、文脈を失ったエージェントは毎回同じ議論を蒸し返します。コードから What は分かるが Why は分からない、という当たり前の話が、書き手が高速化したことで急に効いてきます。

10. 陳腐化との戦いは3層になる

検出手段は3種類に分かれます。CIでの実行コストが安い順に並べると、どこまで自動化するかの判断がしやすくなります。

層 何を見るか 手段 コスト
1. 文体・構造 ドキュメント単体の品質 markdownlint、textlint ほぼゼロ
2. 出典との同期 その記述の根拠にしたコードが変わっていないか 出典行のハッシュ比較 ほぼゼロ
3. 意味の整合 コードの挙動と記述が一致しているか AIエージェント（PRトリガー、定期実行） 高い

2層目は、ドキュメント生成時にどのファイルの何行に由来するかを記録し、その範囲のハッシュを保存しておく方式です。CIはモデルを呼ばず、ハッシュ比較だけでドリフトを検出します。全PRでLLMに整合チェックさせるとCIが遅くなり課金が膨らんで、遅かれ早かれそのチェックは外されます。検出はミリ秒でトークンゼロ、修復だけエージェントを呼ぶ、という分離が要点です[11]。3層目はルールベースのCIでは無理だった領域で、PRをトリガーにエージェントを起動する形で埋めます[9][12]。

ハッシュ比較は「変わったか」しか見ません。「なぜ変えたか」の欠落は検出できないので、ADRのチェックは別建てにする必要があります。

11. どこまで書くか：量の設計

DMM のプラットフォーム開発本部の報告が具体的です。仕様駆動開発を実案件に入れた結果、従来なら数十行で済んだ改修でも仕様が1,000行規模になった。AIの出力が期待と違うたびに「仕様が足りなかったのでは」と説明を追加していたためです[13]。

そこで人が決める範囲（目的、制約、振る舞い、外部仕様）とAIが具体化する範囲（内部設計、実装、検証）を分け、繰り返し必要になる知識は仕様ではなくリポジトリ側のハーネス（ルール、スキル、専門エージェント）に退避させました。

指標 件数 従来 見直し後 変化
仕様記述量 20 1,213行 228行 84.5%削減
仕様策定時間 8 4時間 1時間 75%短縮
実装完了まで 8 8時間 6時間 25%短縮

いずれも案件ごとの中央値で、指標ごとに母数が異なります。適用対象は既存マイクロサービスの継続改修で、同記事は「新規開発では参照できる既存コードやルールに乏しいため、仕様として明示する範囲が広くなる」と課題を明記しています[13]。

つまり「仕様を厚くしても精度は上がらない」は一般化しすぎで、既存コードとハーネスが整っている領域では How を仕様から追い出せるという条件つきの主張です。事前に全ドキュメントを書く戦略を捨て、必要になった時点で書く方式に転換したチームの事例もあり、翌日陳腐化するものを書くコストは書かないコストより高い、と結論づけています[14]。

12. 最小構成と導入順

ここまでを1つのリポジトリに落とした合成案です。intent.md と工程の分け方は Anthropic、ARCHITECTURE.md と docs/generated/ は OpenAI、specs/<feature>/ の3ファイル構成は仕様駆動開発の各ツールから取っています。

/
├─ README.md                 # 人向け
├─ AGENTS.md                 # 全エージェント共通の約束（100行程度）
├─ CLAUDE.md                 # 中身は `@AGENTS.md` の一行だけ（後述）
├─ ARCHITECTURE.md           # ドメインとレイヤのマップ
├─ docs/
│  ├─ principles.md          # 原則。滅多に変えない
│  ├─ glossary.md            # 用語集
│  ├─ adr/                   # なぜ。棄却した選択肢を必ず書く
│  ├─ specs/<feature>/
│  │  ├─ intent.md           # 誰が何をなぜ求めたか
│  │  ├─ spec.md             # What のみ
│  │  ├─ plan.md             # How。長くしない
│  │  └─ tasks.md
│  ├─ generated/             # OpenAPI、DBスキーマ、依存グラフ
│  └─ as-is/                 # レガシーの現状仕様（コードから起こしたもの）
├─ .claude/
│  ├─ skills/                # 方針をスキル化（助言的統制）
│  ├─ agents/                # 検証などの再利用ジョブ
│  └─ settings.json          # フック（決定論的統制）
└─ .github/workflows/
   ├─ docs-drift.yml         # ハッシュ比較。モデルは呼ばない
   └─ agent-evals.yml        # 設定変更時に自動評価を回す

AGENTS.md と CLAUDE.md を両方置くのは、Claude Code が AGENTS.md をネイティブに読まないためです[15]。内容は AGENTS.md に一本化し、CLAUDE.md の中身は @AGENTS.md の一行だけにします。これは Claude Code のインポート構文で、AGENTS.md の内容がそのまま読み込まれます。シンボリックリンク（ln -s AGENTS.md CLAUDE.md）でも同じことができます。

運用ルール

ルール なぜ
人が書くのは Why と What。同じ What を複数ファイルに書かない 重複は必ず片方だけ更新され、どちらを信じるか分からなくなる
How は plan.md、コード、テストに閉じる。仕様に実装手順を書かない 実装手段は最も変わりやすく、仕様が毎回古くなる
生成物は出典つきのビルド成果物として扱い、手で直さない 次の生成で消えるうえ、出典ハッシュとの対応が壊れる
エージェントの失敗はドキュメントのバグとして扱う 指示側を直せば全員とすべてのセッションに効く
セッションで得た教訓はスキルか AGENTS.md に昇格させる チャット履歴は次のセッションから見えない
生成ドキュメントをレビューせずに main に入れない 実装と食い違った説明が次のセッションの入力になり、誤りが自己増幅する

導入順

  1. 使っているドキュメントだけ Markdown 化する。参照されていないものを移しても精度には効かない
  2. AGENTS.md にコマンド、禁則、テストの実行方法だけ書く。最初に厚くすると8章の失敗をやり直すことになる
  3. 新規1機能で intent / spec / plan / tasks を回す。1件で回してみないと、合う粒度が分からない
  4. 生成できる Facts を docs/generated/ に切り出す。人の判断が要らないので投資効率が高い
  5. 実案件20〜50件から自動評価セットを作る。これがないとコンテキストファイルを怖くて触れなくなり、古い記述が残り続ける[1]
  6. 依存の方向を linter と構造テストに落とす。アーキテクチャの合意がない段階で始めると、守らせる対象が定まらない

CI/CDへのエージェント組み込みは、レビューゲートとフックが先です。ゲートが存在しないまま自動化すると、通過速度だけが上がります[1]。

13. 人間の役割はどこに残るか

「方針は人間、実装はAI」と要約すると、2か所ずれます。

決めること 誰が
何を・なぜ作るか 人間。intent.md と spec.md
どの技術で・どのファイルを・どの順で 人間。Spec Kit では plan の引数、プレイブックでは Build 工程で名指しする
その中の実装細部 エージェント
毎回出てくるHow（規約、テストの出し方、禁則） 人間が一度ハーネスに書く。個別の仕様には書かない

1つ目のずれは、How も粒度によって人間が決めていること。11章の削減は How を仕様から追い出しただけで、考えるのをやめたわけではありません。2つ目は、エージェントは自律ではなく柵の中を自走していること。plan mode は承認まで編集せず、フックが操作を止め、承認経路は与えられず、逸脱の程度で権限が変わる。柵は文章ではなく機構です。

その結果、コードを書く仕事が柵を設計する仕事に変わります。どこにゲートを置くか、何をフックで止めるか、どの範囲を自動承認に寄せるか、繰り返す知識をどこに退避させるか。

この記事で扱ってきたドキュメント管理は、真ん中の3つをどう設計するかという話です。

14. プレイブックへの批判

導入前に自分で埋める必要がある部分として読むと有用です。

  • 計測基盤は扱っていない。指標の定義はあるが、集計して継続的に見る仕組みは別途必要[16]
  • 実行時の実態がカバー外。全工程がリポジトリ内のファイルを扱う設計なので、コードが対峙する実サービスやDBの状態には踏み込めない。ローカルで通るのに本番の依存先で壊れる問題は残る[17]
  • 連鎖の途中に突き合わせのないつなぎ目が残る。計画と差分の一致は見られるが、仕様が意図を正しく表しているかを機械的に確認する仕組みはない。最初の翻訳を間違えると、以降は誤った前提を精密に実装する[18]
  • Maintainからの再入がトリガー依存。誰も気づかない劣化は入口に立てない。運用はリポジトリ外の情報（何がどこで動いているか、誰がオーナーか）を必要とするのに、設計はリポジトリ内を前提にしている[19]

まとめ

  1. 引き継ぎ手段をコミットされたファイルにする。チャット履歴ではなく、工程の境目で成果物を版管理に置く。監査証跡と手戻り計測が副産物として手に入る
  2. 書く量より、どこを正式な記録にするかと鮮度の検知に投資する。コンテキストファイルは薄く、仕様は What だけ、Why は ADR、Facts は生成、鮮度はハッシュで測る
  3. 統制はお願いと強制の二層で持つ。スキルで違反を稀にし、フック・linter・構造テストで不可能に近づける

「AIにどうコードを書かせるか」ではなく「AIが正しく判断し続けられる環境をどう作るか」が設計対象になった、というのが調べてみた実感です。

参考資料

一次情報

解説・実務レポート

批判・補足

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?