以前、AI駆動開発で使うためのリポジトリ構造として「AIDD Skeleton」というものを作りました。
目的はシンプルです。
AIに毎回長いプロンプトで、
- まず要件を確認して
- 設計を読んで
- 実装して
- テストして
- ドキュメントも更新して
と指示するのではなく、リポジトリそのものに「どう開発するか」を持たせたいと考えました。
そこで、要件・設計・テスト・実装・調査資料などの役割を分離し、AGENTS.mdでAIの行動規約を定義しました。
最初はかなりうまくいっていました。
AIは必要なドキュメントを読み、実装し、テストし、結果を記録してくれます。
ところが実際のプロジェクトで使い続けていると、少しずつ妙なことが起き始めました。
- 設計書が実装コードの説明書になっていく
- テスト仕様書に過去の実行結果が蓄積していく
- 検証を厳密にするほどEvidenceファイルが増えていく
- 似たような運用手順書が各アプリケーション配下に作られていく
厄介だったのは、AIがほぼ指示通りに動いていたことです。
今回は、実際にAIDD Skeletonを使う中で起きた3つのケースと、その結果として規約をどう考え直したのかを、当時のコミット履歴と一緒に振り返ります。
※この記事は筆者自身の開発経験・判断・問題意識をもとに、生成AI（ChatGPT）との対話を通じて構成・文章化しています。
「AIが勝手なことをした」で済ませられなかった
AIエージェントが妙なファイルを作ったとき、最初に疑いたくなるのはAIです。
そこに作るなよ。
なんでそんなことまで設計書に書くんだ。
テスト結果を仕様書に残すな。
人間から見ると、確かにそう思います。
ところが規約を読み直してみると、AI側にもそれなりの理由がありました。
たとえば、
実装と設計を一致させる
というルールがあれば、現在の実装を調査して設計書へ反映する判断は自然です。
検証結果を記録する
というルールがあれば、テスト結果をドキュメントへ残すのも自然です。
アプリケーション固有の情報は、そのアプリケーション配下へ置く
というルールがあれば、そのアプリをデプロイする手順をアプリ配下へ置くことにも理由があります。
個々の判断だけを見れば、それほどおかしくありません。
それでも、同じ判断が何度も積み重なると、プロジェクト全体がおかしくなっていきます。
そこで考え方を変えました。
なぜAIは間違えたのか、ではなく、なぜその判断を「正しい」と解釈できたのかを見る。
生成物だけではなく、生成物を生み出した規約側を疑うようになりました。
Case 1: Designが実装の写経になっていった
最初に大きく気になったのがDesignでした。
既存システムをAIに変更させると、AIは当然ながら現在のコードを読みます。
そして変更後、設計書も最新状態に更新します。
一見、理想的です。
ところがこれを繰り返していると、Designの中に、
- 現在のクラス名
- 関数名
- ファイルパス
- 内部状態の名前
- 現在採用している細かな実装方法
といった情報が入り始めました。
設計書と実装が一致している。
それ自体は悪いことではありません。
ただ、あるとき疑問が出ました。
もし
products/、つまり現在の実装を全部消したら、このDesignは何のために存在するのだろう。
AIDD Skeletonでは、理想として、
実装が失われても、
plans/に残った要件・設計・テストから、意図したシステムを意味的に再構築できる
状態を考えていました。
もちろんソースコードを一字一句再現する必要はありません。
しかし、
- 何を満たすべきなのか
- どんな責任境界なのか
- 何を設計上固定しているのか
- 何をもって正しいと判断するのか
は残っていてほしい。
そう考えると、現在のprivateなクラス名やファイル構造をDesignへ転記しても、それは必ずしも将来の実装を拘束したい「設計」ではありません。
ここで、
ImplementationとDesignが一致していること
と、
ImplementationをDesignの根拠にすること
は別だと整理しました。
現在の実装は重要です。
しかし、それは「現在どう実現されているか」を示す情報であって、存在しているだけで将来の実装を拘束するAuthorityを持つわけではありません。
Designへ残すべきなのは、
将来の妥当な実装も、この制約には従ってほしい
と言えるものです。
逆に、
今たまたまこう実装されている
だけなら、自動的にDesignへ昇格させるべきではない。
この考え方は後に、normative / non-normativeな情報の境界を明示する規約へ発展しました。
関連コミット
- docs: tighten normative documentation boundaries — 2026-08-20
- docs: guard normative promotion and evidence currency — 2026-08-20
- docs: preserve non-normative maintenance knowledge — 2026-08-20
Case 2: Verificationを厳密にしたら、Evidenceが増殖した
次に起きたのが、検証結果の問題です。
AI駆動開発では、「実装した」だけで完了扱いしたくありませんでした。
そのため、
- テストしたのか
- 何を確認したのか
- 何を確認できていないのか
を区別する規約を強くしていきました。
これは今でも必要だと思っています。
ところが検証を厳密にすればするほど、別の問題が起きました。
- 実行したコマンド
- テスト件数
- CIの結果
- commit SHA
- 確認時点の外部データ
- migrationの結果
- 一時的な調査結果
こうしたものが、どんどん正式なドキュメントの中へ残り始めたのです。
特に厄介なのがTestingでした。
Testingには本来、
何を、どのような方法で確認し、どんなEvidenceがあれば正しいと判断できるか
を書きたい。
ところがそこへ、
2026年○月○日に○件テストして成功した
という情報まで入り始めると、Verification specificationとExecution historyが混ざります。
今日のテスト結果は、明日の仕様ではありません。
ここから、
Testing specificationとExecution evidenceを分離する
という考え方になりました。
関連コミット
- Tighten verification evidence scope — 2026-08-02
- docs: separate execution evidence from normative testing — 2026-08-21
しかし、分離しただけではまだ足りませんでした。
Evidenceもすべて永久保存すればいいわけではありません。
調査中だけ必要な情報。
検証中だけ必要なEvidence。
あとからも参照価値がある知識。
将来の実装を拘束する正式な仕様。
これらを同列に扱うから混乱します。
そこで、情報にはLifecycleがあると考えるようになりました。
概念的には、
workbench
↓
references
↓
plans
のような関係があります。
ただし、時間が経てば自動的に上へ昇格するわけではありません。
workbench/は調査・仮説・作業中のEvidenceを扱う。
その中から将来も参照価値があるものはreferences/へ残せる。
そして、将来の実装を本当に拘束すべき内容だけが、明示的な判断を経てplans/へ採用される。
逆に、用済みになったEvidenceは削除してよい。
情報を残すことと、Authorityを与えることは別です。
そして、
Evidenceには有効期間があります。
半年間変わらない仕様と、昨日成功したテスト結果を同じ種類の「正しい情報」として扱うことはできません。
関連コミット
- docs: route verification evidence through workbench — 2026-08-22
- docs: tighten verification evidence lifecycle — 2026-08-22
ここでようやく、
ドキュメントは多ければ多いほど安全、というわけではない
と考えるようになりました。
必要なのは最大量のドキュメントではなく、
最小限の曖昧さ
です。
Case 3: 「何について書いてあるか」で配置すると破綻する
もうひとつ面白かったのが、ドキュメントの配置です。
たとえば、あるアプリケーションをdeployする手順があります。
直感的には、
plans/apps/example/deployment.md
に置きたくなります。
対象がexampleというアプリだからです。
AIも自然にそう判断します。
ところが複数のアプリを持つプロジェクトで同じルールを適用すると、それぞれの配下に似たdeployment手順が作られ始めました。
ここでもAIは規約を無視しているわけではありません。
そのアプリについての情報だから、そのアプリの下
という分類ルールに従っただけです。
しかし、実際にそのdeploy手順を変更する責任を持っているのは、アプリ自身ではなく、システム全体の運用側かもしれません。
つまり、
何を操作する手順なのか
と、
その手順を誰が所有しているのか
は違います。
同じことはTestingにも起こります。
複数アプリをまたいでテストするからといって、必ずSystem-ownedなテストになるわけではありません。
逆に、一つのアプリだけを対象にしていても、その実行条件や成功判定をシステム側が所有しているなら、System-ownedな責任かもしれません。
そこでPlacementを、
何について書いてあるか
ではなく、
その情報の目的、変更権限、判断責任を誰が持っているか
から考えるようにしました。
OwnershipとPlacementを分離して考えるようになったわけです。
関連コミット
- docs: refine structure and placement ownership — 2026-08-23
- docs: clarify ownership placement boundaries — 2026-08-23
個別ルールを増やすだけでは解決しなかった
この3つの問題は、一見すると別々です。
Designへ実装詳細を書きすぎた。
Evidenceが増えすぎた。
deployment documentの置き場所を間違えた。
それぞれに専用ルールを追加することもできます。
- Designへクラス名を書いてはいけない
- Evidenceは○日経ったら削除する
- deployment.mdはSystem配下に置く
しかし、それでは別の名前のファイル、別の技術、別の構成で同じ問題が起きます。
AIが未知のケースに遭遇しても判断できるようにするなら、必要なのは個別の禁止事項ではありません。
判断に使える原則です。
今回の問題を整理すると、大きく次のような観点が見えてきました。
Authority
その情報は、将来の実装や判断を拘束するのか
Lifecycle
調査・採用・検証・保持・破棄の間をどう移動するのか
Evidence
何が存在し、何が実装され、何が実行され、
どこまで検証されたと言えるのか
Structure / Placement
その情報の変更・判断責任を誰が所有しているのか
最初からこの分類を設計していたわけではありません。
実際にAIへ開発を任せ、何度か破綻させ、その原因を追っていった結果として少しずつ見えてきたものです。
AI駆動開発では、ドキュメントも「実行される」
この経験から、ドキュメントに対する見方も少し変わりました。
人間向けのドキュメントなら、多少曖昧でも読んだ人が、
たぶんこういう意味だろう
と補完してくれます。
AIエージェントにとってのAGENTS.mdやSource of Truthは、それとは少し違います。
AIはそれを読み、
判断し、
ファイルを作り、
ファイルを移動し、
コードを変更します。
つまり、ある意味ではドキュメントが実行されます。
そう考えると、
- 規約が曖昧なら、曖昧な挙動が出る
- 局所的に正しいルールが組み合わさると、全体として誤った挙動になる
- 例外ルールを増やしすぎると、別のケースで矛盾する
- 実際の挙動を観察しないと、規約の欠陥に気づけない
というのは、かなりコードに似ています。
AI用の指示を書いたら終わりではありません。
AIがその指示をどう解釈したかを見る必要があります。
「AIが間違えた」で終わらせない
今回一番大きかった学びは、これかもしれません。
AIが想定外のことをしたとき、
AIが変なことをしたので、次から禁止する
だけなら簡単です。
でも、それを繰り返すとAGENTS.mdは大量の禁止事項で埋まっていきます。
それよりも、
なぜAIは、その判断を妥当だと考えられたのか
を見る。
そこに一般化できる原因があれば、個別の禁止ではなく判断原則を修正する。
AIDD Skeletonは、当初考えていた単なる「AI向けのリポジトリテンプレート」から、少しずつAIの判断に使われる情報そのものを整理する仕組みへ変わっていきました。
まだ完成したとは思っていません。
むしろ、実際に使うほど新しい境界問題が見つかります。
ただ、少なくとも一つ分かったことがあります。
AIは指示を守らなかったから破綻したのではありません。
指示を守った結果として破綻したからこそ、直すべき対象がAIではなく規約だと気づけた。
そして次に問題になったのは、さらに厄介なことでした。
規約を直したとして、
その規約が本当に正しいと、どうやって確認するのか。
これはまた別の話として書こうと思います。
AIDD Skeleton: