101 lines
4.0 KiB
Markdown
101 lines
4.0 KiB
Markdown
# 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}}
|