北京
你剛剛接手一個遺留的微服務模塊，團隊里的AI助手在三秒內就拉出了全套接口說明。路徑、方法、請求體、返回碼，每一項都標注得工工整整，連那個詭異的“寧可返回 418，也不返回 400”的邊界條件都原樣列出來了。可你盯著屏幕，腦子里只有一個念頭：這玩意兒當初究竟為什么非寫成一條茶壺？代碼和規格書都閉嘴，它們不會開口告訴你半年前那個周五下午，為什么產品經理跪求保留這個反直覺的邏輯。工程師圈子里正在蔓延一種濃烈的情緒：“文檔已經死了。”這個論斷聽起來干凈利落、黑白分明。可惜，它錯得徹徹底底。
眼下最時髦的那套敘事，是站在代理驅動開發的浪潮上講的：我們活在一個AI代理能直接啃源碼、秒讀OpenAPI規范的時代，何必再把人類工程師的寶貴小時，砸進注定過時的散文里？代碼的翻書速度太快了，人類手寫的文檔，從按下提交鍵的那一秒起就老了。這的確是一幅迷人的圖景，把所有工程的灰色地帶壓平成了二元選擇。可嚴格的決定論真理之源，本來就是一個美麗的泡影。代碼和規格書擅長告訴你系統是“怎樣”運轉的，但它們在解釋它“為什么”被建成這副模樣這件事上，有著結構性的無能。那個“為什么”，才是真正值錢的工程遺產。
即使你的系統完完全全是為AI代理這個下游消費者建造的，原生的API規格與運行現實之間，仍然橫亙著一道巨大的鴻溝。代理們在模式匹配和語法執行上堪稱天才，可一碰到架構哲學和人類意圖的背景音，它們的耳朵就聾了。我們仍舊需要文字，去給那些看不見的邊界畫上等高線。一份規格能抽絲剝繭地定義端點、參數、載荷，這沒問題；它捕捉不到的，是那種微妙的、在某個特定架構權衡面前為什么選了A而不是B的理由，或者那種沉默的、由遺留邊緣案例背負的歷史上下文。這些信息不會自己說話。
散文，本質上是在為非確定性系統安裝護欄。即便這護欄將來主要是機器在看，不是人類在看，書寫下來的文字，依然是傳輸意圖時杠桿最高的一條路徑。不要誤會，這絕不是鼓吹大家回到手動維護海量靜態Wiki頁面的手工年代。自動化在這套新體系里分量很重——那種隨代碼變更動態生成文檔的級聯式自動化，力量大得嚇人。但這里埋著一個致命的陷阱：用垃圾來描述垃圾，到頭來一無是處。一旦把文檔生成權徹底丟給未經校驗的大語言模型，我們得到的只會是一種幻覺上下文描述著飛速位移的代碼的回聲室。那不是清晰，那是噪聲。
關鍵就一點：人工監修。哪怕文檔百分之百是機器人驅動的，人類工程的審視也不可談判。生成的文本必須經由人的直覺校驗，才能確保它交付的，是一份精準的、站在更高處解釋全局的說明。不如把生成文檔當作API自身的非確定性表親來看——價值連城，但前提是韁繩得被緊緊攥在手里。然而，眼下這套新范式面前最大的路障，偏偏就是信任。文檔領域至今缺少一套可信的“直覺檢驗”指標，這對于人類開發者和自主代理構成了雙重瓶頸。早期開源時代，我們靠的是粗糙但見效的聲譽代理：一個倉庫掛著上萬顆 GitHub 星標，問題追蹤器活蹦亂跳，近期還有提交，你就可以大致推斷這個項目連同它的文字說明是靠譜的。而我們今天，恰恰還沒有找到這種新世界的信任鉚釘。
特別聲明：以上內容(如有圖片或視頻亦包括在內)為自媒體平臺“網易號”用戶上傳并發布，本平臺僅提供信息存儲服務。
Notice: The content above (including the pictures and videos if any) is uploaded and posted by a user of NetEase Hao, which is a social media platform and only provides information storage services.
