@kunlv/atdc 1.0.0

package/prompts/1-update.md

@@ -0,0 +1,198 @@
+# prompts/1-update · 需求变更
+
+从此文件读取后，直接开始执行，无需用户再次确认启动。
+
+---
+
+## Step 0：检测目标 change
+
+```bash
+ls openspec/changes/ | grep -v archive
+```
+
+- 无活跃 change → 提示"当前无活跃 change，请先使用 `/atdc:1-spec` 创建需求"，停止。
+- 有多个活跃 change → 让用户指定目标 change 名。
+- 有且只有一个 → 自动选中。
+
+确认目标 change 路径：`openspec/changes/<name>/`
+
+---
+
+## Step 1：读取现有文档
+
+读取目标 change 的全部文档，理解当前状态：
+
+```bash
+CHANGE_NAME="<目标change名>"
+```
+
+读取以下文件：
+- `openspec/changes/$CHANGE_NAME/proposal.md`
+- `openspec/changes/$CHANGE_NAME/design.md`
+- `openspec/changes/$CHANGE_NAME/tasks.md`
+- `openspec/changes/$CHANGE_NAME/specs/` 下所有 spec.md
+- `openspec/changes/$CHANGE_NAME/.progress.json`（如存在）
+
+---
+
+## Step 2：检查执行状态
+
+根据 `.progress.json` 判断 change 当前阶段：
+
+| 状态 | 允许变更 | 处理方式 |
+|------|---------|---------|
+| 未开始执行（无 .progress.json） | 允许 | 直接变更 |
+| 执行中（有 .progress.json） | 需用户确认 | 警告"变更可能影响已完成任务"，等用户确认后继续 |
+| 已归档（在 archive/ 下） | 不允许 | 提示"该 change 已归档，请使用 `/atdc:1-spec` 创建新 change" |
+
+---
+
+## Step 3：澄清变更内容
+
+用户说明需求变更，AI 逐一确认：
+
+1. 变更的具体内容是什么？（新增需求/修改需求/删除需求）
+2. 变更原因？（外部反馈/技术发现/需求偏差/其他）
+3. 变更影响的模块/文件有哪些？
+
+AI 对比现有文档，输出变更摘要：
+
+```
+📋 需求变更摘要：
+
+变更内容：<一句话>
+影响文件：
+- proposal.md：<变更说明>
+- design.md：<变更说明>
+- specs/<模块>/spec.md：<变更说明>
+- tasks.md：<变更说明（新增/删除/修改哪些任务）>
+
+涉及 Verification Checklist 变更：<是/否>
+```
+
+等用户确认后执行更新。
+
+---
+
+## Step 4：判断影响范围 + 精准更新
+
+> **💡 省钱提示**：接下来将批量更新 specs/ + tasks.md + changelog.md 等文档，预计输出 3-10K token。
+> 如果当前使用昂贵模型，建议切到便宜模型后再继续。
+>
+> **模式 C（可选）**：如果你决定切模型，现在暂停，用 `/model <便宜模型>` 切换后回复"继续"。
+> 不切模型则直接开始更新。
+
+根据变更内容，先判断影响哪些文件，只打开受影响的文件：
+
+| 变更类型 | 必更新 | 按需更新 | 跳过 |
+|---------|--------|---------|------|
+| 新增需求 | specs, tasks, checklist | proposal（背景/范围）, design（模块/接口） | - |
+| 修改需求 | specs | proposal, design, tasks, checklist | - |
+| 删除需求 | specs, tasks, checklist | proposal（范围）, design（模块/接口） | - |
+| 接口变更 | design, specs | tasks, checklist | proposal |
+| 技术方案调整 | design | specs, tasks | proposal |
+| 任务拆分/合并 | tasks, checklist | specs | proposal, design |
+
+输出影响判断：
+
+```
+📋 影响范围：
+
+本次变更将更新：
+- [x] proposal.md  ← 原因：<说明>
+- [ ] design.md    （本次无需更新）
+- [x] specs/       ← 原因：<说明>
+- [x] tasks.md     ← 原因：<说明>
+- [x] checklist    ← 原因：<说明>
+
+确认后开始更新。
+```
+
+等用户确认后，只打开勾选的文件，逐一更新。
+
+### 各文件更新规则
+
+**proposal.md**：
+- **新增需求**：补充背景与目标、追加实施范围
+- **修改需求**：更新技术方案、实施范围
+- **删除需求**：从实施范围中移除
+
+**design.md**：
+- **新增需求**：追加模块/接口/数据流
+- **修改需求**：更新接口签名、数据流、ADR
+- **删除需求**：移除对应模块/接口
+
+**specs/<模块>/spec.md**：
+- **新增需求**：追加 SHALL/MUST 条目
+- **修改需求**：更新对应条目
+- **删除需求**：移除对应条目，同步删除 tasks.md 中的关联任务
+
+**tasks.md**：
+- 新增任务：插入到合适位置，更新 Dependencies
+- 删除任务：移除任务，清理其他任务的 Dependencies 引用
+- 修改任务：更新目标/文件/步骤/验证方式
+- 重新编号（如有删除）
+
+**Verification Checklist**：
+重新生成，确保覆盖所有 SHALL/MUST：
+
+```markdown
+## Verification Checklist
+
+- [ ] 系统 SHALL <需求描述> → Task N
+- [ ] 系统 MUST <需求描述> → Task N
+```
+
+---
+
+## Step 5：记录 changelog
+
+在 `openspec/changes/<name>/changelog.md` 追加一条变更记录：
+
+```markdown
+## [YYYY-MM-DD] <变更标题>
+
+**类型**：新增 / 修改 / 删除
+**原因**：<变更原因>
+**内容**：<变更描述>
+
+**影响文件**：
+- `proposal.md`：<具体变更>
+- `design.md`：<具体变更>
+- `specs/<模块>/spec.md`：<具体变更>
+- `tasks.md`：<具体变更（新增/删除/修改）>
+
+**Verification Checklist 变更**：
+- 新增：<条目>
+- 删除：<条目>
+```
+
+---
+
+## Step 6：C1 重新审核暂停
+
+更新完成后，重新评估复杂度（同 1-spec Phase 3a），暂停等待 C1 重新审核：
+
+```
+📋 需求变更完成，等待 C1 重新审核：
+
+变更目录：openspec/changes/<name>/
+├── proposal.md   📝 已更新
+├── design.md     📝 已更新
+├── tasks.md      📝 已更新（N 个任务）
+├── changelog.md  📝 已追加
+└── specs/        📝 已更新（N 个模块）
+
+变更摘要：<一句话>
+
+审核重点：
+1. 变更后的需求完整、无歧义
+2. 接口变更与现有实现兼容
+3. 新增/删除任务的 Dependencies 正确
+4. Verification Checklist 覆盖所有 SHALL/MUST
+
+审核通过后说"执行"或"run"，AI 必须读取 `atdc/prompts/3-impl.md` 进入执行阶段，禁止直接写代码。
+如需质疑检验，说"grill"。
+```
+
+**不得在用户确认前开始写任何代码。**

