piv-plan-implementation

新しいタスクを計画する

機能：$ARGUMENTS

まず入力を判別する

$ARGUMENTS は、トラッカーチケット（ACC-30 のようなキー、または Jira／Linear／GitHub の課題 URL）か、自由形式の機能説明です。それぞれを判別して、次のように対応します。

• チケット（ABC-123 のようなキー、または課題 URL）：計画を立てる前に、トラッカーから取得します（Jira の場合は Atlassian MCP、GitHub の場合は gh issue view など）。概要、受け入れ条件、チケットごとのコンテキストを確認します。次に、エピックと、エピックにリンクされたアーキテクチャページまでリンクをたどり、そこで決定された内容を引き継ぎます（下記の「引き継ぎ、再検討しない」を参照）。キーだけをもとに計画を立ててはいけません。チケット本文と、そのエピックおよびアーキテクチャが実際の入力です。
• 自由形式の説明：説明をもとに直接計画します（新規開発またはアドホック）。必要に応じて確認の質問をします。

目的

機能リクエストを、体系的なコードベース分析、外部調査、戦略的な計画を通じて、包括的な実装計画に変換します。

基本原則：このフェーズではコードを書きません。AI エージェントが一度の実装で成功できるよう、コンテキストを十分に含んだ実装計画を作成することが目的です。

重要な考え方：コンテキストが重要です。計画には、実装に必要な情報をすべて含める必要があります。パターン、必読資料、ドキュメント、検証コマンドを盛り込み、実行エージェントが初回で成功できるようにします。

引き継ぎ、再検討しない：これはチケットごとの計画です。チケットが、すでにアーキテクチャ上の決定がなされているエピックに属する場合は、リンクされたアーキテクチャページ（チケットのエピックからたどれる、plan-architecture スキルによる Confluence ページなど）、エピックの ## Architecture／## Engineering セクション、またはローカルの architecture.md／engineering-plan.md を先に読み、横断的な決定事項（スタックとバージョン、データモデル、セキュリティ境界、新しいコードを組み込む接続点）はすでに決定済みとして扱います。これらを引き継ぎ、再検討しないでください。チケットレベルで残っている内容、つまり具体的なファイル、踏襲すべきローカルパターン、テストだけを計画します。チケットでエピックレベルの決定を変更する必要が本当にある場合は、黙って方針を逸脱せず、「未解決の質問」に明記してください。

計画プロセス

フェーズ 1：機能の理解

機能の詳細分析：

• 解決しようとしている中心的な問題を抽出する
• ユーザー価値とビジネスへの影響を特定する
• 機能の種類を判断する：新機能／機能強化／リファクタリング／バグ修正
• 複雑さを評価する：低／中／高
• 影響を受けるシステムとコンポーネントを整理する

ユーザーストーリーの形式を作成する。または、ユーザーから提示されたストーリーがある場合は、それを整える：

As a <type of user>
I want to <action/goal>
So that <benefit/value>

フェーズ 2：コードベースの情報収集

専門エージェントを活用し、並行して分析します：

1. プロジェクト構造の分析

• 主な言語、フレームワーク、ランタイムのバージョンを検出します
• ディレクトリ構造とアーキテクチャパターンを把握します
• サービス／コンポーネントの境界と統合ポイントを特定します
• 設定ファイル（pyproject.toml、package.json など）を見つけます
• 環境のセットアップ方法とビルドプロセスを確認します

2. パターンの認識（有用な場合は専門のサブエージェントを使用します）

• コードベース内で類似の実装を検索します
• コーディング規約を特定します：
  • 命名パターン（CamelCase、snake_case、kebab-case）
  • ファイル構成とモジュール構造
  • エラー処理のアプローチ
  • ログのパターンと標準
• 機能のドメインに共通するパターンを抽出します
• 避けるべきアンチパターンを記録します
• プロジェクト固有のルールと規約について CLAUDE.md を確認します

