1. 为什么AI编程项目会“烂掉”1.1 一个普遍但被忽视的现象我接触过不少用AI辅助编程的团队和个人开发者从独立做小工具到多人协作的中型项目都有。一个反复出现的现象是项目启动时进展飞快AI帮你几小时就能搭出原型大家都很兴奋但两三个月后再看代码库已经没人敢动核心模块了。改一个函数三个地方报错想加个新功能发现原来的逻辑像一团乱麻连当初写代码的人自己都说不清为什么这么写。这不是个别案例。AI编程工具让“写代码”这件事的门槛急剧降低但“维护代码”的门槛并没有同步降低甚至因为生成速度太快反而被推高了。传统手写代码时你写一行想一行脑子里有完整的上下文AI生成时你一次拿到几十上百行看起来很合理但你没有经历那个“想”的过程代码对你来说更像一个黑盒。1.2 “烂掉”的本质是什么所谓项目“烂掉”通常表现为几种具体症状命名混乱且不一致、重复逻辑散落各处、模块之间隐式耦合、没有测试或测试形同虚设、文档缺失或严重过时、依赖关系错综复杂。这些症状背后有一个共同根源——缺乏持续的结构治理。传统项目靠人来治理结构靠代码审查、靠架构评审、靠老带新。AI编程项目的问题在于生成速度远超治理速度。你让AI写一个功能它可能给你生成五个文件、十几个函数其中有些是合理的抽象有些是过度设计有些是重复造轮子。如果你不加以约束这些“技术债”会以指数级累积。1.3 为什么“这件事”如此关键标题里说的“这件事”核心就是建立并执行一套面向AI编程的结构约束机制。它不是某个具体工具也不是某个框架而是一套贯穿项目始终的实践习惯。具体包括明确的目录与模块边界、统一的命名与接口约定、自动化的质量检查、以及最重要的——在每次AI生成后进行结构审查与重构。这件事之所以关键是因为AI编程的“快”是一把双刃剑。快意味着你可以在短时间内产出大量代码但也意味着如果你不主动控制结构混乱也会以同样的速度累积。等到你发现项目已经无法维护时重构成本可能已经高到不如重写。我见过一个典型的例子某开发者用AI辅助做了一个数据处理工具初期两周就完成了核心功能但三个月后想加一个导出格式发现需要改动七个文件其中三个文件的逻辑互相矛盾。最后他花了整整一周做重构比当初写核心功能还久。2. 结构治理的核心思路与方案选型2.1 从“生成优先”转向“约束优先”大多数人在使用AI编程时默认的思维模式是“生成优先”先让AI把功能写出来有问题再改。这个模式在原型阶段没问题但一旦项目要持续迭代就必须切换到“约束优先”先定义好结构规则再让AI在规则内生成。约束优先的核心是提前定义边界。比如你可以在项目根目录放一个STRUCTURE.md明确写出每个模块的职责是什么、模块之间允许的依赖方向、公共接口的命名规范、禁止出现的模式比如禁止在业务逻辑层直接调用数据库。然后每次让AI生成代码时把这份文档作为上下文传给它。2.2 工具选型轻量但有效市面上有不少代码质量工具但对于AI编程项目我建议选择轻量、可自动化、反馈快的组合。太重型的工具链会拖慢迭代速度反而让人不愿意用。我常用的组合是格式化工具统一代码风格消除无意义的差异。Python用blackJavaScript/TypeScript用prettierGo用gofmt。这类工具零配置或极少配置直接集成到保存动作里。静态检查Python用ruff比flake8快很多TypeScript用eslintJava用spotbugs。重点不是检查所有规则而是开启那些与结构相关的规则比如未使用的导入、过长的函数、过深的嵌套。依赖分析用import-linterPython或dependency-cruiserJS/TS来强制模块依赖方向。这是防止“隐式耦合”最有效的工具。测试覆盖不追求100%覆盖但要求核心模块必须有测试。用pytest、vitest或jest配合覆盖率报告重点关注新增代码的覆盖率。这些工具的共同特点是安装快、运行快、配置简单、反馈直接。你不需要一次性全部启用可以从格式化静态检查开始逐步增加。2.3 为什么不用重型架构有人可能会想既然要治理结构为什么不直接上领域驱动设计、六边形架构这些重型方案我的经验是AI编程项目的迭代速度太快重型架构的认知负担和前期投入往往得不偿失。重型架构适合需求相对稳定、团队规模较大的项目。但AI编程项目通常是快速试错、频繁调整方向的。你花一周设计的架构可能两周后就被推翻了。所以更务实的做法是用轻量约束保证基本秩序把架构决策推迟到需求稳定之后。具体来说你可以先定义“模块边界”和“依赖方向”这两个最核心的约束其他细节比如具体的类设计、设计模式可以暂时不管。等某个模块的需求稳定了再针对它做更精细的架构设计。3. 核心细节解析与实操要点3.1 目录结构让AI有章可循AI生成代码时如果没有明确的目录结构它会随机把文件放在它觉得“合理”的地方。结果就是相似功能的文件散落在不同目录或者不同功能的文件挤在同一个目录。我的做法是在项目初期就定义好一个三层目录结构并写入STRUCTURE.mdsrc/ core/ # 核心业务逻辑不依赖任何外部框架 adapters/ # 外部接口适配层如数据库、HTTP、消息队列 utils/ # 纯工具函数无业务逻辑 tests/ unit/ # 单元测试 integration/ # 集成测试然后明确规则core/不能导入adapters/或utils/中的业务相关代码adapters/可以导入core/utils/不能导入任何其他目录。这条规则用import-linter或dependency-cruiser自动检查。注意目录结构不要一开始就设计得太细。三层足够等某个目录文件超过20个再考虑拆分。过早细分会导致大量空目录和过度抽象。3.2 命名约定减少AI的“自由发挥”AI在命名上有一个特点它倾向于使用“描述性”但冗长的名字而且同一个概念在不同地方可能用不同词汇。比如“用户”可能被命名为user、customer、client、account取决于AI当时的“心情”。解决办法是维护一个术语表GLOSSARY.md列出核心概念的标准命名。比如概念标准命名禁止使用的别名用户usercustomer, client, account订单orderpurchase, transaction配置configsettings, options, preferences每次让AI生成代码时把术语表作为上下文。同时在代码审查时发现不一致的命名就立即修正。这个习惯坚持两周命名混乱问题基本可以消除。3.3 接口设计显式优于隐式AI生成的代码经常有“隐式接口”的问题函数之间通过全局变量、环境变量或隐式的数据结构传递信息而不是通过明确的参数和返回值。这种代码在单次生成时看起来没问题但一旦要修改你就得追踪所有隐式依赖。我的做法是要求所有跨模块调用必须通过显式接口。具体来说每个模块对外暴露一个__init__.pyPython或index.tsTypeScript只导出公共接口。模块内部函数可以自由命名但对外暴露的函数必须有明确的类型签名。禁止使用全局可变状态。如果确实需要共享状态用依赖注入的方式传入。这条规则可以用静态检查工具部分自动化。比如Python的mypy可以检查类型签名ruff可以检查全局变量使用。3.4 测试策略让AI帮你写测试但你要定规则AI写测试的能力其实不错但前提是你告诉它测试的规则。我的规则是每个公共函数至少有一个正常路径测试和一个异常路径测试。测试文件放在tests/unit/下文件名与被测文件对应。测试中禁止使用真实的数据库、网络或文件系统必须用mock或内存替代。测试必须能在1秒内跑完单个测试文件。这些规则写入TESTING.md每次让AI生成新功能时同时要求它生成对应的测试。然后你只需要检查测试是否覆盖了关键路径而不需要自己从头写。实操心得AI生成的测试经常“过度mock”把被测函数的所有依赖都mock掉导致测试实际上什么都没验证。我的做法是要求AI只mock外部依赖数据库、网络内部模块之间的调用不要mock。这样测试才能真正验证逻辑。4. 实操过程与核心环节实现4.1 初始化项目结构假设你要开始一个新的AI编程项目第一步不是让AI写功能而是手动搭建结构骨架。这个过程大概花15分钟但能省下后面几十小时的重构时间。具体步骤创建目录src/core/、src/adapters/、src/utils/、tests/unit/、tests/integration/。在每个目录下放一个空的__init__.pyPython或index.tsTypeScript。创建STRUCTURE.md写入模块职责和依赖规则。创建GLOSSARY.md写入核心术语表。创建TESTING.md写入测试规则。配置格式化工具和静态检查工具集成到保存动作或pre-commit钩子。这一步的关键是不要跳过。我见过太多人觉得“先写功能结构后面再整理”结果后面根本没时间整理。4.2 让AI在约束内生成代码当你需要AI生成一个新功能时不要直接说“帮我写一个用户注册功能”。而是把约束文档作为上下文然后给出明确的指令参考STRUCTURE.md和GLOSSARY.md在src/core/下实现用户注册逻辑。 要求 - 函数名为register_user参数为email和password - 返回User对象或抛出RegistrationError - 不依赖任何外部框架 - 同时生成tests/unit/test_register.py这样AI生成的代码会自然地符合你的结构约束。你只需要检查逻辑是否正确而不需要花时间调整命名和目录。4.3 每次生成后的结构审查AI生成代码后不要直接提交。花2-3分钟做一次结构审查检查文件是否放在正确的目录。检查命名是否符合术语表。检查是否有跨模块的隐式依赖。运行静态检查和测试。如果发现问题立即修正。这个习惯坚持下来你会发现项目结构始终保持清晰不会出现“越写越乱”的情况。4.4 定期重构小步快跑即使有约束AI生成的代码仍然可能积累一些结构问题。我的做法是每周花30分钟做一次小重构。具体包括合并重复的逻辑。拆分过长的函数超过50行的函数考虑拆分。删除未使用的代码。更新过时的文档。关键是“小步快跑”每次只改一点改完立即运行测试。不要攒着一起改那样风险太大。我个人的经验是每周30分钟的重构比每三个月一次的大重构效率高得多而且几乎不会引入新bug。5. 常见问题与排查技巧实录5.1 AI生成的代码“看起来对但跑不通”这是最常见的问题。原因通常是AI假设了一些不存在的依赖或者使用了过时的API。排查技巧先看错误信息定位到具体文件和行号。检查该文件是否导入了未安装的包。检查API调用是否符合当前版本。如果错误信息不明确让AI解释这段代码的预期行为然后对比实际行为。5.2 模块之间出现循环依赖循环依赖是结构治理的典型问题。表现是A模块导入BB模块又导入A导致导入失败或运行时错误。排查技巧用import-linter或dependency-cruiser生成依赖图。找到循环依赖的路径。将共享逻辑提取到第三个模块通常是utils/或core/中的公共部分。或者用依赖注入打破循环。5.3 测试跑得太慢AI生成的测试经常包含不必要的等待或真实IO操作。排查技巧用pytest --durations10找出最慢的10个测试。检查这些测试是否使用了真实数据库或网络。替换为mock或内存实现。如果测试本身逻辑复杂考虑拆分为多个小测试。5.4 命名不一致导致的理解成本这个问题在多人协作时尤其明显。排查技巧定期运行命名检查脚本可以自己写一个简单的grep脚本。在代码审查时把命名不一致作为必须修改的问题。更新术语表把新出现的概念加入。5.5 常见问题速查表问题可能原因解决方法代码跑不通缺少依赖或API过时检查导入和版本循环依赖模块边界不清提取公共逻辑或依赖注入测试太慢真实IO操作替换为mock命名混乱缺少术语表建立并维护术语表重复逻辑缺少重构每周小重构文档过时忘记更新把文档更新纳入提交检查最后分享一个小技巧我会在项目根目录放一个AI_CONTEXT.md里面汇总了所有约束文档的要点。每次让AI生成代码时只需要把这个文件作为上下文而不需要传多个文档。这个文件保持在一页以内确保AI能完整读取。这个内容后续还可以这样扩展针对不同编程语言Python、TypeScript、Go分别整理具体的工具配置和规则模板或者针对不同项目类型Web应用、数据处理、CLI工具给出差异化的结构治理方案。我个人的体会是结构治理这件事越早开始越轻松等到项目烂掉再治理成本会高到让你想放弃。
1. 为什么AI编程项目会“烂掉”1.1 一个普遍但被忽视的现象我接触过不少用AI辅助编程的团队和个人开发者从独立做小工具到多人协作的中型项目都有。一个反复出现的现象是项目启动时进展飞快AI帮你几小时就能搭出原型大家都很兴奋但两三个月后再看代码库已经没人敢动核心模块了。改一个函数三个地方报错想加个新功能发现原来的逻辑像一团乱麻连当初写代码的人自己都说不清为什么这么写。这不是个别案例。AI编程工具让“写代码”这件事的门槛急剧降低但“维护代码”的门槛并没有同步降低甚至因为生成速度太快反而被推高了。传统手写代码时你写一行想一行脑子里有完整的上下文AI生成时你一次拿到几十上百行看起来很合理但你没有经历那个“想”的过程代码对你来说更像一个黑盒。1.2 “烂掉”的本质是什么所谓项目“烂掉”通常表现为几种具体症状命名混乱且不一致、重复逻辑散落各处、模块之间隐式耦合、没有测试或测试形同虚设、文档缺失或严重过时、依赖关系错综复杂。这些症状背后有一个共同根源——缺乏持续的结构治理。传统项目靠人来治理结构靠代码审查、靠架构评审、靠老带新。AI编程项目的问题在于生成速度远超治理速度。你让AI写一个功能它可能给你生成五个文件、十几个函数其中有些是合理的抽象有些是过度设计有些是重复造轮子。如果你不加以约束这些“技术债”会以指数级累积。1.3 为什么“这件事”如此关键标题里说的“这件事”核心就是建立并执行一套面向AI编程的结构约束机制。它不是某个具体工具也不是某个框架而是一套贯穿项目始终的实践习惯。具体包括明确的目录与模块边界、统一的命名与接口约定、自动化的质量检查、以及最重要的——在每次AI生成后进行结构审查与重构。这件事之所以关键是因为AI编程的“快”是一把双刃剑。快意味着你可以在短时间内产出大量代码但也意味着如果你不主动控制结构混乱也会以同样的速度累积。等到你发现项目已经无法维护时重构成本可能已经高到不如重写。我见过一个典型的例子某开发者用AI辅助做了一个数据处理工具初期两周就完成了核心功能但三个月后想加一个导出格式发现需要改动七个文件其中三个文件的逻辑互相矛盾。最后他花了整整一周做重构比当初写核心功能还久。2. 结构治理的核心思路与方案选型2.1 从“生成优先”转向“约束优先”大多数人在使用AI编程时默认的思维模式是“生成优先”先让AI把功能写出来有问题再改。这个模式在原型阶段没问题但一旦项目要持续迭代就必须切换到“约束优先”先定义好结构规则再让AI在规则内生成。约束优先的核心是提前定义边界。比如你可以在项目根目录放一个STRUCTURE.md明确写出每个模块的职责是什么、模块之间允许的依赖方向、公共接口的命名规范、禁止出现的模式比如禁止在业务逻辑层直接调用数据库。然后每次让AI生成代码时把这份文档作为上下文传给它。2.2 工具选型轻量但有效市面上有不少代码质量工具但对于AI编程项目我建议选择轻量、可自动化、反馈快的组合。太重型的工具链会拖慢迭代速度反而让人不愿意用。我常用的组合是格式化工具统一代码风格消除无意义的差异。Python用blackJavaScript/TypeScript用prettierGo用gofmt。这类工具零配置或极少配置直接集成到保存动作里。静态检查Python用ruff比flake8快很多TypeScript用eslintJava用spotbugs。重点不是检查所有规则而是开启那些与结构相关的规则比如未使用的导入、过长的函数、过深的嵌套。依赖分析用import-linterPython或dependency-cruiserJS/TS来强制模块依赖方向。这是防止“隐式耦合”最有效的工具。测试覆盖不追求100%覆盖但要求核心模块必须有测试。用pytest、vitest或jest配合覆盖率报告重点关注新增代码的覆盖率。这些工具的共同特点是安装快、运行快、配置简单、反馈直接。你不需要一次性全部启用可以从格式化静态检查开始逐步增加。2.3 为什么不用重型架构有人可能会想既然要治理结构为什么不直接上领域驱动设计、六边形架构这些重型方案我的经验是AI编程项目的迭代速度太快重型架构的认知负担和前期投入往往得不偿失。重型架构适合需求相对稳定、团队规模较大的项目。但AI编程项目通常是快速试错、频繁调整方向的。你花一周设计的架构可能两周后就被推翻了。所以更务实的做法是用轻量约束保证基本秩序把架构决策推迟到需求稳定之后。具体来说你可以先定义“模块边界”和“依赖方向”这两个最核心的约束其他细节比如具体的类设计、设计模式可以暂时不管。等某个模块的需求稳定了再针对它做更精细的架构设计。3. 核心细节解析与实操要点3.1 目录结构让AI有章可循AI生成代码时如果没有明确的目录结构它会随机把文件放在它觉得“合理”的地方。结果就是相似功能的文件散落在不同目录或者不同功能的文件挤在同一个目录。我的做法是在项目初期就定义好一个三层目录结构并写入STRUCTURE.mdsrc/ core/ # 核心业务逻辑不依赖任何外部框架 adapters/ # 外部接口适配层如数据库、HTTP、消息队列 utils/ # 纯工具函数无业务逻辑 tests/ unit/ # 单元测试 integration/ # 集成测试然后明确规则core/不能导入adapters/或utils/中的业务相关代码adapters/可以导入core/utils/不能导入任何其他目录。这条规则用import-linter或dependency-cruiser自动检查。注意目录结构不要一开始就设计得太细。三层足够等某个目录文件超过20个再考虑拆分。过早细分会导致大量空目录和过度抽象。3.2 命名约定减少AI的“自由发挥”AI在命名上有一个特点它倾向于使用“描述性”但冗长的名字而且同一个概念在不同地方可能用不同词汇。比如“用户”可能被命名为user、customer、client、account取决于AI当时的“心情”。解决办法是维护一个术语表GLOSSARY.md列出核心概念的标准命名。比如概念标准命名禁止使用的别名用户usercustomer, client, account订单orderpurchase, transaction配置configsettings, options, preferences每次让AI生成代码时把术语表作为上下文。同时在代码审查时发现不一致的命名就立即修正。这个习惯坚持两周命名混乱问题基本可以消除。3.3 接口设计显式优于隐式AI生成的代码经常有“隐式接口”的问题函数之间通过全局变量、环境变量或隐式的数据结构传递信息而不是通过明确的参数和返回值。这种代码在单次生成时看起来没问题但一旦要修改你就得追踪所有隐式依赖。我的做法是要求所有跨模块调用必须通过显式接口。具体来说每个模块对外暴露一个__init__.pyPython或index.tsTypeScript只导出公共接口。模块内部函数可以自由命名但对外暴露的函数必须有明确的类型签名。禁止使用全局可变状态。如果确实需要共享状态用依赖注入的方式传入。这条规则可以用静态检查工具部分自动化。比如Python的mypy可以检查类型签名ruff可以检查全局变量使用。3.4 测试策略让AI帮你写测试但你要定规则AI写测试的能力其实不错但前提是你告诉它测试的规则。我的规则是每个公共函数至少有一个正常路径测试和一个异常路径测试。测试文件放在tests/unit/下文件名与被测文件对应。测试中禁止使用真实的数据库、网络或文件系统必须用mock或内存替代。测试必须能在1秒内跑完单个测试文件。这些规则写入TESTING.md每次让AI生成新功能时同时要求它生成对应的测试。然后你只需要检查测试是否覆盖了关键路径而不需要自己从头写。实操心得AI生成的测试经常“过度mock”把被测函数的所有依赖都mock掉导致测试实际上什么都没验证。我的做法是要求AI只mock外部依赖数据库、网络内部模块之间的调用不要mock。这样测试才能真正验证逻辑。4. 实操过程与核心环节实现4.1 初始化项目结构假设你要开始一个新的AI编程项目第一步不是让AI写功能而是手动搭建结构骨架。这个过程大概花15分钟但能省下后面几十小时的重构时间。具体步骤创建目录src/core/、src/adapters/、src/utils/、tests/unit/、tests/integration/。在每个目录下放一个空的__init__.pyPython或index.tsTypeScript。创建STRUCTURE.md写入模块职责和依赖规则。创建GLOSSARY.md写入核心术语表。创建TESTING.md写入测试规则。配置格式化工具和静态检查工具集成到保存动作或pre-commit钩子。这一步的关键是不要跳过。我见过太多人觉得“先写功能结构后面再整理”结果后面根本没时间整理。4.2 让AI在约束内生成代码当你需要AI生成一个新功能时不要直接说“帮我写一个用户注册功能”。而是把约束文档作为上下文然后给出明确的指令参考STRUCTURE.md和GLOSSARY.md在src/core/下实现用户注册逻辑。 要求 - 函数名为register_user参数为email和password - 返回User对象或抛出RegistrationError - 不依赖任何外部框架 - 同时生成tests/unit/test_register.py这样AI生成的代码会自然地符合你的结构约束。你只需要检查逻辑是否正确而不需要花时间调整命名和目录。4.3 每次生成后的结构审查AI生成代码后不要直接提交。花2-3分钟做一次结构审查检查文件是否放在正确的目录。检查命名是否符合术语表。检查是否有跨模块的隐式依赖。运行静态检查和测试。如果发现问题立即修正。这个习惯坚持下来你会发现项目结构始终保持清晰不会出现“越写越乱”的情况。4.4 定期重构小步快跑即使有约束AI生成的代码仍然可能积累一些结构问题。我的做法是每周花30分钟做一次小重构。具体包括合并重复的逻辑。拆分过长的函数超过50行的函数考虑拆分。删除未使用的代码。更新过时的文档。关键是“小步快跑”每次只改一点改完立即运行测试。不要攒着一起改那样风险太大。我个人的经验是每周30分钟的重构比每三个月一次的大重构效率高得多而且几乎不会引入新bug。5. 常见问题与排查技巧实录5.1 AI生成的代码“看起来对但跑不通”这是最常见的问题。原因通常是AI假设了一些不存在的依赖或者使用了过时的API。排查技巧先看错误信息定位到具体文件和行号。检查该文件是否导入了未安装的包。检查API调用是否符合当前版本。如果错误信息不明确让AI解释这段代码的预期行为然后对比实际行为。5.2 模块之间出现循环依赖循环依赖是结构治理的典型问题。表现是A模块导入BB模块又导入A导致导入失败或运行时错误。排查技巧用import-linter或dependency-cruiser生成依赖图。找到循环依赖的路径。将共享逻辑提取到第三个模块通常是utils/或core/中的公共部分。或者用依赖注入打破循环。5.3 测试跑得太慢AI生成的测试经常包含不必要的等待或真实IO操作。排查技巧用pytest --durations10找出最慢的10个测试。检查这些测试是否使用了真实数据库或网络。替换为mock或内存实现。如果测试本身逻辑复杂考虑拆分为多个小测试。5.4 命名不一致导致的理解成本这个问题在多人协作时尤其明显。排查技巧定期运行命名检查脚本可以自己写一个简单的grep脚本。在代码审查时把命名不一致作为必须修改的问题。更新术语表把新出现的概念加入。5.5 常见问题速查表问题可能原因解决方法代码跑不通缺少依赖或API过时检查导入和版本循环依赖模块边界不清提取公共逻辑或依赖注入测试太慢真实IO操作替换为mock命名混乱缺少术语表建立并维护术语表重复逻辑缺少重构每周小重构文档过时忘记更新把文档更新纳入提交检查最后分享一个小技巧我会在项目根目录放一个AI_CONTEXT.md里面汇总了所有约束文档的要点。每次让AI生成代码时只需要把这个文件作为上下文而不需要传多个文档。这个文件保持在一页以内确保AI能完整读取。这个内容后续还可以这样扩展针对不同编程语言Python、TypeScript、Go分别整理具体的工具配置和规则模板或者针对不同项目类型Web应用、数据处理、CLI工具给出差异化的结构治理方案。我个人的体会是结构治理这件事越早开始越轻松等到项目烂掉再治理成本会高到让你想放弃。
