dev-workflow-planning

開発ワークフローの計画

このスキルは、曖昧またはリスクの高いエンジニアリング作業を、スコープ、順序、チェックポイント、検証、引き継ぎを含む、範囲の定まった実行計画に落とし込むために使います。計画の深さ、実行の形、マルチエージェントのガードレールを扱いますが、システム設計、PRD の作成、ブランチポリシーの判断は扱いません。

クイックリファレンス

タスク	参照先
計画の構成と成果物	references/planning-templates.md、assets/template-work-item-ticket.md、assets/template-milestone-checkpoint.md、../product-management/assets/ops/template-dor-dod.md
プラットフォーム固有のワークフローへの対応付け	references/platform-workflows.md、../ai-agents/references/agent-delivery-methods.md
複数セッションにまたがる計画の状態管理	references/long-horizon-journaling.md
並列処理、セッション、復旧のガードレール	references/operational-checklists.md、references/session-patterns.md、references/session-scope-budgeting.md、../ai-agents/references/context-rotation-and-state.md
仕様駆動型ツールの動向（GitHub Spec Kit、Kiro、BMAD）	references/spec-driven-dev-landscape.md
テストコンテキストの計画	../qa-agent-testing/references/coding-agent-regression-testing.md
不確実なデリバリーコストの定量化	references/uncertain-work-cost.md
変更が混在するケース、失敗するテストを設定できないケース、リスクに応じたプロセスの深さ	references/change-classes.md
ソースマップ	data/sources.json

使用する場面

• 機能追加、移行、リファクタリング、またはリスクの高いバグ修正を、検証可能な手順に分割します。
• 作業を逐次実行するか、範囲を限定した並列ウェーブで実行するかを判断します。
• 要件や RFC を、成功基準とロールバックの検討を含む計画契約に落とし込みます。
• 長期にわたるエージェントの作業を、永続的な成果物とスコープ制限の範囲内に保ちます。

他のスキルを使用する場面

• システム設計、サービス境界、または ADR： software-architecture-designを使います。
• 計画前の PRD または RFC の作成：docs-ai-prdを使います。
• リポジトリの成熟度、コンテキストレイヤー、または指示の展開：dev-context-engineeringを使います。
• ブランチ運用と PR ワークフローポリシー：dev-git-workflowを使います。
• テスト戦略の策定、または進行中の失敗のデバッグ：qa-testing-strategyまたはqa-debuggingを使います。

デフォルト

• 作業を分解する前に、成果と成功基準を明確にします。
• タスクに適した、最小限で永続性のある計画成果物を使います。
• 計画の深さを、実際のリスクとスコープに合わせます。
• インターフェースが変更中の場合や、ファイルが重複する場合は、逐次実行を優先します。
• 並列作業者には、それぞれ自己完結した説明と、担当ファイルを明示して割り当てます。また、新規に開始するのか、親の履歴から分岐するのかを記録します。
• 一般的な「まずテストを書く」という指示ではなく、影響を受けるコードに合わせたテストコンテキストを含めます。

ワークフロー

1. 目標、対象範囲、成功基準、不足している入力を確認します。
2. 変更を修正、変更、リファクタリング、追加に分類し、最初の作業に着手します（変更クラスと最初の作業）。次に、誤った場合のコストに応じて計画の深さを選びます。些細な計画、簡易計画、完全な計画契約、仕様駆動型のいずれかです。
3. 最もリスクの高い前提を取り除くよう、最初の手順を設定し、計画を無効にする観察結果を明示します（たとえば、呼び出し箇所が見積もりを超える、または対象範囲外のテストが失敗するなど）。その兆候が現れたら、続行せずに停止して計画を立て直します。
4. 計画契約を確定します。目標、範囲、依存関係、実行順序、検証、ロールバックを含めます。
5. 実行形式を選択します。逐次実行か、依存関係に基づくウェーブ形式です。
6. 範囲を限定したバッチを実行し、ウェーブ間で検証し、永続的な成果物にチェックポイントの状態を記録します。
7. 引き継ぎでは、完了したこと、未完了のこと、確認したこと、次に行う範囲を限定したアクションを明記します。

中核となる判断

計画の深さ

