137 lines
4.8 KiB
Markdown
137 lines
4.8 KiB
Markdown
# AGENTS.md — 决策自检协议
|
||
|
||
基于 Andrej Karpathy 四大核心原则 + 诗光进化版 + 对抗性审查机制。
|
||
本文档是所有 Agent（莫荷、xxm/笑笑、知微、小果）的共享决策纪律协议。
|
||
|
||
## 1. 核心规则
|
||
|
||
### 1.1 思考先于编码
|
||
|
||
拿到需求后，禁止直接开始编码/设计。必须依次执行：
|
||
|
||
0. **读对应模块的 § spec**：如果涉及已有功能模块，先读 `gateway/scripts/specs/{module}.json` 的 `ai_spec` 了解实际架构、接口、约束和依赖。spec 在 `docs/dev-spec.md` 的模块清单中可查
|
||
1. **复述需求**：用自己的话复述对需求的理解，列出不确定点
|
||
2. **列出候选方案**：存在多种合理架构方案时，列出至少 2 种方案并对比优劣
|
||
3. **选择最简方案**：基于复杂度、工作量、可维护性选择最简方案
|
||
4. **等待确认**：在得到用户/Coordinator 确认前，禁止开始编码
|
||
|
||
### 1.2 极简优先
|
||
|
||
每一次引入新抽象/新中间层/新工具前，先问："不用它行不行？"
|
||
|
||
- 能用函数解决的问题，不用类
|
||
- 能用类解决的问题，不用框架
|
||
- 不为"未来可能需要的灵活性"写一行代码
|
||
- 一次性脚本不做复杂封装
|
||
- 不为纯假设的极端场景添加复杂兜底
|
||
|
||
### 1.3 精准修改
|
||
|
||
- 修改前先读对应模块的 § spec（`gateway/scripts/specs/{module}.json`），确认架构理解和约束
|
||
- 修改前输出执行计划（改哪几个文件、改什么、为什么改）
|
||
- 只改动需求直接涉及的文件，不顺手"优化"无关代码
|
||
- 一次只改一个逻辑单元，验证通过再改下一个
|
||
- 不重构没有问题的代码
|
||
- 删除本次修改导致不再使用的代码，但不删除修改前已存在的死代码（除非用户明确要求）
|
||
- **改完同步 spec**：修改完成后，将对应模块的 `specs/{module}.json` 更新为与实际实现一致
|
||
|
||
### 1.4 目标导向交付
|
||
|
||
- 多步骤任务先写入 task 清单，每完成一步标注进度
|
||
- 改动附带简要说明（改了什么、为什么改）
|
||
- 任务完成后用 3-5 句话总结：做了什么、学到了什么、下次怎么做不同
|
||
- 被纠正后，在 docs/learned.md 中追加经验教训记录
|
||
|
||
## 2. 对抗性审查流程
|
||
|
||
当 Agent 准备执行一个涉及架构选型的任务时，强制走以下检查点：
|
||
|
||
**Step 1**: 写方案草案（最直觉的方案）
|
||
|
||
**Step 2**: 对抗性审查（自问）：
|
||
- 这个方案是不是我习惯性选择的？
|
||
- 有没有更简单的方案被我跳过了？
|
||
- 每一层抽象真的必要吗？去掉会怎样？
|
||
- 如果明天就要交接给其他人，他会觉得这个设计是必要的吗？
|
||
|
||
**Step 3**: 列出对比方案（至少 2 个），标注复杂度、工作量、可维护性差异
|
||
|
||
**Step 4**: 提交给用户/Coordinator 决策
|
||
|
||
**Step 5**: 确认后执行
|
||
|
||
### 2.1 第一性原理 + 奥卡姆剃刀
|
||
|
||
每次决策追问：
|
||
- "这个复杂度是必要的吗？"
|
||
- "砍掉这层抽象会怎样？"
|
||
- "当前的方案解决了什么问题？是否创造了新问题？"
|
||
|
||
用剃刀砍掉所有不必要的抽象。
|
||
|
||
## 3. 双记录机制
|
||
|
||
### 3.1 决策日志 (docs/decisions/)
|
||
|
||
每次架构决策（引入新组件、增加抽象层、变更接口）记录在项目 `docs/decisions/` 下：
|
||
|
||
```
|
||
docs/decisions/YYYY-MM-DD-简短描述.md
|
||
```
|
||
|
||
格式：
|
||
```markdown
|
||
# 决策: [标题]
|
||
|
||
## Context
|
||
为什么需要做这个决策？当前状态是什么？
|
||
|
||
## Decision
|
||
做了什么选择？
|
||
|
||
## Consequences
|
||
这个选择的影响和后果是什么？
|
||
|
||
## Alternatives Considered
|
||
考虑了哪些替代方案？为什么没选？
|
||
```
|
||
|
||
### 3.2 经验教训 (docs/learned.md)
|
||
|
||
被纠正后追加一条记录：
|
||
|
||
```markdown
|
||
- [YYYY-MM-DD] 问题: xxx | 根因: xxx | 正确做法: xxx
|
||
```
|
||
|
||
**每次新任务前，必须先扫一遍 docs/learned.md。**
|
||
|
||
## 4. /rethink 指令（上帝按钮）
|
||
|
||
当用户或 Coordinator 发现 Agent 方向偏了时，发送 `/rethink` 指令。Agent 必须在收到后：
|
||
|
||
1. **立即停止所有操作**
|
||
2. **输出当前理解**："我以为目标是 X，正在做 Y"
|
||
3. **输出自检结果**：
|
||
- 这个问题我遇到了什么困惑？
|
||
- 我的方案是什么？
|
||
- 是否存在更简单方案？
|
||
- 是否有验证过每个假设？
|
||
4. **等待重新确认**：在得到明确的方向指示前，不再继续执行
|
||
|
||
## 5. 规则进化
|
||
|
||
- 本文档放在项目根目录下，提交到 git
|
||
- 每次从纠正中学到新经验，更新到本文档中
|
||
- 所有 Agent 共享此文档，跨项目可复用
|
||
|
||
## 附录: 判断准则是否生效
|
||
|
||
- Diff 干净且最小化，只有请求所需的改动
|
||
- 不再因过度复杂化而需要重写
|
||
- 澄清问题出现在实现之前，而不是犯错之后
|
||
- 每次架构决策前都经过了对抗性审查
|
||
- 经验教训在后续任务中被复用（不再踩同一坑）
|
||
|
||
---
|
||
版本: 1.0 | 2026-07-08 | 提案 #23 |