実践！仕様書駆動開発 ③実装編 — spec-implement が指揮し、spec-code / spec-review / spec-test が分業して PR まで自走する

はじめに

agent-skills 実践ガイドの第 3 回（最終回・実装編）です。第 1 回（セットアップ編）でプロジェクトの「動き方・書き方・レビュー基準」を spec-workflow-init / spec-rules-init で整え、第 2 回（仕様作成編）で spec-generator / spec-inspect / spec-to-issue を使い要件・設計・タスクの 3 点セットを GitHub Issue 化しました。

今回はその Issue を入力として、実装 → レビュー → テスト → PR まで自走させる 4 スキル（spec-implement / spec-code / spec-review / spec-test）を取り上げます。

実装編で扱う 4 スキルの役割分担

実装編の 4 スキルは「指揮者 1 + ワーカー 3」のチーム構成です。

spec-implement の SKILL.md には「🚨 BLOCKING — orchestrator only」と明記されており、ワーカーが未インストールでも自分でフォールバックしてはいけない設計になっています。

spec-implement: オーケストレーションの全体像

spec-implement は 8 フェーズで Issue → PR までを駆動します。

npx skills add anyoneanderson/agent-skills --skill spec-implement -g -y

仕様書から実装 --issue 42
# or
Implement from spec --issue 42 --spec .specs/auth-feature/
# or
Implement from spec --resume   # 中断したタスクから再開

8 フェーズの流れ

Phase 6 の Task Loop と役割タグ

tasks.md の各 Phase には役割タグが付きます。spec-implement はタグに応じて挙動を切り替えます。

• [code]: ワーカーに実装を委譲（spec-code を invoke）
• [orchestrator]: spec-implement 自身が直接実行（コマンド実行・結果確認のみ、ファイル変更はしない）
• -R suffix（例: Phase 2-R: Review Gate [orchestrator]）: 直前の [code] Phase の各タスクに対して spec-review + spec-test を実行する Review Gate

タグなしの Phase は後方互換のため [code] 扱いになります。

Review Gate での fix ループ

Review Gate Phase では、直前 [code] Phase の各タスクに対して以下が走ります。

spec-review → Critical あり → spec-code --feedback {review.md}
  → 再 spec-review → ... 最大 3 回まで
spec-test  → FAIL → spec-code --feedback {test.md}
  → 再 spec-test
review PASS AND test PASS → Review Gate タスクの checkbox を更新

3 回失敗した場合は AskUserQuestion でユーザーに判断を求める安全設計です。

Dispatch モード（実行戦略）

ワーカーを呼ぶ方法は環境に応じて 4 種類から自動選択されます。

優先順位: Codex sub-agents → Claude Code agent team → cmux dispatch → 単独実行。第 1 回の spec-workflow-init でロール定義（workflow-implementer.md / workflow-reviewer.md / workflow-tester.md）を生成しておくと、この dispatch が自動的にエンジン側に最適化されます。

spec-code: 単一タスクの自律実装

spec-code は 1 タスク分 の実装だけを担当するワーカーです。tasks.md のチェックボックス更新は しません（それは orchestrator の責務）。

npx skills add anyoneanderson/agent-skills --skill spec-code -g -y

/spec-code --issue 42 --task T-007 --spec .specs/auth-feature/

Phase A / Phase B の context 読込み

context 読込みには 2 モードあります。

Phase A（初回呼び出し、フル context）:

1. workflow ファイル探索 → 自分の役割を implementer と認識
2. gh issue view {N} で Issue 取得
3. --spec 配下の requirement.md / design.md / tasks.md を全部読む
4. coding-rules.md / CLAUDE.md / AGENTS.md を読む

Phase B（--feedback 再呼び出し、最小 context）:

1. feedback ファイル（review or test 結果）のみ
2. 対象タスクの description
3. 関連する design.md セクション
4. 前回実装で変更されたファイル

--feedback は fix の精度 とコスト効率の両面で効きます。レビュー結果を読んで Critical を最優先で直し、その後 Improvement を見るという順序が SKILL.md に明文化されています。

--feedback モードの自動判定

feedback ファイルの先頭にある type: ヘッダで動作を切り替えます。

• type: review: ## Findings セクションを読み、Critical を file:line で修正 → 次に Improvement
• type: test: ## Test Cases の失敗と ## Completion Criteria Coverage の未達成項目を見て、実装コードを修正してテストを通す

修正対象外のコードには手を加えない、という制約も組み込まれています。

コミット

