# AGENT_RULES

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

## 优先级

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

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

**必读文档**（按顺序）：

1. `AGENT_RULES.local.md` - 项目私有规则（如存在，优先级高于本文件）
2. `memory-bank/project-brief.md` - 项目定位、边界、约束
3. `memory-bank/tech-stack.md` - 技术栈、工具链
4. `memory-bank/architecture.md` - 架构设计、模块职责
5. `docs/plans/` - 最新实施计划（如存在）

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

## 主循环

1. 选择当前 Plan 文档（优先 `docs/plans/` 最新计划）
2. 阅读 Plan 内容与执行顺序
3. 执行该 Plan 内所有可执行子任务
4. 校验输出结果（运行测试/检查日志）
5. **更新 `memory-bank/progress.md`**（记录已完成事项）
6. 如存在歧义/风险/决策点，在回复中明确提出，并视需要记录到 `memory-bank/decisions.md`
7. 若 Plan 已全部完成，更新 Plan 状态并在 `memory-bank/progress.md` 记录完成
8. 若 Plan 因缺少信息而阻塞，在 `memory-bank/progress.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 中所有可执行的子任务
- 若因缺少信息/决策而阻塞：在 `memory-bank/progress.md` 记录阻塞原因
- 每轮只处理一个 Plan
- **小步快跑**：每个 Plan 应该可快速完成
- **可验证**：每个 Plan 必须包含验证步骤

## 执行约束

### 代码修改约束

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

### 决策记录约束

- **重要决策**：记录到 `memory-bank/decisions.md`（ADR 格式）
- **待确认事项**：在回复中列出并等待确认
- **进度留痕**：记录到 `memory-bank/progress.md`（持久化）

## 需要确认的场景

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

## 验证清单

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

- [ ] 代码修改符合 `.agents/` 下的规则
- [ ] 相关测试通过
- [ ] 换行符正确
- [ ] 无语法错误
- [ ] 更新了 `memory-bank/progress.md`

---

**最后更新**：{{DATE}}