Claude Code 開発ワークフロー

English | 简体中文 | 日本語 | Español | 한국어 | Português (Brasil)

Claude Codeはコードベースを深く探索できます。しかし、複雑な作業でより難しいのは、探索そのものではなく結論へ収束させることです。たとえばアカウント復旧フローを設計している途中で、トークン処理の不整合を見つけ、その調査に大半を費やした結果、本来求められていた復旧時の動作が曖昧なまま残ることがあります。

claude-code-workflowsは、探索を合意済みの成果へ向け続けるための仕組みです。設計前に成果と対象外を合意し、設計内容をリポジトリと照合し、コミット前に各タスクを検証します。規模の大きな変更では、完成した実装が合意した成果を実現し、不要な機能や変更を含まず、動作・信頼性・セキュリティに重大な問題がないかを独立してレビューします。その範囲内で、実装の詳細はClaudeがコードベースから判断します。

成果と安全な実装範囲がすでに明確なら、Claude Codeをそのまま使うのが適しています。スコープの合意、後から参照できる設計判断、コンテキスト間の確実な引き継ぎ、独立した検証が必要な変更では、このワークフローを使ってください。

どんなときに役立つか

このワークフローはエージェント呼び出しと成果物を増やすため、そのコストに見合う場面で使うものです。関連する問題の発見によって変更の目的がずれそうな場合、筋の通った設計でも要求された動作を外す可能性がある場合、あるいはテストが通っていても確認したい動作を実際には観測できていない場合に効果を発揮します。

実装範囲の承認後は、Claudeが各タスクに絞った検証、リポジトリの品質チェック、コミット、最終レビューまで進めます。通常の実装判断で逐一確認を求めることはありません。合意したプロダクト成果や対象外を変える必要がある場合だけユーザーに判断を求め、技術設計や実装上の選択はClaudeが進めます。Claude Codeプラグインとして提供されるため、Claudeの手順を固定せずに、複数のリポジトリへ同じ統制を適用できます。

クイックスタート

プラグインマーケットプレイスに対応したバージョンのClaude Codeが必要です。

目的に合うルートを選ぶ

共通セットアップ

# 1. Claude Codeを起動
claude

# 2. マーケットプレイスを追加
/plugin marketplace add shinpr/claude-code-workflows

ワークフロープラグインを1つインストールする

プロジェクトに合うプラグインを選びます。インストール後に/reload-pluginsの実行を求められた場合は、レシピを呼び出す前に実行してください。

# バックエンドまたは一般的な変更
/plugin install dev-workflows@claude-code-workflows
/recipe-implement "Add rate limiting to the public API"

# フロントエンド
/plugin install dev-workflows-frontend@claude-code-workflows
/recipe-front-design "Add account recovery screens"

# フルスタック
/plugin install dev-workflows-fullstack@claude-code-workflows
/recipe-fullstack-implement "Add user authentication with JWT + login form"

インストールするワークフロープラグインは1つだけにしてください。dev-workflows-fullstackにはバックエンドとフロントエンドの両方が含まれています。以前dev-workflowsのフルスタックレシピを使っていた場合は、dev-workflows-fullstackへ移行してください。

/recipe-front-designは、該当するUI仕様と設計ドキュメントがレビュー・承認された時点で終了します。続けて実装する場合は/recipe-front-planと/recipe-front-buildを実行します。バックエンドや一般的な変更にも、同じ段階構成の/recipe-design、/recipe-plan、/recipe-buildがあります。

チームでのセットアップ

Claude Codeはプロジェクト単位のマーケットプレイスとプラグインに対応しています。生成された.claude/settings.jsonをコミットすると、コントリビューターにも同じワークフロープラグインの利用を案内できます。

claude plugin marketplace add shinpr/claude-code-workflows --scope project
claude plugin install dev-workflows-fullstack@claude-code-workflows --scope project

dev-workflows-fullstackは、リポジトリに合うプラグインへ置き換えてください。プロジェクト単位および管理対象のインストール方法については、Claude Codeのプラグインドキュメントを参照してください。

仕組み

flowchart LR
    A[Request] --> B[Agree on outcome and exclusions]
    B --> C{One evident implementation path?}
    C -->|Yes| S[Direct task cycle]
    S --> J[Complete]
    C -->|No| D[Inspect, design, and review]
    D --> E[Approve implementation scope]
    E --> F[Per task: implement, verify, quality-check, commit]
    F --> I[Independent implementation and security review]
    I -->|Correction| F
    I -->|Boundary changed| B
    I -->|Passed| J[Complete]

ルートを決めるのはファイル数や実装量ではなく、必要なプロダクト判断と設計判断の数です。

