docs: add modify-existing-feature flow with pre-read-spec step; update AGENTS.md, dev-spec.md
This commit is contained in:
+137
-134
@@ -1,134 +1,137 @@
|
|||||||
# AGENTS.md — 决策自检协议
|
# AGENTS.md 鈥?鍐崇瓥鑷鍗忚
|
||||||
|
|
||||||
基于 Andrej Karpathy 四大核心原则 + 诗光进化版 + 对抗性审查机制。
|
鍩轰簬 Andrej Karpathy 鍥涘ぇ鏍稿績鍘熷垯 + 璇楀厜杩涘寲鐗?+ 瀵规姉鎬у鏌ユ満鍒躲€?
|
||||||
本文档是所有 Agent（莫荷、xxm/笑笑、知微、小果）的共享决策纪律协议。
|
鏈枃妗ｆ槸鎵€鏈?Agent锛堣帿鑽枫€亁xm/绗戠瑧銆佺煡寰€佸皬鏋滐級鐨勫叡浜喅绛栫邯寰嬪崗璁€?
|
||||||
|
|
||||||
## 1. 核心规则
|
## 1. 鏍稿績瑙勫垯
|
||||||
|
|
||||||
### 1.1 思考先于编码
|
### 1.1 鎬濊€冨厛浜庣紪鐮?
|
||||||
|
|
||||||
拿到需求后，禁止直接开始编码/设计。必须依次执行：
|
鎷垮埌闇€姹傚悗锛岀姝㈢洿鎺ュ紑濮嬬紪鐮?璁捐銆傚繀椤讳緷娆℃墽琛岋細
|
||||||
|
|
||||||
1. **复述需求**：用自己的话复述对需求的理解，列出不确定点
|
0. **璇诲搴旀ā鍧楃殑 搂 spec**锛氬鏋滄秹鍙婂凡鏈夊姛鑳芥ā鍧楋紝鍏堣 `gateway/scripts/specs/{module}.json` 鐨?`ai_spec` 浜嗚В瀹為檯鏋舵瀯銆佹帴鍙ｃ€佺害鏉熷拰渚濊禆銆俿pec 鍦?`docs/dev-spec.md` 鐨勬ā鍧楁竻鍗曚腑鍙煡
|
||||||
2. **列出候选方案**：存在多种合理架构方案时，列出至少 2 种方案并对比优劣
|
1. **澶嶈堪闇€姹?*锛氱敤鑷繁鐨勮瘽澶嶈堪瀵归渶姹傜殑鐞嗚В锛屽垪鍑轰笉纭畾鐐?
|
||||||
3. **选择最简方案**：基于复杂度、工作量、可维护性选择最简方案
|
2. **鍒楀嚭鍊欓€夋柟妗?*锛氬瓨鍦ㄥ绉嶅悎鐞嗘灦鏋勬柟妗堟椂锛屽垪鍑鸿嚦灏?2 绉嶆柟妗堝苟瀵规瘮浼樺姡
|
||||||
4. **等待确认**：在得到用户/Coordinator 确认前，禁止开始编码
|
3. **閫夋嫨鏈€绠€鏂规**锛氬熀浜庡鏉傚害銆佸伐浣滈噺銆佸彲缁存姢鎬ч€夋嫨鏈€绠€鏂规
|
||||||
|
4. **绛夊緟纭**锛氬湪寰楀埌鐢ㄦ埛/Coordinator 纭鍓嶏紝绂佹寮€濮嬬紪鐮?
|
||||||
### 1.2 极简优先
|
|
||||||
|
### 1.2 鏋佺畝浼樺厛
|
||||||
每一次引入新抽象/新中间层/新工具前，先问："不用它行不行？"
|
|
||||||
|
姣忎竴娆″紩鍏ユ柊鎶借薄/鏂颁腑闂村眰/鏂板伐鍏峰墠锛屽厛闂細"涓嶇敤瀹冭涓嶈锛?
|
||||||
- 能用函数解决的问题，不用类
|
|
||||||
- 能用类解决的问题，不用框架
|
- 鑳界敤鍑芥暟瑙ｅ喅鐨勯棶棰橈紝涓嶇敤绫?
|
||||||
- 不为"未来可能需要的灵活性"写一行代码
|
- 鑳界敤绫昏В鍐崇殑闂锛屼笉鐢ㄦ鏋?
|
||||||
- 一次性脚本不做复杂封装
|
- 涓嶄负"鏈潵鍙兘闇€瑕佺殑鐏垫椿鎬?鍐欎竴琛屼唬鐮?
|
||||||
- 不为纯假设的极端场景添加复杂兜底
|
- 涓€娆℃€ц剼鏈笉鍋氬鏉傚皝瑁?
|
||||||
|
- 涓嶄负绾亣璁剧殑鏋佺鍦烘櫙娣诲姞澶嶆潅鍏滃簳
|
||||||
### 1.3 精准修改
|
|
||||||
|
### 1.3 绮惧噯淇敼
|
||||||
- 修改前输出执行计划（改哪几个文件、改什么、为什么改）
|
|
||||||
- 只改动需求直接涉及的文件，不顺手"优化"无关代码
|
- 淇敼鍓嶅厛璇诲搴旀ā鍧楃殑 搂 spec锛坄gateway/scripts/specs/{module}.json`锛夛紝纭鏋舵瀯鐞嗚В鍜岀害鏉?
|
||||||
- 一次只改一个逻辑单元，验证通过再改下一个
|
- 淇敼鍓嶈緭鍑烘墽琛岃鍒掞紙鏀瑰摢鍑犱釜鏂囦欢銆佹敼浠€涔堛€佷负浠€涔堟敼锛?
|
||||||
- 不重构没有问题的代码
|
- 鍙敼鍔ㄩ渶姹傜洿鎺ユ秹鍙婄殑鏂囦欢锛屼笉椤烘墜"浼樺寲"鏃犲叧浠ｇ爜
|
||||||
- 删除本次修改导致不再使用的代码，但不删除修改前已存在的死代码（除非用户明确要求）
|
- 涓€娆″彧鏀逛竴涓€昏緫鍗曞厓锛岄獙璇侀€氳繃鍐嶆敼涓嬩竴涓?
|
||||||
|
- 涓嶉噸鏋勬病鏈夐棶棰樼殑浠ｇ爜
|
||||||
### 1.4 目标导向交付
|
- 鍒犻櫎鏈淇敼瀵艰嚧涓嶅啀浣跨敤鐨勪唬鐮侊紝浣嗕笉鍒犻櫎淇敼鍓嶅凡瀛樺湪鐨勬浠ｇ爜锛堥櫎闈炵敤鎴锋槑纭姹傦級
|
||||||
|
- **鏀瑰畬鍚屾 spec**锛氫慨鏀瑰畬鎴愬悗锛屽皢瀵瑰簲妯″潡鐨?`specs/{module}.json` 鏇存柊涓轰笌瀹為檯瀹炵幇涓€鑷?
|
||||||
- 多步骤任务先写入 task 清单，每完成一步标注进度
|
|
||||||
- 改动附带简要说明（改了什么、为什么改）
|
### 1.4 鐩爣瀵煎悜浜や粯
|
||||||
- 任务完成后用 3-5 句话总结：做了什么、学到了什么、下次怎么做不同
|
|
||||||
- 被纠正后，在 docs/learned.md 中追加经验教训记录
|
- 澶氭楠や换鍔″厛鍐欏叆 task 娓呭崟锛屾瘡瀹屾垚涓€姝ユ爣娉ㄨ繘搴?
|
||||||
|
- 鏀瑰姩闄勫甫绠€瑕佽鏄庯紙鏀逛簡浠€涔堛€佷负浠€涔堟敼锛?
|
||||||
## 2. 对抗性审查流程
|
- 浠诲姟瀹屾垚鍚庣敤 3-5 鍙ヨ瘽鎬荤粨锛氬仛浜嗕粈涔堛€佸鍒颁簡浠€涔堛€佷笅娆℃€庝箞鍋氫笉鍚?
|
||||||
|
- 琚籂姝ｅ悗锛屽湪 docs/learned.md 涓拷鍔犵粡楠屾暀璁褰?
|
||||||
当 Agent 准备执行一个涉及架构选型的任务时，强制走以下检查点：
|
|
||||||
|
## 2. 瀵规姉鎬у鏌ユ祦绋?
|
||||||
**Step 1**: 写方案草案（最直觉的方案）
|
|
||||||
|
褰?Agent 鍑嗗鎵ц涓€涓秹鍙婃灦鏋勯€夊瀷鐨勪换鍔℃椂锛屽己鍒惰蛋浠ヤ笅妫€鏌ョ偣锛?
|
||||||
**Step 2**: 对抗性审查（自问）：
|
|
||||||
- 这个方案是不是我习惯性选择的？
|
**Step 1**: 鍐欐柟妗堣崏妗堬紙鏈€鐩磋鐨勬柟妗堬級
|
||||||
- 有没有更简单的方案被我跳过了？
|
|
||||||
- 每一层抽象真的必要吗？去掉会怎样？
|
**Step 2**: 瀵规姉鎬у鏌ワ紙鑷棶锛夛細
|
||||||
- 如果明天就要交接给其他人，他会觉得这个设计是必要的吗？
|
- 杩欎釜鏂规鏄笉鏄垜涔犳儻鎬ч€夋嫨鐨勶紵
|
||||||
|
- 鏈夋病鏈夋洿绠€鍗曠殑鏂规琚垜璺宠繃浜嗭紵
|
||||||
**Step 3**: 列出对比方案（至少 2 个），标注复杂度、工作量、可维护性差异
|
- 姣忎竴灞傛娊璞＄湡鐨勫繀瑕佸悧锛熷幓鎺変細鎬庢牱锛?
|
||||||
|
- 濡傛灉鏄庡ぉ灏辫浜ゆ帴缁欏叾浠栦汉锛屼粬浼氳寰楄繖涓璁℃槸蹇呰鐨勫悧锛?
|
||||||
**Step 4**: 提交给用户/Coordinator 决策
|
|
||||||
|
**Step 3**: 鍒楀嚭瀵规瘮鏂规锛堣嚦灏?2 涓級锛屾爣娉ㄥ鏉傚害銆佸伐浣滈噺銆佸彲缁存姢鎬у樊寮?
|
||||||
**Step 5**: 确认后执行
|
|
||||||
|
**Step 4**: 鎻愪氦缁欑敤鎴?Coordinator 鍐崇瓥
|
||||||
### 2.1 第一性原理 + 奥卡姆剃刀
|
|
||||||
|
**Step 5**: 纭鍚庢墽琛?
|
||||||
每次决策追问：
|
|
||||||
- "这个复杂度是必要的吗？"
|
### 2.1 绗竴鎬у師鐞?+ 濂ュ崱濮嗗墐鍒€
|
||||||
- "砍掉这层抽象会怎样？"
|
|
||||||
- "当前的方案解决了什么问题？是否创造了新问题？"
|
姣忔鍐崇瓥杩介棶锛?
|
||||||
|
- "杩欎釜澶嶆潅搴︽槸蹇呰鐨勫悧锛?
|
||||||
用剃刀砍掉所有不必要的抽象。
|
- "鐮嶆帀杩欏眰鎶借薄浼氭€庢牱锛?
|
||||||
|
- "褰撳墠鐨勬柟妗堣В鍐充簡浠€涔堥棶棰橈紵鏄惁鍒涢€犱簡鏂伴棶棰橈紵"
|
||||||
## 3. 双记录机制
|
|
||||||
|
鐢ㄥ墐鍒€鐮嶆帀鎵€鏈変笉蹇呰鐨勬娊璞°€?
|
||||||
### 3.1 决策日志 (docs/decisions/)
|
|
||||||
|
## 3. 鍙岃褰曟満鍒?
|
||||||
每次架构决策（引入新组件、增加抽象层、变更接口）记录在项目 `docs/decisions/` 下：
|
|
||||||
|
### 3.1 鍐崇瓥鏃ュ織 (docs/decisions/)
|
||||||
```
|
|
||||||
docs/decisions/YYYY-MM-DD-简短描述.md
|
姣忔鏋舵瀯鍐崇瓥锛堝紩鍏ユ柊缁勪欢銆佸鍔犳娊璞″眰銆佸彉鏇存帴鍙ｏ級璁板綍鍦ㄩ」鐩?`docs/decisions/` 涓嬶細
|
||||||
```
|
|
||||||
|
```
|
||||||
格式：
|
docs/decisions/YYYY-MM-DD-绠€鐭弿杩?md
|
||||||
```markdown
|
```
|
||||||
# 决策: [标题]
|
|
||||||
|
鏍煎紡锛?
|
||||||
## Context
|
```markdown
|
||||||
为什么需要做这个决策？当前状态是什么？
|
# 鍐崇瓥: [鏍囬]
|
||||||
|
|
||||||
## Decision
|
## Context
|
||||||
做了什么选择？
|
涓轰粈涔堥渶瑕佸仛杩欎釜鍐崇瓥锛熷綋鍓嶇姸鎬佹槸浠€涔堬紵
|
||||||
|
|
||||||
## Consequences
|
## Decision
|
||||||
这个选择的影响和后果是什么？
|
鍋氫簡浠€涔堥€夋嫨锛?
|
||||||
|
|
||||||
## Alternatives Considered
|
## Consequences
|
||||||
考虑了哪些替代方案？为什么没选？
|
杩欎釜閫夋嫨鐨勫奖鍝嶅拰鍚庢灉鏄粈涔堬紵
|
||||||
```
|
|
||||||
|
## Alternatives Considered
|
||||||
### 3.2 经验教训 (docs/learned.md)
|
鑰冭檻浜嗗摢浜涙浛浠ｆ柟妗堬紵涓轰粈涔堟病閫夛紵
|
||||||
|
```
|
||||||
被纠正后追加一条记录：
|
|
||||||
|
### 3.2 缁忛獙鏁欒 (docs/learned.md)
|
||||||
```markdown
|
|
||||||
- [YYYY-MM-DD] 问题: xxx | 根因: xxx | 正确做法: xxx
|
琚籂姝ｅ悗杩藉姞涓€鏉¤褰曪細
|
||||||
```
|
|
||||||
|
```markdown
|
||||||
**每次新任务前，必须先扫一遍 docs/learned.md。**
|
- [YYYY-MM-DD] 闂: xxx | 鏍瑰洜: xxx | 姝ｇ‘鍋氭硶: xxx
|
||||||
|
```
|
||||||
## 4. /rethink 指令（上帝按钮）
|
|
||||||
|
**姣忔鏂颁换鍔″墠锛屽繀椤诲厛鎵竴閬?docs/learned.md銆?*
|
||||||
当用户或 Coordinator 发现 Agent 方向偏了时，发送 `/rethink` 指令。Agent 必须在收到后：
|
|
||||||
|
## 4. /rethink 鎸囦护锛堜笂甯濇寜閽級
|
||||||
1. **立即停止所有操作**
|
|
||||||
2. **输出当前理解**："我以为目标是 X，正在做 Y"
|
褰撶敤鎴锋垨 Coordinator 鍙戠幇 Agent 鏂瑰悜鍋忎簡鏃讹紝鍙戦€?`/rethink` 鎸囦护銆侫gent 蹇呴』鍦ㄦ敹鍒板悗锛?
|
||||||
3. **输出自检结果**：
|
|
||||||
- 这个问题我遇到了什么困惑？
|
1. **绔嬪嵆鍋滄鎵€鏈夋搷浣?*
|
||||||
- 我的方案是什么？
|
2. **杈撳嚭褰撳墠鐞嗚В**锛?鎴戜互涓虹洰鏍囨槸 X锛屾鍦ㄥ仛 Y"
|
||||||
- 是否存在更简单方案？
|
3. **杈撳嚭鑷缁撴灉**锛?
|
||||||
- 是否有验证过每个假设？
|
- 杩欎釜闂鎴戦亣鍒颁簡浠€涔堝洶鎯戯紵
|
||||||
4. **等待重新确认**：在得到明确的方向指示前，不再继续执行
|
- 鎴戠殑鏂规鏄粈涔堬紵
|
||||||
|
- 鏄惁瀛樺湪鏇寸畝鍗曟柟妗堬紵
|
||||||
## 5. 规则进化
|
- 鏄惁鏈夐獙璇佽繃姣忎釜鍋囪锛?
|
||||||
|
4. **绛夊緟閲嶆柊纭**锛氬湪寰楀埌鏄庣‘鐨勬柟鍚戞寚绀哄墠锛屼笉鍐嶇户缁墽琛?
|
||||||
- 本文档放在项目根目录下，提交到 git
|
|
||||||
- 每次从纠正中学到新经验，更新到本文档中
|
## 5. 瑙勫垯杩涘寲
|
||||||
- 所有 Agent 共享此文档，跨项目可复用
|
|
||||||
|
- 鏈枃妗ｆ斁鍦ㄩ」鐩牴鐩綍涓嬶紝鎻愪氦鍒?git
|
||||||
## 附录: 判断准则是否生效
|
- 姣忔浠庣籂姝ｄ腑瀛﹀埌鏂扮粡楠岋紝鏇存柊鍒版湰鏂囨。涓?
|
||||||
|
- 鎵€鏈?Agent 鍏变韩姝ゆ枃妗ｏ紝璺ㄩ」鐩彲澶嶇敤
|
||||||
- Diff 干净且最小化，只有请求所需的改动
|
|
||||||
- 不再因过度复杂化而需要重写
|
## 闄勫綍: 鍒ゆ柇鍑嗗垯鏄惁鐢熸晥
|
||||||
- 澄清问题出现在实现之前，而不是犯错之后
|
|
||||||
- 每次架构决策前都经过了对抗性审查
|
- Diff 骞插噣涓旀渶灏忓寲锛屽彧鏈夎姹傛墍闇€鐨勬敼鍔?
|
||||||
- 经验教训在后续任务中被复用（不再踩同一坑）
|
- 涓嶅啀鍥犺繃搴﹀鏉傚寲鑰岄渶瑕侀噸鍐?
|
||||||
|
- 婢勬竻闂鍑虹幇鍦ㄥ疄鐜颁箣鍓嶏紝鑰屼笉鏄姱閿欎箣鍚?
|
||||||
---
|
- 姣忔鏋舵瀯鍐崇瓥鍓嶉兘缁忚繃浜嗗鎶楁€у鏌?
|
||||||
版本: 1.0 | 2026-07-08 | 提案 #23
|
- 缁忛獙鏁欒鍦ㄥ悗缁换鍔′腑琚鐢紙涓嶅啀韪╁悓涓€鍧戯級
|
||||||
|
|
||||||
|
---
|
||||||
|
鐗堟湰: 1.0 | 2026-07-08 | 鎻愭 #23
|
||||||
|
|||||||
+38
-8
@@ -1,4 +1,4 @@
|
|||||||
# 开发规范
|
# 开发规范
|
||||||
|
|
||||||
> 版本: v2.2 | 更新: 2026-07-17
|
> 版本: v2.2 | 更新: 2026-07-17
|
||||||
|
|
||||||
@@ -10,7 +10,7 @@
|
|||||||
|
|
||||||
三条红线：
|
三条红线：
|
||||||
|
|
||||||
1. **先写 Spec，再写代码** — 没有 spec 的模块在 dashboard 不可见，视为未完成
|
1. **先读/写 Spec，再写代码** — 新增功能先写 spec 再实现；修改已有功能先读对应 spec 了解架构和约束再动手。没有 spec 的模块在 dashboard 不可见，视为未完成
|
||||||
2. **部署必验** — 部署后不打开 K Tab 验证 = 部署未完成
|
2. **部署必验** — 部署后不打开 K Tab 验证 = 部署未完成
|
||||||
3. **不可见即不存在** — 组件不在 dashboard 中显示 = 等于没部署。离线不告警 = 监控缺陷
|
3. **不可见即不存在** — 组件不在 dashboard 中显示 = 等于没部署。离线不告警 = 监控缺陷
|
||||||
4. **实现后同步 Spec** — 每轮开发完毕后，必须将 specs/{module}.json 更新为与实际实现一致的状态。文档过期 = 等于没写
|
4. **实现后同步 Spec** — 每轮开发完毕后，必须将 specs/{module}.json 更新为与实际实现一致的状态。文档过期 = 等于没写
|
||||||
@@ -67,12 +67,13 @@ specs/usage_monitor.json
|
|||||||
|
|
||||||
### 当前模块清单
|
### 当前模块清单
|
||||||
|
|
||||||
| 模块 | spec | 状态 |
|
| 模块 | spec 路径 | § 入口 | 状态 |
|
||||||
|------|------|------|
|
|------|----------|--------|------|
|
||||||
| usage_monitor | `specs/usage_monitor.json` | ✅ |
|
| usage_monitor | `gateway/scripts/specs/usage_monitor.json` | Dashboard I Tab → OpenCode Go Usage | ✅ |
|
||||||
| easytier | `specs/easytier.json` | ✅ |
|
| easytier | `gateway/scripts/specs/easytier.json` | Dashboard I Tab → EasyTier | ✅ |
|
||||||
| rdp | `specs/rdp.json` | ✅ |
|
| rdp | `gateway/scripts/specs/rdp.json` | Dashboard I Tab → RDP | ✅ |
|
||||||
| （新增模块） | 待创建 | |
|
| 开发规范本身 | `docs/dev-spec.md` | Dashboard G Tab | ✅ |
|
||||||
|
| （新增模块） | `gateway/scripts/specs/{module}.json` | 待注册 | |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -149,6 +150,35 @@ H: 需求文档 — 双轨体系覆盖不到的架构级/跨模块需求（性
|
|||||||
即以下"操作规范"
|
即以下"操作规范"
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### 修改已有功能流程
|
||||||
|
|
||||||
|
```
|
||||||
|
识别要修改的模块（查看模块清单确定 module 名）
|
||||||
|
│
|
||||||
|
├─ 1. 读 specs/{module}.json
|
||||||
|
│ 重点读 ai_spec 部分：
|
||||||
|
│ - apis：了解接口定义和调用方式
|
||||||
|
│ - constraints：了解必须遵守的约束
|
||||||
|
│ - dependencies：了解依赖关系和部署位置
|
||||||
|
│ - architecture.flow：了解数据流向
|
||||||
|
│ - must_not：了解绝对不能做的事
|
||||||
|
│
|
||||||
|
├─ 2. 确认理解
|
||||||
|
│ - 如果 spec 描述与代码实际行为不一致，优先怀疑 spec 过期
|
||||||
|
│ - 确认后先更新 spec 再做修改
|
||||||
|
│
|
||||||
|
├─ 3. 修改功能代码
|
||||||
|
│ 只改动需求直接涉及的部分，不顺手优化无关代码
|
||||||
|
│
|
||||||
|
├─ 4. 同步更新 Spec
|
||||||
|
│ - 将 specs/{module}.json 更新为与实际实现一致
|
||||||
|
│ - api/constraints/dependencies/architecture 逐一核对
|
||||||
|
│ - 删除过时描述，修正错误假设
|
||||||
|
│
|
||||||
|
└─ 5. 提交 → 部署 → 验证
|
||||||
|
即以下"操作规范"
|
||||||
|
```
|
||||||
|
|
||||||
### Git 操作规范
|
### Git 操作规范
|
||||||
|
|
||||||
| # | 规则 | 说明 |
|
| # | 规则 | 说明 |
|
||||||
|
|||||||
Reference in New Issue
Block a user