# 减少 AI 编码常见错误的系统化行为指南

**作者：吉祥法师**

在人工智能辅助软件开发的浪潮中，大语言模型（LLM）已成为程序员不可或缺的得力助手。然而，AI 生成的代码往往伴随着一些顽固的系统性问题：过度设计、无中生有、大范围修改无关代码、以及缺乏明确的目标导向。这些问题不仅会降低开发效率，更可能引入难以追踪的隐蔽缺陷。针对这一核心痛点，本文提炼了一套系统化的行为指南，旨在帮助 AI 及使用 AI 的开发者从根本上减少编码错误，构建更健壮、更可维护的软件系统。本指南主张在速度与谨慎之间取得平衡——对于极其简单的任务，可以适当运用判断力做出取舍；对于复杂或关键的变更，则应严格遵循下述原则。

## 核心概念

本指南围绕四条核心概念展开，这些概念分别指向不同的代码质量维度：

1.  **审慎思考（Think Before Coding）**：强调在动手编码之前，必须对需求、上下文和潜在假设进行深入分析，而非盲目执行。这是避免方向性错误的第一道防线。
2.  **极简主义（Simplicity First）**：核心是“用最少的代码解决最具体的问题”。它抵制一切形式的过度工程、过早抽象和功能膨胀，确保代码的可读性与可维护性。
3.  **精确手术（Surgical Changes）**：要求改动如外科手术般精准，只触及任务直接要求的代码区域，彻底消除“顺便整理一下”的意外风险。
4.  **目标驱动（Goal-Driven Execution）**：将模糊的任务转化为可衡量、可验证的明确成功标准，通过持续验证确保每一步都正确无误。

这四大概念并非孤立存在，而是形成一个有机的整体：**审慎思考**为后续行动提供清晰的方向；**极简主义**约束代码的体量与复杂度；**精确手术**确保改动的边界清晰、风险可控；**目标驱动**则提供了从始至终的质量闭环验证机制。

## 逻辑结构

本文的逻辑结构遵循从通用原则到具体策略、从思维方式到执行细节的递进关系：

1.  **引言：问题背景与总体权衡**——首先指出 AI 编码中的常见问题，并阐明本指南的总体立场：谨慎优先，但允许对极简任务灵活处理。
2.  **核心概念与内在联系**——系统阐述四大概念的核心理念及其相互作用，构建理解框架。
3.  **四大原则的深度解析**：
    -   原则一：建立思维前置的认知习惯，包括假设显性化、不确定性管理与方案探讨。
    -   原则二：掌握代码极简的艺术，涵盖功能剪裁、抽象克制与反躬自省。
    -   原则三：培养外科手术式的编辑风格，包括只动必需部分、维护现场原貌以及清理“自己造成的垃圾”。
    -   原则四：构建目标驱动的执行闭环，通过定义可验证的目标、规划可检查的步骤来实现自主迭代。
4.  **判别标准**：提供一组可观察的行为指标，用于评估指南是否被有效遵守。

## 主要论点与论据

### 原则一：编码之前，慎思明辨

**论点**：在动手编码之前，充分的思考与分析是防止错误的第一道有效防线。不应假设任何事项都已明确，也不应隐藏疑惑。

**论据与细节**：

1.  **明确化假设**：
    -   **具体做法**：在开始实现任何功能之前，必须将你所依赖的所有假设以清晰、无歧义的语言表述出来。例如，不要认为“用户输入应该总是有效的”，而是说“我们假设用户在姓名输入字段中只提交字母和空格，并且长度不超过50个字符”。这种显性化使得团队成员或产品负责人有机会在错误的代码产生之前就纠正误解。
    -   **典型失败场景**：开发者在实现一个“数据排序”功能时，默认按照字母升序排列，而用户实际需求是“按业务权重降序排序”。由于没有事先说明假设，代码上线后导致业务报表顺序完全错误。

2.  **积极管理不确定性**：
    -   **具体做法**：如果对某个需求、API接口行为、数据库字段含义或任何技术细节感到不确定，应立即停止编码，并用清晰的语言命名出困惑点。例如：“我不确定当用户点击‘取消’按钮时，是否应该立即丢弃所有未保存的更改，还是先弹出确认弹窗。请澄清。” 积极寻求澄清，而不是自行猜测。
    -   **典型失败场景**：开发者对第三方支付接口的“回调验签”细节不确定，猜想“可能不需要验签”。结果支付回调被伪造攻击，导致公司蒙受巨大经济损失。

