back
loading skill details...
AI编程纪律：踩坑记录进化，防止同类错误重复发生
---
name: "coding-disciplines"
description: "AI编程纪律：踩坑记录进化，防止同类错误重复发生"
---
# coding-disciplines
> AI 编程纪律 / AI Coding Disciplines
>
> 核心机制：每次编程出错后，主动把错误原因写进进化记录区。下次编程时自动加载，激活时读到"上次这里踩过坑"，自动调出防备策略。
> 错的次数越多，记录越全，以后出错概率越低。
---
## 激活条件
**每次编程任务开始时，自动加载本技能并读取进化记录区。**
**门控流程（AGENTS.md 强制约束）：**
- GATE-1 开工前必读：读取本文件 + framework.md + WORK_LOG.md + MEMORY.md
- GATE-2 先读后改：修改文件前必须先 read 当前内容
- GATE-3 改后验证：修改后必须运行验证
- GATE-4 更新记录：完成/中断后更新 framework.md + WORK_LOG.md + 进化区
**每个门控必须输出确认信息，未通过禁止继续下一步。**
---
## 核心规则（v5 固定部分）
### R1. 静默逻辑错误是最危险的敌人
- AI 代码错误 60% 是**静默逻辑错误**：能跑通但结果错
- 编译通过 ≠ 逻辑正确，生成代码后必须测输入输出
### R2. if 条件必须双向校验
- if 条件错误占 AI 代码部分失败的 82%（ICSE 2025）
- 每个 if 条件都要考虑：`>`、`>=`、`<`、`<=`，防止方向搞反
- 边界值（0、空数组、null、负数）必测
### R3. 缺少输入校验是 AI 代码最常见安全缺陷
- 安全相关函数必须显式声明参数校验
- Endor Labs 2025：缺少输入校验是 AI 代码最常见安全缺陷
### R4. 生成函数后检查 return 之后是否有垃圾代码
- LLM 常在 return 语句后生成多余代码（Arxiv 2024 LlmFix 研究）
### R5. 验证器通过 ≠ 代码正确
- 验证器对中等难度错误漏过率 20%，困难错误漏过率 40%（NeurIPS 2025）
- 边界条件必须自己构造测试用例，不能只靠验证器
### R6. 同一错误模式记录到进化区，下次自动防备
- 每次出错后填写「进化记录区」，新错误模式自动转为防范规则
### R7. 代码越长，大模型检测错误能力越弱
- 生成代码分段验证，不要一次生成超长代码块（MDPI 2025-08）
### R8. 先写测试，再动手修（最佳实践）
- 修 Bug 前先写一个能复现 Bug 的测试，用测试通过来证明修复有效
- 每修一个 Bug 自动获得回归测试，防止修好 A 结果 B 坏了
### R9. 强制机制：framework.md + WORK_LOG.md 是编程的前置条件（v8）
- **强制流程（不可跳过）：**
1. 接到编程任务
2. **先检查**项目根目录是否有 `framework.md` 和 `WORK_LOG.md`
3. 不存在 → **立即创建这两个文件**，然后告诉用户"✅ framework.md + WORK_LOG.md 已创建"
4. 不开始写任何代码，直到这两个文件存在
5. 每个节点完成后 → **立即写日志到 WORK_LOG.md**（不能最后补）
6. 任务结束 → 清空 plan.json（看板恢复空闲）
- **日志格式（强制）：**
```
### YYYY-MM-DD HH:MM [节点名称]
**action:** 具体动作
**done:** 完成内容
**issue:** 遇到的问题 / 无
**next:** 下一步
```
- **第二天开工前**：先读 framework.md + WORK_LOG.md，确认进度后再动手
- **强制核心**：不是"建议"，是"不这样做任务就卡着不动"；不写日志 = 没完成节点
---
### R10. 代码必须写注释（v5 → v7 进化）
- **核心原则：注释 WHY，不注释 WHAT**。代码做什么看函数名就知道，注释要解释**为什么要这样做**
- **分层规范：**
- 文件头：背景、职责、关键约束
- 函数/方法：意图、参数契约、返回值、异常、复杂度来源
- 复杂逻辑块（if/循环/算法）：边界条件、业务判断原因
- 每一步操作的目的和返回值用途
- **标准标签：**
- `TODO: 约定待办的责任与时限`
- `FIXME: 已知缺陷的定位与修复思路`
- `WARNING: 风险提醒或易错点`
- `HACK: 临时方案 + 撤销条件`
- `DEPRECATED: 弃用说明 + 替代方案`
- `NOTE: 重要说明或上下文补充`
- **不要做的事：**
- ❌ 注释每一行代码
- ❌ 用 `it`/`this` 这种指代不明的代词
- ❌ 写历史记录（用 Git）
- ❌ 代码改了注释不改（同步维护）
### R11. 执行规则——按批次执行，每批必须测试（v6 新增）
- **按批次顺序执行**：批次内可并行，批次间必须确认上一批无问题再继续
- **每个修改必须给出**：文件路径 + 行号 + 修改前代码 + 修改后代码
- **修改后必须测试**：后端 `python -m uvicorn app.main:app --host 127.0.0.1 --port 8001`，前端 `npm run dev`
- **不修改无关代码**：不要重构、不要优化未被提及的部分
- **删旧数据库再测**：删除 `project_data.db` 后再测试，确保建表和初始化数据正确
### R12. 编程任务必须拆解步骤+实时进度清单（v6 新增）
- **接到编程任务后第一步**：用 `update_plan` 工具拆解成有序步骤清单（每步标 pending/in_progress/completed）
- **每个步骤要明确**：做什么、涉及哪些文件、怎么验证
- **自动联动看板**：调用 `update_plan` 后，立即用 `exec` 执行 helper 同步到 `plan.json`，格式与 `update_plan` 完全一致
```powershell
node C:\Users\Administrator\.openclaw\plan-viewer\update-plan.js '{"explanation":"...","steps":[{"step":"...","status":"..."}]}'
```
- **每完成一步**：调用 `update_plan` 更新状态 + 同步 `plan.json`，告诉用户这一步搞定
- **卡住/发现问题**：标 in_progress 不动，说明卡在哪里，等用户确认
- **批次结束点** 是天然的 in_progress 暂停点，需要用户确认后再继续
- **任务完成或放弃**：调用 `update-plan.js --clear` 清空看板，恢复空闲状态
---
## 进化记录区
### v1（2026-06-15）
- 已知问题：finance.py 重算调用漏了两处
- 规则：函数调用后检查返回值是否被使用
### v2（2026-06-15）数据支撑
- **来源**：
- ranger.net 2026-02：60% 是静默逻辑错误（编译通过但结果错）
- MDPI 2025-08：代码越长，模型检测错误能力越弱
- Medium/Dan Cleary 2024：语义错误（逻辑理解偏差）占大头
- **规则**：
- 边界条件必测（空数组/null/0/负数）
- 编译通过 ≠ 逻辑正确，必须测输入输出
- 同一错误模式记录到进化区，下次自动防备
### v3（2026-06-15）数据支撑
- **来源**：
- ICSE 2025（12,837个错误分析）：if 条件错误占部分失败的 82%；LLM 错误是系统性聚集的
- Endor Labs 2025：缺少输入校验是 AI 代码最常见安全缺陷
- Arxiv 2024 LlmFix：3类可直接修复——缩进错误、多余代码、缺少 import
- NeurIPS 2025：20% 中等/40% 困难的错误被验证器漏掉
- **规则**：
- if 条件必须双向校验（`>` 和 `>=`、`<` 和 `<=`）
- 安全相关函数必须显式声明参数校验
- 生成函数后检查 return 之后是否有垃圾代码
- 验证器通过 ≠ 代码正确，边界条件要自己测
### v4（2026-06-16）数据支撑
- **来源**：
- SWE-agent（NeurIPS 2024）：AI agent 只能解决 12.47%（全量）/ 23%（Verified）真实 GitHub Issue，说明 AI 编程失败率极高且错误模式可预测
- Cursor 新基准测试（2026-03）：Claude Haiku 4.5 分数从 73.3→29.4，Sonnet 4.5 从 77.2→37.9，证明现有基准无法反映真实编程能力，AI 错误比想象中更隐蔽
- Nature Scientific Data（2022）：74% 的研究代码首次执行失败，56% 清理后仍失败——即使有人类监督错误率都这么高
- so.html5.qq.com 2026-02-02：让 AI 修 Bug 的最佳实践是先写测试再动手修，每修一个 Bug 自动获得回归测试
- **规则**：
- 生成代码后，**先写测试用例再动手写业务逻辑**（测试驱动）
- AI 生成代码时，分段生成并验证，不要一次生成超过 200 行的连续代码
- 每次修复 Bug 后，记录错误模式和根因到进化区，防止同类问题复现
### v5（2026-06-16）用户补充规则
- **规则 R9**：每个编程项目必须建立 `framework.md`，每个节点更新，第二天开工前先读
- **规则 R10**：代码必须写注释，未完成代码用 `TODO:` 标记
### v6（2026-06-17）执行规范 + 看板联动
- **规则 R11**：按批次执行、每批必须测试、删旧数据库再测
- **规则 R12**：编程任务拆步骤 + update_plan 联动 plan.json 自动同步
- **来源**：用户补充执行规范（文件路径+行号+前后代码）、用户补充看板需求
### v7（2026-06-17）注释规范进化
- **规则 R10 进化**：注释 WHY 不注释 WHAT，分层规范（文件头/函数/逻辑块），标准标签（TODO/FIXME/WARNING/HACK/DEPRECATED/NOTE），不要做的事（不注每一行、不用代词、不写历史、不同步）
- **来源**：前端注释规范（腾讯云 2026）、代码注释最佳实践（CSDN/博客园）
### v8（2026-06-17）工作日志强化 + 强制执行机制
- **规则 R9 强制化**：不是"建议遵守"而是"不这样做任务就卡着"，接到任务先检查/创建 framework.md + WORK_LOG.md，未创建不开始写代码
- **强制日志格式**：`**action:**` / `**done:**` / `**issue:**` / `**next:**`
- **来源**：用户明确要求"务必实施，保证实施"
---
## 自我进化机制
每次编程出错后，执行以下步骤：
1. **分析错误类型**：静默逻辑 / if条件错误 / 缺少输入校验 / 验证器误判 / 其他
2. **提取根因**：写一句简洁的错误模式描述
3. **更新进化区**：将错误模式追加到最新版本的进化记录区
4. **更新规则**：如果新错误模式有普遍性，提炼成新规则加入核心规则
---
## 附：常见错误模式清单
- [ ] 函数调用后返回值未使用（v1）
- [ ] if 条件方向写反（`>` 写成 `>=`）
- [ ] 缺少空数组 / null / 0 / 负数的边界检查
- [ ] 安全函数缺少输入校验
- [ ] return 语句后有多余垃圾代码
- [ ] 一次生成代码超过 200 行未验证
- [ ] 验证器通过但边界条件未测
- [ ] 项目无 framework.md，第二天无法接手
- [ ] 代码无注释，过后看不懂自己的代码
- [ ] 未按批次顺序执行，跨批次未确认就继续（v6）
- [ ] 修改后未删旧数据库就测试，建表/初始化问题漏测（v6）
- [ ] 编程任务未拆解步骤、无进度清单，用户无法跟踪进度（v6）
- [ ] 注释每一行代码，不注 WHY 只注 WHAT（v7）
- [ ] 用代词 `it`/`this` 指代不明，读者看不懂（v7）
- [ ] 代码改了注释没同步，注释失去参考价值（v7）
- [ ] 接任务后未先建 framework.md + WORK_LOG.md 就开始写代码（v8 强制违规）
- [ ] 节点完成未写日志就继续下一个，日志倒填（v8 强制违规）
- [ ] 项目无 WORK_LOG.md，节点没写日志，第二天接手不知道干了啥（v8）
don't have the plugin yet? install it then click "run inline in claude" again.