implementation-planner

実装計画

このスキルは、マイルストーン、タスク、ベストプラクティスの遵守を含む包括的な実装計画を作成します。

前提条件

• business-requirements.yaml が完成していること
• technical-requirements.yaml が完成していること
• 推奨：style-anchors-collection スキルの style-anchors/index.yaml

計画プロセス

Phase 0：順序戦略の選択

要件を分析したりマイルストーンを作成したりする前に、どの順序戦略を使用するかユーザーに尋ねます。次のプロンプトをそのまま提示してください。

---

実装計画を作成する前に、マイルストーンをどのような順序にしたいか確認させてください。戦略を選んでください。

1. マルチ PR／トランクベース — 各マイルストーンは個別に PR を作成でき、継続的に develop／main にマージされます。各マイルストーンは単独でリリース可能である必要があります。トランクベース開発を採用しているチームに最適です。
2. 単一機能ブランチ — すべてのマイルストーンを、最後に単一の PR を作成するまで、1 つの長期ブランチで管理します。順序は技術的な依存関係のみで決まります。完了するまで main に触れてはならない独立した機能に最適です。
3. 価値優先（デモ主導） — 一部のインフラを後回しにしてでも、ユーザーに見える機能をできるだけ早く提供できるよう、マイルストーンを並べ替えます。早期のステークホルダーデモやフィードバックが必要なプロジェクトに最適です。
4. リスク優先 — 不確実性が最も高いものや技術的に未知のマイルストーンを先に配置し、早期に障害要因を明らかにします。不明点が多いプロジェクトに最適です。
5. 垂直スライス／ウォーキングスケルトン — 最初のマイルストーンで、すべてのアーキテクチャ層にまたがる薄いエンドツーエンドのスライスを提供します。その後のマイルストーンで各領域を充実させます。アーキテクチャを早期に検証するのに最適です。
6. 基盤優先（逐次） — まずインフラとツールを整備し、次に機能を実装し、最後に仕上げます。順序は厳密に固定されます。要件が明確なグリーンフィールド開発に最適です。

または、**「おすすめを選んで」**と入力してください。要件に基づいてこちらで選択します。

---

ユーザーの選択を ordering_strategy として記録します。ユーザーが「おすすめを選んで」と言った場合は、要件を分析し、最も適切な戦略を選択して、その理由を説明します。Phase 2（マイルストーンの特定）全体にわたって、対応する順序ルールを適用してください。

戦略ごとの順序ルール：

• マルチ PR／トランクベース：各マイルストーンには「リリース可能」な成功基準が必要で、進行中（未マージ）の他のマイルストーンに依存してはなりません。各マイルストーンを個別にレビューしてマージできるように順序を決めます。
• 単一機能ブランチ：技術的な依存関係のみで順序を決めます。各マイルストーンをリリース可能にする必要はありません。
• 価値優先：ユーザーへの影響が大きい順にマイルストーンを並べます。必要な基盤作業を、前提となるセットアップ作業として最初のマイルストーンにまとめます。
• リスク優先：不確実性／リスクスコアの高い順にマイルストーンを並べます。リスクの高いマイルストーンを m0 または m1 とし、早期にリスクを低減します。
• 垂直スライス：最初のマイルストーンでは、1 つの薄い機能を実現するため、すべてのアーキテクチャ層にまたがって実装します（例：API エンドポイント 1 つ＋UI＋永続化）。残りのマイルストーンでは、機能領域ごとにまとめます。
• 基盤優先：現在のデフォルトの順序です。インフラ → コア機能 → 高度な機能 → 仕上げ／リリース。

フェーズ 0.5：対象読者の選択

ユーザーが順序付けの方針を選択した後、計画の作成対象となる読者を尋ねます。

---

この実装計画の主な対象読者は誰ですか？

1. AI エージェント — 手順ごとの指示、コード例、明示的な制約を含む、実装の詳細な説明です。Claude Code など、AI 主導の開発ワークフローに最適です。

2. 人間の開発者 — 目標、スタイルアンカーの参照、成功基準を含む、概要レベルのタスク説明です。開発者は独自の実装方法を決定します。規範的な手順ではなく計画の構成を必要とする経験豊富なチームに最適です。

3. ハイブリッド — 中程度の詳細レベルです。主要な実装ガイダンスとパターンの参照を含みますが、日常的な判断は開発者に委ねます。混成チーム、AI とのペアプログラミング、または引き継ぎ資料として最適です。

---

ユーザーの選択を target_audience: "ai" | "human" | "hybrid" として記録します。

デフォルト： ユーザーが迷っている場合は、自律的な開発セッションでは「ai」、経験豊富な開発者チームでは「human」を推奨します。

入力の分析

1. 要件の読み込み

   • ビジネス要件を解析し、機能の範囲を把握します
   • 技術要件を解析し、アーキテクチャに関する判断を把握します
   • {base_directory}/artifacts/style-anchors/index.yaml からスタイルアンカーを読み込みます（存在する場合）
   • 依存関係と制約を特定します

