csh
/
playbook
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

📝 docs(templates): add execution and memory-bank prompt templates

This commit is contained in:
csh 2026-05-18 15:43:00 +08:00
parent 223a7974b0
commit a22b324c5c
7 changed files with 536 additions and 132 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

267
templates/README.md
View File

@ -11,8 +11,9 @@ templates/
├── AGENT_RULES.template.md # 执行流程模板 ├── AGENT_RULES.template.md # 执行流程模板
├── memory-bank/ # 项目上下文模板 ├── memory-bank/ # 项目上下文模板
│ ├── project-brief.template.md │ ├── project-brief.template.md
│ ├── tech-stack.template.md │ ├── tech-context.template.md
│ ├── architecture.template.md │ ├── system-patterns.template.md
│ ├── active-context.template.md
│ ├── progress.template.md │ ├── progress.template.md
│ └── decisions.template.md │ └── decisions.template.md
├── prompts/ # 提示词库模板 ├── prompts/ # 提示词库模板
@ -21,13 +22,16 @@ templates/
│ │ └── agent-behavior.template.md │ │ └── agent-behavior.template.md
│ ├── coding/ │ ├── coding/
│ │ ├── clarify.template.md │ │ ├── clarify.template.md
│ │ ├── review.template.md │ │ ├── verify-change.template.md
│ │ ├── close-task.template.md
│ │ ├── update-memory.template.md
│ │ └── code-review.template.md │ │ └── code-review.template.md
│ └── meta/
│ └── prompt-generator.template.md
├── ci/ # CI 模板 ├── ci/ # CI 模板
│ ├── README.md
│ └── gitea/ │ └── gitea/
│ └── .gitea/workflows/ │ └── .gitea/
│ ├── workflows/
│ └── ci/
├── cpp/ # C++ 配置模板 ├── cpp/ # C++ 配置模板
│ ├── .clang-format │ ├── .clang-format
│ ├── .clangd │ ├── .clangd
@ -40,62 +44,35 @@ templates/
## 文件分类 ## 文件分类
从部署角度，文件分为四类： 从部署角度看，本目录的文件分成三类：
| 类型 | 说明 | 部署行为 | - **会同步更新的框架模板**
|------|------|----------| - `AGENT_RULES.md`
| **框架模板** | playbook 提供，可随框架升级 | 可覆盖更新 | - `docs/prompts/system/*.md`
| **项目上下文** | 首次部署后项目填写 | 首次创建，后续保护 | - `docs/prompts/coding/*.md`
| **项目私有** | 项目手动创建 | 不部署 | - `AGENTS.md`、`CLAUDE.md`（按 playbook 区块更新）
| **参考资料** | 留在 playbook 快照中参考 | 不部署到项目根 | - **首次创建后由项目维护的上下文文件**
- `memory-bank/*.md`
- `AGENT_RULES.local.md`
- **只保留在快照中参考的模板**
- `ci/`
- `cpp/`
- `python/`
### 框架模板（A类） 补充说明：
``` - `memory-bank/*.md` 首次创建后应由项目填写；`force=true`
AGENT_RULES.md 会覆盖已填写内容并先备份。
AGENT_RULES.local.md # 首次自动创建（空模板） - `AGENT_RULES.local.md` 由 `[sync_rules]` 首次自动创建，
AGENTS.md（区块更新） 后续不再覆盖。
CLAUDE.md（自动检测/创建，注入 @AGENTS.md） - `docs/prompts/custom/` 和项目新增的 `docs/prompts/**/*`
docs/prompts/system/*.md # 框架提供 不会被 playbook 删除。
docs/prompts/coding/*.md # 框架提供 - `CLAUDE.md` 如已有 playbook 区块则更新；如未引用
docs/prompts/meta/*.md # 框架提供 `@AGENTS.md` 则追加；如已手工引用 `@AGENTS.md` 则跳过。
```
### 项目上下文（B类）
```
memory-bank/
├── project-brief.md
├── tech-stack.md
├── architecture.md
├── progress.md
└── decisions.md
```
> ⚠️ B类文件首次创建后应由项目填写。`force=true` 会覆盖已填写内容（自动备份）。
### 项目私有（C类，不部署）
```
docs/plans/ # 项目实施计划
docs/prompts/custom/ # 项目自定义提示词
docs/prompts/**/* # 项目新增的文件不会被删除
```
> `AGENT_RULES.local.md` 由 `[sync_rules]` 首次自动创建（空模板），后续由项目维护，不会被覆盖。
### 参考资料（D类，不部署到项目根）
```
# 留在 <deploy_root>/templates/ 中参考
ci/ # CI 配置
cpp/ # C++ 配置
python/ # Python 配置
```
## 快速部署 ## 快速部署
使用统一入口 `playbook.py`，配置节存在即启用： 以下命令假设 **playbook 已经部署到项目内**，使用统一入口 `playbook.py`，配置节存在即启用：
```toml ```toml
# playbook.toml # playbook.toml
@ -120,23 +97,41 @@ project_name = "MyProject"
python <deploy_root>/scripts/playbook.py -config playbook.toml python <deploy_root>/scripts/playbook.py -config playbook.toml
``` ```
参数说明见 `playbook.toml.example`（仓库根目录）或项目内的 `<deploy_root>/playbook.toml.example`。 参数说明见 `playbook.toml.example`（仓库根目录）或项目内的
`<deploy_root>/playbook.toml.example`。
其中 `<deploy_root>` 默认为 `docs/standards/playbook`，也可以按项目配置改成 `custom/playbook` 等自定义目录；对应文档入口会变成 `<deploy_root>/docs/...`。 其中 `<deploy_root>` 默认为 `docs/standards/playbook`，
也可以按项目配置改成 `custom/playbook` 等自定义目录；
对应文档入口会变成 `<deploy_root>/docs/...`。
如果你当前是在 **外部 clone 的 playbook 仓库** 中执行，而不是在目标项目内执行快照，请使用：
```bash
python scripts/playbook.py -config playbook.toml
```
此时 `[vendor]` 会把快照写入 `<project_root>/<deploy_root>`；
后续再在目标项目内使用 `<deploy_root>/scripts/playbook.py`
做同步更新。
### 配置节说明 ### 配置节说明
| 配置节 | 部署内容 | 选项 | - `[sync_rules]`：部署 `AGENT_RULES.md`；必要时创建 `.local.md`。
| -------------------- | --------------------------------- | --------------------------------- | 选项：`force`、`no_backup`、`date`
| `[sync_rules]` | AGENT_RULES.md + .local.md | `force`, `no_backup`, `date` | - `[sync_memory_bank]`：部署 `memory-bank/`。
| `[sync_memory_bank]` | memory-bank/ | `project_name`, `force`, `no_backup`, `date` | 选项：`project_name`、`force`、`no_backup`、`date`
| `[sync_prompts]` | docs/prompts/ | `force`, `no_backup`, `date` | - `[sync_prompts]`：部署 `docs/prompts/`。
| `[sync_standards]` | .agents/\<lang\>/ | `langs`, `gitattr_mode`, `no_backup` | 选项：`force`、`no_backup`、`date`
| `[install_skills]` | ~/.agents/skills/ 或 ~/.claude/skills/ | `mode`, `skills`, `agents_home`, `skill_link`, `no_backup` | - `[sync_standards]`：部署 `.agents/<lang>/`。
选项：`langs`、`gitattr_mode`、`no_backup`
- `[install_skills]`：部署到 `~/.agents/skills/` 或
`~/.claude/skills/`。
选项：`mode`、`skills`、`agents_home`、`skill_link`、
`no_backup`
- **配置节存在即启用**：只写需要同步的配置节 - **配置节存在即启用**：只写需要同步的配置节
- **AGENTS.md**：始终按区块更新（`<!-- playbook:xxx:start/end -->`），不受配置节控制 - **AGENTS.md**：始终按区块更新（`<!-- playbook:xxx:start/end -->`），不受配置节控制
- **CLAUDE.md**：自动检测/创建，注入 `@AGENTS.md` / `@AGENT_RULES.md` - **CLAUDE.md**：自动检测/创建；如已存在 playbook 区块则更新，如未引用 `@AGENTS.md` 则追加，否则跳过
- **force**：默认 false，已存在则跳过；设为 true 时覆盖框架文件（会先备份） - **force**：默认 false，已存在则跳过；设为 true 时覆盖框架文件（会先备份）
- **no_backup**：默认 false；设为 true 时跳过备份直接覆盖 - **no_backup**：默认 false；设为 true 时跳过备份直接覆盖
- **不删除项目文件**：只更新框架提供的文件，项目新增的文件不会被删除 - **不删除项目文件**：只更新框架提供的文件，项目新增的文件不会被删除
@ -161,6 +156,35 @@ project_name = "MyProject"
force = true force = true
``` ```
### docs/superpowers 命名约定
为与 thirdparty `superpowers` 上游当前工作流对齐，建议统一使用：
- `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`：
`brainstorming` 产出的设计稿
- `docs/superpowers/plans/YYYY-MM-DD-<topic>.md`：
`writing-plans` 产出的实施计划
其中 `plans/` 为主执行入口；`specs/` 只作为设计背景和上游文档。
### 生命周期总览
```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
```
### 部署后的目录结构 ### 部署后的目录结构
```text ```text
@ -168,20 +192,27 @@ project/
├── AGENTS.md # 路由中心（Codex 入口） ├── AGENTS.md # 路由中心（Codex 入口）
├── AGENT_RULES.md # 执行流程 ├── AGENT_RULES.md # 执行流程
├── AGENT_RULES.local.md # 项目私有规则（自动创建，项目维护） ├── AGENT_RULES.local.md # 项目私有规则（自动创建，项目维护）
├── CLAUDE.md # Claude Code 入口（自动注入 @AGENTS.md） ├── CLAUDE.md # Claude Code 入口（按规则维护/追加 playbook 区块）
├── memory-bank/ # 项目上下文 ├── memory-bank/ # 项目上下文
│ ├── project-brief.md │ ├── project-brief.md
│ ├── tech-stack.md │ ├── tech-context.md
│ ├── architecture.md │ ├── system-patterns.md
│ ├── active-context.md
│ ├── progress.md │ ├── progress.md
│ └── decisions.md │ └── decisions.md
└── docs/prompts/ # 提示词库 └── docs/
├── README.md ├── prompts/ # 提示词库
├── system/agent-behavior.md │ ├── README.md
├── coding/ │ ├── system/agent-behavior.md
│ └── coding/
│ ├── clarify.md │ ├── clarify.md
│ └── review.md │ ├── verify-change.md
└── meta/prompt-generator.md │ ├── close-task.md
│ ├── update-memory.md
│ └── code-review.md
└── superpowers/
├── specs/ # brainstorming 产物
└── plans/ # writing-plans / main_loop 消费
``` ```
## 占位符说明 ## 占位符说明
@ -197,8 +228,11 @@ project/
| `{{PLAYBOOK_SCRIPTS}}` | 脚本路径 | ✅ 是 | | `{{PLAYBOOK_SCRIPTS}}` | 脚本路径 | ✅ 是 |
| 其他 `{{...}}` | 项目特定内容 | ❌ 手动 | | 其他 `{{...}}` | 项目特定内容 | ❌ 手动 |
`{{PROJECT_NAME}}` 可通过 `sync_memory_bank.project_name` 自动替换；未配置时保持原样。 `{{PROJECT_NAME}}` 可通过 `sync_memory_bank.project_name` 自动替换；
`{{PLAYBOOK_SCRIPTS}}` 自动替换为 Playbook 脚本路径（默认 `docs/standards/playbook/scripts`，也可按项目配置改成 `custom/playbook/scripts` 等）。 未配置时保持原样。
`{{PLAYBOOK_SCRIPTS}}` 自动替换为 Playbook 脚本路径
（默认 `docs/standards/playbook/scripts`，
也可按项目配置改成 `custom/playbook/scripts` 等）。
## 模板说明 ## 模板说明
@ -207,11 +241,12 @@ project/
项目上下文文档，用于让 AI 快速理解项目： 项目上下文文档，用于让 AI 快速理解项目：
| 文件 | 用途 | | 文件 | 用途 |
| --------------------------- | -------------------- | | ----------------------------- | -------------------------- |
| `project-brief.template.md` | 项目定位、边界、约束 | | `project-brief.template.md` | 项目定位、边界、约束 |
| `tech-stack.template.md` | 技术栈、工具链、环境 | | `tech-context.template.md` | 技术上下文、工具链、入口 |
| `architecture.template.md` | 架构设计、模块职责 | | `system-patterns.template.md` | 系统模式、边界、不变量 |
| `progress.template.md` | 开发进度追踪 | | `active-context.template.md` | 当前目标、最近变更、下一步 |
| `progress.template.md` | 人类摘要 + Plan 状态块 |
| `decisions.template.md` | 架构决策记录（ADR） | | `decisions.template.md` | 架构决策记录（ADR） |
### prompts/ ### prompts/
@ -219,43 +254,21 @@ project/
工作流程模板（部署后去掉 `.template` 后缀）： 工作流程模板（部署后去掉 `.template` 后缀）：
| 文件 | 用途 | 使用场景 | | 文件 | 用途 | 使用场景 |
| ----------------------------------- | -------------- | ---------------------- | | ----------------------------------- | ------------ | ------------------- |
| `system/agent-behavior.template.md` | 工作模式参考 | 切换探索/开发/调试模式 | | `system/agent-behavior.template.md` | 工作流入口 | 选择执行路径 |
| `coding/clarify.template.md` | 需求澄清模板 | 需求不明确时 | | `coding/clarify.template.md` | 需求澄清模板 | 需求不明确时 |
| `coding/review.template.md` | 复盘总结模板 | Plan 完成后复盘 | | `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 代码评审 |
| `meta/prompt-generator.template.md` | 元提示词生成器 | 创建新的专用提示词 |
### AGENT_RULES.template.md ### AGENT_RULES.template.md
执行流程规范，定义 AI 的工作循环和约束。 执行流程规范，定义 AI 的工作循环和约束。
如需项目私有规则，建议创建 `AGENT_RULES.local.md`，其优先级高于 `AGENT_RULES.md`， 如需项目私有规则，建议维护 `AGENT_RULES.local.md`；该文件通常由 `[sync_rules]`
且不会被 `playbook.py` 覆盖。 首次自动创建，其优先级高于 `AGENT_RULES.md`，且后续不会被 `playbook.py` 覆盖。
主循环会根据 `memory-bank/progress.md` 的 Plan 状态清单， 计划编排与执行细节建议放在 `prompts/README.md` 或相关 workflow 文档中，
通过 `scripts/main_loop.py claim/finish` 原子化领取 Plan 并写回状态。 这里仅说明模板职责与部署边界。
### 示例：不跑测试的计划提示词
当你需要修改代码但暂时不运行测试时，可用以下提示词生成“可执行且不失败”的实施计划：
```text
先使用 $brainstorming。
目标：修改 <模块/功能>，细节如下：<你的需求>
约束：
- 不跑任何测试（test/ci），但允许做可通过的局部验证（格式化/静态检查/人工 diff）。
- Plan 不能包含任何必然失败或未确认的任务；所有依赖必须在 brainstorming 阶段确认清楚。
- 采用 writing-plans 的固定头部格式，且在 `---` 之后追加 `## Plan Meta`：
- Plan Group: <X>
- Parent Plan: <docs/plans/...-design.md>
- Verification Scope: local
- Verification Gate: must-pass
流程：
1) 先完成 brainstorming，并输出设计文档 `docs/plans/YYYY-MM-DD-<topic>-design.md`。
2) 询问我“是否进入 `docs/plans/` 实施计划编写阶段”，确认后使用 writing-plans 生成实现计划。
3) 实现计划内明确标注每步要改的文件与命令；验证步骤只包含可通过的局部验证，不包含测试。
4) 执行计划时只走主循环，并通过 `<deploy_root>/scripts/main_loop.py claim/finish` 更新 `memory-bank/progress.md`。
```
### AGENTS.template.md ### AGENTS.template.md
@ -268,23 +281,28 @@ project/
**playbook 标记**（用于自动更新）： **playbook 标记**（用于自动更新）：
| 标记 | 用途 | 说明 | - `<!-- playbook:agents:start/end -->`：语言规则链接。
| --------------------------------------- | ------------ | -------------------------- | 由 `[sync_standards]` 管理
| `<!-- playbook:agents:start/end -->` | 语言规则链接 | 由 `[sync_standards]` 管理 | - `<!-- playbook:templates:start/end -->`：路由链接。
| `<!-- playbook:templates:start/end -->` | 路由链接 | AGENTS.md 始终按区块更新 | `AGENTS.md` 始终按区块更新
| `<!-- playbook:framework:start/end -->` | 完整框架 | AGENTS.md 始终按区块更新 | - `<!-- playbook:framework:start/end -->`：完整框架。
`AGENTS.md` 始终按区块更新
### ci/、cpp/、python/ ### ci/、cpp/、python/
语言和 CI 配置模板。通过 playbook.py 的 `[vendor]` 复制到快照中： 语言和 CI 配置模板。通过 playbook.py 的 `[vendor]`
复制到快照中：
| 目录 | 内容 | 部署位置 | - `ci/gitea/`：Gitea Actions 工作流与辅助脚本。
| ----------- | ----------------------------------------- | ------------------------ | 部署到快照 `templates/ci/`
| `ci/gitea/` | Gitea Actions 工作流 | 快照 `templates/ci/` | - `cpp/`：`.clang-format`、`.clangd`、`CMakeLists.txt`
| `cpp/` | .clang-format, .clangd, CMakeLists.txt 等 | 快照 `templates/cpp/` | 等文件。
| `python/` | pyproject.toml, .editorconfig 等 | 快照 `templates/python/` | 部署到快照 `templates/cpp/`
- `python/`：`pyproject.toml`、`.editorconfig` 等文件。
部署到快照 `templates/python/`
> 注意：这些模板通过 `[vendor]` 复制到快照的 `templates/` 目录，需手动从快照复制到项目根目录使用。 > 注意：这些模板通过 `[vendor]` 复制到快照的 `templates/` 目录，需手动从快照复制到项目根目录使用。
> 其中 `ci/gitea/` 应按 `templates/ci/README.md` 的说明，整块复制 `.gitea/` 目录，而不只是复制 workflows。
**使用方式**： **使用方式**：
@ -311,8 +329,7 @@ playbook/
├── docs/ # 权威静态文档 ├── docs/ # 权威静态文档
├── templates/ # 本目录：项目架构模板 → 部署到 memory-bank/ 等 ├── templates/ # 本目录：项目架构模板 → 部署到 memory-bank/ 等
└── scripts/ └── scripts/
├── playbook.py # 统一入口：vendor/sync_rules/sync_memory_bank/sync_prompts/sync_standards/... └── playbook.py # 统一入口：vendor / sync_*
└── main_loop.py # 主循环领取与状态写回
``` ```
## 完整部署流程 ## 完整部署流程

48
templates/memory-bank/active-context.template.md Normal file
View File

@ -0,0 +1,48 @@
# 当前上下文
<!--
填写指南：
- 本文件记录高频变化的上下文，供 AI 在跨 Session 时快速恢复工作状态
- 保持简洁，只写“现在仍然重要”的信息
- 任务完成或方向切换后及时更新
-->
## Current Goal
<!-- 当前最重要的目标；一句话即可 -->
- {{CURRENT_GOAL}}
## Recent Changes
<!-- 最近完成且会影响后续判断的变更 -->
- {{RECENT_CHANGE_1}}
## Touched Files
<!-- 最近修改或正在关注的关键文件 -->
- `{{FILE_1}}` - {{FILE_1_REASON}}
## Open Questions
<!-- 尚未确认、但会影响实现或验证的事项 -->
- {{QUESTION_1}}
## Next Steps
<!-- 接下来最优先的 1-3 步 -->
1. {{NEXT_STEP_1}}
## Session Notes
<!-- 只记录本轮最容易忘的上下文 -->
- {{SESSION_NOTE_1}}
---
**最后更新**：{{DATE}}

60
templates/memory-bank/system-patterns.template.md Normal file
View File

@ -0,0 +1,60 @@
# 系统模式与约束
<!--
填写指南：
- 本文件记录跨模块稳定成立的实现模式，而不是一次性的设计草图
- 优先记录：模块边界、数据流、不变量、扩展路径、禁止破坏的约束
- 小项目可只保留最关键的 2-3 个部分
-->
## 模块边界
<!-- 至少列出主要模块及其职责边界 -->
### {{MODULE_1}}
- **职责**：{{MODULE_1_DESC}}
- **输入**：{{MODULE_1_INPUT}}
- **输出**：{{MODULE_1_OUTPUT}}
- **不应负责**：{{MODULE_1_NON_GOAL}}
## 关键数据流
<!-- 描述系统中的主路径；按“输入 -> 处理 -> 输出”写 -->
1. {{FLOW_STEP_1}}
2. {{FLOW_STEP_2}}
3. {{FLOW_STEP_3}}
## 核心不变量
<!-- 这些约束一旦被破坏，系统行为就可能失真 -->
- {{INVARIANT_1}}
## 常见实现模式
<!-- 给 AI 明确“这里通常怎么改” -->
### {{PATTERN_1}}
- **适用场景**：{{PATTERN_1_SCENARIO}}
- **推荐做法**：{{PATTERN_1_APPROACH}}
- **避免事项**：{{PATTERN_1_AVOID}}
## 扩展路径
<!-- 新增功能时，优先走哪些入口或目录 -->
1. {{EXTENSION_STEP_1}}
2. {{EXTENSION_STEP_2}}
## 禁止破坏的约束
<!-- 记录兼容性、安全性或组织层面的硬约束 -->
- {{DO_NOT_BREAK_1}}
---
**最后更新**：{{DATE}}

72
templates/memory-bank/tech-context.template.md Normal file
View File

@ -0,0 +1,72 @@
# 技术上下文与工具链
<!--
填写指南：
- 本文件记录“如何在这个仓库里安全工作”
- 优先填写命令、环境、入口路径、依赖限制
- 未填写的占位符保持原样或删除整行
-->
## 核心技术
<!-- 【必填】项目主要语言、框架、运行时 -->
- {{TECH_1}}
## 项目结构
<!-- 【必填】至少列出关键目录 -->
```text
{{PROJECT_NAME}}/
├── {{DIR_1}}/ # {{DIR_1_DESC}}
└── memory-bank/ # 项目上下文
```
## 关键入口
<!-- 【必填】AI 最常用的入口文件、命令或目录 -->
- `{{ENTRY_PATH_1}}` - {{ENTRY_PATH_1_DESC}}
## 开发环境
<!-- 【必填】至少填写验证相关命令 -->
**必需工具**：
- {{TOOL_1}}
**运行测试**：
```bash
{{TEST_CMD}}
```
**格式化 / Lint**：
```bash
{{FORMAT_OR_LINT_CMD}}
```
## 环境与平台差异
<!-- 【可选】如 Windows/Linux/macOS 行为不同，写在这里 -->
- {{ENV_DIFF_1}}
## 依赖与限制
<!-- 【可选】外部服务、私有依赖、危险命令、慢命令 -->
- {{DEPENDENCY_OR_LIMIT_1}}
## 验证约定
<!-- 【可选】什么叫“验证通过” -->
- {{PASS_CONDITION_1}}
---
**最后更新**：{{DATE}}

60
templates/prompts/coding/close-task.template.md Normal file
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` 状态块
---
**最后更新**：{{DATE}}

79
templates/prompts/coding/update-memory.template.md Normal file
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` 保持一致
---
**最后更新**：{{DATE}}

68
templates/prompts/coding/verify-change.template.md Normal file
View File

@ -0,0 +1,68 @@
# 变更验证模板
<!--
用途：在声明“完成 / 修复 / 可交付”前，明确验证范围与证据
触发：代码修改、配置修改、模板修改、规则修改后
-->
## 验证目标
- 这次改动要证明什么？
- 哪些行为必须通过？
- 哪些验证本轮不做？
## 验证步骤
### 1. 语法 / 结构检查
- 确认修改文件可读、可解析、无明显结构错误
### 2. 定向验证
- 只跑与本次改动直接相关的验证命令
- 记录命令、结果和关键输出
```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` 状态块
---
**最后更新**：{{DATE}}