UI仕様、ADR、結合テストやE2Eテストのスケルトンは、それぞれの判断または検証境界が必要な場合にだけ作成されます。

成果物を生成しただけでは、ワークフローは次へ進みません。採用する設計を左右する前提は承認前に検証し、範囲を絞った動作確認は最小限の検証手段となる場合にだけ実行します。

作業計画は、実装を許可する前に、範囲、依存順序、実行可能な検証方法についてレビューされます。各タスクはそのタスクに絞ったチェックと該当するリポジトリチェックを通過してからコミットされます。段階的な実装が完了すると、実装全体が合意した成果に沿っているか、不要な機能や変更、重大な動作不良や信頼性の問題がないか、必要な動作を確認できているか、セキュリティ上の問題がないかを個別のレビューで確認します。

メインセッションは、どの発見が現在の成果に含まれるかを判断し、リポジトリを根拠に実装上の疑問を解決し、影響を受けない作業を止めずに進めます。レビューの提案が自動的に作業項目になることはありません。受け入れた修正は実装へ戻され、影響する検証ゲートを再度通過します。

新しいコンテキストへ判断を引き継ぐ仕組み

フェーズごとに新しいコンテキストを使うことで、前のフェーズの推論が、次のフェーズで暗黙の権限になることを防ぎます。同梱の作業計画テンプレートでは、設計ドキュメントで承認されたすべての技術要件について、対応するタスクまたは明示的なギャップが必要です。ドキュメントの全セクションやレビュー提案を、無条件にタスクへ変換するものではありません。ギャップとは、承認済み要件に実装タスクまたは検証タスクがまだない状態を指します。

| Design Doc | DD Section | DD Item | Category | Covered By Task(s) | Gap Status | Notes |
|---|---|---|---|---|---|---|
| docs/design/example.md | API contract | Preserve the error response shape | contract-change | Phase 2 Task 1 | covered | |
| docs/design/example.md | Verification | Exercise cache invalidation | verification | | gap | Add a covering task before approval |

タスクテンプレートは、実装を拘束する判断と外部から確認できる契約上の値を引き継ぎ、それぞれにYes/Noで判定できる準拠チェックを持たせます。実行後、コミット前にタスク全体の変更へ該当するリポジトリチェックを行います。最終レビュアーは実装時の会話ではなく、同じ承認済みソースと完成したコードを読みます。/recipe-quality-profileを使うと、リポジトリ固有の品質ルールとその根拠をdocs/project-context/quality.yamlに記録でき、実装担当と最終レビュアーは確認済みの設定を承認済みソースとあわせて使います。

実際のワークフロー実行例

mcp-local-ragの増分同期機能は、ファイルシステムのスキャン、ストレージ、CLI、MCPの各インターフェースにまたがる42ファイルの変更でした。独立したセキュリティレビューによって実装は2回差し戻され、検証前のファイル読み取りと、シンボリックリンクされた親ディレクトリを経由してパス制限を回避できる問題が見つかりました。

この実行は、参照先のADRと設計ドキュメントが存在しない作業計画から始まり、技術判断の根拠が不明確な状態でした。ユーザーは作業計画を正本として扱うことを選び、レシピはそれを13個のタスクに分割しました。最終実装には承認された動作を検証するために必要な変更が含まれ、監視モードと永続ジョブを対象外にした理由はPRに記録されています。

初回実行後に確認すること

• 合意したアプローチは既存の仕組みを拡張しているか。各追加には根拠があるか。
• 各要件からタスクと観測可能な検証方法まで追跡できるか。
• 完了したすべてのタスクが、コミット前にそのタスクに絞ったチェックとリポジトリの品質チェックを通過したか。
• 最終レビューで、実装全体が合意した成果を満たし、不要な機能や変更、動作・信頼性・セキュリティの重大な問題がないことを確認したか。
• レビュアーが追加作業を提案した場合、適用または却下した理由が報告されているか。

代表的なワークフロー

バックエンドまたは一般的な変更を最初から最後まで実装する

/recipe-implement "Add rate limiting to the public API"

レシピは変更範囲を定め、現在の実装を調べ、判断に必要なドキュメントだけを作成します。判断が必要な箇所では承認を求め、作業計画に沿った実装と最終レビューまで進めます。

先に設計し、実装は後で行う

# バックエンドまたは一般
/recipe-design "Design rate limiting for the public API"
/recipe-plan
/recipe-build

# Reactフロントエンド
/recipe-front-design "Build a user profile dashboard"
/recipe-front-plan
/recipe-front-build

設計レシピは既存実装を確認し、範囲を確定し、必要なドキュメントを作成して、独立した整合性レビューを行った後に承認を待ちます。承認済みの成果物があれば、別のコンテキストや別の担当者が後から計画と実装を再開できます。