複雑さ	深さ	成果物	判断基準
単一ファイルで、結果が明らか	些細	なし、または一行	直接実行
複数手順で、範囲が明確	低	目標＋手順＋検証	2～5 ファイル、共有インターフェースなし
複数ファイルで、インターフェースが重複	中	ファイルの担当範囲を含む完全な計画契約	3 ファイル以上、スキーマまたは API の変更
複数エージェント、長期的、または仕様が必須	高	仕様 → 設計 → タスク → 実装	本番環境に影響する変更、依存関係が不明

変更クラスと最初の作業

観察可能な動作にどのような変化が起きるかで分類します。1 つの手順につき 1 つのクラスとし、複数のクラスが混在する依頼は分割します。

クラス	動作	最初の作業	テストファーストのルール
修正	合意済みの仕様に対して、現在の動作が誤っている	バグを再現するテストを書く	新しいテストが報告された理由で現在のコードに失敗し、その後パスすること。回帰テストとして残す
変更	現在の動作は正しいが、意図する動作が変わる	古い動作を検証するテストを見つけ、新しい動作を示すように編集する	編集したテストはコード変更前に失敗すること。計画では編集するすべてのアサーションを明記する
リファクタリング	動作を一切変えてはならない	既存のテスト一式をすべてパスさせる。カバレッジが不十分な場合は、現在の動作を固定する特性テストを追加する	アサーションの編集や新しい動作テストの追加は行わないこと。同じテスト一式が変更前後ともにパスする
追加	新しい動作を追加し、既存の動作は変更しない	受け入れ基準とインターフェースを記述し、再利用可能なコードがないか確認する	実装前に、各基準に対応する新しいテストが失敗すること。既存のテストは編集せずにパスする

クラスによって最初の作業が決まり、リスクによってその周囲の計画の深さが決まります。計画を変える可能性があるところにだけ手順をかけ、取り返しのつかない損害はゲートとして扱います（判断手順とクラスごとの調整、foundations-decision-theoryより）。

計画準備のゲート

中程度または高い深さの計画では、実装開始前に以下をクリアしてください。

1. 曖昧さのゲート。 成果物、成功基準、技術的アプローチに複数の妥当な解釈がある場合は、停止して質問します。推測に基づいて計画を立ててはいけません。
2. 既存パターンの確認。 命名、エラー処理、ログ記録、データアクセス、テストについて、対象領域にある既存の例を path:line 形式で示します。該当する例がない場合は、その旨を伝えます。規約を独自に作ってはいけません。
3. 初見の読者による確認。 コードベースの予備知識がない人でも、追加の検索や質問なしに、計画だけを使ってすべての手順を実行できる状態にします。そうでない場合は、不足しているパス、インポート、コマンドを追加します。
4. 逸脱ログ。 実装中は、計画から逸脱するたびに、何が変わったかとその理由を記録し、そのログを引き継ぎに含めます。

仕様策定を行うか、プロトタイプを作るか

仕様駆動を選ぶ	プロトタイプ先行を選ぶ
エージェントの実行前に仕様が必要（Kiro、Spec Kit のワークフロー）	使い捨ての足場、デモ、または未知の未知を探るための短期検証
受け入れ基準を伴うマルチエージェント間の引き継ぎ	1 回のセッション、開発者 1 人、引き継ぎなし
要件をコンテキストのリセット後も維持する必要がある	同じセッション内で目標が変わる
後続の AI エージェントが契約を再解析する	人間がすべての判断を対話的に進める

不確実性を解消できる場所に応じて、深さを選んでください。範囲を限定した検証や読み取り専用の調査のほうが完全な計画を立てるより早く答えを得られるなら、まずそちらを実施し、計画は暫定のままにします。

分岐の分類とプレイブックへの忠実さ

• 実行前に、「どちらのアプローチか」という分岐をそれぞれ分類します。観察可能な分岐（両方を低コストで試して比較する）か、好みで決める分岐（人間に尋ねる）です。観察可能な分岐については尋ねず、好みで決める分岐についてはプロトタイプを作りません。
• ワークフローまたはプレイブックを選んだら、その手順をそのまま todo リストにコピーします。実施しない手順は削除せず、skip: <reason> と記載します。
• ヒルクライミング最適化ループ（測定ごとに変更を 1 つだけ行う、機微なハーネスを固定する、目標と最小試行回数を明示する、決定ログを記録する）は、agents-swarm-orchestration が担当し、このスキルの対象ではありません。

AI コーディング時代の見積もり

