【2026 最新】Context Repo 是什麼？讓 Claude Code、Codex 與團隊共用記憶（新手實作教學）

你是不是也遇過這種循環：剛把專案背景、命名規則、部署方式教完，下一個 Claude Code 雲端 Session、另一位 Codex Agent，或換一台電腦後，又得從頭說一次？更麻煩的是，真正重要的往往不是某段聊天，而是「這幾個 repo 如何相依」「上次為什麼否決方案 B」「接手前要跑哪些測試」。這些資訊若只留在人的腦中或某個 Session 裡，交接就像每次都重新拼一張散掉的地圖；Context Repo 想補的正是這個缺口。

2026 年 7 月 31 日，Reddit 的一篇 Claude Code 雲端架構分享在我們掃描時累積約 150 票，討論焦點正是：短命的雲端環境怎麼保留規則、Skills、多專案關係與工作交接。這篇教學把那個需求整理成一套更中立、可跨 Claude Code 與 Codex 使用的做法：Context Repo。

先釐清名稱：Context Repo 不是 Git、Anthropic 或 OpenAI 制定的正式標準，網路上也有同名產品。本文說的，是一種實務架構——用一個私有 Git repository 保存跨專案、跨 Agent 都需要的「工作脈絡」。看完你會從零建立 repo、接上 AGENTS.md 與 CLAUDE.md、設計 handoff，並知道 submodule、秘密資訊與最小權限的邊界。

先說結論：Context Repo 是導航圖，不是完整大腦

Context Repo ＝跨專案導航圖＋可審查的交接簿，不是 Agent 的完整大腦。

它最適合保存四種東西：穩定的團隊規則、repo 關係地圖、可重複執行的 Skills，以及附帶分支、commit、測試結果的交接紀錄。它不該保存密碼，也不該複製所有程式碼、聊天全文或即時營運資料。換句話說，Context Repo 管的是「下一位執行者該從哪裡開始、相信什麼、如何驗證」，不是把所有資訊一股腦塞進模型。

Context Repo、專案規則、本機 memory、RAG 到底差在哪？

這四個名詞都在處理「AI 要知道什麼」，但處理的時間尺度與責任不同。最簡單的判斷法是：規則跟著哪個範圍走？資訊要由誰審查？需要精準重現某個版本嗎？

• 專案內的 AGENTS.md／CLAUDE.md：離程式碼最近，適合單一 repo 的建置、測試與風格規則。專案規則應優先於跨專案筆記。
• Context Repo：保存多個 repo 的關係、團隊共識、共用流程與 handoff；靠 Git commit、PR 與 review 留下可追蹤的修改史。
• 本機 memory：工具在某台機器上累積的偏好或筆記，方便個人延續工作，但通常不會自動跟著你跨到另一台機器或新的雲端 VM。Claude Code 的自動記憶位於使用者目錄；截至 2026 年 8 月 3 日，Codex 的 local memories 預設關閉，啟用後存於 CODEX_HOME（預設 ~/.codex/memories/），也不應假設它會同步到其他電腦或 Codex cloud。必要的團隊指引仍要放進 AGENTS.md 或已提交文件。
• RAG：在提問時從大量文件中檢索相關片段。它擅長「找資料」，Context Repo 擅長「定義可信入口與交接狀態」；Context Repo 甚至可以成為 RAG 的資料來源，兩者並不衝突。

如果你想先補齊底層概念，可以搭配閱讀 AlphaLab 的 Context Engineering 入門與 Obsidian QMD 記憶系統。前者談如何設計送進模型的脈絡，後者偏向個人知識的本機檢索；Context Repo 則把重點放在團隊可審查的 Git 工作流。

為什麼雲端 Agent 特別需要這一層？

依照 Anthropic 的 Claude Code cloud environments 文件，每個雲端 Session 會在新的 Ubuntu VM 中執行；repo 內已提交的 CLAUDE.md、規則、Skills 與 .claude/settings.json 中配置的 hooks 會隨 clone 進來，但使用者家目錄裡的本機設定不會因此變成團隊共享資產。關閉瀏覽器不會立刻停止 cloud session；閒置到 VM 被回收後，重開會配置新 VM 並恢復對話歷史。Anthropic 並未承諾還原未提交的完整工作樹，因此需要跨環境保留的成果仍應 commit／push 並寫入 handoff。

