概要

要件→設計→実装→テストの各フェーズでClaude Codeを活用
探索的な開発に特化したIssue Templates
段階的な成長を前提としたai_docs/の構築戦略
プロトタイプから本番まで一貫したワークフロー

🚀 スクラッチ開発用テンプレート: claude-code-starter-kit

💡 保守・移行向けガイド: Claude CodeとGitHub Issuesで効率的に開発する方法も参照してください

目次

はじめに
スクラッチ開発でのClaude Codeの強み
開発フェーズ別の活用法
スクラッチ開発専用Issue Templates
ai_docs/の初期構築戦略
実践例: Webアプリケーションを作る
段階的な開発プロセス
よくある落とし穴と対策
まとめ

はじめに

本記事は、ゼロから新しいプロジェクトを開発する際に、Claude Codeを最大限活用する方法を解説します。

対象読者

新規プロジェクトを立ち上げる方
プロトタイプを素早く作りたい方
アイデアを形にしたいが、どこから始めればよいか迷っている方
Claude Codeをより創造的な作業に使いたい方

保守・移行との違い

観点	保守・移行	スクラッチ開発
既存コード	あり(制約)	なし(自由)
スコープ	明確	探索的
リスク	既存機能を壊す	設計判断のミス
重点	安全性・互換性	創造性・柔軟性
Issue数	少〜中	多(段階的)

スクラッチ開発でのClaude Codeの強み

1. アイデアの具現化が高速

「こんな機能が欲しい」という漠然としたアイデアから、動くプロトタイプまで数時間で到達できます。

## 🎯 やりたいこと
ユーザーがMarkdownで記事を書いて、リアルタイムプレビューできるエディタ

## 📋 Claude Codeへの指示
1. React + TypeScript でプロジェクトを作成
2. Monaco Editorを使った編集画面
3. マークダウンをHTMLに変換してプレビュー
4. 動作するデモを作成

不明点があれば提案してください。

2. 設計の壁打ち相手になる

アーキテクチャや技術選定で迷った時、Claude Codeに選択肢を整理させることができます。

3. ボイラープレートコードの自動生成

プロジェクト初期の定型的なセットアップ作業を任せられます:

プロジェクト構造の作成
設定ファイルの生成
基本的なCRUD実装
テストのテンプレート

4. 段階的な成長をサポート

最初は最小限で始め、必要に応じて機能を追加していくアプローチが取りやすい。

開発フェーズ別の活用法

フェーズ1: 要件定義・アイデア整理

目的: 作りたいものを明確にする

Claude Codeの使い方

## 🔍 調査依頼
類似サービス・ライブラリを調査して、以下をまとめてください:
1. 主要な機能一覧
2. 技術スタック
3. 実装の難易度
4. 推奨アプローチ

結果を `ai_docs/research/initial-research.md` に記録

成果物

競合調査レポート
機能要件リスト
技術的な実現可能性の評価

フェーズ2: 設計・技術選定

目的: アーキテクチャと技術スタックを決定

Claude Codeの使い方

## 🏗️ 設計検討
以下の要件でアーキテクチャ設計案を3つ提示してください:

**要件**:
- リアルタイム通信が必要
- 同時接続100人程度
- モバイル対応必須

**各案について**:
- 技術スタック
- メリット・デメリット
- 実装コスト
- スケーラビリティ

結果を `ai_docs/design/architecture-options.md` に記録

成果物

アーキテクチャ設計書
技術選定の根拠
データモデル設計

フェーズ3: プロトタイピング

目的: アイデアを素早く検証

Claude Codeの使い方

## 🧪 プロトタイプ作成
最小限の動作するプロトタイプを作成してください:

**実装する機能**:
- ユーザー登録・ログイン(簡易版)
- データの作成・表示
- 基本的なUI

**実装しない機能**:
- 高度なバリデーション
- エラーハンドリング
- パフォーマンス最適化

まずは動くものを優先してください。

ポイント

完璧を目指さない: 60%の完成度で十分
視覚的に確認: UIがあると判断しやすい
学びを記録: ai_docs/prototypes/ に学んだことを記録

フェーズ4: 本実装

