让 AI 写出可维护的代码：一份全流程实操指南

AI 编程正在悄悄欠下巨额技术债

slashslashdev·

让 AI 写出可维护的代码：一份全流程实操指南

AI 大幅提升了编码效率，却没能降低代码维护的难度。多项研究证实，AI 正在以惊人的速度催生、堆积技术债。但越来越多一线团队的实战经验印证了同一个结论：问题根源并非模型能力不足，而是引导方式不当——代码的可维护性，需要通过明确的规则和要求主动定义、强制落地。

关键要点

  • 2026 年一项大规模实证研究，追踪了数千个线上真实生产仓库的 AI 提交代码，结果显示，AI 引入的代码问题中，近九成属于"代码坏味道"，且超两成问题至今仍保留在仓库最新版本中，技术债处于持续累积、无人清理的状态。
  • 代码分析平台 GitClear 2025 年发布的报告指出，2024 年是有统计以来，首次出现"复制粘贴式代码量"超越"重构复用式代码量"的年份，重复代码块的出现频率较两年前暴涨约八倍。
  • METR 2025 年的对照实验得出了反直觉结论：资深开源开发者接入 AI 编码工具后，整体任务完成效率反而下降 19%。效率瓶颈不在于工具性能，而在于使用方式与配套流程。
  • 行业公认的有效解决方案，是提前向 AI 输入团队工程规范、将可维护性要求明确纳入开发需求，再通过代码评审、测试校验双重兜底。本文结合 Anthropic、Sanity、Armin Ronacher、Simon Willison 等行业主体 2025–2026 年的一线实战案例，完整拆解全流程落地方法。

速度的另一面：持续滚动的技术债

AI 编码助手能帮助开发者实现极速产出，短短数秒即可生成数百行代码。但近期多项权威研究均指出，这种高效产出存在明显隐性代价。

最新且最具说服力的实证证据，来自 2026 年发布的一项专项研究。研究者追踪了约 6300 个真实生产仓库的 AI 辅助提交代码，累计识别出 48 万余个由 AI 引入的代码问题。其中，导致代码可读性、可调试性、可修改性变差的"代码坏味道"，占所有问题的 89.3%。两大警示性数据更值得警惕：所有主流 AI 编码助手，均有超 15% 的提交记录夹带至少一处问题；而这些被识别的问题中，有 22.7% 一直留存于仓库最新版本，并未被及时修复，形成了长期沉淀的技术债。

GitClear 的纵向数据清晰展现了行业趋势。其 2025 年报告梳理了 2020–2024 年间约 2.11 亿行代码的变更记录，发现行业代码开发模式发生明显反转：代表低效复制粘贴的代码行占比，从 8.3% 升至 12.3%；而代表高质量重构复用的代码移动占比，从 2021 年的近 25% 持续下跌，2024 年已不足 10%。2024 年正式成为行业拐点，粘贴式代码量首次反超重构复用代码量，五行及以上的重复代码块出现频率，较两年前提升约八倍。

安全层面的数据同样不容乐观。代码评审平台 CodeRabbit 2025 年 12 月发布的《State of AI vs Human Code Generation》报告，对比分析了 470 个开源 PR（320 个含 AI 辅助、150 个纯人工开发），结果显示：AI 参与开发的 PR，平均每个包含 10.8 处问题，纯人工 PR 平均仅 6.5 处，问题总量多出约 1.7 倍；其中安全类问题多出 1.5–2 倍，XSS 漏洞数量更是达到人工开发的 2.74 倍。该结论与前述实证研究高度吻合——AI 编码在安全问题上，整体是"引入问题多于修复问题"，净增量约 1.5 倍。

AI 催生的技术债，为何更难解决？

想要有效治理 AI 带来的技术债，首先要厘清其与传统技术债的核心差异。

二者的关键区别在于是否存在人工决策取舍。传统技术债大多是开发者的主动取舍：工程师明确知晓当前是临时折中方案，后续需要迭代优化，是有意识的短期妥协。而 AI 生成的技术债，往往不存在任何人工决策环节：代码可正常运行、可通过常规测试、语法逻辑看似无误，但模型缺乏全局架构视野，在无人察觉的情况下主动走了开发捷径，悄无声息地埋下隐患、累积债务。

这也是 AI 代码极易通过代码评审的核心原因。AI 生成的代码普遍格式规整、注释完整、语法规范，表层质量观感极佳；但真正影响项目长期稳定性的核心问题——架构不匹配、逻辑冗余重复、边界场景缺失等，恰恰是代码评审中最难快速识别的隐性问题。与此同时，AI 将代码产出效率提升了 30%–70%，直接导致评审工作量同步激增，但团队评审人力、审核能力无法同比例扩容，最终使得大量隐性问题被遗漏留存。

