1. 为什么AI辅助编程的项目更容易“烂掉”先说一个我观察到的现象：身边不少朋友用AI写代码之后，项目初期推进速度快得惊人，两三天就能搭出一个能跑的原型。但过了一两个月再去看那些项目，十有八九已经变成了一团乱麻——没人敢改，改了就跑不起来，想加个新功能得先把整个文件重读一遍。这个现象不是个例。AI编程工具让“写代码”这件事的门槛急剧降低，但它并没有同步降低“维护代码”的门槛。恰恰相反，它把维护的难度推到了一个前所未有的高度。原因很简单：AI生成的代码是“局部最优”的，而项目维护需要的是“全局一致”。你让AI帮你写一个数据处理的函数，它会给你一个当下能跑通的版本。你再让它加一个筛选条件，它会在原来的基础上打一个补丁。你继续让它处理一个边界情况，它再打一个补丁。三次对话之后，这个函数可能已经有两百行，里面嵌套了四层条件判断，变量命名风格换了三种，异常处理逻辑前后矛盾。而你自己，因为每次都是“复制粘贴-运行-通过”，根本没有仔细读过中间那两百行到底写了什么。这就是问题的核心：AI编程的“对话式增量开发”模式，天然倾向于产生碎片化、不一致、缺乏整体设计的代码。传统的手写代码，哪怕写得慢，开发者脑子里始终有一个完整的结构图，知道每个模块的职责边界在哪里。而AI辅助开发时，这个结构图往往是不完整的，甚至是缺失的——你只关心“这次对话有没有解决问题”，而不关心“这次修改对整体结构意味着什么”。所以标题说“你的AI编程项目迟早会烂掉”，这不是危言耸听，而是一个几乎必然的结局。除非你做一件事——建立并维护一份项目级的“上下文契约”。2. 什么是“上下文契约”，为什么它能救命“上下文契约”这个词听起来有点抽象，我换个说法：它是一份写给AI看的项目说明书，同时也是写给你自己看的架构备忘录。它的核心作用只有一个：让每一次AI对话都发生在同一个“项目世界观”之下。没有这份契约，你每次打开AI对话窗口，AI对你的项目一无所知，它只能根据你当前粘贴的那几段代码来猜测上下文。你粘贴的代码片段越少，它的猜测就越离谱；你粘贴的代码越多，它越容易在细节中迷失方向。我见过太多人用AI编程的方式是这样的：打开对话框，粘贴一段报错信息，说“帮我修一下”，AI给出一段修改后的代码，复制回去，跑通了，关掉对话框。下一次遇到问题，重新开一个对话框，重复上述流程。整个过程没有任何持久化的项目上下文被保留下来。这种工作方式在项目只有三五个文件的时候还能凑合，一旦文件数量超过十个，模块之间开始有依赖关系，就会迅速失控。因为AI不知道你的项目里已经有一个叫DataProcessor的类了，它可能会建议你再创建一个DataHandler；AI不知道你的项目统一用async/await处理异步，它可能会给你生成一堆.then()链；AI不知道你的错误处理规范是抛出自定义异常，它可能会给你返回null或者-1。“上下文契约”就是来解决这个问题的。它不需要很复杂，但必须包含以下几个核心要素：项目结构说明：目录树、每个目录的职责、关键文件的用途。技术栈与版本约束：用了哪些框架、库，版本号是多少，哪些API是禁止使用的。代码规范约定：命名风格、错误处理方式、日志格式、注释语言。核心数据模型：项目里最重要的几个数据结构长什么样，字段含义是什么。已知的坑与决策记录：为什么某个模块要这样设计，之前踩过哪些坑。这份契约不需要一次性写完，它应该随着项目推进不断增补。每次你让AI做了一个重要的架构决策，就把决策结果追加到契约里。每次你发现AI生成的代码违反了某条规范，就把这条规范明确写进契约里。久而久之，这份契约就成了项目的“宪法”，任何AI对话开始之前，先把契约贴进去，AI的输出质量会有质的提升。3. 上下文契约的具体写法与维护节奏3.1 契约文件的结构设计我自己的习惯是在项目根目录下建一个PROJECT_CONTEXT.md文件，用Markdown格式写，因为AI对Markdown的理解能力最好。文件结构大致如下：# 项目上下文契约 ## 项目概述 一句话说明这个项目是做什么的，目标用户是谁。 ## 技术栈 - 语言：Python 3.11 - Web框架：FastAPI 0.104 - 数据库：PostgreSQL 15 + SQLAlchemy 2.0 - 前端：React 18 + TypeScript 5.2 - 禁止使用：任何ORM的隐式查询、全局可变状态 ## 目录结构 src/ api/ # 路由层，只做参数校验和响应封装 services/ # 业务逻辑层，所有核心逻辑在这里 models/ # 数据模型定义 utils/ # 纯函数工具，不允许有副作用 tests/ # 测试文件，与src结构镜像 ## 代码规范 - 所有函数必须标注类型 - 错误处理统一使用自定义异常类，定义在 src/exceptions.py - 日志使用 structlog，禁止 print - 异步函数统一用 async/await，禁止 .then() 链 ## 核心数据模型 User: id, email, hashed_password, created_at, role Order: id, user_id, items, total_amount, status, created_at ## 架构决策记录 - 2024-01-15：选择FastAPI而非Flask，因为需要原生异步支持和自动文档生成 - 2024-01-20：所有数据库操作必须通过service层，api层不允许直接调用ORM - 2024-02-03：放弃使用Celery，改用FastAPI的BackgroundTasks，因为任务量不大且不想引入Redis依赖这份契约写完之后，每次和AI对话时，把它作为第一条消息发过去，然后再描述你的具体需求。实测下来，AI生成代码的“风格一致性”和“架构合规性”会有非常明显的提升。3.2 契约的更新时机契约不是写完就扔在那里的。我给自己定了几个必须更新契约的触发条件：第一，每次引入新的第三方库时。把库名、版本、用途追加到技术栈部分。同时让AI评估这个库和现有技术栈有没有冲突。第二，每次做出架构层面的取舍时。比如“为什么这个模块不用继承而用组合”“为什么这个接口不拆成两个”，把理由记下来。这些理由在未来AI问你“要不要重构”的时候，就是最好的约束条件。第三，每次发现AI重复犯同一个错误时。比如AI总是忘记给异步函数加await，那就把“所有异步调用必须显式await”写进代码规范，并且加粗。第四，每次项目结构发生变动时。新增了目录、删除了模块、重命名了核心文件，都要同步更新目录结构部分。这个维护节奏听起来有点繁琐，但实际做起来，每次更新也就花两三分钟。相比项目烂掉之后花几天时间重构，这点投入完全可以接受。3.3 一个真实的对比案例我之前同时推进过两个小项目，一个用了上下文契约，一个没用。没用的那个，两周之后我想加一个“导出报表”的功能，打开代码一看，发现数据获取逻辑散落在四个不同的文件里，有的用同步查询，有的用异步，有的返回字典，有的返回对象。我花了整整一个下午才理清楚数据流，最后决定重写。用了契约的那个项目，同样两周后加功能，我先把契约贴给AI，说“我要加一个导出报表的接口，数据从Order模型来，输出CSV格式”。AI直接给出了符合项目规范的代码：在services层新增了一个函数，在api层新增了一个路由，错误处理用了自定义异常，日志用了structlog。我只需要微调一下CSV的列顺序就完成了。整个过程不到二十分钟。这个对比让我彻底信服了一件事：AI编程的效率，不取决于AI有多强，而取决于你给AI的上下文有多完整。4. 没有契约时，AI项目烂掉的典型症状4.1 命名混乱与概念漂移这是最早出现的症状。项目初期，你让AI写一个“获取用户信息”的函数，它给你生成了get_user_info。过了几天，你让AI写一个“查询用户详情”的函数，它给你生成了fetch_user_detail。又过了几天，你让AI写一个“加载用户资料”的函数，它给你生成了load_user_profile。这三个函数做的事情几乎一模一样，但因为每次对话的措辞不同，AI就用了不同的命名。更糟糕的是，它们可能分别定义在不同的文件里，参数签名也不一致。有的接受user_id，有的接受email，有的接受一个完整的User对象。这种“概念漂移”在没有契约的项目里几乎无法避免。因为AI没有记忆，它不知道你之前已经定义过类似的功能。而你自己，如果没有一份契约作为参照，也很难在几十个文件里发现这种重复。4.2 错误处理逻辑自相矛盾AI生成代码时，对错误处理的态度是“看心情”的。有时候它会给你抛异常，有时候它会返回None，有时候它会返回一个包含error字段的字典，有时候它会直接print一条日志然后继续执行。在一个没有契约的项目里，这四种错误处理方式可能同时存在。调用方根本不知道该怎么处理返回值——是检查None？是捕获异常？还是检查字典里的error字段？这种不一致性会导致非常隐蔽的bug。比如某个函数在出错时返回了None，但调用方以为它会抛异常，于是没有做空值检查，结果在某个边缘情况下程序崩溃。而这种崩溃往往在测试环境复现不了，只在生产环境的特定数据下才会触发。4.3 依赖关系变成蜘蛛网没有契约约束的情况下，AI会倾向于“就近解决问题”。你在api/user.py里让AI加一个功能，它发现需要用到services/order.py里的某个函数，于是直接import过来用了。过几天你在api/order.py里让AI加功能，它又反过来import了api/user.py里的东西。几轮下来，模块之间的依赖关系就变成了一张蜘蛛网。你想单独测试services层的某个函数，发现它间接依赖了api层的配置；你想把models层抽出来复用，发现它引用了utils里的一个函数，而那个函数又引用了services里的东西。这种耦合在项目小的时候不会暴露问题，一旦你想做任何结构性调整，就会发现自己被这张网缠得动弹不得。4.4 测试文件与实现代码脱节AI写测试的能力其实不错，但前提是它知道测试的目标是什么。在没有契约的项目里，你让AI“给这个函数写个测试”，它会根据当前看到的函数签名来生成测试用例。但如果你后来修改了函数签名（比如增加了一个可选参数），AI并不知道，它之前写的测试可能就失效了。更常见的情况是，AI生成的测试只覆盖了“正常路径”，没有覆盖边界情况和异常路径。因为你在对话里说“帮我测试一下这个函数”，AI默认理解为“证明这个函数能跑通”，而不是“找出这个函数在什么情况下会失败”。5. 把契约落地到日常AI对话中的操作细节5.1 对话开场的标准模板我现在每次和AI进行编程对话，开场白都是固定的三段式：[第一段：粘贴PROJECT_CONTEXT.md的完整内容] [第二段：说明本次对话的目标] 本次目标：在services/order.py中新增一个calculate_discount函数， 根据用户等级和订单金额计算折扣。 [第三段：说明约束条件] 约束： - 函数必须是纯函数，不依赖外部状态 - 折扣规则从config/discount_rules.py读取，不要硬编码 - 必须处理金额为负数的情况，抛出InvalidAmountError - 需要同时生成对应的单元测试这个模板看起来有点啰嗦，但它把AI需要知道的所有信息都一次性给全了。AI不需要猜测项目结构，不需要猜测代码规范，不需要猜测错误处理方式。它只需要专注于“实现这个函数”这一件事。实测下来，用这个模板之后，AI生成代码的“一次通过率”从大概百分之四五十提升到了百分之八十以上。剩下的百分之二十，通常是因为我的约束条件写得不够精确，或者AI对某个业务规则的理解有偏差，稍微调整一下就能解决。5.2 让AI自己检查契约合规性这是一个很实用的技巧：在让AI生成代码之后，追加一句“请检查你刚才生成的代码是否符合PROJECT_CONTEXT.md中的所有规范，如果有违反的地方，指出来并修正”。AI在“生成模式”和“检查模式”下的表现是不一样的。生成的时候，它倾向于快速给出一个能跑的版本；检查的时候，它会逐条对照规范，发现一些自己之前忽略的问题。我经常遇到的情况是，AI在检查阶段自己发现“哦，我用了print而不是structlog，我改一下”。这个技巧相当于让AI自己做一次code review，成本极低，效果很好。5.3 契约的“冻结”与“解冻”契约不是一成不变的，但也不能频繁变动。我的做法是：每个开发周期（比如一周）开始时，冻结契约；周期内如果有新的决策，先记在一个临时文件里，周期结束时统一合并到契约中。这样做的好处是，在一个开发周期内，所有AI对话都基于同一份契约，生成代码的一致性有保障。如果契约频繁变动，AI每次拿到的上下文都不一样，反而会造成混乱。临时文件我通常叫CONTEXT_PENDING.md，里面就是简单的条目列表：“2024-03-01：决定所有时间字段统一用UTC存储”“2024-03-02：新增了Notification模型，字段包括...”。周期结束时，把这些条目整理进PROJECT_CONTEXT.md的对应章节。5.4 用契约来管理“技术债”AI编程的一个副作用是，它会帮你快速积累技术债。因为AI总是倾向于用“最快能跑通”的方式解决问题，而不是“最可持续”的方式。比如它可能会在一个函数里写一个复杂的条件判断来绕过某个架构限制，而不是去修改架构本身。契约可以帮你管理这些技术债。在契约里专门开一个“已知技术债”章节，每次AI用了“权宜之计”来解决问题，就把这个权宜之计记下来，标注清楚“为什么暂时这样处理”和“未来应该怎么改”。这样做有两个好处：第一，你不会忘记这些技术债的存在；第二，当未来某个时刻你决定还债时，契约里已经记录了足够的上下文，AI可以基于这些上下文给出重构方案。6. 契约之外：那些AI不会告诉你的维护经验6.1 定期做“AI代码审查”我每个月会抽出一个小时，把项目里AI生成的代码通读一遍。不是逐行读，而是带着几个问题去读：有没有重复的功能实现？有没有命名不一致的地方？有没有错误处理方式不统一的地方？有没有模块之间的循环依赖？这些问题在项目小的时候不明显，但一旦积累到一定程度，就会成为压垮项目的最后一根稻草。定期审查可以在问题还小的时候及时发现并修正。审查的时候，我会把可疑的代码片段发给AI，问它“这段代码和项目里其他地方的风格一致吗？有没有更好的写法？”AI在“对比分析”方面的能力很强，它往往能发现我自己忽略的不一致之处。6.2 给AI生成的代码加“标记”这是一个比较极端的做法，但我用下来觉得很有价值：在AI生成的每个函数或类的上方，加一行注释标记# [AI-GENERATED]。这样做的好处是，当你未来需要重构或者排查问题时，你可以快速定位到哪些代码是AI生成的，哪些是你手写的。AI生成的代码往往有特定的“味道”——比如过度使用列表推导式、异常处理不够精确、变量命名偏向通用化。知道一段代码是AI生成的，有助于你调整审查的侧重点。当然，这个标记不需要永久保留。当你确认某段AI生成的代码已经经过充分测试和审查，可以放心维护时，就可以把标记去掉。标记的意义在于“提醒自己这里需要额外关注”，而不是“永久标记这段代码是二等公民”。6.3 不要让AI同时处理多个不相关的任务这是一个很容易犯的错误：你在一个对话里，先让AI修了一个bug，然后紧接着让它加一个新功能，然后又让它改一下配置文件。AI在连续对话中会保留上下文，但这些上下文会互相干扰。比如你刚让AI修了一个关于数据库连接的bug，然后让它加一个前端组件，AI可能会在前端组件里莫名其妙地加入一些数据库相关的错误处理逻辑，因为它还“记得”刚才的数据库问题。我的做法是：一个对话只做一件事。修bug就只修bug，加功能就只加功能，改配置就只改配置。每件事做完之后，把结果合并到项目里，然后开一个新的对话做下一件事。虽然这样会多几次“粘贴契约”的操作，但换来的是更干净、更聚焦的AI输出。6.4 保留“对话历史”作为决策记录AI对话窗口里的历史记录，其实是一份非常宝贵的决策日志。你在对话里解释了为什么要这样改，AI给出了它的建议，你选择了其中一个方案——这些信息如果丢失了，未来你就很难回忆起当时的决策背景。我的做法是：每次对话结束后，把关键决策摘录到契约的“架构决策记录”章节。不需要全文复制，只需要一两句话说明“做了什么决策”和“为什么”。比如“2024-03-05：选择用JWT而非Session，因为前端是SPA且需要跨域”。这些决策记录在未来会非常有用。当你三个月后回头看某个设计，想不起来为什么当时要这样做时，翻一下决策记录就能找到答案。当AI建议你“要不要改成Session认证”时，你可以把决策记录贴给它看，它就会明白这个方案已经被评估过了。7. 一个最小可行的契约模板如果你看到这里，觉得上面的内容有点多，想先从一个最简单的版本开始，那我给你一个最小可行的模板。这个模板只包含三个部分，但已经能解决大部分“AI项目烂掉”的问题：# 项目上下文 ## 技术栈 - 语言/框架/版本： - 数据库： - 关键第三方库： ## 目录职责 - src/api/：路由层，只做参数校验和响应封装 - src/services/：业务逻辑层 - src/models/：数据模型 - src/utils/：纯函数工具 ## 代码规范 - 命名风格： - 错误处理方式： - 日志方式： - 异步处理方式：就这三部分，写起来不到十分钟。但每次和AI对话时把它贴进去，你会发现AI的输出质量有肉眼可见的提升。等你用顺手了，再逐步往里面补充数据模型、架构决策、已知技术债等内容。关键是开始做，而不是追求一步到位。契约的价值在于“持续维护”，而不在于“一次写完美”。8. 当项目已经烂了，怎么用契约来救如果你的项目已经处于“烂掉”的状态——命名混乱、依赖成网、错误处理五花八门——那契约同样可以帮你逐步恢复秩序，只是过程会更长一些。我的建议是分三步走：第一步，先写一份“现状契约”。不要试图描述“项目应该是什么样”，而是如实记录“项目现在是什么样”。把现有的目录结构、实际使用的技术栈、实际存在的命名风格都写进去。这份契约可能很丑，但它是对现状的准确描述。第二步，在现状契约的基础上，写一份“目标契约”。描述你希望项目变成什么样：统一的命名规范、清晰的模块边界、一致的错误处理方式。目标契约不需要很详细，但方向要明确。第三步，每次和AI对话时，同时贴入现状契约和目标契约。告诉AI：“当前项目状态如下，我希望向目标状态靠拢。请你在生成代码时，尽量符合目标契约的规范，如果和现状有冲突，优先遵循目标契约。”这样做的好处是，你不需要停下来专门做一次大重构。你可以在日常开发中，让AI帮你逐步把代码迁移到目标状态。每次修改一个文件，就让它更接近目标契约一点。几个月下来，项目就会慢慢恢复健康。这个过程急不得。我试过强行在一个周末重构一个烂掉的项目，结果改到一半就陷入了“改A导致B坏，改B导致C坏”的循环。后来改用这种“渐进式迁移”的方式，虽然慢，但每一步都是稳定的，不会引入新的混乱。9. 关于契约，我踩过的几个坑第一个坑是契约写得太细。我一开始把契约写成了详细的设计文档，每个函数的签名、每个字段的类型都列进去了。结果每次改代码都要同步改契约，维护成本太高，坚持了两周就放弃了。后来我把契约精简到只记录“约束”和“决策”，不记录“实现细节”，维护负担一下子就降下来了。第二个坑是契约和代码不同步。有一段时间我偷懒，代码改了但契约没更新。结果AI基于过时的契约生成了代码，和实际项目对不上，反而造成了更多混乱。从那以后我给自己定了个规矩：改代码必须同步改契约，就像改代码必须同步改测试一样。第三个坑是把契约当成万能药。契约能解决“一致性问题”，但解决不了“设计问题”。如果你的项目架构本身就有问题，契约只会帮你把问题固化下来。契约是维护工具，不是设计工具。架构设计还是得靠你自己想清楚。10. 最后一点个人体会我用AI编程的时间不算短了，从最早的代码补全工具，到后来的对话式编程，再到现在的多文件编辑，工具在变，但有一个东西始终没变：AI是你的放大器，不是你的替代品。你给它清晰的上下文，它就给你高质量的代码；你给它模糊的指令，它就给你一堆需要收拾的烂摊子。上下文契约这件事，本质上是在做一件很朴素的事情：把项目里那些“只可意会不可言传”的隐性知识，变成显性的、可传递的文档。这件事在AI编程时代之前就很重要，只是那时候开发者靠口口相传和代码审查来传递这些知识。现在AI成了开发团队的一员，它也需要这些知识，而且它比人类更需要——因为人类可以从代码里“猜”出规范，AI只能从你给它的文字里“读”出规范。所以，如果你正在用AI写一个稍微有点规模的项目，我强烈建议你从今天开始，花十分钟写一份最小可行的上下文契约。不用追求完美，先写起来，然后在实践中慢慢完善。这个小小的习惯，可能就是你的项目“烂掉”和“活下来”之间的分界线。
1. 为什么AI辅助编程的项目更容易“烂掉”先说一个我观察到的现象：身边不少朋友用AI写代码之后，项目初期推进速度快得惊人，两三天就能搭出一个能跑的原型。但过了一两个月再去看那些项目，十有八九已经变成了一团乱麻——没人敢改，改了就跑不起来，想加个新功能得先把整个文件重读一遍。这个现象不是个例。AI编程工具让“写代码”这件事的门槛急剧降低，但它并没有同步降低“维护代码”的门槛。恰恰相反，它把维护的难度推到了一个前所未有的高度。原因很简单：AI生成的代码是“局部最优”的，而项目维护需要的是“全局一致”。你让AI帮你写一个数据处理的函数，它会给你一个当下能跑通的版本。你再让它加一个筛选条件，它会在原来的基础上打一个补丁。你继续让它处理一个边界情况，它再打一个补丁。三次对话之后，这个函数可能已经有两百行，里面嵌套了四层条件判断，变量命名风格换了三种，异常处理逻辑前后矛盾。而你自己，因为每次都是“复制粘贴-运行-通过”，根本没有仔细读过中间那两百行到底写了什么。这就是问题的核心：AI编程的“对话式增量开发”模式，天然倾向于产生碎片化、不一致、缺乏整体设计的代码。传统的手写代码，哪怕写得慢，开发者脑子里始终有一个完整的结构图，知道每个模块的职责边界在哪里。而AI辅助开发时，这个结构图往往是不完整的，甚至是缺失的——你只关心“这次对话有没有解决问题”，而不关心“这次修改对整体结构意味着什么”。所以标题说“你的AI编程项目迟早会烂掉”，这不是危言耸听，而是一个几乎必然的结局。除非你做一件事——建立并维护一份项目级的“上下文契约”。2. 什么是“上下文契约”，为什么它能救命“上下文契约”这个词听起来有点抽象，我换个说法：它是一份写给AI看的项目说明书，同时也是写给你自己看的架构备忘录。它的核心作用只有一个：让每一次AI对话都发生在同一个“项目世界观”之下。没有这份契约，你每次打开AI对话窗口，AI对你的项目一无所知，它只能根据你当前粘贴的那几段代码来猜测上下文。你粘贴的代码片段越少，它的猜测就越离谱；你粘贴的代码越多，它越容易在细节中迷失方向。我见过太多人用AI编程的方式是这样的：打开对话框，粘贴一段报错信息，说“帮我修一下”，AI给出一段修改后的代码，复制回去，跑通了，关掉对话框。下一次遇到问题，重新开一个对话框，重复上述流程。整个过程没有任何持久化的项目上下文被保留下来。这种工作方式在项目只有三五个文件的时候还能凑合，一旦文件数量超过十个，模块之间开始有依赖关系，就会迅速失控。因为AI不知道你的项目里已经有一个叫DataProcessor的类了，它可能会建议你再创建一个DataHandler；AI不知道你的项目统一用async/await处理异步，它可能会给你生成一堆.then()链；AI不知道你的错误处理规范是抛出自定义异常，它可能会给你返回null或者-1。“上下文契约”就是来解决这个问题的。它不需要很复杂，但必须包含以下几个核心要素：项目结构说明：目录树、每个目录的职责、关键文件的用途。技术栈与版本约束：用了哪些框架、库，版本号是多少，哪些API是禁止使用的。代码规范约定：命名风格、错误处理方式、日志格式、注释语言。核心数据模型：项目里最重要的几个数据结构长什么样，字段含义是什么。已知的坑与决策记录：为什么某个模块要这样设计，之前踩过哪些坑。这份契约不需要一次性写完，它应该随着项目推进不断增补。每次你让AI做了一个重要的架构决策，就把决策结果追加到契约里。每次你发现AI生成的代码违反了某条规范，就把这条规范明确写进契约里。久而久之，这份契约就成了项目的“宪法”，任何AI对话开始之前，先把契约贴进去，AI的输出质量会有质的提升。3. 上下文契约的具体写法与维护节奏3.1 契约文件的结构设计我自己的习惯是在项目根目录下建一个PROJECT_CONTEXT.md文件，用Markdown格式写，因为AI对Markdown的理解能力最好。文件结构大致如下：# 项目上下文契约 ## 项目概述 一句话说明这个项目是做什么的，目标用户是谁。 ## 技术栈 - 语言：Python 3.11 - Web框架：FastAPI 0.104 - 数据库：PostgreSQL 15 + SQLAlchemy 2.0 - 前端：React 18 + TypeScript 5.2 - 禁止使用：任何ORM的隐式查询、全局可变状态 ## 目录结构 src/ api/ # 路由层，只做参数校验和响应封装 services/ # 业务逻辑层，所有核心逻辑在这里 models/ # 数据模型定义 utils/ # 纯函数工具，不允许有副作用 tests/ # 测试文件，与src结构镜像 ## 代码规范 - 所有函数必须标注类型 - 错误处理统一使用自定义异常类，定义在 src/exceptions.py - 日志使用 structlog，禁止 print - 异步函数统一用 async/await，禁止 .then() 链 ## 核心数据模型 User: id, email, hashed_password, created_at, role Order: id, user_id, items, total_amount, status, created_at ## 架构决策记录 - 2024-01-15：选择FastAPI而非Flask，因为需要原生异步支持和自动文档生成 - 2024-01-20：所有数据库操作必须通过service层，api层不允许直接调用ORM - 2024-02-03：放弃使用Celery，改用FastAPI的BackgroundTasks，因为任务量不大且不想引入Redis依赖这份契约写完之后，每次和AI对话时，把它作为第一条消息发过去，然后再描述你的具体需求。实测下来，AI生成代码的“风格一致性”和“架构合规性”会有非常明显的提升。3.2 契约的更新时机契约不是写完就扔在那里的。我给自己定了几个必须更新契约的触发条件：第一，每次引入新的第三方库时。把库名、版本、用途追加到技术栈部分。同时让AI评估这个库和现有技术栈有没有冲突。第二，每次做出架构层面的取舍时。比如“为什么这个模块不用继承而用组合”“为什么这个接口不拆成两个”，把理由记下来。这些理由在未来AI问你“要不要重构”的时候，就是最好的约束条件。第三，每次发现AI重复犯同一个错误时。比如AI总是忘记给异步函数加await，那就把“所有异步调用必须显式await”写进代码规范，并且加粗。第四，每次项目结构发生变动时。新增了目录、删除了模块、重命名了核心文件，都要同步更新目录结构部分。这个维护节奏听起来有点繁琐，但实际做起来，每次更新也就花两三分钟。相比项目烂掉之后花几天时间重构，这点投入完全可以接受。3.3 一个真实的对比案例我之前同时推进过两个小项目，一个用了上下文契约，一个没用。没用的那个，两周之后我想加一个“导出报表”的功能，打开代码一看，发现数据获取逻辑散落在四个不同的文件里，有的用同步查询，有的用异步，有的返回字典，有的返回对象。我花了整整一个下午才理清楚数据流，最后决定重写。用了契约的那个项目，同样两周后加功能，我先把契约贴给AI，说“我要加一个导出报表的接口，数据从Order模型来，输出CSV格式”。AI直接给出了符合项目规范的代码：在services层新增了一个函数，在api层新增了一个路由，错误处理用了自定义异常，日志用了structlog。我只需要微调一下CSV的列顺序就完成了。整个过程不到二十分钟。这个对比让我彻底信服了一件事：AI编程的效率，不取决于AI有多强，而取决于你给AI的上下文有多完整。4. 没有契约时，AI项目烂掉的典型症状4.1 命名混乱与概念漂移这是最早出现的症状。项目初期，你让AI写一个“获取用户信息”的函数，它给你生成了get_user_info。过了几天，你让AI写一个“查询用户详情”的函数，它给你生成了fetch_user_detail。又过了几天，你让AI写一个“加载用户资料”的函数，它给你生成了load_user_profile。这三个函数做的事情几乎一模一样，但因为每次对话的措辞不同，AI就用了不同的命名。更糟糕的是，它们可能分别定义在不同的文件里，参数签名也不一致。有的接受user_id，有的接受email，有的接受一个完整的User对象。这种“概念漂移”在没有契约的项目里几乎无法避免。因为AI没有记忆，它不知道你之前已经定义过类似的功能。而你自己，如果没有一份契约作为参照，也很难在几十个文件里发现这种重复。4.2 错误处理逻辑自相矛盾AI生成代码时，对错误处理的态度是“看心情”的。有时候它会给你抛异常，有时候它会返回None，有时候它会返回一个包含error字段的字典，有时候它会直接print一条日志然后继续执行。在一个没有契约的项目里，这四种错误处理方式可能同时存在。调用方根本不知道该怎么处理返回值——是检查None？是捕获异常？还是检查字典里的error字段？这种不一致性会导致非常隐蔽的bug。比如某个函数在出错时返回了None，但调用方以为它会抛异常，于是没有做空值检查，结果在某个边缘情况下程序崩溃。而这种崩溃往往在测试环境复现不了，只在生产环境的特定数据下才会触发。4.3 依赖关系变成蜘蛛网没有契约约束的情况下，AI会倾向于“就近解决问题”。你在api/user.py里让AI加一个功能，它发现需要用到services/order.py里的某个函数，于是直接import过来用了。过几天你在api/order.py里让AI加功能，它又反过来import了api/user.py里的东西。几轮下来，模块之间的依赖关系就变成了一张蜘蛛网。你想单独测试services层的某个函数，发现它间接依赖了api层的配置；你想把models层抽出来复用，发现它引用了utils里的一个函数，而那个函数又引用了services里的东西。这种耦合在项目小的时候不会暴露问题，一旦你想做任何结构性调整，就会发现自己被这张网缠得动弹不得。4.4 测试文件与实现代码脱节AI写测试的能力其实不错，但前提是它知道测试的目标是什么。在没有契约的项目里，你让AI“给这个函数写个测试”，它会根据当前看到的函数签名来生成测试用例。但如果你后来修改了函数签名（比如增加了一个可选参数），AI并不知道，它之前写的测试可能就失效了。更常见的情况是，AI生成的测试只覆盖了“正常路径”，没有覆盖边界情况和异常路径。因为你在对话里说“帮我测试一下这个函数”，AI默认理解为“证明这个函数能跑通”，而不是“找出这个函数在什么情况下会失败”。5. 把契约落地到日常AI对话中的操作细节5.1 对话开场的标准模板我现在每次和AI进行编程对话，开场白都是固定的三段式：[第一段：粘贴PROJECT_CONTEXT.md的完整内容] [第二段：说明本次对话的目标] 本次目标：在services/order.py中新增一个calculate_discount函数， 根据用户等级和订单金额计算折扣。 [第三段：说明约束条件] 约束： - 函数必须是纯函数，不依赖外部状态 - 折扣规则从config/discount_rules.py读取，不要硬编码 - 必须处理金额为负数的情况，抛出InvalidAmountError - 需要同时生成对应的单元测试这个模板看起来有点啰嗦，但它把AI需要知道的所有信息都一次性给全了。AI不需要猜测项目结构，不需要猜测代码规范，不需要猜测错误处理方式。它只需要专注于“实现这个函数”这一件事。实测下来，用这个模板之后，AI生成代码的“一次通过率”从大概百分之四五十提升到了百分之八十以上。剩下的百分之二十，通常是因为我的约束条件写得不够精确，或者AI对某个业务规则的理解有偏差，稍微调整一下就能解决。5.2 让AI自己检查契约合规性这是一个很实用的技巧：在让AI生成代码之后，追加一句“请检查你刚才生成的代码是否符合PROJECT_CONTEXT.md中的所有规范，如果有违反的地方，指出来并修正”。AI在“生成模式”和“检查模式”下的表现是不一样的。生成的时候，它倾向于快速给出一个能跑的版本；检查的时候，它会逐条对照规范，发现一些自己之前忽略的问题。我经常遇到的情况是，AI在检查阶段自己发现“哦，我用了print而不是structlog，我改一下”。这个技巧相当于让AI自己做一次code review，成本极低，效果很好。5.3 契约的“冻结”与“解冻”契约不是一成不变的，但也不能频繁变动。我的做法是：每个开发周期（比如一周）开始时，冻结契约；周期内如果有新的决策，先记在一个临时文件里，周期结束时统一合并到契约中。这样做的好处是，在一个开发周期内，所有AI对话都基于同一份契约，生成代码的一致性有保障。如果契约频繁变动，AI每次拿到的上下文都不一样，反而会造成混乱。临时文件我通常叫CONTEXT_PENDING.md，里面就是简单的条目列表：“2024-03-01：决定所有时间字段统一用UTC存储”“2024-03-02：新增了Notification模型，字段包括...”。周期结束时，把这些条目整理进PROJECT_CONTEXT.md的对应章节。5.4 用契约来管理“技术债”AI编程的一个副作用是，它会帮你快速积累技术债。因为AI总是倾向于用“最快能跑通”的方式解决问题，而不是“最可持续”的方式。比如它可能会在一个函数里写一个复杂的条件判断来绕过某个架构限制，而不是去修改架构本身。契约可以帮你管理这些技术债。在契约里专门开一个“已知技术债”章节，每次AI用了“权宜之计”来解决问题，就把这个权宜之计记下来，标注清楚“为什么暂时这样处理”和“未来应该怎么改”。这样做有两个好处：第一，你不会忘记这些技术债的存在；第二，当未来某个时刻你决定还债时，契约里已经记录了足够的上下文，AI可以基于这些上下文给出重构方案。6. 契约之外：那些AI不会告诉你的维护经验6.1 定期做“AI代码审查”我每个月会抽出一个小时，把项目里AI生成的代码通读一遍。不是逐行读，而是带着几个问题去读：有没有重复的功能实现？有没有命名不一致的地方？有没有错误处理方式不统一的地方？有没有模块之间的循环依赖？这些问题在项目小的时候不明显，但一旦积累到一定程度，就会成为压垮项目的最后一根稻草。定期审查可以在问题还小的时候及时发现并修正。审查的时候，我会把可疑的代码片段发给AI，问它“这段代码和项目里其他地方的风格一致吗？有没有更好的写法？”AI在“对比分析”方面的能力很强，它往往能发现我自己忽略的不一致之处。6.2 给AI生成的代码加“标记”这是一个比较极端的做法，但我用下来觉得很有价值：在AI生成的每个函数或类的上方，加一行注释标记# [AI-GENERATED]。这样做的好处是，当你未来需要重构或者排查问题时，你可以快速定位到哪些代码是AI生成的，哪些是你手写的。AI生成的代码往往有特定的“味道”——比如过度使用列表推导式、异常处理不够精确、变量命名偏向通用化。知道一段代码是AI生成的，有助于你调整审查的侧重点。当然，这个标记不需要永久保留。当你确认某段AI生成的代码已经经过充分测试和审查，可以放心维护时，就可以把标记去掉。标记的意义在于“提醒自己这里需要额外关注”，而不是“永久标记这段代码是二等公民”。6.3 不要让AI同时处理多个不相关的任务这是一个很容易犯的错误：你在一个对话里，先让AI修了一个bug，然后紧接着让它加一个新功能，然后又让它改一下配置文件。AI在连续对话中会保留上下文，但这些上下文会互相干扰。比如你刚让AI修了一个关于数据库连接的bug，然后让它加一个前端组件，AI可能会在前端组件里莫名其妙地加入一些数据库相关的错误处理逻辑，因为它还“记得”刚才的数据库问题。我的做法是：一个对话只做一件事。修bug就只修bug，加功能就只加功能，改配置就只改配置。每件事做完之后，把结果合并到项目里，然后开一个新的对话做下一件事。虽然这样会多几次“粘贴契约”的操作，但换来的是更干净、更聚焦的AI输出。6.4 保留“对话历史”作为决策记录AI对话窗口里的历史记录，其实是一份非常宝贵的决策日志。你在对话里解释了为什么要这样改，AI给出了它的建议，你选择了其中一个方案——这些信息如果丢失了，未来你就很难回忆起当时的决策背景。我的做法是：每次对话结束后，把关键决策摘录到契约的“架构决策记录”章节。不需要全文复制，只需要一两句话说明“做了什么决策”和“为什么”。比如“2024-03-05：选择用JWT而非Session，因为前端是SPA且需要跨域”。这些决策记录在未来会非常有用。当你三个月后回头看某个设计，想不起来为什么当时要这样做时，翻一下决策记录就能找到答案。当AI建议你“要不要改成Session认证”时，你可以把决策记录贴给它看，它就会明白这个方案已经被评估过了。7. 一个最小可行的契约模板如果你看到这里，觉得上面的内容有点多，想先从一个最简单的版本开始，那我给你一个最小可行的模板。这个模板只包含三个部分，但已经能解决大部分“AI项目烂掉”的问题：# 项目上下文 ## 技术栈 - 语言/框架/版本： - 数据库： - 关键第三方库： ## 目录职责 - src/api/：路由层，只做参数校验和响应封装 - src/services/：业务逻辑层 - src/models/：数据模型 - src/utils/：纯函数工具 ## 代码规范 - 命名风格： - 错误处理方式： - 日志方式： - 异步处理方式：就这三部分，写起来不到十分钟。但每次和AI对话时把它贴进去，你会发现AI的输出质量有肉眼可见的提升。等你用顺手了，再逐步往里面补充数据模型、架构决策、已知技术债等内容。关键是开始做，而不是追求一步到位。契约的价值在于“持续维护”，而不在于“一次写完美”。8. 当项目已经烂了，怎么用契约来救如果你的项目已经处于“烂掉”的状态——命名混乱、依赖成网、错误处理五花八门——那契约同样可以帮你逐步恢复秩序，只是过程会更长一些。我的建议是分三步走：第一步，先写一份“现状契约”。不要试图描述“项目应该是什么样”，而是如实记录“项目现在是什么样”。把现有的目录结构、实际使用的技术栈、实际存在的命名风格都写进去。这份契约可能很丑，但它是对现状的准确描述。第二步，在现状契约的基础上，写一份“目标契约”。描述你希望项目变成什么样：统一的命名规范、清晰的模块边界、一致的错误处理方式。目标契约不需要很详细，但方向要明确。第三步，每次和AI对话时，同时贴入现状契约和目标契约。告诉AI：“当前项目状态如下，我希望向目标状态靠拢。请你在生成代码时，尽量符合目标契约的规范，如果和现状有冲突，优先遵循目标契约。”这样做的好处是，你不需要停下来专门做一次大重构。你可以在日常开发中，让AI帮你逐步把代码迁移到目标状态。每次修改一个文件，就让它更接近目标契约一点。几个月下来，项目就会慢慢恢复健康。这个过程急不得。我试过强行在一个周末重构一个烂掉的项目，结果改到一半就陷入了“改A导致B坏，改B导致C坏”的循环。后来改用这种“渐进式迁移”的方式，虽然慢，但每一步都是稳定的，不会引入新的混乱。9. 关于契约，我踩过的几个坑第一个坑是契约写得太细。我一开始把契约写成了详细的设计文档，每个函数的签名、每个字段的类型都列进去了。结果每次改代码都要同步改契约，维护成本太高，坚持了两周就放弃了。后来我把契约精简到只记录“约束”和“决策”，不记录“实现细节”，维护负担一下子就降下来了。第二个坑是契约和代码不同步。有一段时间我偷懒，代码改了但契约没更新。结果AI基于过时的契约生成了代码，和实际项目对不上，反而造成了更多混乱。从那以后我给自己定了个规矩：改代码必须同步改契约，就像改代码必须同步改测试一样。第三个坑是把契约当成万能药。契约能解决“一致性问题”，但解决不了“设计问题”。如果你的项目架构本身就有问题，契约只会帮你把问题固化下来。契约是维护工具，不是设计工具。架构设计还是得靠你自己想清楚。10. 最后一点个人体会我用AI编程的时间不算短了，从最早的代码补全工具，到后来的对话式编程，再到现在的多文件编辑，工具在变，但有一个东西始终没变：AI是你的放大器，不是你的替代品。你给它清晰的上下文，它就给你高质量的代码；你给它模糊的指令，它就给你一堆需要收拾的烂摊子。上下文契约这件事，本质上是在做一件很朴素的事情：把项目里那些“只可意会不可言传”的隐性知识，变成显性的、可传递的文档。这件事在AI编程时代之前就很重要，只是那时候开发者靠口口相传和代码审查来传递这些知识。现在AI成了开发团队的一员，它也需要这些知识，而且它比人类更需要——因为人类可以从代码里“猜”出规范，AI只能从你给它的文字里“读”出规范。所以，如果你正在用AI写一个稍微有点规模的项目，我强烈建议你从今天开始，花十分钟写一份最小可行的上下文契约。不用追求完美，先写起来，然后在实践中慢慢完善。这个小小的习惯，可能就是你的项目“烂掉”和“活下来”之间的分界线。