目的: プロダクション品質のコードを書く

Claude Codeの使い方

## 🚀 本実装
プロトタイプを元に、本番環境向けの実装を行ってください:

**品質要件**:
- エラーハンドリング完備
- ユニットテスト カバレッジ80%以上
- セキュリティ対策(XSS, CSRF, SQLインジェクション)
- パフォーマンス最適化

**参照ドキュメント**:
- `ai_docs/coding_standards.md`
- `ai_docs/security_guidelines.md`

段階的に実装し、各機能ごとにPRを作成してください。

ポイント

プロトタイプとは別ブランチ: prototype/ と feature/ を分ける
レビュー重視: 人間が必ず確認
ドキュメント整備: 実装しながら ai_docs/ を充実させる

フェーズ5: テスト・デバッグ

目的: 品質を保証する

Claude Codeの使い方

## 🧪 テスト作成
以下のコンポーネントに対して包括的なテストを作成してください:

**対象**: `src/services/UserService.ts`

**テストケース**:
- 正常系: 各メソッドの基本動作
- 異常系: エラーハンドリング
- 境界値: 空文字、null、undefined
- エッジケース: 同時実行、タイムアウト

テストは `tests/services/UserService.test.ts` に作成

スクラッチ開発専用Issue Templates

保守・移行とは異なる、スクラッチ開発に特化したテンプレートを紹介します。

Template 1: 設計検討用

.github/ISSUE_TEMPLATE/design_discussion.md:

---
name: Design Discussion
about: アーキテクチャ・技術選定の検討
title: '[DESIGN] 検討事項'
labels: design, claude-code
---

## 🏗️ 検討内容


## 📋 背景・制約
**機能要件**:
- 

**非機能要件**:
- パフォーマンス: 
- スケーラビリティ: 
- セキュリティ: 

**制約条件**:
- 予算: 
- 期限: 
- チームのスキルセット: 

## 📑 出力契約(Claude必読)
- 複数の選択肢を提示(最低3案)
- 各案のメリット・デメリットを明記
- 推奨案と理由を明確に
- 実装コストの見積もりを含める

## 📋 Claude Code用タスク定義

1. 要件を分析し、技術的な選択肢を調査
2. 各選択肢について以下を評価:
   - 技術スタック
   - 学習コスト
   - 開発速度
   - 保守性
   - コスト
3. 比較表を作成
4. 推奨案を提示
5. `ai_docs/design/[issue-number]-options.md` にドキュメント作成

## ✅ 完了条件
- [ ] 3つ以上の選択肢を提示
- [ ] 比較表作成完了
- [ ] 推奨案が明確
- [ ] 設計ドキュメント作成完了

Template 2: プロトタイプ作成用

.github/ISSUE_TEMPLATE/prototype.md:

---
name: Prototype
about: 素早くアイデアを検証するプロトタイプ作成
title: '[PROTOTYPE] 機能名'
labels: prototype, claude-code
---

## 🧪 検証したいこと


## 🎯 プロトタイプの目的
- [ ] 技術的な実現可能性の確認
- [ ] UIの使い勝手の確認
- [ ] パフォーマンスの概算確認
- [ ] その他: 

## 📂 スコープ
**実装する機能**:
- 

**実装しない機能(後回し)**:
- エラーハンドリング
- 詳細なバリデーション
- パフォーマンス最適化
- セキュリティ対策
- その他: 

## 📑 出力契約(Claude必読)
- 動作するデモを最優先
- コードの品質は問わない(プロトタイプのため)
- 学んだことを必ず記録
- 本実装への移行パスを提案

## 🛡️ 安全弁
- プロトタイプ専用ブランチ `prototype/[issue-number]` で作業
- 本番環境には絶対にマージしない
- プロトタイプであることをREADMEに明記

## 📋 Claude Code用タスク定義

### 環境準備
1. ブランチ `prototype/[issue-number]-[feature-name]` を作成
2. プロトタイプ用ディレクトリ `prototypes/[issue-number]/` を作成

### 実装
3. 最小限の動作するコードを実装
4. 簡単なREADME(実行方法)を作成
5. スクリーンショットまたはデモ動画を記録

