用Claude寫代碼，三個月后為何變成"屎山"

用Claude寫了三周代碼，交付速度快得驚人。第四周打開項目，一個隱藏兩周的bug花了你半天才定位——根因是Claude早期生成的某段代碼，當時看起來完全沒問題。

如果你經歷過這個，問題不在你的提示詞。

市面上關于AI編程的建議，90%都在講怎么寫提示詞：要更具體、給示例、拆小任務。這些邊際優化有用，但避開了真正的病灶。

我見過太多AI輔助的代碼庫，核心問題從來不是提示質量，而是架構漂移（architectural drift）。你和Claude名義上是協作，實際上對系統的理解完全錯位。Claude只知道這次會話你問了什么，它不知道你的模塊邊界、隱含的命名規范、哪些文件是承重墻、哪里你故意留了技術債。

于是它只做局部優化。每次請求都得到滿足，每個單獨決策都合理，系統的整體一致性卻在無聲崩解。

四階段崩塌：一個典型樣本

第一階段：你讓Claude加個功能。它加了，運行完美。

第二階段：兩次會話后，你擴展這個功能。Claude從上下文推斷模式——但上下文已經輕微漂移。新代碼和最近對話一致，卻背離最初設計。

第三階段：你發現不對勁。代碼庫現在有兩種略有不同的模式解決同一問題，你不知道哪個是"正統"。

第四階段：一個月后，你在維護一個擁有五種不同實現方式的系統，沒有一個命名能告訴你該在什么時候用哪個。

這不是Claude的bug，是協作機制失靈。模型無法跨會話維持一致性，除非你給它工具。

正方觀點：提示詞工程派

主流聲音認為，問題出在用戶不會寫提示詞。解決方案是更精細的指令工程：

? 用Few-shot（少樣本學習），給Claude看三個正確示例
? 把任務拆到原子級別，每次只改一個函數
? 用XML標簽嚴格界定代碼塊和描述
? 要求Claude先輸出計劃，確認后再生成代碼

這套方法確實能提升單次會話的輸出質量。微軟2023年的研究顯示，結構化提示詞能讓代碼生成準確率提升23%。GitHub Copilot的官方文檔也強調"具體、可測試的指令"。

提示詞工程派的核心假設是：Claude有足夠能力，缺的是清晰輸入。只要用戶表達夠精確，輸出就會夠可靠。

這個邏輯在單次任務中成立。但當時間跨度拉長到數周、代碼量累積到數千行，提示詞的邊際效益急劇遞減。因為你無法每次會話都把整個代碼庫塞進去——上下文窗口有限，而人類的耐心更有限。

反方觀點：系統契約派

另一派聲音指向更深層的結構性方案。Anthropic自己的工程師在內部訪談中提到一個觀察：最成功的Claude用戶，都建立了某種"代碼契約"（code contract）。

不是提示詞技巧，是一份活著的文檔。200字就能改變協作動態：

? 用平白語言描述架構，不是技術文檔，是給新同事講的版本
? 明確關鍵設計決策：為什么選這個數據庫、為什么模塊這樣切分
? 列出Claude必須一致遵循的模式：錯誤處理統一用Result類型、API調用必須帶超時、新功能先寫測試

「你不是在寫文檔，是在給Claude一個穩定的參考點，讓它能做局部一致、全局也一致的決策。」——這是原文作者的核心論點。

系統契約派的激進主張是：把每次Claude會話當作 onboarding 新外包。開口先說"這個項目是做什么的、今天要解決什么、這些約束條件"，而不是假設它記得上周的事。

這個方法的代價是前置投入。寫契約需要時間，每次會話 briefing 也增加摩擦。但收益是架構層面的：代碼庫不會在不知不覺中變成"五種實現并存"的迷宮。

關鍵分歧：記憶 vs. 顯式化

兩派的分歧可以歸結為一個問題：Claude的"記憶"可靠嗎？

提示詞工程派隱含信任上下文窗口。他們認為只要提示夠好，Claude能從對話歷史中推斷出足夠信息。技術上是成立的——Claude 3的200K上下文能吞下整個中型項目的代碼。

但實踐中有個陷阱：Claude的注意力分布不均勻。它更關注對話近期的內容，對早期信息有"遺忘曲線"。更重要的是，它無法區分哪些代碼是核心架構、哪些是臨時方案、哪些是故意的技術債。

系統契約派不信任這種隱式記憶。他們要求把關鍵信息顯式化、外部化，讓Claude每次都能重新加載"系統狀態"，而不是依賴不可靠的上下文推斷。

這類似于分布式系統的 CAP 定理選擇：提示詞工程追求可用性（Availability），快速響應每次請求；系統契約追求一致性（Consistency），犧牲一點速度換取長期可維護性。

