Codex override 文件让团队少踩坑

把 /AGENTS.override.md 加进 .gitignore，再配自动升级 Codex，团队就能少踩配置坑。

我用 Codex 工作區一陣子了，順手是真的順手，但有個地方一直讓我卡住：團隊裡只要有人臨時改了 AGENTS 相關設定，那個「臨時」很容易就變成「到底誰的版本才算數」的爛攤子。你以為大家跑的是同一套規則，結果有人本地多了一個 override，另一個人根本沒吃到，第三個人還不小心把它提交了。最後開會對 bug，大家講的像是同一個專案，其實像在講三個不同世界。

我就是因為這種事，才去翻了這篇 知乎文章。它不是在講什麼玄學，而是很直接地把 Codex 在符號連結工作區的 AGENTS 載入問題，跟 /AGENTS.override.md 的處理方式綁在一起看。它提到的重點很實際：把覆蓋文件丟進 .gitignore，再把後續修復交給自動升級。這個思路我很買單，因為它修的不是單一 bug，而是團隊最常見的配置漂移。

別把臨時 override 養成半正式規格

把 /AGENTS.override.md 加進 .gitignore。

這句話看起來很短，但意思其實很重。它不是叫你別用 override，而是叫你別讓 override 變成倉庫裡的準正式文件。很多團隊一開始都這樣：先為了修一個小問題加個臨時檔，後來又補一個 workaround，再後來大家都默認那個檔案「應該存在」。等到有人清理分支、切工作區、或在別台機器上跑，問題就開始了。

翻譯一下就是：本地補丁可以有，但不要讓它污染共享狀態。.gitignore 的作用不是把東西藏起來，而是把「本地能用」和「團隊要提交」切開。這個邊界一畫清楚，大家就不會把臨時實驗誤認成正式約定。

我自己最怕那種長得像文件、其實是補丁的東西。它們剛開始都很無害，過一陣子就會變成事故現場。今天是為了修符號連結工作區，明天就是有人把同名檔案複製到別的目錄，後天你再看，repo 裡已經有兩三份內容差不多、但誰也說不清楚差在哪的規則檔。

實操上我會這樣做：把 /AGENTS.override.md 當成本地覆蓋層，不進正式流程；在 README 或團隊約定裡寫清楚它只給個人調試、局部修補用；如果哪天真的要共享，就把內容搬進主配置檔，不要繼續靠 override 續命。

• 把本地覆蓋檔加入 .gitignore。
• 在團隊文件裡明講：override 只給臨時用途。
• 不要讓 CI、release 或正式文件依賴它。

git status 不是裝飾品，它應該替你報警

我很喜歡這個修法的另一個細節：讓新建的 override 文件被 git status 看見，但又不要被誤提交。很多人對 .gitignore 的理解太單線條，以為它只是「藏檔案」。其實更好的用法是：把該消失的噪音消掉，把該浮出來的風險留在視野裡。

如果一個同事在本地臨時加了 /AGENTS.override.md，而它又沒被忽略，那它就很容易被順手提交。今天只是修 bug，明天 repo 裡就多了一個沒人注意的本地配置。相反，如果它被 .gitignore 管住，git status 就會保持乾淨，真正需要提交的變更也更容易被看見。這種土法很笨，但很有效。

我之前就吃過類似的虧。團隊有個調試用設定檔沒忽略，結果同事趕工時順手提交了。那次沒炸，但它把「本地例外」變成了「倉庫預設」。從那之後，每個人都得先理解那份例外，再判斷自己的問題是不是跟它有關。超浪費時間，也很傷協作信任。

實操上我會定兩條規則：第一，臨時 override 預設不提交；第二，如果真的要共享，就直接升級成正式配置檔，不要繼續用 override 這種灰色地帶。這樣大家看 git status 時，心裡會很清楚哪些是臨時件，哪些是正式件。

• 讓 git status 只暴露真正該處理的東西。
• 把臨時 override 和正式配置分開命名。
• 要共享就搬進主配置檔，不要混著用。

符號連結工作區的坑，本質是發現機制太天真

Codex AGENTS.md 在符號連結工作區無法載入的問題已在 v0.138 版本中修復。

這句話很重要，因為它說明問題不是「某個檔案讀不到」這麼表面，而是「在特定工作區結構下，工具找檔案的方式不對」。符號連結工作區本來就容易把路徑、根目錄、相對引用這些事搞複雜。工具如果只按最理想的目錄結構去找，就很容易在鏈結層翻車。你眼前明明有檔案，它就是不認；你換個入口，又突然好了。這種問題最煩，因為它看起來像偶發，其實是路徑解析太天真。

白話講，就是「文件存在」跟「文件被正確找到」是兩件事。很多工具都死在這裡：它以為自己在讀配置，其實只是讀到一個理想世界裡才成立的路徑。v0.138 這次修的是發現邏輯，不只是補一個邊角問題，這點我覺得很實在。

我自己在 monorepo、pnpm workspace、link 目錄混用時，最討厭的就是這種路徑感知問題。你只要把入口換成符號連結，很多工具就像第一次見到專案。表面上是 bug，底層其實是它根本沒想過真實世界會長這樣。