3. 依存関係の分析

• 機能に関連する外部ライブラリを一覧にします
• ライブラリの統合方法を把握します（import、設定を確認します）
• docs/、ai_docs/、.claude/references、または ai-wiki があれば、関連するドキュメントを見つけます
• ライブラリのバージョンと互換性要件を記録します

4. テストパターン

• テストフレームワークと構成（pytest、jest など）を特定します
• 参考用に類似するテスト例を見つけます
• テストの構成（ユニットテストと統合テスト）を把握します
• カバレッジ要件とテスト標準を記録します

5. 統合ポイント

• 更新が必要な既存ファイルを特定します
• 新規作成が必要なファイルと配置場所を決定します
• ルーター／API の登録パターンを把握します
• 該当する場合は、データベース／モデルのパターンを把握します
• 関連する場合は、認証／認可のパターンを特定します

曖昧な点の確認 — GATE：

コードベースの分析が終わったため、未解決の質問は具体的になっています。適切な質問をするのに十分な情報があり、まだ何も書いていないこのタイミングで確認します。GATE の意味は、質問を投稿してから停止することです。このターンを終了し、回答を待ちます。質問と回答を一度に済ませたり、フェーズ 3 に進んだりしてはいけません。

ひとまとまりにして、番号付きで、質問は最大 3～6 個にします。回答の負担を減らすため、それぞれに推奨するデフォルトを添えます（「特に指定がなければ、最初の案に合わせます」）。質問は、分析によって実際に未解決と分かった点だけに絞ります：

1. スコープの境界 — 妥当な読者なら対象範囲内だと思う隣接機能が、実際には対象外であることを確認します。
2. パターンの選択 — 既存の 2 つのパターンがどちらも適合します。それぞれを file:line で示し、どちらに合わせるかを尋ねます。
3. 契約の形 — チケットで示唆されているものの、明記されていない API の表面、ペイロード、またはデータモデルの変更です。
4. 失敗時の動作 — チケットで言及されていないエラー経路で、何が起きるべきかです。
5. 好み — このコードベースに踏襲すべき先例のないライブラリやトレードオフです。
6. 完了条件 — 欠けている受け入れ条件、または確認できない形で書かれた受け入れ条件です。

真に未解決の点がないカテゴリは省略し、質問の数を満たすために質問を捏造してはいけません。チケット、エピック、アーキテクチャドキュメントで本当にすべて解決済みなら、その旨を 1 行で伝えて先に進みます。沈黙は承認と同じではありません。

曖昧な回答の場合： 曖昧な回答は、未確定の具体的な選択肢として言い換えて確認します（「『エラーを適切に処理する』とは、メッセージ付きの 4xx を返すのか、再試行してから 503 を返すのか、ということですか？」）。もう一度だけ尋ねます。曖昧な回答を、確定した計画に格上げしてはいけません。

相手が確認を断った場合（「とにかく書いて」など）：その意向を尊重しますが、何を推測するのかを明示します。未回答の項目はすべて、OPEN QUESTIONS / ASSUMPTIONS に Assumed — <the assumption>, confirm before execution の行として記載し、その項目が影響するタスクには、それを示す **GOTCHA** を付けます。黙って推測してはいけません。

上流ですでに確定している場合： チケット、エピック、またはリンク先のアーキテクチャページですでに回答されている内容は、未解決ではありません。それを引き継ぎ、省略します（「引き継ぎ、再決定しない」を参照）。

フェーズ 3：外部調査とドキュメント

外部調査に役立つ場合は、専門のサブエージェントを活用します：

ドキュメントの収集：

• ライブラリの最新バージョンとベストプラクティスを調査します
• 特定のセクションへのアンカーがある公式ドキュメントを探します
• 実装例やチュートリアルを探します
• よくある落とし穴や既知の問題を特定します
• 破壊的変更や移行ガイドを確認します

技術トレンド：

