playbook/templates/AGENT_RULES.template.md

AGENT_RULES

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

优先级

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

安全红线

• 不得在代码/日志/注释中写入明文密钥、密码、Token
• 修改鉴权/权限逻辑必须说明动机与风险
• 不确定是否敏感时按敏感信息处理

上下文加载（每次会话开始）

必读文档（按顺序）：

1. AGENT_RULES.local.md - 项目私有规则（如存在，优先级高于本文件）
2. .agents/index.md - 语言规则入口（如存在）
3. memory-bank/project-brief.md - 项目定位、边界、约束
4. memory-bank/tech-stack.md - 技术栈、工具链
5. memory-bank/architecture.md - 架构设计、模块职责
6. memory-bank/decisions.md - 重要决策记录（如存在）
7. memory-bank/progress.md - 执行进度与状态（如存在）
8. docs/plans/ - 最新实施计划（如存在）

目的：让 AI 快速理解项目全貌，避免重复解释。

主循环

0. 选择 Plan：
   • 运行 python {{PLAYBOOK_SCRIPTS}}/plan_progress.py select -plans docs/plans -progress memory-bank/progress.md
   • 如无可执行 Plan，说明情况并询问用户下一步（新增 Plan/切换任务/结束）
1. 标记开始：
   • python {{PLAYBOOK_SCRIPTS}}/plan_progress.py record -plan <plan> -status in-progress -progress memory-bank/progress.md
2. 阅读 Plan：
   • 理解目标、子任务与验证标准
3. 逐步执行：
   • 按顺序执行子任务
   • 每步完成后进行必要验证（测试/日志/diff）
   • 遇到阻塞立即记录并停止
4. 记录结果（写入 memory-bank/progress.md）：
   • 完成：python {{PLAYBOOK_SCRIPTS}}/plan_progress.py record -plan <plan> -status done -progress memory-bank/progress.md
   • 阻塞：python {{PLAYBOOK_SCRIPTS}}/plan_progress.py record -plan <plan> -status blocked -progress memory-bank/progress.md -note <原因>
5. 如存在歧义/风险/决策点，在回复中明确提出，并视需要记录到 memory-bank/decisions.md

Plan 规则

• Plan Meta 必填：Plan 头部 --- 之后、Task 1 之前插入 ## Plan Meta，包含：
  • Plan Group（归类任务）
  • Parent Plan（上层/集成计划链接）
  • Verification Scope（local 或 integration）
  • Verification Gate（must-pass）
• 不允许中断任务：Plan 中不应包含必然失败或依赖未确认的信息；未确认项必须在 $brainstorming 阶段解决后再产出 Plan
• 验证必须可通过：Plan 内验证应为当前阶段可通过的局部验证；需要集成验证的内容放入上层/集成 Plan
• 不因等待确认而中断可执行步骤；待确认事项在回复中列出
• 每轮只处理一个 Plan
• 小步快跑：每个 Plan 应该可快速完成
• 可验证：每个 Plan 必须包含验证步骤

执行约束

代码修改约束

• 必须先读文件再修改：不读文件就提议修改是禁止的
• 必须运行测试验证：相关测试必须通过
• 遵循换行规则：遵循 .gitattributes 规则

决策记录约束

• 重要决策：记录到 memory-bank/decisions.md（ADR 格式）
• 待确认事项：在回复中列出并等待确认
• 进度留痕：通过 {{PLAYBOOK_SCRIPTS}}/plan_progress.py 写入 memory-bank/progress.md，该文件为 Plan 状态唯一权威

需要确认的场景

• 需求不明确或存在多种可行方案
• 需要行为/兼容性取舍
• 风险或约束冲突
• 架构变更：影响多个模块的修改
• 性能权衡：需要在性能和可维护性之间选择
• 兼容性问题：可能破坏现有用户代码

验证清单

每个 Plan 完成后，必须验证：

• 代码修改符合 .agents/ 下的规则（如有）
• 相关测试通过（如有测试且未被豁免）
• 换行符正确
• 无语法错误
• 已更新 memory-bank/progress.md

---

最后更新：{{DATE}}