一、先理解上下文工程：不是給得越多越好

很多團(tuán)隊(duì)第一次用 Codex 分析項(xiàng)目時(shí)，會(huì)把“上下文充足”理解成“盡量多給文件”。實(shí)際效果往往相反：倉(cāng)庫(kù)越大，無(wú)關(guān)代碼越多，模型越容易把歷史邏輯、廢棄模塊、測(cè)試夾具和當(dāng)前任務(wù)混在一起。輸出看起來(lái)很完整，但真正能執(zhí)行的建議并不多。

上下文工程的核心，是讓 Codex 看到足夠但不冗余的信息。它需要知道任務(wù)目標(biāo)、相關(guān)文件、調(diào)用鏈、約束條件、已有測(cè)試和不允許觸碰的邊界。少了這些，它會(huì)猜；多了無(wú)關(guān)內(nèi)容，它會(huì)**擾。

通過(guò)靈能API統(tǒng)一接入后，團(tuán)隊(duì)可以把 Codex 的使用方式從“臨時(shí)問(wèn)答”升級(jí)為“按任務(wù)組織上下文”。這一步做好了，后續(xù)無(wú)論是代碼**、日志分析、文檔生成還是測(cè)試補(bǔ)全，輸出都會(huì)更穩(wěn)定。

• 上下文太少，模型容易憑空補(bǔ)全。
• 上下文太多，模型容易抓錯(cuò)重點(diǎn)。
• 上下文剛好，輸出才更容易復(fù)核和落地。

二、統(tǒng)一接入入口：先把鏈路問(wèn)題和上下文問(wèn)題分開(kāi)

在優(yōu)化上下文之前，先確認(rèn)接入鏈路是穩(wěn)定的。很多看起來(lái)像“模型不理解項(xiàng)目”的問(wèn)題，其實(shí)來(lái)自 *ase **L 寫(xiě)錯(cuò)、模型權(quán)限不足、Key 失效、網(wǎng)絡(luò)超時(shí)或配置卡混用。鏈路沒(méi)穩(wěn)定，上下文再精細(xì)也很難判斷效果。

建議團(tuán)隊(duì)從 https://www.lnsns.com/ 進(jìn)入靈能API控制臺(tái)，確認(rèn)當(dāng)前接入說(shuō)明和可用模型。團(tuán)隊(duì)文檔中只保留入口、變量名、負(fù)責(zé)人和復(fù)核規(guī)則，不寫(xiě)完整密鑰。這樣能讓新成員知道從哪里配置，也能避免敏感信息進(jìn)入倉(cāng)庫(kù)。

鏈路驗(yàn)證通過(guò)后，再進(jìn)入上下文設(shè)計(jì)。這樣排查時(shí)會(huì)很清楚：如果最小任務(wù)失敗，先看接入；如果最小任務(wù)成功但復(fù)雜任務(wù)質(zhì)量差，再看上下文范圍和提示詞。

• 連接失敗先查入口、Key、模型和網(wǎng)絡(luò)。
• 連接正常但答案發(fā)散，再查上下文。
• 接入配置和任務(wù)提示要分開(kāi)維護(hù)。

? 三、給倉(cāng)庫(kù)做分層：哪些文件適合進(jìn)入上下文

**倉(cāng)庫(kù)里的文件并不都適合交給 Codex。業(yè)務(wù)代碼、類型定義、接口文檔、測(cè)試用例、配置示例通常有價(jià)值；依賴目錄、構(gòu)建產(chǎn)物、緩存文件、壓縮包、歷史導(dǎo)出、真實(shí)密鑰和大體積日志通常不該進(jìn)入上下文。

可以把倉(cāng)庫(kù)文件分成四層：核心上下文、輔助上下文、排除上下文、敏感上下文。核心上下文直接影響任務(wù)判斷；輔助上下文用于補(bǔ)充**；排除上下文會(huì)干擾分析；敏感上下文必須隔離，不應(yīng)該被讀取或輸出。

倉(cāng)庫(kù)上下文分層

核心上下文：src/、packages/、api/、sche**s/、tests/
輔助上下文：do**/、README、CHANGELOG、examples/
排除上下文：node_modules/、dist/、*uild/、coverage/、.cache/
敏感上下文：.env、*.pem、secret.*、credentials.json、未打碼日志