AI コーディングエージェントによって、ボトルネックはタイピング速度から、判断の質、レビューの処理能力、検証コストへと移っています。人間のタイピング速度を基準に調整したストーリーポイントや時間で見積もると、作業のコストを正しく評価できません。

• 生成時間ではなく、レビューと検証の負荷を基準に見積もり直します。安定したインターフェースを持つ 3 つのファイルにまたがる 200 行の AI 生成差分は、生成には数分しかかからなくても、安全にレビューするには数時間かかることがあります。制約となる実際のリソースは生成時間ではなく、レビュー時間です。
• あいまいな作業では、仕様の作成と明確化にかかる時間が支配的になっています。仕様が不十分なプロンプトは、AI 支援による最初の実行で節約した時間以上に、やり直しのサイクルでコストがかかります。「実装」に含めず、インタビュー／明確化の段階に明示的な時間を割り当ててください（ループ前のセットアップ段階を参照）。
• AI の生成速度が速く見えるからといって、取り消し不能な作業や影響範囲の大きい作業（スキーマ移行、認証、課金、公開 API）の見積もりを縮めないでください。生成は速くても、安全な段階的リリースと検証の手順には時間がかかります。生成速度だけを基準に見積もると、計画の範囲が不十分になります。
• もっともらしく見える AI 生成の差分は、正しさの証拠ではありません。AI 生成コードにも、同じリスク区分の人間が書いたコードと同じ厳密さで検証の時間を割り当てます。差分がきれいだと誤った安心感が生まれますが、レビュー時間を減らせるわけではありません。
• AI エージェント導入前の過去のベロシティやスループットを、見積もりの比較基準として信頼しないでください。昨年のストーリーごとの平均値を引き継ぐのではなく、AI 支援による作業におけるチーム自身の現在のスループットを基に再調整します。

レビュー、やり直し、または作業項目の量が予算の判断に影響し得る不確実な状況では、不確実性に対処する手順を使用してください。スケジュールのロジックは依存関係の計画に含めます。コストシミュレーションではクリティカルパスは特定できません。

プランモード（Claude Code）

• 変更があいまい、またはリスクが高く、編集前に計画をレビューすると役立つ場合は、/plan を使用します。現在のエントリーポイントとコマンドの制限を確認するには、Claude Code のコマンドと権限のドキュメントを参照してください。

実行モデル

• リスクや重複の可能性が高い場合は、デフォルトで逐次実行します
• タスクが真に独立している場合に限り、ウェーブ方式の並列処理を行います
• 明示的な depends_on、共有インターフェースの定義、ウェーブ間の検証を1回設けます
• インターフェースの変更が頻発したり、ファイルの重複が発生したりしたら、並列処理を停止します
• スキーマまたは API の移行では、拡張 → 読み取り側と書き込み側の移行 → 縮小を、個別にデプロイおよびロールバックできる別々のマイルストーンとして計画します。プロデューサーとすべてのコンシューマーを一括で変更するステップは決して計画しないでください

並列作業を含む計画では、リストの順序に頼らず、依存関係を明示的にモデル化します。各作業項目には、前提条件、生成される成果物または状態、担当者、検証の証跡、およびその項目によって実行可能になる後続項目を記載します。前提条件が確認できた場合にのみ項目を ready とし、名前が明示された依存関係が未解決の場合は blocked とし、証跡が存在する場合にのみ done とします。

現在のクリティカルパスと、並列ブランチが合流する統合ポイントを特定します。スコープや証跡が変化したら、クリティカルパスを再計算します。クリティカルでないタスクに作業者を追加しても、計画の所要時間は短縮されません。すべての関連タスクが個別に完了を報告していても、統合チェックに合格した場合にのみマイルストーンを完了とします。

次に着手可能なマイルストーン

PRD または計画に デリバリーマイルストーン表 が含まれている場合は、記憶ではなく表から次の作業を選びます。

1. 表が DAG であることを確認します。すべての depends-on ID が存在し、循環がないことを確認してください。有向閉路がない場合にのみトポロジカル順序が存在します。有向閉路がある場合は、その閉路を明示してマイルストーンを再分割し、順序を選ばないでください（foundations-graph-theory、クイックリファレンス）。
2. 着手可能とは、すべての依存関係が done である pending の項目を指します。ここでの done は、受け入れチェックに合格していることを意味します。
3. 同順位の場合は、直接または推移的に、その項目に依存する pending のマイルストーンが最も多いものを選びます。このタイブレークは計画上のヒューリスティックであり、グラフ理論の定理ではありません。それでも同順位の場合は、最もリスクの高い前提を解消する項目を選びます（ワークフローのステップ 3）。
4. 着手前に、その項目を in-progress に設定します。並列作業者を使う場合は、agents-swarm-orchestration の説明に従って担当を宣言します。チェックに合格した証跡がある場合にのみ done に設定します。

