piv-plan-implementation

规划新任务

功能：$ARGUMENTS

首先解析输入

$ARGUMENTS 可以是跟踪器工单（例如 ACC-30 这样的键，或 Jira / Linear / GitHub 问题 URL），也可以是自由格式的功能描述。请区分两者并分别处理：

• 工单（例如 ABC-123 这样的键，或问题 URL）：规划前先从跟踪器获取工单（Jira 通过 Atlassian MCP，GitHub 通过 gh issue view 等）。阅读其摘要、验收标准和工单上下文。然后沿着工单中的链接一路查到 Epic 及其关联的架构页面（Confluence 通过 Atlassian MCP），并继承其中的决策（见下文“继承决策，而非重新决策”）。切勿只根据键来规划；工单正文及其 Epic 和架构才是真正的输入。
• 自由格式的描述：直接据此规划（全新开发或临时需求），并根据需要提出澄清问题。

使命

通过系统地分析代码库、开展外部研究并制定策略，将功能请求转化为全面的实现计划。

核心原则：本阶段不编写代码。我们的目标是制定一份上下文丰富的实现计划，让 AI Agent 能够一次性成功完成实现。

关键理念：上下文至关重要。计划必须包含实现所需的所有信息，包括模式、必读内容、文档和验证命令，从而确保执行 Agent 首次尝试即可成功。

继承决策，而非重新决策：这是一个针对单个工单的计划。如果工单属于某个已有架构决策的 Epic——例如关联的架构页面（如通过工单所属 Epic 找到的 plan-architecture 技能生成的 Confluence 页面）、Epic 中的 ## Architecture / ## Engineering 部分，或本地的 architecture.md / engineering-plan.md——请先阅读，并将其中的跨领域决策（技术栈及版本、数据模型、安全边界、新代码接入的部分）视为已经确定。继承这些决策，不要重新讨论。只规划工单层面尚未确定的内容：具体文件、需要遵循的本地模式和测试。如果工单确实需要打破 Epic 层面的决策，请在“待解决问题”中标出，而不是悄然偏离。

规划流程

阶段 1：理解功能

深入分析功能：

• 提取要解决的核心问题
• 确定用户价值和业务影响
• 判断功能类型：新能力 / 功能增强 / 重构 / 错误修复
• 评估复杂度：低 / 中 / 高
• 梳理受影响的系统和组件

创建用户故事格式，或优化用户提供的故事：

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

阶段 2：代码库情报收集

使用专用 Agent 并行分析：

1. 项目结构分析

• 检测主要语言、框架和运行时版本
• 梳理目录结构和架构模式
• 确定服务／组件边界和集成点
• 定位配置文件（pyproject.toml、package.json 等）
• 查找环境设置和构建流程

2. 模式识别（适用时使用专用子 Agent）

• 在代码库中搜索类似实现
• 确定编码规范：
  • 命名模式（CamelCase、snake_case、kebab-case）
  • 文件组织和模块结构
  • 错误处理方式
  • 日志记录模式和标准
• 提取该功能领域的通用模式
• 记录需要避免的反模式
• 检查 CLAUDE.md 中的项目专属规则和规范

3. 依赖分析

• 汇总与该功能相关的外部库
• 了解库的集成方式（检查导入和配置）
• 查找 docs/、ai_docs/、.claude/references 或 ai-wiki 中的相关文档（如果存在）
• 记录库版本和兼容性要求

4. 测试模式

• 确定测试框架和结构（pytest、jest 等）
• 查找类似的测试示例以供参考
• 了解测试组织方式（单元测试与集成测试）
• 记录覆盖率要求和测试标准

5. 集成点

• 确定需要更新的现有文件
• 确定需要创建的新文件及其位置
• 梳理路由器／API 注册模式
• 了解数据库／模型模式（如适用）
• 确定身份验证／授权模式（如相关）

澄清模糊之处 — GATE：

代码库分析已经完成，因此未解决的问题现在是具体的。这是唯一一个你了解得足够多、能够妥善提问，同时又尚未编写任何内容的时刻。GATE 表示：提出问题，然后停止。结束本轮并等待答复。不要在同一轮中既提问又作答，也不要直接进入阶段 3。

将问题集中在一组中，编号列出，最多 3-6 个；每个问题都附上建议默认选项，以便轻松回答（“除非你另有说明，否则我会采用第一个选项”）。问题只能针对分析后确实尚未明确的事项：

1. 范围边界——合理的读者会认为属于范围的相邻事项。确认它不在范围内。
2. 模式分歧——现有的两种模式都适用。列出两者的 file:line，并询问应该参照哪一种。
3. 契约形式——工单暗示了但没有明确说明的 API 表面、负载或数据模型变更。
4. 失败行为——工单没有说明的错误路径应如何处理。
5. 偏好——代码库中没有可供沿用先例的库或权衡方案。
6. 完成标准——缺失或无法验证的验收标准。

如果某个类别确实没有未解决的问题，就跳过；不要为了凑数而编造问题。如果工单、其 Epic 和架构文档确实已经明确了所有事项，就用一句话说明并继续。沉默不等于许可。

模糊答复： 对模糊答复进行复述，指出它留下的具体选择（“‘妥善处理错误’——返回带有消息的 4xx，还是重试后返回 503？”），然后再问一次。绝不要把模糊答复擅自升级为确定方案。

如果对方拒绝回答（“直接写吧”）：尊重这一要求，但说明你的猜测是什么。每个未答复事项都要在 OPEN QUESTIONS / ASSUMPTIONS 中列为一行 Assumed — <the assumption>, confirm before execution，受其影响的任务都要注明一个点名该事项的 **GOTCHA**。绝不要默默猜测。

上游已明确的事项： 工单、其 Epic 或链接的架构页面已经回答的内容，不属于未解决事项。沿用现有结论并跳过（参见“Inherit, don't re-decide”）。

阶段 3：外部研究与文档

在有助于外部研究时，使用专用子 Agent：

收集文档：

• 调研最新的库版本和最佳实践
• 查找带有特定章节锚点的官方文档
• 查找实现示例和教程
• 确定常见陷阱和已知问题
• 检查破坏性变更和迁移指南

技术趋势：

• 调研该技术栈的当前最佳实践
• 查找相关的博客文章、指南或案例研究
• 确定性能优化模式
• 记录安全注意事项

汇总研究参考资料：

## 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：生成计划结构

按照以下结构创建全面的计划：

以下内容是供你填写并交给实现 Agent 的模板：

# 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 包含章节锚点
• 任务描述使用代码库中的关键词
• 验证命令可非交互式执行

成功指标

一次性实施：执行 Agent 无需额外研究或澄清即可完成该功能——用户欠缺的澄清应在阶段 2 的关卡中解决，而不是留给执行 Agent

验证完整：每项任务至少有一条有效的验证命令

上下文充分：该计划通过“无先验知识测试”——不熟悉代码库的人仅凭计划内容即可完成实施

信心评分：首次尝试成功的信心为 #/10

报告

创建计划后，请提供：

• 功能和方案摘要
• 创建的计划文件的完整路径
• 复杂度评估
• 主要实施风险或注意事项
• 一次性成功的预估信心评分