但技术债的问题不能完全归咎于 AI 模型本身。AI 研究机构 METR 在 2025 年初开展的一项标杆实验极具参考性：16 名资深开源开发者（平均拥有五年以上大型开源项目开发经验，经手数万星标、上百万行代码的项目），完成 246 项标准化开发任务后，数据显示，接入 AI 工具辅助开发后，整体效率反而下降 19%。METR 明确表示该结论为特定场景下的阶段性观测结果，但足以说明核心问题：决定 AI 开发成效的关键，从来不是工具性能上限，而是团队的使用能力与配套机制。实验中的开发者均具备成熟编码能力，问题本质是 AI 工具被投入了缺乏流程规范、上下文管理、评审约束的开发环境中。

下文将顺着完整开发流程，拆解一套可落地的方法论，把可维护性要求嵌入开发全链路，所有操作均来自一线团队的成熟实践。

编码前：提前输入工程规范，完成 AI 冷启动

这是投入性价比最高、却最容易被团队忽略的关键步骤。

每一次新建 AI 对话会话，编码智能体都相当于一名完全不了解项目情况的新入职员工。它无法默认知晓项目的技术选型（如 PostgreSQL 而非 SQLite）、团队编码禁忌（如禁止裸捕获异常）、提交校验标准（如测试用例必须全部通过），只会按照通用项目模板生成标准化代码，最终产出大量适配通用场景、却不符合当前项目规范的代码。

解决 AI 项目冷启动问题的标准方案，是在代码仓库中配置智能体可自动读取的上下文规则文件。不同 AI 工具对应的配置文件路径略有差异：Claude Code 读取 CLAUDE.md，Cursor 适配 .cursor/rules/ 目录规则，GitHub Copilot 读取 .github/copilot-instructions.md。2026 年，谷歌、OpenAI、Sourcegraph、Cursor、Factory 等多家行业主体，共同敲定了 AGENTS.md 通用规则格式。目前行业主流最佳实践为：以 AGENTS.md 作为项目统一规则基准，各工具专属配置文件统一引用该基准文件，彻底规避多文件规则不一致、维护混乱的问题。

案例：Anthropic 十大内部团队实战总结

Anthropic 曾公开复盘内部十个部门的 Claude Code 使用规范，总结出一条核心规律：CLAUDE.md 文件中记录的工作流、工具使用规则、开发预期越清晰完整，AI 工具的产出质量和适配度就越高。其数据基础设施团队，将该文件作为新人熟悉代码库的核心入口：通过仓库内各级 CLAUDE.md，明确数据管道依赖关系、上游数据表与看板的对应关系，替代了传统人工梳理的数据目录工具；在标准化迭代场景（如新增数据管道）中，AI 可完全依托既定规则高效落地，大幅提升迭代效率。其安全工程团队也依托该规则文件，重构了旧的低效开发流程，将"先写设计文档、仓促编码、后续重构、最终放弃测试"的粗放模式，优化为可产出稳定、可测试代码的标准化流程。

可落地动作：不要将上下文文件当作简单配置文件填充，而是以「新人入职指南」的标准撰写，清晰说明项目设计初衷、核心主干逻辑、历史踩坑经验、专属开发规范。

一份合格的 AI 上下文规则文件，需完整覆盖核心信息：项目技术栈与整体概览、目录结构与分层调用边界（禁止跨层调用规则）、代码检测工具（linter）无法覆盖的自定义规范（命名、异常处理、日志输出规则）、测试编写约定、项目明确禁用的编码方式（例如禁用 ORM、统一使用原生 SQL）。

相较于内容完整性，内容克制精简更为关键。HumanLayer 在 CLAUDE.md 最佳实践文章中明确指出：这类规则文件贵在精简。现有研究表明，主流大模型可稳定遵守的自定义指令量级，仅百余条左右，而工具自带的系统提示词已占用数十条。行业通用的三条核心精简原则如下：

  1. 标准化格式交由工具处理，不占用自定义规则。缩进、尾逗号等格式问题，可通过 Prettier、ESLint 等工具自动修复，无需写入上下文文件。手动在规则中定义格式要求，不仅执行效率低、成本高，还会占用模型指令容量、干扰核心逻辑判断。可配置 git 钩子，在 AI 代码生成后自动执行格式校验与修复，将报错问题反向推送模型迭代优化。
  2. 按需加载信息，不一次性堆砌全量内容。无需将所有项目信息全部录入规则文件，可仅告知模型各类详细文档的存放路径（如 docs/ 目录），由模型根据开发需求自主查阅调用。
  3. 人工手写规范，拒绝 AI 自动生成。AI 自动生成的规则文件普遍内容空洞、篇幅冗余。DeployHQ 的实战数据显示，规则文件一旦超过 500 行，绝大部分内容会被模型自动忽略，失去约束作用。

