過去半年我所在的團隊開始把一大部分重復性編碼任務交給 AI 完成包括接口對接、數(shù)據(jù)清洗、前端表格頁甚至是重構歷史遺留模塊。功能完成的速度確實快但 Code Review 的時間卻肉眼可見地變長了。原因很簡單AI 生成代碼的“可讀性”經常不在線。它不是寫錯而是寫得讓人看不懂——命名隨意、函數(shù)冗長、上下文邏輯糾纏在一起評審時你甚至需要先把代碼重寫一遍才能確認它是否符合需求。這篇文章不打算教你怎么挑選 AI 工具而是想系統(tǒng)梳理一下如何讓 AI 生成的代碼更容易理解、審查和維護。我踩過的坑、總結出的提示詞寫法、以及拿到初稿后的重構套路都會寫在下面希望能幫你把 AI 編碼真正接入到團隊工作流里。1. 先拆解問題AI 生成代碼最常見的三種“機器味”如果你做過幾十次 AI 代碼審查一定會發(fā)現(xiàn)那些“能跑但難讀”的代碼并不是隨機犯錯而是很有規(guī)律地栽在幾個固定地方。先把這些“機器味”擺到臺面上后面才知道怎么治。1.1 命名空間里的抽象垃圾我審查 AI 生成的 diff 時第一眼永遠是變量名。模型特別喜歡產出data1、result2、temp、info這類名字。不是說不能用temp但在一個函數(shù)里同時出現(xiàn)temp、temp1、temp2或者用data代表“從接口拿到的用戶列表”又用另一個data代表“頁面表單提交的字典”——這就是災難。有一次 AI 幫我們寫一個數(shù)據(jù)同步腳本核心變量分別叫a、b、c然后c在函數(shù)中間被重新賦值成完全不同的東西。功能跑通了沒錯但審查時我根本不敢點“通過”。因為我無法從代碼本身判斷b到底是“上次同步時間”還是“同步條數(shù)”。可讀性差本質上是在逼讀者去“考古”——你得順著上下文一點點推斷原作者想干什么。命名問題還有一個隱蔽變體反義命名。is_not_disabled、should_skip_delete這種雙重否定名字邏輯上沒錯但閱讀時每個人都要多做一次布爾轉換。AI 并不會主動考慮“讀者心智負擔”它只會在訓練數(shù)據(jù)里挑選出現(xiàn)頻率高的表達方式。1.2 一個函數(shù)干三件事“每個函數(shù)只做一件事”是工程師掛在嘴邊的話但 AI 不會自動遵守。模型更傾向于生成流水賬式函數(shù)先初始化配置再遍歷數(shù)據(jù)中間順手更新數(shù)據(jù)庫最后拼接返回結果甚至還在里面加了一段日志輸出。這種函數(shù)的共同特征是行數(shù)很長嵌套很深多個if分支互相糾纏。我曾經審查過一個 200 行的 Python 函數(shù)它同時負責解析配置、調用第三方接口、維護緩存、寫審計日志。AI 之所以這么寫大概率是因為它把“正常人類的實現(xiàn)方式”理解為“從上往下堆步驟”而一個典型的中級工程師照著需求文檔寫也容易寫出這種代碼。問題在于這樣的函數(shù)一旦出現(xiàn) Bug定位成本會成倍上升你無法快速確定是解析出錯、緩存出錯、還是日志寫入阻塞導致接口超時。更麻煩的是長函數(shù)還會讓“復用”變成奢望。另一個需求也想用其中的緩存更新邏輯但因為你沒法安全地“提取”出那一小段只能復制粘貼。AI 生成代碼本來就是要壓縮開發(fā)時間結果這種結構反而制造出大量重復代碼為后續(xù)維護埋雷。1.3 注釋在講另一個版本的故事第三類機器味是注釋和代碼“脫節(jié)”。AI 非常擅長生成模板式注釋// 獲取用戶列表、# 初始化數(shù)據(jù)庫連接。這類“是什么”的注釋對于沒有上下文的新人幾乎毫無價值。更糟的是AI 有時會根據(jù)過時的推理生成注釋而代碼執(zhí)行路徑已經被它自己改過了最終注釋和真實行為不一致。我還經常在 AI 生成代碼里看到空的TODO、無用的import、以及被注釋掉的整段舊邏輯。如果人寫代碼留下這些東西多少會被提醒清理但 AI 生成時會忠實地把訓練語料里的壞習慣“搬運”過來。審查者面對這些噪聲時相當于在信號里找信號嚴重拖慢速度。為了讓你對這三種問題有個直觀印象我整理了一張簡單的對照表機器味典型表現(xiàn)審查代價修復方向命名隨意data1、temp、result2、雙重否定布爾讀者需要反復跳轉上下文用語義化命名能表達“是什么”和“為什么”函數(shù)臃腫一個函數(shù) 200 行多分支多職責難以定位 Bug無法復用按職責拆分控制圈復雜度注釋脫節(jié)模板注釋、無用 TODO、死代碼注釋誤導噪聲淹沒邏輯重寫為“為什么注釋”刪除無效內容如果你也經常在審查 AI 代碼時頭疼大概率是這三種機器味同時出現(xiàn)了。2. 模型為什么總寫出難讀的代碼目標、視野與訓練數(shù)據(jù)的合謀很多人以為 AI 寫得難讀是因為“還不夠聰明”。從工程實踐看這更像是一系列結構性原因疊加的結果。理解這些原因你才能設計出有效的提示詞而不是反復在 Review 里罵模型。2.1 模型優(yōu)化的目標不是“可維護性”大語言模型的訓練目標是預測下一個 Token 的概率。它選擇一段代碼是因為這段代碼在概率上“更像人類寫的”而不是因為它“更容易被別人維護”。這兩個目標之間存在本質偏差。人類代碼庫里大量存在的是“當時能用就行”的一次性腳本、Stack Overflow 上的最小示例、以及個人項目里的快速實現(xiàn)。這些代碼在統(tǒng)計分布上非常常見所以 AI 很容易學到它們的形態(tài)。你希望 AI 寫出結構清晰、命名講究的代碼但它學到的“標準答案”恰恰是大眾平均水平甚至低于平均值。這就解釋了為什么僅僅在提示詞里寫“保持代碼可讀性”效果往往很差。模型聽不懂這種抽象口號它更擅長模仿具體的輸出格式。2.2 上下文窗口帶來的局部視野工程師寫一個模塊時腦子里通常裝著整個系統(tǒng)的邊界入口參數(shù)、數(shù)據(jù)庫表結構、調用方約定、錯誤處理策略。但模型在生成時一次只能處理窗口內有限的 Token。窗口越長注意力越容易被稀釋越到后面的代碼就越容易跟前文脫節(jié)。典型情況是AI 在文件前半部分定義了一個叫users的變量到文件中間已經忘了它代表的是“從數(shù)據(jù)庫查出來的用戶記錄”于是把新的返回結果也塞進同一個users到后半段再出現(xiàn)時變量類型已經悄悄變了。這種“局部視野”帶來的不一致性在長文件、長函數(shù)里尤其明顯。所以一個很實用的經驗是不要指望 AI 一次性生成一個 500 行的完整模塊。讓它分段生成、控制每次輸出范圍可讀性通常會有明顯提升。2.3 訓練數(shù)據(jù)里混入大量“示例級”代碼AI 的訓練語料來自公開代碼倉庫、技術博客、問答社區(qū)。這些地方的主體內容是什么是示例代碼、教學代碼、個人腳本。它們的特點是強調“跑通”忽視“維護”。你在教程里更?？吹絘 3; b 4; print(a b)而不是一個帶完整類型標注、錯誤處理、邊界測試的生產級模塊。模型并不真正理解哪些代碼是“生產環(huán)境標準”哪些只是“演示片段”。在它眼中倉庫里提交的代碼和問答里的代碼片段都是合法樣本。于是生成結果里偶爾會出現(xiàn)測試殘留、無意義變量、缺少空值判斷等“業(yè)余感”也就不奇怪了。想對抗這一點光靠模型自身很難必須由你把生產級標準注入到提示詞里。2.4 缺少“評審打回”的反饋回路人類工程師的代碼質量之所以能提高很大程度靠的是 Code Review。你提交的代碼被同事打回過幾次下一次你自然會注意命名和拆分。但 AI 目前的工作模式通常是“一次性生成一次性交付”沒有經歷過“被要求重構”的反饋循環(huán)。它不會在生成之后問自己這個函數(shù)是不是太長這個變量名別人能看懂嗎這里的異常處理是不是吞掉了錯誤這些思考是審查者視角而模型默認站在“生成者”視角只考慮當前這一步寫什么。所以把“審查視角”前置到提示詞里是提升 AI 代碼可讀性性價比最高的一步。我接下來要講的就是把這一步落地的具體做法。3. 把可讀性條款寫進提示詞從“生成代碼”到“生成可審查代碼”想讓 AI 一開始就輸出可讀性合格的代碼不要指望靠運氣也不要在生成之后再花大量時間返工。正確的做法是在提示詞階段就把可讀性標準“焊死”。3.1 把“可讀性”翻譯成機器能執(zhí)行的具體規(guī)則“請寫一個可讀性好的函數(shù)”這句話基本無效。模型不知道你的團隊標準是什么它只會按照訓練分布里最常見的“可讀性”來寫。你需要把它翻譯成一條條可以被檢查的規(guī)則。我的常用做法是把規(guī)則拆成四類命名規(guī)則變量名必須體現(xiàn)業(yè)務語義禁止data1、tmp這類無意義命名布爾變量用is/has/can開頭禁止雙重否定。函數(shù)規(guī)則單個函數(shù)不超過 30 行條件嵌套不超過 3 層一個函數(shù)只承擔一個職責。常量規(guī)則禁止魔法數(shù)字所有業(yè)務數(shù)字必須定義成具名常量或枚舉字符串必須使用常量不允許直接散落在邏輯中。注釋規(guī)則只寫“為什么”不寫“是什么”刪除模板式注釋和無效 TODO。把這些規(guī)則原樣貼在提示詞里效果遠好于一句“要可讀”。你會發(fā)現(xiàn)模型輸出的代碼形態(tài)會明顯改變因為它確實有能力模仿你給出的格式關鍵在于你有沒有給出明確的格式約束。3.2 給一個差示例和好示例比說教管用我做過對比實驗同樣一個需求一組提示詞只寫“注意可讀性”另一組提示詞貼了一個“好代碼示例”。結果第二組的可讀性評分明顯更高。模型本質上是在做模式匹配你給它的示例越具體它越能復制示例里的風格。實際寫提示詞時我會特意放一個“差代碼”和“改進后代碼”的對照并用一兩句話說清楚改進點下面是同一功能的兩種實現(xiàn)。 差實現(xiàn) - 變量名無意義 - 一個函數(shù) 40 行 - 魔法數(shù)字散落 好實現(xiàn) - 命名語義清晰 - 單一職責每個函數(shù)控制在 15 行內 - 業(yè)務常量集中定義 請按照“好實現(xiàn)”的風格完成以下需求這樣做的原理很簡單Few-shot 示例提供了明確的風格錨點。模型不需要理解“可讀性”的抽象含義它只需要對齊你給出來的具體輸出形態(tài)。3.3 分兩步生成先出設計再出代碼如果你讓 AI 一口氣生成一個完整模塊它極容易陷入局部視野把前文的設計原則忘光。更穩(wěn)妥的方法是讓生成過程分成兩步。第一步讓 AI 先給出設計方案文件清單、每個函數(shù)的名字和職責、關鍵數(shù)據(jù)結構、輸入輸出定義。你在這個階段就能檢查命名和結構是否合理不合理的地方直接在方案階段改掉。第二步確認方案后再讓 AI 按方案逐段實現(xiàn)代碼。這樣每一步的上下文都聚焦在當前的一個函數(shù)上模型的局部視野問題可以被明顯抑制。我在實際項目中用這套“兩段式”提示詞之后Review 返工率至少下降了一半。因為命名和結構在方案階段已經被我把過關生成階段只需要談實現(xiàn)。3.4 我常用的 Prompt 模板下面貼一套我自己在項目里反復用的 Prompt 模板你可以直接復制后修改業(yè)務部分角色你是一名資深軟件工程師代碼風格注重可讀性和可維護性。 任務根據(jù)需求實現(xiàn)功能并輸出完整的可審查代碼。 硬性要求 1. 所有變量、函數(shù)、類名必須使用語義化命名禁止無意義縮寫。 2. 函數(shù)控制在 30 行以內單個函數(shù)只做一件事。 3. 禁止魔法數(shù)字所有業(yè)務常量定義在文件頂部或常量模塊中。 4. 注釋只解釋“為什么”不重復“是什么”。 5. 不生成無用 import、死代碼、TODO 占位。 6. 錯誤處理必須顯式不允許靜默吞掉異常。 輸出格式 - 先列出本次實現(xiàn)的文件結構和核心函數(shù)列表 - 再逐段輸出代碼 - 最后用 3 句話說明你的設計思路和潛在風險點注意最后一條要求 AI 輸出“設計思路和潛在風險點”。這會讓模型在生成時帶一點審查者視角很多可讀性問題在源頭就被抑制了。4. 拿到初稿之后的五個重構動作從“能跑”到“能被看懂”即使提示詞做到位AI 的初稿也不可能百分之百達到可讀性標準。關鍵是你要有一套固定的重構動作像流水線一樣快速過一遍。下面五個動作是我每次審查 AI 代碼時都會做的順序也基本固定。4.1 動刀命名把 temp 改成有語義的名字命名是對可讀性影響最大、成本卻最低的一步。我會先掃描函數(shù)內所有變量名問自己一個問題光看名字能不能猜出這個變量的含義和生命周期舉一個實際的例子。AI 生成的一段緩存處理代碼temp cache.get(user_id) if temp is not None: data temp else: data fetch_from_db(user_id) cache.set(user_id, data)temp和data到底是什么讀者需要讀完 5 行邏輯才能猜。改成這樣cached_profile cache.get(user_id) if cached_profile is not None: return cached_profile profile fetch_from_db(user_id) cache.set(user_id, profile)命名一變邏輯關系立刻就清楚了。這個小步驟不需要任何復雜工具純粹靠審查時的自覺但它能節(jié)省后續(xù)所有讀者的大量時間。4.2 拆分“作者函數(shù)”一個函數(shù)只做一件事遇到超過 40 行的函數(shù)我的默認動作是把它拆開。拆函數(shù)不是單純把代碼塊剪切到新函數(shù)里而是要按“職責”找邊界。典型的信號是函數(shù)里的代碼可以分成“準備數(shù)據(jù)”“處理數(shù)據(jù)”“寫入結果”三個段落且每一段之間通過臨時變量傳遞信息。這一步重構效果非常直接# 重構前一個函數(shù)處理所有事 def import_orders(raw_file): raw load_raw_file(raw_file) parsed [parse_line(line) for line in raw] deduped deduplicate(parsed) validate_orders(deduped) save_to_db(deduped) send_notification(len(deduped)) # 重構后每個函數(shù)各自獨立主流程一目了然 def import_orders(raw_file): orders parse_orders_from_file(raw_file) orders deduplicate_and_validate(orders) save_to_db(orders) notify_import_result(len(orders))拆分后的主函數(shù)像目錄一樣讀者一眼就能看到整個流程的骨架。想深入看細節(jié)再逐個跳進子函數(shù)。認知負擔完全不是一個量級。4.3 消滅魔法數(shù)字常量與枚舉AI 代碼里最常出現(xiàn)的維護隱患就是魔法數(shù)字。比如if retry_count 3: alarm()這個3是代表“最大重試次數(shù)”還是“連續(xù)失敗次數(shù)閾值”如果換個業(yè)務場景應該改哪里AI 不會替你思考這些問題它只會把數(shù)字原樣放在判斷條件里。我的處理方式是把所有業(yè)務數(shù)字提為命名常量或者放進枚舉MAX_CONNECT_RETRY 3 if retry_count MAX_CONNECT_RETRY: trigger_alarm()不要小看這一步。常量集中定義后你只需要檢查常量名就能理解整個文件的業(yè)務規(guī)則。魔法數(shù)字看起來是小問題實際上一旦業(yè)務變化排查成本會成倍上升。4.4 重寫注釋留 Why刪 WhatAI 生成的注釋大多屬于“墻壁紙”類型# 獲取數(shù)據(jù)、// 循環(huán)遍歷。這類注釋對理解代碼沒有任何增量信息并且會因為代碼更新而過時。我會保留兩類注釋解釋“為什么這么寫”的注釋和跨層級的“設計意圖”注釋。比如# 這里不能直接清空表因為上游可能還有未落庫的引用記錄 clear_staging_table(with_checkTrue)這種注釋是真正有價值的。至于# 調用接口獲取用戶列表這種廢話直接刪掉即可。代碼本身已經很清楚地表達了這個動作。還有一個基本原則如果注釋內容需要經常變動那說明代碼還沒有抽取出合適的抽象。好的注釋應當指向穩(wěn)定層而不是追逐實現(xiàn)細節(jié)。4.5 收斂狀態(tài)與副作用能純函數(shù)就純函數(shù)AI 很習慣寫“有狀態(tài)”的函數(shù)改全局變量、寫日志、更新緩存、操作數(shù)據(jù)庫全混在一起。副作用越多函數(shù)越難測試也越難看懂。審查時我會先問這個函數(shù)是不是可以直接接收參數(shù)、返回結果而不依賴外部狀態(tài)如果是就優(yōu)先寫成純函數(shù)。比如# 重構前依賴外部狀態(tài) total 0 def calc_revenue(items): for item in items: total item.price return total # 重構后純函數(shù)輸入輸出一目了然 def calc_revenue(items): return sum(item.price for item in items)純函數(shù)最大的好處是讀者不需要追蹤“這個變量在哪被改過”的全局歷史。你的函數(shù)是黑盒子輸入明確輸出明確審查自然輕松。5. 把可讀性變成團隊習慣審查清單、評分卡與 AI 輔助閉環(huán)一個人能靠自覺把可讀性做好但團隊里的代碼質量要想穩(wěn)定提升需要把“可讀性”從個人偏好變成可執(zhí)行、可度量的流程。這也是我最后想展開的部分。5.1 把“感覺”變成“清單”“這段代碼看起來不好讀”是主觀感受無法指導新手審查者。更有效的做法是把可讀性標準拆成一張硬性清單每條都可以回答“是”或“否”。我團隊現(xiàn)在用的核心清單包括所有命名是否表達業(yè)務語義是否存在data1、tmp、x這類名稱每個函數(shù)是否明顯只做一件事是否超過 30 行是否存在超過 3 層的條件嵌套業(yè)務數(shù)字和字符串是否已定義為常量注釋是否解釋了“為什么”是否存在廢話注釋、死代碼、無用 import函數(shù)是否盡量保持純函數(shù)副作用是否集中在邊界層這張清單不需要很復雜但它把“可讀性”具象成了可以逐條檢查的項目。審查者照著清單走就不會因為“說不上哪里不對”而草率通過。5.2 給代碼可讀性打分如果想讓可讀性持續(xù)提升建議在 Review 時順手打一個分。我用的是一張五分制評分卡維度1 分3 分5 分命名大量無意義命名基本語義化但有歧義命名能直接表達意圖和邊界函數(shù)結構單個函數(shù) 100 行以上部分拆分但職責混雜純函數(shù)優(yōu)先拆分干凈注釋價值模板注釋為主有解釋但部分過時只保留有價值的 Why 注釋常量與魔法值大量魔法數(shù)字部分常量化所有業(yè)務參數(shù)統(tǒng)一管理一致性風格前后矛盾局部一致與團隊規(guī)范完全對齊每次評分不需要很正式但堅持記錄之后你就能看出 AI 生成的代碼在哪個維度最常失分然后針對性調整提示詞。比如連續(xù)幾周命名分都低就在 Prompt 里多放幾個好的命名示例。5.3 讓 AI 在生成代碼時順便自評除了人工打分還可以讓 AI 自己先做一輪“可讀性自檢”。這個方法在上面的 Prompt 模板里已經埋了伏筆要求 AI 在輸出代碼后用幾句話列出它的設計思路和潛在風險。實踐下來效果不錯。模型在自檢時會把注意力放到異常處理、邊界條件、命名一致性上相當于在生成階段加了一層輕量的 Review。你拿到的代碼已經是“被 AI 自己預先審查過一遍”的版本。更進階的做法是要求 AI 輸出代碼的“審查說明”比如每個函數(shù)分別負責什么可能的風險點在哪如果需求變化應該先修改哪個函數(shù)這個流程會讓 AI 的思維組織更接近“可維護代碼”應該有的樣子。雖然不能完全替代人工審查但對提升初稿質量幫助極大。5.4 在 CI 里讓機器先讀一遍最后可讀性不應該只依賴人。很多可讀性問題其實可以被工具自動發(fā)現(xiàn)。在 CI 里接入靜態(tài)檢查和復雜度度量成本不高收益卻很穩(wěn)定。常用的組合包括圈復雜度檢查超過閾值直接構建失敗單函數(shù)行數(shù)限制超過行數(shù)打警告命名規(guī)范檢查強制 camelCase、snake_case 等統(tǒng)一風格重復代碼檢測發(fā)現(xiàn) Copy-Paste 時在 Review 中高亮無用依賴和死代碼檢查清理 AI 留下的垃圾把這些工具跑在 AI 生成代碼的提交上就等于在最前面加了一道自動過濾網(wǎng)。人的審查精力可以用來關注那些工具發(fā)現(xiàn)不了的問題比如設計合理性、業(yè)務邏輯正確性。工具和清單配合使用后團隊里已經形成了一套閉環(huán)AI 生成初稿 → 自評 → 靜態(tài)檢查 → 人工審查 → 打分 → 把失分點反饋回提示詞。我自己的體會是經過兩三周的迭代AI 生成代碼的“機器味”會明顯下降Review 不必再像從前那樣逐行重寫。當然可讀性這件事沒有終點每次新需求、新語言、新框架都會帶來新的挑戰(zhàn)。但只要把標準、工具、反饋三條線建立起來AI 生成代碼的維護成本完全可以被壓到可接受范圍內。最后分享一個我自己的使用習慣凡是 AI 生成的代碼合并前我都會在本地跑一遍“可讀性十五秒測試”——隨便打開一個文件不看注釋只看函數(shù)名和變量名嘗試復述這個模塊的功能。如果復述不清楚說明代碼還不夠直觀。這個土辦法花不了多少時間卻能幫你擋住很大一部分“能用但沒法維護”的 AI 代碼。希望這些經驗也能在你們的項目里派上用場。