📝 docs(templates): refine superpowers prompt boundaries
This commit is contained in:
@@ -1,51 +1,53 @@
|
||||
# 需求澄清模板
|
||||
|
||||
<!--
|
||||
按需使用：当需求不明确或存在歧义时参考本模板。
|
||||
Vibe-coding 场景下可跳过，直接开始实现。
|
||||
用途：当需求存在歧义时，只补齐会改变实现或验证路径的最小信息。
|
||||
触发：需求不明确、存在两种以上合理实现路径、缺少关键约束时。
|
||||
-->
|
||||
|
||||
## 何时使用
|
||||
|
||||
- 需求描述不明确
|
||||
- 存在多种理解方式
|
||||
- 缺少关键信息
|
||||
- 存在多种合理理解方式
|
||||
- 缺少会改变实现路径的关键信息
|
||||
|
||||
---
|
||||
## 先读
|
||||
|
||||
- `AGENT_RULES.md`
|
||||
- `memory-bank/project-brief.md`
|
||||
- `memory-bank/active-context.md`
|
||||
|
||||
## 规则
|
||||
|
||||
- 每轮最多问 1 个问题
|
||||
- 只问会改变实现或验证路径的问题
|
||||
- 能低风险继续时，优先给出默认项后推进
|
||||
- 不重复询问已能从上下文推断的信息
|
||||
|
||||
## 澄清步骤
|
||||
|
||||
### 1. 复述需求
|
||||
1. 用自己的话复述当前理解
|
||||
2. 识别真正影响实现路径的歧义点
|
||||
3. 只提出 1 个最高价值问题
|
||||
4. 给出推荐默认项和理由
|
||||
|
||||
```text
|
||||
我理解你的需求是：[用自己的话复述]
|
||||
## 输出协议
|
||||
|
||||
```markdown
|
||||
## Current Understanding
|
||||
- ...
|
||||
|
||||
## Open Question
|
||||
- ...
|
||||
|
||||
## Recommended Default
|
||||
- ...
|
||||
```
|
||||
|
||||
### 2. 识别歧义
|
||||
## 停止条件
|
||||
|
||||
- 歧义 1：[描述不明确的地方]
|
||||
- 歧义 2：[可能有多种理解的地方]
|
||||
|
||||
### 3. 提出问题
|
||||
|
||||
> 只问阻塞问题，最多 1–2 个；优先给出选项让用户选择。
|
||||
|
||||
- 这个功能是否包括 [场景 A]？
|
||||
- 当 [条件 X] 时，应该 [行为 Y] 还是 [行为 Z]？
|
||||
|
||||
### 4. 提供选项
|
||||
|
||||
**选项 A**：[方案描述]
|
||||
|
||||
- 优点：...
|
||||
- 缺点：...
|
||||
|
||||
**选项 B**：[方案描述]
|
||||
|
||||
- 优点：...
|
||||
- 缺点：...
|
||||
|
||||
**推荐**：[推荐哪个，为什么]
|
||||
- 已有足够信息可低风险推进时停止提问
|
||||
- 问题不影响实现路径时停止提问
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,59 +1,66 @@
|
||||
# 收尾模板
|
||||
|
||||
<!--
|
||||
用途：一轮实现或一个 Plan 结束后做收尾
|
||||
触发：准备结束当前任务、切换上下文、交付结果前
|
||||
用途：一轮实现或一个 Plan 结束后形成可交付摘要，并把下一轮仍重要的信息留痕。
|
||||
触发：准备结束当前任务、切换上下文、交付结果前。
|
||||
-->
|
||||
|
||||
## 目标
|
||||
|
||||
确认当前任务已经形成可交付结果，并把后续工作所需的信息留痕。
|
||||
|
||||
## 先读
|
||||
|
||||
- `AGENT_RULES.md`
|
||||
- `memory-bank/active-context.md`
|
||||
- `memory-bank/progress.md`
|
||||
|
||||
## 规则
|
||||
|
||||
- 如果任务状态变更，优先通过 `main_loop.py finish` 留痕
|
||||
- 未验证内容必须显式说明
|
||||
- 只写对下一轮仍重要的信息
|
||||
- 不手工改写 `workflow-state` 或 `plan-status` 状态块
|
||||
|
||||
## 执行步骤
|
||||
|
||||
### 1. 核对结果
|
||||
1. 核对已完成项与未完成项
|
||||
2. 核对已运行验证与未运行验证
|
||||
3. 核对 `main_loop.py finish` 是否已经写回 `plan-status`
|
||||
4. 核对 `workflow-state.phase` 是否与当前结果一致
|
||||
5. 如需回写上下文，更新 `active-context`、`progress` 上半部分和 `decisions`
|
||||
6. 输出本轮摘要与下一步
|
||||
|
||||
- 已完成哪些改动？
|
||||
- 哪些内容仍未完成？
|
||||
- 是否存在阻塞、风险或待确认事项？
|
||||
|
||||
### 2. 核对验证
|
||||
|
||||
- 已运行哪些验证？
|
||||
- 哪些验证未运行，原因是什么？
|
||||
- 当前结果是否满足本轮交付标准？
|
||||
|
||||
### 3. 核对状态留痕
|
||||
## 状态留痕复核
|
||||
|
||||
- `main_loop.py finish` 是否已经写回 `plan-status`
|
||||
- `workflow-state.phase` 是否与当前结果一致
|
||||
- 如为代码类执行，`workflow-state` 中是否保留了
|
||||
`executor=executing-plans` 与既定 `constraints`
|
||||
|
||||
### 4. 回写上下文
|
||||
|
||||
- 需要写入 `memory-bank/active-context.md` 的信息
|
||||
- 需要写入 `memory-bank/progress.md` 上半部分摘要
|
||||
- 需要写入 `memory-bank/decisions.md` 的关键决策
|
||||
|
||||
### 5. 输出收尾摘要
|
||||
## 输出协议
|
||||
|
||||
```markdown
|
||||
## 本轮结果
|
||||
## Completed
|
||||
- ...
|
||||
|
||||
- 已完成：...
|
||||
- 未完成：...
|
||||
- 验证：...
|
||||
- 风险 / 待确认：...
|
||||
- 下一步：...
|
||||
## Not Completed
|
||||
- ...
|
||||
|
||||
## Verification
|
||||
- ...
|
||||
|
||||
## Risks
|
||||
- ...
|
||||
|
||||
## Next Steps
|
||||
- ...
|
||||
```
|
||||
|
||||
## 原则
|
||||
## 停止条件
|
||||
|
||||
- 只写对下一轮仍然重要的信息
|
||||
- 未验证的内容必须显式说明
|
||||
- 如果任务状态变更，优先通过 `main_loop.py finish` 留痕
|
||||
- 不手工改写 `workflow-state` 或 `plan-status` 状态块
|
||||
- 如状态未写回，先完成留痕再收尾
|
||||
- 如验证不足以支持交付，停止并标记风险
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Code Review 流程
|
||||
# Code Review 入口
|
||||
|
||||
## 触发场景
|
||||
|
||||
@@ -20,62 +20,38 @@ gh pr view <PR_NUMBER>
|
||||
gh pr diff <PR_NUMBER>
|
||||
```
|
||||
|
||||
## 评审流程
|
||||
## 审查顺序
|
||||
|
||||
逐步执行以下维度。改动简单时可跳过某些步骤。
|
||||
1. 先理解业务目标；目标不明确先要求补足上下文
|
||||
2. 优先审查 bug、风险、回归和缺失测试
|
||||
3. 再审查代码清晰度、KISS 和单一职责
|
||||
4. 最后汇总剩余风险与待确认项
|
||||
|
||||
### 1. 理解业务目标
|
||||
## 规则
|
||||
|
||||
- 能否理解本次改动的业务目标？
|
||||
- 如果目标不明确，先确认再评审。
|
||||
- Findings 优先，按严重度排序
|
||||
- 每条结论必须附文件路径、行号或可复现依据
|
||||
- 没有证据的问题按待确认假设处理
|
||||
- 评审不只看 diff，需结合代码库整体上下文
|
||||
|
||||
### 2. High-level Review
|
||||
## 输出协议
|
||||
|
||||
- 改动是否放在了合适的位置？
|
||||
- 是否尽可能复用已有实现？
|
||||
- 是否有破坏现有设计与逻辑的可能？
|
||||
```markdown
|
||||
## Findings
|
||||
1. [severity] path - issue
|
||||
|
||||
### 3. Bug 检查
|
||||
## Open Questions
|
||||
- ...
|
||||
|
||||
- 是否隐含业务错误、逻辑纰漏或安全问题？
|
||||
- **未修改**的相关联代码是否有遗漏？
|
||||
## Residual Risk
|
||||
- ...
|
||||
```
|
||||
|
||||
### 4. 代码清晰度
|
||||
## 停止条件
|
||||
|
||||
- 逻辑是否简洁易懂？
|
||||
- 命名是否清晰合理？
|
||||
- 一年后再读，是否能轻松理解？
|
||||
- 目标不明时停止并要求补足上下文
|
||||
- 缺少 diff 或无法读取关键上下文时停止并说明
|
||||
|
||||
### 5. KISS 原则
|
||||
---
|
||||
|
||||
- 是否有不必要的复杂度？
|
||||
- 是否有未使用的定义、过多参数？
|
||||
- 是否重复造轮子？
|
||||
|
||||
### 6. 单一职责
|
||||
|
||||
- 每个函数/类是否只做一件事？
|
||||
- 文件/类/方法行数是否合理？
|
||||
|
||||
### 7. 测试覆盖
|
||||
|
||||
- 复杂业务逻辑（含 if/else/for）是否有测试？
|
||||
- 测试是否有效（非空实现）？
|
||||
- 不应过度测试无控制逻辑的代码。
|
||||
|
||||
## 输出
|
||||
|
||||
评审完成后，总结发现的**重点问题**，按严重性排列。
|
||||
|
||||
## AI 与人工的分工
|
||||
|
||||
| 维度 | 负责方 | 说明 |
|
||||
| -------------------------- | ------------- | ------------------------------------- |
|
||||
| Bug、逻辑漏洞、安全问题 | **AI + 人工** | AI 负责初筛与证据收集，结论需人工复核 |
|
||||
| 代码清晰度、KISS、单一职责 | **AI + 人工** | AI 提供候选问题，人工决定是否采纳 |
|
||||
| 架构合理性、业务对齐 | **人工** | AI 反馈少且准确率低，需人工把关 |
|
||||
| 兼容性、历史债务、战略取舍 | **人工** | 依赖背景知识，AI 难以判断 |
|
||||
|
||||
> 规则：AI 结论必须附文件路径、行号或可复现依据；缺少证据时按待确认假设处理。
|
||||
>
|
||||
> 注意：评审不只看 diff，需结合代码库整体上下文做评估。
|
||||
**最后更新**：{{DATE}}
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# 回写记忆模板
|
||||
|
||||
<!--
|
||||
用途：在任务完成、方向切换或发现新规律后更新 memory-bank
|
||||
触发：完成一轮实现、形成新决策、当前焦点变化时
|
||||
用途：在任务完成、方向切换或发现新规律后更新 memory-bank。
|
||||
触发：完成一轮实现、形成新决策、当前焦点变化时。
|
||||
-->
|
||||
|
||||
## 什么时候需要回写
|
||||
@@ -12,12 +12,17 @@
|
||||
- 发现新的系统模式或约束
|
||||
- 做出了值得保留的决策
|
||||
|
||||
## 回写路径
|
||||
## 先读
|
||||
|
||||
- `memory-bank/active-context.md`
|
||||
- `memory-bank/progress.md`
|
||||
- `memory-bank/decisions.md`
|
||||
- `memory-bank/system-patterns.md`
|
||||
|
||||
## 回写目标
|
||||
|
||||
### `memory-bank/active-context.md`
|
||||
|
||||
更新：
|
||||
|
||||
- 当前目标
|
||||
- 最近变更
|
||||
- touched files
|
||||
@@ -25,55 +30,55 @@
|
||||
|
||||
### `memory-bank/progress.md`
|
||||
|
||||
更新：
|
||||
|
||||
- 先读取 `workflow-state`：当前阶段、spec、plan、executor、constraints
|
||||
- 再读取 `plan-status`：当前 Plan 的机器状态
|
||||
- Current Focus
|
||||
- Recent Changes
|
||||
- Next Steps
|
||||
- Open Risks
|
||||
|
||||
只更新上半部分的人类摘要，不修改状态块。
|
||||
|
||||
推荐写法：
|
||||
|
||||
- `Current Focus`：当前阶段结束后，项目现在最重要的工作
|
||||
- `Recent Changes`：本轮实际完成的变更、写回的状态、关键验证结果
|
||||
- `Next Steps`：下一轮最自然的 1-3 个动作
|
||||
- `Open Risks`：仍未解决的阻塞、环境约束、待确认事项
|
||||
|
||||
禁止：
|
||||
|
||||
- 手工改写 `<!-- workflow-state:start/end -->`
|
||||
- 手工改写 `<!-- plan-status:start/end -->`
|
||||
- 把临时聊天内容、未验证猜测写进摘要
|
||||
- 只更新上半部分的人类摘要，不修改状态块
|
||||
|
||||
### `memory-bank/decisions.md`
|
||||
|
||||
仅在出现重要决策时记录 ADR：
|
||||
|
||||
- 为什么这样做
|
||||
- 备选方案是什么
|
||||
- 影响范围是什么
|
||||
|
||||
### `memory-bank/system-patterns.md`
|
||||
|
||||
仅在发现稳定模式时更新：
|
||||
|
||||
- 模块边界
|
||||
- 不变量
|
||||
- 扩展路径
|
||||
- 禁止破坏的约束
|
||||
|
||||
## 原则
|
||||
## 规则
|
||||
|
||||
- 只回写长期有价值的信息
|
||||
- 临时聊天内容不要写进去
|
||||
- 高变化信息放 `active-context`，稳定约束放 `system-patterns`
|
||||
- 高变化信息放 `active-context`，稳定技术模式放 `system-patterns`
|
||||
- 流程规则或项目私有约束变更写入 `AGENT_RULES.local.md`
|
||||
- `progress.md` 的状态块只由 `main_loop.py` 维护
|
||||
- 摘要应与 `workflow-state` / `plan-status` 保持一致
|
||||
|
||||
## 禁止事项
|
||||
|
||||
- 手工改写 `<!-- workflow-state:start/end -->`
|
||||
- 手工改写 `<!-- plan-status:start/end -->`
|
||||
- 把临时聊天内容、未验证猜测写进摘要
|
||||
|
||||
## 输出协议
|
||||
|
||||
```markdown
|
||||
## Updated Files
|
||||
- ...
|
||||
|
||||
## New Context
|
||||
- ...
|
||||
|
||||
## Outstanding Risks
|
||||
- ...
|
||||
```
|
||||
|
||||
## 停止条件
|
||||
|
||||
- 如果没有值得沉淀的信息，则停止并说明
|
||||
|
||||
---
|
||||
|
||||
**最后更新**：{{DATE}}
|
||||
|
||||
@@ -1,38 +1,56 @@
|
||||
# 变更验证模板
|
||||
|
||||
<!--
|
||||
用途：在声明“完成 / 修复 / 可交付”前，明确验证范围与证据
|
||||
触发：代码修改、配置修改、模板修改、规则修改后
|
||||
用途：在声明“完成 / 修复 / 可交付”前，用 fresh run 证明改动成立。
|
||||
触发：代码、配置、模板、规则修改后；准备交付结果前。
|
||||
-->
|
||||
|
||||
## 验证目标
|
||||
|
||||
- 这次改动要证明什么？
|
||||
- 哪些行为必须通过？
|
||||
- 哪些验证本轮不做？
|
||||
- 这次改动要证明什么
|
||||
- 哪些行为必须通过
|
||||
- 哪些验证本轮不做
|
||||
|
||||
## 先读
|
||||
|
||||
- `AGENT_RULES.md`
|
||||
- `memory-bank/progress.md`
|
||||
- 如存在：`docs/prompts/custom/verify.md`
|
||||
|
||||
## 规则
|
||||
|
||||
- 没有证据，不宣称完成
|
||||
- 验证命令必须 fresh run
|
||||
- 局部修改优先局部验证
|
||||
- 不能运行的验证必须写明原因
|
||||
- 不手工改写 `workflow-state` 或 `plan-status` 状态块
|
||||
|
||||
## 验证步骤
|
||||
|
||||
### 1. 语法 / 结构检查
|
||||
1. 做语法或结构检查，确认改动文件可读、可解析
|
||||
2. 运行与本次改动直接相关的验证命令
|
||||
3. 记录命令、结果和关键输出
|
||||
4. 复核 diff 是否只包含预期修改
|
||||
5. 复核 `workflow-state.phase`、`plan-status` 与当前声明一致
|
||||
6. 汇总未覆盖项和剩余风险
|
||||
|
||||
- 确认修改文件可读、可解析、无明显结构错误
|
||||
## 输出协议
|
||||
|
||||
### 2. 定向验证
|
||||
```markdown
|
||||
## Validated
|
||||
- ...
|
||||
|
||||
- 只跑与本次改动直接相关的验证命令
|
||||
- 记录命令、结果和关键输出
|
||||
- 如仓库存在项目私有验证提示词（例如 `docs/prompts/custom/verify.md`），先读取并执行其中的附加约束
|
||||
## Evidence
|
||||
- ...
|
||||
|
||||
```bash
|
||||
{{VERIFY_CMD}}
|
||||
## Not Validated
|
||||
- ...
|
||||
|
||||
## Risks
|
||||
- ...
|
||||
```
|
||||
|
||||
### 3. 差异复核
|
||||
|
||||
- 核对 diff 是否只包含预期修改
|
||||
- 确认没有误删、误改、命名漂移或路径漂移
|
||||
|
||||
### 4. 状态留痕复核
|
||||
## 状态留痕复核
|
||||
|
||||
- `workflow-state.phase` 是否与当前声明一致
|
||||
- `plan-status` 是否已经通过 `main_loop.py finish` 写回
|
||||
@@ -40,29 +58,10 @@
|
||||
`executor=executing-plans`
|
||||
`constraints=karpathy-guidelines,.agents,AGENT_RULES`
|
||||
|
||||
### 5. 剩余风险
|
||||
## 停止条件
|
||||
|
||||
- 本轮未覆盖的验证
|
||||
- 环境限制
|
||||
- 需要人工确认的点
|
||||
|
||||
## 输出格式
|
||||
|
||||
```markdown
|
||||
## 验证结果
|
||||
|
||||
- 已验证：...
|
||||
- 证据：...
|
||||
- 未验证：...
|
||||
- 风险：...
|
||||
```
|
||||
|
||||
## 原则
|
||||
|
||||
- 没有证据，不宣称完成
|
||||
- 局部修改优先局部验证
|
||||
- 不能运行的验证要明确写原因
|
||||
- 不手工改写 `workflow-state` 或 `plan-status` 状态块
|
||||
- 关键验证失败时停止并汇报
|
||||
- 证据不足以支持“完成”结论时停止并汇报
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user