跳到主要內容
maxstudioNews
AI 自動化DEV Community (Claude Code)約 16 分鐘

CLAUDE.md 實戰指南:來自 28 個 Next.js 與 NestJS 應用程式的精華範例

本文提供 Next.js 和 NestJS 應用程式的 CLAUDE.md 實用範例,旨在協助開發者為 AI 程式碼助理(如 Claude Code)提供精確的專案上下文。這些範例強調簡短、具體的檔案內容,以有效引導 AI 理解專案慣例、腳本和潛在問題,避免不必要的資訊。透過這些來自真實專案的經驗,開發者能最佳化 AI 在開發工作流程中的輔助效果。

CLAUDE.md 實戰指南:來自 28 個 Next.js 與 NestJS 應用程式的精華範例
圖片來源:DEV Community (Claude Code)

這篇文章最初發表於 Aniq UI 部落格。值得借鏡的 CLAUDE.md 範例都簡短而具體,它們精確地呈現了一個真實專案的指令、埠號和慣例,且內容遠少於 200 行,不包含任何 Claude 可以透過開啟資料夾自行學習的內容。檔案樹和依賴列表在每次會話中都會消耗上下文,卻無法讓 Claude 學到新東西。

本頁提供了四個 CLAUDE.md 範例,這些範例是根據我們交付的 28 個 Next.js 和 NestJS 應用程式的程式碼編寫而成:一個根檔案、一個 Next.js 應用程式、一個 NestJS API 以及一個用於 Codex 和 Cursor 的 AGENTS.md 檔案。每一行都附有其原因,文章結尾還提供了一個免費技能,可以從你的程式碼草擬並檢查這些檔案。

簡而言之,在儲存庫根目錄和每個應用程式資料夾中放置一個簡短的 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:

  • " /messages/ /*.json"

---

  • 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:

Share

覺得值得一看?分享給朋友。

以上為 AI 自動翻譯導讀。原文版權歸 DEV Community (Claude Code) 所有, 建議透過「閱讀原文」前往原始網站,以取得最完整資訊並支持原作者。

Newsletter

不用每天追,AI 重點每週寄給你

43 個來源、每 2 小時更新,太多看不完。電子報每週挑最值得看的幾則,附上 Max 的看法。

每週一封。Email 只用來寄電子報,每封信都能一鍵退訂。