# 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