🎉
実践『Claude Code 入門』の SPEC 駆動開発を、既存プロジェクトで使うなら

2026/01/01に公開
 『実践Claude Code 入門』に出てきた SPEC 駆動開発について『実践 Claude Code 入門』に出てきた SPEC 駆動開発が実践的で学びになりました。
https://www.amazon.co.jp/dp/4297153548
本の中では、主に 0→1 でプロダクトを作る場面を想定した場合のフローがかいてありました。
すでに動いている運用中のプロジェクトの場合、

プロダクト全体が巨大でどこかカオスになっているケースも少なくありません。
プロジェクトによっては、仕様書や大枠の機能設計、コーディング規約自体はすでにまとまっていることもあります。
そうした前提の中での開発は主に、機能の実装や改修とレビューが中心という場合が多いと思います。
そのときに Claude Code をどう使うか、

どんな Command・Skill・Agent の構成にすると現実的か、

そのあたりを考えながら、本に書かれていた内容を参考にして整理しました。
参考になれば幸いです。

 実装とレビューに特化した .claude/ 設計ガイドゼロから .claude/ ディレクトリを設計し、実装とレビューを効率化する方法を解説します。

 📋 目次最小構成の設計思想
ステップ1: ディレクトリ構造を作る
ステップ2: 実装用のCommand設計
ステップ3: 実装用のSkill設計
ステップ4: レビュー用のAgent設計
ステップ5: 段階的な拡張

 最小構成の設計思想
 実装とレビューに必要な最小要素.claude/
├── commands/
│   └── add-feature.md ← 1つだけ（新機能開発）
├── skills/
│   └── steering/ ← 1つだけ（進捗管理）
│       └── SKILL.md
└── agents/
    └── code-reviewer.md ← 1つだけ（コードレビュー）
この3ファイルで大体のユースケースをカバーできそう。

 設計原則YAGNI（You Aren't Gonna Need It）: 必要になってから追加
単一責任: 1つのファイルは1つの目的
段階的改善: 最小構成から始めて、使いながら拡張

 ステップ1: ディレクトリ構造を作る
 1-1. 最小構成を作成mkdir -p .claude/commands
mkdir -p .claude/skills/steering
mkdir -p .claude/agents

 1-2. 完成形（最小構成）.claude/
├── commands/
│   └── add-feature.md ← 新機能開発の自動化
├── skills/
│   └── steering/
│       ├── SKILL.md ← 進捗管理スキル
│       └── templates/
│           ├── requirements.md ← 要件テンプレート
│           ├── design.md ← 設計テンプレート
│           └── tasklist.md ← タスクリストテンプレート
└── agents/
    └── code-reviewer.md ← コードレビュー自動化
所要時間: 5分

 ステップ2: 実装用のCommand設計
 2-1. add-feature.md の役割目的: 新機能開発を完全自動化
ワークフロー:
1. ユーザー: /add-feature ユーザー認証
2. Command: ステアリングファイル作成（.steering/20251230-ユーザー認証/）
3. Skill: requirements.md, design.md, tasklist.md 生成
4. 実装: tasklist.md に従って自動実装
5. Agent: コード品質検証
6. テスト: npm test/lint/typecheck
7. 振り返り: tasklist.md に記録

 2-2. add-feature.md の実装---
description: 新機能を既存パターンに従って、完全に無停止で実装する
---

# 新機能の追加 (完全自動実行モード)

**引数:** 機能名 (例: `/add-feature ユーザー認証`)

---

## ステップ1: 準備とコンテキスト設定

1. 現在のタスクコンテキストを確立:
   - 機能名: `[引数で与えられた機能名]`
   - 日付: `[現在の日付をYYYYMMDD形式で取得]`
   - ステアリングディレクトリパス: `.steering/[日付]-[機能名]/`

2. ステアリングディレクトリを作成

3. 以下の3つの空ファイルを作成:
   - `[ステアリングディレクトリパス]/requirements.md`
   - `[ステアリングディレクトリパス]/design.md`
   - `[ステアリングディレクトリパス]/tasklist.md`

## ステップ2: プロジェクト理解

1. `CLAUDE.md`を読み、プロジェクトの全体像を把握
2. `docs/`ディレクトリ内のドキュメントを確認

## ステップ3: 既存パターンの調査

1. Grepツールで関連するキーワードを検索:

   Grep('[機能に関連するキーワード]', 'src/')

2. 既存の実装パターン、命名規則を特定

## ステップ4: 計画フェーズ

