Codex 和 Claude Code 能良好遵循哪些目錄慣例與程式碼風格？
Codex 和 Claude Code 本身並不偏好特定的程式語言、框架、縮排寬度或資料夾配置。它們能相對可靠遵循的環境，是那些既有儲存庫慣例一致、必要規則的適用範圍明確，且變更可自動驗證的環境。因此，目標不是創造 AI 可能喜歡的結構，而是讓人員與新加入的貢獻者都能理解、簡短且可驗證的專案慣例。openai.comcode.claude.com
本文中的 Codex 和 Claude Code，是指可讀取儲存庫檔案、參考指示、修改程式碼或執行指令的程式設計代理工具。這類工具可從程式碼本身取得許多線索，但不一定能準確推斷產品領域術語、禁止變更事項、部署前檢查，或特定資料夾的例外規則。儲存庫結構、指示檔和可執行的驗證程序可填補這項落差。cdn.openai.com
為什麼一致性比「正確的資料夾結構」更重要？
例如，一個團隊可能按功能組織 src/payments/ 和 src/users/，另一個團隊則可能按分層組織 src/controllers/、src/services/ 和 src/repositories/。沒有依據能斷言任一做法對 Codex 或 Claude Code 必然更好。重要的是，同類職責在儲存庫內有相似的位置、新檔案依相同標準放置，且測試和匯入風格遵循既有模式。
當代理新增付款功能時也是如此。若既有付款模組展示了如何安排請求驗證、錯誤處理、資料存取與測試，延續該模式較為安全。反之，若每個新功能都引入新的檔名與分層，或單一資料夾混有領域程式碼、建置產物與暫存檔，無論代理或人員都難以判斷應在哪裡修改，以及修改會影響什麼。
因此，目錄慣例不只是外觀規則。它們是一套導覽系統，揭示程式碼在哪裡、哪些內容應一起變更，以及應執行哪些驗證。名稱與邊界越穩定，就越不需要在指示檔中重複冗長說明。
儲存庫的基本指引應放在哪裡？
在 Codex 中，AGENTS.md 通常作為專案指示檔。此檔案中的程式碼風格、結構、命名與測試指示，會套用到檔案所在目錄及其子樹；當發生衝突時，較深層位置的指示可作為更具體的指引。也支援個人環境的指示，以及透過 AGENTS.override.md 進行覆寫。openai.com
在 Claude Code 中，CLAUDE.md 或 .claude/CLAUDE.md 可作為專案記憶與指引的中心。父層路徑中的 CLAUDE.md 可在啟動時作為脈絡提供，而子目錄中的檔案則會在處理該路徑的檔案時視需要載入。也可以使用 CLAUDE.local.md 作為每位使用者的設定，並使用家目錄層級的檔案。code.claude.com
儘管兩個檔案名稱相近，它們的自動探索行為並不相同。尤其不要假設 Claude Code 會自動讀取 AGENTS.md 作為共用指示。同時使用兩種工具時，應在 CLAUDE.md 中以 @AGENTS.md 匯入共用檔案，或明確定義符合團隊作業模式的連結。code.claude.com
根層指引檔最好更接近一份入口地圖，而非詳盡描述整個儲存庫的百科全書。只要展示新貢獻者首先需要的指令、頂層結構、關鍵不變條件，以及詳細文件的位置即可。單一且冗長的指示檔會占用原本應用於實際程式碼與任務需求的脈絡，並可能讓關鍵限制更難被注意到。一個與 OpenAI Codex 相關的範例，也呈現了約 100 行、簡短且地圖式檔案搭配獨立文件的組合。openai.com
AGENTS.md 和 CLAUDE.md 應包含哪些內容？
良好的指示不會大量重複程式碼中已顯而易見的事實，而是優先放入難以僅從程式碼得知，或錯誤推斷成本很高的資訊。與 Codex 相關的資料指出，命名慣例、領域語言、已知限制與相依性，以及建置和測試程序，是值得放入 AGENTS.md 的資訊。cdn.openai.com
根層指示可以簡潔回答下列問題：
- 初步變更後，哪些指令可執行格式化、靜態分析、型別檢查與測試？
- 原始碼、測試、設計文件與操作文件位於何處？
- 擴充既有模組時，應遵循哪些檔案命名、匯入、錯誤處理與測試慣例？
- 是否可修改或將產生檔、建置產物、鎖定檔和密鑰納入儲存庫？
- 高風險區域是否需要計畫、額外審查或特定測試？
- 哪些文件包含詳細設計與操作程序？
相較之下，「寫出乾淨的程式碼」、「優先考慮安全性」或「盡力而為」等廣泛敘述，很難轉換為可執行規則。「對外部輸入使用既有驗證模組，並為每個新增 API 路由加入對應整合測試」這類敘述則更有用，因為能被觀察與驗證。Claude Code 指引同樣強調，應具體撰寫專案專屬規則，並隨著指示增加而定期檢視和整理。code.claude.com
指示應是決策標準的壓縮記錄，而非規定每一項實作細節的文件。較長且可能變動的知識，例如特定函式庫的使用方式、API 合約或事件回應順序，移至 docs/ 下適當的文件會更容易維護；根層指示則指出其位置與使用條件。
何時需要個別子目錄的規則？
子目錄規則不是應機械式加到每個資料夾的檔案。若共用根層規則已足夠，獨立檔案反而可能增加導覽成本與衝突機會。它們最適合保留給明顯偏離一般規則，或錯誤會有重大後果的邊界。
例如，src/payments/ 可以記錄貨幣計算應如何表達、外部付款服務提供者的 mock 應如何使用，以及應執行哪一個特定整合測試指令。infra/ 可以要求變更前先提出計畫、套用前先檢查，以及限制可修改的環境專屬檔案。generated/ 可以說明禁止直接編輯，並識別來源與產生指令。這些規則的目的不是讓資料夾看似特殊，而是要在工作脈絡中精確提供該區域的實際限制。
對 Codex 而言，巢狀的 AGENTS.md 會套用於其目錄以下，而更深層檔案可以提供更具體的規則。Claude Code 同樣可以將多個 CLAUDE.md 累積為脈絡，因此巢狀檔案較安全的做法，是補充只在該區域需要的具體條件，而非做出推翻父層檔案的模糊宣告。openai.comcode.claude.com
例如，根層可以寫「執行已變更套件的測試」，而付款資料夾可以寫「若付款合約變更，請同時執行單元測試與整合測試」。反之，在根層寫「必須一律執行測試」，又在子資料夾寫「不要執行測試」，不只工具，人員也會不清楚該遵循哪項規則。
應如何拆分 Claude Code 的 .claude/rules/？
在 Claude Code 中，可以將一律需要的全域規則放在 CLAUDE.md，並將主題不同或具路徑相依行為的規則，拆分至 .claude/rules/ 下的小型檔案。規則檔可以遞迴組織，且路徑條件能讓規則僅套用於特定檔案或區域。code.claude.com
拆分的標準不是檔案數量，而是會一起變更的規則之內聚性。例如，測試指令與測試資料原則可放在 testing.md；匯入、命名與格式化的例外可放在 code-style.md；涉及密鑰、外部請求與權限的限制可放在 security.md。每個檔案應處理單一主題，且標題應清楚說明何時需要閱讀。
此做法的優點是，不必一直完整閱讀不必要的指示。例如，若完整的資料庫遷移規則仍混在只編輯文件的工作中，就可能掩蓋關鍵指示。然而，規則拆得過細會使其位置難以尋找。較平衡的做法是在根層 CLAUDE.md 中簡短介紹主要規則群組及其目的，同時將實際內容保留在主題專屬檔案中。
分離規則後，避免將相同義務複製到多個檔案。副本很容易隨時間產生差異。將共用原則保留在單一位置，並僅在路徑專屬檔案中記錄例外與附加條件，可減少衝突。
應如何指定程式碼風格？
「對 AI 友善的程式碼風格」不是指 tab 與空格、函數式與物件導向程式設計等某種通用選擇。更重要的標準是能否重現儲存庫的在地慣例。當新模組遵循既有模組的檔案命名模式、匯出風格、匯入順序、錯誤處理路徑與測試結構時，審查與維護都會更容易。
專案所做的任何選擇，只要與該語言的常見慣例不同，就特別值得記錄。Claude Code 文件以 ES modules 或具名匯入解構等專案專屬程式碼風格為例。換言之，與其重寫語言的所有預設規則，更有效率的是描述「我們的專案與預設做法有何不同」。code.claude.com
下表提供判斷風格指引的簡單標準。
| 區域 | 較適合交給程式碼與工具 | 較適合在指示中說明 |
|---|---|---|
| 格式化 | 格式化工具設定已在儲存庫中，且已定義指令 | 特定檔案類型需要格式化工具例外 |
| 匯入 | 既有檔案遵循一致模式 | 存在特殊規則，例如禁止預設匯出或使用內部別名 |
| 錯誤處理 | 共用錯誤類型與處理流程一致 | 存在領域限制，例如禁止重試或區分面向使用者的訊息 |
| 測試 | 測試位置與名稱一致 | 特定變更需要合約測試或整合測試 |
| 命名 | 程式碼中一致使用領域術語 | 對容易混淆的概念有正式名稱或禁用術語 |
格式化工具、linter 和型別檢查器可讓風格透過機制進行測試，而不是藉由文字強制執行。因此，指示最好指定實際要執行的指令與預期的失敗處理方式，而不是說「把格式弄漂亮」。Claude Code 最佳實務也建議採用清楚的專案指示與可驗證的開發工作流程。code.claude.com
可以從哪種目錄結構開始？
以下是同時考量 Codex 與 Claude Code 時可使用的範例。這不是強制標準，而是一種將共用指示、詳細文件與區域專屬例外分開的可能起點。
repo/
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── ARCHITECTURE.md
├── docs/
│ ├── design-docs/
│ ├── product-specs/
│ ├── runbooks/
│ └── generated/
├── src/
│ ├── feature-a/
│ └── feature-b/
├── tests/
└── .claude/
├── rules/
│ ├── testing.md
│ ├── code-style.md
│ └── security.md
└── settings.json
此處，README.md 可包含人員開始使用儲存庫所需的資訊，ARCHITECTURE.md 可描述系統的主要邊界與結構，而 docs/ 可存放冗長且詳細的設計、產品與操作知識。src/ 與 tests/ 的實際配置，應主要遵循專案既有結構。.claude/rules/ 是存放 Claude Code 主題專屬或路徑專屬規則的位置。code.claude.com
若擔心根目錄有太多檔案，關鍵問題不是檔名數量，而是職責是否分離。若一份檔案同時承擔專案介紹、系統設計、操作回應、詳細 API 慣例與風格規則，就難以判斷哪些資訊對目前任務不可或缺。相反地，能指向必要詳細文件的簡短根層指引，讓貢獻者只需探索到必要深度。
在功能專屬資料夾中放置指示檔時，同樣適用這項原則。除非該功能有專屬規則，否則不要新增；只有在存在明確理由時才新增，例如敏感資料處理或自動產生程序。規則檔頻繁擴張，可能使結構本身變得複雜，而非解釋結構。
同時使用兩種工具時，如何減少重複規則？
其中一種做法是，將標準的共用開發慣例保留在 AGENTS.md，從根層 CLAUDE.md 匯入它，再僅附加 Claude Code 所需內容。例如：
@AGENTS.md
## Claude Code only
- Present a plan before changing `src/payments/`.
- Follow the path-specific rules in `.claude/rules/`.
此設定減少了在兩個檔案中重複維護測試指令、共用命名規則與產生檔原則的需要。同時，它仍保留 Claude Code 專屬規則與以 .claude/rules/ 為基礎的設定。不過，如前所述，Claude Code 不會自動讀取 AGENTS.md 作為共用指示，因此必須實際設定匯入或等效連結。code.claude.com
共用檔案應放在哪裡，可取決於團隊對工具的相對使用情形與既有儲存庫慣例。若最常使用 Codex，AGENTS.md 很適合作為標準來源；若作業以 Claude Code 的規則系統為中心，則可改以 CLAUDE.md 作為標準來源。無論選擇何者，重點是為每條規則指定一個權威原始來源，並在另一檔案中只保留參照或工具專屬補充。
最好將個人偏好與團隊慣例分開。個人環境中的指令別名、本機工具選擇與個人工作習慣，可放在個人覆寫檔。相較之下，所有複製儲存庫的人都必須知道的測試程序、安全限制與程式碼結構，應保留在受版本控制的專案指示中。Codex 和 Claude Code 都支援專案層級與個人層級的指示設定。openai.comcode.claude.com
為什麼驗證指令應是指示的核心？
程式設計代理提出的建議或變更可能看似合理，但不會自動保證正確性、相容性或安全性。與 Codex 相關的指引也說明，仍需要人工審查與驗證輸出結果。openai.com
因此，良好的儲存庫指示不只說明「如何寫程式」，也說明「如何檢查」。只要可行，就以可實際執行的形式列出格式化、lint、型別檢查、單元測試、整合測試和建置指令。對於要求每項任務都進行完整驗證並不實際的大型儲存庫，可以區分依變更位置而定的最低驗證，以及需要完整驗證的條件。
例如，文件更新可能只需要連結檢查或文件建置；公開 API 合約的變更則可能需要單元測試與整合測試。資料庫 schema 或基礎設施設定等難以回復的變更，可能需要額外審查階段。重要的不是期待工具能神奇地評估風險，而是將團隊已知的驗證路徑明確記錄在儲存庫中。
從驗證角度來看，產生的程式碼與建置產物也應清楚區分。若檔案不得直接編輯，應記錄其來源位置與產生程序；若允許編輯產物，則應說明哪個指令可更新它。也較安全的做法是清楚表明：密鑰與環境專屬的個人設定不應放入儲存庫、範例檔案的位置，以及必要的驗證步驟。
常見的誤解與失敗模式有哪些？
第一項誤解是「更多指示能帶來更好的遵循度」。實際上，長篇文件可能埋沒最重要的規則。若指示已變得過長，請移除重複說明、已自動化的規則與不再有效的例外，並將詳細知識移至獨立文件。code.claude.comopenai.com
第二項是「每個資料夾都需要指示檔」。巢狀指示只在有特殊限制之處有用。缺乏具體內容的巢狀檔案，只會增加另一份要閱讀的檔案，並可能使其與父層規則的關係不明確。
第三項是「符合風格規則就足夠」。即使格式一致，若未執行測試、違反領域規則，或直接編輯產生檔，變更不一定是好的。風格自動化、測試與審查程序並非互相替代；它們是共同運作的保障。
第四項是「工具會自行解決文件中的矛盾」。父層與子層指示，或共用與工具專屬指示發生衝突時，結果會變得難以預測。應將同一條規則保留在單一位置，並清楚說明子層規則的適用範圍與附加條件。由於 Claude Code 的記憶設定也會處理階層式指示，因此設計規則以避免衝突十分重要。code.claude.com
最後，不要把指示檔當作品質保證。指示提供支援代理與人員判斷的脈絡；它們不是能保證產生程式碼正確、安全或通過測試的機制。審查變更並執行必要驗證仍不可或缺。openai.com
在我們的儲存庫中，應先套用什麼？
不需要從一開始就重新設計整個資料夾結構。根據目前儲存庫中反覆出現的困惑，從小幅改善開始會更務實。例如，若新貢獻者找不到測試指令，就將它加到根層指示；若付款模組重複發生相同錯誤，就只為該路徑增加具體規則；若設計文件與程式碼混在一起且難以導覽，先在 docs/ 中區分文件類型。
可使用以下評估順序：
- 識別目前程式碼庫中確實反覆出現的檔案放置、命名與測試慣例。
- 整理格式化工具、linter、型別檢查與測試的指令及失敗條件。
- 識別難以僅從程式碼理解的領域限制、禁止編輯區域與產生程序。
- 僅將最重要的內容簡潔寫入根層
AGENTS.md或CLAUDE.md。 - 只有在一般規則無法說明的敏感區域，才新增巢狀指示或路徑專屬規則。
- 為共用規則指定一個原始來源，並在另一工具的檔案中只保留參照與工具專屬規則。
- 定期檢視指示在實際工作中是否有幫助，以及是否包含不必要或矛盾的敘述。
在此過程中，無須將「工具容易理解」與「人員容易維護」視為相互對立的目標。簡短、準確的文件，可預測的模組邊界，以及可自動執行的驗證，對兩者都有幫助。反之，試圖只靠指示檔補償連人員都難以解釋的結構，很可能讓文件變得難以使用。
結論：應選擇哪些慣例？
適合 Codex 與 Claude Code 的目錄慣例和程式碼風格，關鍵不在於採用某種流行結構。務實的做法是持續維持既有程式碼庫的慣例、在根層保留簡短指引、將詳細知識分離至適當文件，並僅在必要之處增加範圍明確的規則。
對 Codex，可使用 AGENTS.md；對 Claude Code，則可使用 CLAUDE.md，並視需要使用 .claude/rules/。若同時使用兩種工具，請為共用規則指定單一來源，並在 Claude Code 中明確連結共用檔案以減少重複。最重要的是，將指示與格式化工具、linter、型別檢查、測試及人工審查結合。由於產品專屬的指示解讀方式可能隨版本改變，建議在查閱實際操作工具的官方文件之餘，讓規則保持簡短清楚。openai.comcode.claude.com