案例：Armin Ronacher 实战技巧——让运行状态对 AI 可见

Flask、Jinja 框架作者 Armin Ronacher 分享过一条低门槛、高收益的 AI 编码优化经验：与其在提示词中反复描述系统运行状态，不如直接将运行数据开放给编码智能体，让模型自主感知、判断、纠错。他的具体落地方式为：在调试模式下，将系统外发邮件、验证码等核心输出打印至标准输出，并将该配置写入 CLAUDE.md。基于该规则，模型在实现登录、密码找回等核心流程时，可自主读取运行日志、获取验证码信息、打通全流程逻辑，无需开发者反复口头交代场景细节。同时他也强调边界：AI 可快速实现"可运行"的基础功能，但容易忽略性能、稳定性等细节（如限流功能缺少随机抖动、存储方案不合理），这类隐性问题仍需人工校验修复。

可落地动作：将系统日志、测试输出、健康检查结果等真实运行数据，对编码智能体开放，赋予模型自查自纠的能力；同时坚守人工验收底线，仅在自身可完全理解、可完整验收的业务场景中，允许 AI 自主迭代开发。

行业已验证的高效捷径：给模型提供团队标准代码范例，优于罗列十条抽象规则。一段贴合项目风格、符合业务规范的示例代码，能让 AI 精准产出适配项目生态的代码，效果远优于冗长、抽象的文字规约。

以下是一套适配 NestJS 后端 API 项目的 AGENTS.md 通用模板，可直接修改复用：

# AGENTS.md

## 项目概览
订单中心后端 API。技术栈为 NestJS 10 + TypeScript + PostgreSQL（Prisma）+ Redis。
对外提供 REST 接口，部署于 K8s 集群，支撑多个前端业务模块调用。

## 分层与边界
- 标准分层结构：Controller → Service → Repository（Prisma）
- Controller 仅负责参数校验与流程编排，不编写业务逻辑，不直接操作数据库
- 所有业务逻辑收敛至 Service 层，所有数据库操作收敛至 Repository / Prisma 层
- 跨模块调用统一通过对方导出的 Service 实现，禁止直接引入其他模块的 Repository
- 新增功能前，优先检索 src/modules/ 目录现有 Service，优先复用存量能力

## 自定义规范（linter 未覆盖）
- 所有请求入参统一通过 DTO + class-validator 校验，禁止 any 类型接收请求体
- 统一通过 NestJS HttpException 子类抛错，禁止裸抛出 Error 异常
- 数据库变更必须配套 Prisma migration，禁止手动修改数据表结构
- 环境变量统一通过 ConfigService 获取，禁止直接读取 process.env

## 测试规范
- 测试框架使用 Jest，Service 层编写单元测试，Repository 层采用 mock 测试
- 每个 Controller 必须配套至少一个 e2e 测试（supertest），覆盖鉴权失败等异常场景
- 代码修改完成后，需执行 `npm run test` 与 `npm run test:e2e`，所有用例通过后方可提交

## 协作约束
- 开发前优先查阅同模块存量代码，严格遵循项目既有编码风格
- 本地调试统一使用 Nest Logger 输出日志，验证码、外部通知等信息打印至控制台，方便 AI 与人工自查
- 设计方案存疑时优先输出技术方案评估，禁止直接落地代码实现

编码中：将可维护性明确纳入需求规格

上下文文件解决了"项目整体规范"的问题，而单任务的需求定义方式，直接决定 AI 最终的代码产出质量。

GitHub 在开源工具包 Spec Kit 介绍文档中，给出了一个精准类比：多数开发者将编码智能体当作搜索引擎使用，但其本质是严格按字面指令执行的结对开发搭档，擅长模式复刻与逻辑落地，但极度依赖清晰、无歧义的人工指令。近年快速普及的规格驱动开发，正是为解决这一问题而生：将模糊的"帮我实现功能"，拆解为带人工审核卡点的标准化开发流程。以 Spec Kit 为例，完整流程分为四步：/specify（需求转规格）、/plan（输出技术方案）、/tasks（拆解可测试小任务）、implement（分步落地实现），每一步均需人工审核确认后，再进入下一环节。

案例：Simon Willison 高效 AI 编码三件套

