# 影片筆記：2026版AI+Codex零基础全套视频课程，Codex从入门到大神AI编程开发，涵盖安装配置、代码分析、Bug修复及完整项目实战 p07 6、Codex AGENTS.md 配置与架构设计

## 一句話總結

本節課程詳細講解了 Codex 中 `agents.md` 文件的配置機制，包括其作為項目規範載入的核心作用、全局/項目/模塊三層級的優先級邏輯，以及如何通過精簡內容、利用 AI 輔助生成及調試命令來優化開發體驗。

## 核心重點

1.  **`agents.md` 的核心價值**：作為 Codex 規範化編程的架構設計，用於定義項目開發規範、結構及開發指南。Codex 在加載項目時會優先讀取此文件，建立全局視圖，從而提高代碼生成的效率與準確性。
2.  **三層級配置文件載入順序**：
    *   **全局層**：位於用戶主目錄下的 `.codex` 目錄，適用於個人開發者統一所有項目的規範。
    *   **項目層**：位於項目根目錄，適用於特定項目的技術棧、命令及架構規範，優先級高於全局層。
    *   **模塊層**：位於項目特定子目錄下，用於覆蓋上層規範，適應不同團隊或模組的獨立規範，優先級最高。
3.  **配置機制與限制**：
    *   **覆蓋邏輯**：系統從最外層開始查找，越靠近當前目錄的文件優先級越高。若兩者皆寫，則都會讀取，但高優先級覆蓋低優先級的通用說明。空文件會被跳過。
    *   **上下文窗口限制**：Codex 有默認的上下文窗口上限，`agents.md` 內容應精簡，建議控制在 100 行左右。過大的文件會導致上下文超限、增加 Token 成本或指令被截斷。
4.  **驗證與調試**：
    *   使用 `codex status` 檢查工作區狀態。
    *   通過終端管理員權限打開 Codex 詢問開發規範來驗證配置是否生效。
    *   常見問題包括配置被更高層級覆蓋、備用文件名未加載、指令被截斷等。
5.  **撰寫建議**：建議利用 AI 輔助生成 `agents.md`，提示詞可要求分析當前項目結構並輸出規範，但需人工審查確保內容精簡，僅保留核心模塊、命令及結構。

## 詳細大綱

### 一、 Agents.md 的核心作用
*   **規範驅動開發**：作為 Codex 規範化編程的架構設計，定義項目開發規範。
*   **全局視圖建立**：Codex 加載項目時優先讀取，了解項目結構、目錄層級及關鍵文件位置。
*   **提升效率**：通過清晰的「代碼地圖」描述，讓 AI 快速掌握重點，提高生成代碼的效率和速度。

### 二、 配置文件載入層級與優先級
Codex 啟動時會整理指令鏈，按順序檢查以下層級：

1.  **全局層 (Global Layer)**
    *   **位置**：當前登錄用戶目錄下的 `.codex` 目錄（或通過環境變量指定的目錄）。
    *   **文件**：`agents.md` 或 `agents.overload.md`。
    *   **適用場景**：個人開發者統一多個語言項目（如 Python、Java）的編碼風格與規範。
    *   **優先級**：基礎層，若無項目層配置則生效。

2.  **項目層 (Project Layer)**
    *   **位置**：項目根目錄。
    *   **文件**：`agents.md`。
    *   **適用場景**：特定項目的結構、後端命令、數據庫配置、前端依賴（npm, package.json）、技術棧（Vue, React）及路由配置。
    *   **優先級**：高於全局層，覆蓋全局配置。

3.  **模塊層 (Module Layer)**
    *   **位置**：項目內的特定子目錄（如支付模組）。
    *   **文件**：`agents.md`。
    *   **適用場景**：不同小組或模組擁有獨立規範，需覆蓋上層配置。
    *   **優先級**：最高，越靠近當前目錄的文件優先級越高，覆蓋更通用的說明。

