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 完全一致

  node C:UsersAdministrator.openclawplan-viewerupdate-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）