實操上，如果你也在做 agent、CLI 或任何會讀工作區設定的工具，別假設使用者永遠從標準 repo 根目錄啟動。真實情況是，別人會從符號連結、掛載目錄、容器卷、子目錄入口進來。你要嘛支援這些入口，要嘛就老老實實寫清楚限制，含糊其辭最坑人。

如果你是使用者，那就自己驗一次：在符號連結工作區裡確認 Codex 能不能找到 AGENTS 檔，確認 override 是否按預期生效。別等到團隊跑偏了，才發現根本不是你以為的那個行為。

自動升級比人工盯版本更像樣

這篇裡我最認同的一點，是把修復和升級策略綁在一起看，而不是只看 bug 本身。單獨修一次版本問題，當然能救急；但如果團隊還停在舊版本上，那修復就只是「某個人知道了」，不是「整個團隊吃到了」。所以我一直比較偏好用 Renovate 或 Dependabot 這種自動化工具，而不是靠人肉提醒。

這裡的邏輯很現實：Codex 這類工具的行為修復，通常不是一次性的。今天是符號連結工作區，明天可能是別的路徑發現問題，後天又來配置優先級調整。你不可能要求每個開發者都盯 release note，也不該這樣要求。自動升級至少能保證一件事：新修復會更快進到大家日常工作環境。

我看過太多團隊嘴上說「我們會定期升級」，實際上就是等到有人撞 bug 才想起來看版本。這種模式很脆。你今天不自動化，明天就會在 Slack 裡反覆問「誰能順手升一下」。然後一拖再拖，最後變成「先別升，等這個分支合完」。結果就是，已知修復被你們自己拖成未知風險。

實操上我會建議：如果你用 GitHub，就先把 Dependabot 開起來；如果團隊已經在用 Renovate，就直接替 @openai/codex 配規則。升級策略不用花俏，核心就是兩件事：盡快拿到修復，盡量減少人工判斷成本。你甚至可以把它設成小步快跑，而不是一次跳大版本，回滾也比較不痛。

• 用 Renovate 或 Dependabot 自動提版。
• 把 Codex 相關依賴納入常規更新隊列。
• 優先接收修復型版本，別把更新拖成技術債。

把本地補丁從團隊約定裡拆出去

這件事其實是整篇最值得學的地方。AGENTS.override.md 這個命名本身就很誠實：它不是主配置，它是覆蓋層。覆蓋層存在的目的，是讓你在不動主配置的前提下做局部調整。可一旦你把它提交進倉庫，它就不再只是覆蓋層，而會變成一種隱性約定。隱性約定最可怕，因為它沒有邊界，也沒有負責人。

我更願意把這類檔案看成「個人工作台上的便條」，不是「專案說明書的一部分」。個人便條可以很多，甚至可以很亂，但它們不該污染團隊共識。團隊共識應該盡量少而清楚：哪些檔案是正式的，哪些只是本地的，哪些能自動升級，哪些必須人工審查。邊界越清楚，工具越不容易把人帶進坑裡。

如果要落地，我會建議你順手一起做這幾件事：

• 明確主配置檔和 override 檔的責任分工。
• 給本地覆蓋檔加進 .gitignore。
• 把工具版本升級納入自動化流程。
• 在團隊文件裡寫明：符號連結工作區也要驗證。

這樣一來，問題就不會被拆成零碎的「誰的機器壞了」「誰忘了提交」「誰沒升版本」，而是回到比較健康的狀態：規則清楚，路徑明確，升級自動化，臨時補丁不亂飛。說到底，開發體驗裡最值錢的不是少敲幾行字，而是少猜幾次系統到底在幹嘛。

可抄的模板

# Codex team setup: keep local overrides out of git, and auto-upgrade Codex

## Files
# Local-only override file for experiments and machine-specific fixes
/AGENTS.override.md

## .gitignore
# Keep local Codex overrides out of version control
/AGENTS.override.md

## Team rule
# - AGENTS.md is the shared source of truth
# - AGENTS.override.md is local-only and must not be committed
# - If an override needs to be shared, promote it into the main AGENTS.md

## Verification checklist
# 1. Open the workspace through a symlinked path
# 2. Confirm Codex loads AGENTS.md correctly
# 3. Create /AGENTS.override.md locally
# 4. Confirm git status stays clean for the override file
# 5. Confirm the override is picked up only on the local machine

## Renovate example
{
  "packageRules": [
    {
      "matchPackageNames": ["@openai/codex"],
      "automerge": false,
      "enabled": true
    }
  ]
}

## Dependabot example
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    allow:
      - dependency-name: "@openai/codex"

## PR note
# When Codex is updated, re-check:
# - symlink workspace loading
# - AGENTS discovery
# - override precedence

我會把這份模板當成起點，不是終點。你可以按自己的 repo 結構改路徑，按自己的套件管理器改升級規則，但原則別變：本地 override 不進倉庫，工具修復靠自動升級，符號連結工作區要單獨驗證。

原始問題和修復點來自這篇知乎文章：Codex AGENTS.md 在符號連結工作區無法載入的問題已在 v0.138 版本中修復。我上面這套整理是基於它做的實戰化改寫，不是逐字照抄；真正有價值的是把修復變成團隊能直接執行的約定。