一、為什么要先做倉(cāng)庫(kù)知識(shí)包

很多團(tuán)隊(duì)在使用 Codex 時(shí)，習(xí)慣把當(dāng)前問題、幾段代碼和一句“幫我改一下”直接發(fā)出去。簡(jiǎn)單任務(wù)這樣做沒問題，但一旦涉及跨文件修改、接口聯(lián)動(dòng)、舊邏輯兼容、測(cè)試補(bǔ)齊，缺少上下文就會(huì)讓 Codex 只能猜。猜得越多，人工復(fù)查成本越高。

倉(cāng)庫(kù)知識(shí)包的作用，就是把項(xiàng)目里反復(fù)需要解釋的**資料提前整理好。靈能API提供統(tǒng)一 API 中轉(zhuǎn)站入口，CC Switch保存項(xiàng)目對(duì)應(yīng)配置，而知識(shí)包則告訴 Codex：這個(gè)倉(cāng)庫(kù)怎么組織、核心模塊在哪里、接口如何命名、哪些邊界不能隨便改。

二、知識(shí)包不是把整個(gè)倉(cāng)庫(kù)塞進(jìn)去

倉(cāng)庫(kù)知識(shí)包不是全量復(fù)制項(xiàng)目文件。它更像一份經(jīng)過篩選的導(dǎo)航圖，只保留 Codex 做判斷時(shí)最需要的信息。信息太少會(huì)導(dǎo)致模型猜測(cè)，信息太多又會(huì)稀釋重點(diǎn)，甚至把無(wú)關(guān)舊邏輯帶進(jìn)當(dāng)前任務(wù)。

整理知識(shí)包時(shí)，重點(diǎn)不是追求資料多，而是讓資料可判斷。Codex 看到一份清楚的資料包，會(huì)比看到幾十個(gè)無(wú)標(biāo)注文件更容易給出靠譜建議。

• 保留：目錄結(jié)構(gòu)、核心模塊說明、接口約定、錯(cuò)誤碼規(guī)則、測(cè)試命令、發(fā)布注意點(diǎn)。
• 壓縮：歷史**、重復(fù)文檔、舊版本說明、已經(jīng)廢棄的接口說明。
• 剔除：完整密鑰、真實(shí)用戶數(shù)據(jù)、內(nèi)部賬號(hào)、無(wú)關(guān)日志、臨時(shí)調(diào)試輸出。
• 標(biāo)記：仍在使用、準(zhǔn)備廢棄、只讀參考、禁止修改的模塊。

三、先確認(rèn)靈能API入口與模型范圍

在整理知識(shí)包之前，先進(jìn)入靈能API https://www.lnsns.com/，確認(rèn) API *ase、可用模型、賬號(hào)狀態(tài)和團(tuán)隊(duì)當(dāng)前使用策略。知識(shí)包通常會(huì)配合較長(zhǎng)上下文任務(wù)使用，因此模型范圍和響應(yīng)穩(wěn)定性都要提前核對(duì)。

團(tuán)隊(duì)文檔里可以把靈能API寫成可點(diǎn)擊鏈接，方便成員回到統(tǒng)一入口核對(duì)信息。需要注意的是，知識(shí)包里不要保存完整 Key，也不要把賬號(hào)截圖當(dāng)成項(xiàng)目資料長(zhǎng)期分發(fā)。

四、按項(xiàng)目建立 CC Switch 配置卡

如果團(tuán)隊(duì)同時(shí)維護(hù)多個(gè)項(xiàng)目，不建議所有項(xiàng)目共用同一張 CC Switch 配置卡。不同項(xiàng)目的語(yǔ)言棧、目錄結(jié)構(gòu)、測(cè)試命令、代碼風(fēng)格都不一樣，配置卡和知識(shí)包最好一一對(duì)應(yīng)。