2. マイルストーンの特定

   • 関連する機能を論理的なマイルストーンにまとめます
   • マイルストーンの順序と dependencies の設定時に、選択した ordering_strategy の順序付けルールを適用します
   • 依存関係の順序を確立します
   • マイルストーンの成果物を定義します

3. タスクの生成

   • マイルストーンを最小単位のタスクに分割します
   • タスクの規模に関するルール（30m～2.5h）を適用します
   • タスクの依存関係を定義します
   • タスクの種類とファイルパターンに基づき、index.yaml から関連するスタイルアンカーを選択します
   • タスクの指示にスタイルアンカーへの参照を埋め込みます
   • 各マイルストーンに最終コードレビュータスクを追加します

4. ベストプラクティスの適用

   • TDD の要件
   • スタイルアンカーの参照
   • 品質上の制約
   • ドリフト防止ルール
   • 包括的なコードレビュー

ベストプラクティス（組み込み）

基本原則

段階的な検証

モデルは局所的に最適化するため、段階的な検証（プロンプト → IDE → コミット → CI → 実行時）を用いて全体的な制約を適用します。

スタイルアンカー

• テンプレートとして常に模範的なファイルを 2～3 個含めます
• 正確なパスと行番号を参照します
• 具体的なリポジトリの例（コード + テスト + README）を優先します
• 早い段階でアンカーを適用し、アーキテクチャのドリフトを防ぎます

タスクの規模

• 作業を 30m～2.5h の最小単位のタスク（最適な時間は 30～150 分）に分割します
• 範囲を特定のファイルに限定します
• 小さなタスクごとにコミットします
• ドリフトが発生したら、直ちに元に戻します
• タスクが 30m 未満の場合は、見積もりを増やすか、根拠を示して分割します

肯定的な指示

• 許可される操作を明示します
• 否定的な表現を避けます
• 「A、B、C を使わないでください」ではなく「X、Y、Z のみを使用してください」とします

階層化されたルール

• グローバル：ユーザー設定（形式、言語、長さ）
• プロジェクト：CLAUDE.md または .cursor/rules/ に記述された永続的なルール
• コンテキスト対応：ディレクトリまたはファイルパターンごとに自動で適用されるルール

品質制約

TDD を基軸にする

• 実装前に TDD チェックリストを必須にします
• テスト → 最小限のコード → 追加のテスト → リファクタリング
• テストが失敗した場合は、失敗した出力とともに次の指示を返します：「これまでに合格したすべてのテストを維持したまま、このテストに合格するよう実装を修正してください。テストを変更しないでください。依存関係を追加しないでください。」

逸脱への対処

• 予期しない依存関係や見慣れないパターンがあれば、直ちに中止して元に戻します
• 作業の途中で修正しないでください
• 各セッション後に学んだことを記録し、永続的なルールを更新します

プロンプトの配置

• 重要な仕様、スタイルの基準、厳守すべきルールは冒頭に配置します
• プロンプトの最後にも繰り返し記載します
• 要件を途中に埋もれさせないでください

外部データの検証

• 外部データに対して型アサーションを使用しないでください
• すべての外部入力を適切なエラー処理とともに検証します
• 実行時アサーションではなく、スキーマ検証を使用します

出力形式

マイルストーンの構成

バージョン、プロジェクトのメタデータ、メタセクション（順序付け戦略、対象者）、およびmilestones配列を含むmilestones.yamlを生成します。metaセクションには、ordering_strategy、ordering_rationale、target_audience（ai/human/hybrid）を含めます。各マイルストーンには、id（m0、m1...）、name、description、dependencies、estimated_duration、tasks_file、success_criteriaを含めます。任意のフィールドとして、acceptance_criteria（functional、non_functional、testing、documentation）とexit_checklistを含めることができます。

すべてのフィールド、順序付け戦略、任意のフィールドを含む完全なドキュメント仕様については、**references/milestones-spec.md**を参照してください。

完全な例については、**references/milestones-example.yaml**を参照してください。

任意のフィールドに関する注意：

• success_criteria（必須）：計画段階の高レベルな受け入れ基準
• acceptance_criteria（任意）：要件の追跡、テスト要件、ドキュメントに関する期待事項を含む詳細な成果物の基準。厳格なマイルストーン承認が必要な場合に使用します。
• exit_checklist（任意）：コードレビュー用の二者択一式の実施可否チェックリスト。正式なゲート主導型プロセスが必要な場合に使用します。

ほとんどのプロジェクトではsuccess_criteriaのみを使用します。次の場合は詳細な受け入れ基準を追加してください。

• プロジェクトで監査に対応できる要件の追跡可能性が必要な場合
• 複数の関係者に明確な承認基準が必要な場合
• QA チームがマイルストーンごとの明示的なテスト要件を必要とする場合
• コードレビューのプロセスで詳細なチェックリストが必要な場合

生成後に詳細な基準を追加するには： /definition-of-doneを実行して、要件に基づくacceptance_criteriaフィールドとexit_checklistフィールドをmilestones.yamlに追加します。

