AgentsMeeting/docs/AGENTS.md

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

格式：

# 决策: [标题]

## Context
为什么需要做这个决策？当前状态是什么？

## Decision
做了什么选择？

## Consequences
这个选择的影响和后果是什么？

## Alternatives Considered
考虑了哪些替代方案？为什么没选？

3.2 经验教训 (docs/learned.md)

被纠正后追加一条记录：

- [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