icpg

iCPG スキル（意図拡張コードプロパティグラフ）

目的： コード構造の上に理由グラフのレイヤーを追加し、すべての関数、クラス、モジュールについて、それを作成した目標、担当するエージェントまたは人、そして本来の役割を果たし続けているかを追跡できるようにします。

┌────────────────────────────────────────────────────────────────┐
│  iCPG = AST + CFG + PDG + RG (Reason Graph)                    │
│  ─────────────────────────────────────────────────────────────│
│  AST  = Abstract Syntax Tree (structure)      ← existing       │
│  CFG  = Control Flow Graph (execution paths)  ← existing       │
│  PDG  = Program Dependency Graph              ← existing       │
│  RG   = Reason Graph (WHY layer)              ← THIS SKILL     │
│                                                                │
│  The RG stores ReasonNodes (goals/tasks), links them to code   │
│  symbols via typed edges, enforces contracts (DbC), and        │
│  detects when code drifts from its original purpose.           │
│                                                                │
│  Storage: .icpg/reason.db (SQLite, per-project, gitignored)   │
│  CLI: icpg init | create | record | query | drift | bootstrap │
└────────────────────────────────────────────────────────────────┘

---

基本原則

まず意図、次にコードです。 コードを記述または変更する前に、理由グラフを照会し、既存コードが書かれた理由、維持すべき制約、そして変更内容が過去の作業と重複していないかを把握します。

---

タスク開始前に実行する3つの標準クエリ

すべてのエージェントは、コードを書く前に必ず次のクエリを実行する必要があります。

#	クエリ	コマンド	確認できること
1	search_prior_work	icpg query prior "<goal>"	以前に試みられたことがあるか。重複を防ぎます。
2	get_constraints	icpg query constraints <file>	変更対象ファイルにどのような不変条件が適用されるか。破損を防ぎます。
3	get_risk_profile	icpg query risk <symbol>	このシンボルは壊れやすいか。ドリフトの履歴や所有者の変更を確認します。

---

ReasonNode — 中核となるプリミティブ

各 ReasonNode は、正式な契約とともに明示された目的を記録します。

id              UUID
goal            Natural language: what is this trying to achieve
decision_type   business_goal | arch_decision | task | workaround | constraint | patch
scope           Files/modules expected to be touched
owner           Human or agent accountable
status          proposed | executing | fulfilled | drifted | abandoned
source          manual | commit | inferred | agent-session

FORMAL CONTRACT (Design by Contract):
  preconditions    What must be true before this intent executes
  postconditions   What must be true when fulfilled
  invariants       What must remain true throughout and after

ドリフト = 述語の不成立です。 シンボルの現在の動作が、それを作成した ReasonNode の事後条件を満たさなくなった場合、または不変条件に違反した場合、そのシンボルにはドリフトが発生しています。

---

6種類のエッジ

CREATES      Reason  → Symbol   (this intent created this function)
MODIFIES     Reason  → Symbol   (this intent changed this function)
REQUIRES     Reason  → Reason   (B depends on A being done first)
DUPLICATES   Reason  → Reason   (these two goals overlap)
VALIDATED_BY Reason  → Test     (this test proves the intent was satisfied)
DRIFTS_FROM  Symbol  → Reason   (this symbol no longer does what it was made for)

---

6次元のドリフトモデル

次元	意味	検出方法
仕様ドリフト	MODIFIES エッジがない状態でシンボルのチェックサムが変更された	保存済みのチェックサムと現在のチェックサムを比較します
決定ドリフト	事後条件が成立しなくなった	コードベースに対して述語を評価します
所有権ドリフト	一貫した監督体制がないまま、所有者が3人を超える	エッジ上の一意な所有者の数を数えます
テストドリフト	VALIDATED_BY テストが存在しない、または失敗している	テストファイルの存在を確認し、テストを実行します
使用状況ドリフト	シンボルが当初のスコープ外で使用されている	スコープ外からのインポートを grep で検索します
依存関係ドリフト	下流の REQUIRES 理由にドリフトが発生している	REQUIRES エッジをたどります

icpg drift check を実行すると、すべての次元をスキャンします。それぞれについて、0～1の重大度スコアが算出されます。

---

CLI リファレンス

セットアップ

icpg init                          # Create .icpg/ and database
icpg bootstrap --days 90           # Infer ReasonNodes from git history
icpg bootstrap --days 90 --no-llm  # Without LLM (commit-message only)

作成と記録

icpg create "Add JWT auth" --scope src/auth/ --owner feature-auth --type task
icpg record --reason <id> --base main         # Record symbols from git diff
icpg record --reason <id> --edge-type MODIFIES # Record as modifications

クエリ（3つの標準クエリ）

icpg query prior "user authentication"     # 1. Duplicate detection
icpg query constraints src/auth/service.ts  # 2. Invariants for file
icpg query risk validateToken              # 3. Symbol risk profile
icpg query context src/auth/service.ts     # All intents for a file
icpg query blast <reason-id>               # Full blast radius

ドリフト

icpg drift check          # Full scan across all dimensions
icpg drift resolve <id>   # Mark drift event resolved

ステータス

icpg status               # Stats: reasons, symbols, edges, drift

---

ストレージ

プロジェクトごとに管理され、Git で無視されます。インフラストラクチャは不要です。

.icpg/
  reason.db       SQLite database (4 tables: reasons, symbols, edges, drift_events)
  .gitignore      Contains: *
  chroma/         ChromaDB vectors (if chromadb installed)
  tfidf_cache.json  TF-IDF fallback cache
  .current-intent   Marker file for active intent (used by Stop hook)

インストール方法：

pip install ./scripts/icpg            # Core (zero deps)
pip install "./scripts/icpg[vectors]"  # + ChromaDB for duplicate detection
pip install "./scripts/icpg[all]"      # + ChromaDB + scikit-learn + openai