タスクの構成

task_summaries、スタイルの基準、グローバル制約、品質ゲート、およびtasks配列を含むmilestone-m*.tasks.yamlを生成します。

必須セクション：

• task_summaries（マップ）：タスク ID と、平易な英語による1～2文の要約の対応。一覧しやすい概要として先頭に配置します。各要約は20～300文字とし、方法ではなく何を・なぜ行うかに焦点を当て、能動態を使用します。例：m1-001: "Creates core User model with validation rules for all user operations."
• global_constraints：許可するパターン、禁止するパターン、TDD 要件、タスクの最大所要時間、コミット戦略
• quality_gates：タスク開始前、コミット前、タスク完了時、マイルストーン完了時、プッシュ前の各段階
• tasks：タスクオブジェクトの配列

各タスクには次の項目を含めます： id（mN-NNN 形式）、name、description、estimate_minutes（30～150）、type（code/test/docs/config）、dependencies、files（create/modify/touch_only）、style_anchor_refs、および詳細なinstructions。

タスクの構成、品質ゲート、TDD チェックリストを含む完全なドキュメント仕様については、**references/milestone-tasks-spec.md**を参照してください。

完全な例については、**references/milestone-tasks-example.yaml**を参照してください。

タスクの規模に関するガイドライン

最適なタスクの所要時間

• 最短：30 分
  • タスクがそれより短い場合は、理由を記録します
  • 関連するタスクとの統合を検討します
• 最適：30～150 分
  • 原子的で、範囲が明確な変更
  • 1 回のセッションで完了できる
  • 明確な成功基準がある
• 最長：150 分（2.5 時間）
  • タスクがそれより長い場合は、より小さなタスクに分割します
  • 自然な区切りを特定します
  • サブタスク間に依存関係を設定します

タスクの規模の例

小さすぎる（30 分未満）

- id: m1-001
  name: Add export statement
  estimate_minutes: 10
  rationale: "Simple addition but critical for module system"

最適（30～150 分）

- id: m1-002
  name: Implement user authentication service
  estimate_minutes: 90
  dependencies: [m1-001]

大きすぎる（150 分超）— 分割

# BEFORE (too large):
- id: m1-003
  name: Build complete API layer
  estimate_minutes: 300

# AFTER (properly split):
- id: m1-003
  name: Define API interface and types
  estimate_minutes: 60

- id: m1-004
  name: Implement API routes
  estimate_minutes: 90
  dependencies: [m1-003]

- id: m1-005
  name: Add API middleware and error handling
  estimate_minutes: 60
  dependencies: [m1-004]

タスク指示の詳細レベル

タスクの指示は、フェーズ 0.5 で選択された対象ユーザーに基づいて、異なる詳細レベルで生成されます。

AI エージェントを対象とする場合（詳細）

構成：

• 目的： 構築するものを明確に示します
• スタイルの基準： 行番号付きのパターンファイルへのリンク
• 参照ファイル： コードベース内の具体例
• 実装手順： 番号付きの具体的な手順（1、2、3...）
• 制約： 「次のもののみ使用する」「次のものは絶対に使用しない」を明示します
• TDD チェックリスト： テストファーストの要件を段階的に示します
• 検証： 期待される出力を含む正確なコマンド
• 逸脱時の方針： 作業を中止して元に戻す条件

例：

