簡而言之,在儲存庫根目錄和每個應用程式資料夾中放置一個簡短的 CLAUDE.md 檔案。應用程式檔案僅在 Claude 於該資料夾中工作時才會載入。寫下程式碼無法一眼看出的內容:確切的腳本、埠號、應用程式如何連接、可供複製的慣例檔案,以及潛在的陷阱。每個檔案的內容應保持在 200 行以下,我們的四個範例介於 34 到 43 行之間。
當沒有 CLAUDE.md 檔案時,Claude Code 會自行讀取 AGENTS.md(v2.1.277 及更高版本)。若要與 Codex 和 Cursor 共享一個檔案,請在 CLAUDE.md 檔案開頭使用 @AGENTS.md。
免費的 nextjs-claude-md 技能會讀取你的專案,然後檢查結果中的每個指令和路徑。想要這些檔案所依據的專案嗎?我們的 SaaS 啟動套件 Northstack 包含一個網站、一個工作區儀表板和一個 NestJS API,支援英文和阿拉伯文,並提供完整的從右到左佈局。
完整堆疊套件售價 149 美元,或網站 39 美元、儀表板 49 美元、API 單獨 99 美元。請參閱 Northstack SaaS 啟動套件或瀏覽所有範本。
什麼內容屬於 CLAUDE.md?Anthropic 將 CLAUDE.md 描述為一個地方,用於存放那些你原本需要在每次會話中重複解釋的內容。Claude 在每次會話開始時將其作為上下文讀取,而非強制配置,因此一條可被檢查的指令勝過模糊的描述:「執行 yarn typecheck」優於「測試你的變更」。最佳實踐頁面進一步縮小了範圍。
保留用於確認工作的指令、程式碼容易誤導的地方、儲存庫中未記錄的決策,以及任何你已修正過兩次的問題。省略架構導覽和資料夾佈局,因為文件說明 Claude 會自行讀取儲存庫。搜尋結果首頁上的許多範例都是為虛構專案編寫,而非取自真實專案。我們範例中的每一行都指明了真實的腳本、真實的複製檔案或真實的陷阱,並且每個檔案都通過了針對其描述程式碼運行的檢查器。
你可以從 /init 開始,它會從你的程式碼庫中編寫第一個 CLAUDE.md 檔案,或者在檔案存在時提出改進建議。設定 CLAUDE_CODE_NEW_INIT=1 後,它會詢問要設定哪些檔案(CLAUDE.md、技能、掛鉤),並在寫入前顯示建議。之後,文件說明,大部分工作就是刪除多餘的行。
CLAUDE.md 檔案的存放位置和載入時機:
託管政策:macOS 上為 /Library/Application Support/ClaudeCode/CLAUDE.md,Linux 上為 /etc/claude-code/CLAUDE.md。由組織設定。
使用者:家目錄中 .claude 資料夾內的 CLAUDE.md。你的偏好設定,適用於所有專案。
專案:./CLAUDE.md 或 ./.claude/CLAUDE.md。提交並共享。
本地:./CLAUDE.local.md。你針對單一專案的筆記,不納入 Git 管理。
在你啟動 Claude 的資料夾中,以及其上層的每個資料夾中的檔案都會在啟動時載入。它們是合併而非覆蓋的,因此最接近你的檔案會最後讀取。如果兩個檔案的規則衝突,Claude 可能會遵循其中任何一個,因此一條規則應僅存在於一個地方。子資料夾中的 CLAUDE.md 檔案僅在 Claude 讀取、寫入或編輯該資料夾中的檔案時才會載入。
這就是為什麼我們的範例按應用程式劃分:根檔案保持簡短,儀表板的規則在 Claude 開啟儀表板檔案時才載入,而 API 會話則不會攜帶這些規則。
像 @AGENTS.md 這樣的行會匯入另一個檔案,最多可深入四層,但不會儲存上下文,因為被匯入的檔案會隨同引用它的檔案一起載入。.claude 資料夾中 rules 資料夾內的規則檔案可以包含一個路徑列表,並且僅在 Claude 觸及匹配檔案時才會載入。這個範例保護了 Northstack 兩個前端的訊息檔案:
```
--- paths:
---
- Every key exists in both en.json and ar.json of the same namespace.
- A new namespace file is listed in website/src/i18n/request.ts (website) or dashboard/src/config/dashboardNamespaces.ts (dashboard), or it never loads.
```
要查看載入了哪些內容,請運行 /context all 並查看「Memory files」下方。CLAUDE.md 中的 HTML 註解在 Claude 讀取前會被移除,這使其成為維護人員撰寫筆記的免費空間。
我們如何編寫這些 CLAUDE.md 範例:一個腳本遍及 28 個應用程式。我們編寫了一個小型唯讀 Node.js 腳本 facts.mjs,它讀取每個應用程式的 package.json、.env.example 中的名稱、其資料夾、訊息檔案和配置。
我們將其運行在我們銷售的 12 個儲存庫上:共 28 個應用程式,其中 19 個使用 Next.js 16,9 個使用 NestJS 10 到 12。只有當程式碼支援時,規則才會被納入範例。
在 2026 年 11 月 14 日,該腳本發現:28 個 package.json 檔案中沒有一個包含版本範圍。每個依賴、解析和覆蓋都是精確的。所有 28 個應用程式都使用 Yarn 4,並且每個都有一個 .env.example(總共 376 個變數名稱)。
所有 19 個 Next.js 應用程式都使用 next-intl,訊息檔案位於 messages/<namespace>/<locale>.json,支援英文和阿拉伯文,包含 [locale] 片段和 src/proxy.ts:共 640 個訊息檔案,分屬 158 個命名空間。
19 個應用程式中有 16 個將端點保留在 src/lib/api 中,並透過 src/services 中的 TanStack Query 鉤子讀取它們。所有 19 個應用程式都使用 react-hook-form 和 zod 建構表單。
在 6,969 個元件檔案中:3,467 個邏輯側邊類別(ms-、start-、text-start)和 189 個實體類別(ml-、left-)。這 189 個類別中有許多是定位類別,例如 left-1/2,在兩個方向上讀取方式相同。
所有 9 個 NestJS API 都在 /api 下回應,帶有全域白名單的 ValidationPipe,並且僅在開發環境中同步 schema。9 個應用程式中有 8 個沒有 migrations 資料夾。28 個應用程式中沒有一個有測試腳本。
19 個 Next.js 應用程式中有 17 個將型別檢查命名為 typecheck,一個命名為 type-check,一個沒有。
最後一行很重要。一個 CLAUDE.md 檔案如果說「運行測試」,但在專案中沒有測試腳本,則會在每次會話中將 Claude 導向一個失敗的指令。我們的範例說明沒有測試套件,並指明了現有的檢查。
這是 Northstack 原始碼的實際輸出:
$ node facts.mjs .
Project: northstack
Apps: 3 ( 2 Next.js, 1 NestJS )
Instruction files at the root: none
## back-end (nest, northstack-backend)
versions: @nestjs/core 12.3.3, typescript 5.9.3
package manager: yarn@4.8.1, node ^22.13.0 || >= 24.11.0
scripts: build, format, start, dev, start:debug, start:prod, lint, typeorm, seed, seed:prod, schema, schema:prod, admin:create, admin:create:prod, reset, drop, remove:demo, export:mock
port: 8000
env example: .env.example, 54 names
versions not pinned exactly: none
agent files in this app: none
global prefix: api ; ValidationPipe: global, whitelist ; ORM: typeorm
synchronize: configService.get ( 'NODE_ENV' ) === 'development' ; migrations folder: none ; modules: 22
## dashboard (next, northstack-dashboard)
versions: next 16.4.5, react 19.3.1, typescript 5.9.3, tailwindcss 4.3.4, next-intl 4.14.9
package manager: yarn@4.8.1, node >= 22.9.0
scripts: dev, build, start, remove:mock, lint, typecheck, remove:demo
port: 3031
env example: .env.example, 6 names, 5 NEXT_PUBLIC_
versions not pinned exactly: none
agent files in this app: none
app router: src/app, [ locale ] segment ; proxy/middleware: src/proxy.ts
next config: next.config.js, agentRules false
src folders: app, components, config, features, fonts, hooks, layouts, lib, providers, services, store, styles, types
i18n: next-intl, messages/ < namespace > / < locale > .json, locales ar/en ( RTL locale present ) , 8 namespaces
data layer: src/lib/api ( 31 entries ) ; TanStack Query yes ; services with hooks/: 26
forms: react-hook-form + zod + @hookform/resolvers
side classes in 419 files: 303 logical ( ms-, ps-, start-, text-start... ) , 1 physical ( ml-, pl-, left-, text-left... )
## website (next, northstack-website)
versions: next 16.4.5, react 19.3.1, typescript 6.0.3, tailwindcss 4.3.4, next-intl 4.14.9
package manager: yarn@4.8.1, node >= 22.9.0
scripts: dev, build, start, lint, typecheck, remove:demo, remove:mock
port: 3030
env example: .env.example, 9 names, 7 NEXT_PUBLIC_
versions not pinned exactly: none
agent files in this app: none
app router: src/app, [ locale ] segment ; proxy/middleware: src/proxy.ts
next config: next.config.ts, agentRules false
src folders: app, components, config, content, features, fonts, hooks, i18n, lib, services, styles
i18n: next-intl, messages/ < namespace > / < locale > .json, locales ar/en ( RTL locale present ) , 10 namespaces
data layer: src/lib/api ( 5 entries ) ; TanStack Query yes ; services with hooks/: 2
forms: react-hook-form + zod + @hookform/resolvers
side classes in 168 files: 147 logical ( ms-, ps-, start-, text-start... ) , 0 physical ( ml-, pl-, left-, text-left... )
CLAUDE.md 範例 1:Next.js 和 NestJS 產品的根目錄。根檔案會在儲存庫中任何地方啟動的每個會話中載入。它包含三個應用程式共享的內容:它們的位置、如何運行和檢查它們、它們如何連接,以及任何應用程式都不能違反的規則。共 41 行,2,075 個字元。
# Northstack
Three apps in one repository. Each has its own package.json, yarn.lock and .env.example, so run every command inside the app's folder.
- website/ : Next.js 16 public site, port 3030
- dashboard/ : Next.js 16 workspace dashboard and platform admin, port 3031
- back-end/ : NestJS 12 API, port 8000, every route under /api``
## Run
- Yarn 4 through Corepack ( corepack enable once). Not npm, not pnpm.
- All three at once: docker compose up --build in this folder.
- Without Docker, the API first: cd back-end && yarn seed && yarn dev , ready when http://localhost:8000/api/health answers.
- Then cd dashboard && yarn dev and cd website && yarn dev .
## Check your work
- Frontends: cd dashboard && yarn typecheck && yarn lint , the same in website/ .
- API: cd back-end && yarn build && yarn lint . It has no typecheck script.
- There is no test suite: typecheck, lint and build are the checks.
## How the apps connect
- The frontends call the API at NEXT_PUBLIC_API_BASE_URL , which ends in /api .
- A frontend on a new address goes in CORS_ORIGIN in back-end/.env.example , or every browser call to the API fails.
- NEXT_PUBLIC_* values are compiled into the bundle: restart yarn dev after changing one, and never put a secret in one. Provider keys live in the API only.
- With NEXT_PUBLIC_API_BASE_URL empty, a frontend runs on its own sample data in src/lib/mock/ . Keep that mode working.
## Rules for all three apps
- Exact versions in every package.json: