開發者用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秒"正在等待被解釋？