---

ワークフロー：コードを変更する前に

0. INTENT       → icpg create (or identify existing intent)
1. DEDUP        → icpg query prior (check for duplicate work)
2. CONSTRAINTS  → icpg query constraints (understand invariants)
3. RISK         → icpg query risk (check fragile symbols)
4. LOCATE       → search_graph to find symbols (code-graph skill)
5. CHANGE       → Make the edit (PreToolUse hook shows context)
6. RECORD       → icpg record (link symbols to intent)
7. DRIFT CHECK  → icpg drift check (verify no unintended drift)
8. VERIFY       → Run tests, lint, typecheck

自律型エージェントにとって、ステップ0は必須です。 すべての変更は、明示された目的に関連付ける必要があります。意図がなければ、ドリフトを測定する基準がありません。

---

フックとの統合

PreToolUse フック（コンテキストを自動注入）

.claude/settings.json に追加します。

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "scripts/icpg-pre-edit.sh",
        "timeout": 3,
        "statusMessage": "Checking intent context..."
      }]
    }]
  }
}

ファイルを編集する前に、エージェントには次の情報が表示されます。

═══ iCPG CONTEXT ═══
INTENTS for src/auth/service.ts:
  [>] a1b2c3d4 — User authentication with JWT tokens
      Owner: feature-auth | Status: executing
      Invariants: 2
CONSTRAINTS for src/auth/service.ts:
  From intent: User authentication with JWT tokens
    INV: file_exists("src/auth/middleware.ts")
    POST: test_exists("src/auth/__tests__/service.test.ts")
PRESERVE function signatures unless your task requires changing them.
═══════════════════

Stop フック（シンボルを自動記録）

実装がテストに合格すると、シンボルが自動的に記録されます。

{
  "hooks": {
    "Stop": [{
      "hooks": [
        {"type": "command", "command": "scripts/tdd-loop-check.sh", "timeout": 60},
        {"type": "command", "command": "scripts/icpg-stop-record.sh", "timeout": 5}
      ]
    }]
  }
}

---

エージェントチームとの統合

更新後のパイプライン（agent-teams + iCPG）

 0. INTENT       Team lead creates ReasonNode from feature spec
 0b. DEDUP       icpg query prior — check for duplicate intents
 1. SPEC         Feature agent writes spec
 2. SPEC-REVIEW  Quality agent reviews spec + intent alignment
 3. TESTS (RED)  Feature agent writes tests
 4. RED-VERIFY   Quality agent verifies tests fail
 5. IMPLEMENT    Feature agent codes (PreEdit hook shows context)
 5b. RECORD      Auto-record symbols → intent (Stop hook)
 5c. DRIFT-CHECK Quality agent verifies no scope drift
 6. GREEN-VERIFY Quality agent verifies tests pass + coverage
 7. VALIDATE     Lint + typecheck + full suite
 8. CODE-REVIEW  Review agent (sees intent context per file)
 9. SECURITY     Security agent
10. BRANCH-PR    Merger agent (PR includes intent traceability)

エージェントの責務

エージェント	iCPG の操作
チームリード	タスクチェーンの作成時に icpg create を実行します。重複を確認するため icpg query prior を実行します。
機能エージェント	実装前に icpg query constraints を実行します。自動記録用に .icpg/.current-intent を書き込みます。
品質エージェント	GREEN 検証中に icpg drift check を実行します。スコープとの整合性を確認します。
レビューエージェント	ファイルのレビュー時に、PreToolUse フックを通じて意図のコンテキストを確認します。
マージエージェント	PR の説明に意図のトレーサビリティを含めます。

Git 履歴からのブートストラップ

既存のコードベースでは、コミット履歴から ReasonNodes を推定します。

icpg bootstrap --days 90 --verbose

これにより、次の処理が行われます。

1. 過去 90 日間のコミットを取得します
2. 時間的な近さ（2 時間のウィンドウ）に基づいてクラスタリングします
3. LLM（Claude または OpenAI）またはコミットメッセージの解析によって意図を推定します
4. source: "inferred"、confidence: 0.6-0.8 を設定して ReasonNodes を作成します
5. 変更されたファイルからシンボルを抽出し、CREATES エッジを作成します
6. 既存の ReasonNodes と重複していないか検出します

品質に関する注意： 推定された意図には、信頼度が低いことを示すマークが付けられます。価値の高いものを確認し、手動で昇格させてください。

---

コントラクト述語

述語は、コードベースの状態に対する構造化されたアサーションです。

file_exists("src/auth/middleware.ts")
test_exists("src/auth/__tests__/service.test.ts")
symbol_count("src/auth/") <= 15
function_signature("validateToken") == "(token: string) => Promise<User>"

コントラクトの作成方法は次のとおりです。

• リスクの高い ReasonNodes 用に手動で作成
• icpg create --infer-contracts によるLLM 推定
• ヒューリスティック（スコープ → file_exists、テスト → test_exists）

---

アンチパターン

アンチパターン	代わりに行うこと
意図を示さずにコーディングする	重要な変更を行う前に、毎回 icpg create を実行する
変更が他に影響しないと思い込む	まず icpg query constraints と icpg query risk を実行する
すでに存在するものを作り直す	icpg query prior で過去の作業を確認する
意図をいつまでも「executing」のままにする	完了したらステータスを「fulfilled」に更新する
ドリフトイベントを無視する	毎週 icpg drift check を実行し、解決するか新しい意図を作成する
シンボルにソース全体を保存する	署名とチェックサムのみを保存し、ソースはファイルから読み取る
既存のリポジトリでブートストラップを省略する	icpg bootstrap --days 90 を実行して初期グラフを構築する