這樣做的好處是邊界清楚。成員不會(huì)把項(xiàng)目 A 的規(guī)則帶到項(xiàng)目 *，也不會(huì)在簡(jiǎn)單問答里加載過重的上下文。

• project-a-codex-context：項(xiàng)目 A 的開發(fā)與審閱配置，綁定項(xiàng)目 A 知識(shí)包。
• project-*-codex-api-do**：項(xiàng)目 * 的接口文檔配置，重點(diǎn)處理接口說明和調(diào)用示例。
• project-c-codex-test-helper：項(xiàng)目 C 的測(cè)試補(bǔ)齊配置，重點(diǎn)讀取測(cè)試規(guī)范。
• shared-codex-light：輕量問答配置，不默認(rèn)加載大型知識(shí)包。

五、知識(shí)包建議包含哪些文件

第一版知識(shí)包不需要做得太大。建議從 6 類文件開始，每類文件都要短、準(zhǔn)、能驗(yàn)證。文件名也要清楚，方便成員和 Codex 都能理解它的用途。

repo-context/
  01-overview.md          項(xiàng)目目標(biāo)、核心業(yè)務(wù)、主要角色
  02-directory-**p.md     目錄結(jié)構(gòu)、模塊歸屬、禁止隨意改動(dòng)區(qū)域
  03-api-contracts.md     接口命名、請(qǐng)求響應(yīng)、錯(cuò)誤碼約定
  04-code-style.md        代碼風(fēng)格、依賴規(guī)則、常見模式
  05-test-guide.md        測(cè)試命令、測(cè)試數(shù)據(jù)、驗(yàn)收標(biāo)準(zhǔn)
  06-release-notes.md     發(fā)布流程、回滾提醒、觀察指標(biāo)

這些文件不必追求一次寫完。可以先覆蓋最常被問到的內(nèi)容，再隨著 Codex 使用過程不斷補(bǔ)充。每次發(fā)現(xiàn)模型因?yàn)槿鄙倌硞€(gè)**而答偏，就把這個(gè)**沉淀進(jìn)對(duì)應(yīng)文件。

六、目錄結(jié)構(gòu)要寫給人看，也寫給 Codex 看

目錄結(jié)構(gòu)文檔不要只復(fù)制 tree 輸出。更有價(jià)值的是解釋每個(gè)關(guān)鍵目錄負(fù)責(zé)什么、誰(shuí)維護(hù)、哪些目錄可以修改、哪些目錄只讀參考。Codex 做跨文件修改時(shí)，最需要這類邊界信息。

目錄說明示例：
/src/api       接口封裝層，新增接口優(yōu)先放這里
/src/do**in    業(yè)務(wù)規(guī)則層，修改前需要確認(rèn)對(duì)應(yīng)測(cè)試
/src/ui        頁(yè)面組件層，不直接寫請(qǐng)求邏輯
/tests         單元測(cè)試與集成測(cè)試，新增功能必須補(bǔ)測(cè)試
/scripts       本地維護(hù)腳本，禁止寫入真實(shí)賬號(hào)與密鑰

這種說明能讓 Codex 更快判斷修改位置，而不是在多個(gè)目錄之間來回試探。對(duì)新人也有幫助，因?yàn)樗举|(zhì)上就是項(xiàng)目導(dǎo)航文檔。

七、接口文檔要補(bǔ)上真實(shí)約束

接口文檔如果只寫路徑和字段，Codex 仍然容易漏掉業(yè)務(wù)限制。更適合 AI 協(xié)作的接口文檔，要補(bǔ)上鑒權(quán)方式、錯(cuò)誤碼、冪等規(guī)則、分頁(yè)規(guī)則、限流提示和兼容要求。

靈能API https://www.lnsns.com/ 負(fù)責(zé)中轉(zhuǎn)接入，項(xiàng)目自己的接口文檔則負(fù)責(zé)業(yè)務(wù)上下文。兩者不要混在一起：一個(gè)解決模型調(diào)用入口，一個(gè)解決項(xiàng)目知識(shí)表達(dá)。