無効な順序または制約付きの選択に関する基礎

• リストの順序によって状態依存の前提条件、不可逆な影響、または実行を無効にする可能性のある代替順序が見えにくくなっている場合は、planning/search を使用します。初期状態の証跡、アクションの前提条件と影響、再生して確認した有効な順序または最初に失敗した前提条件、および再計画のトリガーを示してください。不明な前提条件は未解決です。抽象的に有効な順序であっても、実装の成功を証明するものではありません。定型的なチェックリストや、前提条件がすでに明示され直接確認できる依存関係 DAG には、このモデルを使用しないでください。
• 分割できない作業項目の選択が、定量化されたキャパシティ、予算、またはその他の厳しい制約をめぐって競合し、貪欲な順位付けでは実行可能な組み合わせを見落とす可能性がある場合は、数学的最適化 を使用します。変数と定義域、目的関数と係数の出典、制約、実行可能な選択、および手法・境界・ギャップの状況を示してください。分割できない性質を維持してください。連続緩和は境界であり、実行可能な割り当てではありません。通常の定性的な優先順位付けや、入力がモデル化に不十分な場合には使用せず、未解決のトレードオフを記録してください。このスキルは引き続き、実行、担当、検証、チェックポイントを担います。

コンテキストとセッションの規律

• 各ワーカーに自己完結した概要を渡し、新規に開始するのか、親の履歴を引き継いで分岐するのかを記録します。「ワーカー」というだけでは、新しいウィンドウや完全なウィンドウが保証されません（agents-swarm-orchestration と同じルールです）。
• 計画、進捗、決定事項をファイルまたは安定したタスク成果物に記録します。
• 可能であれば、セッションごとに範囲を限定した成果を1つにします。
• 再試行や読み直しが繰り返される場合は、力ずくで進めるのではなく、スコープを見直します。

スコープクリープの検出

スコープクリープは、後になって収拾するより、早い段階で見つけるほうが簡単です。各チェックポイントで、次の兆候がないか確認します。

• タスクが、元の計画の契約に記載されていないファイルやシステムに及んでおり、それを意図的に決定した人がいません。
• 実装の途中で、元の成功基準になかった受け入れ基準が追加されています（「ここまでやるなら、ついでに……」）。
• 「簡単な修正」のはずが、エージェント（または人間）が隣接する不適切なコードに気づいたために、リファクタリングへと膨らんでいます。
• 検証計画が、元のスコープで約束していなかった範囲まで対象を広げ続けています。
• 複数のチェックポイントにわたって、残作業の見積もりが進捗を伴わずに何度も「ほぼ完了」に戻っています。

対応：追加内容を黙って現在のセッションに取り込まないでください。追加内容を明示し、（a）計画の契約を見直して、何がなぜ変わったのかを人間に伝えるか、（b）後続のマイルストーンに分割し、現在のセッションでは元の成功基準を維持します。契約を再交渉せずにスコープを取り込むと、範囲が限定されたタスクが際限のないものになります。

計画ドキュメントの出力形式

受け入れ基準は、バージョン管理された計画の中で解析可能な形式に保ちます。ドキュメント形式の選択には、docs-ai-prd を使用してください。

テストのコンテキストと検証

• 対象領域の source -> tests のコンテキストを含めます。
• 完全な依存関係グラフが利用できない場合は、入手可能な最善の近似を使用します。
• 引き継ぎ時に、正確な検証コマンドまたはレビューの証拠を求めます。
• バグ修正や新しい動作を実装する前に、該当する種類に適用されるテストファーストのルール（変更の種類）に従います。現在のコードで失敗または不足を記録し、変更後にそれが解消されることを示します。
• 動作を維持するリファクタリングや安全性の変更では、安全だといえる根拠となる事実を1つ明示し、差分を読むのではなく、実際のコードパスを実行して証明します。回帰の基準として、関連する既存チェックを変更の前後に実行し、それらのチェックでカバーされないリスクには、対象を絞ったチェックまたはレビューを追加します。
• 仕様や契約の検証が利用できない場合は、合格したと主張せず、その旨を伝えます。

