概要
- Claude Codeを使った独自の開発ワークフローの全体像
- 計画と実装の完全な分離による品質向上
- research.md・plan.mdなどマークダウンファイルを活用した共同作業
- アノテーションサイクルによる反復的な計画修正
- 実装・フィードバック・進捗管理までの具体的な運用例
Claude Codeを最大活用するためのワークフロー
- Claude Code を9ヶ月間メイン開発ツールとして利用した独自ワークフロー
- 一般的なAIコーディングツールの利用法（プロンプト投入→修正→繰り返し）とは一線を画す運用
- コア原則は「 計画の承認が終わるまでClaudeにコードを書かせない」という徹底した分業
- 計画（Plan）と実装（Implement）の分離により、無駄な作業の削減・設計のコントロール・トークン消費の最適化を実現
ワークフローフロー図
- Research → Plan → Annotate（1～6回反復）→ Todo List → Implement → Feedback & Iterate
Phase 1: Research（リサーチ）
- すべてのタスクは「 深読み指示」から開始
- Claudeに対象コードベースを徹底的に理解させ、 research.md に詳細な調査結果を書かせる
- 例：「このフォルダを徹底的に読解し、仕組み・機能・特徴を深く理解した上で、research.mdに学びと発見を詳細に記述」
- 例：「通知システムの複雑さを深掘りし、notificationの仕組みを全てまとめたresearch.mdを作成」
- 例：「タスクスケジューリングのバグを全て特定し、詳細な調査レポートを書く」
- 「 deeply, in great details, intricacies」などの強調ワードを必ず含めることで表面的な読解を防止
- research.mdは単なる宿題ではなく、「 レビューのための成果物」
- Claudeの理解度を確認・修正し、誤解があれば計画段階の前に修正
- 誤った調査→誤った計画→誤った実装の連鎖（Garbage in, garbage out）を防止
- システム全体への影響も考慮した設計ミスの予防
Phase 2: Planning（計画）
- 調査内容を確認後、 plan.md に詳細な実装計画を書かせる
- 例：「新機能<概要>を追加したい。plan.mdに詳細な実装計画を書いて」
- 例：「リストエンドポイントをカーソルベースページネーションに変更したい。plan.mdに具体的な手順を書いて」
- 例：「必ず現状のコードを読んだ上で計画を立てること」
- plan.mdには下記を必ず含める
- アプローチの詳細説明
- 変更点のコードスニペット
- 変更対象ファイルパス
- 注意点・トレードオフ
- built-in plan modeは使わず、独自のplan.mdを活用
- エディタで自由に編集・注釈追加可能、永続的な成果物として管理
- 参考実装がある場合は、関連コードを貼り付け「この実装を参考にplan.mdを書いて」と指示
- 具体例がある方がClaudeの精度が大幅に向上
- 計画自体よりも「 その後のアノテーションサイクル」が本質
アノテーションサイクル（Annotation Cycle）
- Claudeがplan.mdを作成→エディタでインラインノートを追加→Claudeに修正依頼→plan.md更新→満足するまで繰り返し
- ノート例
- 「migrationsはdrizzle:generateを使うこと、raw SQLは不可」— Claudeが知らないドメイン知識
- 「これはPATCH、PUTではない」— 誤った仮定の修正
- 「このセクションは不要、キャッシュは不要」— 提案の却下
- 「キューのリトライは既存で対応済み、重複処理は不要」— 理由付きの修正指示
- 「visibilityフィールドはリスト単位、アイテム単位ではない。スキーマを修正」— 設計全体の方向修正
- 修正指示には「 まだ実装しないこと」を明記し、計画が完成するまで実装を阻止
- この反復により、汎用的な計画をプロジェクトに最適化
- plan.mdはClaudeと自分の「共有・可変な状態」 として機能
- チャットでの曖昧な指示ではなく、計画書の該当箇所へ直接注釈
- 全体像を俯瞰しやすく、意思決定の履歴も明確
Todo List（タスクリスト）
- 実装前に「 詳細なTodoリスト」をplan.mdに追加させる
- 全フェーズ・全タスクを細分化して列挙
- 「まだ実装しないこと」を必ず指示
- このチェックリストが進捗管理の基準
- Claudeが進捗に応じてタスクを完了マーク
- 長時間セッションでも進捗が一目瞭然
Phase 3: Implementation（実装）
- 実装開始時の標準プロンプト例
- 「implement it all. when you’re done with a task or phase, mark it as completed in the plan document. do not stop until all tasks and phases are completed. do not add unnecessary comments or jsdocs, do not use any or unknown types. continuously run typecheck to make sure you’re not introducing new issues.」
- ポイント
- 計画通りに全て実装、一部だけ・途中確認は不要
- 完了ごとにplan.mdにチェック、進捗はplan.mdが唯一の真実
- 余計なコメントやany/unknown型禁止、型チェックは常時実行
- 計画段階で全ての意思決定が済んでいるため、実装は「機械的・退屈」な作業に
- 創造的判断はAnnotation Cycleで済ませる
- 計画なしで始めると、誤った仮定に基づく修正地獄に陥りやすい
フィードバックと実装中の修正
- Claudeが実装中は、ユーザーは「 設計者から監督者」へ役割シフト
- フィードバックは短く簡潔に
- 例：「deduplicateByTitle関数が未実装」「settingsページはadmin appで作るべき、main appではない」
- Claudeはplan.mdとセッション全体の文脈を保持しているため、短い修正指示で十分
- フロントエンドは特に反復が多い
- ブラウザで確認→「wider」「まだ切れてる」「2px隙間」など即時修正指示
- スクリーンショット添付で視覚的な問題を迅速に伝達
- 既存コードを参照して「usersテーブルと同じ見た目に」など、既存パターンの再利用を指示
- 大きく方向性がずれた場合は「 gitで巻き戻し・スコープ再設定」が最善
- 例：「全てリバート。今回はlist viewをよりミニマルにするだけで良い」
- 修正地獄に陥るより、スコープを狭めてやり直す方が効果的
主導権を握り続ける
- Claudeに実装を委任しても、「 何を作るかの最終決定権は自分」
- ほとんどの調整・判断はplan.mdで行い、Claudeの自動判断に任せきりにしない
- Claudeが提案する解決策は「技術的には正しいが、プロジェクトに合わない」場合がある
- 例：過剰設計、既存APIの互換性崩壊、シンプルな選択肢を無視
- システム全体の文脈、プロダクトの方向性、エンジニアリング文化など、Claudeにはない背景知識を活かし続けることが重要