package/prompts/2-qa.md

@@ -0,0 +1,164 @@
+# prompts/2-qa · 规格质疑检验（Grill 模式）
+
+从此文件读取后，直接开始执行，无需用户再次确认。
+
+可在 C1 审核前后触发，也可通过 `/atdc:grill` 独立触发。
+
+---
+
+## Step 1：确认当前 change 并读取规格
+
+若 `<name>` 未知（独立触发 `/atdc:grill` 时），先执行：
+
+```bash
+ls openspec/changes/ | grep -v archive
+```
+
+取唯一活跃 change，或有多个时询问用户选择哪一个，再**按需精确读取**（不 cat 全文）：
+
+```bash
+# 提取 proposal/design 的关键章节（背景、方案、排除选项）
+grep -A5 "^## 背景\|^## 方案\|^## 排除\|^## 技术方案\|^## Background\|^## Rejected" \
+  openspec/changes/<name>/proposal.md openspec/changes/<name>/design.md
+
+# 提取 tasks.md 的任务标题 + Files 声明 + Verification Checklist
+grep -E "^### [0-9]+\.|^\*\*Files\*\*|^## Verification|^- \[" \
+  openspec/changes/<name>/tasks.md
+
+# 提取所有 spec 的 SHALL/MUST 条目
+grep -h "SHALL\|MUST\|Scenario\|Given\|When\|Then" \
+  openspec/changes/<name>/specs/*/spec.md
+```
+
+> 若上述摘要不足以回答某维度的问题，再用 `sed -n 'N,Mp'` 精确读取对应段落。
+
+---
+
+## Step 2：生成问题清单（内部，不输出给用户）
+
+> **💡 省钱提示**：接下来将逐个追问，预计多轮交互 3-8K token。
+> 如果当前使用昂贵模型，建议切到便宜模型后再继续。
+>
+> **模式 C（可选）**：如果你决定切模型，现在暂停，用 `/model <便宜模型>` 切换后回复"继续"。
+> 不切模型则直接开始。
+
+从以下四个维度**内部生成完整问题清单**（不输出），按严重程度排序：
+
+**验证优先规则**：如果某个问题可以通过探索代码库验证（如"是否已有类似实现"、"接口是否已存在"、"该表是否有唯一索引"），优先用 CodeGraph 或 grep 查代码找答案。能从代码中确认的事实直接从清单中移除，不问用户。
+
+### 2a. 隐性假设
+proposal.md 和 design.md 中没有明说、但实现时必须成立的前提：
+- 依赖的外部服务/接口行为假设
+- 数据格式、字段存在性假设
+- 并发/性能假设
+- 业务规则假设（"用户一定已登录"、"该字段一定非空"等）
+
+### 2b. 边界与遗漏
+spec.md 中覆盖不足的场景：
+- 有 happy path 但缺对应 sad path
+- 缺边界值（空值/零值/超限/最大值）
+- 并发场景（同一资源同时被多个请求操作）
+- 降级场景（依赖服务不可用时的行为）
+- 权限/鉴权边界
+
+### 2c. 技术风险
+design.md 中存在的潜在问题：
+- 引入的新依赖是否稳定
+- 性能瓶颈（N+1 查询、无缓存的高频接口、大事务）
+- 数据一致性风险（跨表操作、缓存与 DB 不同步）
+- 可观测性缺失（无日志、无指标、无报警）
+
+### 2d. Task 与 Spec 对齐缺口
+tasks.md 中每个 task 是否都有 spec 需求对应：
+- 有 task 但 spec 没有对应 SHALL/MUST → "野 task"
+- 有 SHALL/MUST 但没有 task 承接 → "漏实现"
+- task 的 Files 声明是否覆盖了所有需要改动的文件
+
+### 2e. 受影响流程（Blast Radius 质疑）
+design.md 中声明的"涉及文件"是否覆盖了所有受影响的用户流程：
+
+1. 用 `codegraph_impact` 对 design.md 中的关键符号做 1-hop 分析
+2. 识别 blast radius 内是否有 spec 未覆盖的用户流程
+3. 检查：
+   - 是否有被间接影响的入口函数（handler / CLI command / 消费者）未在 proposal 中提及
+   - 是否有共享依赖被修改但下游调用方未考虑
+   - 变更是否影响消息队列消费者、定时任务、Webhook 等异步链路
+
+验证优先规则同样适用：能从 CodeGraph 确认的流程直接标记为已验证，不问用户。只把"确实存在但不确定是否需要处理"的流程纳入追问。
+
+---
+
+## Step 3：逐个追问（grill-me 模式）
+
+按严重程度从高到低，**每次只问一个问题**：
+
+```
+🔍 [维度] <问题>
+
+我的判断：<AI 自己的分析和推荐方案>
+
+你怎么看？
+```
+
+规则：
+- **每个问题附带 AI 推荐方案**：不要只抛问题，给出"如果是我，我会这样处理"的建议
+- **能从代码验证的已经过滤掉了**（Step 2 规则），剩下的是真正需要用户判断的
+- 等用户回答后再问下一个，不得连续追问
+- 用户回答"跳过" → 跳过当前问题，继续下一个
+- 用户回答"够了" → 停止追问，进入 Step 4
+
+每得到一个用户回答，记录到内部清单（问题 + 用户决策 + AI 建议）。
+
+---
+
+## Step 4：输出最终报告
+
+所有问题问完或用户说"够了"后，输出总结：
+
+```
+🔍 Grill 质疑报告 — <change-name>
+
+已验证（代码库确认）：N 条 → 无需处理
+已追问并决策：N 条
+
+### 决策记录
+| # | 维度 | 问题 | 用户决策 | 建议方案 |
+|---|------|------|---------|---------|
+| 1 | 隐性假设 | <问题> | <用户回答摘要> | <AI 推荐> |
+| 2 | 边界遗漏 | <问题> | <用户回答摘要> | <AI 推荐> |
+| ... | | | | |
+
+### 需回改规格的项
+- <需要修改 proposal/specs/tasks 的具体项>
+
+### 已确认可继续
+- <用户确认无需修改的项>
+
+严重问题（需修改规格后才能执行）：N 条
+建议优化（可执行但建议跟进）：N 条
+```
+
+---
+
+## Step 5：等待用户决策
+
+根据报告内容给出明确建议：
+
+- **有严重问题** → 输出：`建议回到规格修改后再执行，说"修改"返回 propose，说"忽略"强制继续。`
+- **仅建议优化** → 输出：`无阻塞问题，可以继续执行。说"执行"或"run"开始实施，说"修改"返回调整规格。`
+- **无问题** → 输出：`规格质量良好，未发现问题。说"执行"或"run"开始实施。`
+
+---
+
+## Step 6（可选）：决策沉淀到项目文档
+
+Grill 过程中产生的决策和术语澄清可持久化，供后续 change 复用：
+
+> 以上 <N> 条决策 + <N> 条术语澄清是否需要沉淀？
+> - 说 `docs` → 执行沉淀：
+>   1. 术语澄清 → 更新 CONTEXT.md 的「领域词汇表」段
+>   2. 重大决策（涉及技术选型/架构方向/排除方案）→ 生成 ADR
+>   3. 边界场景发现 → 更新 CONTEXT.md 的「已知约束」段
+> - 说 `继续` → 跳过沉淀，直接输出完成提示
+
+> **触发条件**：Step 4 报告中「已追问并决策」≥ 1 条时显示；0 条则隐藏。