• 鑒權(quán)：接口是否需要登錄態(tài)、服務(wù)端簽名或內(nèi)部調(diào)用權(quán)限。
• 錯(cuò)誤碼：哪些錯(cuò)誤可以重試，哪些錯(cuò)誤必須直接提示用戶。
• 兼容性：新增字段是否可選，舊客戶端是否能忽略。
• 冪等性：重復(fù)提交是否會(huì)產(chǎn)生重復(fù)數(shù)據(jù)。
• 觀察點(diǎn)：接口上線后看哪些日志、狀態(tài)碼和業(yè)務(wù)指標(biāo)。

八、測(cè)試指南要能直接執(zhí)行

讓 Codex 幫忙補(bǔ)測(cè)試時(shí)，最怕只告訴它“補(bǔ)一下測(cè)試”。知識(shí)包里的測(cè)試指南應(yīng)該明確測(cè)試框架、命令、目錄、命名規(guī)則、哪些場(chǎng)景必須覆蓋，以及測(cè)試失敗時(shí)先看哪里。

測(cè)試指南字段：
測(cè)試框架：
單元測(cè)試命令：
集成測(cè)試命令：
測(cè)試文件命名：
Mock 數(shù)據(jù)位置：
必須覆蓋場(chǎng)景：正常路徑 / 參數(shù)異常 / 權(quán)限失敗 / 邊界值
提交前驗(yàn)收：

如果這些內(nèi)容已經(jīng)整理好，Codex 生成測(cè)試時(shí)會(huì)更貼合項(xiàng)目習(xí)慣。否則它可能生成一個(gè)語(yǔ)法上沒問題、但完全不符合團(tuán)隊(duì)測(cè)試結(jié)構(gòu)的文件。

九、脫敏規(guī)則要寫在知識(shí)包最前面

知識(shí)包要長(zhǎng)期復(fù)用，脫敏規(guī)則必須放在明顯位置。不要依賴成員每次臨時(shí)判斷哪些內(nèi)容能發(fā)、哪些不能發(fā)。規(guī)則越明確，協(xié)作越順。

脫敏規(guī)則不只是安全要求，也能提高輸出質(zhì)量。Codex 看到清楚的假數(shù)據(jù)和真實(shí)字段含義，會(huì)比看到一堆混亂的真實(shí)日志更容易分析。

• 禁止放入：完整 Key、真實(shí)手機(jī)號(hào)、郵箱、***、支付信息、**賬號(hào)。
• 可以替換：用戶 ID、訂單號(hào)、接口域名、內(nèi)部項(xiàng)目代號(hào)。
• 可以概括：業(yè)務(wù)規(guī)模、客戶名稱、內(nèi)部流程細(xì)節(jié)。
• 必須標(biāo)注：示例數(shù)據(jù)是否為假數(shù)據(jù)，錯(cuò)誤日志是否已脫敏。

十、給 Codex 的知識(shí)包使用提示詞

知識(shí)包準(zhǔn)備好后，還需要一段固定提示詞告訴 Codex 如何使用它。重點(diǎn)是要求先讀規(guī)則、再判斷任務(wù)類型、最后輸出**證結(jié)果。

提示詞模板：
你將基于 repo-context 中的資料處理當(dāng)前任務(wù)。
請(qǐng)先讀取項(xiàng)目概覽、目錄結(jié)構(gòu)、接口約定和測(cè)試指南。
不要修改標(biāo)記為只讀或禁止改動(dòng)的模塊。
如果資料不足，請(qǐng)列出缺失信息，不要自行補(bǔ)全。
輸出必須包含：修改建議、涉及文件、驗(yàn)證方式、風(fēng)險(xiǎn)提醒。

這段提示詞可以和 CC Switch 配置卡一起保存。成員每次切換到項(xiàng)目配置時(shí)，就能沿用同一套上下文規(guī)則，減少臨時(shí)溝通。

