概要
- 要件→設計→実装→テストの各フェーズで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で効率的に開発する方法 - 保守・移行編