### 三、 配置機制與細節
*   **覆蓋邏輯**：
    *   系統從最外層開始查找，找到即優先使用。
    *   若全局無配置，則讀取項目層。
    *   若項目層無配置，則讀取全局層。
    *   若兩者皆寫，則都會讀取，但越靠近當前目錄的文件優先級越高，覆蓋前面的通用說明。
    *   空文件會被跳過。
*   **大小限制與上下文窗口**：
    *   Codex 有默認的上下文窗口上限。
    *   `agents.md` 內容應精簡，建議控制在 100 行左右。
    *   過大的文件（如 1MB）會導致上下文超限，增加 Token 成本，甚至導致指令被截斷無法執行。
    *   內容應僅包含核心命令、工程規範及項目結構。
*   **備用文件名配置**：
    *   可在 `config.tom`（Codex 應用配置文件）中配置備用文件名列表。
    *   例如將 `teamgather` 加入備用列表，Codex 會將其當作說明文件加載。
    *   若不使用備用配置，直接使用 `agents.md` 最為方便。
*   **環境變量配置**：
    *   可通過設置 `CODEX_HOME` 環境變量，單獨指定 Codex 的目錄，實現不同場景下的獨立配置。

### 四、 驗證與調試
*   **驗證方法**：
    *   在 `.codex` 目錄或項目目錄創建 `agents.md` 並寫入規範。
    *   使用終端管理員權限打開 Codex，詢問開發規範以驗證是否加載。
    *   觀察 AI 回應是否包含配置的規範內容。
*   **狀態檢查**：
    *   執行 `codex status` 分析工作區狀態。
    *   檢查是否為 Git 倉庫、是否為空目錄等。
*   **常見問題排查**：
    *   **配置未生效**：檢查是否有更高層級（全局或用戶級）的 `agents.overload.md` 覆蓋了配置。
    *   **備用文件名未加載**：檢查路徑是否正確，配置是否生效。
    *   **指令被截斷**：檢查 `project_dockmarks` 參數，過大會導致 Token 消耗增加及上下文截斷。
    *   **環境變量衝突**：確認是否設置了 `CODEX_HOME` 導致邏輯路徑偏移。
    *   **利用 AI 調試**：將配置丟給 Codex 讓其自行分析排查錯誤。

### 五、 撰寫建議與技巧
*   **AI 輔助生成**：
    *   提示詞建議：「請幫我分析當前項目結構，然後輸出一份 agents.md，包含當前項目結構和代碼規範」。
    *   優點：AI 生成的內容通常比手寫更完善，能自動掃描目錄和代碼。
*   **內容審查**：
    *   AI 生成的內容可能存在誤解，開發人員需進行審查和糾正。
    *   確保內容精簡，僅保留核心模塊、命令、配置及結構。
*   **模型效果差異**：
    *   使用 Cloud 模型或 Codex 5.3 效果較好。
    *   其他模型的效果可能無法保證。

## 工具 / 模型 / 名詞整理

*   **Codex**：提及的 AI 編程工具/插件。
*   **agents.md**：規範配置文件名稱。
*   **agents.overload.md**：全局覆蓋配置文件名稱。
*   **.codex**：全局配置目錄名稱。
*   **config.tom**：Codex 應用配置文件。
*   **CODEX_HOME**：環境變量名稱。
*   **project_dockmarks**：提及的參數（疑點：需查證是否為正確參數名，逐字稿原文如此）。
*   **Codex Status**：用於檢查狀態的命令。
*   **Cloud 模型**：提及的模型類型。
*   **Codex 5.3**：提及的模型版本。
*   **DDD (Domain-Driven Design)**：領域驅動設計，提及的開發方式。
*   **Python / Java**：提及的編程語言。
*   **Vue / React**：提及的前端框架。
*   **npm / package.json**：前端依賴管理相關。
*   **POM**：提及的項目結構文件（通常指 Maven 的 pom.xml）。
*   **Harness Engineering**：提及的實現或框架名稱。
*   **Admin / Framework / System / UI**：提及的項目模塊名稱。

