Project Intent Management

プロジェクトや worktree の意図・方針を JSON 形式で構造化管理し、AI エージェントとのコンテキスト共有を最適化する。

解決する課題

Claude Code を使って開発を進める際、以下の問題が発生しやすい：

• コンテキストの喪失: どのプロジェクトで、どんな判断基準で進めていたか分からなくなる
• 前提の混同: 別プロジェクトや別 worktree の前提を混ぜてしまう
• 設計判断の忘却: 「なぜその設計判断をしたのか」を思い出すコストが高い
• 意図の復元困難: Issue / Task を見ても、上位の意図（方向性）が復元できない

これらは 「何を正しいとみなしていたか」 という上位コンテキストが失われることが原因である。

基本概念

管理するのは「作業」ではなく「姿勢」

Issue や Task は「何をするか」を管理するが、失われやすいのは以下の情報：

• いまは探索なのか、収束なのか
• 何を優先し、何を捨てると決めていたか
• 判断に迷ったときの基準
• 次に意思決定するための一手（仮説・賭け）

2 層構造

ファイル仕様

.intent/project.json（プロジェクト憲法）

プロジェクト全体で共有される不変的な方針を JSON で記述する。

JSON キー（必須）

JSON キー（オプション）

例

{
  "schemaVersion": "1.0",
  "type": "project",
  "id": "proj-parallel-dev-001",
  "name": "Parallel Development Platform",
  "intent": "複数の Claude が同時並行で開発タスクを進行できる環境を提供し、開発速度を最大化しながらコンフリクトを最小化する。",
  "summary": "並列開発環境の構築",
  "successCriteria": [
    "3つ以上のタスクを同時並行で進行できる",
    "タスク間のコンフリクト率が 10% 以下"
  ],
  "guardrails": [
    "マージ前に必ずテストを実行する",
    "全タスクで同じコーディング規約を使用する"
  ],
  "nonGoals": ["リアルタイム協調編集機能は提供しない", "IDE 統合は対象外"],
  "technicalStack": ["Python 3.11+", "FastAPI"],
  "keyDecisions": [
    {
      "date": "2024-01-15",
      "text": "worktree ベースの並列開発方式を採用（コンフリクト最小化のため）"
    }
  ]
}

テンプレート: references/templates/project.json

.intent/brief.json（worktree 思考メモ）

各 worktree の一時的な作業方針を JSON で記述する。

JSON キー（必須）

JSON キー（オプション）

Mode の定義

テンプレート: references/templates/brief.json

セットアップ手順

1. プロジェクト全体のセットアップ

# .intent ディレクトリを作成
mkdir -p .intent

# スクリプトを使用
bash scripts/init-project-intent.sh

# または手動でテンプレートをコピー
cp templates/project.json .intent/project.json

2. .gitignore の設定

# Worktree thinking / intent
.intent/brief.json
worktrees/**/.intent/brief.json

3. worktree ごとの brief.json 作成

cd worktrees/task-name
mkdir -p .intent

# スクリプトを使用
bash ../../scripts/init-brief.sh "task-name"

# または手動でテンプレートをコピー
cp ../../templates/brief.json .intent/brief.json

日常的な運用

作業開始時のルーティン

各 worktree で作業を開始する際、必ず以下を Claude に指示する：

この worktree の .intent/brief.json と、プロジェクトの .intent/project.json を読み、
mode / focus / nonGoals / nextBet を最初に要約してから作業を開始してください。

または、スクリプトを使用：

bash scripts/load-context.sh

brief.json の更新タイミング

1. 重要な判断をしたとき → decisionsLog に追加
2. 選択肢を捨てたとき → discardedOptions に追加
3. フォーカスが変わったとき → focus を更新
4. モードが変わったとき → mode を更新
5. 次の一手が明確になったとき → nextBet を更新

project.json への昇格

brief.json で記録した判断のうち、プロジェクト全体に影響する重要な決定は project.json に昇格させる：

# brief.json から重要な決定を抽出
# → project.json の "keyDecisions" に追記
# → commit する

効果

1. コンテキストスイッチの高速化: worktree を切り替えても「何を考えていたか」がすぐ戻る
2. 前提混同の防止: 別プロジェクトの前提を混ぜる事故が減る
3. AI エージェントの理解向上: Claude が JSON を直接パースし、正確に理解できる
4. 思考の自由度向上: brief.json を気軽に書き換えられる（履歴を汚さない）
5. 設計判断の追跡可能性: なぜその判断をしたのかが明確に記録される
6. VS Code 拡張との連携: JSON 形式により、Intent Board UI での高速パースが可能

設計原則

JSON には判断の骨格のみ

• 1〜2 文で表現できる内容のみ
• 長文説明は別途 notes.md に記載
• AI に曖昧な自然文解釈をさせない

人間と機械の責務分離

• JSON: 機械がパースする構造化データ
• Markdown: 人間が読む補足説明

関連ドキュメント

• project.json テンプレート
• brief.json テンプレート
• 詳細ガイド