playbook/templates/AGENT_RULES.template.md

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：

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列表>。

写回状态：

# 完成
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）：

python {{PLAYBOOK_SCRIPTS}}/main_loop.py status \
  -plans docs/superpowers/plans \
  -progress memory-bank/progress.md

规划留痕：

# 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}}