公司推行AI First後為AI另立代碼規範：一篇掘金長文記錄二層規範結構的實作輪廓

2026年9月6日，掘金平臺作者「阿南」發布一篇篇幅近四十八分鐘閱讀量的技術長文，標題為「項目中新增給AI制定的代碼規範」。文章記錄其所屬公司在推行「AI First」策略後，將既有針對人類工程師的代碼培訓規範，改寫為供AI編程工具讀取的專案文件，並設計出一套可跨專案複用的二層結構。本臺依據該篇公開貼文與可核實的周邊資料，整理事件的輪廓、具體條目與產業背景。

事件的起點：從培訓工程師到約束AI

根據原 文，作者所在公司開始推行「AI First」，方向是以後所有代碼都盡量交由AI編寫。作者的判斷是「趨勢使然」，因此過去用於內部培訓的代碼規範，現在的對象從工程師換成了AI工具，做法是把規範寫成文件，讓AI在生成代碼時讀取並遵守。

這不是單一公司的孤立動作。與工程師社羣中流傳的後端轉AI的三個月彎路等轉職敘述對照，可以看見同一波AI編程工具普及下，企業內部流程調整與個人職涯路線兩個不同層面的反應。前者處理組織如何約束機器產出，後者處理個人如何與機器協作。

二層結構：通用規範與專案補充規則分離

原 文給出的核心設計是二層結構。第一層是通用規範，置於 docs/standards/IOS_DEVELOPMENT.md，收錄跨專案通用的內容；第二層是專案專屬規則，置於各專案目錄下的 AGENTS.md，例如 qiji/AGENTS.md。作者說明，公司專案較多，每個專案又橫跨 iOS、Android、Flutter 三個技術棧，因此先把一個專案的規範編寫完成，其他專案可直接複用，而這個複用過程本身也計畫交由AI執行。

規則之間的優先順序在文件中有明確定義。通用規範是預設基線，專案層的 AGENTS.md 可以補充或收緊規則；兩者衝突時，只有明確寫出原因與適用範圍的專案規則才可覆蓋通用規範。子目錄還可以再放置更具體的 AGENTS.md 進一步收緊，但若要放寬強制要求，必須經模組負責人確認。文件同時聲明，開發者、AI編程工具與自動化腳本均須遵守這套規則。

iOS 規範條目：命名、網路層與日誌脫敏

在 iOS 部分，文件對修改範圍劃出明確界線。預設只允許修改自有源碼目錄，禁止改動或格式化 Pods、External、第三方 framework 與 xcframework 等生成或外部代碼，除非需求明確要求並經過評審。修改工程配置時，也只能調整與當前需求相關的 target、build configuration 與文件引用，禁止無關的 pbxproj 排序或重寫。

技術約定方面，條目相當具體。Swift 代碼必須相容專案現行的 Swift 5.0 設定；Objective-C 業務類型優先沿用既有的 HXQ、HXS 等命名前綴；實現方法的左大括號單獨一行，指標星號靠近變數名。新增異步代碼必須沿用所在模組現有的回呼、Promise 或 async/await 模式，不得在單一需求中混用架構。Objective-C 呼叫 Swift 時，必須核對實際生成的 Swift.h 名稱、Bridging Header 與所有相關呼叫方。

網路與資料層的條目偏向風險控制。新增或修改接口必須復用專案現有網路層，並保留既有的鑑權、簽名、加解密、錯誤映射與日誌處理。安全請求邏輯應集中在現有 Swift 元件中，Objective-C 相容層保持輕量，禁止在業務頁面重複實作協議細節。修改請求或響應模型、加密信封、序列化欄位及快取結構時，必須同時檢查 Objective-C 與 Swift 兩側的相容性。

日誌與本地化條目同樣具約束力。Release 環境不得新增無條件輸出的 print、NSLog 或等效日誌；網路日誌禁止輸出 Token、Cookie、完整請求頭、未脫敏參數、加密金鑰或解密後的敏感響應。本地化則優先沿用現有的封裝入口，不得為單一需求另建一套機制。

依賴管理條目要求，依賴變更必須同時檢查 Podfile、Podfile.lock、Swift Package 配置、workspace 與相關 target 連結；Flutter add-to-app、CocoaPods 與 Swift Package 的整合邊界不得在無關需求中調整。文件並明確指出，該倉庫尚未統一引入 SwiftFormat、SwiftLint 或 clang-format，因此規範中不得假設這些工具可用。

為何寫給AI的規範與寫給人的不同

從條目設計可以看出這套文件的取向差異。傳統代碼規範多聚焦風格與可讀性，例如命名、縮排與註解習慣。這份文件的重量則明顯放在邊界與禁區：哪些目錄不可碰、哪些既有機制不可繞過、哪些輸出不可出現。這類「負面清單」式條款，對應的是AI編程工具的一個已知特性，也就是生成過程可能觸及需求範圍之外的代碼，或以自認合理的方式重構既有結構。

原 文提到，生成這份規範時，作者讓AI參考了官方與大型企業的規範，同時以公司內部代碼規範和歷史風格為主要依據。換言之，規範本身的產出過程也是人機協作，人提供公司脈絡與歷史約定，AI負責整理成結構化文件。

訊源與可核實邊界

本事件屬於個人技術分享性質，訊源為掘金平臺上的單一作者貼文。文中所涉公司名稱、專案名稱（qiji、QeekLive）與內部推行「AI First」的具體時程，均來自作者自述，未有公司官方管道的獨立佐證。閱讀量方面，截至本臺查核時，該文顯示閱讀數為個位數，與其篇幅形成明顯落差，顯示內容尚在早期傳播階段，後續是否被廣泛引用仍有待觀察。

與其他平臺對照，AGENTS.md 作為AI編程工具的配置文件名，近年已在多種開發工具的官方文件中被採用，做法是將專案約定寫入倉庫根目錄或子目錄，供工具在生成代碼前讀取。原 文的二層結構是將此慣例與公司內部多專案、多技術棧的現實結合，屬於既有實務的具體落地，而非新提出的標準。

後續觀察

這篇長文呈現的，是企業在AI編程工具普及後必然面對的治理問題：當代碼的主要產出者從人換成模型，規範的讀者、格式與執行方式都要跟著調整。文中可複用的二層結構、明確的覆蓋優先序與負面清單式條目，提供了一個可直接檢視的樣本。至於這類「寫給AI的規範」會在多大程度上取代傳統的工程師培訓文件，或兩者長期並存，原 文未給出答案，目前也缺乏可量化的產業數據可供比對。