Codex cloud 的原理相似：官方的 cloud environment 文件說明它會建立容器、checkout 指定 branch 或 commit，再執行 setup。如果目標是跨使用者、跨工具又能 review，最可靠的共同基線仍是已提交的 repo 狀態與明確文件；Codex 的 environment 設定與 container cache 是另一層平台狀態，不能取代 Git handoff。這也是為什麼一份聊天摘要不夠：它缺少 diff、commit SHA、驗證命令與 review。

但不要反過來誤會：把 Context Repo 加進 Session，不代表另一個 repo 會自動套用它的所有規則。多 repo Session 解決的是「檔案可見」，不是「指令必然被讀取」。啟動時仍要明確要求 Agent 先讀 Context Repo 的入口檔，再讀實際專案裡更接近程式碼的規則。

一個好用的 Context Repo，至少要有 5 個零件

1. 入口：README.md 說明這個 repo 的目的、誰維護、資料可信順序與開始方式。
2. Agent 轉接層：AGENTS.md 給 Codex；CLAUDE.md 給 Claude Code。兩份檔案指向同一套核心規則，避免維護兩份互相漂移的真相。
3. 長期脈絡：context/CORE.md 放穩定原則，REPOS.md 畫專案關係，DECISIONS.md 記錄重要決策、理由、owner 與最後驗證日期。
4. 可執行 Skills：把部署、QA、release 等反覆流程寫成 Agent 可以照做的步驟；仍要把權限控制放在工具與平台層。
5. 短期 handoff：每次任務一個獨立檔案，記錄 repo、branch、commit／PR、完成內容、測試結果與下一步；不要讓多個 Agent 同時改同一份「最新狀態」。

實作：從零建立一個私有 Context Repo

步驟一：建立資料夾與私有 repo

以下用 GitHub CLI 示範。把 ACME 換成你的組織名稱；建立前先確認目前登入的帳號。

gh auth status
mkdir team-context && cd team-context
git init -b main
mkdir -p context sessions repos .agents/skills .claude/skills
touch README.md AGENTS.md CLAUDE.md
touch context/CORE.md context/REPOS.md context/DECISIONS.md
touch sessions/INDEX.md sessions/TEMPLATE.md
git add .
git commit -m "context: initialize shared agent memory"
gh repo create ACME/team-context --private --source=. --remote=origin --push
gh repo view ACME/team-context --json url,isPrivate

最後一行不是裝飾：它讓你在放入任何內部資訊前，先確認遠端真的是 private。私有 repo 代表「受存取控制的版本庫」，不是秘密保管箱；可讀取 repo 的人與 Agent，仍能看到裡面的全部內容。

步驟二：用 AGENTS.md 當共同入口

Codex 會沿目錄層級讀取 AGENTS.md；越靠近目前工作目錄的規則優先。先把這份檔案寫短，只放啟動順序與權威邊界：

# Team Context

