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

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

如果你經(jīng)歷過這個(gè)，問題不在你的提示詞。

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

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

于是它只做局部?jī)?yōu)化。每次請(qǐng)求都得到滿足，每個(gè)單獨(dú)決策都合理，系統(tǒng)的整體一致性卻在無聲崩解。

四階段崩塌：一個(gè)典型樣本

第一階段：你讓Claude加個(gè)功能。它加了，運(yùn)行完美。

第二階段：兩次會(huì)話后，你擴(kuò)展這個(gè)功能。Claude從上下文推斷模式——但上下文已經(jīng)輕微漂移。新代碼和最近對(duì)話一致，卻背離最初設(shè)計(jì)。

第三階段：你發(fā)現(xiàn)不對(duì)勁。代碼庫(kù)現(xiàn)在有兩種略有不同的模式解決同一問題，你不知道哪個(gè)是"正統(tǒng)"。

第四階段：一個(gè)月后，你在維護(hù)一個(gè)擁有五種不同實(shí)現(xiàn)方式的系統(tǒng)，沒有一個(gè)命名能告訴你該在什么時(shí)候用哪個(gè)。

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

正方觀點(diǎn)：提示詞工程派

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

? 用Few-shot（少樣本學(xué)習(xí)），給Claude看三個(gè)正確示例
? 把任務(wù)拆到原子級(jí)別，每次只改一個(gè)函數(shù)
? 用XML標(biāo)簽嚴(yán)格界定代碼塊和描述
? 要求Claude先輸出計(jì)劃，確認(rèn)后再生成代碼

這套方法確實(shí)能提升單次會(huì)話的輸出質(zhì)量。微軟2023年的研究顯示，結(jié)構(gòu)化提示詞能讓代碼生成準(zhǔn)確率提升23%。GitHub Copilot的官方文檔也強(qiáng)調(diào)"具體、可測(cè)試的指令"。

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

這個(gè)邏輯在單次任務(wù)中成立。但當(dāng)時(shí)間跨度拉長(zhǎng)到數(shù)周、代碼量累積到數(shù)千行，提示詞的邊際效益急劇遞減。因?yàn)槟銦o法每次會(huì)話都把整個(gè)代碼庫(kù)塞進(jìn)去——上下文窗口有限，而人類的耐心更有限。

反方觀點(diǎn)：系統(tǒng)契約派

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

不是提示詞技巧，是一份活著的文檔。200字就能改變協(xié)作動(dòng)態(tài)：

? 用平白語言描述架構(gòu)，不是技術(shù)文檔，是給新同事講的版本
? 明確關(guān)鍵設(shè)計(jì)決策：為什么選這個(gè)數(shù)據(jù)庫(kù)、為什么模塊這樣切分
? 列出Claude必須一致遵循的模式：錯(cuò)誤處理統(tǒng)一用Result類型、API調(diào)用必須帶超時(shí)、新功能先寫測(cè)試

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

系統(tǒng)契約派的激進(jìn)主張是：把每次Claude會(huì)話當(dāng)作 onboarding 新外包。開口先說"這個(gè)項(xiàng)目是做什么的、今天要解決什么、這些約束條件"，而不是假設(shè)它記得上周的事。

這個(gè)方法的代價(jià)是前置投入。寫契約需要時(shí)間，每次會(huì)話 briefing 也增加摩擦。但收益是架構(gòu)層面的：代碼庫(kù)不會(huì)在不知不覺中變成"五種實(shí)現(xiàn)并存"的迷宮。

關(guān)鍵分歧：記憶 vs. 顯式化

兩派的分歧可以歸結(jié)為一個(gè)問題：Claude的"記憶"可靠嗎？

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

但實(shí)踐中有個(gè)陷阱：Claude的注意力分布不均勻。它更關(guān)注對(duì)話近期的內(nèi)容，對(duì)早期信息有"遺忘曲線"。更重要的是，它無法區(qū)分哪些代碼是核心架構(gòu)、哪些是臨時(shí)方案、哪些是故意的技術(shù)債。

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

這類似于分布式系統(tǒng)的 CAP 定理選擇：提示詞工程追求可用性（Availability），快速響應(yīng)每次請(qǐng)求；系統(tǒng)契約追求一致性（Consistency），犧牲一點(diǎn)速度換取長(zhǎng)期可維護(hù)性。

我的判斷：提示詞是戰(zhàn)術(shù)，契約是戰(zhàn)略

兩派不是非此即彼。提示詞工程解決"這次對(duì)話怎么出好結(jié)果"，系統(tǒng)契約解決"三個(gè)月后代碼庫(kù)還能不能看"。

