📝 docs(templates): refine superpowers prompt boundaries
This commit is contained in:
parent
25d895d8b3
commit
61afff9d48
|
|
@ -22,6 +22,7 @@ tags
|
|||
reports/
|
||||
.worktrees/
|
||||
tmp/
|
||||
docs/superpowers/
|
||||
|
||||
scripts/__pycache__
|
||||
tests/__pycache__
|
||||
|
|
|
|||
15
README.md
15
README.md
|
|
@ -41,9 +41,9 @@ Playbook：工程规范与代理规则合集，当前覆盖：
|
|||
`templates/` 目录除了语言配置模板外，还包含 AI 代理工作环境的项目架构模板：
|
||||
|
||||
- `templates/memory-bank/`：项目上下文文档模板（project-brief、tech-context、system-patterns、active-context、progress、decisions）
|
||||
- `templates/prompts/`：工作流入口模板（agent-behavior、clarify、verify-change、close-task、update-memory、code-review）
|
||||
- `templates/AGENTS.template.md`：路由中心模板（项目主入口）
|
||||
- `templates/AGENT_RULES.template.md`：执行流程模板
|
||||
- `templates/prompts/`：任务入口模板（agent-behavior、clarify、verify-change、close-task、update-memory、code-review），不是流程权威
|
||||
- `templates/AGENTS.template.md`：入口导航模板（项目主入口）
|
||||
- `templates/AGENT_RULES.template.md`：superpowers-first 执行规则模板
|
||||
|
||||
### 快速部署
|
||||
|
||||
|
|
@ -95,6 +95,14 @@ python <deploy_root>/scripts/playbook.py \
|
|||
`memory-bank/progress.md`。
|
||||
真正执行 Plan 仍然走 `main_loop.py claim/finish`。
|
||||
|
||||
完整主链只在 `templates/AGENT_RULES.template.md` 定义，这里不重复展开。
|
||||
如果项目采用 `superpowers`：
|
||||
|
||||
- 设计产物落到 `docs/superpowers/specs/`
|
||||
- 计划产物落到 `docs/superpowers/plans/`
|
||||
- 状态留痕通过 `playbook.py -record-spec/-record-plan` 与
|
||||
`main_loop.py claim/finish` 维护
|
||||
|
||||
详见：`templates/README.md`
|
||||
|
||||
## rulesets/（规则集模板库 - 三层架构）
|
||||
|
|
@ -271,6 +279,7 @@ git commit -m ":package: deps(playbook): add tsl standards"
|
|||
```
|
||||
|
||||
2. 在目标项目根创建 `playbook.toml`，并用 `deploy_root` 指定项目内的部署根。例如：
|
||||
|
||||
- `project_root` 写目标项目根目录。
|
||||
- `deploy_root` 写目标项目内的相对路径。
|
||||
- 不要把外部 clone 的路径（如 `/opt/playbook`）写进 `deploy_root`；那只是你执行脚本的位置。
|
||||
|
|
|
|||
|
|
@ -21,9 +21,9 @@
|
|||
- [memory-bank/active-context.md](memory-bank/active-context.md) - 当前上下文
|
||||
- [memory-bank/progress.md](memory-bank/progress.md) - 进度追踪
|
||||
|
||||
### 工作流入口
|
||||
### 任务入口
|
||||
|
||||
- [docs/prompts/README.md](docs/prompts/README.md) - 提示词与流程入口
|
||||
- [docs/prompts/README.md](docs/prompts/README.md) - 提示词与任务入口
|
||||
<!-- playbook:templates:end -->
|
||||
|
||||
<!-- playbook:framework:end -->
|
||||
|
|
|
|||
|
|
@ -2,6 +2,10 @@
|
|||
|
||||
目的：为本仓库提供稳定的执行流程与行为规范。
|
||||
|
||||
本文件是项目内唯一流程约束中心；`docs/superpowers/`
|
||||
是唯一设计与计划产物中心；执行状态统一写回
|
||||
`memory-bank/progress.md`。
|
||||
|
||||
## 优先级
|
||||
|
||||
1. 系统/开发者指令与安全约束
|
||||
|
|
|
|||
|
|
@ -1,14 +1,15 @@
|
|||
# 项目架构模板
|
||||
|
||||
本目录包含项目架构的模板文件，用于快速初始化新项目的 AI 代理工作环境。
|
||||
本目录包含以 `superpowers` 为基石的项目模板，用于快速初始化新项目的
|
||||
AI 代理工作环境。
|
||||
|
||||
## 目录结构
|
||||
|
||||
```text
|
||||
templates/
|
||||
├── README.md # 本文件
|
||||
├── AGENTS.template.md # 路由中心模板
|
||||
├── AGENT_RULES.template.md # 执行流程模板
|
||||
├── AGENTS.template.md # 入口导航模板
|
||||
├── AGENT_RULES.template.md # superpowers-first 执行规则模板
|
||||
├── memory-bank/ # 项目上下文模板
|
||||
│ ├── project-brief.template.md
|
||||
│ ├── tech-context.template.md
|
||||
|
|
@ -16,7 +17,7 @@ templates/
|
|||
│ ├── active-context.template.md
|
||||
│ ├── progress.template.md
|
||||
│ └── decisions.template.md
|
||||
├── prompts/ # 提示词库模板
|
||||
├── prompts/ # 任务入口模板（不是流程权威）
|
||||
│ ├── README.md
|
||||
│ ├── system/
|
||||
│ │ └── agent-behavior.template.md
|
||||
|
|
@ -48,6 +49,7 @@ templates/
|
|||
|
||||
- **会同步更新的框架模板**
|
||||
- `AGENT_RULES.md`
|
||||
- `docs/prompts/README.md`
|
||||
- `docs/prompts/system/*.md`
|
||||
- `docs/prompts/coding/*.md`
|
||||
- `AGENTS.md`、`CLAUDE.md`（按 playbook 区块更新）
|
||||
|
|
@ -69,6 +71,8 @@ templates/
|
|||
不会被 playbook 删除。
|
||||
- `CLAUDE.md` 如已有 playbook 区块则更新；如未引用
|
||||
`@AGENTS.md` 则追加；如已手工引用 `@AGENTS.md` 则跳过。
|
||||
- 流程约束统一收敛到 `AGENT_RULES.md`；`docs/prompts/`
|
||||
只负责把代理导向正确的任务入口。
|
||||
|
||||
## 快速部署
|
||||
|
||||
|
|
@ -158,6 +162,12 @@ force = true
|
|||
|
||||
### docs/superpowers 命名约定
|
||||
|
||||
`docs/superpowers/` 统一承载设计稿和实施计划：
|
||||
|
||||
- 设计只落到 `specs/`
|
||||
- 计划只落到 `plans/`
|
||||
- 执行状态只写回 `memory-bank/progress.md`
|
||||
|
||||
为与 thirdparty `superpowers` 上游当前工作流对齐，建议统一使用：
|
||||
|
||||
- `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`：
|
||||
|
|
@ -169,28 +179,20 @@ force = true
|
|||
|
||||
### 生命周期总览
|
||||
|
||||
```text
|
||||
需求澄清
|
||||
-> using-superpowers
|
||||
-> brainstorming
|
||||
-> docs/superpowers/specs/*.md
|
||||
-> playbook.py -record-spec
|
||||
-> writing-plans
|
||||
-> docs/superpowers/plans/*.md
|
||||
-> playbook.py -record-plan
|
||||
-> main_loop.py claim
|
||||
-> executing-plans
|
||||
-> [代码类任务] + karpathy-guidelines + .agents + AGENT_RULES
|
||||
-> main_loop.py finish
|
||||
-> update-memory / close-task
|
||||
```
|
||||
完整主链只在 `AGENT_RULES.template.md` 定义；本文件不重复展开。
|
||||
这里仅说明职责分层：
|
||||
|
||||
- `docs/prompts/`：任务入口层，只负责把代理导向正确入口
|
||||
- `docs/superpowers/specs/`：设计稿
|
||||
- `docs/superpowers/plans/`：实施计划与主执行输入
|
||||
- `memory-bank/progress.md`：执行状态留痕
|
||||
|
||||
### 部署后的目录结构
|
||||
|
||||
```text
|
||||
project/
|
||||
├── AGENTS.md # 路由中心（Codex 入口）
|
||||
├── AGENT_RULES.md # 执行流程
|
||||
├── AGENTS.md # 入口导航（Codex 入口）
|
||||
├── AGENT_RULES.md # superpowers-first 执行规则
|
||||
├── AGENT_RULES.local.md # 项目私有规则（自动创建，项目维护）
|
||||
├── CLAUDE.md # Claude Code 入口（按规则维护/追加 playbook 区块）
|
||||
├── memory-bank/ # 项目上下文
|
||||
|
|
@ -201,7 +203,7 @@ project/
|
|||
│ ├── progress.md
|
||||
│ └── decisions.md
|
||||
└── docs/
|
||||
├── prompts/ # 提示词库
|
||||
├── prompts/ # 任务入口层
|
||||
│ ├── README.md
|
||||
│ ├── system/agent-behavior.md
|
||||
│ └── coding/
|
||||
|
|
@ -251,33 +253,37 @@ project/
|
|||
|
||||
### prompts/
|
||||
|
||||
工作流程模板（部署后去掉 `.template` 后缀）：
|
||||
任务入口模板（部署后去掉 `.template` 后缀）：
|
||||
|
||||
其中 `templates/prompts/README.md` 部署后对应 `docs/prompts/README.md`，
|
||||
作为任务入口索引。
|
||||
|
||||
| 文件 | 用途 | 使用场景 |
|
||||
| ----------------------------------- | ------------ | ------------------- |
|
||||
| `system/agent-behavior.template.md` | 工作流入口 | 选择执行路径 |
|
||||
| `system/agent-behavior.template.md` | 入口路由模板 | 选择执行路径 |
|
||||
| `coding/clarify.template.md` | 需求澄清模板 | 需求不明确时 |
|
||||
| `coding/verify-change.template.md` | 变更验证模板 | 声称完成前验证 |
|
||||
| `coding/close-task.template.md` | 本轮收尾模板 | 一轮工作结束时 |
|
||||
| `coding/update-memory.template.md` | 回写记忆模板 | 上下文变化后回写 |
|
||||
| `coding/code-review.template.md` | 代码评审流程 | 执行 MR/PR 代码评审 |
|
||||
| `coding/code-review.template.md` | 代码评审入口 | 执行 MR/PR 代码评审 |
|
||||
|
||||
### AGENT_RULES.template.md
|
||||
|
||||
执行流程规范，定义 AI 的工作循环和约束。
|
||||
执行规则模板，定义 AI 的工作循环和约束。
|
||||
如需项目私有规则，建议维护 `AGENT_RULES.local.md`；该文件通常由 `[sync_rules]`
|
||||
首次自动创建，其优先级高于 `AGENT_RULES.md`，且后续不会被 `playbook.py` 覆盖。
|
||||
计划编排与执行细节建议放在 `prompts/README.md` 或相关 workflow 文档中，
|
||||
计划编排与执行细节统一指向 `docs/superpowers/`、
|
||||
`playbook.py -record-spec/-record-plan` 与 `main_loop.py claim/finish`；
|
||||
这里仅说明模板职责与部署边界。
|
||||
|
||||
### AGENTS.template.md
|
||||
|
||||
路由中心模板，作为项目的主入口。
|
||||
入口导航模板，作为项目的主入口。
|
||||
|
||||
**设计理念**：
|
||||
|
||||
- **最小化内容**：只包含导航链接，不包含详细规则
|
||||
- **结构化导航**：分为核心规则、项目上下文、工作流程三个板块
|
||||
- **结构化导航**：分为核心规则、项目上下文、任务入口三个板块
|
||||
|
||||
**playbook 标记**（用于自动更新）：
|
||||
|
||||
|
|
|
|||
|
|
@ -35,6 +35,13 @@
|
|||
|
||||
- {{CONSTRAINT_1}}
|
||||
|
||||
## 成功定义
|
||||
|
||||
<!-- 【必填】至少写出本轮或本项目如何判断“完成” -->
|
||||
|
||||
- 功能完成的判定标准：{{SUCCESS_1}}
|
||||
- 本轮不覆盖的内容：{{OUT_OF_SCOPE_1}}
|
||||
|
||||
## 核心概念
|
||||
|
||||
<!-- 【可选】项目特有的术语或概念 -->
|
||||
|
|
|
|||
|
|
@ -61,6 +61,12 @@
|
|||
|
||||
- {{DEPENDENCY_OR_LIMIT_1}}
|
||||
|
||||
## 不可假设项
|
||||
|
||||
<!-- 【可选】记录 AI 不能默认成立、必须先验证的信息 -->
|
||||
|
||||
- {{DO_NOT_ASSUME_1}}
|
||||
|
||||
## 验证约定
|
||||
|
||||
<!-- 【可选】什么叫“验证通过” -->
|
||||
|
|
|
|||
|
|
@ -1,6 +1,8 @@
|
|||
# 提示词入口
|
||||
|
||||
本目录包含 AI 代理的工作流入口模板，用于把任务路由到合适的执行路径。
|
||||
本目录包含 AI 代理的任务入口模板，用于把任务路由到合适的执行路径。
|
||||
它是薄入口层，不是流程权威；完整流程与执行约束只在
|
||||
`AGENT_RULES.md` 定义。
|
||||
|
||||
## 目录结构
|
||||
|
||||
|
|
@ -8,13 +10,13 @@
|
|||
prompts/
|
||||
├── README.md # 本文件
|
||||
├── system/
|
||||
│ └── agent-behavior.md # 工作流入口
|
||||
│ └── agent-behavior.md # 入口路由
|
||||
├── coding/
|
||||
│ ├── clarify.md # 需求澄清模板
|
||||
│ ├── verify-change.md # 变更验证模板
|
||||
│ ├── close-task.md # 本轮收尾模板
|
||||
│ ├── update-memory.md # 回写记忆模板
|
||||
│ └── code-review.md # MR/PR 代码评审流程
|
||||
│ └── code-review.md # MR/PR 代码评审入口
|
||||
└── custom/ # 可选：项目私有提示词
|
||||
```
|
||||
|
||||
|
|
@ -22,53 +24,31 @@ prompts/
|
|||
|
||||
| 模板 | 触发场景 |
|
||||
| --------------------- | -------------------- |
|
||||
| **agent-behavior.md** | 选择工作流入口 |
|
||||
| **agent-behavior.md** | 选择任务入口 |
|
||||
| **clarify.md** | 需求不明确时澄清 |
|
||||
| **verify-change.md** | 声称完成前做验证 |
|
||||
| **close-task.md** | 本轮工作收尾 |
|
||||
| **update-memory.md** | 上下文变化后回写记忆 |
|
||||
| **code-review.md** | 执行 MR/PR 代码评审 |
|
||||
| **custom/*.md** | 项目私有补充流程 |
|
||||
| **custom/\*.md** | 项目私有补充入口 |
|
||||
|
||||
## 工作流程
|
||||
## 入口边界
|
||||
|
||||
```text
|
||||
需求不清 → clarify.md
|
||||
↓
|
||||
入口约束 → using-superpowers
|
||||
↓
|
||||
头脑风暴 → $brainstorming skill → docs/superpowers/specs/*-design.md
|
||||
↓
|
||||
spec 完成后 → `playbook.py -record-spec <path> -progress memory-bank/progress.md`
|
||||
↓
|
||||
生成计划 → $writing-plans skill → docs/superpowers/plans/*.md
|
||||
↓
|
||||
plan 完成后 → `playbook.py -record-plan <path> -progress memory-bank/progress.md`
|
||||
↓
|
||||
领取计划 → `main_loop.py claim`
|
||||
↓
|
||||
执行计划 → `$executing-plans`
|
||||
↓
|
||||
代码类任务 → `karpathy-guidelines` + `.agents/` + `AGENT_RULES.md`
|
||||
↓
|
||||
写回状态 → `main_loop.py finish`
|
||||
↓
|
||||
更新摘要 → update-memory.md
|
||||
↓
|
||||
验证改动 → verify-change.md
|
||||
↓
|
||||
本轮收尾 → close-task.md
|
||||
↓
|
||||
代码评审（有 MR/PR 时）→ code-review.md
|
||||
```
|
||||
- 需求不明确：看 `clarify.md`
|
||||
- 需要判断设计、计划或执行路径：先回到 `AGENT_RULES.md`
|
||||
- 需要验证交付结果：看 `verify-change.md`
|
||||
- 需要结束本轮并整理交付摘要：看 `close-task.md`
|
||||
- 需要回写上下文：看 `update-memory.md`
|
||||
- 需要评审 MR/PR：看 `code-review.md`
|
||||
- 需要保留设计与计划产物：只写入 `docs/superpowers/`
|
||||
|
||||
> `coding/` 下是可被框架覆盖更新的标准模板；
|
||||
> 项目私有流程应沉淀到 `custom/`。
|
||||
> `coding/` 下是可被框架覆盖更新的标准入口模板；
|
||||
> 项目私有补充入口应沉淀到 `custom/`。
|
||||
>
|
||||
> `prompts/` 是入口层；核心规则在 `AGENT_RULES.md`，
|
||||
> 长期记忆在 `memory-bank/`，状态留痕必须走
|
||||
> `playbook.py -record-spec/-record-plan` 与
|
||||
> `main_loop.py claim/finish`。
|
||||
> `prompts/` 只负责把代理导向正确入口；`AGENT_RULES.md`
|
||||
> 是唯一流程权威；`AGENT_RULES.local.md` 保存项目私有规则；
|
||||
> `memory-bank/` 保存项目上下文与状态；`docs/superpowers/`
|
||||
> 保存设计与计划产物。
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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` 状态块
|
||||
- 关键验证失败时停止并汇报
|
||||
- 证据不足以支持“完成”结论时停止并汇报
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,49 +1,27 @@
|
|||
# 工作流入口
|
||||
# 任务入口路由
|
||||
|
||||
<!--
|
||||
本文件不重复定义核心规则；它只负责把任务路由到合适的工作流入口。
|
||||
本文件不重复定义核心规则；它只负责把任务路由到合适的任务入口。
|
||||
安全红线、验证要求、主循环规则见 AGENT_RULES.md。
|
||||
-->
|
||||
|
||||
## 路由原则
|
||||
|
||||
- 需求不明确：先看 `docs/prompts/coding/clarify.md`
|
||||
- 需要设计或拆解方案：走
|
||||
`using-superpowers` → `$brainstorming` → `$writing-plans`
|
||||
- `brainstorming` 结束后：立即
|
||||
`playbook.py -record-spec <path> -progress memory-bank/progress.md`
|
||||
- `writing-plans` 结束后：立即
|
||||
`playbook.py -record-plan <path> -progress memory-bank/progress.md`
|
||||
- 需要执行已有 Plan：先 `main_loop.py claim`，再走
|
||||
`$executing-plans`
|
||||
- 如为代码类执行：在 `$executing-plans` 前强制叠加
|
||||
`karpathy-guidelines`，并同时遵循 `.agents/` 与 `AGENT_RULES.md`
|
||||
- 需要判断设计、计划或执行路径：先回到 `AGENT_RULES.md`
|
||||
- 需要确认改动是否站得住：看 `docs/prompts/coding/verify-change.md`
|
||||
- 一轮工作收尾：看 `docs/prompts/coding/close-task.md`
|
||||
- 需要更新上下文：看 `docs/prompts/coding/update-memory.md`
|
||||
- 需要评审 MR/PR：看 `docs/prompts/coding/code-review.md`
|
||||
|
||||
## 最小工作流
|
||||
|
||||
```text
|
||||
需求不清 -> clarify
|
||||
需求明确 -> using-superpowers / brainstorming / writing-plans
|
||||
brainstorming 完成 -> record planning/spec
|
||||
writing-plans 完成 -> record plan/executor/constraints
|
||||
进入执行 -> claim -> executing-plans
|
||||
代码执行 -> + karpathy-guidelines + .agents + AGENT_RULES
|
||||
执行结束 -> finish -> update-memory
|
||||
准备交付 -> verify-change
|
||||
本轮结束 -> close-task
|
||||
上下文变化 -> update-memory
|
||||
```
|
||||
|
||||
## 说明
|
||||
## 边界说明
|
||||
|
||||
- `prompts/` 是入口，不是规则权威
|
||||
- 稳定约束写入 `memory-bank/` 或 `AGENT_RULES.local.md`
|
||||
- 执行留痕以 `memory-bank/progress.md` 的
|
||||
`workflow-state` 与 `plan-status` 为准
|
||||
- 完整流程与执行约束只在 `AGENT_RULES.md`
|
||||
- 项目私有规则写入 `AGENT_RULES.local.md`
|
||||
- 设计产物只放 `docs/superpowers/specs/`
|
||||
- 计划产物只放 `docs/superpowers/plans/`
|
||||
- 项目上下文与执行状态写入 `memory-bank/`
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -71,6 +71,8 @@ fi
|
|||
if validate_file_exists "$AGENT_RULES_TEMPLATE" "AGENT_RULES.template.md"; then
|
||||
validate_contains "$AGENT_RULES_TEMPLATE" "AGENT_RULES" "包含 AGENT_RULES 标题"
|
||||
validate_contains "$AGENT_RULES_TEMPLATE" "{{DATE}}" "包含 {{DATE}} 占位符"
|
||||
validate_contains "$AGENT_RULES_TEMPLATE" "docs/superpowers/plans/" "包含 superpowers plans 路径"
|
||||
validate_contains "$AGENT_RULES_TEMPLATE" "using-superpowers -> brainstorming -> writing-plans" "包含规划主链"
|
||||
fi
|
||||
|
||||
validate_file_exists "$README_TEMPLATE" "templates/README.md"
|
||||
|
|
|
|||
|
|
@ -57,6 +57,7 @@ class DeploymentRoutesE2ETests(unittest.TestCase):
|
|||
for rel in expected:
|
||||
with self.subTest(path=rel):
|
||||
self.assertTrue((project_root / rel).exists(), f"missing: {rel}")
|
||||
self.assertFalse((project_root / "docs" / "workflows").exists())
|
||||
|
||||
def assert_docs_prefix(self, project_root: Path, docs_prefix: str) -> None:
|
||||
agents_index = (project_root / ".agents" / "index.md").read_text(encoding="utf-8")
|
||||
|
|
|
|||
|
|
@ -66,6 +66,7 @@ deploy_root = "{DEFAULT_DEPLOY_ROOT}"
|
|||
|
||||
self.assertTrue(custom.exists())
|
||||
self.assertTrue((prompts / "system" / "agent-behavior.md").is_file())
|
||||
self.assertFalse((root / "docs" / "workflows").exists())
|
||||
|
||||
def test_sync_memory_bank_force_overwrites_template_files_only(self):
|
||||
with tempfile.TemporaryDirectory() as tmp_dir:
|
||||
|
|
|
|||
|
|
@ -36,11 +36,18 @@ class SyncTemplatesPlaceholdersTests(unittest.TestCase):
|
|||
)
|
||||
self.assertNotIn("{{MAIN_LANGUAGE}}", templates_readme)
|
||||
self.assertNotIn("{{LANGUAGE_1}}", templates_readme)
|
||||
self.assertNotIn("docs/workflows/", templates_readme)
|
||||
self.assertNotIn("templates/workflows/", templates_readme)
|
||||
self.assertIn("docs/superpowers/", templates_readme)
|
||||
self.assertIn("docs/prompts/README.md", templates_readme)
|
||||
self.assertIn("完整主链只在 `AGENT_RULES.template.md` 定义", templates_readme)
|
||||
|
||||
agents_template = (ROOT / "templates" / "AGENTS.template.md").read_text(
|
||||
encoding="utf-8"
|
||||
)
|
||||
self.assertNotIn("{{MAIN_LANGUAGE}}", agents_template)
|
||||
self.assertIn("AGENT_RULES.md", agents_template)
|
||||
self.assertIn("docs/prompts/README.md", agents_template)
|
||||
|
||||
tech_context_template = (
|
||||
ROOT / "templates" / "memory-bank" / "tech-context.template.md"
|
||||
|
|
@ -48,36 +55,91 @@ class SyncTemplatesPlaceholdersTests(unittest.TestCase):
|
|||
self.assertNotIn("{{MAIN_LANGUAGE}}", tech_context_template)
|
||||
self.assertNotIn("{{LANGUAGE_1}}", tech_context_template)
|
||||
self.assertNotIn("**主要语言**", tech_context_template)
|
||||
self.assertIn("## 不可假设项", tech_context_template)
|
||||
|
||||
project_brief_template = (
|
||||
ROOT / "templates" / "memory-bank" / "project-brief.template.md"
|
||||
).read_text(encoding="utf-8")
|
||||
self.assertIn("## 成功定义", project_brief_template)
|
||||
|
||||
update_memory_template = (
|
||||
ROOT / "templates" / "prompts" / "coding" / "update-memory.template.md"
|
||||
).read_text(encoding="utf-8")
|
||||
self.assertIn("workflow-state", update_memory_template)
|
||||
self.assertIn("plan-status", update_memory_template)
|
||||
self.assertIn("## Updated Files", update_memory_template)
|
||||
self.assertIn("## New Context", update_memory_template)
|
||||
self.assertIn("## Outstanding Risks", update_memory_template)
|
||||
self.assertIn("AGENT_RULES.local.md", update_memory_template)
|
||||
|
||||
close_task_template = (
|
||||
ROOT / "templates" / "prompts" / "coding" / "close-task.template.md"
|
||||
).read_text(encoding="utf-8")
|
||||
self.assertIn("main_loop.py finish", close_task_template)
|
||||
self.assertIn("workflow-state.phase", close_task_template)
|
||||
self.assertIn("## Completed", close_task_template)
|
||||
self.assertIn("## Not Completed", close_task_template)
|
||||
self.assertIn("## Verification", close_task_template)
|
||||
self.assertIn("## Risks", close_task_template)
|
||||
self.assertIn("## Next Steps", close_task_template)
|
||||
|
||||
verify_change_template = (
|
||||
ROOT / "templates" / "prompts" / "coding" / "verify-change.template.md"
|
||||
).read_text(encoding="utf-8")
|
||||
self.assertIn("workflow-state.phase", verify_change_template)
|
||||
self.assertIn("plan-status", verify_change_template)
|
||||
self.assertIn("## Validated", verify_change_template)
|
||||
self.assertIn("## Evidence", verify_change_template)
|
||||
self.assertIn("## Not Validated", verify_change_template)
|
||||
self.assertIn("## Risks", verify_change_template)
|
||||
|
||||
clarify_template = (
|
||||
ROOT / "templates" / "prompts" / "coding" / "clarify.template.md"
|
||||
).read_text(encoding="utf-8")
|
||||
self.assertNotIn("Vibe-coding", clarify_template)
|
||||
self.assertIn("## Current Understanding", clarify_template)
|
||||
self.assertIn("## Open Question", clarify_template)
|
||||
self.assertIn("## Recommended Default", clarify_template)
|
||||
|
||||
code_review_template = (
|
||||
ROOT / "templates" / "prompts" / "coding" / "code-review.template.md"
|
||||
).read_text(encoding="utf-8")
|
||||
self.assertIn("## Findings", code_review_template)
|
||||
self.assertIn("## Open Questions", code_review_template)
|
||||
self.assertIn("## Residual Risk", code_review_template)
|
||||
|
||||
prompts_readme = (
|
||||
ROOT / "templates" / "prompts" / "README.md"
|
||||
).read_text(encoding="utf-8")
|
||||
self.assertIn("playbook.py -record-spec", prompts_readme)
|
||||
self.assertIn("playbook.py -record-plan", prompts_readme)
|
||||
self.assertIn("AGENT_RULES.md", prompts_readme)
|
||||
self.assertIn("docs/superpowers/", prompts_readme)
|
||||
self.assertIn("不是流程权威", prompts_readme)
|
||||
self.assertNotIn("playbook.py -record-spec", prompts_readme)
|
||||
self.assertNotIn("playbook.py -record-plan", prompts_readme)
|
||||
self.assertNotIn("using-superpowers", prompts_readme)
|
||||
self.assertNotIn("main_loop.py claim", prompts_readme)
|
||||
self.assertNotIn("docs/workflows/", prompts_readme)
|
||||
self.assertIn("设计与计划产物", prompts_readme)
|
||||
|
||||
agent_behavior_template = (
|
||||
ROOT / "templates" / "prompts" / "system" / "agent-behavior.template.md"
|
||||
).read_text(encoding="utf-8")
|
||||
self.assertIn("playbook.py -record-spec", agent_behavior_template)
|
||||
self.assertIn("playbook.py -record-plan", agent_behavior_template)
|
||||
self.assertIn("AGENT_RULES.md", agent_behavior_template)
|
||||
self.assertIn("AGENT_RULES.local.md", agent_behavior_template)
|
||||
self.assertIn("docs/superpowers/specs/", agent_behavior_template)
|
||||
self.assertIn("docs/superpowers/plans/", agent_behavior_template)
|
||||
self.assertNotIn("using-superpowers", agent_behavior_template)
|
||||
self.assertNotIn("main_loop.py claim", agent_behavior_template)
|
||||
self.assertNotIn("playbook.py -record-spec", agent_behavior_template)
|
||||
self.assertNotIn("playbook.py -record-plan", agent_behavior_template)
|
||||
self.assertIn("项目上下文与执行状态写入 `memory-bank/`", agent_behavior_template)
|
||||
|
||||
rules_template = (
|
||||
ROOT / "templates" / "AGENT_RULES.template.md"
|
||||
).read_text(encoding="utf-8")
|
||||
self.assertIn("唯一流程约束中心", rules_template)
|
||||
self.assertIn("唯一设计与计划产物中心", rules_template)
|
||||
self.assertIn("memory-bank/progress.md", rules_template)
|
||||
|
||||
def test_sync_templates_replaces_playbook_scripts_without_main_language_support(self):
|
||||
with tempfile.TemporaryDirectory() as tmp_dir:
|
||||
|
|
|
|||
Loading…
Reference in New Issue