Coding Agent 前提のプロジェクト情報管理 ─ DRY・SSoT で設計するフォルダ構成

AI エージェント開発の情報管理 - 原則.md

AI エージェント開発の情報管理 - 原則

AI コーディングエージェントを前提とする開発プロジェクトの情報管理原則とフォルダ構成。 特定のツール（Claude Code, GitHub Copilot 等）に依存しない一般論。

スコープ: 情報の分類・配置・管理の原則。 プロジェクト管理（スケジュール、タスク管理等）は扱わない。

関連: AIエージェント開発の情報管理-設計根拠（各原則の背景と根拠）

前提

• Single Source of Truth（SSoT）: 各情報の「正」は1箇所で管理し、他はそこから導出する

フォルダ構成と導出フロー

情報を以下の領域に配置する。

project-root/
├── rules/        # 方針・スコープ・拘束的制約
├── backlog/      # やること・バグメモ等（コミット対象、完了分は整理）
├── tests/        # テスト（振る舞いの正）
├── src/          # ソースコード（実装の正）
├── config/       # 実行環境固有の値（.env, CI設定等）
├── decisions/    # 意思決定ログ（append-only）
├── derived/      # 派生ビュー（正からの一方通行導出）
├── references/   # 参照情報（正ではない補助的な情報）
└── tmp/          # 揮発的一時情報（gitignore 対象）

導出フロー

人の脳/組織
  → rules/    mission, planning, principles を定める
  → rules/    mission から scope（プロダクトの境界）を定める
  → backlog/  scope から直近やることを決める
  → tests/    backlog からテストを書く
  → src/      tests からコードを書く

config/ は実行環境ごとに独立して決まる。decisions/ は各段階の判断時に横断的に生まれる。

上流を変えたら下流に影響する。この依存の方向が各領域の関係を決める（作業の順序ではない）。

情報の分類

情報源の定義

情報の種類ごとに「正」の領域を1つだけ定める。

情報の種類	問い	正の所在
原則・制約	must	rules/
振る舞い	what	tests/
実装	how	src/
環境固有の値	where	config/
判断理由	why	decisions/

正ではない情報

正に分類されない情報は以下の3種類に分かれる。

derived/（正の再表現）: 既存の正を読みやすく再構成した文書。フローの一部ではなく、何かの上流にもならない。正と矛盾する場合は正が優先される。

例: ユーザー向けマニュアル、API リファレンス、コマンド一覧、アーキテクチャ概要図。

references/（参照情報）: 実装判断に影響するが、他のどの領域にも属さない補助的な情報。正と矛盾した場合は正が優先される。

例: 技術的知見（ライブラリの罠、エッジケース）、外部ドキュメントの要点、回避策の記録。

一時情報: 永続させない情報。拘束力があるなら永続領域に移し、ないなら一時情報として扱う。

区分	git 管理	例
揮発的一時情報	gitignore	作業メモ、実験コード
追跡可能一時情報	git コミットして削除後も履歴に残す	バックログ

永続領域への記録判断

作業中に得た知見や新たに確定した要求事項は、適切な永続領域に記録する。

判断基準は2つの観点:

• 反復コスト削減: 記録しないと同じ議論を繰り返す情報
• 破局コスト回避: セキュリティ・法務・データ損失に関わる情報

判断に迷った場合は記録しない。

各領域の詳細

rules/

目的別にファイルを分割する。以下はファイル構成の例。

• mission: プロダクト目的・非目標
• scope: 主要機能・ユースケース定義（状態管理は持たない）
• planning: 優先度の決め方
• constraints: 破ると破局や再議論を招く制約（検出方法併記）
• principles: 方向づけのための方針

backlog/

新規の要求は方針から具体化されて backlog/ に入る。実装中に発見したバグや課題も backlog/ に追加する。

拘束力は弱く、テスト・コードに吸収されるまでの中間情報。コミット対象とし、完了した項目は整理する。外部ツール（GitHub Issues 等）で置き換えてもよい。

decisions/

後から理由を問われうる判断を記録する場所（いわゆる ADR: Architecture Decision Records）。append-only で運用する。

運用ガイド

各領域の定義を補足する実践的な指針。

rules/

• scope は粒度を荒く保つ（主要ユースケース・主要機能まで）
• constraints は可能なら自動検出できる形にする（linter、CI、テスト等）
• 自動化できない項目にはレビューポイントを併記する
• 検出もレビューもできない項目は decisions/ に移す

decisions/

• 各記録に日付と文脈を記載する

backlog/

• 完了した項目は定期的に整理する

derived/

• 更新漏れの検出方法は rules/ で定める

AI エージェント開発の情報管理 - 設計根拠.md

AI エージェント開発の情報管理 - 設計根拠

AIエージェント開発の情報管理-原則 の各原則がなぜそうなっているのか、背景と根拠を補足する。

この文書の目的

各原則の背景にある考え方や、別の選択肢を採らなかった理由を補足する。将来の判断で参照できるようにする。

採用した原則: DRY と SSoT

情報管理の基盤として DRY（Don't Repeat Yourself）と SSoT（Single Source of Truth）を採用する。DRY で重複を排し、SSoT で情報の種類ごとに「正」の置き場所を1つだけ定める。

導出フローを構成原理とする理由