十一、知識(shí)包要有版本記錄

知識(shí)包不是一次性資料。項(xiàng)目目錄會(huì)變，接口會(huì)變，測(cè)試命令會(huì)變，發(fā)布流程也會(huì)變。如果知識(shí)包長(zhǎng)期不更新，Codex 反而會(huì)基于舊信息給出錯(cuò)誤建議。

知識(shí)包版本記錄：
日期：
修改文件：
修改原因：
影響任務(wù)：開發(fā) / 審閱 / 測(cè)試 / 文檔 / 發(fā)布
負(fù)責(zé)人：
是否需要通知團(tuán)隊(duì)：是 / 否

版本記錄不需要很復(fù)雜，但要讓成員知道什么時(shí)候更新過、為什么更新。尤其是接口約定和測(cè)試命令，一旦變化，就應(yīng)該同步更新知識(shí)包。

十二、當(dāng) Codex 答偏時(shí)，先修知識(shí)包

如果 Codex 輸出不理想，不要馬上認(rèn)為模型不行。先檢查輸入資料：是不是目錄說明缺失、接口約束沒寫、測(cè)試命令過期、只讀模塊沒有標(biāo)注。很多偏差其實(shí)是上下文質(zhì)量問題。

這種修復(fù)方式很劃算。修一次知識(shí)包，后續(xù)很多任務(wù)都會(huì)受益；只在單次對(duì)話里糾正，下一次還可能重復(fù)踩坑。

• 答錯(cuò)目錄：補(bǔ)充目錄結(jié)構(gòu)和模塊職責(zé)。
• 漏掉測(cè)試：補(bǔ)充測(cè)試指南和提交前驗(yàn)收。
• 接口理解錯(cuò)誤：補(bǔ)充請(qǐng)求響應(yīng)、錯(cuò)誤碼和兼容規(guī)則。
• 建議過度修改：補(bǔ)充禁止改動(dòng)區(qū)域和最小修改原則。

十三、完整落地順序

• 第一步：進(jìn)入靈能API https://www.lnsns.com/，確認(rèn) API *ase、模型范圍和賬號(hào)狀態(tài)。
• 第二步：按項(xiàng)目建立 CC Switch 配置卡，不同項(xiàng)目不要混用上下文。
• 第三步：整理項(xiàng)目概覽、目錄結(jié)構(gòu)、接口約定、代碼風(fēng)格、測(cè)試指南和發(fā)布提醒。
• **步：把脫敏規(guī)則放在知識(shí)包最前面，避免敏感信息進(jìn)入資料。
• 第五步：寫一段固定提示詞，要求 Codex 按知識(shí)包規(guī)則處理任務(wù)。
• 第六步：用小任務(wù)驗(yàn)證知識(shí)包是否有效，再擴(kuò)展到復(fù)雜任務(wù)。
• 第七步：每次答偏都回頭更新知識(shí)包，而不是只修單次對(duì)話。

? 十四、結(jié)語(yǔ)：好的上下文，比臨時(shí)堆文件更重要

Codex API 中轉(zhuǎn)站接入完成后，團(tuán)隊(duì)真正要持續(xù)打磨的是上下文質(zhì)量。靈能API提供統(tǒng)一入口，CC Switch負(fù)責(zé)不同項(xiàng)目配置，倉(cāng)庫(kù)知識(shí)包負(fù)責(zé)把項(xiàng)目經(jīng)驗(yàn)變成可復(fù)用資料。

當(dāng) Codex 能穩(wěn)定讀到項(xiàng)目概覽、目錄邊界、接口規(guī)則、測(cè)試方式和脫敏要求時(shí)，它給出的建議會(huì)更貼近真實(shí)工程。與其每次臨時(shí)解釋一遍項(xiàng)目**，不如把這些**沉淀下來，讓每一次調(diào)用都站在更清楚的上下文上。