implementation-planning

実装計画

これは厳格なガイドラインです。 以下のルールに正確に従ってください。

セッションをまたいで保持される実装計画を作成、管理するための手順です。

---

構成

実装計画は、次のディレクトリ構成に従います。

docs/planning/implementation/
  {feature-name}/
    index.md              # Navigation hub with progress tracking
    phase-0-*.md          # Prerequisite/setup phase
    phase-1-*.md          # First implementation phase
    phase-2-*.md          # Second implementation phase
    ...
    post-implementation.md # Validation, handoff, troubleshooting

（計画の保存場所に関するユーザーの設定は、このデフォルトより優先されます。）

フェーズとステップ

フェーズ ＝ 関連する作業をまとめた1つのドキュメント

• 各フェーズには専用のファイルがあります：phase-N-descriptive-name.md
• 各フェーズは500行未満にしてください。これにより、編集対象のコードとともにLLMのコンテキストに収まります
• フェーズは番号順（0、1、2、...）に実行します
• フェーズファイルの名前を変更する場合は、index.md内の参照をすべて更新してください

ステップ ＝ フェーズ内の小さな作業単位

• 各ステップには番号を付けます：Step N.1、Step N.2など（Nはフェーズ番号）
• フェーズ内のステップは順番に実行します
• 各ステップは次の条件を満たす必要があります。
  • 1回の集中した作業（数分程度で、数時間はかかりません）で完了できる
  • 個別にテストできる
  • コミット可能である（コードベースが動作する状態を保てる）

例：

phase-1-api-endpoints.md contains:
  - Step 1.1: Write failing test for GET /items
  - Step 1.2: Run test to verify it fails
  - Step 1.3: Implement GET /items handler
  - Step 1.4: Run test to verify it passes
  - Step 1.5: Commit

phase-2-database-setup.md contains:
  - Step 2.1: Write failing test for table access
  - Step 2.2: Run test to verify it fails
  - Step 2.3: Define DynamoDB table in CDK
  - Step 2.4: Run test to verify it passes
  - Step 2.5: Commit

番号付けのルール

• フェーズ番号は連番にします：0、1、2、3、...
• フェーズ0は常に前提条件／セットアップです
• ステップの形式：{phase}.{step} — フェーズ1のステップは1.1、1.2、1.3
• フェーズ内のステップは順番に実行する必要があります
• 検証と引き継ぎにはpost-implementation.mdを使用します

---

ファイルの対応付け

フェーズ内のステップを定義する前に、作成または変更するファイルと、それぞれの役割を一覧にしてください。これにより、分解方針をあらかじめ確定できます。

**Files:**
- Create: `src/handlers/get-items.ts` — GET /items Lambda handler
- Create: `tests/handlers/get-items.test.ts` — handler tests
- Modify: `infrastructure/api.ts:45-60` — add route

ルール：

• ファイルパスは必ず正確に記載します
• ファイルごとに明確な役割を1つ割り当てます
• 一緒に変更するファイルは同じ場所に配置します
• 既存のコードベースでは、確立されたパターンに従います

---

ステップの内容

ステップには、実行するエージェントに必要な情報をすべて含めてください。プレースホルダーや曖昧な説明を使ってはいけません。

すべてのコードステップに必須の項目：

• 完全なコード（スタブや疑似コードではありません）
• 実行する正確なコマンドと期待される出力
• 次に進む前に確認する内容

次のような記述は計画の失敗にあたります。絶対に書かないでください。

• 「TBD」「TODO」「後で実装する」「詳細を補う」
• 「適切なエラー処理を追加する」／「検証を追加する」
• （実際のテストコードを示さずに）「上記のテストを書く」
• 「Step N.1と同様」（内容を繰り返してください。エージェントが各フェーズを個別に読み込む場合があります）
• 方法を示さず、何をするかだけを説明するステップ

TDDの手順（該当する場合）：

1. 失敗するテストを書く
2. 実行して失敗することを確認する
3. 合格する最小限の実装を書く
4. 実行して合格することを確認する
5. コミットする

すべてのステップでTDDが必要なわけではありません（設定変更、CDKインフラなど）。ただし、可能な場合はコードステップでこの手順に従ってください。

---

インデックスファイルの構成

index.mdは、ナビゲーションと進捗管理を一元化するハブとして機能します。

# {Feature Name} - Implementation Guide

**Last Updated**: YYYY-MM-DD

---

## Quick Navigation

| Phase | Document |
|-------|----------|
| Phase 0 | [Phase Name](./phase-0-*.md) |
| Phase 1 | [Phase Name](./phase-1-*.md) |
| Phase 2 | [Phase Name](./phase-2-*.md) |

---

## Overview

Brief description of what this implementation achieves.

### Prerequisites

Before starting:
- Requirement 1
- Requirement 2

### Implementation Principles

- Key principle 1
- Key principle 2

---

## Progress Tracking

**Current Step**: Phase X, Step X.X - {Step Name}

### Phase 0: {Name}
- [ ] Step 0.1: Description
- [ ] Step 0.2: Description

### Phase 1: {Name}
- [ ] Step 1.1: Description
- [ ] Step 1.2: Description

---

フェーズドキュメントの構成

## Phase {N}: {Phase Name}

**Goal**: Single sentence describing what this phase achieves.

**Files:**
- Create: `exact/path/to/file.ts`
- Modify: `exact/path/to/existing.ts`
- Test: `tests/exact/path/to/test.ts`

---

### Step {N}.1: {Step Name}