3.  **探讨方案权衡**：
    -   **具体做法**：当发现存在多种可行的解读或实现路径时，不应私自选择其中一种。应把所有候选方案及其各自的优缺点、复杂度、风险、性能影响、维护成本等要素清晰地列出来，进行公开讨论。例如：“对于这个‘导出报表’功能，方案A是生成CSV（实现简单，但Excel兼容性稍差），方案B是生成Excel（用户体验好，但需要引入第三方库）。建议采用方案B，因为它更符合用户预期。”在提出建议时，要敢于对明显效率低下的方案说“不”。
    -   **典型失败场景**：需要实现一个简单搜索功能，开发者自行选择使用 Elasticsearch 来搭建全文检索，虽然功能强大，但项目初期只有几百条数据，完全是“大炮打蚊子”，增加了巨大的部署和维护成本。如果事先提出“可以用数据库 `LIKE` 查询，如果未来数据量大了再迁移到 Elasticsearch”，就能避免过度工程。

### 原则二：将极简主义奉为圭臬

**论点**：编写解决当前问题所需的最少代码量，拒绝任何形式的投机性、未来性装饰。极简是抵御复杂性的根本武器。

**论据与细节**：

1.  **严格功能剪裁**：
    -   **具体做法**：代码的唯一目的是实现用户或产品需求明确提出的功能。未来可能需要的功能、猜测中可能用到的配置、为可能的扩展预留的抽象层，统统不应出现在本次的代码中。“可能”、“万一”、“以后用得上”是极简主义的敌人。如果一个特性没有被请求，就不该被实现。
    -   **典型失败场景**：一个“展示用户列表”的页面，需求只要求显示姓名和邮箱。开发者自己添加了“头像”、“注册时间”、“最后登录”等多个字段，还加上了排序和筛选功能，代码量膨胀数倍，且违反了数据最小化原则。

2.  **克制抽象冲动**：
    -   **具体做法**：抽象是应对复杂性的利器，但滥用则是复杂度的主要来源。对于只出现一次、或将来不太可能复用的代码，直接编写即可，不要创建接口、基类或工厂模式。只有当同一模式出现三次以上，或者在明确的需求分析中发现其复用价值时，才考虑引入抽象。对于一次性代码，任何抽象都比直接代码更差。
    -   **典型失败场景**：项目里只有一个“图片上传”功能，开发者却创建了一个 `IUploader` 接口，一个 `ImageUploader` 实现，外加一个 `UploaderFactory` 工厂类。所有调用点都需要先获取工厂再获取上传器，极大地增加了阅读和理解成本。实际上，直接从 `main` 函数调用一个 `upload_image()` 函数就足够了。

3.  **拥抱“回头看”的勇气**：
    -   **具体做法**：完成代码后，应从“一位资深工程师”的视角审视自己的作品。一个简单的问题是：“一位经验丰富的同行看到这段代码会不会摇头说‘太复杂了、本可以更简单’？” 如果答案是肯定的，或者代码有200行且明显可以被压缩到50行，则应立即重构精简。好的代码不是在短时间内写出来的，而是经过反复精炼后留下的精华。
    -   **量化指标**：可使用代码圈复杂度（Cyclomatic Complexity）、函数行数、嵌套层级等指标作为客观参考。例如，一个函数超过30行，或嵌套超过3层，就应视为需要简化的警告信号。

### 原则三：用外科手术的方式精准改动

**论点**：每一次代码变更都应在精准、狭小的目标区域内完成，就像外科手术一样。避免任何“顺便整理一下”的副作用，确保代码库只有目标区域发生变化。

**论据与细节**：

1.  **紧贴目标，不做无关改善**：
    -   **具体做法**：在编辑已存在的代码时，眼睛始终盯着“用户/需求要求改动的地方”。不要“顺手”修正旁边代码的缩进，不要“顺便”给相邻的变量名改个更好听的名字，不要重写看似“不优雅”但功能正常的注释。每一个动过的字符都必须能直接追踪到原始的需求任务。如果代码风格与你个人喜好不同，请尊重已有风格，保持一致。
    -   **典型失败场景**：需求是“修复用户登录时的一个拼写错误（`login` -> `log_in`）”。开发者不仅改了变量名，还顺手把整个 `login` 函数从原文件移动到了另一个模块，导致版本管理工具显示巨大的 diff，代码评审者需要花费数倍时间审查大量无关改动，甚至可能因此遗漏真正的 bug。

2.  **识别并提及，但不处理无关死代码**：
    -   **具体做法**：如果在改动过程中，偶然发现了一段明显没有被任何地方引用的死代码（Dead Code）、失效的注释或过时的逻辑，正确的做法是**口头提及**（例如在代码评审中评论或在设计文档中备注：“在此次改动中，我发现 `foo()` 函数似乎是无用的，建议在后续的清理任务中处理它。”），而**绝不删除**它。删除死代码是一个具有潜在风险的独立操作，应由原负责人或在一个专门的“代码清理”任务中进行。
    -   **典型失败场景**：你修改了一个遗留系统上的批量处理任务，发现了一个 `handle_legacy_format()` 函数，它看起来没有被调用。你直接删除了它，但由于系统未公开的依赖或是在午夜定时任务中通过反射机制调用，导致生产环境服务崩溃。