1. `Skill('steering')`を実行し、ステアリングファイルの内容を生成
2. 完了後、ただちにステップ5に進む

## ステップ5: 実装ループ

**このステップは、`tasklist.md`の全タスクが完了するまで繰り返す**

1. タスクリストの読み込み:
   - `[ステアリングディレクトリパス]/tasklist.md`を読み込む

2. 進捗の確認:
   - 未完了タスク (`[ ]`) が存在するか確認
   - 存在しない場合: ステップ6へ進む
   - 存在する場合: 次の処理に進む

3. タスクの実行:
   - 先頭の未完了タスクを1つ実行
   - `Skill('steering')`を使用して進捗管理

4. タスクリストの更新:
   - 完了したタスクを `[x]` に変更

5. ループ継続:
   - ステップ5の先頭に戻る

## ステップ6: 品質検証

1. `Task`ツールで`code-reviewer`エージェントを起動:

   Task(
     subagent_type='code-reviewer',
     prompt='今回実装した [機能名] のコード品質を検証してください'
   )

## ステップ7: 自動テスト

1. 以下のコマンドを実行:

   npm test  
   npm run lint  
   npm run typecheck  

2. エラーがあれば修正して再実行

## ステップ8: 振り返り

1. `Skill('steering')`を振り返りモードで実行
2. `tasklist.md`に以下を記録:
   - 実装完了日
   - 計画と実績の差分
   - 学んだこと
   - 次回への改善提案

## 完了条件

- tasklist.mdの全タスクが完了
- code-reviewerの検証をパス
- 全テストが成功
- 振り返りが記録されている
ポイント:
✅ 8ステップで構造化
✅ 各ステップで何をするか明確
✅ 完全自動実行（ユーザーの介入不要）

 ステップ3: 実装用のSkill設計
 3-1. steering/SKILL.md の役割目的:
ステアリングファイル（requirements.md, design.md, tasklist.md）の作成
tasklist.mdに基づいた進捗管理
3つのモード:
計画モード: requirements.md, design.md, tasklist.md を生成
実装モード: tasklist.mdに従って実装し、進捗を記録
振り返りモード: tasklist.mdに申し送り事項を記録

 3-2. steering/SKILL.md の実装---
name: steering
description: 作業指示毎の作業計画、タスクリストをドキュメントに記録
allowed-tools: Read, Write, Edit
---

# Steering スキル

## スキルの目的

- ステアリングファイルの作成支援
- tasklist.mdに基づいた段階的な実装管理
- 進捗の自動追跡
- 実装完了後の振り返り記録

## 使用タイミング

1. **作業計画時**: ステアリングファイルを作成
2. **実装時**: tasklist.mdに従って実装
3. **検証時**: 振り返りを記録

---

## モード1: ステアリングファイル作成

### 手順

1. **永続ドキュメントの確認**
   - `CLAUDE.md`を読む
   - `docs/`内のドキュメントを読む

2. **テンプレートからファイル作成**
   - `./templates/requirements.md` を参照
   - `./templates/design.md` を参照
   - `./templates/tasklist.md` を参照

3. **具体的な内容に置き換える**
   - プレースホルダーを実際の内容に置き換え
   - タスクを具体化

---

## モード2: 実装

### 重要な原則

**MUST（必須）**:
- tasklist.mdを常に開いた状態で実装
- タスク完了時に必ず`[ ]`→`[x]`に更新
- **全タスクが完了するまで作業を継続**

**NEVER（禁止）**:
- tasklist.mdを見ずに実装を進める
- 未完了タスクを残したまま作業を終了

### タスク完全完了の原則

1. **全タスクが完了するまで継続**
   - 全てのタスクが`[x]`になるまで実装
   - 「時間がかかる」などの理由でスキップしない

2. **タスクが大きすぎる場合**
   - 小さなサブタスクに分割
   - 分割したサブタスクをtasklist.mdに追加

---

## モード3: 振り返り

### 記録する内容

tasklist.mdの末尾に以下を追加:

## 実装後の振り返り

### 実装完了日
[YYYY-MM-DD]

### 計画と実績の差分

**計画と異なった点**:
- [実装中に変更した内容]

**新たに必要になったタスク**:
- [追加で必要になったタスク]

### 学んだこと

**技術的な学び**:
- [実装を通じて学んだ技術的な知見]

**プロセス上の改善点**:
- [次回に活かせる改善点]