分層之后，提示詞就可以寫(xiě)得更精確。比如“只讀取 src/modules/order、tests/order 和 do**/api/order.md，不讀取 dist、coverage 和任何 .env 文件”。這類約束比一句“請(qǐng)注意安全”有效得多。

• 核心上下文用于判斷任務(wù)。
• 輔助上下文用于補(bǔ)充**。
• 敏感上下文必須從規(guī)則層面隔離。

四、先做索引說(shuō)明：讓 Codex 知道項(xiàng)目地圖

在大型倉(cāng)庫(kù)里，直接讓 Codex 分析具體問(wèn)題之前，可以先準(zhǔn)備一份項(xiàng)目索引說(shuō)明。索引說(shuō)明不是復(fù)制所有代碼，而是告訴模型各目錄負(fù)責(zé)什么、核心模塊在哪里、測(cè)試在哪里、文檔在哪里、哪些目錄不要讀取。

索引說(shuō)明最好由團(tuán)隊(duì)維護(hù)，而不是每次都讓模型重新猜。它可以放在 do**/codex-context.md 之類的位置，作為所有 Codex 任務(wù)的前置說(shuō)明。內(nèi)容保持簡(jiǎn)潔，重點(diǎn)寫(xiě)目錄職責(zé)、常見(jiàn)任務(wù)入口和禁止讀取范圍。

## Codex 項(xiàng)目索引

- src/modules/order：訂單業(yè)務(wù)邏輯
- src/modules/payment：支付和退款邏輯
- src/api：接口請(qǐng)求封裝
- src/types：前端類型定義
- tests：?jiǎn)卧獪y(cè)試和接口測(cè)試
- do**/api：接口說(shuō)明

禁止讀?。?env、dist、coverage、node_modules、未打碼生產(chǎn)日志

• 項(xiàng)目索引說(shuō)明要短，不要變成完整架構(gòu)文檔。
• 索引中必須寫(xiě)清楚禁止讀取范圍。
• 目錄職責(zé)變化后，要同步更新索引。

?? 五、用 CC Switch 固定上下文任務(wù)配置

上下文工程也需要配置卡。日常問(wèn)答、倉(cāng)庫(kù)分析、PR 預(yù)審、文檔生成對(duì)模型和權(quán)限的要求不同，不應(yīng)該都走一張默認(rèn)配置。CC Switch 可以幫助團(tuán)隊(duì)把這些場(chǎng)景拆開(kāi)，減少誤用。

配置卡可以命名為 Lingneng-Codex-Context-Read 或 Lingneng-Codex-Repo-Review。備注里寫(xiě)清楚：默認(rèn)只讀、優(yōu)先讀取索引說(shuō)明、禁止讀取敏感文件、輸出必須列出引用到的文件范圍、無(wú)法確認(rèn)的結(jié)論必須標(biāo)記待確認(rèn)。

配置卡備注建議

用途：**倉(cāng)庫(kù)上下文分析
權(quán)限：默認(rèn)只讀
優(yōu)先讀取：do**/codex-context.md
禁止讀?。?env、secret.*、credentials.json、dist、coverage
輸出要求：列出已讀取文件、結(jié)論依據(jù)、待確認(rèn)問(wèn)題
復(fù)核要求：涉及權(quán)限、賬務(wù)、生產(chǎn)事故的結(jié)論必須人工確認(rèn)

• 配置卡要寫(xiě)用途和禁止范圍。
• 上下文分析默認(rèn)只讀。
• 輸出要列出依據(jù)，方便評(píng)審人追溯。

六、最小樣本驗(yàn)證：先讓 Codex 讀一個(gè)模塊

不要一開(kāi)始就讓 Codex 分析整個(gè)倉(cāng)庫(kù)。最小樣本可以選擇一個(gè)邊界清晰的模塊，比如訂單、會(huì)員、支付、消息通知。讓它讀取模塊代碼、對(duì)應(yīng)測(cè)試和接口文檔，輸出模塊職責(zé)、關(guān)鍵流程、風(fēng)險(xiǎn)點(diǎn)和待確認(rèn)事項(xiàng)。

