16 KiB

Raw Blame History

AGENT_RULES

目的：为本仓库提供稳定的执行流程与行为规范。

本文件是项目内唯一流程约束中心；docs/superpowers/ 是唯一设计与计划产物中心；执行状态统一写回 memory-bank/progress.md。

优先级

系统/开发者指令与安全约束
项目私有规则：AGENT_RULES.local.md（如存在）
仓库规则：.agents/ 与 AGENTS.md
本文件

安全与沟通

安全红线

不得在代码、日志或注释中写入明文密钥、密码、Token
修改鉴权、权限或敏感数据流时，必须说明动机与风险
不确定是否敏感时，一律按敏感信息处理
执行会修改文件系统的命令前，必须说明目的与潜在影响

沟通原则

统一使用简体中文
专业、直接、简洁，避免对话填充词
发现用户理解有误时，礼貌纠正
无法满足请求时，简洁说明原因并提供替代方案
不给时间估算，专注事实、风险与下一步
代码块必须标注语言类型
不使用 emoji，除非用户明确要求

工作原则

模仿项目现有风格，先看周围代码、配置和测试再动手
不假设库、框架或命令可用，先验证再使用
完整覆盖用户请求，不遗漏边界条件和收尾工作
技术准确性优先于迎合；不确定时先调查再回答
只做当前任务需要的改动，不顺手加功能、不顺手重构
不为一次性操作增加抽象，不为假设的未来需求设计

项目边界

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 时才纳入

会话启动

每次新会话开始时，按顺序加载以下上下文：

AGENT_RULES.local.md：项目私有规则（如存在）
.agents/index.md：语言规则与工具入口（如存在）
memory-bank/project-brief.md：项目定位、边界、约束
memory-bank/tech-context.md：技术上下文、工具链、验证命令
memory-bank/system-patterns.md：系统模式、边界与不变量
memory-bank/active-context.md：当前目标、最近变更、下一步
memory-bank/decisions.md：重要决策记录（如存在）
memory-bank/progress.md：执行进度与 Plan 状态（如存在）
docs/superpowers/specs/：最新设计稿（如存在）
docs/superpowers/plans/：相关实施计划（如存在）

目的：快速建立项目全貌，避免重复解释和重复试错。

规划与执行模型