### 次回への改善提案
- [次回の実装で改善できる点]
ポイント:
✅ 3つのモードで責務を明確化
✅ タスク完全完了の原則を強調
✅ 振り返りのテンプレート提供

 3-3. テンプレートファイルの作成
 templates/requirements.md# [機能名] の要件定義

## 概要
[この機能の目的と背景を簡潔に記述]

## 機能要件

### 1. [要件1]
- [詳細な説明]
- [受け入れ条件]

### 2. [要件2]
- [詳細な説明]
- [受け入れ条件]

## 非機能要件

- **パフォーマンス**: [具体的な数値目標]
- **セキュリティ**: [セキュリティ要件]
- **可用性**: [可用性要件]

## 受け入れ基準
- [ ] [基準1]
- [ ] [基準2]
- [ ] [基準3]

 templates/design.md# [機能名] の設計

## アーキテクチャ変更

### 新規追加ファイル
- `src/[パス]/[ファイル名].ts` - [役割]

### 修正ファイル
- `src/[パス]/[ファイル名].ts` - [変更内容]

## データモデル

```ts
interface [InterfaceName] {
  id: string;
  name: string;
  // ...
}

 API設計（該当する場合）
 エンドポイントPOST /api/[endpoint]
Request: { ... }
Response: { ... }

 エラーハンドリング
 テスト方針ユニットテスト: [テスト対象]
統合テスト: [テスト対象]

#### templates/tasklist.md

```md
# タスクリスト

## フェーズ1: 型定義
- [ ] `src/types/[Type].ts` を作成
- [ ] インターフェース定義

## フェーズ2: ビジネスロジック
- [ ] `src/services/[Service].ts` を作成
- [ ] メソッド実装

## フェーズ3: API/UI層
- [ ] エンドポイント作成 / コンポーネント作成
- [ ] バリデーション追加

## フェーズ4: テスト
- [ ] ユニットテスト作成
- [ ] 統合テスト作成

## フェーズ5: ドキュメント
- [ ] README更新
- [ ] API仕様書更新（該当する場合）

---

## 実装後の振り返り
（実装完了後に記録）

 ステップ4: レビュー用のAgent設計
 4-1. code-reviewer.md の役割目的: プロジェクト固有の規約でコードレビューを自動化
レビュー観点:
コーディング規約準拠
テストカバレッジ
エラーハンドリング
パフォーマンス
セキュリティ

 4-2. code-reviewer.md の実装---
name: code-reviewer
description: プロジェクト固有の規約でコード品質をレビュー
model: sonnet
---

# コードレビューエージェント

あなたはコードの品質を評価し、具体的な改善提案を行う専門エージェントです。

---

## レビュー観点

### 1. コーディング規約準拠

**チェック項目**:
- [ ] `CLAUDE.md`に記載された規約に従っているか
- [ ] `docs/development-guidelines.md`の命名規則に従っているか
- [ ] 既存コードと一貫したスタイルか

**評価基準**:
- ✅ 準拠: 全ての規約に従っている
- ⚠️ 改善推奨: 一部規約から逸脱
- ❌ 不準拠: 重大な規約違反

---

### 2. テストカバレッジ

**チェック項目**:
- [ ] 新規コードにテストがあるか
- [ ] エッジケースがテストされているか
- [ ] モックが適切に使われているか

**評価基準**:
- ✅ 十分: 主要なパスとエッジケースをカバー
- ⚠️ 不十分: 一部のケースが未テスト
- ❌ テストなし: テストが存在しない

---

### 3. エラーハンドリング

**チェック項目**:
- [ ] try-catchが適切に使われているか
- [ ] エラーメッセージが分かりやすいか
- [ ] カスタムエラークラスを使っているか

**評価基準**:
- ✅ 適切: エラーが適切に処理されている
- ⚠️ 改善推奨: 一部のエラーケースが未処理
- ❌ 不十分: エラー処理がない

---

### 4. パフォーマンス

**チェック項目**:
- [ ] N+1クエリがないか（DB操作）
- [ ] 不要な再レンダリングがないか（React）
- [ ] メモリリークの可能性がないか

**評価基準**:
- ✅ 問題なし: パフォーマンス問題が見当たらない
- ⚠️ 改善可能: 最適化の余地がある
- ❌ 問題あり: 明らかなパフォーマンス問題

---

### 5. セキュリティ

**チェック項目**:
- [ ] SQLインジェクション対策があるか
- [ ] XSS対策があるか
- [ ] 機密情報がログに出力されていないか
- [ ] 認証・認可が適切か

