前編で紹介したアイマス診断ツール iMAS Chara Match は、単にAIに実装させたのではなく、「AIが仕様を無視して勝手に作る/テストを書かない/レビューをすり抜ける」を仕組みで防ぐハーネスを組んだ上で作りました。後編はその開発手法 ―― 仕様駆動開発(SDD)と、それをClaude Codeのフックで強制する仕掛け ―― を解説します。
↓リポジトリはこちら
この記事のゴール
- AIコーディングの「勝手に作る」問題を、プロンプトではなく決定論で抑える発想を知る
- SDDの5段階ワークフローと人間の承認ゲートを理解する
- Claude Codeのフック・サブエージェント・スキル・プロファイルで監督層をどう組んだかを知る
対象読者は、AIエージェントに大きめの実装を任せたいが「品質を担保できるのか」が不安な人です。
1. なぜ ― AIコーディングの「勝手に作る」問題
AIエージェントに実装を丸ごと任せると、こういうことが起きがちです。
これらは 散文の指示(「〜してください」「〜は禁止です」)だけでは防げません。自然言語のプロンプトは確率的にしか効かないからです。README に「domain は Web に依存しないこと」と書いても、AI がうっかり import すれば通ってしまいます。
そこで発想を変えます。
守らせたいことは、お願い(プロンプト)ではなく、壁(決定論的なガード)にする。
これを実現するのが SDD(仕様駆動開発) と、それをAIに強制する ハーネス です。
2. SDDの5段階ワークフロー
開発は次の5段階を順に進めます。各段階はClaude Codeのスキル(/discover のようなスラッシュコマンド)で駆動し、AIが成果物を起草し、人間が承認するまで次に進めません。
各段階の成果物は先頭に Status: Draft を持ち、人間がレビューして Status: Approved に変えるまで凍結されます。「コードの前に仕様を固め、承認された仕様にコードを錨付ける(spec-anchored)」進め方です。
記法 ― EARS と Gherkin
-
要件は EARS 形式で書く(例:
WHEN <トリガー>, the <システム> SHALL <応答>)。EARSは「ルールの台帳」。 - **受け入れ基準は Gherkin(Given-When-Then)**で書く。EARS要件1件に対しシナリオが複数ぶら下がる(正常系・異常系・境界値)。
- Gherkinの一次著作は specify段階の1回だけ。下流(tasks/implement)は参照・変換するだけで新規作成しない。これで「仕様が実装のたびに揺れる」のを防ぐ。
# acceptance.feature の例(イメージ)
Rule: 推薦に適さない好み入力は、推薦を実行せず理由が分かる形で拒否される
Scenario: 空文字は拒否される
Given 好み入力が空文字である
When 推薦を要求する
Then 推薦は返らず、入力が不正である旨が返る
Scenario: 200文字ちょうどは受理される
Given 好み入力が200文字である
When 推薦を要求する
Then 推薦一覧が返る
3. 役割分担 ― 進行役・ワーカー・レビュアー
各段階は、役割別のサブエージェントに委譲して進めます。進行役は自分で成果物を書かず、Claude Code の Agent ツールで実際に別コンテキストのエージェントを起動します。
- discover は3アナリスト(product / quality / solution)を並行起動して観点を出し、進行役が統合
- specify は scenario-author が EARS + Gherkin に清書
- plan / tasks は solution-analyst が設計・分解
- implement は engineer が TDD で実装
- 実装後はレビュー役を独立コンテキストで回す。実装者の思い込みが持ち込まれないので、レビューが「自作自演」になりません
4. ハーネス ― 方法論を"決定論"で強制する
ここが本題です。**「絶対に起きてはならないこと」は、READMEの文章では強制できません。**本物のガードレールを Claude Code のフック(PreToolUse) に置きました。
4つのガード
| フック | 何を止めるか |
|---|---|
guard_architecture.py |
Clean Architecture違反(domain/applicationへのFW import、直接SQL) |
guard_sdd_gates.py |
SDDゲート違反(前段が未承認なのに次段を書く/承認済み文書を書き換える) |
guard_no_verify.py |
pre-commit迂回(--no-verify、-n、SKIP=、core.hooksPath差し替え等) |
guard_harness.py |
人間ゲート(ask)。specsへのStatus: Approved書き込み(AIの自己承認防止)と、強制層自体への変更に人間の承認を要求 |
たとえば、AIが domain/ 層でうっかり from fastapi import ... と書こうとすると、編集がその場で拒否されます。「domain は何にも依存しない」という不変条件が、願いではなく実行時の壁になっているわけです。
実際にガードを発火させると、こう止まります(本物の guard_architecture の出力)。
編集は実行されず、AIが何度試行しても domain 層の純粋性は崩れません。
承認ゲートの凍結と、差し戻しフロー
Status: Approved になった仕様は編集不可になります。変更したいときは次の道しか通れません。
これで「承認済みの仕様をこっそり書き換えて実装を通す」ができなくなります。
検証の連鎖 ― 「修正を守る仕組み」まで閉じている
徹底しているのは、ガード自体にも検証がある点です。
- ガードを直したら →
test_guards.py(79ケースの自己テスト)が pre-commit/CI で走り、テストと不整合な修正はコミット不可 - プロファイルを直したら →
validate.py(契約適合チェック)が走る - 実装を直したら → 編集時ガード+品質ゲート(lint・型・アーキ検証・テスト)
- 迂回しようとしたら →
guard_no_verifyが--no-verifyなどの迂回自体を遮断
つまり検証の連鎖は「実装 ← ガード ← ガードのテスト」まで遡って閉じており、どの層の修正にも"それを検査する層"が存在する。唯一の例外はスキル・エージェントの散文で、そこは人間レビューが最後の砦。
5. スタック差し替え層 ― プロファイル
方法論(SDDワークフロー・不変条件)はスタック非依存に保ち、技術固有のもの(層→実ディレクトリの対応、禁止import、テストコマンド、実装者エージェント)は .claude/profiles/<id>/ に隔離しました。
このハーネスは、変わる頻度で4つに区分されています。
今回のプロファイルは python-fastapi(FastAPI + React)。別スタックで作りたくなったら、プロファイルを1式書けば同じSDDハーネスがそのまま使えます。profile.yml が「単一の真実」で、ガードフックもこの guard: セクションを直接読みます(設定の二重化=driftを避けるため)。
6. 実際の開発の流れ ― 2機能をフルサイクルで
Git履歴を辿ると、SDDフルサイクルを2機能分きれいに完走しているのが見えます。
Feature 0001 ― 推薦API(backend)
discover段階でExample Mapを使い、価値・ルール・具体例・疑問を洗い出しました。ここで潰した「疑問」の例:
- 対象は何人か? → 資料が14人/15人で食い違っていたのを実データで確認して14人に確定
- 上限超過は切り詰めか拒否か? → 拒否(黙って切り詰めると利用者が理由を失う)
- 低類似度の閾値を設けるか? → 設けない(生値の絶対値解釈が難しく根拠ある閾値を今決められない)
specify段階でEARS要件と38本のGherkinシナリオに清書。implement段階のTDDは、Git履歴がそのまま内側→外側の層の順序になっています。
feat(domain): 好み推薦のドメインモデルを実装(T04〜T10)
feat(application): ポートとユースケースを実装(T11・T13)
feat(adapters): API契約とエラー写像を実装(T14〜T16)
feat(infrastructure): 設定・ローダ・埋め込み器を実装(T17〜T21)
test(acceptance): 38シナリオ全件をgreenにする
Feature 0002 ― 最小Web UI(frontend)
0001の推薦を人が触れる形に落とす薄いクライアント。React 19 + Vite + Atomic Design で、27本のGherkinシナリオを定義しました。
- 業務ルール(長さ上限・正規化・整列・類似度値域)は backend/domain が唯一の正。UIに再実装しない
- 状態の3表示(送信中/一覧/エラー)と、エラーの日本語切り分け(入力起因422/サーバ都合503・504・500/通信断)
- 二重送信・stale応答の防止
UIの状態遷移はこう設計しました。
サーバが応答できないときは、真っ白にせず日本語のエラーを出して「次にどうするか」を伝えます。
7. やってみて ― 学び
効いたこと
- 「コードの前に仕様を固める」規律が、AIの暴走を根本から抑える。discover で「疑問」を明示的に潰すのが特に効いた
- 強制は散文ではなくフックに置く。domainのFW依存を「願う」のではなく編集時に「弾く」。何度試行しても不変条件が崩れない
- レビューを独立コンテキストのサブエージェントに回すと、実装者の思い込みが持ち込まれない
- テストダブルで重い依存を隔離すると、CIが軽くなり、受け入れ基準を決定論的に書ける
一言でいうと
「AIに任せる」の質は、任せる前にどれだけ仕組みを作れるかで決まる。
プロンプトで頼むのではなく、守らせたいことをフックとゲートに落とし込む。SDDはそのための良い骨格でした。
まとめ
- 前編:何を・どんな仕組みで作ったか(埋め込み×コサイン類似度、Clean Architecture)
- 後編(この記事):AIに設計通り実装させるハーネス(SDD 5段階、4つのガード、プロファイル)
このハーネスは汎用テンプレート sdd-harness をベースにしています。同じ骨格を別スタック・別プロダクトにも持ち込めるよう設計しました。
👉 前編を読む 【前編】自然文の「好み」からアイマスのキャラを推薦するツールを作った
by NeoSoleil