instructions: |
  **Objective:**
  Define Project and Milestone domain models using Model.Class.

  **Style Anchors:**
  Follow these established patterns:
  - See `artifacts/style-anchors/SA-002.md` — Model.Class with makeRepository
  - See `artifacts/style-anchors/SA-006.md` — Effect Schema domain types

  Reference files:
  - `~/Sites/ai/effect/packages/sql/src/Model.ts:82-157` — Model.Class definition
  - `~/Sites/ai/EffectPatterns/packages/pipeline-state/src/schemas.ts:1-234` — domain patterns

  **Implementation Steps:**
  1. Create `packages/shared/src/schemas/project.ts`:
     - PipelineStatus: Schema.Literal union of all pipeline stages (intake through archived)
     - Priority: Schema.Literal("low", "medium", "high", "critical")
     - Project model using Model.Class with fields:
       id (Model.Generated), slug, name, description, pipelineStatus,
       assignedPeople (Model.JsonFromString array), tags (Model.JsonFromString array),
       priority, createdAt (DateTimeInsert), updatedAt (DateTimeUpdate)
  2. Create `packages/shared/src/schemas/milestone.ts`:
     - MilestoneStatus: Schema.Literal("pending", "in-progress", "blocked", "complete")
     - Milestone model using Model.Class with fields:
       id, projectId, name, description, status, orderIndex, estimatedDays,
       acceptanceCriteria, createdAt, updatedAt
  3. Export all types and schemas from each file
  4. Update schemas/index.ts barrel export

  **Constraints:**
  - ONLY use: Model.Class, Schema.Literal, Schema.Struct
  - Follow **SA-002** for Model.Class structure with variant schemas (insert, update, select)
  - Follow **SA-006** for Schema.Literal enum patterns
  - NEVER use: TypeScript enum keyword or plain interfaces
  - NEVER use: type assertions (as) on external data
  - Include proper JSDoc comments for all exported types

  **TDD Checklist:**
  Before writing implementation:
  - [ ] Write failing test for Project.insert.make() constructor
  - [ ] Write failing test for Milestone.insert.make() constructor
  - [ ] Write failing test for Schema.decodeUnknown validation (valid cases)
  - [ ] Write failing test for Schema.decodeUnknown rejection (invalid cases)

  After implementation:
  - [ ] All tests pass
  - [ ] TypeScript inference works without explicit types
  - [ ] Variant schemas (insert, update, select) generate correctly

  **Validation:**
  ```bash
  pnpm test packages/shared/src/schemas/project.test.ts
  pnpm test packages/shared/src/schemas/milestone.test.ts
  pnpm run typecheck
  pnpm run lint

期待される結果：すべてのテストが成功し、型エラーも lint エラーもないこと

逸脱時の方針： 次の場合は直ちに中止してください：

• 実装に、制約に記載されていない依存関係が必要な場合
• テストが失敗し、テストの変更を検討している場合
• 予期しない変更が必要なファイルが 3 つを超える場合
• 記載されたファイル内で型エラーを解決できない場合

### Human Developer Audience (High-Level)

**Structure:**
- **Objective:** Clear statement of what to build with key requirements
- **Style Anchors:** Links to pattern files for reference
- **Key Requirements:** Bullet list of essential features/fields
- **Constraints:** Technology choices and architectural patterns only
- **Success Criteria:** Measurable outcomes without prescribing approach

**Example:**
```yaml
instructions: |
  **Objective:**
  Define Project and Milestone domain models using Model.Class with insert, update,
  and select variants. Include pipeline status enum, priority levels, and proper
  field constraints.

  **Style Anchors:**
  - See `artifacts/style-anchors/SA-002.md` — Model.Class with makeRepository pattern
  - See `artifacts/style-anchors/SA-006.md` — Effect Schema domain types

  **Key Requirements:**

  *Project Model:*
  - Fields: id, slug, name, description, pipelineStatus, assignedPeople (JSON array),
    tags (JSON array), priority, timestamps
  - PipelineStatus enum: intake → analysis → planning → development → review → qa →
    deploy → complete → archived
  - Priority: low, medium, high, critical
  - Use Model.Generated for id, Model.JsonFromString for JSON arrays

  *Milestone Model:*
  - Fields: id, projectId, name, description, status, orderIndex, estimatedDays,
    acceptanceCriteria, timestamps
  - MilestoneStatus: pending, in-progress, blocked, complete

  **Constraints:**
  - Use Model.Class, Schema.Literal, Schema.Struct only
  - Follow SA-002 for variant schemas (insert, update, select)
  - No TypeScript enums or plain interfaces
  - All fields must support runtime validation via Effect Schema

  **Success Criteria:**
  - Models compile with full type inference
  - insert.make(), update.make() constructors available
  - Schema.decodeUnknown validates correctly for valid and invalid inputs
  - Tests pass, no type errors, no lint errors

ハイブリッドを対象とする場合（中程度の詳細）

構成：

• 目的： 構築するものを明確に示します
• スタイルの基準： パターンファイルへのリンク
• 実装方針： 重要な判断点を含む大まかなアプローチ
• 制約： 技術とパターンに関する要件
• 検証： 成功を確認するコマンド

例：

instructions: |
  **Objective:**
  Define Project and Milestone domain models using Model.Class.

  **Style Anchors:**
  - See `artifacts/style-anchors/SA-002.md` — Model.Class pattern
  - See `artifacts/style-anchors/SA-006.md` — Schema.Literal patterns

  **Implementation Approach:**
  1. Create project.ts:
     - Define PipelineStatus as Schema.Literal union covering all stages
     - Define Priority as Schema.Literal("low", "medium", "high", "critical")
     - Define Project using Model.Class with: id (Generated), slug, name, description,
       pipelineStatus, assignedPeople (JsonFromString), tags (JsonFromString),
       priority, timestamps

  2. Create milestone.ts:
     - Define MilestoneStatus as Schema.Literal union
     - Define Milestone using Model.Class with: id, projectId, name, description,
       status, orderIndex, estimatedDays, acceptanceCriteria, timestamps

  3. Update schemas/index.ts to export both schemas

  **Constraints:**
  - Use Model.Class for entities, Schema.Literal for enums
  - Follow SA-002 variant schema pattern (insert, update, select)
  - No TypeScript enum keyword
  - Include JSDoc for exported types

  **Validation:**
  Run tests and typecheck to verify:
  - Model constructors (insert.make, update.make) work correctly
  - Schema.decodeUnknown validates and rejects appropriately
  - Full type inference without explicit type annotations

実装ロジック

タスクを生成する際は、target_audience に基づいて指示の詳細レベルを決定します。

