Intent Tree モデル
Intent ツリーは、実際にはディスク上の「YAML フロントマターつきの小さな markdown ファイルの集まり」として存在する、辿れる階層です。中心の 3 系統 ── Purpose（なぜ）／ User Context（誰が、いつ）／ Means（どうやって）── が「なぜ・誰のために・どう実現するか」を答え、その周りに rules / specs / execution / clarifications という 4 つの運用フォルダが置かれます。人間が育て、人間とエージェントの両方が読みます。
3 つの系統
Purpose
システムが存在する理由。Mission / Vision / Value / Product Goal。
User Context
誰が、どんな状況で使うか。Primary Actor / Usage Situation / Session Shape。
Means
どのやり方で解きたいか。Interaction Style / System Behavior Style / Abstraction Choice / 技術戦略。
実際のディレクトリ構成
本番で運用している Intent ツリーは、小さな markdown ファイルが集まった一つのフォルダです。3 系統は intent-tree/ の下に、その隣に rules / specs / execution / clarifications という 4 つの運用フォルダが並びます。ルートの 00-map.md が、人間（とエージェント）にどこから読み始めるかを示します。
intents/<domain>/
intent-tree/
00-map.md # 読み順と、各クラスタが受け持つ範囲
purpose/
01-mission.md
02-vision.md
03-value.md
04-product-goal.md
user-context/
01-primary-actor.md
02-usage-situation.md
03-session-shape.md
means/
01-queue-topology.md
02-tooling-strategy.md
03-persistence-strategy.md
...
rules/ # 技術・運用ガードレール
specs/ # 下流の契約
execution/ # Issue にできるスライスと順序
clarifications/ # 未解決の問い ── AI が出し、人間が答える
design/ # 判断の理由と代替案実例: intent-cli 自身、加えて社内のプロダクト領域（現時点では非公開）。同じ形がプロダクト領域にも、インフラ領域にも、「このチームはどう判断するか」のようなメタ領域にも使えます。
最初のファイルはどこから来るのでしょうか。プロダクトの初期段階では Intent Storming を行います ── プロダクトオーナーとして技術と意図をまとめる作業で、チームでも、AI にヒアリングしてもらう一人作業でも進められます。出てきた答えはそのまま Purpose / User Context / Means の各ノードとしてツリーに書き込みます。 Intent Storming の詳細 →
ひとつの意図は、フロントマターつきの小さなファイル
各ノードは、固有 ID、状態、1 行の要約、依存する／支える他の意図へのリンクを持ちます。これがあるから、人間が grep できるただのフォルダでありながら、機械からも辿れる構造になります。
--- intent_id: ICL.M.TOPOLOGY domain: intent-cli intent_type: means intent_state: canonical # inferred → clarified → canonical readiness: structured summary: sub-issue を単位にした queue-aware supervisor と selective block を採る。 tags: - domain:intent-cli - intent:means - state:canonical parent_intents: [ICL.P.MISSION] related_intents: [ICL.M.TOOLING, ICL.M.WORKER] source_concepts: - intents/rules/nonblocking-agent-loop.md --- # 本文は普通の日本語／英語 ── なぜそうするか、どの選択肢を採ったか。
あとでこの意図から Issue を切り出すとき、このファイルと、ここからリンクされている関連意図がまとめて Issue の文脈になります。「分かりやすい Issue を書く」が苦行でなくなるのは、文脈が最初から構造化されて添付できる状態にあるからです。
意図が固まっていく 3 つの状態
意図がどれくらい固まっているかを「推測」ではなく「状態」として扱います。意図は次の 3 つの状態を順に通っていきます:
inferred (推定) ── エージェントが提案した状態。人間の確認待ち ↓ clarified (確定) ── 人間が確認した状態。意味が固まる ↓ canonical (正式採用) ── 下流の spec を縛る基準として採用された状態
canonical（正式採用）の状態にある意図は、spec やコードレビューから「縛り」として参照できます。inferred（推定）のままの意図は参照できません。
昇格は手作業での編集ではなく、クラリフィケーションによって進みます。AI がツリーを継続的にレビューし、「ここはどうしますか？」という問いを推奨案つきで一括して提示します。人間はこだわりがない部分（多くの場合）は推奨案を採用し、こだわりたい部分（自分の判断が本当に効く場所）だけ自分で答える。受け入れた答えはその意図を一段昇格させます。サイクルを回すたびにツリーは厚くなり、最初に巨大な仕様書を書く必要はありません ── そして以後ツリーから切り出される Issue はすべて、その厚くなった文脈を受け継ぎます。
バグ報告も意図を強化する信号になる
Intent ツリーがしっかりしていても、実装は完璧にはなりません。リリース後にバグや調整事項が必ず出てきます ── これはループの「例外」ではなく、ループの一部です。Intent-System では、バグ報告ひとつひとつを次の 2 種類に分類しながら受け止めます:
- 実装バグ. 意図は正しく書かれていたが、コードがそれを守れていなかったケース。コードを修正します。ツリーは変えません。
- 意図の漏れがバグとして現れたケース. 意図が何も言っていなかった点について、実装者（人間でもエージェントでも）がそれらしい判断を独自に下し、結果として意図しない振る舞いになったケース。これは純粋なバグというよりも、現実から戻ってきたクラリフィケーション要求です。対応は、関連する意図を追加するか強化して、次回以降同じ点で違う判断が再発しないようにすることです。
この線を正しく引けることで、ツリーは「ただ膨らむ」のではなく「鍛えられて強くなっていく」ものになります。意図の漏れを「単なるコード修正」で済ませてしまうと、チームが本当は何を望んでいたかを記録する機会を失います。逆に、本当は実装ミスにすぎないものを「意図の漏れ」として扱うと、本来書く必要のなかったルールでツリーが汚れていきます。Intent-System は両方の流れを扱います ── コード修正は通常のレビュー・ループへ。クラリフィケーション扱いになったものはツリーを昇格させ、以後切り出される Issue はすべて、より鋭くなった意図を受け継ぎます。
運用上は、各報告は Intent-Bug Issue として起票され、ai-develop 上のエージェント修正ループに再投入されます。そこから main への昇格も、通常の Issue とまったく同じレビュー経路を通ります。 Git-AI-Flow ── 昇格経路を見る →
他の概念との違い
- 要件定義. spec はスナップショットになります。intent は蓄積します。
- ADR. ADR は決定を記録します。intent は将来の判断を駆動する理由を記録します。
- ユーザストーリー. ストーリーは slice。intent はそれが育つツリー。