• 技術スタックに関する現在のベストプラクティスを調査します
• 関連するブログ記事、ガイド、またはケーススタディを探します
• パフォーマンス最適化のパターンを特定します
• セキュリティに関する考慮事項を記録します

調査資料をまとめる：

## Relevant Documentation

- [Library Official Docs](https://example.com/docs#section)
  - Specific feature implementation guide
  - Why: Needed for X functionality
- [Framework Guide](https://example.com/guide#integration)
  - Integration patterns section
  - Why: Shows how to connect components

フェーズ 4：深い戦略的思考

さらに深く検討する点：

• この機能は既存のアーキテクチャにどのように適合しますか？
• 重要な依存関係と処理の順序は何ですか？
• 何が問題になり得ますか？（エッジケース、競合状態、エラー）
• 包括的にテストするにはどうすればよいですか？
• パフォーマンスにどのような影響がありますか？
• セキュリティに関する考慮事項はありますか？
• このアプローチはどの程度保守しやすいですか？

設計上の決定：

• 明確な根拠を示して、代替案から選択します
• 拡張性と将来の変更を考慮して設計します
• 必要に応じて後方互換性を確保する計画を立てます
• スケーラビリティへの影響を考慮します

フェーズ 5：計画の構成を生成

以下の構成で包括的な計画を作成します：

以下は、実装エージェント向けに記入するテンプレートです：

# Feature: <feature-name>

The following plan should be complete, but its important that you validate documentation and codebase patterns and task sanity before you start implementing.

Pay special attention to naming of existing utils types and models. Import from the right files etc.

## Feature Description

<Detailed description of the feature, its purpose, and value to users>

## User Story

As a <type of user>
I want to <action/goal>
So that <benefit/value>

## Problem Statement

<Clearly define the specific problem or opportunity this feature addresses>

## Solution Statement

<Describe the proposed solution approach and how it solves the problem>

## Out of Scope / Non-Goals

<Explicitly bound the work: what this feature does NOT include. Name the things a reasonable reader might assume are in scope but aren't — this is what stops the agent from gold-plating or solving the wrong problem.>

- Not included: <thing> (defer to <later / separate ticket>)
- Not changing: <existing behavior to leave alone>

## Feature Metadata

**Feature Type**: [New Capability/Enhancement/Refactor/Bug Fix]
**Estimated Complexity**: [Low/Medium/High]
**Primary Systems Affected**: [List of main components/services]
**Dependencies**: [External libraries or services required]

## Related Work

<Links between this plan and the work around it. Distinct from CONTEXT REFERENCES below (which lists files/docs to read for *this* implementation) — this is the plan's place in the larger graph.>

**Implements**: <ticket id / link>   ·   **Epic**: <engineering-plan.md path or epic link — if this ticket inherits an epic's engineering plan (see Mission), record it here>

**Back-references** (plans this builds on or inherits decisions from):

- `.claude/plans/<prior-plan>.md` - Why: shares the auth seam / reuses the X service

**Forward-references** (plans that extend or supersede this — append as follow-ups get created):

- (none yet)

---

## CONTEXT REFERENCES

### Relevant Codebase Files IMPORTANT: YOU MUST READ THESE FILES BEFORE IMPLEMENTING!

<List files with line numbers and relevance>

- `path/to/file.py` (lines 15-45) - Why: Contains pattern for X that we'll mirror
- `path/to/model.py` (lines 100-120) - Why: Database model structure to follow
- `path/to/test.py` - Why: Test pattern example

### New Files to Create

- `path/to/new_service.py` - Service implementation for X functionality
- `path/to/new_model.py` - Data model for Y resource
- `tests/path/to/test_new_service.py` - Unit tests for new service

### Relevant Documentation YOU SHOULD READ THESE BEFORE IMPLEMENTING!

- [Documentation Link 1](https://example.com/doc1#section)
  - Specific section: Authentication setup
  - Why: Required for implementing secure endpoints
- [Documentation Link 2](https://example.com/doc2#integration)
  - Specific section: Database integration
  - Why: Shows proper async database patterns

### Patterns to Follow

<Specific patterns extracted from codebase - include actual code examples from the project>

**Naming Conventions:** (for example)

**Error Handling:** (for example)

**Logging Pattern:** (for example)

**Other Relevant Patterns:** (for example)

---

## IMPLEMENTATION PLAN

Phases run **top to bottom by default** — each assumes the phase above it is done. Where that is NOT the true dependency, make it explicit with a `**Depends on:**` line under the phase header, and a `**Independent of:**` line where two phases don't block each other. Independent phases are candidates to run in **parallel** (e.g. separate worktrees / parallel loops). Only annotate where it changes execution order or unlocks parallelism — skip the obvious sequential case.

### Phase 1: Foundation

<Describe foundational work needed before main implementation>

**Tasks:**

- Set up base structures (schemas, types, interfaces)
- Configure necessary dependencies
- Create foundational utilities or helpers

### Phase 2: Core Implementation

**Depends on:** Phase 1 (needs the base schemas/types)

<Describe the main implementation work>

**Tasks:**

- Implement core business logic
- Create service layer components
- Add API endpoints or interfaces
- Implement data models

### Phase 3: Integration

<Describe how feature integrates with existing functionality>

**Tasks:**

- Connect to existing routers/handlers
- Register new components
- Update configuration files
- Add middleware or interceptors if needed

### Phase 4: Testing & Validation

<Describe testing approach>

**Tasks:**

- Implement unit tests for each component
- Create integration tests for feature workflow
- Add edge case tests
- Validate against acceptance criteria

---

## STEP-BY-STEP TASKS

IMPORTANT: Execute every task in order, top to bottom. Each task is atomic and independently testable.

### Task Format Guidelines

Use information-dense keywords for clarity:

- **CREATE**: New files or components
- **UPDATE**: Modify existing files
- **ADD**: Insert new functionality into existing code
- **REMOVE**: Delete deprecated code
- **REFACTOR**: Restructure without changing behavior
- **MIRROR**: Copy pattern from elsewhere in codebase

### {ACTION} {target_file}

- **IMPLEMENT**: {Specific implementation detail}
- **PATTERN**: {Reference to existing pattern - file:line}
- **IMPORTS**: {Required imports and dependencies}
- **GOTCHA**: {Known issues or constraints to avoid}
- **VALIDATE**: `{executable validation command}`
- **SATISFIES**: {which acceptance criterion this task advances — e.g. AC #2 — so every task traces to a criterion}

<Continue with all tasks in dependency order...>

---

## TESTING STRATEGY

<Define testing approach based on project's test framework and patterns discovered during research>

### Unit Tests

<Scope and requirements based on project standards>

Design unit tests with fixtures and assertions following existing testing approaches

### Integration Tests

<Scope and requirements based on project standards>

### Edge Cases

<List specific edge cases that must be tested for this feature>

---

## VALIDATION COMMANDS

<Define validation commands based on project's tools discovered in Phase 2>

Execute every command to ensure zero regressions and 100% feature correctness.

### Level 1: Syntax & Style

<Project-specific linting and formatting commands>

### Level 2: Unit Tests

<Project-specific unit test commands>

### Level 3: Integration Tests

<Project-specific integration test commands>

### Level 4: Manual Validation

<Feature-specific manual testing steps - API calls, UI testing, etc.>

### Level 5: Additional Validation (Optional)

<MCP servers or additional CLI tools if available>

---

## ACCEPTANCE CRITERIA

<List specific, measurable criteria that must be met for completion>

- [ ] Feature implements all specified functionality
- [ ] All validation commands pass with zero errors
- [ ] Unit test coverage meets requirements (80%+)
- [ ] Integration tests verify end-to-end workflows
- [ ] Code follows project conventions and patterns
- [ ] No regressions in existing functionality
- [ ] Documentation is updated (if applicable)
- [ ] Performance meets requirements (if applicable)
- [ ] Security considerations addressed (if applicable)

---

## COMPLETION CHECKLIST

- [ ] All tasks completed in order
- [ ] Each task validation passed immediately
- [ ] All validation commands executed successfully
- [ ] Full test suite passes (unit + integration)
- [ ] No linting or type checking errors
- [ ] Manual testing confirms feature works
- [ ] Acceptance criteria all met
- [ ] Code reviewed for quality and maintainability

---

## OPEN QUESTIONS / ASSUMPTIONS

<Surface anything still uncertain instead of silently guessing. List the assumptions this plan makes, and any question that — if answered differently — would change the plan. Flag unresolved critical questions for the user before execution.>

## NOTES (open canvas)

<No fixed shape. Reason freely here: alternatives you weighed and rejected and why, a tradeoff matrix, a sequencing or rollout risk, a data-flow sketch, open threads, links — whatever serves the plan. The sections above template the plan's *shape* so the trifecta and the implementation agent can consume it; this section keeps your *reasoning* unconstrained. Prose, lists, tables, code blocks all welcome.>

## AMENDMENTS

<Append-only history of changes made to this plan AFTER it was first approved/executed. Leave empty at creation; newest entry at the bottom. Each entry: date — what changed and why.>

- <ISO date> — <what changed and why, e.g. "scope cut: deferred bulk-import to a follow-up ticket after AC review">

出力形式

ファイル名：.claude/plans/{kebab-case-descriptive-name}.md

• {kebab-case-descriptive-name}を、短く内容がわかる機能名に置き換えます
• 例：add-user-authentication.md、implement-search-api.md、refactor-database-layer.md

ディレクトリ：.claude/plans/が存在しない場合は作成します

品質基準

コンテキストの網羅性 ✓

• 必要なパターンをすべて特定し、記録している
• 外部ライブラリの使用方法をリンク付きで記録している
• 統合ポイントを明確にマッピングしている
• 落とし穴とアンチパターンを記録している
• すべてのタスクに実行可能な検証コマンドがある
• フェーズ 2 の確認事項をまとめた質問が行われ、回答されている。または未解決事項がないことが明示的に記録されている

実装の準備 ✓

• 別の開発者が追加のコンテキストなしで実行できる
• タスクが依存関係の順に並んでいる（上から順に実行できる）
• 各タスクが独立したテストを行える単位になっている
• パターンの参照に具体的なファイル名と行番号が含まれている

パターンの一貫性 ✓

• タスクが既存のコードベースの規約に従っている
• 新しいパターンを明確な根拠で正当化している
• 既存のパターンやユーティリティを再発明していない
• テスト方法がプロジェクトの標準に合っている

情報密度 ✓

• 一般的な参照がなく、すべて具体的で実行可能である
• 該当する場合、URLにセクションへのアンカーが含まれている
• タスクの説明にコードベースで使われているキーワードを使用している
• 検証コマンドが対話操作なしで実行できる

成功指標

一度で実装：実行エージェントが追加の調査や確認なしで機能を完成できること。ユーザーが回答する必要のある確認事項は、実行エージェントに先送りせず、フェーズ 2 のゲートで確認します

検証完了：すべてのタスクに、少なくとも 1 つの動作する検証コマンドがあること

コンテキストの充実度：計画が「事前知識なしのテスト」に合格すること。つまり、コードベースに詳しくない人でも、計画の内容だけを使って実装できること

信頼度スコア：初回の試行で実装が成功する確率を #/10 で示します

レポート

計画の作成後、以下を提示します：

• 機能とアプローチの概要
• 作成した計画ファイルの完全なパス
• 複雑さの評価
• 実装に関する主なリスクまたは考慮事項
• 一度で実装が成功する確信度の推定スコア