323 lines
14 KiB
Markdown
323 lines
14 KiB
Markdown
# AGENT_RULES
|
||
|
||
目的：为本仓库提供稳定的执行流程与行为规范。
|
||
|
||
本文件是框架流程约束基线；`docs/superpowers/`
|
||
是唯一设计与计划产物中心；执行状态统一写回
|
||
`memory-bank/progress.md`。
|
||
|
||
## 优先级
|
||
|
||
1. 系统/开发者指令
|
||
2. 项目私有规则：`AGENT_RULES.local.md`（如存在）
|
||
3. 仓库规则：`.agents/` 与 `AGENTS.md`
|
||
4. 本文件
|
||
|
||
## 沟通原则
|
||
|
||
- 统一使用简体中文
|
||
- 专业、直接、简洁，避免对话填充词
|
||
- 发现用户理解有误时，礼貌纠正
|
||
- 无法满足请求时，简洁说明原因；如有可行替代方案则一并给出
|
||
- 不给时间估算，专注事实、风险与下一步
|
||
|
||
## 项目边界
|
||
|
||
### Playbook 目录
|
||
|
||
- `{{PLAYBOOK_ROOT}}/` 是 Playbook 模板/供应商目录，不是业务项目源码、
|
||
业务文档或当前项目私有规则
|
||
- 除非用户明确要求维护、升级或调试 Playbook 本身，不得修改
|
||
`{{PLAYBOOK_ROOT}}/` 下内容
|
||
- 当前项目的生效规则是项目根目录的 `AGENT_RULES.md`、`AGENT_RULES.local.md`、
|
||
`AGENTS.md` 与 `.agents/`；`{{PLAYBOOK_ROOT}}/templates/` 与
|
||
`{{PLAYBOOK_ROOT}}/rulesets/` 只是模板源，不是当前项目已生效规则
|
||
- 可按 `.agents/` 指向读取 `{{PLAYBOOK_ROOT}}/docs/` 作为标准文档；
|
||
读取不代表该目录属于业务改动范围
|
||
- 搜索、批量修改、代码审查、归档/提交时，默认排除 `{{PLAYBOOK_ROOT}}/`；
|
||
只有任务目标明确涉及 Playbook 时才纳入
|
||
|
||
## 会话启动
|
||
|
||
每次新会话开始时，按以下建议顺序加载上下文以快速建立项目全貌；
|
||
清单中文件不存在则跳过：
|
||
|
||
1. `AGENT_RULES.local.md`：项目私有规则
|
||
2. `.agents/index.md`：语言规则与工具入口
|
||
3. `memory-bank/project-brief.md`：项目定位、边界、约束
|
||
4. `memory-bank/tech-context.md`：技术上下文、工具链、验证命令
|
||
5. `memory-bank/system-patterns.md`：系统模式、边界与不变量
|
||
6. `memory-bank/active-context.md`：当前目标、最近变更、下一步
|
||
7. `memory-bank/decisions.md`：重要决策记录
|
||
8. `memory-bank/progress.md`：执行进度与 Plan 状态
|
||
9. `docs/superpowers/specs/`：最新设计稿
|
||
10. `docs/superpowers/plans/`：相关实施计划
|
||
|
||
**执行约束**：加载顺序可调整，但在处理首个实质性任务前（修改文件、运行项目命令、给出实现结论），必须先完成上述相关上下文加载。
|
||
|
||
## 规划与执行模型
|
||
|
||
> 记号约定：`$<skill-name>` 表示在对话中点名触发的 skill（如
|
||
> `$brainstorming`）；无 `$` 的同名 skill 指其阶段或产物，二者指向同一 skill。
|
||
> `using-superpowers` 是会话启动时判断并加载适用 skill 的入口 skill。
|
||
|
||
- 规划阶段必须走 `using-superpowers -> brainstorming -> writing-plans`
|
||
- `$brainstorming` 产出 `docs/superpowers/specs/*-design.md`；写出 spec 后
|
||
立即用 `playbook.py -record-spec` 记录 `phase=planning` 与 `spec=<path>`
|
||
- `$writing-plans` 产出 `docs/superpowers/plans/*.md`；写出 plan 后立即用
|
||
`playbook.py -record-plan` 记录 `plan=<path>`、`executor=executing-plans`、
|
||
`constraints=karpathy-guidelines,.agents,AGENT_RULES`
|
||
- spec/plan 产出阶段不单独提交或归档，只做文件落地与状态留痕；如外部 skill
|
||
要求写完后立即提交，以本文件为准，推迟到 Plan 完成后统一处理
|
||
- Plan 生命周期由 `main_loop.py` 协调，通过 `memory-bank/progress.md` 留痕
|
||
- Plan 执行入口只能是主循环：领取前不得进入 `$executing-plans`，领取后默认用
|
||
`$executing-plans` 执行，`$subagent-driven-development` 仅在 Plan 或平台明确要求时使用
|
||
- 代码类执行必须同时遵循 `$karpathy-guidelines`、`.agents/`、`AGENT_RULES.md`
|
||
- 执行完成后按「Plan 完成归档契约」收尾
|
||
|
||
### 条件触发 Skills
|
||
|
||
以下 skill 是额外能力，只在满足触发条件时使用，不改变主流程顺序，
|
||
也不由 `main_loop.py` 自动调度：
|
||
|
||
| Skill | 触发条件 | 负责范围 |
|
||
| ------------------ | -------------------------------------- | -------------------------------------- |
|
||
| `codebase-recon` | 架构、跨模块、重构、迁移或风险不明任务 | 代码库侦察、热点分析、影响面判断 |
|
||
| `brooks-audit` | 方案影响架构边界、模块职责或长期维护性 | 架构审查、结构风险识别 |
|
||
| `codebase-migrate` | 大规模迁移、多文件重构、API 替换 | 分批迁移、可审查 refactor、CI 验证节奏 |
|
||
| `brooks-review` | 代码类 Plan 完成后，归档前需要审查 | diff / PR 级代码审查 |
|
||
| `brooks-test` | 测试改动复杂，或需要确认测试质量 | 测试有效性、覆盖边界、断言质量审查 |
|
||
| `gitea-fix-ci` | Gitea Actions 失败 | 拉取 CI 日志、定位失败、形成修复计划 |
|
||
| `style-cleanup` | 代码实现后需要格式或 lint 收尾 | 格式化、lint cleanup，不改变语义 |
|
||
| `commit-message` | 需要提交或归档当前 Plan 改动 | commit message 生成与 staged diff 检查 |
|
||
|
||
### Plan 要求
|
||
|
||
- `Plan Meta` 必填，位于 Plan 头部 `---` 之后、Task 1 之前
|
||
- `Plan Meta` 至少包含：
|
||
- `Verification Scope`
|
||
- `Verification Gate`
|
||
- Plan 不得包含必然失败或未确认的内容；未确认项须在 `$brainstorming`
|
||
阶段解决后才能产出 Plan
|
||
- Plan 内验证必须是当前阶段可通过的局部验证；跨 Plan 的集成验证自成一个独立 Plan
|
||
- 每个 Plan 应自身可独立交付，不依赖其他 Plan 的执行结果；有先后顺序的工作
|
||
放入同一 Plan 的有序 Task，不跨 Plan 表达执行依赖
|
||
- 不因等待确认而中断可执行步骤；待确认事项写入回复
|
||
- 每个 Plan 应小步、可验证、可快速完成
|
||
|
||
## 主循环执行契约
|
||
|
||
### 触发方式
|
||
|
||
- 常规模式：`执行主循环`、`继续执行`、`下一个 Plan`
|
||
- 无交互模式：`自动执行所有 Plan`
|
||
|
||
### Plan 状态
|
||
|
||
- `pending`：待执行
|
||
- `in-progress`：执行中，用于恢复中断任务
|
||
- `done`：已完成
|
||
- `blocked`：阻塞，需人工介入或切换环境
|
||
- `skipped`：永久跳过，不再执行，`workflow-state.phase` 也写为
|
||
`skipped`
|
||
|
||
`skipped` 如需恢复，必须手动改回 `pending`。
|
||
|
||
### 环境阻塞格式
|
||
|
||
- 格式：`env:<环境>:<Task列表>`
|
||
- 示例：`env:windows:Task2,Task4`
|
||
- `Task` 列表必须使用英文逗号分隔，且不要包含空格
|
||
|
||
### 领取与写回
|
||
|
||
**领取 Plan**：
|
||
|
||
```bash
|
||
python {{PLAYBOOK_SCRIPTS}}/main_loop.py claim \
|
||
-plans docs/superpowers/plans \
|
||
-progress memory-bank/progress.md \
|
||
-owner "<当前session或agent标识>"
|
||
```
|
||
|
||
该命令在锁保护下完成：自动识别当前环境（windows/linux/darwin）、校验 Plan Meta、优先恢复 `in-progress`、选择第一个可执行 Plan、写入 `claimed_by`/`claimed_at` 并清理上一轮 `verification`。
|
||
|
||
stdout 必须包含 `PLAN=<path>`；如为环境恢复，还会附带 `NOTE=env:<环境>:<Task列表>`。
|
||
|
||
**写回状态**：
|
||
|
||
```bash
|
||
# 完成
|
||
python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
|
||
-plan <plan> -status done \
|
||
-progress memory-bank/progress.md \
|
||
-verified "<本轮已通过的验证命令或证据>"
|
||
|
||
# 阻塞（环境）
|
||
python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
|
||
-plan <plan> -status blocked \
|
||
-progress memory-bank/progress.md \
|
||
-note "env:<所需环境>:<Task列表>"
|
||
|
||
# 阻塞/跳过（其他原因）
|
||
python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
|
||
-plan <plan> -status blocked|skipped \
|
||
-progress memory-bank/progress.md \
|
||
-note "<原因>"
|
||
```
|
||
|
||
**查看状态**（只读，不修改 progress.md）：
|
||
|
||
```bash
|
||
python {{PLAYBOOK_SCRIPTS}}/main_loop.py status \
|
||
-plans docs/superpowers/plans \
|
||
-progress memory-bank/progress.md
|
||
```
|
||
|
||
**规划留痕**：
|
||
|
||
```bash
|
||
# brainstorming 完成后
|
||
python {{PLAYBOOK_SCRIPTS}}/playbook.py \
|
||
-record-spec docs/superpowers/specs/<topic>-design.md \
|
||
-progress memory-bank/progress.md
|
||
|
||
# writing-plans 完成后
|
||
python {{PLAYBOOK_SCRIPTS}}/playbook.py \
|
||
-record-plan docs/superpowers/plans/<topic>.md \
|
||
-progress memory-bank/progress.md
|
||
```
|
||
|
||
### Plan 场景下的执行上下文与隔离策略
|
||
|
||
- 本节仅适用于通过主循环领取并执行 Plan 的场景
|
||
- 默认在当前项目上下文直接执行 Plan，不强制创建隔离上下文
|
||
- 仅在以下场景使用隔离工作区：
|
||
- 用户明确要求隔离执行
|
||
- Plan 文本自身明确要求隔离执行
|
||
- 当前任务需要并行隔离以避免相互影响
|
||
- 如外部技能、工具或默认流程要求先隔离，再执行 Plan，以本文件和用户当前指令为准
|
||
|
||
### 执行规则
|
||
|
||
1. 先 `claim`，拿到 `PLAN=` 后再读取 Plan 内容
|
||
2. 如返回 `NOTE=env:...`，本轮只执行列出的 Task
|
||
3. 代码类任务在执行前必须显式加载 `$karpathy-guidelines`
|
||
4. 执行时同时遵循 `.agents/`、`AGENT_RULES.md` 和 Plan
|
||
5. 按顺序执行 Task，并完成 Plan 约定的验证
|
||
6. 环境不匹配时，记录所需环境和 Task，继续处理本 Plan
|
||
其余可执行 Task
|
||
7. 其他阻塞写回 `blocked`；永久放弃写回 `skipped`
|
||
8. 遇到决策点时按「需要确认的场景」处理：常规模式下满足该节
|
||
条件的先向用户确认；无交互模式按该节自动处理
|
||
9. 每次 `claim` 只领取一个 Plan；写回并归档当前 Plan 变更后
|
||
再领取下一个
|
||
10. 全部 Plan 处理完后，统一汇总完成项、阻塞项、跳过项、
|
||
环境需求与待确认事项
|
||
|
||
### Plan 完成归档契约
|
||
|
||
**核心原则**：
|
||
|
||
- Plan `done` 后必须完成当前 Plan 变更的归档/提交，然后才能继续领取下一个 Plan
|
||
- `main_loop.py finish -status done` 只负责写回机器状态，不自动提交或归档，不代表已完成交付
|
||
- Plan 范围是归档/提交边界，不以整个工作区是否干净作为唯一判断
|
||
|
||
**收尾顺序**：
|
||
|
||
1. 完成 Plan 约定验证
|
||
2. 运行 `main_loop.py finish -status done -verified "<证据>"` 写回状态
|
||
3. 必要时更新 `progress.md` 上半部分摘要和相关 memory
|
||
4. 检查当前变更清单与差异
|
||
5. 只归档/提交当前 Plan 相关改动
|
||
|
||
**当前 Plan 相关改动包括**：
|
||
|
||
- 本轮代码、配置、测试、模板改动
|
||
- 当前 Plan 文件（创建、补充、勾选 Task、记录结果等）
|
||
- `memory-bank/progress.md` 中本轮 `workflow-state`、`plan-status` 与摘要更新
|
||
- 必要 memory 更新（如 `active-context.md`、`decisions.md`）
|
||
|
||
**归档约束**：
|
||
|
||
- 不得把用户已有改动或其他 Plan/session 的改动混入当前 Plan 交付单元；
|
||
这类改动只要不属于、不冲突当前 Plan，允许其未归档共存
|
||
- 如 Plan `done` 后没有当前 Plan 相关差异，必须在回复中说明无归档原因
|
||
- 如当前 Plan 相关差异仍未归档，只能声称「状态已写回，交付未完成」，不得声称 Plan 完成
|
||
- `blocked` / `skipped` 不默认归档/提交代码改动；只有状态留痕或已验证的局部成果需要保留时才归档
|
||
- 继续领取下一个 Plan 前，必须确认当前 Plan 无遗留差异；如剩余差异与当前 Plan 或下一个 Plan 的预期范围冲突，常规模式先向用户确认；无交互模式将当前 Plan 写回 `blocked` 并记录冲突，继续领取下一个
|
||
|
||
### 决策与留痕
|
||
|
||
- 重要决策记录到 `memory-bank/decisions.md`
|
||
- 待确认事项在回复中显式列出
|
||
- `workflow-state` 和 `plan-status` 只能通过
|
||
`{{PLAYBOOK_SCRIPTS}}/main_loop.py` 维护
|
||
- `progress.md` 上半部分是短期状态快照，不是 changelog；
|
||
阶段变化或执行结束后整理/替换摘要，不做无限追加
|
||
- `active-context.md` 是短期上下文快照，不是长期日志；
|
||
只保留当前 Plan / 下一轮仍重要的目标、变化、文件与下一步
|
||
- 同一错误重复两次以上，或发现项目特有规律时，沉淀到
|
||
`AGENT_RULES.local.md`（决策类记入 `memory-bank/decisions.md`）
|
||
|
||
### 归档操作
|
||
|
||
- 不改写既有归档历史，除非用户明确要求
|
||
- 不覆盖他人或其他 session 的归档成果；如用户坚持，必须先说明风险
|
||
- 不跳过项目约定的归档前检查
|
||
- 如项目没有归档机制，在回复中列出本轮交付的文件清单与验证证据
|
||
|
||
## 需要确认的场景
|
||
|
||
### 常规模式
|
||
|
||
执行 Plan 过程中，遇到以下决策点先向用户确认：
|
||
|
||
- 需求不明确，或存在多种可行方案
|
||
- 需要行为、兼容性或性能取舍
|
||
- 涉及架构变更、破坏性修改或约束冲突
|
||
- 风险较高，且继续执行可能放大返工成本
|
||
|
||
以下 Plan 改动可直接推进，无需确认：
|
||
|
||
- 明显的 bug 修复
|
||
- 符合现有模式的小改动
|
||
- 测试用例补充或局部验证补齐
|
||
|
||
### 无交互模式
|
||
|
||
严格按 Plan 的 Task 执行，不自行做设计决策；一个 Plan 卡住不影响其余 Plan，
|
||
继续领取下一个，直到所有 Plan 处理完毕：
|
||
|
||
- Task 明确可执行：直接执行
|
||
- Task 存在歧义或需要未在 Plan 中确认的设计决策：写回 `blocked`，不猜测、不替代设计
|
||
（此类决策本应在 `$brainstorming` 阶段解决，缺失说明 Plan 不合格）
|
||
- 需要架构变更、破坏性修改，且 Plan 未明确授权：写回 `blocked`
|
||
- 环境不匹配：记录 `env:<环境>:<Task列表>`，跳过该 Task，继续本 Plan 其余 Task
|
||
|
||
每个被 `blocked` 的 Plan 记录原因，继续领取下一个，不因单个 Plan 卡住而中止整批。
|
||
|
||
## Session 收尾
|
||
|
||
出现以下情况时，建议开启新 Session：
|
||
|
||
- 当前方向明显跑偏
|
||
- 讨论阶段产出多个候选方案，准备进入执行
|
||
- Session 过长，开始重复犯同类错误
|
||
|
||
## 验证清单
|
||
|
||
每个 Plan 完成后，至少确认：
|
||
|
||
- [ ] 代码修改符合 `.agents/` 下的规则（如有）
|
||
- [ ] 相关验证已执行，且测试在未豁免时通过
|
||
- [ ] 换行符与文件格式正确
|
||
- [ ] 无语法错误或明显运行时错误
|
||
- [ ] 已通过 `main_loop.py finish` 写回 Plan 状态
|
||
- [ ] Plan `done` 后已完成当前 Plan 变更归档/提交，或已说明无当前 Plan
|
||
差异无需归档
|
||
|
||
---
|
||
|
||
**最后更新**：{{DATE}}
|