**評価基準**:
- ✅ 安全: セキュリティ問題が見当たらない
- ⚠️ 要確認: 潜在的なリスクがある
- ❌ 脆弱性あり: 明らかな脆弱性がある

---

## レビュープロセス

### ステップ1: コードの読み込み
指定されたファイルまたはPRのコードを読み込む

### ステップ2: プロジェクト規約の確認
- `CLAUDE.md`を読む
- `docs/development-guidelines.md`を読む
- 既存の類似実装をGrepで検索

### ステップ3: 5つの観点で評価
各観点について、✅/⚠️/❌で評価

### ステップ4: レビューレポート作成
以下の形式で出力:

## 出力フォーマット

## コードレビュー結果: [ファイル名またはPR番号]

### 総合評価

| 観点 | 評価 | スコア |
|-----|------|--------|
| コーディング規約 | [✅/⚠️/❌] | [1-5] |
| テストカバレッジ | [✅/⚠️/❌] | [1-5] |
| エラーハンドリング | [✅/⚠️/❌] | [1-5] |
| パフォーマンス | [✅/⚠️/❌] | [1-5] |
| セキュリティ | [✅/⚠️/❌] | [1-5] |

**総合スコア**: [平均]/5

---

### 良い点
- [具体的な良い点1]
  - **ファイル**: `src/[ファイル名].ts:行番号`
  - **理由**: [なぜ良いのか]

- [具体的な良い点2]
  - **ファイル**: `src/[ファイル名].ts:行番号`
  - **理由**: [なぜ良いのか]

---

### 改善が必要な点

#### [🚨 Critical] 即座に修正が必要
**問題1**: [問題の説明]
- **ファイル**: `src/[ファイル名].ts:行番号`
- **問題のコード**:

- **理由**: [なぜ問題か]
    
- **修正方法**:
    
    ```ts
    // 修正後のコード
    ```
    

#### [⚠️ Warning] 改善推奨

**問題2**: [問題の説明]

- **ファイル**: `src/[ファイル名].ts:行番号`
    
- **理由**: [なぜ改善すべきか]
    
- **改善案**: [具体的な改善方法]
    

#### [💡 Suggestion] さらなる改善

**提案1**: [提案内容]

- **メリット**: [この改善のメリット]
    
- **実装方法**: [どう改善するか]
    

---

### 次のステップ

1. [最優先で対応すべきこと]
    
2. [次に対応すべきこと]
    
3. [時間があれば対応すること]
    

---

## レビューの姿勢

- **建設的**: 批判ではなく、改善のための提案
    
- **具体的**: 「どこが」「なぜ」「どう改善するか」を明示
    
- **バランス**: 悪い点だけでなく、良い点も必ず指摘
    
- **実用的**: 実際に実行可能な改善案を提示
    


 ステップ5: 段階的な拡張
 5-1. 最小構成で運用開始（〜1週間）.claude/
├── commands/
│   └── add-feature.md
├── skills/
│   └── steering/
└── agents/
    └── code-reviewer.md
この3ファイルで開始し、使いながら課題を発見

 5-2. よく使うパターンをSkill化する例: API エンドポイント追加が頻繁に発生
# .claude/skills/api-endpoint/SKILL.md

---
name: api-endpoint
description: REST API エンドポイント追加の標準手順
---

## テンプレート

### エンドポイント設計
- HTTPメソッド: [GET/POST/PUT/DELETE]
- パス: `/api/[resource]`
- 認証: [必要/不要]

### 実装チェックリスト
- [ ] リクエストバリデーション（Zod）
- [ ] エラーハンドリング
- [ ] レスポンス型定義
- [ ] ユニットテスト
- [ ] 統合テスト
- [ ] OpenAPI仕様書更新
使い方:
> Skill('api-endpoint') を使って、/api/users/:id のエンドポイントを追加

 5-3. 専門的なレビューをAgent化する例: セキュリティレビューが必要
# .claude/agents/security-reviewer.md

---
name: security-reviewer
description: セキュリティ脆弱性を検出
model: sonnet
---

## チェック項目

### OWASP Top 10

1. **Injection（インジェクション）**
- [ ] SQLインジェクション対策
- [ ] コマンドインジェクション対策

2. **Broken Authentication（認証の不備）**
- [ ] パスワードのハッシュ化（bcrypt推奨）
- [ ] セッション管理

3. **Sensitive Data Exposure（機密データの露出）**
- [ ] 環境変数での機密情報管理
- [ ] ログに機密情報が出力されていないか