フロントエンドでは、UIの構造や動作に設計の余地がある場合にUI分析とUI仕様を追加し、さらにコンポーネント設計、React Testing Library、TypeScriptのチェックを行います。

たとえば2つのダッシュボードコンポーネントが個別にはローディングを正しく処理していても、一方がローディング中で他方が失敗したときの画面全体の動作が未定義な場合があります。UI仕様はその状態の組み合わせを記録し、結合前に設計とテスト作業へ対応付けます。

フルスタック開発

/recipe-fullstack-implement "Add user authentication with JWT + React login form"

変更に複数の独立したプロダクト成果がある場合は、1つのPRDで機能全体を扱います。バックエンドとフロントエンドの設計は分離したまま、design-syncが境界の整合性を確認し、作業計画は垂直スライスを使って早い段階から結合を検証します。

既存のフルスタック作業計画から再開するには/recipe-fullstack-buildを使います。フルスタックプラグインには、対応するバックエンドとフロントエンドのレシピも含まれます。

/recipe-review

/recipe-diagnose "API returns 500 on user login"

/recipe-reverse-engineer "src/auth module"

/recipe-front-adjust "Align the card spacing and actions with the design source"

ワークフローレシピ一覧

すべてのワークフローはrecipe-で始まります。/recipe-まで入力してTabキーを押すと、インストール済みの候補を補完できます。

プラグインに含まれるもの

専門エージェントは分析と設計を実行・最終レビューから分離します。各プラグインには、そのワークフローが使う役割だけが含まれ、フルスタックプラグインはバックエンドとフロントエンドの役割を統合します。役割の全一覧は以下で確認できます。

/plugin install dev-skills@claude-code-workflows

# dev-skillsからdev-workflowsへ
/plugin uninstall dev-skills@claude-code-workflows
/plugin install dev-workflows@claude-code-workflows

# dev-workflowsからdev-skillsへ
/plugin uninstall dev-workflows@claude-code-workflows
/plugin install dev-skills@claude-code-workflows

/plugin install discover@claude-code-workflows
/plugin install metronome@claude-code-workflows
/plugin install linear-prism@claude-code-workflows
/plugin install pr-review@claude-code-workflows

FAQ

Q：エラーが発生した場合はどうなりますか？

A：quality-fixerエージェントが、承認済みの成果の範囲内でテスト、型、lint、ビルドの失敗を修正します。同じ責務や契約に必要な周辺変更も対象です。

ワークフローがユーザーに判断を求めるのは、要求された成果と対象外を両立できなくなった場合か、元に戻せない外部操作に承認が必要な場合だけです。技術設計、契約、UI、アーキテクチャ、永続化、実装の変更は、プロダクトが提供する価値を変えない限りClaudeが進めます。

Q：OpenAI Codex CLI向けのバージョンはありますか？

A：はい。**codex-workflows**は同じワークフローモデルをCodex CLI向けに調整しています。

Q：docs/plans/の作業計画とタスクファイルはコミットすべきですか？

A：いいえ。レシピはdocs/plans/を一時的な作業状態として扱います。処理済みのタスクファイルと中間修正ファイルは、正常終了後に削除されます。作業計画はレビューや後続のビルドのために残る場合がありますが、不要になれば削除できます。この作業状態がGit管理に入らないよう、プロジェクトの.gitignoreへ次の行を追加してください。

docs/plans/

PRD、ADR、UI仕様、設計ドキュメントは、それぞれdocs/prd/、docs/adr/、docs/ui-spec/、docs/design/に配置され、コミット対象です。

外部プラグインのコントリビューション

このマーケットプレイスは、プロダクト品質、発見、実装統制、検証まで、AIを使ったプロダクト開発のライフサイクル全体を支援します。AIコーディングエージェントによる開発を改善するプラグインをお持ちなら、ぜひお知らせください。

提出方法と受け入れ基準はCONTRIBUTING.mdを参照してください。

claude-code-workflows/
├── .claude-plugin/
│   └── marketplace.json        # Plugin definitions and per-plugin contents
├── agents/                     # Specialized analysis, design, execution, and review roles
├── skills/
│   ├── recipe-*/               # Workflow entry points
│   ├── documentation-criteria/ # Document rules and templates
│   ├── coding-principles/
│   ├── testing-principles/
│   ├── external-resource-context/
│   ├── llm-friendly-context/
│   └── ...
├── LICENSE
└── README.md

設計上の背景

ライセンス

MIT License。自由に利用、変更、配布できます。

詳細はLICENSEを参照してください。

@shinprが開発・メンテナンスしています。