• AI を対象とする場合： すべてのセクションを最大限に詳しく記載します（手順、TDD、逸脱時の方針、具体的な検証）
• 人間を対象とする場合： 目的、スタイルの基準、主要な要件、制約、成功基準のみを記載します
• ハイブリッドを対象とする場合： 目的、スタイルの基準、実装方針（大まかな手順）、制約、検証コマンドを記載します

同じタスク構造とメタデータ（id、name、description、estimate、type、dependencies、files、style_anchor_refs）を、すべての対象ユーザーに使用します。詳細レベルに応じて変わるのは、instructions フィールドの内容のみです。

コードレビュータスクの要件

最終マイルストーンのタスク

重要： すべてのマイルストーンには、最後のタスクとして最終コードレビュータスクを必ず含めてください。このタスクにより、次のマイルストーンに進む前に、品質管理とスタイルの基準との整合性を確保できます。

コードレビュータスクのテンプレート

- id: [milestone]-[last-number]
  name: Comprehensive code review for [milestone-name]
  description: |
    Conduct a thorough code review of all work completed in this milestone.
    Review against style anchors, architectural decisions, and best practices.
    Document findings and create actionable recommendations.
  estimate_minutes: 60
  type: code-review
  dependencies: [all other tasks in this milestone]
  files:
    create:
      - code-reviews/[yyyy-mm-dd]-{n}-code-review.yaml
    modify: []
    touch_only: [all files created/modified in this milestone]
  instructions: |
    **Objective:**
    Review all code, tests, and documentation created or modified during this milestone
    for quality, consistency, and alignment with project standards.

    **Review Checklist:**
    1. **Style Anchor Compliance:**
       - [ ] Code follows patterns defined in style anchors
       - [ ] Naming conventions are consistent
       - [ ] File structure matches established patterns
       - [ ] Import organization follows standards

    2. **Code Quality:**
       - [ ] No code duplication or unnecessary complexity
       - [ ] Clear, meaningful variable and function names
       - [ ] Appropriate use of types (no any, proper generics)
       - [ ] Error handling is comprehensive and consistent
       - [ ] No magic numbers or hardcoded values

    3. **Testing:**
       - [ ] All new code has corresponding tests
       - [ ] Tests follow TDD patterns from style anchors
       - [ ] Edge cases are covered
       - [ ] Test names are descriptive

    4. **Architecture:**
       - [ ] Follows technical requirements decisions
       - [ ] Service patterns are consistent
       - [ ] Dependencies are properly injected
       - [ ] No circular dependencies

    5. **Documentation:**
       - [ ] JSDoc comments for public APIs
       - [ ] Complex logic is explained
       - [ ] README updated if needed
       - [ ] Examples are accurate

    **Review Process:**
    1. Review each file modified in this milestone
    2. Compare against referenced style anchors
    3. Run all quality gates (lint, typecheck, tests)
    4. Document problems with specific file:line references
    5. Provide recommended solutions with code examples
    6. Create code-reviews/[yyyy-mm-dd]-{n}-code-review.yaml

    **Output Format:**
    ```yaml
    milestone: [milestone-id]
    milestone_name: [milestone-name]
    review_date: [yyyy-mm-dd]
    reviewer: claude-code

    summary:
      files_reviewed: [count]
      issues_found: [count]
      critical_issues: [count]
      overall_quality: [excellent|good|fair|needs-improvement]

    style_anchor_compliance:
      - anchor: [path/to/anchor:lines]
        status: [compliant|partial|non-compliant]
        notes: |
          [Specific observations]

    issues:
      - severity: [critical|major|minor]
        category: [style|architecture|testing|documentation|security]
        file: [path:line]
        description: |
          [Clear description of the problem]
        recommendation: |
          [Specific solution with code example if applicable]
        related_anchor: [path/to/anchor:lines]

      - severity: major
        category: testing
        file: src/example.ts:45
        description: |
          Missing error case test for invalid input scenario
        recommendation: |
          Add test case:
          ```typescript
          it.effect("should reject invalid input", () =>
            Effect.gen(function* () {
              const result = yield* service.process({ invalid: true })
              expect(result).toMatchError(ValidationError)
            })
          )
          ```
        related_anchor: test/example.test.ts:20-35

    strengths:
      - [What was done well]
      - [Good patterns observed]

    recommendations:
      - priority: [high|medium|low]
        action: |
          [Specific action to take]
        impact: |
          [Why this matters]

    sign_off:
      ready_for_next_milestone: [yes|no|with-fixes]
      blocking_issues: [list of critical issues that must be fixed]
      notes: |
        [Additional context or observations]
    ```

    **Constraints:**
    - ONLY review code from this milestone
    - Reference specific style anchors when citing issues
    - Provide actionable, specific recommendations
    - Include code examples in recommendations when possible

    **Validation:**
    ```bash
    # Ensure all quality gates pass
    npm run lint
    npm run typecheck
    npm test

    # Verify review file is created
    ls code-reviews/[yyyy-mm-dd]-*.yaml
    ```
    Expected: All quality gates pass, review file exists with complete analysis

    **Drift Policy:**
    If critical issues are found that violate style anchors or architectural
    decisions, mark as blocking and recommend fixes before proceeding to next milestone.

  validation:
    commands:
      - npm run lint
      - npm run typecheck
      - npm test
    expected_output: All quality gates pass
    on_failure: Document failures in review and mark milestone as needing fixes

