【Claude Code】実装と評価をAIに任せても設計がブレない仕組み｜15ステップ実践と全コード
昨日決めた方針を、今日の Claude Code はもう覚えていません。
「圧縮のあと、前提が抜けている」
「レビューしてと頼むと、自分の実装を褒めて終わる」
この記事では、計画・実装・評価を分けて開発を任せる「開発ハーネス」の作り方と、状態を残すファイルの中身を全部出します。
この仕組みで、自作の Web サービスの 15 ステップをエージェントに実装させました。エージェントが QUESTIONS.md に書いた確認事項は、Q1〜Q19 の 19 件です（2026-10-19 時点）。
こんな場面に心当たりはありませんか
長い会話の途中で、最初に決めた方針と違うコードが出てくる
同じ会話で「レビューして」と頼むと、問題なしで返ってくる
ライブラリやデータ構造が、相談なしに変わっている
翌日に再開するたびに、前提を説明し直している
1 つでも当てはまるなら、この記事はあなた向けです。
原因は、指示の書き方ではありません
プロンプトや CLAUDE.md の書き方のせいではありません。
計画も進み具合も、会話の中にしか置いていないからです。
会話は圧縮されれば要約になります。サブエージェントは、メインの会話の履歴を持たずに起動します。
だから私は、状態を会話からファイルに移しました。
遠回りした 2 つの失敗
1 つ目は、2026 年 6 月に作った開発ハーネスの最初の版です。
計画から全フェーズまで一気に自動で回す作りで、評価が不合格のままでも、5 回で打ち切って次のフェーズへ進みます。
スクレイピングを AI に設計させるサービスの試作で使うと、知見を残すファイル（KNOWLEDGE.md）に、同じフェーズの節が 2 つずつできていました（Phase 2〜5）。
2 つ目は、2026 年 8 月、別の自作エージェント基盤での失敗です。
LLM の呼び出しに失敗すると既定の雛形が返る作りで、実施していないレビューが「70 点・条件付き承認」として保存されていました。
実測では、10 回中 3〜4 回が失敗していました。開発ハーネスの方は、評価の結果が返らなければ合格にしない作りです（第 4 章）。
転機: 計画は人と作り、実装と評価だけを任せた
2026 年 10 月 10 日、1 ステップずつ進める版に作り替えました。
計画（PLAN.md）は、既存の設計書をもとに、メインの会話で Claude Code と一緒に作ります。エージェントに任せるのは、1 ステップの実装と評価だけです。
設計から外れる判断が出たら、エージェントは QUESTIONS.md に選択肢と推奨を書いて止まります。
結果は次のとおりです（PROGRESS.md・QUESTIONS.md・git の記録、2026-10-10〜10-19）。
15 ステップすべてが DONE
確認事項は Q1〜Q19。18 件が設計判断、1 件が私への作業依頼
コミットは 41 件
実装と評価はエージェントが行いました。確認事項には、私か、メインの会話で Claude Code と相談して答えています。
PROGRESS.md の実物から 2 行を抜き出すと、次のとおりです（表を箇条書きに直し、内容に関わる語は〈〉で伏せています）。
- Step 6: IaCとデプロイのパイプライン — DONE — 評価合格(1イテレーション)。Q10 の回答を反映。本番への適用は未実施
- Step 14: 〈対象〉の一括置き換え(core) — DONE — 2回目の実行で評価合格(1回目の評価で見つかった〈形式〉の不具合を修正、Q15〜Q17 を反映)
以前の記事で「状態を管理する 3 つのファイル」と予告しました。後から足した 4 つ目の QUESTIONS.md も含めて出します。
配る前に、一般化した版を動かしました
実物にはプロジェクト固有の名前やパスが入っているので、配布用に一般化して書き直しました。
一般化した版は、Claude Code のエージェントに使い捨てのリポジトリで計 6 回（Workflow 版 4 回・サブエージェント版 2 回）動かさせ、できたファイルを確認しています（2026-11-03）。
Workflow 版（全工程、計画だけ）: 5 観点のレビューの指摘を反映した PLAN.md ができた
Workflow 版（1 ステップ）: 設計に触れるステップを渡すと、実装せず BLOCKED で止まった
サブエージェント版: 計画 1 回、1 ステップの実装と評価 1 回が、想定どおりに動いた
Workflow 版（全工程、修正後）: 計画から 3 フェーズの実装・評価まで完走し、すべて DONE、テスト 5/5
Workflow 版（1 ステップ、修正後）: 同じステップを 2 回動かしても BLOCKED で止まり、記録も確認事項も重複しなかった
サブエージェント版は、元の環境に同じ形のものが無かったため、この記事のために新しく設計しました。確認は 2 回だけで、そのあと変えたスキルの文言は、まだ動かしていません。
Workflow 版は、2026-11-03 時点で Pro を含む全有料プランで使えます（Pro は /config で有効化）。
読み終えると、できるようになること
リポジトリに 4 つの状態ファイルを置く
新しい会話でも、ファイルだけを読ませて続きから再開する
実装役と評価役を、別のエージェントに分ける
不合格の指摘を、上限回数つきで実装役に差し戻す
設計から外れる判断で AI を止め、人の回答で再開する
計画を、実装の前に 5 つの観点でレビューさせる
Workflow を使わない環境でも、サブエージェントで同じ形を組む
有料部の目次（全 8 章）
第 1 章 全体像: 3 つの役割と 4 つのファイル（なぜ会話でなくファイルか）
第 2 章 PLAN.md と、CLAUDE.md の止まる条件（ステップと受け入れ基準の書き方）
第 3 章 PROGRESS.md と KNOWLEDGE.md（重複させない記録の仕方）
第 4 章 実装役と評価役を分ける（構造化出力と、上限つきの差し戻し）
第 5 章 AI に決めさせない: QUESTIONS.md と BLOCKED（評価まで行ってから止める理由）
第 6 章 計画を先に叩く: 5 観点のレビュー（planOnly と executeOnly）
第 7 章 動かし方 2 通り（Workflow 版とサブエージェント版の全ファイル）
第 8 章 運用で決めたこと・つまずき（使わない場面と、人が見る箇所）
最後に、導入のチェックリストも付けました。
こんな方に向いています
Claude Code を毎日使い、数日かかる開発を任せたい方
AI が設計にない判断を黙って入れることに困っている方
サブエージェントや CLAUDE.md を触ったことがある方
こんな方には向きません
Claude Code を使ったことがない方（インストールや基本操作は扱いません）
1 ファイル・数十行の修正が中心の方（トークンを多く使うので割に合いません）
コードを読まずに完成品が出てくることを期待する方（確認事項への回答と最終確認は残ります）
特典: コピーして置ける 5 点
全工程版のワークフロースクリプト: 計画とレビューから、全フェーズの実装・評価まで回す
1 ステップ版のワークフロースクリプト: 設計から外れる判断で止まる
サブエージェント 3 体の定義と指揮役のスキル: Workflow を使わない環境用
状態ファイル 4 つと「止まる条件」のテンプレート: リポジトリ直下に置くだけ
計画レビュー 5 観点のプロンプト: 計画だけ先に叩きたいときに単体で使える（起動用のコマンド定義も付けます）
では、本編に入ります。
