Claude CodeでSpec駆動開発 – AI駆動時代の計画術

はじめに

ども！龍ちゃんです。皆さん、Spec駆動開発やってますか？

AIが出てきて、開発スピードが爆上がりしたり、開発を丸投げできたり、いろんなことができるようになりましたよね。そんなAI駆動開発の文脈でよく語られるのがSpec駆動開発（SDD）です。

SDDツールも色々出てきてます。Kiro、Spec Kit、AI-DLC…。でも、新しいツールを導入するには学習コストがかかりますよね。プログラミング言語と同じで、「じゃあそのツールを勉強しなきゃ」となる。

「Claude Code契約したし、まずは小さく始めたい」

実は、Claude Codeの標準機能 /plan を使えば、Spec駆動開発の基本はできます。計画を立ててから実装する、という流れは標準でサポートされています。

ただ、使っていくうちに「もうちょっとこうしたい」が出てくるんですよね。今回は、標準の /plan を拡張したカスタムコマンド /feature-plan を紹介します。

関連記事

標準Plan Modeの進化

2026年1月頃、標準の /plan モードに待望の機能が追加されました。plansDirectory で保存先を変更できるようになったんです。

// .claude/settings.json
{
  "plansDirectory": "./docs/plans"
}

今まではホームディレクトリ配下（~/.claude/plans/）に保存されていたのが、任意の場所に保存できるようになりました。これで計画書をGit管理できます。

計画書が資産として保存できるようになった。 これは大きな進化です。

標準Plan Modeの限界：ドメイン知識の不足

ただ、保存できるようになっただけでは足りないんですよね。

良い計画を作るには、リポジトリのドメイン知識が必要です。まっさらなリポジトリならいいんですけど、機能追加の時って：

• プロジェクトの基盤情報
• 既に何が実装されているか
• どのディレクトリに何があるか
• プロジェクト固有の設計方針

これらを理解した上で方向性を決める必要があります。

標準の /plan を打つときって、プロンプトしか入力できないですよね。プロジェクトが大きくなると、毎回ドメイン知識を説明するのは面倒です。

カスタムコマンドなら、打った段階でリポジトリのドメイン知識を自動で読み込ませることができます。

/feature-plan で標準を補完する

僕が作った /feature-plan コマンドは、標準Plan Modeの足りない部分を補完します。

📎 原文は Gist で公開しています。以下では要点を抜粋して説明します。

出力の補完：plan.md + action-plan.md

標準のPlan Modeだと、特別な指示がなければ plan.md しか作りません。これだけだと手戻りが発生するなと感じていました。

そこで、2つのファイルを作らせることにしました：

plan.md には設計判断を書きます：

## 代替案の検討
| アプローチ | メリット | デメリット | 採用 |
|------------|----------|------------|------|
| 案A | シンプル | 拡張性が低い | × |
| 案B | 拡張しやすい | 複雑 | ○ |

## リスクと対策
| リスク | 影響度 | 対策 |
|--------|--------|------|
| 既存機能への影響 | 中 | 回帰テストを追加 |

action-plan.md には実装ステップと対象ファイルを書きます：

### ステップ 1: CLIエントリーポイントの作成
- **対象ファイル**: `src/cli.py`（新規）
- **完了基準**: `uv run cli --help` でヘルプが表示される

### ステップ 2: コア機能の実装
- **対象ファイル**: `src/core.py`（新規）
- **完了基準**: ユニットテストが通る

なぜ2つに分けるのか？

レビュー時に両方見ると、意図と違う実装を事前に検知できるんです。

action-plan.md に意図していないファイルが書いてあったら、「いや、そうじゃなくて…」と指示を修正できます。自分のプロンプトが悪かったのか、Claudeの解釈が違ったのか、この段階で発見できるのが大きいです。

あと、rate limitでセッションが中断したり、セッションが切れたりしても、ファイルに進捗が残っているので戻ってこれます。どこまでやったか把握しやすいんですよね。

入力の補完：ドメイン知識の注入

カスタムコマンドのもう一つの利点は、計画フェーズ特有の指示を埋め込めることです。

## CRITICAL CONSTRAINTS

1. **Read-only analysis first**: 既存コードを先に分析する
2. **Output directory**: 出力は `docs/features/$ARGUMENTS/` に保存
3. **Language**: ドキュメントは日本語で出力

僕は他にも /research コマンドで調査結果を docs/research/ に保存しています。これらの資産と統合しやすいのもカスタムコマンドの良いところです。

/feature-plan の実装例

実際のコマンドファイルはこんな構造です：

配置場所: .claude/commands/feature-plan.md

frontmatter

---
description: 実装計画とアクションプランを作成し、docs/features/ に保存。機能開発の計画フェーズをサポートします。
argument-hint: [feature-name]
allowed-tools: Read, Glob, Grep, Task, Write, Bash, WebSearch, WebFetch, TodoWrite, AskUserQuestion
---

• description: コマンドの説明（/help で表示される）
• argument-hint: 引数のヒント（$ARGUMENTS で受け取る）
• allowed-tools: 使用可能なツールを制限

CRITICAL CONSTRAINTS（重要な制約）

コマンド本文の冒頭で、守るべきルールを明示しています：

## CRITICAL CONSTRAINTS

You MUST follow these rules strictly:

1. **Read-only analysis first**: Do NOT modify any existing code until the plan is approved
2. **Output directory**: All documents MUST be saved to `docs/features/$ARGUMENTS/`
3. **Create subdirectory**: First create the directory before saving files
4. **Language**: Write all documents in Japanese

これにより「計画が承認されるまでコードを変更しない」という原則を徹底できます。

Workflow Phases（5フェーズ）

Phase 1: Initial Understanding - 要件の明確化、コードベース分析
Phase 2: Design              - 実装アプローチ、リスク評価
Phase 3: Review              - ユーザー要求との整合性確認
Phase 4: Create Documents    - plan.md、action-plan.md 作成
Phase 5: Summary             - ユーザーへのサマリー提示

各フェーズで何をすべきかを明記することで、Claudeの動作が安定します。

使い方

/feature-plan thumbnail-generator

これで docs/features/thumbnail-generator/ に plan.md と action-plan.md が作成されます。

📎 /feature-plan の全文は Gist で公開しています。 テンプレートの詳細やTodoWrite連携など、試したい方はそちらを参照してください。

Tips：英語記述で思考精度を向上させる

これ、めちゃくちゃ余談なんですけど。

/feature-plan コマンドは英語で記述しています。Claudeは英語の方が思考能力が高いと言われているので、CLAUDE.md で「思考は英語、出力は日本語」と指示しています。

あと、ドメイン知識の注入も、読み出すファイルやディレクトリを固定化しておけば、/feature-plan は使い回しできます。静的情報として管理しておくのがおすすめです。

まとめ

Spec駆動開発を始めるのに、新しいツールを導入する必要はありません。カスタムコマンド1つで小さく始められます。

• plan.md で意思決定を記録
• action-plan.md で変更先を確定し、進捗を管理
• カスタムコマンドでドメイン知識を自動注入

必要に応じてテンプレートを調整し、チームの運用に合わせて進化させていけばOKです。

ここまで読んでいただき、ありがとうございました！

参考リンク

公式ドキュメント

• Claude Code – Slash commands
• Claude Code – Common workflows
• Claude Code – Settings

Gist

• /feature-plan 原文