🔧 chore(playbook): align repo with latest workflow
lsp-server ci / build-and-test (push) Failing after 0s

sync playbook-managed rules and prompts.
migrate memory-bank to the new structure and move plans to docs/superpowers/plans.
keep product README files untouched.
This commit is contained in:
csh
2026-05-24 13:34:07 +08:00
parent 696920df73
commit 7838f3ec3d
27 changed files with 1063 additions and 901 deletions
+47 -20
View File
@@ -1,6 +1,6 @@
# 提示词
# 提示词入口
本目录包含 AI 代理的工作流程参考模板
本目录包含 AI 代理的工作流入口模板,用于把任务路由到合适的执行路径
## 目录结构
@@ -8,41 +8,68 @@
prompts/
├── README.md # 本文件
├── system/
│ └── agent-behavior.md # 工作模式参考
│ └── agent-behavior.md # 工作流入口
├── coding/
│ ├── clarify.md # 需求澄清模板
── review.md # 复盘总结模板
└── meta/
── prompt-generator.md # 元提示词生成器
── verify-change.md # 变更验证模板
│ ├── close-task.md # 本轮收尾模板
── update-memory.md # 回写记忆模板
│ └── code-review.md # MR/PR 代码评审流程
└── custom/ # 可选:项目私有提示词
```
## 使用方式
| 模板 | 触发场景 |
| ----------------------- | ------------------------------ |
| **agent-behavior.md** | 切换工作模式(探索/开发/调试) |
| **clarify.md** | 需求不明确时澄清 |
| **review.md** | Plan 完成后复盘总结 |
| **prompt-generator.md** | 创建新的专用提示词 |
| 模板 | 触发场景 |
| --------------------- | -------------------- |
| **agent-behavior.md** | 选择工作流入口 |
| **clarify.md** | 需求不明确时澄清 |
| **verify-change.md** | 声称完成前做验证 |
| **close-task.md** | 本轮工作收尾 |
| **update-memory.md** | 上下文变化后回写记忆 |
| **code-review.md** | 执行 MR/PR 代码评审 |
| **custom/*.md** | 项目私有补充流程 |
## 工作流程
```
```text
需求不清 → clarify.md
头脑风暴 → $brainstorming skill
入口约束 → using-superpowers
生成计划 → $writing-plans skill → docs/plans/*.md
头脑风暴 → $brainstorming skill → docs/superpowers/specs/*-design.md
执行计划 → AGENT_RULES 主循环(留痕)
spec 完成后 → `playbook.py -record-spec <path> -progress memory-bank/progress.md`
完成复盘 → review.md
生成计划 → $writing-plans skill → docs/superpowers/plans/*.md
沉淀提示词 → prompt-generator.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
```
> **核心规则在 `AGENT_RULES.md`**,第三方 skills 负责规划,主循环负责执行和留痕。
> `coding/` 下是可被框架覆盖更新的标准模板;
> 项目私有流程应沉淀到 `custom/`。
>
> `prompts/` 是入口层;核心规则在 `AGENT_RULES.md`
> 长期记忆在 `memory-bank/`,状态留痕必须走
> `playbook.py -record-spec/-record-plan` 与
> `main_loop.py claim/finish`。
---
**最后更新**2026-02-03
**最后更新**2026-05-24
+1 -1
View File
@@ -49,4 +49,4 @@ Vibe-coding 场景下可跳过,直接开始实现。
---
**最后更新**2026-02-03
**最后更新**2026-05-24
+60
View File
@@ -0,0 +1,60 @@
# 收尾模板
<!--
用途:一轮实现或一个 Plan 结束后做收尾
触发:准备结束当前任务、切换上下文、交付结果前
-->
## 目标
确认当前任务已经形成可交付结果,并把后续工作所需的信息留痕。
## 执行步骤
### 1. 核对结果
- 已完成哪些改动?
- 哪些内容仍未完成?
- 是否存在阻塞、风险或待确认事项?
### 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
## 本轮结果
- 已完成:...
- 未完成:...
- 验证:...
- 风险 / 待确认:...
- 下一步:...
```
## 原则
- 只写对下一轮仍然重要的信息
- 未验证的内容必须显式说明
- 如果任务状态变更,优先通过 `main_loop.py finish` 留痕
- 不手工改写 `workflow-state``plan-status` 状态块
---
**最后更新**2026-05-24
+81
View File
@@ -0,0 +1,81 @@
# Code Review 流程
## 触发场景
收到 MR/PR 需要评审时。
## 准备
切换到对应分支并获取变更内容:
```bash
# GitLab
glab mr checkout <MR_ID>
glab mr view <MR_ID> | cat
glab mr diff <MR_ID> | cat
# GitHub
gh pr checkout <PR_NUMBER>
gh pr view <PR_NUMBER>
gh pr diff <PR_NUMBER>
```
## 评审流程
逐步执行以下维度。改动简单时可跳过某些步骤。
### 1. 理解业务目标
- 能否理解本次改动的业务目标?
- 如果目标不明确,先确认再评审。
### 2. High-level Review
- 改动是否放在了合适的位置?
- 是否尽可能复用已有实现?
- 是否有破坏现有设计与逻辑的可能?
### 3. Bug 检查
- 是否隐含业务错误、逻辑纰漏或安全问题?
- **未修改**的相关联代码是否有遗漏?
### 4. 代码清晰度
- 逻辑是否简洁易懂?
- 命名是否清晰合理?
- 一年后再读,是否能轻松理解?
### 5. KISS 原则
- 是否有不必要的复杂度?
- 是否有未使用的定义、过多参数?
- 是否重复造轮子?
### 6. 单一职责
- 每个函数/类是否只做一件事?
- 文件/类/方法行数是否合理?
### 7. 测试覆盖
- 复杂业务逻辑(含 if/else/for)是否有测试?
- 测试是否有效(非空实现)?
- 不应过度测试无控制逻辑的代码。
## 输出
评审完成后,总结发现的**重点问题**,按严重性排列。
## AI 与人工的分工
| 维度 | 负责方 | 说明 |
| -------------------------- | ------------- | ------------------------------------- |
| Bug、逻辑漏洞、安全问题 | **AI + 人工** | AI 负责初筛与证据收集,结论需人工复核 |
| 代码清晰度、KISS、单一职责 | **AI + 人工** | AI 提供候选问题,人工决定是否采纳 |
| 架构合理性、业务对齐 | **人工** | AI 反馈少且准确率低,需人工把关 |
| 兼容性、历史债务、战略取舍 | **人工** | 依赖背景知识,AI 难以判断 |
> 规则:AI 结论必须附文件路径、行号或可复现依据;缺少证据时按待确认假设处理。
>
> 注意:评审不只看 diff,需结合代码库整体上下文做评估。
-66
View File
@@ -1,66 +0,0 @@
# 复盘模板
<!--
用途:Plan 或阶段完成后的回顾总结
触发:主循环汇总报告时、阶段性工作完成时
-->
## 何时使用
- 一批 Plan 执行完毕后
- 阶段性工作告一段落
- 遇到重大阻塞需要总结
---
## 复盘格式
```markdown
# 复盘: [日期/阶段名称]
## 完成情况
### 已完成
- [x] Plan 1: 简述
- [x] Plan 2: 简述
### 阻塞
- [ ] Plan 3: 阻塞原因
### 跳过
- [ ] Plan 4: 跳过原因
## 关键发现
### 做得好的
- 发现1
- 发现2
### 待改进
- 问题1 → 建议改进方式
- 问题2 → 建议改进方式
## 决策记录
| 决策 | 理由 | 影响 |
|------|------|------|
| 决策1 | 为什么 | 影响范围 |
## 下一步
- [ ] 待处理事项1
- [ ] 待处理事项2
```
---
## 复盘原则
- **客观记录**:如实记录完成/阻塞/跳过
- **提取经验**:总结做得好的和待改进的
- **决策留痕**:重要决策记录到 decisions.md
- **明确下一步**:列出后续待处理事项
---
**最后更新**2026-02-03
+79
View File
@@ -0,0 +1,79 @@
# 回写记忆模板
<!--
用途:在任务完成、方向切换或发现新规律后更新 memory-bank
触发:完成一轮实现、形成新决策、当前焦点变化时
-->
## 什么时候需要回写
- 当前目标已经变化
- 最近改动会影响下一轮判断
- 发现新的系统模式或约束
- 做出了值得保留的决策
## 回写路径
### `memory-bank/active-context.md`
更新:
- 当前目标
- 最近变更
- touched files
- 下一步
### `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`
- `progress.md` 的状态块只由 `main_loop.py` 维护
- 摘要应与 `workflow-state` / `plan-status` 保持一致
---
**最后更新**2026-05-24
+69
View File
@@ -0,0 +1,69 @@
# 变更验证模板
<!--
用途:在声明“完成 / 修复 / 可交付”前,明确验证范围与证据
触发:代码修改、配置修改、模板修改、规则修改后
-->
## 验证目标
- 这次改动要证明什么?
- 哪些行为必须通过?
- 哪些验证本轮不做?
## 验证步骤
### 1. 语法 / 结构检查
- 确认修改文件可读、可解析、无明显结构错误
### 2. 定向验证
- 只跑与本次改动直接相关的验证命令
- 记录命令、结果和关键输出
- 如仓库存在项目私有验证提示词(例如 `docs/prompts/custom/verify.md`),先读取并执行其中的附加约束
```bash
{{VERIFY_CMD}}
```
### 3. 差异复核
- 核对 diff 是否只包含预期修改
- 确认没有误删、误改、命名漂移或路径漂移
### 4. 状态留痕复核
- `workflow-state.phase` 是否与当前声明一致
- `plan-status` 是否已经通过 `main_loop.py finish` 写回
- 如为代码类任务,`workflow-state` 中是否保留:
`executor=executing-plans`
`constraints=karpathy-guidelines,.agents,AGENT_RULES`
### 5. 剩余风险
- 本轮未覆盖的验证
- 环境限制
- 需要人工确认的点
## 输出格式
```markdown
## 验证结果
- 已验证:...
- 证据:...
- 未验证:...
- 风险:...
```
## 原则
- 没有证据,不宣称完成
- 局部修改优先局部验证
- 不能运行的验证要明确写原因
- 不手工改写 `workflow-state``plan-status` 状态块
---
**最后更新**2026-05-24
-126
View File
@@ -1,126 +0,0 @@
# 提示词生成器(元提示词)
<!--
用途:根据场景自动生成专用提示词
原理:α-prompts(生成)+ Ω-prompts(优化)递归循环
-->
## 何时使用
- 需要为新场景创建专用提示词
- 现有提示词不满足特定需求
- 需要批量生成同类提示词
---
## 生成流程(α循环)
### 1. 分析场景
```markdown
**场景名称**[名称]
**目标用户**[AI/人类/两者]
**触发条件**[何时使用这个提示词]
**预期输出**[使用后应该产出什么]
```
### 2. 提取约束
```markdown
**必须做**
- 约束1
- 约束2
**禁止做**
- 禁止1
- 禁止2
**边界条件**
- 边界1
- 边界2
```
### 3. 生成草稿
```markdown
# [提示词标题]
<!--
用途:[一句话描述]
触发:[触发条件]
-->
## 何时使用
- 场景1
- 场景2
## [核心内容]
[根据场景填充]
## [约束/原则]
- 约束1
- 约束2
---
**最后更新**2026-02-03
```
---
## 优化流程(Ω循环)
### 1. 评估维度
| 维度 | 问题 |
| ---------- | ---------------------- |
| **清晰度** | 指令是否明确无歧义? |
| **完整度** | 是否覆盖所有必要场景? |
| **简洁度** | 是否有冗余内容可删除? |
| **可操作** | AI 能否直接执行? |
### 2. 迭代优化
```
草稿 → 评估 → 修改 → 再评估 → ... → 定稿
```
### 3. 验证测试
- 用实际场景测试提示词效果
- 收集反馈,持续迭代
---
## 提示词模板库
### 标准结构
```markdown
# [标题]
<!--
用途:
触发:
-->
## 何时使用
## [核心内容]
## [约束/原则]
---
**最后更新**2026-02-03
```
### 命名规范
- 文件名:`[动词]-[对象].template.md`
- 示例:`clarify-requirement.template.md`
---
**最后更新**2026-02-03
+38 -50
View File
@@ -1,62 +1,50 @@
# 工作模式参考
# 工作流入口
<!--
本文件定义三种工作模式,供 AI 根据任务类型选择
核心规则(安全红线、验证清单等)见 AGENT_RULES.md。
本文件不重复定义核心规则;它只负责把任务路由到合适的工作流入口
安全红线、验证要求、主循环规则见 AGENT_RULES.md。
-->
## 模式 1: 探索模式(Explore
## 路由原则
**目的**:理解代码库、分析问题、收集信息
- 需求不明确:先看 `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`
- 需要确认改动是否站得住:看 `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
```
**适用场景**
## 说明
- 理解某个模块的实现
- 分析 bug 的根本原因
- 评估功能实现的可行性
- `prompts/` 是入口,不是规则权威
- 稳定约束写入 `memory-bank/``AGENT_RULES.local.md`
- 执行留痕以 `memory-bank/progress.md`
`workflow-state``plan-status` 为准
---
## 模式 2: 开发模式(Develop
**目的**:实现功能、修复 bug、重构代码
**行为**
- 先读取相关文件,理解现有逻辑
- 进行精确修改
- 修改后运行测试验证
**适用场景**
- 实现新功能
- 修复已知 bug
- 优化性能
---
## 模式 3: 调试模式(Debug
**目的**:诊断问题、对比差异、验证行为
**行为**
- 收集相关日志和输出
- 分析差异原因
- 修复后重新验证
**适用场景**
- 测试失败
- 输出不符合预期
- 性能问题诊断
---
**最后更新**2026-02-03
**最后更新**2026-05-24