4
3

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

【後編】AIに"設計通り"実装させる ― 仕様駆動開発(SDD)ハーネスをClaude Codeで組んだ

4
Last updated at Posted at 2026-07-25

前編で紹介したアイマス診断ツール 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 の出力)。

image.png

編集は実行されず、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の状態遷移はこう設計しました。

サーバが応答できないときは、真っ白にせず日本語のエラーを出して「次にどうするか」を伝えます。

image.png


7. やってみて ― 学び

効いたこと

  • 「コードの前に仕様を固める」規律が、AIの暴走を根本から抑える。discover で「疑問」を明示的に潰すのが特に効いた
  • 強制は散文ではなくフックに置く。domainのFW依存を「願う」のではなく編集時に「弾く」。何度試行しても不変条件が崩れない
  • レビューを独立コンテキストのサブエージェントに回すと、実装者の思い込みが持ち込まれない
  • テストダブルで重い依存を隔離すると、CIが軽くなり、受け入れ基準を決定論的に書ける

一言でいうと

「AIに任せる」の質は、任せる前にどれだけ仕組みを作れるかで決まる。

プロンプトで頼むのではなく、守らせたいことをフックとゲートに落とし込む。SDDはそのための良い骨格でした。


まとめ

  • 前編:何を・どんな仕組みで作ったか(埋め込み×コサイン類似度、Clean Architecture)
  • 後編(この記事):AIに設計通り実装させるハーネス(SDD 5段階、4つのガード、プロファイル)

このハーネスは汎用テンプレート sdd-harness をベースにしています。同じ骨格を別スタック・別プロダクトにも持ち込めるよう設計しました。

👉 前編を読む 【前編】自然文の「好み」からアイマスのキャラを推薦するツールを作った


by NeoSoleil

4
3
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
4
3

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?