Claude Code 跨專案記憶怎麼配置？三層方案（2026）

官方文件建議將 CLAUDE.md 控制在 200 行以內，而 auto memory 的 MEMORY.md 在每次會話最多載入 200 行或 25KB。這兩個限制已經說明一件事：Claude Code 跨專案記憶不應靠一份不斷膨脹的全域提示詞完成，而應採用三層方案——CLAUDE.md 保存穩定事實、Claude Code Skills 保存按需載入的流程、外部 Agent Memory 保存跨會話的動態偏好與任務狀態。(Claude Code 記憶官方文件)

這篇適合同時維護多個倉庫、想減少重複輸入專案規則的個人開發者；也適合需要統一團隊流程、卻不想把個人偏好散播到所有專案的研發負責人。若團隊準備讓編碼 Agent 長期執行，還需要一併規劃持久化、使用者隔離、備份與刪除機制。

最後更新於 2026 年 8 月 10 日，內容依 Claude Code 官方記憶、Skills、設定與診斷文件核對；升級版本後，仍應在測試倉庫重新驗收。

先記住：重新載入設定檔，不等於模型擁有永久記憶。 Claude Code 每次會話仍會建立新的上下文；能否正確使用過往資訊，取決於檔案是否被載入、內容是否清晰，以及目前專案是否有權看到這些資料。

第一階段：先把「記憶」分成三種資料

在建立任何跨專案設定前，先將資訊分成以下三類，否則很容易把客戶背景、某個倉庫的內部架構，誤當成所有專案都適用的規則。

第一層是穩定事實。 例如「API handler 位於 src/api/handlers/」、「提交前必須執行 pnpm test」、「此專案使用兩格縮排」。這類內容適合放入專案根目錄的 CLAUDE.md，因為它需要在每次會話開始時出現。

第二層是可重複流程。 例如部署預備環境、審查 Pull Request、產生版本變更紀錄或執行一組測試。這些內容通常包含多個步驟，不應全部塞進 CLAUDE.md，而應整理成 SKILL.md，在相關任務出現時才載入。

第三層是持續變化的狀態。 例如某位使用者偏好的測試順序、上次除錯時留下的線索、尚未完成的遷移工作或跨會話任務進度。這才是 Agent Memory 的適用範圍；若需要跨機器、跨伺服器或跨多個倉庫共享，才考慮外部持久化元件。

不應跨專案共享的內容包括：

• API 金鑰、.env、憑證與部署權限。
• 客戶名稱、內部工單、未公開產品資料。
• 某個倉庫專屬的資料庫結構、路徑與測試帳號。
• 尚未確認的除錯推論，以及可能已失效的臨時決策。

Claude Code 官方設定文件提供 permissions.deny，可拒絕讀取 .env、憑證與秘密資料夾；但權限規則和 CLAUDE.md 的「操作指引」不是同一層，前者用來設限，後者用來描述專案如何運作。(Claude Code 設定官方文件)

第二階段：建立單一專案的 CLAUDE.md

先不要急著做全域共享，應在虛構專案 Atlas-Notes 中建立最小可用版本：

# Atlas-Notes

## 專案結構
- API handler 位於 src/api/handlers/
- 網頁元件位於 src/components/

## 常用命令
- 安裝依賴：pnpm install
- 執行測試：pnpm test
- 執行型別檢查：pnpm typecheck

## 修改限制
- 不得直接修改 migrations/ 內已套用的檔案
- 修改 API 回應格式前，先更新對應測試

這份內容只放長期有效、能被驗證的事實，不放完整部署手冊，也不放「遇到問題時請先分析」這類無法驗收的句子。官方文件建議使用清楚、具體、可檢查的規則，並將過長內容拆到 path-scoped rules 或 Skills。