长期深耕 AI 编码实践的开发者 Simon Willison，将大模型定义为"过度自信的结对搭档"，并总结出三套可直接复用的落地方法：

  1. 以函数签名作为核心规格：由人工定义标准化函数签名，明确参数名、参数类型、返回值类型，人工把控架构设计，让 AI 仅负责具体逻辑实现。固定接口边界后，可严格约束 AI 的发挥范围，避免逻辑偏移、架构失控。
  2. 先出方案规划，再落地代码实现：但凡中等及以上复杂度的迭代需求，先让 AI 输出完整实现方案，人工打磨确认无误后，再启动编码开发。该思路与 JetBrains 智能体 Junie 的官方建议完全一致：让 AI 读取 requirements.md 需求文档，生成聚焦"实现目标、核心步骤、依赖资源、潜在风险"的 plan.md 方案文件，人工审批通过后再进行编码。通用可复用提示词："读取 requirements.md 文件，生成完整实现方案，包含开发目标、核心步骤、依赖项与风险点，暂不编写任何代码，将方案输出为 plan.md 文件。"
  3. 复用行业通用行话，简化规格描述：Willison 发现，仅通过 Use red/green TDD（采用红绿测试驱动开发）这类行业通用术语，即可唤醒模型对整套开发流程的认知，无需长篇赘述规则。用行业约定话术替代冗长文档，可大幅提升指令精准度与执行效率。

配套两类开发习惯，可进一步降低代码维护成本：一是小步迭代开发，将"实现用户认证"这类大颗粒需求，拆解为"实现邮箱格式校验注册接口"这类可独立测试的细分小任务，避免一次性生成数百行冗余代码，降低评审与修改难度；二是用具体约束替代模糊描述，"代码优雅、逻辑清晰"等模糊指令毫无意义，明确的粒度、复用、约束规则，才能产出可维护代码。指令优化对比如下：

低效模糊指令："帮我新增导出 CSV 的功能。"

高效精准指令："在 order.service.ts 中新增 CSV 导出方法，优先复用本模块现有文件读写逻辑，禁止重复开发。方法保持单一职责原则，针对空数据集、字段含逗号两类边界场景编写测试用例。先输出实现方案，确认无误后再编码。"

微软规格驱动开发相关文档中明确核心准则：需求规格的质量，直接决定代码产出质量。Augment Code 工程师也给出了落地判断标准：若需求理解偏差会导致开发返工，就必须编写标准化规格；若偏差可通过简单补全指令修正，则可直接快速迭代，按需控制规格编写成本。

编码后：建立 AI 代码专属评审制度

前置规范与需求定义做得再完善，最终的人工把关环节也绝对不可省略。该环节可重点参考 Sanity 资深工程师公开的六周实战复盘，整套流程可直接作为团队操作手册落地。

案例：Sanity 团队 AI 代码评审实战体系

Sanity 资深工程师在复盘时直言：AI 首次生成的代码，约 95% 存在各类问题。但这并非工具缺陷，而是正常的迭代流程。团队核心做法是：给予模型三次迭代优化机会，每一轮均将上一轮的问题与整改要求反向输入模型，同时以「经验不足、无项目积累的初级开发者」的标准，严格审核所有 AI 产出代码。基于长期实战，团队沉淀出四条硬性规范：

  • 人工修改代码显性标注：明确区分 AI 原生代码与人工优化代码，避免模型无法识别人工整改逻辑，下次迭代自动覆盖、还原正确修改。
  • 禁止多智能体并行处理同一问题：多 AI 工具同时参与同一功能开发，会导致逻辑冲突、规则混乱，最终放大代码问题、增加维护成本。
  • 交付责任人终身兜底：团队明文规定，无论代码由人工编写还是 AI 生成，最终提交交付的工程师承担全部责任，彻底杜绝"AI 代码无人负责"的乱象。
  • 弱化主观情感，强化客观评审：相较于亲手编写的代码，开发者对 AI 生成代码无情感包袱，可更客观、严苛地排查架构、逻辑、隐性缺陷，评审精准度更高。

通用评审优化技巧，可固化为团队固定流程：让 AI 自主讲解自身代码逻辑，无法清晰解释的部分，大概率存在隐性问题；调用另一大模型反向评审、挑错，基于问题完成代码重构；将测试用例作为安全网与活文档，把需求规格中的验收标准落地为可执行断言。

