以前の記事「Harness Engineeringとは何か」では、概念として「エージェントが動く実行環境そのものの設計」を扱いました。今回は、それを実際にどう構築するかを、Claude Codeを例に手を動かしながら見ていきます。
概念として理解するのと、自分の環境に組み込むのとでは、必要な作業がまったく違います。ここでは「知っている」を「作れる」に変えることだけを目的にします。
1. 最初の一歩：許可するツールを明文化する
Harness Engineeringの出発点は、「このエージェントに何をさせて良いか」をコードとして残すことです。口頭やドキュメントでの申し合わせではなく、設定ファイルとして明文化します。
Claude Codeでは、これはallowedTools（許可ツールリスト）として表現できます。
{
"allowedTools": [
"Read",
"Grep",
"Glob",
"Bash(git status)",
"Bash(git diff)",
"Bash(git log)"
]
}
この設定は「読む・調べる」系のツールだけを許可し、ファイルの書き換えやコミットは許可しません。エージェントに「まず調査だけしてほしい」フェーズでは、これだけで十分な境界線になります。
ポイントは、Bashをまるごと許可するのではなく、Bash(git status)のように実行できるコマンドパターンまで絞り込むことです。「Bashを許可する」は、実質「何でも許可する」と同じ意味になってしまいます。
2. 書き込み権限は、別レイヤーとして足す
調査フェーズで問題なければ、次に書き込み系の権限を追加します。ここでも一括で足さず、段階的に広げるのが安全です。
{
"allowedTools": [
"Read", "Grep", "Glob",
"Bash(git status)", "Bash(git diff)", "Bash(git log)",
"Edit",
"Write"
]
}
EditとWriteを足した時点で、エージェントはファイルの中身を変更できるようになります。ここまでは「自分のプロジェクトの中で完結する変更」なので、比較的リスクは低い領域です。
危険なのは、この次の段階——外部に影響が及ぶ操作です。
3. 不可逆な操作は、別枠で扱う
git push、外部APIへの送信、課金が発生する操作。これらは「一度実行すると取り消せない」という共通点があります。Harness Engineeringの実務では、この種の操作を他の権限と同列に並べません。
Claude Codeでは、これをフック（Hooks）で実現できます。実行前に必ず人の承認を挟む設定です。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash(git push*)",
"hooks": [
{
"type": "command",
"command": "echo '⚠️ git push が実行されようとしています。承認しますか？'"
}
]
}
]
}
}
このフックは、git pushを含むコマンドが実行される直前に必ず割り込みます。「調査・変更は自動、公開は人が最終確認する」という、Human-in-the-loopとは何かで扱った原則を、コード上で強制する形です。
4. 環境ごとにHarnessを分ける
同じエージェントでも、「調査用」「実装用」「公開用」で、許可すべきツールの範囲はまったく違います。1つの巨大な許可リストを使い回すのではなく、用途ごとに設定を分けることをお勧めします。
.claude/
settings.investigate.json # 読み取り専用
settings.implement.json # 読み書き可、push不可
settings.deploy.json # push・公開系も含む、承認必須
タスクの性質に応じて設定ファイルを切り替える運用にすると、「うっかり本番環境に書き込んでしまった」という事故を、そもそも起こりようのない状態にできます。
5. 実行ログを残す
最後に、Harness Engineeringの仕上げとして、エージェントが「何を、いつ、なぜ実行したか」を追跡できる形にしておきます。これはObservability設計と重なる部分ですが、最低限の記録だけはこの段階で組み込んでおくと後が楽になります。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Bash|Edit|Write",
"hooks": [
{
"type": "command",
"command": "echo \"$(date -u +%FT%TZ) $TOOL_NAME executed\" >> .claude/audit.log"
}
]
}
]
}
}
これだけで、後から「このエージェントは今日何をしたか」を人間が確認できるログが残ります。
まとめ
Harness Engineeringの実装は、大きく分けると次の4段階です。
- 読み取り系のツールだけを許可し、まず「調査させてみる」
- 書き込み系を段階的に足す
- 不可逆な操作（push・送信・課金）はフックで人の承認を必須にする
- 実行ログを残し、後から追跡できるようにする
理屈としては単純ですが、実際にやってみると「このコマンドは許可すべきか」という判断に何度も迷う場面が出てきます。迷ったら、「取り消せるか、取り消せないか」を基準にすると、判断がぶれにくくなります。
拙著『AIエージェント設計論 — Harness/Loop EngineeringからRAGまで』では、この考え方の全体像を扱っています。