コードレビューの命名規則

コードレビューのファイル名には、次の要素を含めてください。

• 日付：レビューを実施した日を YYYY-MM-DD 形式で記載します
• 連番：同じ日に複数のレビューを行う場合は番号を増やします
• 形式：code-reviews/YYYY-MM-DD-{n}-code-review.yaml

例：

• code-reviews/2025-01-27-1-code-review.yaml（1 月 27 日の 1 回目のレビュー）
• code-reviews/2025-01-27-2-code-review.yaml（同日の 2 回目のレビュー）
• code-reviews/2025-01-28-1-code-review.yaml（翌日の 1 回目のレビュー）

マイルストーンの進行への統合

1. マイルストーンの計画時：

   • マイルストーンで計画されているタスクの総数を数えます
   • 最後のタスクとしてコードレビュータスクを追加します
   • それ以外のすべてのタスクを依存関係として設定します

2. 開発中：

   • すべての実装タスクを完了します
   • 最終コードレビュータスクを実行します
   • 見つかった阻害要因に対処します
   • マイルストーンの完了を承認します

3. 次のマイルストーンに進む前に：

   • コードレビューの承認が「yes」または「with-fixes」であることを確認します
   • 「with-fixes」の場合は、まず阻害要因に対処します
   • 品質基準を満たした場合にのみ先へ進みます

スタイル基準との統合

スタイルアンカーの読み込み

{base_directory}/artifacts/style-anchors/index.yaml が存在する場合：

1. インデックスを読み込みます：

   Read {base_directory}/artifacts/style-anchors/index.yaml
   

2. アンカーデータを解析します：

   • カテゴリとアンカーを抽出します
   • パターンのマッピング用に usage_matrix を読み込みます
   • タスクタイプとファイルパターンごとのルックアップテーブルを作成します

3. 生成する各タスクについて：

   • タスクタイプ（code/test/docs/config）を判定します
   • タスク内のファイルパターンをアンカーの applies_to ルールと照合します
   • usage_matrix を参照して、推奨されるアンカーを確認します
   • 最も関連性の高いアンカーを上位 2～3 個選択します

スタイルアンカーの選択ロジック

タスクタイプ別：

task.type == "code" → usage_matrix.task_types[type="code"].recommended_anchors
task.type == "test" → usage_matrix.task_types[type="test"].recommended_anchors
task.type == "api"  → usage_matrix.task_types[type="api"].recommended_anchors

ファイルパターン別：

For each anchor in anchors:
  For each pattern in anchor.applies_to.file_patterns:
    If task.files match pattern:
      Include this anchor

マイルストーンタイプ別：

For each anchor in anchors:
  If milestone.type in anchor.applies_to.milestone_types OR "all" in milestone_types:
    Consider this anchor

タスク指示へのアンカーの埋め込み

タスク YAML を生成するときは、スタイルアンカーへの参照を含めます：

instructions: |
  **Objective:**
  [Task objective]

  **Style Anchors:**
  Follow these established patterns:
  - See `artifacts/style-anchors/[anchor-id].md` - [anchor.name]
  - See `artifacts/style-anchors/[anchor-id].md` - [anchor.name]

  Reference files:
  - `[anchor.source.path]:[anchor.source.lines]` - [what it demonstrates]

  **Implementation Steps:**
  1. [Step 1]
  2. [Step 2]

  **Constraints:**
  - ONLY use: [specific libraries/approaches]
  - Follow pattern in: [anchor reference]
  - File scope: ONLY modify listed files

  [Rest of task instructions...]

優れたスタイルアンカーの条件

1. 具体的 - 抽象的な説明ではなく、実際のファイルパスを示します
2. 詳細 - 精度を高める行番号を記載します
3. 網羅的 - コード、テスト、ドキュメントを含みます
4. 最新 - 現在のベストプラクティスを反映しています
5. 模範的 - パターンを正しく示しています

スタイルアンカーが存在しない場合

{base_directory}/artifacts/style-anchors/index.yaml が存在しない場合：

• 警告を表示します：「⚠️ スタイルアンカーが見つかりません。具体的なコード例なしでタスクを生成します。ドリフトのリスクを抑えるため、まず /style-anchors-collection を実行することを検討してください。」
• 代わりに一般的なベストプラクティスを用いてタスクを生成します
• タスク指示にスタイルアンカー用のプレースホルダーを含めます：

  instructions: |
    **Style Anchors:**
    (No style anchors collected. Follow general best practices from technical requirements)
  

品質ゲートの設定

コミット前フック

quality_gates:
  - stage: pre-commit
    commands:
      - npm run lint
      - npm run typecheck
      - npm test
    must_pass: true

CI パイプライン

