AIコーディングを安定させたくて、以前はプロンプトを細かく書く方向に寄りがちでした。
でも、個人開発でClaude CodeやCodexへ実装を任せていると、プロンプトだけでは埋まらない部分が結構あります。
どこまで触ってよいのか。何をもって完成とするのか。何回失敗したら人間へ戻すのか。
ここが決まっていないと、指示文を長くしても安心して任せられませんでした。
今の結論は、プロンプトを捨てることではありません。プロンプトを、小さな検証ループの中に置くことです。
最初からきれいに設計できたわけではなく、レビューで穴が見つかったり、禁止ルールが作業を止めたりするたびに直してきました。この記事では、その中で今も残している仕組みを書いてみます。
ハーネスとループ
「ハーネスエンジニアリング」「ループエンジニアリング」は、人によって少し定義が違います。自分はこんなふうに分けています。
- ハーネス: AIモデルの周りに置くルール、ツール、権限、検証環境
- ループ: 目的を受け取り、実行し、評価し、修正するか停止するまでの流れ
ざっくり言うと、ハーネスはAIが走るためのコースで、ループはそのコースをどう回るか。OpenAIのHarness engineeringの記事では、人間の仕事は環境設計、意図の明示、フィードバックループ作りだと整理されています。
AnthropicのBuilding effective agentsでも、明確な評価基準があり、反復で結果が良くなる場合にEvaluator–Optimizerの構成が向いていると説明されています。用語の境界より、「どこまでなら事故らず任せられるか」を基準にしました。
役割を分けても、受け渡しで詰まる
実装タスクはplanner、generator、evaluatorの3役に分けています。plannerが要件と受け入れ条件を作り、generatorが実装し、evaluatorがコードとテストを確認したうえで、型エラーやセキュリティ上の問題がないか、ユーザーが実際に使えるかまで見ます。同じAIが全部担当すると、自分で書いたコードに甘くなることがあるため、評価は別の役割へ渡しています。
この形を見直したとき、最初に見つかったのは仕様書の矛盾でした。あるリポジトリのルールでは、仕様書をrequirements、design、tasklistの3ファイルに分ける決まりなのに、plannerのテンプレートは単一ファイルのまま。個別にはそれらしく見える指示でも、受け渡し部分では食い違っていました。
合格条件も「いい感じに動く」ではなく、あとから観察できる形で書きます。
- キャンセルしたらデータは変わらない
- 失敗したら入力内容が残る
- 日付をまたいだら前日の操作を受け付けない
- 対象テスト、型チェック、lintが成功する
plannerが書いた条件をevaluatorがそのまま照合し、合否の結果には確認内容と根拠を残す。ここが地味に効きました。
人間が確認する3か所
全部をAIへ任せているわけではありません。個人開発では、方針、実装計画、完了の3か所で確認しています。
課金や認証、データベースまわりは、自動で決めない範囲です。外部公開やプロダクトの主要な体験も、人間が確認します。同じ実装で3回詰まったら止める上限があるので、終わるまで動かし続けることもありません。
ルールは実行時にも守る
最初は「--no-verifyを使わない」「force pushしない」とドキュメントへ書いていました。それだけでは実行時に止まらないため、危険なgitコマンドを実行前に止めるhookを追加しています。ルールをお願いから仕組みに変えた感じです。
セッションの最後には、何を直したか、どこで詰まったかをログへ残します。ただし、全部を永続ルールにはしません。繰り返しそうな失敗だけを、次のルールや実装パターンへ移しています。
7月のレビュー
2026年7月、ちょうどClaude Fable 5を使える期間だったので、このAI開発環境をまとめてレビューしてみました。形はできていたつもりでしたが、細かく読むとまだ穴がありました。
evaluator向けには「たぶん大丈夫で合格にしない」と書いていたものの、見つけた問題を総評で弱めたり、作業量に加点したりするのを止める条件がありませんでした。そこで、問題を根拠なしで打ち消さないことと、合格基準を実行結果へ固定することを追加しました。
修正の2回目以降にも、前回レポートを読む手順がありませんでした。generatorの「直しました」をそのまま受け取らないよう、前回指摘を最初に一覧化し、修正済み、未修正、別の問題を生んだ、の3点を確認してから次のレビューへ進みます。
generator側では、レビューコメントを全件並べ、対応内容を1行ずつ残す形へ変えました。不同意なら黙って無視せず、理由を書いてevaluatorへ返す決まりです。
ガードがコミットを止めた日
hookを追加した直後、その変更を説明するコミットメッセージに --no-verify と書いたところ、作ったばかりのガードに止められました。実行オプションだけでなく、説明文の文字列まで拾っていたためです。
引用文字列やコミットメッセージの本文を除外してから判定するように直し、ガード自体にも回帰テストを追加しました。ルールを機械的に強くすると、誤検知も機械的に作業を止めます。
ガードを強くするなら、ガード自身にもテストが必要です。
入れなかった仕組み
ハーネスを調べると、自動で学びをスコア化する仕組み、10点満点の評価、夜中に何時間も回す自律ループなどが出てきます。どれも面白いのですが、今回は見送りました。個人開発では、仕組みを管理する時間の方が大きくなりそうだったためです。
Anthropicの長時間開発向けハーネスの記事では、ハーネスは「モデルにできないこと」への仮定を含み、モデルの進化で古くなる可能性があると説明されています。必要になったら足し、不要になったら外す。このくらいが今の規模には合っています。
今のハーネスを1枚にまとめると
今使っている仕組みを、実装前に確認するカードへ落とすと次の形です。
目的:
作業場所:
触ってよい範囲:
禁止事項:
検証方法:
最大試行回数:
人間が確認する場所:
停止条件:
最初に試すなら、1PR、1ユーザーフローくらいの単位で十分です。例えば「削除確認を追加する」なら、キャンセル、確定、関連データが残るかまでを検証条件にします。3回直しても通らなければ、人間へ戻す。
このくらいでも、任せる範囲はかなり分かりやすくなりました。
プロンプトを直す前に
ハーネスやループを整えても、プロンプトは使います。何を作るか、なぜ作るかは、今も人間が言葉にしないと始まりません。
変わったのは、毎回すべての注意事項を書かなくても済むようになったことです。指示文の言い回しを考える時間も減りました。今は、何を目指すか、どこまで任せるか、何を合格にしていつ止めるかを先に決めています。
確認作業を減らすために、小さなループを作る。この進め方が自分には合っていました。
あくまで個人開発で試した範囲ですが、AIコーディングの差し戻しが増えているなら、プロンプトを長くする前にループカードを1枚作ってみると、原因を見つけやすくなるかもしれません。