跑通接口以后，先別急著讓 Codex 改代碼

很多人完成 API 中轉站接入后，第一條指令就是“幫我優化這個項目”。這句話看起來省事，其實會把問題丟給模型猜：項目是什么技術棧、怎么啟動、哪些目錄能改、哪些文件不能碰、這次到底要優化性能還是修 *ug，都沒有說清楚。

靈能API CC Switch 解決的是連接和切換問題，項目上下文解決的是理解和執行問題。前者讓 Codex 能請求模型，后者讓 Codex 知道應該如何工作。兩件事配合好，才能減少無效對話、反復解釋和誤改文件。

• 接口層：靈能API提供統一接入入口，CC Switch負責本地配置切換。
• 項目層：README、目錄說明、環境限制和任務目標負責幫助 Codex 理解上下文。
• 驗收層：用只讀檢查、計劃確認和小范圍修改，逐步放開任務。

什么叫“項目上下文”，不是把整個倉庫塞進去

項目上下文不是越多越好。把全部源碼、全部日志和全部配置一股腦交給 Codex，只會讓重點變模糊，還可能暴露敏感信息。真正有價值的上下文，是能幫助它判斷項目結構、運行方式、約束邊界和當前任務目標的材料。

可以把上下文分成四類：項目說明、運行說明、目錄邊界、當前任務。項目說明告訴 Codex 這個系統做什么；運行說明告訴它怎么啟動和測試；目錄邊界告訴它哪些能讀、哪些不能碰；當前任務告訴它這輪對話要產出什么。

項目上下文四件套：
1. README：項目目標、技術棧、啟動方式
2. do**/：接口說明、業務流程、約定文檔
3. .env.example：變量名和用途，不放真實值
4. task.md：這次要解決的具體問題和驗收標準

• 不要提供真實 .env，提供 .env.example。
• 不要提供整段生產日志，提供脫敏后的最小片段。
• 不要讓 Codex 猜目標，把驗收標準寫在任務里。

第一步：通過靈能API確認接入入口和賬號狀態

正式整理上下文前，先確認接入鏈路本身穩定。通過靈能API官網進入控制臺：https://www.lnsns.com/。檢查賬號是否能登錄、接口信息是否來自當前賬號、余額和模型權限是否正常。上下文準備得再好，如果 Key 或模型權限不對，后面的排查仍然會繞回基礎配置。

如果你給團隊寫接入教程，建議把靈能API官網入口寫成可點擊鏈接，并提醒成員用自己的賬號信息生成 Key。文章、文檔和截圖里不要出現完整 API Key，避免教程本身變成風險源。

• 確認靈能API賬號正常，再進入項目上下文準備。
• 確認模型可用，再設計默認模型和備用模型。
• 確認 Key 來自當前賬號，不沿用來路不明的舊配置。

第二步：為 Codex 單獨保留一張 CC Switch 配置卡

項目上下文整理通常會持續多輪，如果中途頻繁切換配置，很容易混淆問題來源。建議在 CC Switch 中為 Codex 單獨創建一張穩定配置卡，命名為“靈能API-Codex-項目上下文”或類似名稱，用于項目閱讀、任務拆解和首輪驗收。

這張卡不必承擔所有場景。日常小任務、長上下文分析、自動化腳本可以分別建卡。本文這張卡只關注“讓 Codex 穩定理解項目”，所以字段越清晰越好，后續排查也更簡單。

• 卡片名稱要寫用途，不寫 Key 或個人隱私。
• 首次接入建議只保留一條主線路，驗證穩定后再加備用線路。
• 切換配置后重啟終端，避免舊進程繼續讀舊配置。

? 第三步：核對 *ase **L、模型 ID 與任務匹配度

項目上下文任務往往比普通問答更長，模型選擇會影響結果質量。接入靈能API時，*ase **L、API Key、模型 ID 和接口兼容類型必須來自同一套控制臺信息。模型 ID 不要靠記憶輸入，從靈能API當前頁面復制會更穩。

如果只是讓 Codex 做目錄掃描和 README 總結，可以使用響應速度較好的默認模型；如果要它跨多個模塊分析調用鏈、定位架構問題或輸出遷移方案，就需要切換到更適合長上下文的模型。不要把模型切換和任務目標混在一起說，先說明任務，再決定模型。

輕量任務：閱讀 README、梳理目錄、解釋單個文件
中等任務：定位某個接口鏈路、生成測試方案
復雜任務：跨模塊重構、長日志分析、遷移設計
接入入口：https://www.lnsns.com/