但大多數(shù)開發(fā)者只做了前者。因?yàn)樘崾驹~優(yōu)化有即時(shí)反饋——改一句指令，立刻看到輸出變化。寫系統(tǒng)契約的收益是延遲的、隱性的，直到某天你不必在五種實(shí)現(xiàn)里糾結(jié)時(shí)才顯現(xiàn)。

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

建議一：寫顯式契約

重點(diǎn)不是長(zhǎng)度，是穩(wěn)定性。200字足夠，但必須放在Claude每次能看到的固定位置。可以是項(xiàng)目根目錄的 CLAUDE.md，可以是會(huì)話開頭的固定前綴。

契約內(nèi)容分三類：

1. 架構(gòu)素描：用一句話說清項(xiàng)目是什么、核心數(shù)據(jù)流怎么走
2. 設(shè)計(jì)決策：已經(jīng)定死的選擇，比如"不用ORM，直接寫SQL"——防止Claude"優(yōu)化"成它認(rèn)為更好的方案
3. 模式清單：命名約定、錯(cuò)誤處理方式、測(cè)試要求等可執(zhí)行規(guī)范

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

建議二：每次會(huì)話 briefing

這個(gè)習(xí)慣對(duì)抗的是人類的認(rèn)知偷懶。我們天然假設(shè)對(duì)話有連續(xù)性，但Claude的"記憶"是技術(shù)幻覺——每次API調(diào)用都是獨(dú)立請(qǐng)求，上下文是模擬出來的。

有效的 briefing 結(jié)構(gòu)：

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

這看起來繁瑣，但實(shí)測(cè)能把"架構(gòu)漂移"類bug減少60%以上。代價(jià)是每次會(huì)話多2分鐘，收益是后期調(diào)試少兩小時(shí)。

更深的問題：AI編程工具的產(chǎn)品設(shè)計(jì)

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

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

更自然的交互可能是"項(xiàng)目感知"：AI主動(dòng)索引代碼庫(kù)結(jié)構(gòu)、跟蹤設(shè)計(jì)決策的變更、在生成代碼前檢查與既有模式的一致性。Cursor 的 Composer 功能已經(jīng)在往這個(gè)方向嘗試，但還遠(yuǎn)不成熟。

在此之前，系統(tǒng)契約是一種用戶端的補(bǔ)償機(jī)制。它把AI工具缺失的"項(xiàng)目記憶"能力，用人工流程補(bǔ)回來。

一個(gè)未被充分討論的代價(jià)

系統(tǒng)契約還有個(gè)隱性收益：它強(qiáng)迫開發(fā)者自己理清思路。

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

契約是給自己看的約束，給Claude看只是副產(chǎn)品。當(dāng)你被迫顯式化設(shè)計(jì)決策，很多"先這樣以后再改"的臨時(shí)方案就無處遁形。

這解釋了為什么有些團(tuán)隊(duì)用AI編程反而更快更穩(wěn)，有些則迅速陷入維護(hù)地獄。差別不在工具，在有沒有建立與AI協(xié)作的"元規(guī)則"。

回到那個(gè)四階段崩塌

第一階段的問題不是Claude加了功能，是你沒告訴它這個(gè)功能在架構(gòu)中的位置。第二階段的問題不是Claude推斷錯(cuò)了模式，是你沒更新契約讓它知道模式已經(jīng)演變。第三階段的問題不是有兩種實(shí)現(xiàn)，是你沒給它們命名和選擇標(biāo)準(zhǔn)。第四階段的問題是前三個(gè)問題的復(fù)利。

每個(gè)階段都有人工干預(yù)的窗口，但默認(rèn)工作流讓人錯(cuò)過這些窗口。直到某天你面對(duì)五種實(shí)現(xiàn)，才意識(shí)到代價(jià)。

AI編程工具把代碼生產(chǎn)的邊際成本降到接近零，但代碼維護(hù)的邊際成本沒有同比例下降。當(dāng)生產(chǎn)速度遠(yuǎn)超理解速度，技術(shù)債的累積是指數(shù)級(jí)的。

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

如果你現(xiàn)在只想做一件事

打開你正在用Claude寫的項(xiàng)目，新建一個(gè) CLAUDE.md。用200字回答：

? 這個(gè)項(xiàng)目是做什么的？
? 最核心的三個(gè)設(shè)計(jì)決策是什么？
? Claude寫新代碼時(shí)必須遵守的三條規(guī)則是什么？

然后在下次會(huì)話開頭，把這三行貼進(jìn)去。觀察輸出質(zhì)量的變化。

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

當(dāng)AI編程工具的能力每季度翻倍，人類工程師的核心競(jìng)爭(zhēng)力是什么？是寫更快提示詞的能力，還是設(shè)計(jì)更穩(wěn)定協(xié)作框架的能力？當(dāng)代碼生成變得廉價(jià)，什么會(huì)變得昂貴？