CLAUDE.md 可放在專案根目錄的 ./CLAUDE.md 或 ./.claude/CLAUDE.md；個人專案偏好則可放在 CLAUDE.local.md，並加入 .gitignore。使用者層設定通常位於 ~/.claude/CLAUDE.md，適合所有專案共用的個人習慣，例如輸出格式或常用工具。

建立後，開啟新的 Claude Code 會話，執行 /memory，確認目前會話實際載入了哪些 CLAUDE.md。接著用固定測試驗證，而不是只問「你有沒有讀到」：

1. 要求 Claude 說出測試命令。
2. 要求它指出 API handler 的目錄。
3. 提出一項與規則衝突的修改，確認它是否先提出警告。
4. 在子目錄新增一份規則，再測試該規則是否只在讀取相關檔案時出現。

「檔案存在」和「檔案已被載入」是兩件事；使用 /memory 查看載入來源，並參考 Claude Code 的工作機制說明，才能確認設定是否真的進入目前上下文。

CLAUDE.md 和 Skills 應該分別放什麼？

最簡單的判斷方式是：如果刪掉一個步驟，這段內容仍然是專案事實，就放 CLAUDE.md；如果內容本身就是一套需要照順序執行的操作，就放 Skills。

對照如下：

選項	適合保存	載入方式	跨專案共享方式	主要風險
CLAUDE.md	架構、命令、命名規範、不可違反的專案約束	通常在會話開始載入	提交到倉庫、放使用者層或由組織管理	內容過長、規則互相衝突
SKILL.md	部署、審查、測試、產生文件等重複流程	使用時按需載入，也可手動呼叫	個人層、專案層或插件層	描述不清，導致誤觸發或找不到
外部 Agent Memory	動態偏好、歷史決策、未完成任務狀態	由外部元件依專案與使用者查詢	需自行設計權限與儲存	錯誤召回、資料越界、刪除困難

Skills 通常放在 .claude/skills/<skill-name>/SKILL.md，也可以放在個人層的 ~/.claude/skills/。官方文件說明，Skill 的完整內容只有在使用時載入，因此比把整套操作手冊放進 CLAUDE.md 更節省上下文空間。(Claude Code Skills 官方文件)

例如，review-change/SKILL.md 可以只負責以下流程：

---
description: Review a code change, check tests, API compatibility, and security-sensitive files.
---

1. Read the current diff.
2. Identify affected tests.
3. Check API compatibility.
4. Report security-sensitive changes.
5. Do not modify files unless explicitly requested.

描述文字要能幫助 Claude Code 判斷何時使用。部署 Skill、個人 Skill 與插件 Skill 的作用域並不相同；若同名技能出現在不同層級，應先確認實際生效來源，避免團隊規則被個人設定意外覆蓋。

多個專案如何共享 Claude Code 配置？

共享配置不代表所有專案共享所有上下文。較穩妥的做法是採用「窄共享、寬驗證」：

• 個人層：放所有倉庫都適用的輸出偏好與工具習慣。
• 專案層：放團隊共同維護的架構、命令與品質門檻。
• 技能層：放可在多個倉庫重複使用的審查、測試或部署流程。
• 記憶層：只保存帶有專案識別碼與使用者識別碼的動態資料。

若團隊想共享 Skills，可將技能目錄納入版本控制；若只想個人使用，則放在 ~/.claude/skills/。技能檔案變更後通常可以在目前會話中反映，但首次建立原本不存在的頂層技能目錄時，可能需要重新啟動 Claude Code。

建議每個倉庫都保留一份簡短的專案 CLAUDE.md，而不是用一份全域檔案覆蓋所有細節。這樣當 Atlas-Notes 和另一個虛構專案 Cedar-Billing 使用不同測試命令時，Claude Code 看到的是當前目錄的明確規則，不必從一堆無關內容中自行猜測。

第三階段：何時接入外部 Agent Memory？

Claude Code 現在已有官方 auto memory，會將部分學習內容寫入依專案區分的記憶目錄；官方文件也說明，該記憶是機器本機儲存，不會自動跨機器或雲端環境共享。(Claude Code auto memory 官方說明)