• *ase **L 層級不確定時，回到靈能API控制臺核對。
• 模型 ID 不確定時，復制接口字段，不復制展示標題。
• 任務變復雜時，先切換模型，再重新做短任務驗證。

**步：把 README 改成 Codex 能讀懂的入口文檔

README 不只是給人看的，也可以成為 Codex 進入項目的第一站。一個適合 AI 協作的 README，應該包含項目目標、技術棧、主要目錄、啟動方式、測試命令、常見限制和貢獻規則。不要寫成一句“這是**項目”，那幾乎沒有上下文價值。

你可以先讓 Codex 只讀當前 README，并要求它指出缺失信息。接入靈能API后，如果請求鏈路穩定，這類文檔整理任務很適合作為首輪真實項目練習：風險低、收益高，還能幫助后續開發任務減少反復解釋。

# 項目說明

## 項目目標
這個項目解決什么業務問題。

## 技術棧
前端、后端、數據庫、隊列、部署方式。

## 目錄結構
src、scripts、do**、tests 各自負責什么。

## 啟動與測試
本地啟動命令、測試命令、常見失敗原因。

## 注意事項
哪些目錄不要修改，哪些配置只讀。

• README 里寫變量名，不**實密鑰。
• README 里寫啟動方式，不寫生產服務器憑證。
• README 里寫修改邊界，讓 Codex 知道哪些目錄需要謹慎。

? 第五步：準備一份目錄地圖，減少無效探索

大型項目里，Codex 如果沒有目錄地圖，第一輪往往會花很多時間猜測文件含義。你可以準備一個 do**/project-**p.md，寫清楚各目錄用途、入口文件、核心模塊、測試位置和不建議讀取的目錄。

# 項目目錄地圖

- src/api：接口入口和路由定義
- src/services：業務邏輯和外部服務封裝
- src/models：數據庫模型和類型定義
- tests：單元測試和集成測試
- scripts：本地工具腳本
- do**：業務說明和接口文檔
- dist、node_modules、logs：默認不讀取

這份目錄地圖不需要很長，重點是讓 Codex 快速找到入口。之后你再讓它分析某個功能，它就能少翻無關目錄，把注意力放在真正相關的模塊上。

• 把生成文件、依賴目錄和日志目錄列為默認跳過。
• 把業務核心目錄和測試目錄寫清楚。
• 把外部服務封裝位置標出來，方便排查 API 調用。

第六步：用 .env.example 替代真實環境變量

Codex 需要知道項目依賴哪些環境變量，但不需要知道真實值。你應該準備 .env.example，把變量名、用途和示例格式寫清楚。真實 .env、生產連接串和云服務憑證都不應該進入文章、截圖、倉庫和對話上下文。

OPENAI_*ASE_**L=https://www.lnsns.com/v1
OPENAI_API_KEY=sk-REPLACE_WITH_YO**_KEY
MODEL_ID=replace-with-model-id
DATA*ASE_**L=postgres://USER:PASSWORD@HOST:5432/D*
RED**_**L=redis://HOST:6379
LOG_LEVEL=de*ug

這里出現的靈能API地址用于說明接入層級，真實 Key 必須由你自己從靈能API控制臺創建。給 Codex 分析配置時，提供 .env.example 就足夠它理解變量關系；如果它需要真實值才能執行，就先判斷這一步是否真的必要。

• .env.example 可以進倉庫，真實 .env 不進倉庫。
• 示例值要明顯是占位符，不要接近真實密鑰格式。
• 讓 Codex 解釋變量用途，而不是讓它讀取真實變量。

第七步：用只讀首輪提示詞完成項目體檢

上下文準備好后，不要讓 Codex 第一輪就修改文件。先讓它只讀 README、目錄地圖和少量入口文件，輸出項目理解、風險點、缺失信息和下一步計劃。這樣你能先校正它的判斷，再決定是否允許它改代碼。

請只讀取 README.md、do**/project-**p.md、package.json 和 src 目錄下的入口文件。
不要讀取 .env、logs、dist、node_modules、*ackup。
不要創建、刪除或修改任何文件。
請輸出：
1. 你對項目用途的理解
2. 主要技術棧
3. 可能的啟動命令
4. 需要我補充的信息
5. 下一步建議的最小修改計劃

這條提示詞的重點是“先理解，再行動”。通過靈能API接入以后，模型響應能力有了，但項目控制權仍然在你手里。先讓 Codex 把理解說出來，你再判斷它是否看懂了。