最小樣本的意義，是測(cè)試“給定范圍內(nèi)的理解質(zhì)量”。如果單模塊都輸出空泛，說(shuō)明索引說(shuō)明、文件選擇或提示詞還需要調(diào)整；如果單模塊穩(wěn)定，再擴(kuò)展到跨模塊調(diào)用鏈會(huì)更穩(wěn)。

最小樣本提示詞

請(qǐng)只讀取以下范圍：
- do**/codex-context.md
- src/modules/order/
- tests/order/
- do**/api/order.md

輸出：
1. 模塊職責(zé)
2. 關(guān)鍵調(diào)用流程
3. 已覆蓋測(cè)試
4. 潛在風(fēng)險(xiǎn)點(diǎn)
5. 需要人工確認(rèn)的問(wèn)題

限制：不讀取 .env、dist、coverage、node_modules，不修改文件。

• 先驗(yàn)證單模塊，再做跨模塊。
• 輸出必須列出已讀取范圍。
• 不確定結(jié)論必須進(jìn)入待確認(rèn)。

七、提示詞結(jié)構(gòu)：用六段式減少誤讀

上下文任務(wù)的提示詞不能只寫(xiě)“幫我看看這個(gè)項(xiàng)目”。穩(wěn)定的寫(xiě)法應(yīng)該包含六段：角色、目標(biāo)、讀取范圍、排除范圍、輸出結(jié)構(gòu)、復(fù)核規(guī)則。六段都寫(xiě)清楚，Codex 才更容易把注意力放在正確位置。

角色用于限定視角，例如代碼**助手、接口文檔助手、測(cè)試用例助手；目標(biāo)用于限定任務(wù)；讀取范圍告訴它看哪里；排除范圍告訴它不要看哪里；輸出結(jié)構(gòu)保證結(jié)果可讀；復(fù)核規(guī)則提醒它哪些結(jié)論不能直接定稿。

六段式提示詞

角色：你是團(tuán)隊(duì)倉(cāng)庫(kù)上下文分析助手。
目標(biāo)：理解訂單模塊的接口、測(cè)試和風(fēng)險(xiǎn)點(diǎn)。
讀取范圍：do**/codex-context.md、src/modules/order、tests/order、do**/api/order.md。
排除范圍：.env、dist、coverage、node_modules、未打碼日志。
輸出結(jié)構(gòu)：模塊職責(zé)、調(diào)用鏈、測(cè)試覆蓋、風(fēng)險(xiǎn)點(diǎn)、待確認(rèn)事項(xiàng)。
復(fù)核規(guī)則：權(quán)限、賬務(wù)、生產(chǎn)事故相關(guān)結(jié)論必須標(biāo)記待確認(rèn)。

• 提示詞先寫(xiě)范圍，再寫(xiě)任務(wù)。
• 排除范圍必須明確列出。
• 復(fù)核規(guī)則要寫(xiě)在提示詞里，不靠事后提醒。

八、敏感文件隔離：安全邊界必須前置

**倉(cāng)庫(kù)里最危險(xiǎn)的不是業(yè)務(wù)代碼，而是容易被誤讀、誤傳、誤輸出的敏感文件。比如 .env、證書(shū)、賬號(hào)憑據(jù)、生產(chǎn)日志、用戶數(shù)據(jù)導(dǎo)出、內(nèi)部訪問(wèn)地址。上下文工程必須先定義安全邊界，再談?shì)敵鲑|(zhì)量。

安全邊界要落到三層：倉(cāng)庫(kù)忽略規(guī)則、任務(wù)提示詞、復(fù)核檢查。倉(cāng)庫(kù)層面不要把敏感文件放進(jìn)可讀范圍；提示詞層面明確禁止讀取和輸出；復(fù)核層面檢查生成內(nèi)容中是否出現(xiàn)密鑰、賬號(hào)、真實(shí)用戶數(shù)據(jù)或內(nèi)部地址。

敏感隔離清單

[ ] .env 不進(jìn)入上下文
[ ] 證書(shū)和私鑰不進(jìn)入上下文
[ ] 生產(chǎn)日志必須打碼后再分析
[ ] 用戶數(shù)據(jù)導(dǎo)出不直接提供給模型
[ ] 輸出結(jié)果不包含完整密鑰、賬號(hào)憑證和內(nèi)部地址
[ ] 截圖中的敏感字段已遮擋