package/prompts/3-impl-bugfix.md

@@ -0,0 +1,271 @@
+# prompts/3-impl-bugfix · Bugfix 快速流程
+
+从此文件读取后直接开始执行，无需用户再次确认。
+
+> **设计参考**：
+> - [Compound Engineering `/ce-debug`](https://github.com/EveryInc/compound-engineering-plugin)：causal chain gate、assumption audit、trivial fast-path、smart escalation
+> - [Matt Pocock `/diagnosing-bugs`](https://github.com/mattpocock/skills)：feedback loop first、3-5 ranked hypotheses、post-mortem
+
+---
+
+## 🔴 Step -1：规则加载
+
+```
+Read @atdc/reference/guards.md   → R2 TDD 约束
+Read @atdc/reference/tdd.md      → RED→GREEN→REFACTOR 完整循环
+```
+
+> Bugfix 只加载 TDD 相关规则。R5/R6/R8 按需引用。
+
+---
+
+## Step 0：恢复断点
+
+```bash
+cat openspec/changes/<name>/.progress.json 2>/dev/null
+```
+
+- 存在 → 报告进度，询问"从断点继续 / 从头开始"
+- 不存在 → 创建初始 `.progress.json`
+
+---
+
+## Step 0.5：区分 hotfix vs bugfix
+
+> ⚠️ 如果 `.phase-state.json` 中 `mode=hotfix`，不要用这个 prompt。hotfix 是"紧急热修"，可用最简流程。
+> `mode=bugfix` 才是本 prompt 的适用场景：已知 Bug，需要根因分析 + 回归测试。
+
+---
+
+## Phase 0：Build a Feedback Loop
+
+> 目标：构造一个能复现 Bug 的 tight loop。**一条命令，agent-runnable，红色 = Bug 存在，绿色 = 已修复。**
+
+### 0a. 判断是否需要完整 loop
+
+**Trivial fast-path**：明显 Bug（typo/missing import/null deref/off-by-one/单行修复）→ 跳过 Phase 0-1，直接写 `bug-report.md`（一行描述 + 修复），进 Phase 2。
+
+其他情况 → 构造 feedback loop。
+
+### 0b. 构造反馈循环
+
+按优先级尝试：
+
+1. Failing test — 能找到的最小粒度的 test
+2. Curl / HTTP script — 对 dev server 发请求
+3. CLI invocation — 命令行复现
+4. 手动复现步骤 — 前 3 种都构造不出来时才用
+
+**完成标准**：
+- 一条命令可以运行（test 命令 / curl / script）
+- 红色 = Bug 存在（能观察到用户描述的症状）
+- 已实际运行过至少一次（输出证据）
+
+```bash
+# 示例：将 feedback loop 命令写在这里，运行并确认红色
+```
+
+### 0c. 无法构造 loop
+
+停止，输出：
+
+```
+⚠️ 无法构造 feedback loop。请提供：
+(a) 可以复现 Bug 的环境
+(b) 错误日志/堆栈/HAR file
+(c) 手动复现步骤（越详细越好）
+```
+
+---
+
+## Phase 1：Reproduce + Root Cause
+
+### 1a. 复现 Bug
+
+运行 Phase 0 的 feedback loop，确认红色。
+
+### 1b. 最小化
+
+缩小复现场景到最小范围——每次去掉一个元素，重跑 loop，确认仍然红色。保留所有 load-bearing 元素。
+
+### 1c. Assumption Audit
+
+列出你的理解依赖的所有"这必须为真"的信念。每条标记 **verified**（你读过代码/跑过测试/检查过状态）或 **assumed**。
+
+```
+| 假设 | 状态 |
+|------|------|
+| <假设1> | verified |
+| <假设2> | assumed |
+```
+
+### 1d. Hypothesise
+
+生成 3-5 个可证伪假设，按可能性排序。每个假设格式：
+
+```
+#N: <可能性> <假设描述>
+  Evidence: <支撑证据（具体值/行为/输出）>
+  Causal chain: <trigger> → <step1> → ... → <symptom>
+  Prediction: 如果这个假设正确，<在X条件/场景下>应该观察到<Y>
+```
+
+### 1e. Test Hypotheses
+
+从可能性最高的假设开始，一次只验证一个。使用 predication 做区分。
+
+### 1f. Causal Chain Gate
+
+> 🔴 **因果链闸门**：必须能完整解释从 trigger 到 symptom 的全链路，无缺口。否则禁止进入 Phase 2。
+
+### 1g. 写入 bug-report.md
+
+将以上分析写入 `bug-report.md`：
+
+```markdown
+# bug-report: <简短描述>
+
+## 描述
+<Bug 现象、影响>
+
+## 复现步骤
+1. <步骤1>
+2. <步骤2>
+
+## Feedback Loop
+`<命令>`
+
+## 根因分析
+### 因果链
+<trigger> → <step1> → ... → <symptom>
+
+### 假设审计
+<assumption audit 表>
+
+### 验证过的假设
+<#N 假设 + 结论>
+
+## 影响范围
+<涉及模块/用户>
+```
+
+---
+
+## Phase 2：TDD Fix
+
+### 2a. 回归测试（RED）
+
+先写回归测试，确认 Bug 可复现（基于 Phase 0 的 feedback loop）：
+
+```bash
+# 运行回归测试，确认 RED
+```
+
+### 2b. 最小修复（GREEN）
+
+只改根因，不夹带重构/格式化/无关清理。一处改动 = 一个 fix。
+
+```bash
+# 运行回归测试，确认 GREEN
+```
+
+### 2c. REFACTOR
+
+清理冗余代码、改进可读性。不改行为。
+
+### 2d. Smart Escalation
+
+> 修复失败 ≥ 3 次 → 停止盲目重试。诊断为什么失败：
+
+| Pattern | Diagnosis | Next |
+|---------|-----------|------|
+| 修复仍红色 | 根因判断错误 | 回到 Phase 1 |
+| 修复通过但新测试失败 | 修复引入新 Bug | 回退，重新分析影响范围 |
+| 修复间歇性通过 | 非确定性 Bug | 提高 feedback loop 复现率 |
+
+### 2e. 更新 bug-report.md
+
+追加修复信息：
+
+```markdown
+## 修复
+<改动内容和理由>
+
+## 回归测试
+`<测试命令>` — <结果>
+```
+
+---
+
+## Phase 3：Cleanup + Post-mortem
+
+### 3a. 确认修复
+
+```bash
+# 重跑 feedback loop — 确认绿色
+# 运行相关测试套件 — 确认无回归
+```
+
+### 3b. 清理
+
+- 删除所有 debug 日志/throwaway 代码
+- 确认只改了修复需要的文件
+
+### 3c. Post-mortem
+
+写入 `bug-report.md`：
+
+```markdown
+## Post-mortem
+
+### 什么可以预防这个 Bug？
+<本次修复总结>
+
+### 架构改进建议（如有）
+- **问题**：<seam 不足 / 耦合过紧 / 缺少 guard / 缺少测试覆盖>
+- **建议**：<具体的架构改进方向>
+- **优先级**：<建议 / 低 / 中 / 高>
+```
+
+> 架构建议是参考性的，不作为 MUST 要求。
+
+### 3d. 记录 Evidence
+
+```bash
+atdc evidence record <name> task_complete --phase=build --task=bugfix --files="<changed-files>"
+atdc evidence metrics <name> --snapshot
+```
+
+---
+
+## Phase 4：Handoff
+
+### 4a. C3 验证
+
+引用 `@atdc/prompts/4-verify.md`，按 Verification Checklist 逐条验证：
+
+- Feedback loop 绿色（Bug 不再复现）
+- 回归测试通过
+- 无越界文件变更
+
+### 4b. C2 Review + 归档
+
+引用 `@atdc/prompts/5-done.md`，执行归档流程。
+
+归档前记录最终 evidence：
+
+```bash
+atdc evidence record <name> done --phase=archive
+atdc evidence metrics <name> --commit
+atdc evidence canvas <name>
+```
+
+---
+
+## Verification Checklist（由 Agent 从 bug-report.md 提取）
+
+- [ ] Feedback loop 绿色（Bug 不再复现）
+- [ ] 回归测试通过
+- [ ] Causal chain 完整无缺口
+- [ ] Post-mortem 已记录
+- [ ] Evidence 事件已记录