（続く...）

## 出力フォーマット

### [🚨 Critical] CVSSスコア 7.0以上
- **脆弱性**: [脆弱性名]
- **CVSSスコア**: [数値]
- **影響**: [どのような影響があるか]
- **修正方法**: [具体的な修正コード]
使い方:
> セキュリティレビューをお願いします

 5-4. プロジェクト固有のCommandを追加（必要に応じて）例: デプロイ前チェックが頻繁
# .claude/commands/pre-deploy-check.md

---
description: デプロイ前の品質チェックを自動実行
---

# デプロイ前チェック

## ステップ1: テスト実行
npm test
npm run lint
npm run typecheck

## ステップ2: ビルド確認
npm run build

## ステップ3: セキュリティスキャン
npm audit

## ステップ4: パフォーマンステスト
（必要に応じて）

## ステップ5: レポート作成
チェック結果をまとめたレポートを出力
使い方:
> /pre-deploy-check

 まとめ: 設計のポイント
 最小構成から開始1. commands/add-feature.md ← 実装の自動化
2. skills/steering/ ← 進捗管理
3. agents/code-reviewer.md ← レビューの自動化
この3つでほとんどのユースケースをカバー

 段階的に拡張Week 1: 最小構成で運用開始
Week 2-4: よく使うパターンをSkill化
Month 2-3: 専門的なレビューをAgent化
Month 4+: プロジェクト固有のCommand追加

 設計原則YAGNI: 必要になってから追加
DRY: 繰り返しパターンをSkill/Agent化
単一責任: 1ファイル1目的
段階的改善: 小さく始めて、使いながら拡張

 実装例: ファイル構成
 .claude/ 構成例.claude/
├── commands/
│   ├── add-feature.md ← 新機能開発
│   └── pre-deploy-check.md ← デプロイ前チェック（拡張）
│
├── skills/
│   ├── steering/ ← 進捗管理（必須）
│   │   ├── SKILL.md
│   │   └── templates/
│   │       ├── requirements.md
│   │       ├── design.md
│   │       └── tasklist.md
│   │
│   └── api-endpoint/ ← APIエンドポイント追加（拡張）
│       ├── SKILL.md
│       └── template.md
│
└── agents/
    ├── code-reviewer.md ← コードレビュー（必須）
    └── security-reviewer.md ← セキュリティレビュー（拡張）

 感想最初から全部盛り込んでいこうとすると、もりもりになってしまって、今までやっていた運用と全く違うものになりそうだなと思いました。
他の開発者との認識ずれが生まれたり、既存プロジェクトの開発フローとのずれでうまくいかない部分が大きくなる気もしました。
なのでまずはスキルとエージェントだけ追加して、実装用とレビュー用のものを入れて活用していく。
テンプレートをもとにして、ステアリングフォルダに タスクリスト・要件・設計 のファイルを出力するのを癖付けていく。
そこから必要に応じて、たとえば API エンドポイント作成のスキルを作ったり、よく使う手順をスキル化したり、レビュー観点をエージェント化していくと、だんだん幅も広がっていって、実務の中でも取り入れやすくなる気がしました。
『実践Claude Code 入門』に出てきた SPEC 駆動開発について

実装とレビューに特化した .claude/ 設計ガイド

📋 目次

最小構成の設計思想

実装とレビューに必要な最小要素

設計原則

ステップ1: ディレクトリ構造を作る

1-1. 最小構成を作成

1-2. 完成形（最小構成）

ステップ2: 実装用のCommand設計

2-1. add-feature.md の役割

2-2. add-feature.md の実装

ステップ3: 実装用のSkill設計

3-1. steering/SKILL.md の役割

3-2. steering/SKILL.md の実装

3-3. テンプレートファイルの作成

templates/requirements.md

templates/design.md

API設計（該当する場合）

エンドポイント

エラーハンドリング

テスト方針

ステップ4: レビュー用のAgent設計

4-1. code-reviewer.md の役割

4-2. code-reviewer.md の実装

ステップ5: 段階的な拡張

5-1. 最小構成で運用開始（〜1週間）

5-2. よく使うパターンをSkill化する

5-3. 専門的なレビューをAgent化する

5-4. プロジェクト固有のCommandを追加（必要に応じて）

まとめ: 設計のポイント

最小構成から開始

段階的に拡張

設計原則

実装例: ファイル構成

.claude/ 構成例

感想

Discussion