使用靈能API統(tǒng)一入口接入，并不意味著可以忽略本地上下文安全。入口解決調(diào)用路徑，敏感文件隔離解決輸入邊界。兩者配合，才能讓團(tuán)隊(duì)放心地把 Codex 放進(jìn)真實(shí)項(xiàng)目流程。

• 敏感文件默認(rèn)不讀。
• 生產(chǎn)日志先脫敏再分析。
• 輸出結(jié)果也要做殘留檢查。

九、控制上下文成本：長(zhǎng)上下文要按價(jià)值使用

上下文越長(zhǎng)，成本和等待時(shí)間通常越高，輸出也不一定更好。團(tuán)隊(duì)需要把長(zhǎng)上下文作為資源管理，而不是默認(rèn)選項(xiàng)。短任務(wù)只給關(guān)鍵片段，標(biāo)準(zhǔn)任務(wù)給模塊范圍，深度任務(wù)才讀取更完整的調(diào)用鏈。

可以把任務(wù)分成三檔：短上下文、模塊上下文、跨模塊上下文。短上下文用于錯(cuò)誤解釋和命令說(shuō)明；模塊上下文用于接口、測(cè)試、文檔；跨模塊上下文用于架構(gòu)分析、復(fù)雜事故復(fù)盤(pán)和發(fā)布風(fēng)險(xiǎn)評(píng)估。

上下文長(zhǎng)度策略

短上下文：日志片段、錯(cuò)誤碼、單個(gè)函數(shù)
模塊上下文：一個(gè)業(yè)務(wù)模塊、對(duì)應(yīng)測(cè)試、接口文檔
跨模塊上下文：調(diào)用鏈、配置、測(cè)試、發(fā)布說(shuō)明、歷史變更

默認(rèn)規(guī)則：能用短上下文解決的，不升級(jí)到跨模塊上下文。

• 上下文長(zhǎng)度要和任務(wù)價(jià)值匹配。
• 高頻任務(wù)優(yōu)先短上下文。
• 跨模塊上下文建議手動(dòng)觸發(fā)。

十、輸出要帶依據(jù)：讓每個(gè)結(jié)論能回到文件

Codex 輸出的結(jié)論如果沒(méi)有依據(jù)，復(fù)核成本會(huì)很高。評(píng)審人看到“這里可能有權(quán)限風(fēng)險(xiǎn)”，還要回頭找是哪個(gè)文件、哪段邏輯、哪個(gè)接口導(dǎo)致的。上下文任務(wù)應(yīng)要求輸出結(jié)論時(shí)同時(shí)列出依據(jù)位置。

依據(jù)不需要復(fù)雜到精確行號(hào)，但至少要包含文件名、模塊名、相關(guān)函數(shù)或接口。對(duì)于無(wú)法確認(rèn)的內(nèi)容，要明確標(biāo)注“沒(méi)有在當(dāng)前上下文中找到依據(jù)，需要人工確認(rèn)”。這樣可以防止猜測(cè)混進(jìn)確定結(jié)論。

結(jié)論輸出格式

結(jié)論：訂單取消接口存在狀態(tài)邊界風(fēng)險(xiǎn)
依據(jù)：src/modules/order/cancel.ts，tests/order/cancel.spec.ts
說(shuō)明：測(cè)試覆蓋了已支付訂單，但未看到已發(fā)貨訂單的取消斷言
建議：補(bǔ)充已發(fā)貨狀態(tài)的接口測(cè)試
狀態(tài)：需要人工確認(rèn)業(yè)務(wù)規(guī)則

• 每條結(jié)論都要有依據(jù)。
• 沒(méi)有依據(jù)的內(nèi)容要標(biāo)記待確認(rèn)。
• 依據(jù)越清楚，復(fù)核越快。

十一、建立上下文模板庫(kù)：讓團(tuán)隊(duì)不用每次重寫(xiě)提示詞

當(dāng)團(tuán)隊(duì)發(fā)現(xiàn)某類上下文任務(wù)反復(fù)出現(xiàn)，就應(yīng)該把提示詞沉淀成模板。比如單模塊理解、接口變更分析、測(cè)試缺口掃描、錯(cuò)誤日志復(fù)盤(pán)、發(fā)布風(fēng)險(xiǎn)評(píng)估，都適合放進(jìn)模板庫(kù)。