头脑风暴使用 $brainstorming，产出 docs/superpowers/specs/*-design.md
实施计划使用 $writing-plans，产出 docs/superpowers/plans/*.md
Plan 生命周期由 main_loop.py 协调，并通过 memory-bank/progress.md 留痕
默认执行器是 $executing-plans
代码类执行必须同时遵循： karpathy-guidelines、.agents/、AGENT_RULES.md

重要约束：

规划阶段必须走 using-superpowers -> brainstorming -> writing-plans
brainstorming 写出 spec 后，立即用 playbook.py -record-spec 记录 phase=planning 与 spec=<path>
writing-plans 写出 plan 后，立即用 playbook.py -record-plan 记录 plan=<path>、executor=executing-plans、 constraints=karpathy-guidelines,.agents,AGENT_RULES
未领取 Plan 前，不得直接进入 $executing-plans
已领取 Plan 后，默认执行使用 $executing-plans
$subagent-driven-development 仅在 Plan 或平台明确要求时使用，不是默认执行器
执行完成后，必须先运行 main_loop.py finish 写回状态，再更新 progress.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 至少包含：
- Plan Group
- Parent Plan
- Verification Scope
- Verification Gate
Plan 中不得包含必然失败或依赖未确认的信息
未确认项必须在 $brainstorming 阶段解决后，才能产出 Plan
Plan 内验证必须是当前阶段可通过的局部验证
需要集成验证的内容，放入上层或集成 Plan
Plan 生成完成后，执行入口只能是主循环
代码类 Plan 应显式声明执行约束： karpathy-guidelines、.agents/、AGENT_RULES.md
不因等待确认而中断可执行步骤；待确认事项写入回复
每个 Plan 应小步、可验证、可快速完成

主循环执行契约

触发方式

常规模式：执行主循环、继续执行、下一个 Plan
无交互模式：自动执行所有 Plan

Plan 状态

pending：待执行
in-progress：执行中，用于恢复中断任务
done：已完成
blocked：阻塞，需人工介入或切换环境
skipped：永久跳过，不再执行，workflow-state.phase 也写为 skipped

skipped 如需恢复，必须手动改回 pending。

环境阻塞格式

格式：env:<环境>:<Task列表>
示例：env:windows:Task2,Task4
Task 列表必须使用英文逗号分隔，且不要包含空格

领取与写回

领取命令：

python {{PLAYBOOK_SCRIPTS}}/main_loop.py claim \
  -plans docs/superpowers/plans \
  -progress memory-bank/progress.md \
  -owner "<当前session或agent标识>"

该命令会在锁保护下串行完成三件事：

自动识别当前环境：windows、linux、darwin
校验 Plan 文件包含必需 Plan Meta
已有 in-progress 优先恢复
如无 in-progress，按 Plan 文件顺序选择第一个可执行 Plan： pending 或 blocked: env:<当前环境>:...
将选中的 Plan 写成 in-progress
在 workflow-state 写入 claimed_by、claimed_at，并清理上一轮 verification

这里的锁保护的是 progress.md 状态块更新，避免多个 session 同时读写时发生覆盖。

stdout 必须包含：

PLAN=<path>
如为环境恢复，还会附带 NOTE=env:<环境>:<Task列表>

规划与执行留痕示例：

# 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

写回命令示例：

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 "<原因>"

只读状态命令：

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

status 只汇总 pending、in-progress、done、blocked、 skipped 和当前 workflow-state，不得修改 progress.md。

Plan 场景下的执行上下文与隔离策略

本节仅适用于通过主循环领取并执行 Plan 的场景
默认允许在当前项目上下文直接执行 Plan
不强制为 Plan 执行创建隔离上下文
仅在以下场景使用隔离工作区：
- 用户明确要求隔离执行
- Plan 文本自身明确要求隔离执行
- 当前任务需要并行隔离以避免相互影响
如外部技能、工具或默认流程要求先隔离，再执行 Plan，以本文件和用户当前指令为准

执行规则

先 claim，拿到 PLAN= 后再读取 Plan 内容
如返回 NOTE=env:...，本轮只执行列出的 Task
默认执行器是 $executing-plans；代码类任务在执行前必须显式加载 karpathy-guidelines
执行时同时遵循 .agents/、AGENT_RULES.md 和 Plan 本身；如发生冲突，以优先级更高的规则为准
按顺序执行 Task，并完成 Plan 约定的验证
环境不匹配时，记录所需环境和 Task，继续处理本 Plan 其余可执行 Task
其他阻塞写回 blocked；永久放弃写回 skipped
触碰安全红线时立即停止，不继续后续 Plan
常规模式下可对高风险事项向用户确认；无交互模式按本文件的“需要确认的场景”自动处理
每次 claim 只领取一个 Plan；写回并归档当前 Plan 变更后再领取下一个
全部 Plan 处理完后，统一汇总完成项、阻塞项、跳过项、环境需求与待确认事项

Plan 完成归档契约

归档指按当前项目约定创建可回溯的交付记录；具体机制由项目本地规则或用户指令定义
main_loop.py finish -status done 只负责写回机器状态，不代表 Plan 已完成交付；memory 更新或回复摘要也不等同于归档
Plan done 后必须完成当前 Plan 变更的归档/提交，然后才能继续领取下一个 Plan；归档方式由项目约定决定
收尾顺序：

完成 Plan 约定验证
运行 main_loop.py finish -status done -verified "<证据>" 写回状态
必要时更新 progress.md 上半部分摘要和相关 memory
检查当前变更清单与差异
只归档/提交当前 Plan 相关改动

当前 Plan 相关改动包括但不限于：
- 本轮代码、配置、测试、模板改动
- 当前 Plan 文件（创建、补充、勾选 Task、记录结果等）
- memory-bank/progress.md 中本轮 workflow-state、plan-status 与摘要更新
- 必要 memory 更新，例如 active-context.md、decisions.md
Plan 范围是归档/提交边界，不以整个工作区是否干净作为唯一判断
允许存在其他 session 的未归档改动，只要它们不属于当前 Plan、不与当前 Plan 范围冲突、且不会被混入本轮归档/提交
不得由 main_loop.py finish 自动执行提交或变更归档
不得把用户已有改动或其他 Plan 的改动混入当前 Plan 交付单元
如 Plan done 后没有当前 Plan 相关差异，必须在回复中说明无归档原因
如当前 Plan 相关差异仍未归档，只能声明“状态已写回，交付未完成”，不得声明 Plan 完成
blocked / skipped 不默认归档/提交代码改动；只有状态留痕或已验证的局部成果需要保留时才归档/提交
继续领取下一个 Plan 前，必须确认当前 Plan 无遗留差异；如剩余差异属于其他 session 或其他 Plan，保留在原处并在报告中说明
如剩余差异与当前 Plan 或下一个 Plan 的预期范围冲突，常规模式先向用户确认；无交互模式写入风险并停止继续领取

通用执行约束

代码与配置修改

必须先读文件再修改
遵循 .agents/、项目代码风格和现有命名约定
只改必要部分，不顺手重构无关内容
执行与改动相称的验证；如有相关测试且未被豁免，必须通过
遵循项目声明的换行与文件格式规则

决策与留痕

重要决策记录到 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
发现项目特有规律时，沉淀到 AGENT_RULES.local.md

归档操作

不改写既有归档历史，除非用户明确要求
不覆盖他人或其他 session 的归档成果；如用户坚持，必须先说明风险
不跳过项目约定的归档前检查
如项目没有归档机制，在回复中列出本轮交付的文件清单与验证证据

工具使用

独立步骤尽可能并行执行
严格遵循工具参数定义与 schema
优先使用专用工具，不重复探测同一信息
文本搜索优先使用 rg

需要确认的场景

常规模式

需求不明确，或存在多种可行方案
需要行为、兼容性或性能取舍
涉及架构变更、破坏性修改或约束冲突
风险较高，且继续执行可能放大返工成本

无交互模式

安全红线：立即停止，不继续后续 Plan
架构变更、兼容性问题、破坏性修改：写回 blocked
多种可行方案：选择最保守方案，并在报告中说明理由
一般歧义、风险或决策点：记录到报告，继续执行安全部分

可以直接执行

明显的 bug 修复
符合现有模式的小改动
测试用例补充或局部验证补齐

Session 收尾

汇总已完成、阻塞、跳过的 Plan 及原因
标出需要其他环境处理的事项：env:<环境>:<Task列表>
必要时将重要结论写入 memory-bank/decisions.md
出现以下情况时，建议开启新 Session：
- 当前方向明显跑偏
- 讨论阶段产出多个候选方案，准备进入执行
- Session 过长，开始重复犯同类错误

验证清单

每个 Plan 完成后，至少确认：

代码修改符合 .agents/ 下的规则（如有）
相关验证已执行，且测试在未豁免时通过
换行符与文件格式正确
无语法错误或明显运行时错误
已通过 main_loop.py finish 写回 Plan 状态
Plan done 后已完成当前 Plan 变更归档/提交，或已说明无当前 Plan 差异无需归档

最后更新：{{DATE}}

16 KiB Raw Blame History Unescape Escape