用AI写代码三周后，项目突然崩了。追查三小时，元凶是两星期前一段"完全没问题"的代码。这不是你不会写提示词——是你们的协作从根本上就缺了张蓝图。
被误读的病灶
市面上九成教程都在教你怎么"驯服"AI：指令要具体、给示例、拆小任务。这些边际优化确实有用，但搞错了主战场。
我见过太多AI辅助的代码库，核心问题从来不是提示词质量。是架构漂移——你和Claude技术上在协作，脑子里却没有同一张系统图。
Claude记得住这回合你要什么，但它不知道你的模块边界在哪、命名约定是什么潜规则、哪些文件是承重墙、哪里你故意留了技术债。它只能局部优化，产出满足当下请求的代码。每个单独看都合理的决策，系统性地瓦解着整体一致性。
原文作者描述了一个经典四阶段崩塌：
第一阶段：你让Claude加功能，它加了，跑得完美。
第二阶段：两回合后你扩展这功能，Claude从上下文推断模式——但上下文已经漂了。新代码和最近对话一致，和最初设计背离。
第三阶段：你发现怪事。代码库现在有两种稍有不同的模式解决同一问题，你不知道哪个是"正统"。
第四阶段：一个月后，你在维护一个有五种写法的东西，命名完全看不出该用哪个。
这不是Claude的bug，是协作断裂。模型没法跨会话维持一致性，除非你给它工具。
正方：提示词优化派
主流声音认为，问题出在用户不会"说话"。更精确的指令、更丰富的上下文示例、更细粒度的任务拆分，能让输出质量跃升。
这派观点有数据支撑。Anthropic自己的研究显示，结构化提示词确实能降低幻觉率。很多开发者的实践经验也印证：给Claude看现有代码片段、明确输出格式要求，短期效果立竿见影。
更激进的玩法是"提示词工程"——把常见任务封装成可复用的模板，甚至用元提示词（meta-prompt）让AI自己优化指令。这套方法论在特定场景下效率极高，比如生成标准化CRUD代码或单元测试。
但这里有个隐藏假设：AI的记忆和推理是连续的。实际上，Claude的上下文窗口虽大，却非真正的长期记忆。每次会话都是新的起点，只是带了点历史 baggage。
提示词优化派的问题在于，把AI当成了需要"调教"的工具，而非需要"协作"的伙伴。你越精进指令技巧，越容易陷入一种幻觉：只要我说得够清楚，它就能理解整个系统。
真相是，再完美的提示词也替代不了共享的认知框架。
反方：架构契约派
原文作者代表的另一种思路：别折腾提示词了，先给AI一张地图。
核心主张是"显式契约"——在动手写任何重要代码前，先写一份简短文档，用平白语言定义：架构长什么样、关键设计决策是什么、Claude该遵循哪些模式保持一致。这不是给人类看的文档，是给AI的锚定点，让它能做局部一致、全局也兼容的决策。
200字就能显著改变动态。这个数字很关键：它说明契约不需要厚重，需要的是存在。
更激进的实践是把每次Claude会话当作" onboarding 新外包"。新外包第一天需要上下文：项目目标、已定决策、锋利边缘在哪。大多数人误以为Claude记得上周的事，它没有。 briefing 它。
这个转变——开场白变成"这是代码库做什么的、今天做什么、约束条件是什么"——能大幅减少导致维护噩梦的漂移。
契约派的底层洞察是：AI编码工具的本质是状态管理问题。人类开发者有跨时间的连贯心智模型，AI没有。填补这个gap不能靠更聪明的提示词，只能靠更结构化的信息传递机制。
我的判断：契约是基础设施，提示词是战术动作
两派不是非此即彼，是层次问题。
提示词优化解决的是"单次交互质量"，架构契约解决的是"跨会话一致性"。当你用Claude写第100个功能时，前者帮你这回合不出错，后者帮你100个功能不会互相打架。
更关键的是成本结构。提示词工程是持续投入——每次新任务都要重新设计指令。架构契约是一次性投入——前期花两小时写清楚，后期每次会话省下的认知负荷和返工时间，复利惊人。
原文作者没说的一个维度：团队规模。个人项目里，架构漂移靠开发者自己的记忆还能勉强兜住。三人以上团队共用Claude辅助开发，没有显式契约就是灾难——每个人和AI的"默契"都不一样，代码库迅速分裂成多个平行宇宙。
另一个被低估的点：契约文档本身就是可测试的。你可以把它喂给Claude，让它检查新代码是否符合约定。这比人工code review更前置，成本更低。
具体怎么落地？原文给了两个 actionable 建议，值得展开。
契约文档写什么
不是写给自己看的架构设计文档，是给AI看的决策摘要。关键三部分：
一是架构素描。用一句话说清系统核心抽象，比如"所有业务逻辑在领域层，API层只做序列化和校验"。Claude不需要知道每个类的关系，需要知道哪里该放什么。
二是模式清单。列出"遇到X情况，用Y方式处理"的显式规则。比如"所有异步操作必须用Result类型包裹，禁止裸抛异常"。这些是代码审查时不会逐行检查、但累积起来决定代码气质的东西。
三是债务地图。坦诚标注哪里切了角、为什么、计划什么时候还。Claude看到"这里临时绕过类型系统，Q3重构"和看到一段怪代码，推断出的后续方案完全不同。
长度控制在200-500字。太长AI抓不住重点，太短缺关键约束。
会话开场怎么 briefing
别直接扔需求。三句话结构：
上下文："我们在做X系统，当前阶段是Y，今天解决Z问题。"
约束："注意A模块是性能敏感区，B模式已废弃别用，C文件是生成的别改。"
输出要求："需要D格式的结果，包含E但不包含F。"
这看起来是更好的提示词技巧？不，区别在信息类型。普通提示词优化聚焦"怎么表达需求"，briefing聚焦"同步系统状态"。前者让AI更懂你的话，后者让AI更懂你的系统。
一个实用技巧：把契约文档和最近相关代码片段一起塞进上下文窗口。Claude的200K上下文足够容纳中型项目的核心模块，这是它的优势，也是你的责任——别浪费在无关文件上。
更深层的行业信号
这篇文章值得注意的，不是具体建议，是它揭示的AI工具演进阶段。
第一阶段，我们把AI当搜索引擎用，问问题拿答案。第二阶段，当执行器用，给指令拿代码。现在进入第三阶段：当协作者用，需要共享上下文、对齐目标、管理长期状态。
这恰好对应软件开发本身的成熟度曲线。个人英雄主义 → 工程化流程 → 协作基础设施。AI编码工具正在快速经历同样的演进。
原文没提但相关的：Cursor、Windsurf等AI原生IDE已经在尝试解决部分问题——自动索引代码库、跨文件引用、甚至维护"项目记忆"。但这些是工具层面的补丁，不能替代开发者的主动设计。契约文档的价值，恰恰在于它是人类可理解、可审计、可争论的，而黑箱化的AI记忆不是。
另一个观察：这个问题在Claude上特别明显，因为它的设计哲学更偏向" helpful assistant "——你说什么它尽力满足。相比之下，o1等推理模型会更频繁地反问、指出潜在冲突。但长远看，无论模型多聪明，跨会话的一致性都需要外部化机制。
给从业者的行动清单
如果你正在或计划用Claude辅助开发：
今天就能做的：打开你最近一个AI辅助的项目，找一段"当时没问题、现在看不懂"的代码，追溯它诞生的会话。你会发现上下文漂移的蛛丝马迹。
这周要做的：选一个活跃项目，写第一份架构契约。别追求完美，写下你直觉上"Claude应该知道但没地方知道"的三件事。
下个月验证的：把契约文档作为所有Claude会话的固定输入，观察返工率和"奇怪代码"的出现频率变化。
给团队负责人的：把契约文档纳入代码审查范围，不是审查文档本身，是审查新代码是否违背契约。这比审查代码风格更有杠杆效应。
开放提问
当AI编码工具从"助手"变成"同事"，我们的工程实践准备好了吗？契约文档会不会成为新的"代码注释"——写的时候虔诚，维护的时候遗忘？或者，它反而倒逼我们写出更清晰、更可传递的架构决策？你在项目中是怎么处理人和AI的"共同记忆"问题的？
热门跟贴