tsl-devkit/templates/AGENT_RULES.template.md

AGENT_RULES

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

优先级

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

安全与沟通

安全红线

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

沟通原则

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

工作原则

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

会话启动

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

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/：相关实施计划（如存在）

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

规划与执行模型

• 头脑风暴使用 $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 要求

• 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：永久跳过，不再执行

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

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

• 自动识别当前环境：windows、linux、darwin
• 按顺序选择可执行 Plan： in-progress > pending > blocked: env:<当前环境>:...
• 将选中的 Plan 写成 in-progress

这里的锁保护的是 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

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

Plan 场景下的分支与隔离策略

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

执行规则

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

通用执行约束

代码与配置修改

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

决策与留痕

• 重要决策记录到 memory-bank/decisions.md
• 待确认事项在回复中显式列出
• workflow-state 和 plan-status 只能通过 {{PLAYBOOK_SCRIPTS}}/main_loop.py 维护
• progress.md 上半部分的人类摘要在阶段变化或执行结束后同步更新
• 同一错误重复两次以上时，立即更新 AGENT_RULES.local.md 或 memory-bank/decisions.md
• 发现项目特有规律时，沉淀到 AGENT_RULES.local.md

Git 操作

• 不使用 --amend，除非用户明确要求
• 不使用 --force；如用户坚持，必须先说明风险
• 不使用 --no-verify 跳过 hooks

工具使用

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

需要确认的场景

常规模式

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

无交互模式

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

可以直接执行

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

Session 收尾

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

验证清单

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

• 代码修改符合 .agents/ 下的规则（如有）
• 相关验证已执行，且测试在未豁免时通过
• 换行符与文件格式正确
• 无语法错误或明显运行时错误
• 已通过 main_loop.py finish 写回 Plan 状态

---

最后更新：{{DATE}}