模板庫(kù)的重點(diǎn)不是堆很多提示詞，而是讓每個(gè)模板都有明確使用場(chǎng)景、輸入范圍、輸出結(jié)構(gòu)和復(fù)核要求。模板越清晰，新成員越容易正確使用，歷史結(jié)果也越容易比較。

模板庫(kù)目錄建議

templates/
  module-sum**ry.prompt.md
  api-change-review.prompt.md
  test-gap-scan.prompt.md
  error-log-review.prompt.md
  release-risk-check.prompt.md

每個(gè)模板包含：適用場(chǎng)景、讀取范圍、排除范圍、輸出結(jié)構(gòu)、復(fù)核規(guī)則

模板庫(kù)可以和 CC Switch 配置卡配合使用。配置卡負(fù)責(zé)模型和入口，模板負(fù)責(zé)任務(wù)語(yǔ)言和邊界。兩者分工清楚后，團(tuán)隊(duì)不會(huì)每次都從零組織提示詞。

• 高頻任務(wù)模板化。
• 模板必須包含排除范圍。
• 模板變更要記錄版本和原因。

十二、復(fù)核與迭代：根據(jù)結(jié)果修正上下文，而不是只改提示詞

當(dāng) Codex 輸出不理想時(shí)，很多人第一反應(yīng)是改提示詞。但上下文工程里，問(wèn)題可能不在提示詞，而在輸入范圍。也許缺少測(cè)試文件，也許給了過(guò)期文檔，也許包含了廢棄目錄，也許沒(méi)有告訴它哪部分是當(dāng)前版本。

建議每次復(fù)核都記錄兩個(gè)問(wèn)題：這次缺了什么上下文？這次多給了什么干擾內(nèi)容？前者用于補(bǔ)充索引，后者用于更新排除規(guī)則。這樣上下文質(zhì)量會(huì)逐步變好，而不是每次靠臨場(chǎng)調(diào)整。

復(fù)核記錄模板

任務(wù)：訂單模塊接口變更分析
結(jié)果問(wèn)題：模型把舊接口當(dāng)成當(dāng)前接口
缺失上下文：缺少 do**/api/order-v2.md
干擾上下文：讀取了 legacy/order-old.ts
修正動(dòng)作：更新項(xiàng)目索引，標(biāo)注 legacy 為排除范圍
確認(rèn)人：后端負(fù)責(zé)人

• 輸出不好時(shí)，先檢查上下文范圍。
• 缺失內(nèi)容進(jìn)入索引，干擾內(nèi)容進(jìn)入排除規(guī)則。
• 每次復(fù)核都讓下一次任務(wù)更準(zhǔn)。

? 十三、收尾：上下文工程做好，Codex 才會(huì)越用越穩(wěn)

Codex 接入 Claude中轉(zhuǎn) 后，真正決定長(zhǎng)期效果的不是單次提示詞寫(xiě)得多漂亮，而是團(tuán)隊(duì)能不能持續(xù)提供準(zhǔn)確、干凈、可追溯的上下文。上下文工程做得好，模型會(huì)更少猜測(cè)，評(píng)審人也更容易復(fù)核。

落地順序可以很清楚：先通過(guò)靈能API確認(rèn)統(tǒng)一入口，再建立倉(cāng)庫(kù)分層和索引說(shuō)明，然后用 CC Switch 固定上下文任務(wù)配置，接著從單模塊樣本驗(yàn)證，最后把提示詞模板、敏感隔離和復(fù)核記錄沉淀下來(lái)。

當(dāng)團(tuán)隊(duì)不再隨手把整個(gè)倉(cāng)庫(kù)丟給模型，而是按任務(wù)選擇上下文、按規(guī)則排除敏感文件、按依據(jù)復(fù)核結(jié)論，Codex 就會(huì)從“偶爾靈光的助手”變成穩(wěn)定的工程協(xié)作能力。

• 先統(tǒng)一入口，再治理上下文。
• 先做單模塊驗(yàn)證，再擴(kuò)展跨模塊分析。
• 先隔離敏感文件，再進(jìn)入團(tuán)隊(duì)流程。