### 評価・記録
6. 学んだことを `ai_docs/prototypes/[issue-number]-learnings.md` に記録:
   - うまくいったこと
   - うまくいかなかったこと
   - 本実装への推奨事項
7. このIssueに結果を報告

## ⏱️ タイムボックス
このプロトタイプに使える時間: **最大4時間**
それ以上かかる場合は、スコープを削減するか中断して報告

## ✅ 完了条件
- [ ] 動作するデモが完成
- [ ] 検証したいことが確認できた
- [ ] 学びを記録済み
- [ ] 本実装への推奨事項を提示

Template 3: 新機能実装用

.github/ISSUE_TEMPLATE/feature_implementation.md:

---
name: Feature Implementation
about: 本番品質の新機能実装
title: '[FEATURE] 機能名'
labels: feature, claude-code
---

## 🎯 機能概要


## 📋 詳細仕様
**入力**:
- 

**処理**:
- 

**出力**:
- 

**エッジケース**:
- 

## 📑 出力契約(Claude必読)
- プロダクション品質のコード
- 包括的なテストを含む
- エラーハンドリング完備
- ドキュメント整備

## 📂 スコープ境界
**許可パス**:
- `src/features/[feature-name]/`
- `tests/features/[feature-name]/`

**禁止パス**:
- 既存の他の機能
- 共通モジュール(別途相談)

## 🛡️ 安全弁
- **Draft PR**必須
- CI全てグリーン
- コードレビュー必須

## 📋 Claude Code用タスク定義

### 設計
1. `ai_docs/design/[feature-name].md` に詳細設計を記述:
   - データフロー
   - API設計
   - エラーハンドリング戦略
2. 設計レビュー待機(このIssueで承認を受ける)

### 実装
3. ブランチ `feature/[issue-number]-[feature-name]` で作業
4. 以下の順序で実装:
   - データモデル・型定義
   - コアロジック
   - API/UI層
   - エラーハンドリング
5. 各段階でコミット(コミット規約に従う)

### テスト
6. ユニットテスト作成(カバレッジ80%以上)
7. 統合テスト作成
8. エッジケースのテスト

### ドキュメント
9. API仕様書を `docs/api/[feature-name].md` に作成
10. 使い方ガイドを更新

### 完了処理
11. **Draft PR**作成
12. CI確認
13. 作業ログをこのIssueに記録

## 🧾 コミット規約
`feat(feature-name): 説明 (#issue-number)`

## ⚠️ 品質要件
- [ ] TypeScript型定義完備(any禁止)
- [ ] エラーハンドリング完備
- [ ] ユニットテストカバレッジ80%以上
- [ ] セキュリティチェック済み
- [ ] パフォーマンス確認済み
- [ ] `ai_docs/coding_standards.md` 準拠

## ✅ 完了条件
- [ ] **CI全てグリーン**
- [ ] 機能が仕様通り動作
- [ ] テスト完備
- [ ] ドキュメント整備
- [ ] セキュリティレビュー済み
- [ ] パフォーマンス問題なし
- [ ] Draft PRレビュー依頼済み

Template 4: アーキテクチャ決定用

.github/ISSUE_TEMPLATE/architecture_decision.md:

---
name: Architecture Decision Record
about: 重要なアーキテクチャ決定を記録
title: '[ADR] 決定事項'
labels: architecture, documentation
---

## 🏛️ 決定事項


## 📋 背景
なぜこの決定が必要になったか:


## 🧩 検討した選択肢

### 選択肢1: [名前]
**説明**:

**メリット**:
- 

**デメリット**:
- 

**採用コスト**:

### 選択肢2: [名前]
**説明**:

**メリット**:
- 

**デメリット**:
- 

**採用コスト**:

### 選択肢3: [名前]
(以下同様)

## ✅ 決定内容
採用する選択肢: **[選択肢番号]**

理由:


## 📋 Claude Code用タスク定義

1. 各選択肢について技術調査
2. PoC(概念実証)コードを作成(必要に応じて)
3. 比較表を作成
4. `ai_docs/adr/[issue-number]-[title].md` にADRを記録
5. このIssueに推奨案を報告