SSoT で「正を1箇所にする」としても、開発に必要な情報は複数種類ある。これらをどう整理するかが次の問題になる。

上流を変えたら下流に影響する。この依存の方向がフォルダ構成を決める自然な根拠になる。「情報の種類を列挙してグループ分けする」のではなく、「何が何から生まれるか」を追うことで各領域の境界が決まる。

情報の分類

情報源の定義

AI が無限の性能と速度を持つなら、テストとコード（あるいはコードだけ）で十分かもしれない。しかし現実には、開発初期にテストの手がかりとなる上流の情報が必要であり、抽象度の異なる情報は同じものの重複ではなくそれぞれに正がある。

導出フローの各段階が答える問いに対応させると、原則の表に示す5種類の「正」が自然に現れる。

テストで代替できないもの

テストは「機械的に検証可能な仕様」の正として機能する。しかしテストで表現できないものがある:

• 目的（なぜ）: 「ブルートフォース攻撃を緩和するため」という目的はテストに載らない
• 非現実的な検証コスト: 「GDPR 準拠」をテストだけで表現するのは非現実的
• 優先順位の判断基準: 「データ整合性を優先する」という方針はテストの記述対象ではない

これらは rules/ や decisions/ に置く。

派生ビューの位置づけ

「正」から導出可能な情報をファイルとして保持することは二重管理に見える。しかし実運用で以下の問題がある。

導出コストの問題: テストとコードが「正」であっても、全コマンドの一覧や全体像を毎回導出するのはコンテキスト消費と時間の両面で非現実的。

非決定性の問題: 同じ正から導出しても毎回微妙に表現が変わる。安定した参照先がないと共通理解を持ちにくい。

参照パターンの問題: コードレベルの詳細ではなく、全体を俯瞰したい場面がある。

references/ の必要性

導出フローに乗らない情報も現実の開発では必要になる。

実装中に発見した技術的知見（ライブラリの罠、エッジケース）はテストやコードから読み取れるとは限らない。外部ドキュメントの要点や回避策は、そもそもプロジェクトの導出フローから生まれたものではない。

これらは正ではないが、実装判断に影響する。rules/ に入れると「知っておくと便利」程度の知見が拘束的な制約と混在する。derived/ に入れると「正の再表現」という定義が崩れる。decisions/ に入れると判断記録と事実ベースの知見が混在する。

既存のどの領域にも収まらないため、references/ に置く。

一時情報の区分

一時情報の中に性質の異なる2種類がある。

揮発的一時情報: 作業メモ、実験コード。削除後に履歴を辿る必要がない。gitignore でよい。

追跡可能一時情報: バックログ。削除後にも履歴が必要な理由:

• エージェントがファイルを破損・消失した場合の復元
• 要求やタスクの変遷を後から追跡する場面がある

永続領域への記録判断

判断に迷った場合は記録しないとしているのは、無条件に記録すると rules/ や decisions/ が肥大化し、参照コストが上がって逆に反復コストが増えるため。

各領域の詳細

rules/ の目的別分割

rules/ の中身は性質の異なる情報を含む。プロダクトの目的（mission）、境界（scope）、優先度の決め方（planning）、破局的な制約（constraints）、方向づけの方針（principles）。これらを1ファイルにまとめると、参照時に必要な部分を探すコストが上がる。

以下は目的別ファイルの例:

• mission: 「このツールは Markdown ファイル間のリンク整合性を保つ」「IDE プラグインは作らない」
• scope: 「リンク切れの検出と報告」「リンクの一括変換」「Obsidian wikilink と Markdown リンクの相互変換」
• planning: 「ユーザー影響のある変更を優先する」「1コミットは1つの論理的変更にまとめる」
• constraints: 「公開 API のレスポンス形式は変更しない」「個人情報はこのテーブルにしか保存しない」（検出: grep で確認）
• principles: 「エラーは黙って飲まず必ずユーザーに報告する」「設定より規約（Convention over Configuration）を優先する」

scope はプロダクトの境界を定める。境界の内側は実現すべきもの、外側は作らないもの。この境界定義は rules/mission（非目標）と一体であり、rules/ の他のファイル（mission, constraints 等）と同様に守るべき制約として扱う。

scope に実装状態（実装済/未実装）を持たせない理由:

• 状態管理を持たせると更新頻度が上がり、rules/ の安定性と衝突する
• 実装状態の確認が必要なときは、テスト・コードから AI に判断させる
• 直近でやることは backlog/ で管理する
• scope は「最終的に提供するもの」の一覧として安定させる

constraints に検出方法の併記を求めているのは、原則が形骸化するのを防ぐため。検出もレビューポイントも書けない項目は、実効性のある制約とは言えないため decisions/ に移す。

backlog/ の役割

導出フローでは rules/scope から tests/ へ情報が流れる。しかし scope は「最終的に提供するもの」の一覧であり、「今週やること」は書かれていない。tests/ に書くには具体化が足りない。

scope と tests/ の間に、直近の作業項目を管理する場所が要る。これが backlog/ である。他の領域と異なり、backlog/ はコラボレーション機能（GitHub Issues 等）と重なりやすい。

decisions/ の役割

導出フローの中で decisions/ は特殊な位置にある。フローの特定段階に属するのではなく、どの段階でも判断が発生したときに横断的に生まれる。