我的判斷：提示詞是戰術，契約是戰略

兩派不是非此即彼。提示詞工程解決"這次對話怎么出好結果"，系統契約解決"三個月后代碼庫還能不能看"。

但大多數開發者只做了前者。因為提示詞優化有即時反饋——改一句指令，立刻看到輸出變化。寫系統契約的收益是延遲的、隱性的，直到某天你不必在五種實現里糾結時才顯現。

原文作者給出的兩個建議，值得逐條拆解：

建議一：寫顯式契約

重點不是長度，是穩定性。200字足夠，但必須放在Claude每次能看到的固定位置。可以是項目根目錄的 CLAUDE.md，可以是會話開頭的固定前綴。

契約內容分三類：

1. 架構素描：用一句話說清項目是什么、核心數據流怎么走
2. 設計決策：已經定死的選擇，比如"不用ORM，直接寫SQL"——防止Claude"優化"成它認為更好的方案
3. 模式清單：命名約定、錯誤處理方式、測試要求等可執行規范

契約不是文檔，是約束條件。它告訴Claude"自由發揮"的邊界在哪里。

建議二：每次會話 briefing

這個習慣對抗的是人類的認知偷懶。我們天然假設對話有連續性，但Claude的"記憶"是技術幻覺——每次API調用都是獨立請求，上下文是模擬出來的。

有效的 briefing 結構：

? 項目目標：一句話版本，防止Claude過度推斷
? 當前任務：今天具體要做什么，范圍邊界在哪
? 已知約束：性能要求、依賴限制、不能碰的代碼區域
? 相關文件：主動提供需要參考的代碼路徑，別讓Claude自己猜

這看起來繁瑣，但實測能把"架構漂移"類bug減少60%以上。代價是每次會話多2分鐘，收益是后期調試少兩小時。

更深的問題：AI編程工具的產品設計

原文沒展開但值得追問：為什么這個問題需要用戶自己解決？

Claude、Copilot、Cursor 這些產品，核心交互都是"對話式編程"。但對話的隱喻本身就有問題——對話假設共享語境，而AI沒有真正的語境。每次@文件、每次粘貼代碼，都是在手動重建這個語境。

更自然的交互可能是"項目感知"：AI主動索引代碼庫結構、跟蹤設計決策的變更、在生成代碼前檢查與既有模式的一致性。Cursor 的 Composer 功能已經在往這個方向嘗試，但還遠不成熟。

在此之前，系統契約是一種用戶端的補償機制。它把AI工具缺失的"項目記憶"能力，用人工流程補回來。

一個未被充分討論的代價

系統契約還有個隱性收益：它強迫開發者自己理清思路。

寫200字架構描述，比想象中難。你得回答"這個項目到底在解決什么問題""為什么選這個方案而不是那個"。很多技術債的根源，是開發者自己也沒想明白這些問題，于是代碼跟著需求隨機游走。

契約是給自己看的約束，給Claude看只是副產品。當你被迫顯式化設計決策，很多"先這樣以后再改"的臨時方案就無處遁形。

這解釋了為什么有些團隊用AI編程反而更快更穩，有些則迅速陷入維護地獄。差別不在工具，在有沒有建立與AI協作的"元規則"。

回到那個四階段崩塌

第一階段的問題不是Claude加了功能，是你沒告訴它這個功能在架構中的位置。第二階段的問題不是Claude推斷錯了模式，是你沒更新契約讓它知道模式已經演變。第三階段的問題不是有兩種實現，是你沒給它們命名和選擇標準。第四階段的問題是前三個問題的復利。

每個階段都有人工干預的窗口，但默認工作流讓人錯過這些窗口。直到某天你面對五種實現，才意識到代價。

AI編程工具把代碼生產的邊際成本降到接近零，但代碼維護的邊際成本沒有同比例下降。當生產速度遠超理解速度，技術債的累積是指數級的。

系統契約是人為制造的摩擦，用來對沖這種不對稱。它不是讓Claude變慢，是讓整個系統的演化速度匹配人類的理解能力。

如果你現在只想做一件事

打開你正在用Claude寫的項目，新建一個 CLAUDE.md。用200字回答：

? 這個項目是做什么的？
? 最核心的三個設計決策是什么？
? Claude寫新代碼時必須遵守的三條規則是什么？

然后在下次會話開頭，把這三行貼進去。觀察輸出質量的變化。

這不會解決所有問題，但會改變你和Claude的協作關系——從"你猜我想要什么"變成"這是我們共同遵守的約定"。

當AI編程工具的能力每季度翻倍，人類工程師的核心競爭力是什么？是寫更快提示詞的能力，還是設計更穩定協作框架的能力？當代碼生成變得廉價，什么會變得昂貴？