intent-layer

Intent Layer

エージェントがシニアエンジニアのようにコードベースを把握できるようにする、階層型の AGENTS.md インフラストラクチャです。

基本原則

ルートのコンテキストファイルは 1 つだけにしてください。 プロジェクトのルートで CLAUDE.md と AGENTS.md を併用してはいけません。複雑なサブシステムでは、サブディレクトリに子 AGENTS.md を作成することを推奨します。

ワークフロー

1. Detect state
   scripts/detect_state.sh /path/to/project
   → Returns: none | partial | complete

2. Route
   none/partial → Initial setup (steps 3-5)
   complete     → Maintenance (step 6)

3. Measure [gate - show table first]
   scripts/analyze_structure.sh /path/to/project
   scripts/estimate_tokens.sh /path/to/each/source/dir

4. Decide
   No root file  → Ask: CLAUDE.md or AGENTS.md?
   Has root file → Add Intent Layer section + child nodes if needed

5. Execute
   Use references/templates.md for structure
   Use references/node-examples.md for real-world patterns
   Validate: one root, READ-FIRST directive, <4k tokens per node

6. Maintenance mode (when state=complete)
   Ask user:
   a) Audit nodes     → Use references/capture-protocol.md for SME questions
   b) Find candidates → Re-measure tokens, suggest new nodes
   c) Both

子ノードを作成するタイミング

シグナル	アクション
ディレクトリ内が 20k トークン超	AGENTS.md を作成
責任範囲が変わる	AGENTS.md を作成
隠れた契約や不変条件がある	最も近い祖先に記録
複数の領域にまたがる懸念事項	LCA に配置

次の場合は作成しないでください：すべてのディレクトリ、単純なユーティリティ、テストフォルダー（複雑な場合を除く）。

記録するための質問

既存のコードを文書化するときは、次の点を確認してください。

1. この領域が担う責任は何ですか？対象外のものは何ですか？
2. 決して破ってはならない不変条件は何ですか？
3. 新しいエンジニアが繰り返し戸惑う点は何ですか？
4. 常に従うべきパターンは何ですか？

リソース

スクリプト：

• scripts/detect_state.sh - Intent Layer の状態（なし／部分的／完了）を確認
• scripts/analyze_structure.sh - 意味上の境界を特定
• scripts/estimate_tokens.sh - ディレクトリの複雑さを測定

リファレンス：

• references/templates.md - ルートノードと子ノードのテンプレート
• references/node-examples.md - 実例
• references/capture-protocol.md - SME インタビュープロトコル