feat: 提案#23 AGENTS.md 决策自检协议

引入 Andrej Karpathy 四大规则 + 对抗性审查流程 + 双记录机制 + /rethink 指令。

新增文件:
- docs/AGENTS.md — 共享决策自检协议文档
- docs/learned.md — 经验教训记录模板
- docs/decisions/ — 决策日志目录

所有 Agent 共享此协议,跨项目可复用。
This commit is contained in:
2026-07-08 01:55:10 +08:00
parent d72c1a907c
commit d53aa1e06b
3 changed files with 155 additions and 0 deletions
+134
View File
@@ -0,0 +1,134 @@
# AGENTS.md — 决策自检协议
基于 Andrej Karpathy 四大核心原则 + 诗光进化版 + 对抗性审查机制。
本文档是所有 Agent(莫荷、xxm/笑笑、知微、小果)的共享决策纪律协议。
## 1. 核心规则
### 1.1 思考先于编码
拿到需求后,禁止直接开始编码/设计。必须依次执行:
1. **复述需求**:用自己的话复述对需求的理解,列出不确定点
2. **列出候选方案**:存在多种合理架构方案时,列出至少 2 种方案并对比优劣
3. **选择最简方案**:基于复杂度、工作量、可维护性选择最简方案
4. **等待确认**:在得到用户/Coordinator 确认前,禁止开始编码
### 1.2 极简优先
每一次引入新抽象/新中间层/新工具前,先问:"不用它行不行?"
- 能用函数解决的问题,不用类
- 能用类解决的问题,不用框架
- 不为"未来可能需要的灵活性"写一行代码
- 一次性脚本不做复杂封装
- 不为纯假设的极端场景添加复杂兜底
### 1.3 精准修改
- 修改前输出执行计划(改哪几个文件、改什么、为什么改)
- 只改动需求直接涉及的文件,不顺手"优化"无关代码
- 一次只改一个逻辑单元,验证通过再改下一个
- 不重构没有问题的代码
- 删除本次修改导致不再使用的代码,但不删除修改前已存在的死代码(除非用户明确要求)
### 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
+12
View File
@@ -0,0 +1,12 @@
# 决策日志目录
每次架构决策记录在 YYYY-MM-DD-简短描述.md 文件中。
格式:
- Context: 为什么需要做这个决策?
- Decision: 做了什么选择?
- Consequences: 影响和后果?
- Alternatives Considered: 考虑了什么替代方案?
---
+9
View File
@@ -0,0 +1,9 @@
# 经验教训记录
每次被纠正后追加一条记录。每次新任务前先扫一遍本文档。
## 格式
- [YYYY-MM-DD] 问题: xxx | 根因: xxx | 正确做法: xxx
---