quality_gates:
  - stage: ci
    commands:
      - npm run lint
      - npm run typecheck
      - npm test
      - npm run test:integration
    coverage_threshold: 80

タスクの完了

quality_gates:
  - stage: task-completion
    criteria:
      - All tests passing
      - No lint errors
      - No type errors
      - Code formatted
      - Documentation updated
      - Commit message follows convention

使用方法

実装計画を生成します：

/implementation-planner [base-directory]

ディレクトリが指定されていない場合は、現在のディレクトリで requirements/business-requirements.yaml を探して自動検出します。

見つからない場合は、ユーザーに「要件ドキュメントはどこにありますか？」と尋ねます。

続行する前に、ユーザーからパスが提供されるまで待ちます。base_directory として保存します。

このスキルでは、次の処理を行います：

1. マイルストーンの順序付け戦略をユーザーに選択してもらいます（フェーズ 0）
2. {base_directory}/requirements/ から両方の要件ドキュメントを読み込み、分析します
3. {base_directory}/artifacts/style-anchors/index.yaml からスタイルアンカーを読み込みます（存在する場合）
4. 選択した戦略に沿って機能に基づく論理的なマイルストーンを特定します
5. 依存関係の順序に従ってマイルストーンを分割します
6. 各マイルストーンについて、次の処理を行います：
   • 詳細なタスク分解を生成します
   • 各タスクの平易な英語による 1～2 文の要約を含む task_summaries マップを作成します（人がすばやく確認できるようにします）
   • タスクタイプとファイルパターンに基づいて、関連するスタイルアンカーへの参照を選択して埋め込みます
   • タスクの規模に関するルールを適用します
   • TDD と品質に関する制約を追加します
   • 最後のタスクとして、最終コードレビュータスクを追加します
7. {base_directory}/implementation/ に milestones.yaml を出力します
8. {base_directory}/implementation/tasks/ に milestone-m*.tasks.yaml ファイルを出力します
9. 生成されている場合は、FEATURE_FLAGS.md と UPDATES.md を {base_directory}/artifacts/ に出力します

計画のベストプラクティス

マイルストーンの特定

1. 基盤から始める - まずインフラストラクチャとツールを整備します
2. 垂直に構築する - 機能をエンドツーエンドで完成させます
3. 依存関係を最小限にする - 可能な場合は並行作業を行います
4. 早期に価値を届ける - 初期のマイルストーンで動作するソフトウェアを提供します
5. 制約を守る - スケジュール、リソース、複雑さを考慮します

タスクの分解

1. 単一責任 - 各タスクで行うことは 1 つにします
2. 明確な依存関係 - タスクの順序を明示します
3. テスト可能 - すべてのタスクに検証基準を設けます
4. 範囲を限定 - 対象ファイルと複雑さを限定します
5. 元に戻せる - 必要なときに簡単に取り消せるようにします

依存関係の管理

1. クリティカルパスを最小限にする - 可能な場合は並列化します
2. 明確なインターフェース - タスク間の契約を明確に定義します
3. 前提条件を文書化する - 各タスクが先行タスクに何を期待するかを記載します
4. 失敗に備える - 依存関係が失敗した場合の対応を計画します

ワークフローの例

入力ファイル

project/
├── business-requirements.yaml
├── technical-requirements.yaml
└── examples/
    ├── service.ts
    ├── service.test.ts
    └── schema.ts

コマンド

/implementation-planner \
  business-requirements.yaml \
  technical-requirements.yaml \
  --style-anchors ./examples

出力ファイル

存在しない場合はディレクトリを作成します：

mkdir -p {base_directory}/implementation/tasks
mkdir -p {base_directory}/artifacts

出力構造：

{base_directory}/
├── implementation/
│   ├── milestones.yaml
│   └── tasks/
│       ├── milestone-m0.tasks.yaml  # Foundation
│       ├── milestone-m1.tasks.yaml  # Core features
│       ├── milestone-m2.tasks.yaml  # Advanced features
│       └── milestone-m3.tasks.yaml  # Polish & release
└── artifacts/
    ├── FEATURE_FLAGS.md     # If generated
    ├── UPDATES.md          # If generated
    └── style-anchor-references.yaml  # If generated

レビューとギャップ分析

マイルストーンとタスクファイルを生成した後、ギャップ分析を自動的に実行します：

完全性チェック

マイルストーンの構造：

• すべてのマイルストーンに明確な成果物がある
• 依存関係が正しい順序になっている
• 循環依存がない
• タイムラインが現実的である
• 成功基準がテスト可能である

タスクの分解：

• すべての要件がタスクで網羅されている
• タスクの規模が30～150分のルールに従っている
• タスク間の依存関係が明示されている
• ファイルの範囲が明確に定義されている
• 各タスクに検証基準がある

タスクの品質：

• 指示が明確で実行可能である
• 制約が明示されている
• コードタスクにTDDチェックリストが含まれている
• 検証コマンドが指定されている
• ドリフトポリシーが記載されている

整合性チェック

ビジネス要件：

