AIエージェント
ハーネス設計ガイド

コンテキストファイルにはグローバル（ユーザー全体）・リポジトリ（プロジェクト）・ディレクトリ（サブ）の3スコープがある。スコープが狭いほど優先度が高く、広いスコープのルールを上書きできる。

コンテキストファイルに書いた情報はモデルが毎回読む。作業メモや一時的な状態はコンテキストファイルではなく外部ファイル（scratchpad等）に切り出し、必要な時だけ参照させる設計が望ましい。

ローカル開発と本番・CI/CDでは権限を分けて管理する。特にCI環境ではエージェントが触れるリソースを厳密に制限することが重要。

# 本番CI用 settings.json（Claude Code の例）
{
  "permissions": {
    "deny": [
      "Bash(rm *)",
      "Bash(curl *)",
      "Bash(wget *)",
      "WebFetch"
    ],
    "allow": [
      "Read",
      "Write(src/**)",
      "Bash(npm test)",
      "Bash(npm run lint)"
    ]
  }
}

PreToolUse で危険なコマンドをブロックするパターン。Decide型の典型例。

#!/bin/bash
# PreToolUse Hook — 危険コマンドブロッカー（Claude Code用）
INPUT=$(cat)
CMD=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_input',{}).get('command',''))")

# pipe-to-shell パターンをブロック
if echo "$CMD" | grep -qE '(curl|wget).*\|(bash|sh)'; then
  echo '{"decision":"block","reason":"pipe-to-shell is not allowed"}'
  exit 0
fi

exit 0  # allow

同様のパターンをCodex・Antigravityでも実装できる。出力フォーマットだけ異なる：

SessionStartでプロジェクト情報を自動注入するパターン。Transform型の活用例。

#!/bin/bash
# SessionStart Hook — プロジェクトコンテキスト自動注入
BRANCH=$(git branch --show-current 2>/dev/null)
TODO_COUNT=$(grep -r 'TODO' src/ 2>/dev/null | wc -l | tr -d ' ')

cat <<EOF
{
  "additionalContext": "現在のブランチ: ${BRANCH}\n未解決TODO: ${TODO_COUNT}件"
}
EOF

どちらの形式でも重要なのはシークレットを設定ファイルに直書きしないこと。APIキーやトークンは必ず環境変数か外部シークレットマネージャーを使う。

サブエージェントに付与する権限はそのタスクに必要な最小限にする。オーケストレーターが持つ権限をそのまま継承させるのは避ける。

// オーケストレーターがサブエージェントを生成する例（Claude Code SDK）
const subagent = await agent.createSubagent({
  task: "src/components/ のテストを追加する",
  permissions: {
    allow: ["Read(src/**)", "Write(src/**/*.test.ts)", "Bash(npm test)"],
    deny:  ["Bash(git push)", "Bash(rm *)"]  // pushとrmは禁止
  }
});