AI Coding Harness

概要

AI コーディングハーネスとは、コーディングエージェントが何かを壊すことなく自律的に動作できるよう、その周囲に構築する強制と検証のための足場です。ガードレールが自分で覚えておかなければならない習慣（テストを実行する、差分を読む）であるのに対し、ハーネスは代わりに覚えてくれる機械です。エージェントの意図と現実世界の間に位置し、危険なステップのたびに記録し、警告し、あるいはブロックします。dancinlab/harness はプロジェクト非依存のリファレンスエンジンであり、共有された TypeScript コアを基盤として、各リポジトリは harness.config.json といくつかの .harness/*.json データファイルだけが異なります。

強み

ガードレールを任意の習慣からコードによって強制されるルールへと変える — エージェントはそれをスキップできません。
ツールのライフサイクル全体をゲートで管理します。コマンドが実行される前、ファイルが書き込まれる前、プロンプトに対して、コミット時、そしてプッシュ時に。
追記専用の JSONL 台帳が、エージェントが行ったすべてを改ざん検知可能な形で記録します。書き込みは安価で、監査も容易です。
どんなリポジトリにも組み込めます。挙動はコードのフォークではなく、設定とデータで決まります。
問題がないときは静かに保つよう設計されているため、警告が出たときにはそれが意味を持ち続けます。

トレードオフ

これは配管であって魔法ではありません。ハーネスは間違いを安価に検知できるようにするだけで、AI を正しくするわけではありません。
初期セットアップと、プロジェクトの危険地帯に合わせて調整された設定が必要です。
厳しすぎるルールは摩擦を生みます。「bitter-gate」の規律（新しいルールを追加する前に休眠中のルールを廃止する）は、まさにこれと戦うために存在します。
実際のユーザーがいる実プロジェクトで最も価値があります。使い捨てのプロトタイプには過剰です。

最適な用途

エージェントに複数ファイルにまたがる変更を行わせ、コマンドをほぼ監視なしで実行させる本格的なバイブコーディングで、悪い操作のコストをゼロ近くに保つ必要がある場合。

5 つの原則 (H1–H5)

H1 成功は静かに、失敗は大きく — 無視するようになるノイズを出さない。
H2 自動修正は決してしない — 提案、ブロック、または警告する。決めるのは人間か、状況を把握したエージェント。
H3 Bitter-gate — 新しいルールを追加する前に、休眠中のルールを廃止する。
H4 設定駆動 — エンジンは 1 つ、プロジェクトごとに harness.config.json。
H5 AI ネイティブ — 追記専用の JSONL 台帳。こっそり書き換えることは不可能。

実際の姿

最小限の設定のスケッチ:

// harness.config.json
{
  "lockedPaths": ["src/auth/**", "infra/**", ".github/**"],
  "blockCommands": ["rm -rf", "git push --force", "curl * | sh"],
  "verify": ["npm run lint", "npm run typecheck", "npm test"],
  "ledger": ".harness/ledger.jsonl"
}

そして、単一のエージェント操作を取り巻く pre/post フックの流れ:

agent intends an action
        │
   ┌────▼─────────────┐
   │ pre  (PreToolUse) │  block dangerous? warn? → else allow
   └────┬─────────────┘
        │  command runs / file is written
   ┌────▼──────────────┐
   │ post (PostToolUse) │  record to JSONL · warn if a locked file was touched
   └────┬──────────────┘
        │  at commit / push
   ┌────▼─────┐
   │  verify  │  lint · typecheck · tests (parallel) → green or stop
   └──────────┘

エージェントはゲートを回避できません — それがすべての要点です。