## 📄 ADR形式
Architecture Decision Recordは以下の形式で記録:

~~~markdown
# ADR-[番号]: [タイトル]

## ステータス
提案中 | 承認済み | 却下 | 廃止

## 背景

## 決定内容

## 結果
この決定により期待される影響:
- プラス影響
- マイナス影響
- リスク

## 関連Issue
~~~

## ✅ 完了条件
- [ ] 全選択肢を調査済み
- [ ] ADR文書作成完了
- [ ] チームの合意を得た
- [ ] 実装に向けたIssue作成

ai_docs/の初期構築戦略

スクラッチ開発では、ai_docs/も成長させていくアプローチを取ります。

開始時(Day 1)

最小限のドキュメントだけ作成:

ai_docs/
├── README.md           # このディレクトリの使い方
├── vision.md          # プロジェクトのビジョン
└── decisions.md       # 初期の技術選定理由

vision.md の例:

# プロジェクトビジョン

## 何を作るか
リアルタイム協調編集ができるMarkdownエディタ

## 誰のために
技術ブログを書くエンジニア

## なぜ作るか
既存ツールは重すぎる or 機能不足

## 成功の定義
- 100人が日常的に使う
- ページロード3秒以内
- データロスゼロ

プロトタイプ完成時

プロトタイプから学んだことを追加:

ai_docs/
├── architecture.md    # 確定したアーキテクチャ
├── tech_stack.md     # 採用技術とその理由
├── prototypes/       # プロトタイプの学び
│   └── 001-realtime-sync.md
└── design/           # 設計ドキュメント
    └── data-model.md

本実装開始時

開発ルールを整備:

ai_docs/
├── coding_standards.md    # コーディング規約
├── security_guidelines.md # セキュリティガイドライン
├── testing_strategy.md    # テスト戦略
└── api_conventions.md     # API設計規約

成熟期

運用に必要な情報を追加:

ai_docs/
├── deployment.md         # デプロイ手順
├── monitoring.md         # 監視・アラート
├── troubleshooting.md   # トラブルシューティング
└── adr/                 # Architecture Decision Records
    ├── 001-database-choice.md
    └── 002-state-management.md

ポイント

必要になってから書く: 先に完璧なドキュメントを作らない
Claude Codeに手伝わせる: ドキュメント作成もIssue化
決定の理由を残す: なぜその選択をしたかを記録
定期的に見直す: 古くなった情報は更新

実践例: Webアプリケーションを作る

実際にゼロから簡単なWebアプリを作る流れを見てみましょう。

プロジェクト: タスク管理アプリ

要件:

ユーザーはタスクを作成・編集・削除できる
タスクには期限と優先度を設定できる
タスクは完了状態にできる

ステップ1: プロジェクト初期化

Issue #1: プロジェクトセットアップ

## 🎯 目的
タスク管理アプリの初期セットアップ

## 📋 Claude Code用タスク定義

1. プロジェクト構造を作成:
   - Next.js 14 + TypeScript
   - Prisma + PostgreSQL
   - Tailwind CSS

2. 基本的なディレクトリ構造:
   - `src/app/` - Next.js App Router
   - `src/components/` - Reactコンポーネント
   - `src/lib/` - ユーティリティ
   - `prisma/` - データベーススキーマ

3. 開発環境の設定:
   - ESLint, Prettier
   - Husky(pre-commit hook)
   - jest(テストランナー)

4. `ai_docs/` 初期構築:
   - vision.md
   - tech_stack.md
   - decisions.md

5. README.md作成(セットアップ手順)

まず環境構築から始めてください。

ステップ2: データモデル設計

Issue #2: データモデル設計

## 🏗️ 検討内容
タスク管理に必要なデータモデル

## 📋 要件
- User: ユーザー情報
- Task: タスク情報(タイトル、説明、期限、優先度、ステータス)
- User と Task は 1:N の関係

## 📋 Claude Code用タスク定義

1. ER図を作成(Mermaid形式)
2. Prismaスキーマを作成
3. マイグレーションファイルを生成
4. シードデータを作成
5. `ai_docs/design/data-model.md` にドキュメント化

