架构优先计划
计划主要回答两个问题：组成部分是什么以及它们如何连接（图），以及它们之间的确切契约是什么（接口）。任务列表是次要的；一个能干的实现者可以从良好的接口中推导出它们。
计划是本地且私人的：~/plans/<YYYY-MM-DD>-<slug>/。Markdown 文件是真理之源。工件是它的一个视图。
1. 理解请求
- 用一两句话重述目标，并明确指出不在范围内的事项。
- 如果需求不明确，请提问（参见下面的提问）。只问那些会改变设计的问题。如果答案打开了新的分支，则再进行一轮。
- 当好的默认值取决于代码已有的功能时，先快速执行第 2 步，这样你的建议就基于仓库而非猜测。
提问
在此步骤、辩论之后以及迭代过程中，每个向用户提出的问题都必须通过 AskUserQuestion 工具进行，绝不能以聊天列表的形式出现。用户应能一键回答大部分问题：
- 预先填充推荐。 让你选择的选项成为第一个，在其标签末尾加上
(推荐)。基于代码库现有模式、AGENTS.md以及保持设计最简单的原则。 - 每道题提供 2-4 个具体选项，每个都是真实的选择，并附带说明它对设计意味着什么（例如“添加迁移”、“重用
useCursorFeed”）。不要添加“其他”选项：该工具会为用户提供自由文本输入。 - 自成一体。 用户可能只看到对话框，因此每个问题都应指明功能和待决定的事项，并简要说明你发现了什么（如果这是驱动问题的原因）。
- 每次调用最多提 4 个问题，每个问题都有一个简短的
header标签（≤12 个字符，例如“存储”、“认证”、“范围”）。将相关问题分组；对剩余问题另做一次调用。 - 仅当选项不互斥时（例如“哪些界面获得此功能？”）才使用
multiSelect。当比较具体工件时（接口草图、模式、ASCII 布局）使用preview。 - 如果你有明确的答案且该选择很容易撤销，则不要提问：做出决定，并将其记录在决策表中。
2. 收集上下文
在 phave-ng（主检出或栈的工作树）中：
- 首先阅读
CLAUDE.md、AGENTS.md和.claude/rules/*。它们编码了你不得违背的决策。 - 找到现有内容：该功能触及或可重用的类型、服务、路由、表、作业和组件。对于广泛扫描，并行运行
Explore代理，每个区域一个，仅保留它们的结论。 - 记录你将扩展的每个现有接口及其
path:line。
3. 评估规模
| 小规模 | 大规模 | |
|---|---|---|
| 信号 | 代码库的一个区域，大致一个 PR（少于 ~400 行），无迁移或只有简单的迁移 | 多个区域，模式变更，新的后台作业，不止一个 PR，或多个人或多个会话 |
| 输出 | 仅 plan.md | plan.md 加上 slices/01-<名称>.md，slices/02-<名称>.md，... |
不要拆分小型工作。 对单个 PR 的变更进行繁琐操作是浪费。
对于大型工作，切割垂直切片：每个切片可独立合并，保持主分支正常工作，并能交付可测试的内容。仅涉及模式的“切片”或“前端切片”不是真正的切片。按依赖关系排序切片，并保持每个切片大致相当于一个 PR。
4. 编写计划
~/plans/<日期>-<摘要>/plan.md：
# <标题>
**状态：** 草稿 | 已批准 | 进行中 | 已完成
**规模：** 小规模 | 大规模（N 个切片）
**仓库/基准：** phave-ng @ <提交>
## 目标
<2-3 句话> · **超出范围：** <要点列表>
## 架构
### 组件
<Mermaid 流程图：现有部分使用普通样式，新部分高亮显示，变更部分标记>
### 关键流程
<Mermaid 时序图，每个重要流程一个，包括主要的错误路径>
### 数据模型
<如果更改了表或列，则使用 Mermaid ER 图；如果某物有生命周期，则使用状态图>
## 接口
<该功能添加或更改的每个契约，以仓库语言的真实代码形式呈现。
每个契约标记为 NEW 或 CHANGED，并附有其目标文件路径。>
- 类型 / 领域模型
- 函数和服务：完整的签名，以及它们抛出的异常
- HTTP / 服务器操作：方法、路径、请求和响应类型、认证、错误代码
- 数据库：表、列、索引、RLS 策略、迁移名称
- 作业 / 事件：名称、负载类型、幂等性、重试策略
- UI 组件：属性以及渲染它们的页面
## 关键设计决策
| 决策 | 考虑的选项 | 选定的 | 原因 |
## 开放问题
- [ ] <问题> — 谁能回答该问题，以及答案会改变什么
## 切片 （仅大规模）
| # | 切片 | 交付内容 | 依赖 | 状态 |
## 计划 （仅小规模）
<有序步骤；每一步包括：其实现的接口、文件以及如何测试>
## 测试策略
<什么是单元测试，什么是在栈上测试（参见 `ai-test` / `manual-test`）>
## 风险
每个 slices/0N-<名称>.md 包含：目标、从 plan.md 实现的接口（链接到它们，不要复制）、文件、有序步骤、验收标准、测试，以及实现说明（留空，由 implement-plan 填写）。
规则：
- 图表使用 Mermaid，每个图表表达一个概念。如果一个图表需要超过约 12 个节点，请拆分它。
- 接口是代码，而不是散文。指明真实的文件。尽可能重用现有类型，并说明这一点。
- 每个可能被合理工程师做出不同选择的决策都必须放入决策表。
- 未知事项放入开放问题，每个问题附带你推荐的答案。不要默默猜测。
5. 批评 / 辩护辩论
使用代理工具并行启动两个代理。为每个代理提供计划路径和要阅读的关键仓库文件，而不是你的结论：
- 批评者：“找出问题所在。设计是否满足目标？接口是否缺失、有漏洞或与代码库模式不一致？切片是否不是真正的垂直切片？是否存在过度设计或指定不足的部分、遗漏的重用、故障模式、迁移风险、权限缺口？报告每个问题并附上具体的修复方案。”
- 辩护者：“为计划的每个选择提出最有力的论据，特别是当明显的替代方案被拒绝时。指出批评者可能攻击的地方，并说明当前设计为何站得住脚。”
然后进行反驳轮次：将另一方的输出发送给每个代理（SendMessage），并要求其接受或坚持每个观点，并说明理由。
你是裁判。对于每个争议点：
- 同意更改：将其应用于
plan.md/ 切片文件。 - 未解决且需要用户参与：将其移至开放问题，并附上你推荐的选项。
- 被拒绝：保留该决策，并在决策表中记录原因。
在 plan.md 末尾添加 ## 辩论总结：观点 → 批评者 → 辩护者 → 解决方案。
6. 作为工件呈现
加载 artifact-design 和用于图表的 artifact-diagramming。发布一页供审查，顺序如下：
- 标题、状态、规模以及一段简介
- 关键设计决策（表格）
- 开放问题：你需要用户提供的内容，置顶且易于查找
- 架构图，渲染好的，而非原始 Mermaid 文本
- 接口，高亮代码形式，按层分组，带有 NEW / CHANGED 徽章
- 切片（大规模）或步骤（小规模）
- 辩论要点：仅那些改变了计划或仍悬而未决的观点
plan.md的本地路径
在聊天中提供链接。然后使用 AskUserQuestion（参见提问）询问开放问题，每个问题都将批评者和辩护者的立场作为选项，并将你的推荐放在首位。
7. 迭代直至获批
用户的回答和评论首先被纳入 plan.md：已回答的问题从开放问题移至决策表。迭代过程中产生的新问题以相同方式提出，使用 AskUserQuestion 并附带推荐的选项。然后重新发布同一个工件（相同的文件路径，以便 URL 保持不变）。当用户批准后，设置状态：已批准并指向他们 implement-plan。
不要在此技能中编写产品代码。