同时坚持增量重构，拒绝推倒重来。GitClear 数据清晰反映行业现状：AI 极大降低了代码新增门槛，导致团队过度侧重新增功能，忽视代码梳理与重构优化。针对性解决方案为：将代码重构纳入日常开发流程，定期让 AI 梳理重复逻辑、收敛通用能力、封装可复用模块，且要求 AI 迭代前优先检索存量代码，杜绝重复造轮子。Anthropic 安全工程团队已实现该流程自动化：通过 GitHub Actions 触发 Claude 自动评审 PR，批量处理格式问题、优化测试用例、梳理冗余逻辑，让机器承担机械性评审工作，人工专注架构、逻辑、业务合理性等核心判断。

从个人技巧，沉淀为团队资产

想要长期稳定产出可维护的 AI 代码，核心是将个人实战技巧，转化为团队标准化、可复用的流程资产。

团队编码一致性，远比个人开发习惯更重要。所有 AI 上下文规则文件，需同业务代码一起提交仓库、纳入版本管理。这类文件不仅服务于编码智能体，也能统一团队开发认知、明确评审标准，让新成员接入后，快速适配项目编码风格，获取合规的 AI 辅助代码。针对多仓库单体架构（monorepo），可在根目录配置全局通用规则，各服务子目录配置个性化局部规则，主流编码智能体可自动向上检索、合并规则，实现精准适配。

评审环节需针对性区分人工代码与 AI 代码的风险侧重点：AI 生成代码需重点排查逻辑重复、抽象过度 / 不足、表面合规但架构偏移等高频问题。同时将团队验证有效的提示词、需求规格模板统一沉淀，实现优质引导方式的团队复用，摆脱"依赖个人经验"的局限。

附：AI 代码可维护性自查清单

本清单整合全文核心方法论，适配开发全流程，可直接用于团队 wiki 归档、工位自查、代码提审校验。

编码前（上下文配置）

  • 仓库已配置 AGENTS.md / CLAUDE.md 规则文件，并纳入版本管理
  • 规则文件明确记录技术栈、分层调用边界、异常处理、命名规范等核心规则
  • 格式类规范全部交由 linter / 格式化工具处理，未占用自定义规则容量
  • 规则文件精简可控，详细参考文档存放于 docs/ 目录，按需调用
  • 已为模型提供团队标准代码范例，以案例替代纯文字规则
  • 日志、测试输出、验证码等核心运行状态对 AI 开放，支持自主自查纠错

编码中（需求规格定义）

  • 中等及以上复杂度迭代，先输出技术方案并人工确认，再启动编码
  • 需求已拆解为可独立测试的小颗粒任务，避免一次性大规模代码生成
  • 指令采用具体量化约束，无"优雅实现"等模糊描述
  • 明确要求 AI 优先复用存量代码，禁止无意义新建逻辑
  • 强制配套测试用例，覆盖正常流程与核心边界场景

编码后（代码评审校验）

  • 以初级开发者标准严苛评审 AI 代码，重点核查逻辑模糊、解释不清的模块
  • 采用双模型交叉评审，通过反向挑错完成代码重构优化
  • 重点排查 AI 代码的重复逻辑、抽象不合理、架构偏移三类核心问题
  • 人工修改代码已显性标注，避免后续迭代被模型覆盖
  • 严格落实"谁交付、谁负责"原则，AI 代码纳入人工责任范围

团队层面（长效机制建设）

  • 规则文件、提示词模板、规格模板已沉淀为团队共享资产
  • 评审流程区分人工代码与 AI 代码的风险侧重点，差异化校验
  • 常态化开展增量重构，平衡代码新增与存量优化，杜绝技术债堆积

结语

让 AI 持续产出可维护代码，核心从来不是模型能力问题，而是工程落地问题：将团队隐性的工程规范、开发标准、架构认知，转化为 AI 可精准识别、稳定执行的显性指令。通过前置上下文规范、标准化需求规格、后置评审兜底，将可维护性要求嵌入开发全链路。

从 Anthropic、Sanity 的大厂实践，到 Armin Ronacher、Simon Willison 的个人实战，所有成熟方案的核心逻辑高度一致：不依赖 AI 自主合规，而是通过明确的工程纪律、标准化流程，约束和引导 AI 的编码行为。

正如 METR 实验揭示的核心结论：决定 AI 开发成效的关键，从来不是工具本身，而是使用者的规范与方法。代码是开发意图的直观投射，意图越清晰、规则越具体，AI 的产出就越合规、越可靠。

参考资料

本文为 AI 辅助创作。写作主题、资料筛选与最终编辑由人工主导，初稿由大模型基于公开研究与一线实践整理生成；文中数据、引用及来源链接均经人工逐条核实。如发现疏漏，欢迎指正。*

AI-Assisted DevelopmentTechnical DebtAI CodingCode ReviewVibe Coding
DEV WEEKLY

开发者周报

精选编程语言、开发者工具和新产品，5 分钟读完。