設計案を提示してください。承認後に実装します。

ステップ3: プロトタイプ作成

Issue #3: UIプロトタイプ

## 🧪 検証したいこと
ユーザー体験の確認・デザイン方向性の決定

## 📂 スコープ
**実装する**:
- タスク一覧画面(モックデータ)
- タスク作成フォーム(動作不要)
- 基本的なレイアウト

**実装しない**:
- バックエンド連携
- バリデーション
- 状態管理

## 📋 Claude Code用タスク定義

1. `prototypes/ui/` ディレクトリで作業
2. Tailwind CSSで基本的なUIを実装
3. モックデータで表示確認
4. レスポンシブデザイン対応
5. スクリーンショットを撮影
6. `ai_docs/prototypes/003-ui-prototype.md` に学びを記録

デザインの方向性も提案してください。

ステップ4: 機能実装

Issue #4: タスクCRUD実装

## 🎯 機能概要
タスクの作成・読み取り・更新・削除機能

## 📂 スコープ境界
**許可パス**:
- `src/app/api/tasks/` - API Routes
- `src/components/TaskList/` - コンポーネント
- `src/lib/tasks.ts` - ビジネスロジック
- `prisma/` - データベース操作

## 📋 Claude Code用タスク定義

### 実装順序
1. Prismaクライアントのセットアップ
2. API Routes実装:
   - GET /api/tasks - 一覧取得
   - POST /api/tasks - 作成
   - PATCH /api/tasks/[id] - 更新
   - DELETE /api/tasks/[id] - 削除
3. バリデーション(Zod)
4. エラーハンドリング
5. フロントエンド統合
6. ユニットテスト作成

### 品質要件
- [ ] バリデーション完備
- [ ] エラーハンドリング完備
- [ ] ユニットテストカバレッジ80%以上
- [ ] API仕様書を `docs/api/tasks.md` に作成

段階的にコミットしてください。

ステップ5: テスト・改善

Issue #5: E2Eテスト作成

## 🧪 目的
ユーザーシナリオのテスト自動化

## 📋 Claude Code用タスク定義

1. Playwright セットアップ
2. 主要なユーザーフローのテスト作成:
   - タスク作成フロー
   - タスク編集フロー
   - タスク削除フロー
   - タスク完了フロー
3. CI/CDへの統合
4. `ai_docs/testing_strategy.md` を作成

テストシナリオを提案してください。

成果

約20個のIssueで、基本的なタスク管理アプリが完成します:

Issue #1-5: 基本機能
Issue #6-10: 認証機能
Issue #11-15: フィルター・検索
Issue #16-20: UI改善・バグ修正

段階的な開発プロセス

スクラッチ開発を成功させるための段階的アプローチ。

Week 1: 探索フェーズ

目標: 技術的な実現可能性を確認

Issueの種類:

[RESEARCH] 技術調査 × 2-3個
[PROTOTYPE] プロトタイプ × 2-3個
[DESIGN] アーキテクチャ決定 × 1-2個

Week 2-4: 基盤構築フェーズ

目標: 開発基盤を整備

Issueの種類:

[SETUP] 環境構築 × 1個
[DESIGN] データモデル設計 × 1-2個
[FEATURE] 基本機能実装 × 5-10個

Week 5-8: 機能実装フェーズ

目標: MVP(Minimum Viable Product)を完成させる

Issueの種類:

[FEATURE] 新機能 × 10-20個
[BUG] バグ修正 × 5-10個
[TEST] テスト追加 × 3-5個

Week 9-12: 改善・リリースフェーズ

目標: プロダクション品質に磨き上げ

Issueの種類:

[PERF] パフォーマンス改善 × 2-3個
[SECURITY] セキュリティ対策 × 2-3個
[DOCS] ドキュメント整備 × 2-3個
[DEPLOY] デプロイ準備 × 1-2個

ポイント

週単位で区切る: 長期計画は立てにくいため
振り返りをIssue化: 週次レビューもIssueで管理
優先順位を明確に: ラベルで管理(P0/P1/P2)
学びを蓄積: 毎週 ai_docs/weekly-notes/ に記録