At the start of a task:
1. Read context/CORE.md and context/REPOS.md.
2. Read the target project's own AGENTS.md or CLAUDE.md.
3. Read the newest relevant sessions/*.md handoff.

Authority order:
live system state > target project rules > this context repo.

Before declaring DONE:
- record repo, branch, commit or PR;
- run the target project's required checks;
- write a new session handoff instead of overwriting another agent's file.

Never store credentials, tokens, private keys, or customer data here.

Claude Code 原生讀取的是 CLAUDE.md，而不是 AGENTS.md。官方的 memory 文件支援用 @ 匯入其他檔案，因此轉接檔可以只有：

@AGENTS.md

# Claude Code adapter
At session start, explicitly read the target project's CLAUDE.md too.

這個設計的重點不是讓兩個 Agent 行為完全相同，而是讓共用原則只有一個可 review 的來源。各工具獨有的設定留在 adapter；各專案獨有的規則留在專案 repo。

步驟三：共用 Skill，但保留工具原生路徑

Claude Code 的專案 Skills 放在 .claude/skills/<name>/SKILL.md；Codex 的專案 Skills 放在 .agents/skills/<name>/SKILL.md。Codex 支援 symlinked skill folders；Claude Code Skills 文件則標示 Skill 目錄 symlink 需要 v2.1.203 以上。確認版本後，macOS／Linux 團隊可把內容只維護一份：

mkdir -p .agents/skills/release-check .claude/skills
$EDITOR .agents/skills/release-check/SKILL.md
up=..
ln -s "$up/$up/.agents/skills/release-check" .claude/skills/release-check
unset up
git add .agents/skills .claude/skills
git commit -m "context: add shared release-check skill"

若使用舊版 Claude Code，或團隊的 Windows／Git 設定不方便保留 symlink，就用一支 setup script 從共同來源複製到兩個原生路徑，並在 CI 比對內容是否一致。Skill 本身是流程說明，不是權限沙箱；Claude Code 的 allowed-tools 只代表免詢問的預先授權，不會封鎖其他工具。真正的限制應由 deny rules、sandbox、GitHub 權限與執行環境共同落實。想把這一層做得更完整，可以延伸閱讀 AI Agent Harness 是什麼與 如何打造 Agent Harness。

步驟四：要不要用 Git submodule？先理解它保存的是「指標」

若你需要精準重現「當時搭配哪一版 frontend 與 API」，可以把專案加成 submodule：

git submodule add -b main https://github.com/ACME/frontend.git repos/frontend
git submodule add -b main https://github.com/ACME/api.git repos/api
git add .gitmodules repos
git diff --cached --submodule=log
git commit -m "context: pin frontend and api repos"
git push

-b main 記錄追蹤分支的提示，真正被 Context Repo commit 固定的是 submodule 的 commit 指標，不會自動永遠漂在最新 main。新 clone 還要執行：

git clone --recurse-submodules https://github.com/ACME/team-context.git
cd team-context
git submodule sync --recursive
git submodule update --init --recursive
git submodule status --recursive

submodule 初始常在 detached HEAD；要修改子專案，先切到明確分支，再在子專案 commit／push，最後回到 Context Repo commit 更新後的指標。這是兩段 Git 歷史、通常也是兩個 PR，不是一個大 repo。

• 選 submodule：你需要可重現的 commit pin、專案各自 ACL 與獨立歷史，也願意承擔初始化、detached HEAD 與兩次 commit 的認知成本。
• 選平台原生多 repo／兄弟資料夾：你只需要讓 Agent 同時看見幾個 repo，並可在 REPOS.md 記 branch 或 commit；這通常是新手最省事的起點。
• 慎選 subtree：它把程式碼複製進 Context Repo，會擴大 repo 體積與可讀範圍。除非你本來就需要一起分發那份程式碼，否則不太像「只存脈絡」。

原始討論裡的 BlitzOS 正好展示這個取捨：它的 builder 可以寫入 submodule 指標，預設雲端啟動則把 context 與 member repos 當成同一 Session 的兄弟 checkout。截至 2026 年 8 月 3 日，該版 README 仍把 Codex support 列在後續規劃，因此它應被理解為一個偏 Claude 的實作案例，而不是已完成的跨 Agent 標準；本文加入 AGENTS.md 與 CLAUDE.md adapter，是在這個模式上做的工具中立延伸。

完整示範：Claude Code 雲端做到一半，交給 Codex 接手

第一棒：Claude Code cloud

1. 在 Claude Code web 建立 Session，加入 ACME/team-context 與目標 ACME/frontend。官方 web quickstart支援一個 Session 選取多個 repo。
2. 先用 Plan 模式，提示：「直接讀 team-context/AGENTS.md、team-context/context/CORE.md 與 team-context/context/REPOS.md，再讀 frontend 自己的 CLAUDE.md；不要假設兄弟 repo 的指令檔已自動載入。若衝突，以 frontend 規則為準。」
3. 審閱並核准 plan、切換到 Accept edits 後，讓 Session 在它建立的工作分支修改，跑專案指定的 lint、typecheck 與 test，commit 並 push；完成後用 git branch --show-current 與 git rev-parse HEAD 把實際 branch／commit 寫進 handoff。下文的 agent/auth-timeout 只是示意名稱。
4. 不要改共享的 sessions/LATEST.md。建立唯一檔名，例如 sessions/2026-08-03-auth-timeout.md，透過 Context Repo 的 PR 送出交接。

handoff 模板至少寫清楚：

# auth-timeout handoff
status: blocked
owner: frontend-platform
last_verified: 2026-08-03

repo: ACME/frontend
branch: agent/auth-timeout
commit: 1a2b3c4
PR: #418

changed:
- retry only idempotent requests after token refresh

verification:
- pnpm lint: PASS
- pnpm typecheck: PASS
- pnpm test auth: PASS
- e2e staging: BLOCKED — test account unavailable

next:
- obtain the test account through the approved secret channel
- run e2e and attach the result to PR #418

blocked 比假裝 done 更有用；PASS、FAIL、BLOCKED、SKIPPED 應分開記。範例用短 SHA 方便閱讀，正式交接應貼上 git rev-parse HEAD 的完整輸出。commit SHA 與命令讓下一位 Agent 能驗證，而不是相信一段語氣很有自信的摘要。

第二棒：Codex

Codex 接手時 clone Context Repo，初始化 submodule，再切到 Claude 已推送的工作分支：

git clone --recurse-submodules https://github.com/ACME/team-context.git
cd team-context
git -C repos/frontend fetch origin
git -C repos/frontend switch --track origin/agent/auth-timeout
codex

提示 Codex 先核對 handoff 裡的 branch 與 commit，再讀 frontend 的專案規則、重跑必要測試。它完成 e2e 後，若所用 GitHub 身分可寫入該 PR 的 head branch，就把新 commit 推到原 PR；若分支位於 fork、未允許 maintainer edits 或受規則限制，就另開 PR 或只附上驗證證據。接著另開一個 Context Repo PR 更新 handoff 或 index。這樣 Claude 與 Codex 不必共享同一段對話，也能共享一條可查核的工作鏈。若你想比較兩者的操作差異，可看 Claude Code vs Codex。

安全邊界：private repo 不是保險箱

Context Repo 集中的是組織地圖、指令與交接，外洩時同樣有價值。安全設計應從「誰能讀哪個 repo、Session 能做哪些動作」開始，而不是只加一行 .gitignore。

• 秘密不進 Git：API key、PAT、私鑰、客戶資料與正式環境憑證交給核准的 secret manager 或 credential broker。截至 2026 年 8 月 3 日，Claude Code cloud environment 不是專用秘密庫；若組織政策允許且不得不用環境變數，應採短效、最小權限憑證，並視為同一 environment 的使用者都可能讀取。.gitignore 只會阻止尚未追蹤的檔案被加入，救不了已 commit 的秘密。
• GitHub 成員權限才是底線：不要假設安裝 GitHub App 時勾選少數 repo，就等於每次雲端 Session 的精細隔離。Agent 使用的帳號本身只應看見任務需要的 repo。
• 憑證縮小範圍：若平台提供 scoped Git proxy，讓真正 token 留在 VM 外並限制部分 Git 操作；這不等於完整的 repo 隔離。以 Claude Code cloud 為例，push 受目前分支約束，但連線帳號仍可能 clone／fetch 它本來看得到的其他 repo。自行配置時使用短效、細粒度且最小權限的憑證。
• 規則也要 review：AGENTS.md、CLAUDE.md 與 Skills 會影響 Agent 行為。應在 branch protection／ruleset 啟用「Require a pull request before merging」與 required reviews，再用 CODEOWNERS 指定 owner；單放 CODEOWNERS 只會請求 reviewer，不會自動阻擋 merge。
• 限制網路與工具：文字規則只能指導行為，不能取代 sandbox。Anthropic 的 雲端 sandbox 架構也把檔案系統、網路與 Git 憑證分層處理。

如果秘密已被 commit，第一步是撤銷或輪替，不是只刪檔案再 commit。GitHub 的 敏感資料移除指南也指出，必要時要重寫歷史並協調 clones、forks 與 PR refs。

什麼時候值得用？什麼時候一份專案文件就夠？

值得建立 Context Repo 的訊號，是你同時符合其中兩三項：工作跨多個 repo；Claude、Codex 與人類輪流接手；常開 fresh cloud environment；同一套 release／QA 規則散落各處；團隊反覆問「哪個 repo 管什麼」；交接需要 commit 與測試證據。

先不要建立 的情況也很清楚：只有一個 repo、一位主要開發者；專案內的 README、issue、PR 與 AGENTS.md／CLAUDE.md 已足夠；資訊是工單、CRM、監控數據等即時狀態，應由 API 或原系統取得。這時多一個 repo 只會多一份需要除舊的文件。

也別把它誤當 monorepo。monorepo 把多個產品程式碼放進同一份歷史；Context Repo 原則上只放導航、規則與交接，必要時用 submodule 指向外部專案。先從「純文件＋平台多 repo」起步，真的遇到重現版本的需求，再加 submodule。

最常見的 6 個失敗模式

1. 把 handoff 寫成作文：沒有 branch、commit、PR 與測試命令，下一位無從驗證。
2. 所有 Agent 改同一份狀態檔：平行 Session 互相覆蓋。改用唯一檔名與 PR，index 只在 merge 時更新。
3. 規則越堆越長：Agent 抓不到重點，舊規則又沒刪。每段標 owner、scope、last_verified；入口只放路由。
4. 跨 repo 規則壓過本地規則：Context Repo 應當導航，不該遠端改寫某專案的測試與安全限制。
5. 把「已寫」當成「已強制」：文件裡寫禁止 push，不等於技術上不能 push；權限、sandbox、branch protection 才是執行邊界。
6. 把完整聊天當記憶：聊天包含猜測、過時資訊與大量雜訊。保留決策、證據與下一步，原始 Session 只作補充。

Context Repo 常見問題

1. Context Repo 是 Anthropic 或 OpenAI 的正式功能嗎？

不是。本文把它定義為一種 Git-native 實務模式；Claude Code 與 Codex 各自提供雲端環境、指令檔與 Skills，Context Repo 是把這些元件組成跨專案工作流的方法。

2. 有 Context Repo，還需要 AGENTS.md 或 CLAUDE.md 嗎？

需要。Context Repo 的入口仍靠這些工具原生檔案；每個專案也應保留最接近程式碼的規則。跨專案層提供地圖，本地層提供精確操作。

3. 它可以取代 RAG 或向量資料庫嗎？

不能直接取代。文件少而精時，Agent 依入口讀檔就夠；資料量大時，可用 RAG 找出相關片段。Context Repo 負責治理哪些資料可信、如何交接，RAG 負責檢索。

4. Claude Code 雲端 Session 關掉後，Context Repo 能恢復所有工作嗎？

不能靠 Context Repo 完整恢復。關閉瀏覽器不會立刻停止 cloud session；VM 被回收後重開時，Claude Code 會在新 VM 恢復對話歷史，但官方沒有承諾還原未提交的完整工作樹。Git 這一層只能保存已 commit／push 的檔案、分支與 handoff，因此重要成果仍要落到 branch、commit、PR 與可重跑的命令。

5. 一定要用 submodule 嗎？

不用。剛開始用 REPOS.md 加平台原生多 repo 最簡單；只有需要固定跨 repo 版本組合時，submodule 的 commit pin 才特別有價值。

6. 多位 Agent 可以直接一起改 main 嗎？

不建議。每個任務用獨立 branch、獨立 handoff 檔與 PR，並在 branch protection／ruleset 啟用 required PR reviews。這能降低平行 Session 覆蓋內容與錯誤 handoff 進 main 的機率；CODEOWNERS 可指定 reviewer，但必須配合 required review 才會成為合併門檻。

7. 可以把 API key 放在 private Context Repo 嗎？

不要。private repo 的讀者仍能看到歷史，誤分享或權限擴大也可能暴露內容。只在 repo 記「秘密的名稱與取得流程」，值本身放在核准的 secret manager 或 credential broker；不得不用環境變數時，採短效值並把同環境使用者視為可讀者。

8. 個人開發者也適合嗎？

如果你跨多個 repo、常在本機與雲端 Agent 間切換，就有幫助；若長期只做單一專案，一份維護良好的專案文件更輕。先觀察自己是否每週重複解釋同一組跨專案資訊。

新手只要先做這 4 件事

1. 建一個 private repo，只放導航、規則、Skills 與 handoff，不放 secrets。
2. 以 AGENTS.md 為共同入口，讓 CLAUDE.md 匯入它；在團隊約定的權威順序中，專案本地規則高於跨專案層。這是文件約定，強制邊界仍靠 hooks、deny rules 與 sandbox。
3. 每次交接都寫 branch、commit／PR、驗證結果與下一步，透過 PR 合併。
4. 先不用 submodule；等你真的需要跨 repo 的精準版本 pin，再承擔它的 Git 成本。

📚 延伸閱讀：把共用記憶接進完整工作流

• 想先理解「該送什麼給模型」：從 Context Engineering 完整教學開始。
• 想把規則、工具與驗證組成執行環境：接著看 如何打造 AI Agent Harness。
• 想決定任務該交給哪一個 coding agent：參考 Claude Code vs Codex 客觀比較。
• 想系統化學習更多實作：瀏覽 AlphaLab AI 專區與 AI 課程。

結論：真正能共用的記憶，必須可以被查核

Context Repo 最有價值的地方，不是讓 Agent 看起來永不失憶，而是把「團隊正在相信什麼」變成可以 diff、review、回溯與驗證的檔案。聊天會結束、VM 會更換、工具也會不同；一個附帶 commit、測試與責任人的交接，卻能讓下一位從可靠的起跑線繼續。

如果你今天就要開始，先建立 README.md、AGENTS.md、CLAUDE.md 與一份 handoff template，選一個真實的小任務做完整交接。等流程真的卡在跨 repo 版本，再加入 submodule；等文件多到找不到，再接 RAG。這個順序比一開始打造龐大「第二大腦」更容易維護，也更符合 把 AI 納入工作系統的核心：讓資訊、權限與驗證各自待在正確的位置。