エージェントのハーネス早見表：構成要素、ファイル、よくある問題、起動チェックリスト

ハーネスの5つのサブシステム

ゼロから作る場合の順序は、フィードバック → 指示 → 状態 → 環境 → ツールです。

ハーネスのファイル

AGENTS.md の骨組み

# プロジェクト：決済バックエンド（FastAPI、PostgreSQL）

## 起動
docker compose up -d && ./scripts/init.sh

## 検証
make check   # リンター、型、単体テスト、arch-check
make e2e     # エンドツーエンドのシナリオ

## 完了の定義
- make check と make e2e が終了コード0
- 機能は scripts/verify.sh で passing に設定されている
- PROGRESS.md が更新されている

## MUST
- DBアクセスはリポジトリ経由のみ
- シークレットは環境変数からのみ読む

## ドキュメント
- docs/payments.md——決済と返金に関わるタスク
- docs/migrations.md——DBスキーマを変更するタスク

機能の状態

検証の層

一番上の層を通過して初めて「完了」と言えます。緑の単体テストは完了ではありません。

ルールの機械化

#!/usr/bin/env bash
fail=0
if grep -rn "from app.db" app/services/; then
  echo "WHY: サービス層は DB に直接アクセスしない"
  echo "FIX: app/repositories/ のリポジトリを使う"
  fail=1
fi
exit $fail

よくある問題と対処法

長いタスクにおける役割

自律作業の予算

• 目標は一文で書く（例：すべての機能を passing にする）。
• WIP=1。機能ごとに時間と試行回数の上限を設ける。
• 指標は単調に増え、回帰が起きたら即座にロールバックする。
• マイグレーション、インフラ、お金は人に引き継ぐ。
• レビューが何度も失敗したら、その機能はクリーンなコンテキストで最初からやり直す。

エージェント起動のチェックリスト

1. AGENTS.md がある：技術スタック、起動方法、検証コマンド、完了の定義。
2. クリーンなクローンで make check が通る。
3. 環境が再現可能：ロックファイル、Docker または devcontainer。
4. エージェントに必要なコマンドの権限があり、危険なコマンドは禁止されているかサンドボックス内にある。
5. 主要なシナリオを一つ以上カバーする E2E テストがある。
6. PROGRESS.md があり、セッションの開始時に読むよう定められている。
7. 機能リストにステータスがあり、アクティブなのは一つだけ。
8. passing の設定はスクリプトが行う。
9. 検査のメッセージに WHY と FIX が含まれる。
10. タスクに受け入れ基準があり、スコープの境界が明確。
11. 人間の判断が必要な事項が明確になっている。
12. 変更の前に verification gap を計算し、後で比較できるようにしている。

ハーネスの指標

まとめ

ハーネスはファイル一つではなく、指示、ツール、環境、状態、フィードバックからなる一つのループです。検証から始め、AGENTS.md は短く保ち、「完了」の判定はスクリプトに任せ、ハーネスを定期的に見直してください。これらはすべて、ハーネスエンジニアリングの講座で、実際のプロジェクトを通した完全なハーネスとしてまとめています。