完了したらコミットします。フォーマットは coding-rules.md / CLAUDE.md から読み込み、デフォルトは feat(scope): {task-id} — {brief description}。実装ファイルだけステージし、tasks.md はステージしません（orchestrator が後で更新）。

spec-review: rule × file マトリクスの構造化レビュー

spec-review は rule × file マトリクス という、漏れなく照合する設計のレビュースキルです。

npx skills add anyoneanderson/agent-skills --skill spec-review -g -y

/spec-review --task T-007 --base-commit abc1234 --spec .specs/auth-feature/
# or
/spec-review   # 引数なしで現在の staged diff をレビュー

Step 1: ルール収集

review_rules.md（第 1 回で生成）と coding-rules.md を読み、以下のような構造化リストに変換します。

rule_list: [
  { id: "RR-001", severity: "Critical", description: "No SQL injection", category: "security" },
  { id: "CR-MUST-001", severity: "MUST", description: "Use strict TypeScript", category: "typescript" },
  ...
]

ルールファイルが無ければ最小デフォルト（security / correctness / style）にフォールバックします。

Step 2: diff の取得

context に応じて diff の取り方を切り替えます。

Step 3: マトリクスレビュー（コア）

for each rule in rule_list:
  for each file in changed_files:
    if rule.category is relevant to this file type:
      check if any added/modified line violates this rule
      if violation: record { rule.id, file.path, line_number, description, severity }

カテゴリ × ファイル種別のマッチング:

• security → 全ファイル
• typescript → .ts / .tsx
• test → *.test.* / *.spec.*
• style → 全ソースファイル
• api → controller / route ファイル

Step 4: Design Consistency Check

--spec 指定時、design.md の対象セクションを読んで実装と比較します。指定インターフェイスが実装されているか、データモデルが一致しているか、アーキテクチャ判断が守られているか、を Improvement severity で記録します。

Step 5: レビューファイルの書き出し

.specs/{feature}/review-{task-id}.md に以下フォーマットで出力します。

# Review: T-007
type: review
 
## Meta
- Reviewer: spec-review
- Date: ...
- Iteration: 1
- Rules checked: 36 rules across 5 files
- Diff basis: git diff abc1234...HEAD
 
## Findings
 
### Critical
- [ ] **RR-001** `src/auth/service.ts:48` — SQL injection: 直接 string concat で query 生成
 
### Improvement
- [ ] **CR-SHOULD-002** `src/auth/service.ts:62` — return type を明示推奨
 
## Summary
- Critical: 1 | Improvement: 1 | Minor: 0
- Gate: FAIL

Gate 判定: Critical 1 件でも → FAIL / Improvement・Minor のみ → PASS（警告付き）/ 何もなし → PASS。

このファイルがそのまま spec-code --feedback の入力になります。

spec-test: 完了条件ベースのテスト生成・実行

spec-test は tasks.md の完了条件 を元にテストを設計・実行するスキルです。

npx skills add anyoneanderson/agent-skills --skill spec-test -g -y

/spec-test --task T-007 --spec .specs/auth-feature/

Step 1〜2: 完了条件抽出 + テストパターン検出

1. tasks.md から対象タスクの完了条件 / 対象ファイル / requirement ID を抽出
2. プロジェクト内をスキャンして既存のテスト規約を検出:
   • test ファイル: *.test.*, *.spec.*, __tests__/, test/, tests/
   • framework: Jest / Vitest / Mocha / pytest / Go test / Rust test
   • pattern: AAA（Arrange-Act-Assert）/ describe-it / fixtures
   • test command: package.json scripts / Makefile / CLAUDE.md から検出

既存テストが無ければ言語に応じたデフォルトを使います。

Step 3〜4: テストケース設計と作成

完了条件 + design から 3 種類のテストケースを設計します。

• Happy path: 各完了条件 → 少なくとも 1 つのテスト
• Edge cases: 空入力、境界値、エラー条件
• Negative tests: 不正入力、認可なし、データ欠落

検出した命名規約・配置場所・AAA パターンに従って書きます。

Step 5〜6: 実行 + 結果書き出し

検出したコマンドで実行（npm test / pytest / go test 等）。新規テストを先に走らせてから全スイートで回す方式。結果は .specs/{feature}/test-{task-id}.md に書き出されます。

# Test: T-007
type: test
 
## Meta
- Tester: spec-test
- Date: ...
- Command: npm test -- --coverage
- Framework: Vitest
 
## Results
- Tests: 8/9 passed
- Coverage: 87%
- Duration: 1.2s
 