複数セッションにまたがる計画状態

セッションの境界をまたぐ作業では、目標、決定事項、検証済みの進捗、次の範囲を限定したアクションを保持できる、既存の最小限の永続的な成果物を選びます。複数セッションにまたがる計画状態 では、探索的作業と範囲を限定した実装作業向けに、2つの任意のレイアウトを示しています。自律ループの終了には ai-coding-agents-state を使用し、複数ウェーブのディスパッチには agents-swarm-orchestration を使用してください。

既知の落とし穴

• 作業を分解した計画を立てても、判断の境界、成功基準、明示的な停止条件を一度も定めない。

• 書面上では独立して見えるタスクリストを根拠に、ファイルや不安定なインターフェースが重複する作業を並列ワーカーに割り当てる。

• 実際には具体的なコマンド、データセット、手動レビューのチェックポイントが必要なタスクで、「テストが必要」とするだけで十分な検証計画だとみなす。

• 状態を十分に永続化しないため、後続のセッションで永続的な成果物ではなくチャットから意図や進捗を再構築しなければならなくなる。

• リトライや混乱が繰り返されても、検証可能な成果に縮小せず、当初のスコープを維持する。

• 既知のバグ、リグレッション、フレームワーク／コンパイラー／ランタイムの落とし穴を、一次情報源のウェブ上の情報で確認せずに現在の事実として扱う。バージョン固有のクラッシュ情報や回避策はすぐに古くなります。

• Claude Code、Codex、GitHub、または関連するワークフローツールの一次ドキュメントで検証せずに、プラットフォーム固有のワークフロー、計画機能、製品上の制限について、現在の動作として断定する。

よくあるアンチパターン

• 直接実行すべき低リスクの作業に、完全な仕様策定のための過剰な手順を設ける。
• 担当、依存関係、ロールバックのロジックを定めずに、作業を多数の小さなタスクに分割する。
• 作業範囲を限定したタスクパケットと明確な受け入れ基準ではなく、会話履歴全体をワーカーに渡す。
• 計画した検証ゲートを実際に通過する前に、作業の一連の段階が完了したと宣言する。
• 最終引き継ぎを、何が変わり、何を確認し、何が残っているかを正確に示すものではなく、説明的な要約にしてしまう。

ナビゲーション

基盤となる資料は、特定された判断上の不足を補う場合にのみ読み込みます。適用条件とスキップ条件を確認し、当てはまらない場合は適用中のワークフローを続けるか、その担当者が必要な場合に限って担当者に引き継ぎます。

• 計画とプラットフォームの資料：references/planning-templates.md、references/platform-workflows.md、../ai-agents/references/agent-delivery-methods.md
• 並列処理と復旧：references/operational-checklists.md、references/session-patterns.md、references/session-scope-budgeting.md、references/flow-metrics.md、../ai-agents/references/context-rotation-and-state.md
• 補足的なワークフロー資料：../product-management/references/agile-ceremony-patterns.md、../product-management/references/remote-async-workflows.md、../product-management/references/technical-debt-management.md、../qa-agent-testing/references/coding-agent-regression-testing.md、data/sources.json
• 仕様駆動のツールとワークフロー：references/spec-driven-dev-landscape.md
• 基盤：../foundations-theory-of-constraints/SKILL.md — ボトルネックの特定、WIP 制限、T/CU のスループット計上。これらは flow-metrics.md および product-management の technical-debt-management.md の基礎となります
• テンプレート：../product-management/assets/ops/template-dor-dod.md、assets/template-work-item-ticket.md、assets/template-milestone-checkpoint.md、assets/example-medium-plan-contract.md（中規模の計画契約の記入例）

学びのループ

過去の判断や落とし穴が関係する場合は、learnings.consolidated.md があれば参照してください。必要な履歴を確認する場合、または他に利用できるものがない場合に限り、learnings.md を使用してください。それ以外の場合は、どちらも参照しないでください。

適用後、覚えておく価値のあるパターン、防止すべきミス、または意外だった分野の事実に気づいた場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って、日付付きの箇条書きを learnings.md に1つ追記してください。SKILL.md 自体は変更しないでください。