よくある落とし穴と対策

落とし穴1: 完璧主義

症状:

プロトタイプに時間をかけすぎる
最初から全機能を実装しようとする
ドキュメントを完璧にしようとする

対策:

## タイムボックス設定
各Issueに時間制限を設ける:

- [PROTOTYPE]: 最大4時間
- [RESEARCH]: 最大2時間
- [FEATURE]: 最大8時間

時間内に完了しない場合は、スコープを削減するか分割。

落とし穴2: スコープクリープ

症状:

Issue実行中に次々と機能を追加
「ついでに」が増える
完了条件が曖昧

対策:

## スコープ固定ルール
Issue作成時に明確に定義:

**このIssueでやること**:
- 

**このIssueでやらないこと**(別Issueで対応):
- 

Claude Codeは「やらないこと」に手を出さないこと。

落とし穴3: ドキュメント不足

症状:

なぜその判断をしたか忘れる
同じ議論を繰り返す
後から見て理解できない

対策:

## 決定事項の記録を必須化
重要な決定は必ずADR(Architecture Decision Record)として記録:

**トリガー**:
以下の判断をした時は必ずADR作成:
- ライブラリ・フレームワークの選定
- アーキテクチャパターンの採用
- データベース設計の変更
- セキュリティ方針の決定

落とし穴4: テスト後回し

症状:

「後でテスト書く」が習慣化
バグ発見が遅れる
リファクタリングが怖い

対策:

## テストファースト原則
全ての [FEATURE] Issueに必須項目を追加:

## ✅ 完了条件
- [ ] **ユニットテスト作成済み**(これがないとPRマージ不可)
- [ ] テストカバレッジ80%以上
- [ ] 主要なエッジケースをカバー

Claude Codeには「テスト無しのコードは未完成」と指示。

落とし穴5: Claude Codeへの過度な依存

症状:

レビューせずにマージ
設計判断を全て委ねる
理解せずに使う

対策:

## 人間による必須レビューポイント
以下は必ず人間が確認:

- [ ] セキュリティに影響する変更
- [ ] データベーススキーマの変更
- [ ] 外部API連携の実装
- [ ] 認証・認可ロジック
- [ ] 課金・決済処理

これらが含まれるIssueには `needs-human-review` ラベルを付与。

落とし穴6: Issue粒度が大きすぎる

症状:

1つのIssueに複数日かかる
レビューが大変
途中で方向転換しづらい

対策:

## Issue分割ルール
以下を超える場合は分割:

- 変更ファイル数: 20ファイル以上
- コード行数: 500行以上
- 実装時間: 1日(8時間)以上

分割例:
- [FEATURE] ユーザー管理機能
  ↓
  - [FEATURE] ユーザーモデル実装
  - [FEATURE] ユーザー作成API実装
  - [FEATURE] ユーザー一覧API実装
  - [FEATURE] ユーザー編集UI実装

まとめ

スクラッチ開発でClaude Codeを活用するためのポイント:

✅ Do(やるべきこと)

段階的に開発: 探索→プロトタイプ→本実装→改善
タイムボックス: 各フェーズに時間制限を設ける
学びを記録: プロトタイプの学びを ai_docs/ に蓄積
スコープ固定: Issue毎に明確な境界を設定
テストファースト: テストを後回しにしない
定期的なレビュー: 人間が重要な判断を行う

❌ Don't(避けるべきこと)

完璧主義: 60%の完成度でまず動かす
スコープクリープ: 「ついでに」を許さない
ドキュメント後回し: 決定理由を必ず記録
テスト後回し: テストなしのコードは未完成
盲目的な信頼: Claude Codeのコードも必ずレビュー
大きすぎるIssue: 1日以内に完了するサイズに分割

次のステップ

小さなプロジェクトで試す: まずは個人プロジェクトから
テンプレートをカスタマイズ: プロジェクトに合わせて調整
学びを共有: チームでノウハウを蓄積

スクラッチ開発用のテンプレートリポジトリは準備中です。公開をお待ちください!

関連記事

Claude CodeとGitHub Issuesで効率的に開発する方法 - 保守・移行編

参考リンク