1. 從“補(bǔ)全代碼”到“交付功能”重新理解 Claude 寫代碼這件事很多人第一次聽說“用 Claude 寫全部代碼”腦子里浮現(xiàn)的畫面是打開一個(gè)聊天窗口敲一句“幫我寫個(gè)登錄頁面”然后復(fù)制粘貼。這種用法確實(shí)存在但它和真正把 Claude 當(dāng)作主力開發(fā)工具是兩件完全不同的事。前者是把模型當(dāng)成一個(gè)高級(jí)搜索引擎后者是把模型當(dāng)成一個(gè)能讀項(xiàng)目、能改文件、能跑命令、能提交 PR 的協(xié)作方。差別不在模型本身而在你給它搭的“工作環(huán)境”和“約束規(guī)則”。我自己從最早用聊天窗口貼代碼到后來把 Claude 接進(jìn)終端、接進(jìn)編輯器、讓它直接操作倉庫中間踩的坑基本都集中在三個(gè)地方上下文怎么給、權(quán)限怎么控、結(jié)果怎么驗(yàn)。這三個(gè)問題不解決模型再強(qiáng)也只能當(dāng)玩具解決了它才可能承擔(dān)真實(shí)項(xiàng)目里 60% 到 80% 的重復(fù)性編碼工作。這篇文章不打算復(fù)述官方文檔而是把“工程師到底怎么用 Claude 寫代碼”拆成可復(fù)現(xiàn)的環(huán)節(jié)從安裝和接入方式的選擇到AGENTS.md這類上下文文件的寫法再到讓它改代碼、跑測(cè)試、提 PR 的完整鏈路最后講清楚哪些活絕對(duì)不能交給它、哪些坑我踩過之后再也不碰。適合已經(jīng)會(huì)寫代碼、但還沒把大模型真正嵌進(jìn)日常開發(fā)流的人看也適合剛開始接觸 Claude Code 這類工具、想知道“別人到底怎么用”的讀者。需要先說明一點(diǎn)下面提到的具體命令、配置和文件結(jié)構(gòu)一部分來自我自己的實(shí)踐一部分是基于這類工具常見設(shè)計(jì)做的合理推斷。不同版本、不同接入方式會(huì)有差異重點(diǎn)是理解背后的思路而不是死記某一條命令。2. 接入方式的選擇終端、編輯器還是桌面端2.1 三種形態(tài)各自解決什么問題Claude 寫代碼的接入方式目前主流是三類終端里的命令行工具、編輯器插件、以及獨(dú)立的桌面客戶端。它們不是互相替代的關(guān)系而是對(duì)應(yīng)不同的工作場(chǎng)景。終端形態(tài)最大的優(yōu)勢(shì)是離倉庫最近。你在項(xiàng)目根目錄啟動(dòng)它能直接讀到當(dāng)前目錄的文件樹、git狀態(tài)、甚至最近的提交記錄。對(duì)于“改一個(gè)函數(shù)、跑一下測(cè)試、看 diff”這種高頻小循環(huán)終端形態(tài)的延遲最低也最容易和現(xiàn)有的npm、pytest、make等命令串起來。缺點(diǎn)是交互界面樸素長對(duì)話回溯不如圖形界面方便。編輯器插件解決的是邊看邊改的問題。你在文件里選中一段代碼直接讓它解釋、重構(gòu)、補(bǔ)測(cè)試改動(dòng)以 diff 形式呈現(xiàn)在編輯器里接受或拒絕都在同一個(gè)窗口完成。它適合“我已經(jīng)知道要改哪里只是懶得手寫”的場(chǎng)景。但插件對(duì)項(xiàng)目全局的理解通常弱于終端形態(tài)因?yàn)樗玫降纳舷挛耐窒抻诋?dāng)前打開的文件。桌面客戶端則更像一個(gè)獨(dú)立的工作臺(tái)適合做跨倉庫的調(diào)研、寫文檔、整理需求或者在不方便開終端的環(huán)境里做原型驗(yàn)證。它的短板是和本地文件系統(tǒng)的聯(lián)動(dòng)不如前兩者直接很多時(shí)候還是要靠復(fù)制粘貼。我的建議是主力用終端形態(tài)編輯器插件做補(bǔ)充桌面端留給非編碼任務(wù)。不要一上來就三個(gè)都裝先把一個(gè)用順再按需擴(kuò)展。2.2 安裝前必須確認(rèn)的環(huán)境前提在動(dòng)手安裝之前有幾個(gè)環(huán)境問題必須先確認(rèn)否則后面會(huì)卡在莫名其妙的地方。第一是Node.js 版本。這類命令行工具大多基于 Node 生態(tài)分發(fā)版本過低會(huì)直接報(bào)錯(cuò)。建議用當(dāng)前 LTS 版本安裝前先跑node -v確認(rèn)。如果機(jī)器上有多個(gè)項(xiàng)目依賴不同 Node 版本用版本管理工具切換不要硬改全局。第二是系統(tǒng)權(quán)限和虛擬化相關(guān)提示。在部分系統(tǒng)上首次啟動(dòng)會(huì)提示需要啟用某些平臺(tái)組件這屬于正常的運(yùn)行環(huán)境要求按提示開啟即可。如果公司電腦有安全策略限制提前和 IT 確認(rèn)別裝到一半被攔。第三是網(wǎng)絡(luò)與鑒權(quán)。無論用哪種接入方式都要先解決“模型怎么調(diào)用”的問題。有的走官方賬號(hào)登錄有的走 API Key有的接第三方兼容接口。這里有個(gè)原則鑒權(quán)信息只放在環(huán)境變量或?qū)Ｓ门渲美锝^不寫進(jìn)代碼倉庫。我見過有人把 Key 直接寫進(jìn)AGENTS.md或者提交到 git這是典型的自找麻煩。正確的做法是本地用.env文件并加入.gitignoreCI 環(huán)境用密鑰管理服務(wù)注入。第四是先在一個(gè)小倉庫里試。不要拿公司核心項(xiàng)目當(dāng)試驗(yàn)田。找一個(gè)自己的練手項(xiàng)目或者新建一個(gè)空倉庫把安裝、啟動(dòng)、第一次對(duì)話跑通再考慮遷移到真實(shí)項(xiàng)目。2.3 第一次啟動(dòng)后該做的三件事裝完之后別急著讓它寫業(yè)務(wù)代碼先做三件小事建立信任。第一件讓它描述當(dāng)前倉庫結(jié)構(gòu)。問一句“這個(gè)項(xiàng)目的目錄結(jié)構(gòu)是怎樣的入口文件在哪”看它能不能準(zhǔn)確讀出來。如果它答得含糊說明上下文沒接上先解決這個(gè)問題。第二件讓它做一個(gè)只讀操作。比如“找出所有沒有被引用的導(dǎo)出函數(shù)”或者“列出最近三次提交改動(dòng)了哪些文件”。只讀操作不會(huì)破壞任何東西但能驗(yàn)證它是否真的能訪問倉庫信息。第三件讓它改一個(gè)無關(guān)緊要的文件比如給某個(gè)工具函數(shù)補(bǔ)一行注釋然后你自己看 diff。這一步是建立“它改的東西我會(huì)檢查”的習(xí)慣后面所有操作都建立在這個(gè)習(xí)慣上。這三件事做完你基本就知道當(dāng)前這套配置的能力邊界在哪了。3. AGENTS.md 到底該寫什么把隱性規(guī)則變成顯性約束3.1 為什么需要一個(gè)上下文文件模型每次對(duì)話都是“失憶”的它不知道你的項(xiàng)目用什么框架、命名規(guī)范是什么、哪些目錄不能碰、測(cè)試怎么跑。如果每次都要在對(duì)話里重復(fù)這些信息效率極低而且容易漏。AGENTS.md這類文件的作用就是把這些每次都要說的規(guī)則固化下來讓模型在開始工作前自動(dòng)讀取。它本質(zhì)上是一份“給 AI 看的項(xiàng)目說明書”。寫得好模型第一次輸出就八九不離十寫得差你就要在每一輪對(duì)話里反復(fù)糾正。我見過太多人抱怨“模型不聽話”其實(shí)問題出在規(guī)則根本沒寫清楚。3.2 必須寫進(jìn)去的四類信息一份能用的AGENTS.md至少覆蓋四類內(nèi)容。第一類是項(xiàng)目定位和技術(shù)棧。用兩三句話說明這個(gè)項(xiàng)目是干什么的、用什么語言和框架、依賴管理工具是什么。比如“這是一個(gè)基于 Node 的 CLI 工具用 TypeScript 編寫包管理用 pnpm測(cè)試用 vitest”。這幾句話能讓模型在生成代碼時(shí)自動(dòng)匹配技術(shù)棧而不是給你寫一段 Python。第二類是目錄約定和禁區(qū)。明確哪些目錄是源碼、哪些是生成產(chǎn)物、哪些絕對(duì)不能改。比如“src/是源碼dist/是構(gòu)建產(chǎn)物不要手動(dòng)改migrations/下的文件一旦提交不要修改”。禁區(qū)寫清楚能避免很多災(zāi)難性操作。第三類是編碼規(guī)范和命令。包括命名風(fēng)格、導(dǎo)入順序、注釋語言以及最關(guān)鍵的——怎么跑測(cè)試、怎么跑 lint、怎么構(gòu)建。把命令寫進(jìn)去模型就能自己驗(yàn)證改動(dòng)而不是改完就交差。這一條是區(qū)分“能用”和“好用”的關(guān)鍵。第四類是協(xié)作規(guī)則。比如“每次改動(dòng)前先說明計(jì)劃”“不要一次改超過三個(gè)文件”“提交信息用中文還是英文”。這些規(guī)則決定了你和模型的協(xié)作節(jié)奏。下面是一個(gè)簡化示例實(shí)際項(xiàng)目按需增刪# 項(xiàng)目說明 這是一個(gè)內(nèi)部使用的數(shù)據(jù)處理 CLITypeScript Node 20包管理用 pnpm。 # 目錄約定 - src/ 源碼所有改動(dòng)只在這里 - tests/ 測(cè)試文件新增功能必須補(bǔ)測(cè)試 - dist/ 構(gòu)建產(chǎn)物禁止手動(dòng)修改 - config/ 配置文件改動(dòng)前先確認(rèn) # 常用命令 - 安裝依賴pnpm install - 跑測(cè)試pnpm test - 類型檢查pnpm typecheck - 構(gòu)建pnpm build # 協(xié)作規(guī)則 - 改動(dòng)前先用一句話說明計(jì)劃 - 單次改動(dòng)不超過 3 個(gè)文件 - 提交信息用中文格式類型: 簡述3.3 寫 AGENTS.md 最容易犯的三個(gè)錯(cuò)第一個(gè)錯(cuò)是寫得太長。有人把整個(gè)架構(gòu)文檔塞進(jìn)去幾千字結(jié)果模型每次都要消耗大量上下文去讀真正有用的規(guī)則反而被淹沒。原則是只寫“每次都需要知道”的信息詳細(xì)的架構(gòu)文檔放單獨(dú)文件需要時(shí)再引用。第二個(gè)錯(cuò)是規(guī)則模糊。“代碼要寫得優(yōu)雅”“注意性能”這種話等于沒寫。要寫成可執(zhí)行的判斷標(biāo)準(zhǔn)比如“函數(shù)超過 50 行就拆分”“避免在循環(huán)里做數(shù)據(jù)庫查詢”。第三個(gè)錯(cuò)是寫完就不管。項(xiàng)目在變規(guī)則也要跟著變。我習(xí)慣每次發(fā)現(xiàn)模型重復(fù)犯同一個(gè)錯(cuò)就回頭往AGENTS.md里補(bǔ)一條。這個(gè)文件是活的不是一次性作業(yè)。提示如果你的項(xiàng)目已經(jīng)有README或貢獻(xiàn)指南不要直接復(fù)制過來。AGENTS.md面向的是模型要更簡潔、更命令化去掉所有面向人類的客套話。4. 讓它真正改代碼從單文件到跨文件重構(gòu)的實(shí)操鏈路4.1 單文件改動(dòng)的標(biāo)準(zhǔn)流程單文件改動(dòng)是最基礎(chǔ)的場(chǎng)景但流程不對(duì)照樣出問題。我的標(biāo)準(zhǔn)流程是四步說計(jì)劃、看 diff、跑測(cè)試、再提交。第一步先讓它說計(jì)劃。不要直接說“幫我改這個(gè)函數(shù)”而是說“我想讓這個(gè)函數(shù)支持超時(shí)參數(shù)你先說說打算怎么改”。模型會(huì)給出一個(gè)方案你看一眼有沒有跑偏。這一步花不了幾秒鐘但能擋掉大部分方向性錯(cuò)誤。第二步讓它改然后你自己看 diff。不要因?yàn)樗f“已完成”就信了。重點(diǎn)看三件事有沒有動(dòng)到不該動(dòng)的文件、有沒有引入新的依賴、邏輯是不是真的符合你的預(yù)期。我遇到過模型為了“順手優(yōu)化”把無關(guān)代碼也改了的情況diff 一看就發(fā)現(xiàn)。第三步跑測(cè)試。如果項(xiàng)目有測(cè)試讓它自己跑如果沒有至少跑一下類型檢查和 lint。這一步是底線不能省。第四步確認(rèn)無誤再提交。提交信息可以讓它生成但你要過一眼。4.2 跨文件重構(gòu)怎么控制風(fēng)險(xiǎn)跨文件重構(gòu)是模型最容易翻車的地方。它可能改了一個(gè)函數(shù)的簽名卻漏掉了三個(gè)調(diào)用點(diǎn)或者重命名了一個(gè)模塊卻忘了更新導(dǎo)入路徑?？刂骑L(fēng)險(xiǎn)的核心是縮小單次改動(dòng)范圍并且讓它在改之前先列出影響面。具體做法是先讓它“找出所有引用了這個(gè)函數(shù)的地方”確認(rèn)清單完整然后讓它“按這個(gè)清單逐個(gè)修改每改完一個(gè)文件停下來等我確認(rèn)”。不要一次性說“把整個(gè)項(xiàng)目里所有用到這個(gè)函數(shù)的地方都改了”那樣你根本來不及檢查。另一個(gè)技巧是用 git 分支隔離。每次讓它做大改動(dòng)之前先開一個(gè)新分支。改完如果不對(duì)直接丟棄分支不影響主線。這個(gè)習(xí)慣救過我很多次。還有一個(gè)細(xì)節(jié)跨文件改動(dòng)時(shí)讓它先改被依賴的底層再改上層調(diào)用。順序反了的話中間狀態(tài)會(huì)有一堆編譯錯(cuò)誤很難判斷是模型改錯(cuò)了還是順序問題。4.3 測(cè)試和驗(yàn)證環(huán)節(jié)不能省模型生成的代碼最大的問題不是“寫不出來”而是“看起來對(duì)但實(shí)際有邊界問題”。比如它寫的解析函數(shù)正常輸入沒問題遇到空值就崩。這類問題只有跑測(cè)試才能發(fā)現(xiàn)。我的做法是讓它改代碼的同時(shí)補(bǔ)測(cè)試。在AGENTS.md里寫清楚“新增功能必須補(bǔ)測(cè)試”它就會(huì)在改完之后順手寫幾個(gè)用例。這些用例不一定完美但至少覆蓋了主路徑。然后你自己再補(bǔ)幾個(gè)邊界用例。如果項(xiàng)目測(cè)試覆蓋率本來就低可以先讓它“為這個(gè)模塊補(bǔ)一批測(cè)試覆蓋主要分支”跑通之后再動(dòng)業(yè)務(wù)代碼。這樣你手里就有一張安全網(wǎng)后面改動(dòng)心里有底。注意不要完全信任模型寫的測(cè)試。它有可能寫出“永遠(yuǎn)通過”的假測(cè)試比如斷言寫得太寬松或者干脆沒斷言。跑完之后掃一眼測(cè)試內(nèi)容確認(rèn)它真的在驗(yàn)證行為。5. 從改代碼到提 PR把重復(fù)勞動(dòng)交給它把判斷留給自己5.1 讓它生成 PR 描述和提交信息寫 PR 描述是典型的重復(fù)勞動(dòng)而且模型做得不差。它能讀 diff、讀提交記錄然后總結(jié)出“改了什么、為什么改、怎么驗(yàn)證”。我的做法是讓它生成初稿然后自己改兩處補(bǔ)充業(yè)務(wù)背景和刪掉它過度自信的表述。提交信息同理。約定好格式之后讓它按格式生成你過一眼就行。這里有個(gè)小技巧在AGENTS.md里寫清楚提交信息的格式和語言它就會(huì)一直遵守不用每次提醒。5.2 自動(dòng)化檢查該掛在哪一環(huán)真正高效的用法是把模型接進(jìn) CI 流程的前置環(huán)節(jié)而不是替代 CI。比如在提交前讓它跑一遍 lint 和類型檢查把明顯問題擋在本地CI 里該跑的測(cè)試、構(gòu)建、安全掃描一個(gè)都不能少。我見過有人讓模型“自己判斷能不能合并”這是危險(xiǎn)的。模型的判斷不能替代 CI 的硬性檢查。正確的分工是模型負(fù)責(zé)生成和初步驗(yàn)證CI 負(fù)責(zé)最終把關(guān)。5.3 哪些 PR 絕對(duì)不要讓模型碰有幾類改動(dòng)我的原則是模型可以參與討論但不能直接提交。第一類是涉及鑒權(quán)、加密、支付的代碼。這類邏輯一旦出錯(cuò)后果不是“功能不可用”而是“數(shù)據(jù)泄露”或“資金損失”。模型可以幫你讀代碼、解釋邏輯但最終改動(dòng)必須人工寫、人工審。第二類是數(shù)據(jù)庫遷移腳本。遷移一旦執(zhí)行就很難回滾模型對(duì)生產(chǎn)數(shù)據(jù)狀態(tài)的理解有限讓它生成遷移腳本風(fēng)險(xiǎn)太高。第三類是刪除操作。無論是刪文件、刪表還是刪字段都要人工確認(rèn)。模型對(duì)“這個(gè)字段還有沒有在用”的判斷經(jīng)常不準(zhǔn)。第四類是依賴升級(jí)。大版本升級(jí)往往涉及破壞性變更模型可能只改了表面調(diào)用沒處理深層兼容問題。這四類之外的日常業(yè)務(wù)代碼、工具函數(shù)、測(cè)試、文檔基本都可以放心交給它。6. 踩過的坑和踩完之后總結(jié)的規(guī)矩6.1 上下文給太多和給太少都會(huì)出問題剛開始用的時(shí)候我習(xí)慣把整個(gè)項(xiàng)目都塞給它覺得信息越多越好。結(jié)果發(fā)現(xiàn)模型反而抓不住重點(diǎn)改出來的東西東一榔頭西一棒子。后來改成按需給上下文改哪個(gè)模塊就只讓它讀那個(gè)模塊和直接依賴效果明顯好轉(zhuǎn)。反過來上下文給太少也不行。有一次我只說“改一下這個(gè)函數(shù)”沒告訴它這個(gè)函數(shù)被哪些地方調(diào)用結(jié)果它改了簽名上層全炸了。所以現(xiàn)在的習(xí)慣是改之前先讓它自己找出調(diào)用點(diǎn)把影響面摸清楚再動(dòng)手。6.2 模型“自信地犯錯(cuò)”是最難防的模型最危險(xiǎn)的地方不是它說“我不會(huì)”而是它用非?？隙ǖ恼Z氣給出錯(cuò)誤答案。比如它說“這個(gè) API 支持某某參數(shù)”實(shí)際上根本不支持或者說“我已經(jīng)處理了所有邊界情況”實(shí)際上漏了空數(shù)組。防這個(gè)的辦法只有一個(gè)關(guān)鍵結(jié)論必須自己驗(yàn)證。它說某個(gè)庫有某個(gè)方法你去文檔確認(rèn)它說改完了你去看 diff它說測(cè)試通過了你去看測(cè)試輸出。不要因?yàn)樗Z氣肯定就跳過驗(yàn)證。6.3 密鑰泄露這件事必須從流程上堵死用大模型寫代碼密鑰泄露是真實(shí)存在的風(fēng)險(xiǎn)。模型可能會(huì)把你的 Key 寫進(jìn)示例代碼、寫進(jìn)注釋、甚至寫進(jìn)它生成的配置文件。一旦這些內(nèi)容被提交就等于公開了。我的做法是三層防護(hù)第一層所有密鑰只放環(huán)境變量代碼里只引用變量名第二層.gitignore里把.env、*.key、config.local.*全部排除第三層提交前用工具掃一遍 diff確認(rèn)沒有硬編碼的密鑰。第三層可以用現(xiàn)成的密鑰掃描工具也可以寫個(gè)簡單的正則檢查。還有一點(diǎn)不要在對(duì)話里粘貼真實(shí)密鑰。如果非要讓模型幫你調(diào)試鑒權(quán)邏輯用占位符代替真實(shí)值調(diào)試完再換回去。6.4 別讓它一次改太多這是我最深刻的教訓(xùn)。有一次我讓它“重構(gòu)整個(gè)數(shù)據(jù)處理模塊”它一口氣改了十幾個(gè)文件結(jié)果中間狀態(tài)根本沒法驗(yàn)證最后只能全部回滾重來。現(xiàn)在的規(guī)矩是單次改動(dòng)不超過三個(gè)文件超過就拆成多輪。每輪改完、驗(yàn)證完、提交完再開始下一輪。慢是慢一點(diǎn)但可控。而且拆成小步之后出問題容易定位回滾成本也低。7. 我現(xiàn)在的日常用法和幾條硬規(guī)矩用到現(xiàn)在我的日常流程基本固定下來了。早上開工先讓它讀一遍昨天的提交記錄總結(jié)一下進(jìn)度然后按任務(wù)清單逐個(gè)處理每個(gè)任務(wù)走“說計(jì)劃、改代碼、跑測(cè)試、提交”的循環(huán)遇到不確定的 API 用法讓它先查再寫寫完之后自己過一遍 diff確認(rèn)沒問題再推。幾條硬規(guī)矩我基本不會(huì)破鑒權(quán)、支付、遷移、刪除這四類代碼模型只讀不寫。任何改動(dòng)必須自己看 diff不看不算完成。密鑰永遠(yuǎn)不進(jìn)代碼也不進(jìn)對(duì)話。單次改動(dòng)不超過三個(gè)文件超了就拆。AGENTS.md持續(xù)維護(hù)發(fā)現(xiàn)重復(fù)錯(cuò)誤就補(bǔ)規(guī)則。這套用法下來重復(fù)性的編碼工作確實(shí)省了很多時(shí)間但判斷和把關(guān)的責(zé)任一點(diǎn)沒少。模型是個(gè)很好的執(zhí)行者但它不是責(zé)任人。代碼最終署的是你的名字該看的、該驗(yàn)的、該拒的一樣都不能省。如果你剛開始用建議先從一個(gè)小項(xiàng)目、一個(gè)模塊試起把上面這套流程跑順再逐步擴(kuò)大范圍。別一上來就想著“全自動(dòng)”那大概率會(huì)翻車。先把協(xié)作節(jié)奏建立起來效率自然就上來了。