**Goal**: What this step accomplishes.

[Full code, exact commands, expected output]

**Verify**: How to confirm this step worked.

**Commit**: `type: description`

---

### Step {N}.2: {Step Name}

...

制限事項：

• フェーズドキュメント全体を500行未満にしてください
• 500行に近づいている場合、そのフェーズは大きすぎます。複数の目的に絞ったフェーズに分割してください
• むやみに分割するのではなく、各フェーズが1つの明確な目標を持つように作業を再構成してください

---

実装ワークフロー

黄金律：常に計画に従う

計画を確認せずにコードを書いてはいけません。

実行エージェントが読み込むのはindex.mdと現在のフェーズだけです。計画全体をコンテキストに含める必要はありません。

1. index.mdを読む — 現在のステップを確認します
2. 現在のフェーズを読み込む — ステップに正確に従います
3. 計画から逸脱する必要がある場合 → 作業を停止し、プランニングモードに入ります

Planning Mode

次の場合に気づいたら：

• 現在のステップを記述どおりに進められない
• より良い方法がある
• 依存関係が不足している
• 前提が誤っていた

ただちに Planning Mode に入ってください：

1. コードの記述を停止する
2. 問題について開発者と話し合う
3. 新しいアプローチに合わせて計画を更新する
4. 後続のステップを確認する — 変更の影響はあるか？
5. 原則に照らして検証する — 中核となる原則やパターンに沿っているか？
6. index.md を更新する — 進捗状況に変更を反映する
7. 実装を再開する前に確認を得る

計画を更新する際は：

• 具体的に記述する：何を、なぜ変更するのかを正確に記録する
• 以前のアプローチを削除しない — superseded（置き換え済み）と明記する
• index.md を最新の状態に保つ

---

Alignment Check

コミット前に各ステップの後で行う、簡易的な健全性チェックです。単独では動作しても、機能の目標に沿わない変更による逸脱を検出します。

Procedure

1. index.md にざっと目を通す — 概要、実装原則、現在のフェーズの目標を確認します。深く読み込むのではなく、手早く確認してください。
2. 未コミットの差分を次の質問に照らして確認する：
   • 目標との整合性：機能の目標に近づいているか、それとも逸脱しているか？
   • アーキテクチャへの適合性：プロジェクトのパターンに沿っているか？
   • アーキテクチャ文書：このプロジェクトにアーキテクチャ文書や設計文書（例：docs/architecture/、ADR、設計上の決定事項）はあるか？ある場合、この変更は記録済みの決定事項に反していないか？変更箇所に関係する文書だけを確認し、すべてを読み直さないでください。
   • スコープの逸脱：このステップで計画にないものを導入していないか？
3. 判定：
   • ✅ 順調 — コミットする。
   • 🟡 軽微な逸脱 — index.md に懸念事項を記録してコミットし、フェーズの終了時に見直す。
   • 🔴 逸脱あり — コミットしない。Planning Mode に入る。

ルール：

• 対象は現在のステップの差分のみであり、コードベース全体ではありません。
• コードレビュー全体ではなく、方向性の確認だけを行います。
• 🟡 の場合は、index.md の該当ステップのチェックボックスに1行の注記を記載する必要があります。

---

Phase Completion

フェーズが完了したら：

• すべてのステップが正常に実行された
• すべての Alignment Check に合格した（🟡 のフラグはすべて解消する）
• すべてのテストが合格した
• 変更がコミットされた
• Index.md が次のフェーズに更新された
• 次のフェーズの前提条件が確認された

---

Scope Check

仕様に複数の独立したサブシステムが含まれる場合は、サブシステムごとに計画を分割することを提案してください。各計画は、それ単独で動作し、テスト可能なソフトウェアを成果物とする必要があります。

---

Creating a New Implementation Plan

1. スコープを確認する — サブシステムごとに計画を1つ作成する
2. index.md を作成する — ナビゲーションと進捗管理を行う
3. フェーズに分割する — 各フェーズは、1つの文書と、焦点を絞った1つの目標で構成する
4. フェーズごとにファイルを割り当てる — 正確なパスと明確な責任を定める
5. フェーズをステップに分割する — 小さく、テスト可能で、コミット可能なステップとし、コードをすべて含める
6. 自己レビューする — 仕様の網羅性、プレースホルダーの確認、フェーズ間の型の一貫性をチェックする
7. 連番を付ける — フェーズ：0、1、2 | ステップ：1.1、1.2 | 2.1、2.2

---

When to Create Implementation Plans

作成する場合：

• 調整が必要な複数日にわたる機能
• 依存関係のある複数フェーズで構成される機能
• 慎重な順序立てが必要な機能
• セッションをまたぐ進捗管理が必要な機能

作成しない場合：

• 単一ファイルの変更
• 単純なバグ修正
• 定常的な保守作業
• 1ステップで完了する作業

---

Reordering Work

フェーズ内のステップを並べ替える場合：

1. フェーズ文書内のステップ番号を更新する
2. index.md 内の参照を更新する
3. 並べ替えによって実行できなくなるステップがないことを確認する

新しいフェーズを挿入する場合：

1. 新しいフェーズファイルを作成する
2. 後続のフェーズファイルと、それぞれの内部ステップ番号を振り直す
3. index.md 内のすべての参照を更新する

---

Progressive Improvement

開発者が、このスキルによって防止されるべきだった振る舞いを修正した場合は、将来同じ指摘を防ぐため、このスキルに追加する具体的な修正案を提案してください。