因此，外部 Agent Memory 不是「讓 Claude Code 突然擁有永久記憶」，而是額外建立一個可查詢、可持久化、可管理的狀態層。只有在以下情況才值得接入：

• 任務需要在重啟後恢復。
• 多個倉庫需要共享同一位使用者的長期偏好。
• 多位 Agent 需要讀取經審核的歷史決策。
• 開發環境會在不同伺服器或遠端工作區之間切換。

最低限度應設計四個欄位：

project_id: atlas-notes
user_id: developer-01
memory_type: decision | preference | task_state
evidence: commit / issue / session reference

其中 project_id 防止 Cedar-Billing 的資料被 Atlas-Notes 召回；user_id 防止團隊成員的私人偏好互相污染；evidence 讓團隊可以追查某個記憶從何而來；刪除規則則確保客戶資料或已失效決策不會永久殘留。

跨專案記憶如何避免洩露程式碼資訊？答案不是只在提示詞中寫「請小心」，而是從資料模型與權限層阻斷：預設拒絕跨專案查詢、禁止記憶儲存秘密、對召回結果附加來源、為不同使用者分開命名空間，並定期檢查是否出現不屬於目前倉庫的檔案路徑。團隊可再對照 Claude Code 權限設定官方文件，將讀取、修改與命令執行的規則分開驗證。

最後階段：用固定任務驗收與遷移

每次更新 Claude Code、修改 Skills 或更換記憶元件前，先備份以下內容：

• 所有層級的 CLAUDE.md、CLAUDE.local.md。
• .claude/skills/ 與個人技能目錄。
• settings.json、權限拒絕規則與環境變數範本。
• Agent Memory 的索引、專案映射與刪除政策。

接著用同一組回歸任務驗收：

• 新會話是否讀到專案命令？
• /skills 是否列出預期技能？
• 新增或修改 Skill 後是否能正確觸發？
• 切換到另一個倉庫後，是否仍召回前一個專案的記憶？
• 重啟 Claude Code 或遠端工作區後，任務狀態是否能恢復？
• 將某筆記憶刪除後，查詢結果是否真的不再出現？

官方診斷入口可用來檢查技能、記憶、權限、設定錯誤與目前生效的設定來源；升級後應以相同測試倉庫重新執行，而不是只確認程式可以啟動。

若團隊需要長時間執行編碼 Agent，遠端工作區的硬碟持久化、使用者隔離與重啟策略會比單純增加提示詞更重要。可先參考 Zutcloud 的 Mac 遠端使用方案，再透過 Zutcloud 幫助中心確認連線與環境管理方式；實際部署前，仍應依照團隊的程式碼保密要求與權限政策驗證。

如果目前方案只是把全部歷史對話放進全域提示詞，常見缺點是上下文快速膨脹、不同倉庫規則互相污染，而且很難追蹤某項偏好或決策的來源。若改用只在本機短時間執行，則又會受到工作環境不固定、重啟後狀態遺失，以及多人共用時隔離不足等限制。對需要持續運行、多人協作或反覆重啟的情境，將三層配置放在具備持久化與隔離能力的遠端 Mac 環境，通常比臨時拼接提示詞更容易維護；Zutcloud 的 Mac mini 租用方案可作為測試遠端編碼 Agent 工作流的入口，但長期固定重負載或必須使用實體介面的團隊，仍應評估自購 Mac 或專用基礎設施。

最後可直接套用這份分配模板：

• CLAUDE.md：穩定架構、命令、團隊規範。
• Claude Code Skills：部署、測試、審查等按需流程。
• Agent Memory：個人偏好、歷史決策、可恢復任務狀態。
• 權限與備份：阻止秘密外洩，並確保重啟與升級後可以回復。

這樣配置的重點不是讓 Claude Code「記住一切」，而是讓每一類資訊只在正確的時間、以正確的作用域出現。