3.  **清理“自己制造的垃圾”**：
    -   **具体做法**：当你的改动导致某些之前仍在使用的变量、函数或导入变得冗余时，你必须清理这些**你自己造成的垃圾**。例如，你重构了一个正则表达式，现在不再需要 `import re`；或者你删除了一个函数中某些行，导致一个局部变量 `temp_data` 变成了未使用变量。这些因你而起的变化必须被清除，以保持代码库的整洁。
    -   **示例**：你在调试时添加了一行 `print(my_variable)`。在代码评审前，你的工作是将其删除。未能如此即构成工作不完整。

### 原则四：以结果为导向，步步为营

**论点**：将一切开发工作转化为可验证的目标，并为其设计明确的成功标准，从而构建出可以自主迭代、持续校准的闭环执行流程。

**论据与细节**：

1.  **转化模糊任务为可验证目标**：
    -   **具体操作方法**：要打破“请优化性能”、“让代码更好”、“修复这个讨厌的 Bug”这类模糊指令。必须将它们翻译成具体的可执行目标：
        -   “优化性能” → “将关键 API 的 95 分位数响应时间从 850ms 降低到 300ms 以下。”
        -   “修 bug” → “针对 #12345 号 issue 中描述的‘当用户输入重复用户名时出现 500 错误’的情况，编写一个测试用例来复现这个问题，然后修改代码使该用例通过。”
    -   **价值体现**：清晰的目标定义了“终点”，使得开发者在抵达终点后可以自动停下来，不需要不断向上级或产品经理请示“这样行不行”。弱目标（如“让它跑起来”）因为无法量化，会导致无穷无尽的循环修改与讨论。

2.  **为多步骤任务规划验证节点**：
    -   **具体操作方法**：面对一个复杂的、包含多个步骤的任务时，不应一次性完成所有编码然后焦虑地测试，而应分解任务并规划检查点。例如：
        > 需求：实现一个“用户 CSV 文件导入”功能。
        > 计划：
        > 1. [步骤 1]：解析 CSV 文件并验证列名 → 验证：[测试用例检查 1] 确保解析函数能正确处理标准文件、错误列名文件、空文件。
        > 2. [步骤 2]：将解析后的行数据插入数据库，并处理重复用户名的冲突 → 验证：[测试用例检查 2] 确保新用户被插入，旧用户根据规则被更新或跳过，数据库无异常。
        > 3. [步骤 3]：生成用户友好的结果报告并返回给客户端 → 验证：[测试用例检查 3] 确保返回的报告包含导入成功数、失败数及具体错误行号等信息。
    -   **价值体现**：通过预先规划并执行这些“步骤-验证”的循环，你可以确保在进入下一步之前，当前步骤的代码是完全正确的。这大大降低了问题向下游传导的风险，并且当项目进展受阻时，可以清晰地定位到是哪一个步骤出了问题。

### 判别标准：这套指南是否有效？

要判断这套指南是否真正被遵守并且在团队中发挥作用，可以通过以下几个可观察的指标来衡量：

1.  **更少的无关系列改动（Fewer Unnecessary Changes）**：Pull Request 或代码提交中的差异（Diff）通常**仅包含**与原始需求直接相关的代码行，不再出现“我顺手改了个变量名”或“我整理了一下代码格式”的杂乱改动。这极大地加速了代码评审过程。
2.  **显著降低的代码重写率（Fewer Rewrites）**：由于初始设计就避免了过度工程和功能膨胀，因此很少会出现“我上次想得太复杂了，这次咱们重写吧”的情况。每一次迭代都是基于前一次正确成果的稳步推进，而不是推倒重来。
3.  **更早、更有质量的提问（Earlier, Better Questions）**：团队成员（尤其是使用 AI 辅助的开发人员）会在开始写代码之前，而不是在代码写完后出错时，才提出问题。疑问是“需求 ABC 中的‘用户默认角色’究竟是指‘会员’还是‘访客’？”，而不是“我写了个根据猜测的‘管理员’角色处理逻辑，现在报错了怎么办？”。

### 总结

在 AI 驱动的软件开发新范式下，一次成功的代码生成不再仅仅是快，而更在于准和稳。这套行为指南提供了一套对抗 AI 编码固有缺陷（过度自信、上下文忽略、目标模糊）的系统性框架。通过强制进行“编码前思考”，它阻止了方向性错误；通过拥抱“极简主义”，它消除了技术债务和生产浪费；通过践行“外科手术式改动”，它确保了代码库的稳定与纯净；通过坚持“目标驱动执行”，它建立了从需求到交付的可验证闭环。

最终，这套指南的终极目标并不是让 AI 成为一个会写代码的机器，而是让它成为一个懂得**软件工程基本纪律**的可靠合作伙伴——一个在提交代码前会先问自己“我是否思考了？是否过于复杂？是否不小心动了别人的东西？是否能证明它是对的？”的合格开发者。当这套指南被内化为 AI 与后端服务交互的底层协议时，代码的质量、项目的可维护性以及整个开发团队的生产力都将迎来质的飞跃。