wiring

配線の検証

インフラストラクチャコンポーネントを構築する際は、実行パスで実際に呼び出されることを確認してください。

パターン

すべてのモジュールには明確なエントリーポイントが必要です。デッドコードはコードがないよりも悪く、メンテナンスの負担と誤った安心感を生みます。

4 ステップの配線チェック

インフラストラクチャを「完了」とする前に、次の項目を確認してください。

1. エントリーポイントがある：ユーザーの操作によって、このコードはどのように実行されますか？
2. 呼び出しグラフを追跡できる：エントリーから実行までの経路をたどれますか？
3. 統合テストを実施した：エンドツーエンドテストでこの経路を検証していますか？
4. デッドコードがない：構築したすべてのコンポーネントに到達できますか？

実施すること

エントリーポイントを確認する

# Hook registered?
grep -r "orchestration" .claude/settings.json

# Skill activated?
grep -r "skill-name" .claude/skill-rules.json

# Script executable?
ls -la scripts/orchestrate.py

# Module imported?
grep -r "from orchestration_layer import" .

呼び出しグラフを追跡する

# Entry point (hook)
.claude/hooks/pre-tool-use.sh
  ↓
# Shell wrapper calls TypeScript
npx tsx pre-tool-use.ts
  ↓
# TypeScript calls Python script
spawn('scripts/orchestrate.py')
  ↓
# Script imports module
from orchestration_layer import dispatch
  ↓
# Module executes
dispatch(agent_type, task)

エンドツーエンドでテストする

# Don't just unit test the module
pytest tests/unit/orchestration_layer_test.py  # NOT ENOUGH

# Test the full invocation path
echo '{"tool": "Task"}' | .claude/hooks/pre-tool-use.sh  # VERIFY THIS WORKS

配線をドキュメント化する

## Wiring

- **Entry Point**: PreToolUse hook on Task tool
- **Registration**: `.claude/settings.json` line 45
- **Call Path**: hook → pre-tool-use.ts → scripts/orchestrate.py → orchestration_layer.py
- **Test**: `tests/integration/task_orchestration_test.py`

実施しないこと

配線せずに構築する

# BAD: Created orchestration_layer.py with 500 lines
# But nothing imports it or calls it
# Result: Dead code, wasted effort

# GOOD: Start with minimal wiring, then expand
# 1. Create hook (10 lines)
# 2. Test hook fires
# 3. Add script (20 lines)
# 4. Test script executes
# 5. Add module logic (iterate)

並行するルーティングを作成する

# BAD: Agent router has dispatch logic
# AND skill-rules.json has agent selection logic
# AND hooks have agent filtering logic
# Result: Three places to update, routing conflicts

# GOOD: Single source of truth for routing
# skill-rules.json activates skill → skill calls router → router dispatches

インポートが機能すると決めつける

# BAD: Assume because you wrote the code, it's imported
from orchestration_layer import dispatch  # Does this path exist?

# GOOD: Verify imports at integration test time
uv run python -c "from orchestration_layer import dispatch; print('OK')"

統合テストを省略する

# BAD: Only unit test
pytest tests/unit/  # All pass, but nothing works end-to-end

# GOOD: Integration test the wiring
pytest tests/integration/  # Verify full call path

よくある配線漏れ

フックが登録されていない

// .claude/settings.json - hook definition exists but not in hooks section
{
  "hooks": {
    "PreToolUse": []  // Empty! Your hook never fires
  }
}

修正方法：フックの登録を追加します。

{
  "hooks": {
    "PreToolUse": [{
      "matcher": ["Task"],
      "hooks": [{
        "type": "command",
        "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/orchestration.sh"
      }]
    }]
  }
}

スクリプトが実行可能ではない

# Script exists but can't execute
-rw-r--r-- scripts/orchestrate.py

# Fix: Make executable
chmod +x scripts/orchestrate.py

モジュールをインポートできない

# Script tries to import but path is wrong
from orchestration_layer import dispatch
# ModuleNotFoundError

# Fix: Add to Python path or use proper package structure
sys.path.insert(0, str(Path(__file__).parent.parent))

ルーターにディスパッチ経路がない

# BAD: Router has beautiful mapping
AGENT_MAP = {
    "implement": ImplementAgent,
    "research": ResearchAgent,
    # ... 18 agent types
}

# But no dispatch function uses the map
def route(task):
    return "general-purpose"  # Hardcoded! Map is dead code

# GOOD: Dispatch actually uses the map
def route(task):
    agent_type = classify(task)
    return AGENT_MAP[agent_type]

配線チェックリスト

インフラストラクチャを「完了」とする前に、次の項目を確認してください。

• エントリーポイントを特定し、テストした（hook/skill/CLI）
• 呼び出しグラフをドキュメント化した（entry → module execution）
• 統合テストで全経路を検証した
• 孤立したモジュールがない（すべてがインポートまたは呼び出される）
• 登録が完了している（settings.json/skill-rules.json）
• 権限が正しい（スクリプトが実行可能）
• インポートパスを検証した（手動インポートテストに合格）

実例

例 1：DAG オーケストレーション（このセッション）

構築したもの：

• opc/orchestration/orchestration_layer.py（500 行以上）
• opc/orchestration/dag/（DAG ビルダー、バリデーター、エグゼキューター）
• 18 種類のエージェント定義
• 高度なルーティングロジック

配線漏れ：

• orchestration_layer.py を呼び出すフックがない
• DAG モジュールをインポートするスクリプトがない
• エージェントのルーティングが、ハードコードされた「general-purpose」を返す
• 結果：コードの 100% がデッドコード

修正方法：

1. Task ツール用の PreToolUse フックを作成する
2. フックから scripts/orchestrate.py を呼び出す
3. スクリプトで orchestration_layer.dispatch() をインポートして呼び出す
4. ディスパッチで AGENT_MAP を使い、実際のエージェントにルーティングする
5. 統合テスト：Task を送信し、正しいエージェント種別が使われたことを確認する

例 2：アーティファクトインデックス（前回のセッション）

構築したもの：

• SQLite データベーススキーマ
• インデックス作成ロジック
• クエリー関数

配線漏れ：

• インデックス作成をトリガーするフックがない
• ファイルは作成されるが、インデックス化されない

修正方法：

1. Write ツールに PostToolUse フックを設定する
2. フックからインデックス作成スクリプトを即座に呼び出す
3. 統合テスト：ファイルを書き込み、インデックス化されたことを確認する

検出方法

孤立したコードを grep で検索する

# Find Python modules
find . -name "*.py" -type f

# Check if each is imported
for file in $(find . -name "*.py"); do
  module=$(basename $file .py)
  grep -r "from.*$module import\|import.*$module" . || echo "ORPHAN: $file"
done

フックの登録を確認する

# List all hooks in .claude/hooks/
ls .claude/hooks/*.sh

# Check each is registered
for hook in $(ls .claude/hooks/*.sh); do
  basename_hook=$(basename $hook)
  grep -q "$basename_hook" .claude/settings.json || echo "UNREGISTERED: $hook"
done

スクリプトの実行を検証する

# Find all Python scripts
find scripts/ -name "*.py"

# Test each can be imported
for script in $(find scripts/ -name "*.py"); do
  uv run python -c "import sys; sys.path.insert(0, 'scripts'); import $(basename $script .py)" 2>/dev/null || echo "IMPORT FAIL: $script"
done

出典

• このセッション：DAG オーケストレーションの配線漏れ — 500 行以上のデッドコードを発見
• 以前のセッション：アーティファクトインデックス、LMStudio の統合 — 初期構築後に配線を追加