• すべての機能要件がタスクに対応付けられている
• 優先順位がビジネス上の優先事項と一致している
• MVPの範囲が明確に定義されている
• 成功基準を検証できる

技術要件：

• アーキテクチャ上の決定が構造に反映されている
• 技術選定が制約によって適用されている
• テスト戦略が実装されている
• セキュリティ要件に対応している

タスク規模の分析

違反を確認します：

• 30分未満のタスク：統合するか、理由を記録する
• 150分を超えるタスク：より小さなタスクに分割する
• クリティカルパスに適切な規模のタスクがある

規模レポートを生成します：

task_sizing_analysis:
  total_tasks: [count]
  average_duration: [minutes]

  too_small:
    - task_id: [id]
      estimate: [minutes]
      rationale: [why it's small]
      recommendation: [merge with X or accept]

  too_large:
    - task_id: [id]
      estimate: [minutes]
      recommendation: [split into X, Y, Z]

  optimal_range:
    count: [number]
    percentage: [%]

依存関係の分析

クリティカルパス：

• マイルストーン間のクリティカルパスを特定する
• 並行実行できる機会を確認する
• 不要な依存関係がないことを確認する
• 依存関係が必要最小限でありながら十分であることを確認する

依存関係グラフの検証：

dependency_analysis:
  critical_path: [m0 → m1 → m3 → m5]
  critical_path_duration: [time]

  parallel_opportunities:
    - [m2 and m3 can run in parallel]
    - [m4 can start after m1]

  dependency_issues:
    - task: [id]
      issue: [unnecessary dependency / missing dependency]
      recommendation: [fix]

ギャップの特定

確認する一般的なギャップ：

• インフラストラクチャタスク（セットアップ、ツール）の不足
• テストタスクの不足
• ドキュメント作成タスクの不足
• エラー処理タスクの不足
• 設定タスクの不足
• デプロイ／リリースタスクの不足
• タスク内の前提条件が文書化されていない
• 新しいパターンのスタイルアンカーが不足している
• ファイルの境界が明確でないタスク
• コンポーネント間の統合タスクが不足している

カバレッジ分析

要件カバレッジマトリックス：

requirement_coverage:
  functional_requirements:
    FR-1: [m1-001, m1-002] # Tasks covering this requirement
    FR-2: [m1-003]
    FR-3: [gap] # Not covered!

  non_functional_requirements:
    performance: [m2-001, m2-002]
    security: [m1-005]
    usability: [gap] # Not covered!

スタイルアンカーの検証

• スタイルアンカーが既存のファイルを参照している（指定されている場合）
• スタイルアンカーが正しいパターンを示している
• 行番号が正確である
• 説明が役に立つ

レビュー結果

包括的なギャップ分析レポートを生成します：

gap_analysis:
  completeness_score: [1-10]
  alignment_score: [1-10]
  feasibility_score: [1-10]

  critical_gaps:
    - category: [category]
      issue: [description]
      impact: [high/medium/low]
      affected_requirements: [FR-1, FR-2, etc]
      recommendation: [how to fix]

  missing_coverage:
    requirements:
      - [FR-X not covered]
      - [NFR-Y not covered]

    task_types:
      - [Missing: integration tests]
      - [Missing: documentation]

  sizing_issues:
    too_small_count: [n]
    too_large_count: [n]
    recommendations: [list]

  dependency_issues:
    - [description]

  strong_areas:
    - [what's well-planned]

  optimization_opportunities:
    - [parallel execution: m2 and m3]
    - [combine tasks: m1-002 and m1-003]

  suggestions:
    - [improvement suggestions]

  ready_for_development: [yes/no/with-modifications]

  estimated_timeline:
    optimistic: [time]
    realistic: [time]
    pessimistic: [time]

重大なギャップが見つかった場合は、次のように尋ねます：

「実装計画にいくつかのギャップを特定しました：

重大な問題：

• [問題1]
• [問題2]

不足しているカバレッジ：

• [要件FR-Xがカバーされていません]
• [統合テストが計画されていません]

次のどれを行いますか？

1. 不足しているタスクを今すぐ追加する（こちらで生成します）
2. 計画を確認して手動で調整する
3. 開発に進む（必要に応じてギャップに対処します）」

開発との統合

マイルストーンの開始

# Load milestone tasks into context
Read milestone-m1.tasks.yaml

# Review style anchors
Read examples/service.ts:10-50
Read examples/service.test.ts:1-40

# Begin first task
# Task m1-001: Implement core service

タスクの完了

1. 検証コマンドを実行する
2. すべての基準を満たしていることを確認する
3. 変更をコミットする
4. タスクのステータスを更新する
5. 次のタスクに進む

ドリフトへの対処

予期しないパターンに遭遇した場合：

1. 停止 - 続行しない
2. 記録 - 何が予期しなかったのかを記録する
3. 元に戻す - 最後に正常と確認できた状態に戻す
4. 報告 - 指示を求める
5. 更新 - 再発を防ぐルールを追加する

例

出力ファイルの例については、references/milestones-example.yaml および references/milestone-tasks-example.yaml を参照してください。