## 操作流程整理

1.  **配置全局規範**：
    *   在用戶主目錄創建 `.codex` 目錄。
    *   在該目錄下創建 `agents.md` 或 `agents.overload.md`，寫入通用的編碼風格與規範。
2.  **配置項目規範**：
    *   在項目根目錄創建 `agents.md`，寫入特定項目的結構、技術棧、命令及架構規範。
3.  **配置模塊規範（可選）**：
    *   在項目特定子目錄下創建 `agents.md`，寫入該模組的獨立規範，以覆蓋上層配置。
4.  **驗證配置生效**：
    *   使用終端管理員權限打開 Codex。
    *   詢問開發規範，觀察 AI 回應是否包含配置的規範內容。
    *   執行 `codex status` 檢查工作區狀態。
5.  **利用 AI 生成規範**：
    *   向 Codex 發送提示詞：「請幫我分析當前項目結構，然後輸出一份 agents.md，包含當前項目結構和代碼規範」。
    *   審查 AI 生成的內容，確保精簡並僅保留核心部分。
6.  **調試與排查**：
    *   若配置未生效，檢查是否有更高層級的覆蓋文件。
    *   若指令被截斷，檢查 `project_dockmarks` 參數及文件大小。
    *   將配置丟給 Codex 讓其自行分析排查錯誤。

## 值得注意的限制或風險

1.  **上下文窗口超限風險**：`agents.md` 內容若過大（如 1MB），會導致上下文超限，增加 Token 成本，甚至導致指令被截斷無法執行。建議控制在 100 行左右。
2.  **配置覆蓋風險**：若存在更高層級（全局或用戶級）的 `agents.overload.md`，可能會覆蓋當前項目的配置，導致配置未生效。
3.  **AI 生成內容誤解風險**：利用 AI 輔助生成 `agents.md` 時，內容可能存在誤解，開發人員必須進行人工審查和糾正，確保內容精簡且準確。
4.  **模型效果差異**：使用 Cloud 模型或 Codex 5.3 效果較好，其他模型的效果可能無法保證。

## 逐字稿辨識疑點

*   **CodexAgence.md / Agence.md / agency.md / agents.md**：逐字稿中多次混用這些名稱，指代同一個配置文件，需查證標準名稱是否為 `agents.md`。
*   **agents.overload.md / agents.overall.md / agency.overload.md**：逐字稿中對覆蓋文件名的稱呼不一致，需查證標準文件名。
*   **環境面量**：應為「環境變量」的聽寫錯誤。
*   **vio 的一些酷**：應為「Vue 的一些庫」的聽寫錯誤。
*   **project dockmarks**：需查證此參數名稱是否正確，或是否為 `project_markdowns` 或其他名稱。
*   **Cloud 的模型**：需查證是否指特定雲端模型服務。
*   **Codex 5.3**：需查證此模型版本編號是否準確。
*   **Harness Engineering**：需查證此名稱是否為特定框架或筆誤。
*   **pacent.md**：應為 `package.md` 或 `agents.md` 的聽寫錯誤，上下文提及是 Python 小遊戲的規範文件。
*   **渣滑包 / 買白利斯**：應為「第三方包」或特定庫名稱的聽寫錯誤，需查證具體指代。
*   **MPM / npm run lint**：提及前端命令，MPM 可能為 npm 的誤讀或特定工具。

## 可延伸追問

1.  `agents.md` 的具體語法格式是否有官方推薦的模板？
2.  如何精確計算 `agents.md` 的 Token 消耗，以優化上下文窗口使用？
3.  在團隊協作中，如何協調全局層、項目層和模塊層的配置衝突？
4.  `project_dockmarks` 參數的具體含義和調整建議是什麼？
5.  除了 `agents.md`，Codex 還支持哪些其他配置文件來增強開發體驗？