开发者用AI写代码3年，发现1个文件夹能让错误率暴跌

GitHub上有个叫Yoav Abrahami的人，去年干了一件事：他把和AI结对编程的经验，压缩成了一个文件夹的命名规则。结果这个叫Design-Log的方法，正在悄悄改变一小撮开发者的工作流——不是那些写CRUD的，是做安全工具、搞复杂系统的。

我花了两周跟踪这个方法的实际用例，发现它的核心就一句话：别再把AI当搜索引擎用，把它当同事。而那个文件夹，就是你们俩的共享大脑。

上下文墙：每个用AI写过1000行以上代码的人都撞过的墙

有个做网络安全工具的研究者跟我描述过他的典型一天：早上让Claude Sonnet 3.7写个漏洞扫描器的认证模块，下午加新功能时AI已经忘了早上的加密方案，晚上部署时发现密钥管理逻辑前后矛盾。他算过，平均每个复杂功能要经历12-17轮"复制终端输出→贴到聊天框→等AI道歉→再复制回去"的循环。

这不是模型能力问题。Claude 3.5/3.7、GPT-4、Gemini 1.5 Pro他都重度用过，Warp的agentic终端、WaveTerm的多路复用也订阅了一年多。瓶颈在于对话本身的结构——它是一次性的、线性的、不可追溯的。

Yoav Abrahami给这个现象起了个名字：上下文墙（Context Wall）。当代码库超过某个阈值，AI对项目历史的记忆就像金鱼，每次新对话都是重启。你喂给它50页的需求文档，它点头；三天后你问"为什么这里用RSA而不是EC"，它开始编。

更隐蔽的伤害是决策漂移。研究者举了个例子：他让AI实现"失败三次后锁定账户"的安全策略，第一轮代码是对的；第二轮加日志功能时，AI为了"优化"把锁定逻辑改成了可配置参数，默认关闭。没有恶意，只是忘了为什么当初要硬编码。

Design-Log：一个文件夹如何重构人机协作

Yoav的解法朴素到让人尴尬：在Git仓库里建一个./design-log/目录，用Markdown把每个设计决策写下来。不是文档，是日志——带时间戳、带讨论过程、带被否决的方案。

三条铁律：

1. 写之前先读（Read Before You Write）

任何AI会话开始前，先加载相关的设计日志。不是可选步骤，是强制流程。研究者现在的习惯：新建功能分支时，第一件事是把./design/下的相关.md文件塞进Claude的上下文窗口，比喂代码库高效10倍——代码是"是什么"，设计日志是"为什么"。

2. 实现之前先设计（Design Before Implementation）

不再直接说"给我写个OAuth中间件"。而是先写./design-log/auth-middleware.md，里面包含：威胁模型（哪些攻击向量要防）、决策记录（为什么选JWT而不是session）、验收标准（什么日志级别、超时策略）。AI在这个阶段是评审者，不是执行者。

3. 历史不可篡改（Immutable History）

设计日志一旦提交，只追加不修改。需要变更？新建文件，引用旧决策，说明废止原因。研究者展示了他的一个案例：最初用bcrypt做密码哈希，后来迁移到Argon2，文件夹里有完整的决策链——AI永远不会再问"为什么不用bcrypt"，因为它能读到当时的性能测试数据。

一个真实用例：从12轮循环到3轮定稿

研究者允许我引用他最近的一个项目：基于LLM的日志异常检测工具。按老方法，这种涉及数据流设计、模型选择、隐私合规的三端系统，他预估需要200+轮对话。

用Design-Log后，结构变成：

./design-log/00-threat-model.md — 数据驻留要求、PII处理边界
./design-log/01-pipeline-arch.md — 为什么流式处理优于批处理
./design-log/02-model-selection.md — 本地小模型 vs API大模型的成本矩阵
./design-log/03-implementation-log.md — 实际编码中的妥协和债务

关键转变发生在第三天。他发现初始架构在高峰流量下会丢日志，需要改缓冲策略。在老工作流里，这意味着向AI解释整个系统重来一遍；现在，他追加./design-log/01-pipeline-arch-v2.md，引用v1的瓶颈分析，AI在15秒内理解了变更范围。

最终统计：设计阶段4个文件，实现阶段7个日志条目，总对话轮次31轮——其中28轮是单轮确认（"按设计日志第3节实现，对吗？"），只有3轮需要实质性纠偏。

为什么这个方法反直觉地有效

我注意到一个细节：Yoav和这位研究者都不是传统软件工程师。Yoav是Wix的前首席架构师，研究者自述"不是开发者，是研究员和tinkerer"。这个背景可能是关键——他们没有"代码即真相"的包袱，更愿意把设计意图显性化。

专业开发者常有的惯性：觉得写设计文档是"额外工作"，代码注释足够。但AI不是人类同事，它不会从代码风格里读出"这里用了单例模式是因为测试时mock方便"，它只会照抄模式然后在你没注意的地方再创建一个实例。

Design-Log强迫你做的，其实是把隐性知识变成契约。研究者有个精妙的类比：以前和AI结对编程像打电话，信号不好就重拨；现在像用Git协作，有提交历史、有差异对比、有回滚点。

另一个被低估的收益：审计友好。安全工具需要合规审查时，./design-log/文件夹就是现成的决策证据链。研究者最近的一个渗透测试报告，直接引用了三个设计日志文件来说明某处"看似奇怪"的权限设计——审查员读完沉默了5分钟，然后签字。

局限和正在发生的进化

这个方法不是银弹。我整理了实际使用者反馈的三个摩擦点：

启动成本。第一个项目需要克制"先写代码"的冲动，研究者估计多花了40%时间在前期设计。但第二个项目开始，他直接复制了第一个项目的./design-log/模板，边际成本骤降。

工具链缺口。目前没有IDE原生支持Design-Log工作流。研究者的土方案：Warp终端分屏，左边代码右边日志，手动复制路径到Claude。他期待有人做个插件，能自动根据当前编辑的文件推荐相关设计日志。

团队协作未定。Yoav的原方案假设单人+AI，研究者尝试和另一个人类开发者共享设计日志时，发现需要额外约定：谁负责更新日志？代码审查时先看日志还是先diff？这些问题还没有最佳实践。

有意思的是，Cursor和Windsurf这类AI原生IDE的最新版本，开始实验"项目记忆"功能——自动提取代码中的关键决策，生成可查询的知识库。这像是Design-Log的自动化版本，但使用者普遍反馈：机器提取的"决策"缺少被否决的方案，而知道"为什么没选B"往往比"为什么选A"更重要。

研究者最近在实验一个变体：把设计日志和测试用例绑定。每个设计决策必须对应至少一个失败测试（证明约束有效）和一个通过测试（证明实现正确）。这让他发现了两处AI生成的"正确代码"——功能对，但违反了设计日志里的安全约束。

Yoav Abrahami在原文里埋了一句很少被引用的话："AI不是替代思考，是放大思考的质量——但前提是你真的在思考。" Design-Log的残酷之处在于，它把"有没有思考"变得可审计了。那些习惯让AI代劳设计决策的人，会发现自己面对一个空文件夹时无所适从。

研究者上周发给我一张截图：他的某个设计日志文件被另一个开发者点了星，附言"终于知道为什么这里的超时设成7秒而不是5秒或10秒"。这个细节他从来没在代码注释里写过，因为"当时觉得太显然"。

你的代码库里，有多少个"7秒"正在等待被解释？