## Test Cases
- [x] auth-service: ログイン成功時にトークンを返す
- [ ] auth-service: パスワードハッシュ照合失敗 — FAILED: expected 401 but got 500
 
## Completion Criteria Coverage
| Criterion | Test | Status |
|---|---|---|
| ログイン成功でセッション作成 | login-success | PASS |
| 不正パスワードで 401 | login-fail | FAIL |
 
## Gate: FAIL

Gate: 全 pass → PASS / 1 つでも fail → FAIL。失敗があれば spec-code --feedback で fix に進みます。spec-test 自身は実装コードを直しません（責務分離）。

連載第 1〜2 回との接続

第 1〜2 回で作ったドキュメントが、第 3 回でどう活きるかをまとめます。

つまり連載 3 回を通すと、1 つの自然言語指示から PR まで到達する パイプラインが完成します。

spec-workflow-init / spec-rules-init  ← セットアップ（第1回）
  ↓ docs/issue-to-pr-workflow.md / docs/coding-rules.md / docs/review_rules.md
spec-generator → spec-inspect → spec-to-issue  ← 仕様作成（第2回）
  ↓ .specs/{feature}/ + GitHub Issue #N
spec-implement(--issue N)  ← 実装（第3回）
  ├─ spec-code
  ├─ spec-review
  └─ spec-test
  ↓
PR

よくある質問

Q. spec-implement は本当に自分でコードを書かないのですか？

A. 書きません。SKILL.md には「🚨 BLOCKING — orchestrator only」と明記されており、ワーカー（spec-code 等）が未インストールでも自分でフォールバックしないように設計されています。これにより「指揮者がコードを書いて整合性が崩れる」事故を防いでいます。

Q. --feedback で何回までリトライしますか？

A. Review Gate での fix ループは 最大 3 回 です。3 回試して PASS にならない場合は AskUserQuestion でユーザーに判断を求めます。test 失敗も同様で、fix → 再 test の構造です。

Q. [code] / [orchestrator] タグが付いていない既存仕様書でも動きますか？

A. 動きます。タグなし Phase は 後方互換で [code] 扱い になります。これは spec v3 以前の仕様書との互換性のための設計です。

Q. Codex / Claude Code / cmux のどれを使うのが推奨ですか？

A. 環境次第ですが、第 1 回でロール定義（.codex/agents/workflow-*.toml または .claude/agents/workflow-*.md）を生成しておくと、spec-implement が自動的にランタイムネイティブ（Codex sub-agents / Claude Code agent team）を優先します。cmux は 明示選択時のみ 使われる位置づけです。

Q. PR 作成時に test が落ちている場合は？

A. 作りません。Phase 7 の最終品質ゲート（test / lint / typecheck）を満たすまで PR は作成されません。落ちていれば spec-code --feedback で fix してリトライ、それでも通らなければ AskUserQuestion で判断を求めます。

Q. --resume で再開するときは？

A. tasks.md の未チェック先頭タスクから再開します。Phase 6 の Task Loop は冪等に設計されているので、中断してから spec-implement --resume で続行できます。

まとめ

spec-implement / spec-code / spec-review / spec-test は、「指揮 + 実装 + レビュー + テスト」を 4 スキルに分業 したオーケストレーション設計です。指揮者がコードを書かないこと、レビュアー / テスターが実装を直さないこと、ワーカーは --feedback でフィックスループに参加すること——この役割分離が「AI が責任を持って自走する」ための核です。

連載 3 回で扱った 9 スキルが揃うと、「ECサイトの仕様を全部作って」「Issue にして」「実装を開始」 の 3 ステップで PR まで到達できる状態になります。ZenChAIne でも、本連載のドキュメント群を実プロジェクトに適用しながら運用ノウハウを蓄積しています。

これで「実践！仕様書駆動開発」連載は完結です。第 1 回・第 2 回と合わせて、agent-skills の spec 系 9 スキルを「何のために、どう使うか」のレベルで一通りカバーしました。読んで触って、自分のプロジェクトに合わせてルールやエージェント定義を育てていく、というのが Spec 駆動開発の本来の楽しさです。

参考ソース

• agent-skills - GitHub
• spec-implement SKILL.md
• spec-code SKILL.md
• spec-review SKILL.md
• spec-test SKILL.md
• 実践！仕様書駆動開発 ①セットアップ編 - ZenChAIne
• 実践！仕様書駆動開発 ②仕様作成編 - ZenChAIne
• Agent Skills とは何か - ZenChAIne
• agent-skills オープンソース公開 - ZenChAIne
• skills.sh