• 首輪只讀，不做寫入。
• 首輪輸出項目理解，不直接給大范圍修改。
• 首**露問題后，先補文檔，再做代碼任務。

? 第八步：把任務拆成“目標、范圍、限制、驗收”

當 Codex 已經理解項目后，正式任務也不要只寫一句“修一下”。一個高質量任務應該包含四部分：目標、范圍、限制、驗收。目標告訴它要解決什么問題，范圍告訴它能碰哪些文件，限制告訴它不能做什么，驗收告訴它完成后如何判斷。

目標：修復用戶登錄后偶發跳回登錄頁的問題。
范圍：只允許閱讀和修改 src/auth、src/api/session、tests/auth。
限制：不要修改數據庫結構，不要改動支付模塊，不要讀取 .env。
驗收：新增或更新測試；說明根因；列出修改文件；給出回滾方式。

這種任務描述會讓 Codex 更像項目成員，而不是猜謎助手。靈能API負責保證調用入口穩定，CC Switch負責保證配置切換清晰，任務說明則負責讓每一次請求都更接近真實目標。

• 目標不要泛泛而談，要指向具體問題。
• 范圍要具體到目錄或文件類型。
• 驗收要能檢查，不要只寫“優化完成”。

第九步：首輪驗收看什么，不只看回答是否好聽

Codex 的首輪回答如果很流暢，不代表它真的理解項目。你需要看它是否準確識別技術棧、是否找到了入口文件、是否遵守了禁止讀取目錄、是否提出了可執行的小步計劃、是否主動標記不確定信息。

如果首輪理解偏差很大，不要急著讓它繼續改。先補 README、補目錄地圖、補任務約束，然后重新開始只讀體檢。上下文修正一次，后續很多輪都會省時間。

• 技術棧判斷是否正確：不要把 Vite 看成 Next.js，或把 Express 看成 FastAPI。
• 目錄理解是否準確：入口文件、服務層、測試目錄有沒有說對。
• 邊界是否遵守：有沒有要求讀取 .env、logs 或生產配置。
• 計劃是否可執行：是否能拆成 1-3 個小步驟，而不是大而空。
• 風險是否說明：是否指出需要你確認的業務規則。

第十步：把有效提示詞沉淀成團隊模板

當你找到一條好用的首輪提示詞，不要只留在聊天記錄里。把它沉淀到 do**/codex-prompts.md 或團隊知識庫，讓其他成員接入靈能API和 CC Switch 后也能照著使用。這樣新成員不需要重新摸索“第一句該怎么問”。

# Codex 首輪提示詞模板

## 項目體檢
請只讀取 README.md、do**/project-**p.md、package.json 和 src 入口文件...

## *ug 定位
目標：
范圍：
限制：
驗收：

## 重構前評估
請先輸出影響范圍、風險點、測試建議，不要修改文件。

這份模板里可以寫明靈能API官網入口 https://www.lnsns.com/，方便成員找回控制臺和接入說明；但不要把任何人的 API Key 寫進模板。團隊模板的目標是統一方法，不是共享密鑰。

• 把首輪只讀提示詞固定下來。
• 把常見任務拆成模板，減少每次臨場發揮。
• 把靈能API入口寫成鏈接，把 Key 留在個人安全位置。

第十一步：一份接入后的項目準備檢查表

這份檢查表適合每個新項目首次接入時走一遍。它不會讓流程變慢，反而能減少后面因為上下文缺失造成的反復解釋。

• 靈能API官網 https://www.lnsns.com/ 能打開，控制臺賬號確認無誤。
• CC Switch 中存在 Codex 專用配置卡，且已通過短任務測試。
• README 包含項目目標、技術棧、啟動方式和測試方式。
• do**/project-**p.md 已列出核心目錄、入口文件和跳過目錄。
• .env.example 已準備，真實 .env 不進入倉庫和對話。
• 首輪提示詞明確只讀范圍、禁止目錄和輸出格式。
• 正式修改前，Codex 已輸出計劃并經過人工確認。

? 收尾：好用的 Codex，不只靠模型，也靠上下文

API 中轉站接入解決的是連接問題，項目上下文解決的是協作問題。靈能API讓入口統一，CC Switch讓本地配置清晰，而 README、目錄地圖、示例環境變量和首輪提示詞讓 Codex 真正理解項目。

建議每次接入新項目都按這個順序來：先確認靈能API線路，再整理上下文，再做只讀體檢，最后允許小范圍修改。這樣生成結果會更穩，也更適合在團隊里長期復用。