rpiv-loop-plan-feature

> `<rpiv-loop-root>` 解析顺序：环境变量 `RPIV_LOOP_ROOT` -> `CLAUDE_PLUGIN_ROOT` -> 当前插件根目录；均不存在时停止并请用户配置 `RPIV_LOOP_ROOT` 或 `CLAUDE_PLUGIN_ROOT`。 # 规划新任务 ## 功能：$ARGUMENTS ## 使命 通过系统的代码库分析、外部研究和战略规划，将功能请求转换为**全面的实施计划**。 **核心原则**：在此阶段我们**不编写代码**。我们的目标是创建一个上下文丰富的实施计划，使 AI 代理能够一次性成功实施。 **关键理念**：上下文为王。计划必须包含实施所需的所有信息——模式、必读内容、文档、验证命令——以便执行代理在第一次尝试时就能成功。 ## 规划流程 ### 阶段 0：前置检查 **在开始规划前执行状态管理：** 1. 检查是否存在相关的 PRD 文件：`rpiv/requirements/prd-*.md` 2. 如果存在相关 PRD： - 读取该 PRD 文件内容 - 检查是否有 YAML frontmatter - 根据 PRD 当前 status 处理： - `pending` → 更新为 `in-progress`，更新 `updated_at` - `in-progress` → **可能是上次会话中断**。提示用户但继续执行（Plan 创建完成后仍会将 PRD 标记为 completed） - `completed` → PRD 已完成，正常继续 - `superseded` → 警告用户此 PRD 已被取代，询问是否仍要基于它创建 Plan - 记录 PRD 文件路径，用于后续 related_files - **读取 PRD frontmatter 的 `product_types` 字段**（缺失时按 `[code]` 处理，行为与改造前一致）。若含 `skill`，本次规划走 skill 分支：Read `<rpiv-loop-root>/references/skill-authoring/skill-plan-guide.md`，按其指引替换阶段 2 的调研内容、补充结构设计决策、并在阶段 5.6 注入 skill 标准 AC 条目。含 `code` 时下方各阶段原样执行；`[code, skill]` 时两者叠加、互不遮蔽 3. 如果没有 frontmatter（旧文件），跳过状态更新 4. **版本替代检查**：检查是否存在同名特性的旧版本文件（如当前要创建 `plan-{name}-v2.md`，而 `plan-{name}.md` 已存在；或新建的 `feature-{name}-complete.md` 取代旧 todo `todo-{name}-refine.md`）。如果存在旧版本且状态不是 `superseded` / `archived`，**按文件类型分别处理**： - **流程文件（PRD/Plan/validation 各类）**：使用 AskUserQuestion 询问用户是否将旧版本标记为 `superseded`。确认后更新旧文件 frontmatter：`status: superseded`，追加 `superseded_by: {新文件路径}`，更新 `updated_at`；同时建议在新文件反向加 `supersedes: {旧文件路径}` 形成双向闭环。 - **todo 文件**：todo **不支持** `superseded`（hook 会拒）。使用 AskUserQuestion 询问用户是否将被取代的旧 todo **直接归档**：确认后更新旧文件 frontmatter `status: archived`，追加 `superseded_by: {新文件路径}` 作为追溯笔记，更新 `updated_at`。这与 flow_status 对误标 superseded 的 todo 的自动归一化产出一致——就地 `status: archived` 即逻辑终态；archive 技能只归档 `completed`/`superseded`，不会再搬已 `archived` 的文件，故 `archived_at` 可不补、物理位置不强制。 ### 阶段 1：功能理解 **深入功能分析：** - 提取要解决的核心问题 - 识别用户价值和业务影响 - 确定功能类型：新功能/增强/重构/错误修复 - 评估复杂度：低/中/高 - 映射受影响的系统和组件 **创建用户故事格式或完善用户提供的故事：** ``` 作为 <用户类型> 我想要 <行动/目标> 以便 <收益/价值> ``` ### 阶段 2：代码库情报收集 **使用专门的代理和并行分析：** **1. 项目结构分析** - 检测主要语言、框架和运行时版本 - 映射目录结构和架构模式 - 识别服务/组件边界和集成点 - 定位配置文件（pyproject.toml、package.json 等） - 查找环境设置和构建流程 **2. 模式识别**（在有益时使用专门的子代理） - 在代码库中搜索类似的实现 - 识别编码约定： - 命名模式（CamelCase、snake_case、kebab-case） - 文件组织和模块结构 - 错误处理方法 - 日志记录模式和标准 - 提取功能领域的常见模式 - 记录要避免的反模式 - 检查 CLAUDE.md 以了解项目特定的规则和约定 **3. 依赖分析** - 编录与功能相关的外部库 - 了解库的集成方式（检查导入、配置） - 在 docs/、ai_docs/、rpiv/reference 或 ai-wiki（如果可用）中查找相关文档 - 注意库版本和兼容性要求 **4. 测试模式** - 识别测试框架和结构（pytest、jest 等） - 查找类似的测试示例作为参考 - 了解测试组织（单元测试 vs 集成测试） - 注意覆盖率要求和测试标准 **5. 集成点** - 识别需要更新的现有文件 - 确定需要创建的新文件及其位置 - 映射路由器/API 注册模式 - 如果适用，了解数据库/模型模式 - 如果相关，识别身份验证/授权模式 **澄清模糊之处：** - 如果此时需求不清楚，在继续之前询问用户以澄清 - 获取具体的实施偏好（库、方法、模式） - 在继续之前解决架构决策 ### 阶段 3：外部研究与文档 **在有益时使用专门的子代理进行外部研究：** **文档收集：** - 研究最新的库版本和最佳实践 - 查找带有特定章节锚点的官方文档 - 定位实施示例和教程 - 识别常见的陷阱和已知问题 - 检查破坏性更改和迁移指南 **技术趋势：** - 研究技术栈的当前最佳实践 - 查找相关的博客文章、指南或案例研究 - 识别性能优化模式 - 记录安全考虑 **编译研究参考：** ```markdown ## 相关文档 - [库官方文档](https://example.com/docs#section) - 特定功能实施指南 - 原因：需要 X 功能 - [框架指南](https://example.com/guide#integration) - 集成模式部分 - 原因：展示如何连接组件 ``` ### 阶段 4：深度战略思考 **深入思考：** - 此功能如何融入现有架构？ - 关键依赖和操作顺序是什么？ - 可能出现什么问题？（边缘情况、竞争条件、错误） - 如何全面测试？ - 存在哪些性能影响？ - 是否有安全考虑？ - 这种方法的可维护性如何？ **设计决策：** - 在替代方法之间选择，并给出明确的理由 - 为可扩展性和未来修改而设计 - 如果需要，规划向后兼容性 - 考虑可扩展性影响 ### 阶段 5：计划结构生成 **使用以下结构创建全面的计划：** 完整计划模板已按 progressive disclosure 抽出：Read `<rpiv-loop-root>/references/plan-feature/plan-template.md`，按其结构逐节填写。 模板章节骨架（字段细节以模板文件为准）：功能描述 / 用户故事 / 问题陈述 / 解决方案陈述 / 功能元数据 / 上下文参考（必读文件・新建文件・相关文档・要遵循的模式）/ 实施计划（阶段 1-4）/ 逐步任务（DEPENDS_ON・IMPLEMENT・PATTERN・IMPORTS・GOTCHA・PROPAGATE・VALIDATE 字段）/ 测试策略 / 验证命令（级别 1-5）/ 验收标准 / 完成检查清单 / 备注 ### 阶段 5.6：产出 acceptance.yaml（AC 对账的权威数据源） **目的**：与 plan 文件同步生成结构化的 Gherkin 风格验收判据（AC），作为 `validate` 填写证据、`delivery-report` 门禁校验的唯一真实源。 **文件路径**：`rpiv/validation/<feature>/acceptance.yaml`（若目录不存在需一并创建）。 **plan 阶段职责**（本 SKILL 只写以下字段）： - `id`：全文件唯一，格式 `AC-NNN`（三位数字），**禁止重复** - `given` / `when` / `then`：严格按 Gherkin 三段式书写 - `verification_method`：具体到命令 / 测试文件路径 / 脚本名，禁止"人工检查"这种泛词 - `blocking`：`true` 表示强约束项，交付前必须 passed 或 not_applicable；`false` 为软性目标 - `notes`（可选）：额外上下文 **validate 阶段后续职责**（不要在 plan 阶段预填）： - `evidence`：执行 verification_method 后的具体证据（路径:行号 / 日志片段 / 截图文件名） - `status`：`passed` / `failed` / `not_applicable`（初始留空，由 QA 翻状态） **delivery-report 阶段职责**：只读 `acceptance.yaml`，**禁止修改任何字段**。`check_acceptance.py` 通过 `uv run --no-project python <rpiv-loop-root>/tools/check_acceptance.py <feature>` 校验后以退出码决定能否出具交付报告。 **质量门（plan 阶段自检清单）**： - [ ] `acceptance.yaml` 条目数 ≥ 3 - [ ] 所有 `id` 唯一且连号 - [ ] 所有 `verification_method` 非空且具体 - [ ] 每个 `blocking: true` 项都配了可执行的 `verification_method` - [ ] `given/when/then` 用祈使句描述系统行为，禁止"用户应该感觉良好"这种无法验证的措辞 **YAML 示例**：Read `<rpiv-loop-root>/references/plan-feature/acceptance-template-example.md`（最小可用示例，复制后替换内容）；空白骨架另见 `<rpiv-loop-root>/tools/acceptance_template.yaml`，根键统一用 `criteria:`。 **产出约束**： - 本章节要求 `acceptance.yaml` 与 plan.md **同一会话内产出**，缺一不可 - plan.md 的「验收标准」章节可保留对 plan 自身的 checklist，但强约束 AC 的**唯一权威源**是 `acceptance.yaml` - 与 delivery-report 的 `check_acceptance.py` 构成闭环：plan 写骨架 → validate 翻状态 → delivery-report 校验通过才放行 --- ## 输出格式 **文件名**：`rpiv/plans/plan-{kebab-case-feature-name}.md` - 将 `{kebab-case-feature-name}` 替换为简短、描述性的功能名称 - 示例：`plan-user-authentication.md`、`plan-search-api.md`、`plan-database-refactor.md` **目录**：如果不存在，创建 `rpiv/plans/` ### 文件格式 文件必须包含 YAML frontmatter 和内容： ```markdown --- description: "功能实施计划: {feature-name}" status: pending created_at: {YYYY-MM-DDTHH:MM:SS} updated_at: {YYYY-MM-DDTHH:MM:SS} archived_at: null related_files: - rpiv/requirements/prd-{feature-name}.md # 如果存在相关 PRD --- # {计划内容} ``` **Frontmatter 字段说明：** - `description`: 文件描述 - `status`: 文件状态，新创建时固定为 `pending` - `created_at`: 创建时间戳，ISO 8601 格式 - `updated_at`: 更新时间戳，创建时与 created_at 相同 - `archived_at`: 归档时间戳，创建时固定为 `null` - `related_files`: 关联文件列表（如果存在相关 PRD 则添加） ### 完成后续 计划创建完成后： 1. 如果在前置检查中更新了 PRD 的状态，将其 status 从 `in-progress` 改为 `completed` 2. 更新 PRD 的 `updated_at` 时间戳 3. 提示用户："计划已创建。相关 PRD 已标记为完成。" 4. 建议下一步："建议 `/clear` 后执行 `/rpiv-loop:execute rpiv/plans/plan-{feature-name}.md` 开始实施。" ## 质量标准 ### 上下文完整性 ✓ - [ ] 所有必要的模式已识别和记录 - [ ] 外部库使用已记录并附有链接 - [ ] 集成点已清晰映射 - [ ] 已捕获陷阱和反模式 - [ ] 每个任务都有可执行的验证命令 ### 实施就绪 ✓ - [ ] 其他开发者可以在没有额外上下文的情况下执行 - [ ] 任务按依赖顺序排列（可以从上到下执行） - [ ] 每个任务都是原子的且可独立测试 - [ ] 模式引用包括特定的文件:行号 ### 模式一致性 ✓ - [ ] 任务遵循现有代码库约定 - [ ] 新模式有明确的理由说明 - [ ] 没有重新发明现有的模式或工具 - [ ] 测试方法符合项目标准 ### 信息密度 ✓ - [ ] 无通用引用（全部具体且可操作） - [ ] URL 在适用时包含章节锚点 - [ ] 任务描述使用代码库关键字 - [ ] 验证命令是非交互式可执行的 ## 成功指标 **一次性实施**：执行代理可以在没有额外研究或澄清的情况下完成功能 **验证完整**：每个任务至少有一个有效的验证命令 **上下文丰富**：计划通过"无先验知识测试" - 不熟悉代码库的人可以仅使用计划内容进行实施 **信心分数**：#/10 表示执行将在第一次尝试时成功 ## 报告 创建计划后，提供： - 功能和方法的摘要 - 创建的计划文件的完整路径 - 复杂度评估 - 关键实施风险或考虑因素 - 一次性成功的估计信心分数