.claude/ 資料夾的結構解析

CLAUDE.md、自訂命令、技能、Agent 和權限的完整指南，以及如何正確設定它們。

---

大多數 Claude Code 使用者將 .claude 資料夾視為一個黑盒子。他們知道它存在。他們看過它出現在他們的專案根目錄中。但他們從未打開過它，更不用說了解其中每個檔案的作用了。

這是一個錯失的機會。

.claude 資料夾是控制 Claude 在您的專案中行為的中心。它包含您的指令、您的自訂命令、您的權限規則，甚至 Claude 跨會話的記憶。一旦您了解了什麼內容位於何處以及為何存在，您就可以將 Claude Code 配置成您的團隊所需的方式。

本指南將帶您了解該資料夾的完整結構，從您每天都會使用的檔案到您設定一次就忘記的檔案。

兩個資料夾，而非一個

在深入探討之前，有一件事值得事先了解：實際上存在兩個 .claude 目錄，而不是一個。

第一個位於您的專案內部，第二個位於您的家目錄中：

專案層級資料夾包含團隊配置。您將其提交到 git。團隊中的每個人都會獲得相同的規則、相同的自訂命令、相同的權限策略。

全域 ~/.claude/ 資料夾包含您的個人偏好設定和本機狀態，例如會話歷史記錄和自動記憶。

CLAUDE.md：Claude 的操作手冊

這是整個系統中最重要的檔案。當您啟動 Claude Code 會話時，它讀取的第一個檔案就是 CLAUDE.md。它會將其直接載入到系統提示中，並在整個對話中牢記在心。

簡而言之：無論您在 CLAUDE.md 中寫什麼，Claude 都會遵循。

如果您告訴 Claude 總是在實作之前撰寫測試，它就會這麼做。如果您說「絕不使用 console.log 進行錯誤處理，一律使用自訂的 logger 模組」，它每次都會遵守。

在您的專案根目錄中放置 CLAUDE.md 是最常見的設定。但您也可以在 ~/.claude/CLAUDE.md 中放置一個用於適用於所有專案的全域偏好設定，甚至可以在子目錄中放置一個用於資料夾特定規則。Claude 會讀取所有這些檔案並將它們結合。

CLAUDE.md 中實際應包含的內容

大多數人要麼寫太多，要麼寫太少。以下是有效的方法。

撰寫：

• 建置、測試和 lint 命令 (npm run test, make build, etc.)

• 關鍵架構決策（「我們使用帶有 Turborepo 的 monorepo」）

• 不明顯的陷阱（「TypeScript 嚴格模式已開啟，未使用的變數是錯誤」）

• 導入慣例、命名模式、錯誤處理風格

• 主要模組的檔案和資料夾結構

不要撰寫：

• 任何屬於 linter 或格式化程式配置的內容

• 您可以直接連結的完整文件

• 解釋理論的長篇段落

將 CLAUDE.md 保持在 200 行以下。超過該長度的檔案會開始佔用太多上下文，而 Claude 的指令遵循度實際上會下降。

這是一個簡潔但有效的範例：

# Project: Acme API

## Commands
npm run dev          # Start dev server
npm run test         # Run tests (Jest)
npm run lint         # ESLint + Prettier check
npm run build        # Production build

## Architecture
- Express REST API, Node 20
- PostgreSQL via Prisma ORM
- All handlers live in src/handlers/
- Shared types in src/types/

## Conventions
- Use zod for request validation in every handler
- Return shape is always { data, error }
- Never expose stack traces to the client
- Use the logger module, not console.log

## Watch out for
- Tests use a real local DB, not mocks. Run `npm run db:test:reset` first
- Strict TypeScript: no unused imports, ever

這大約是 20 行。它為 Claude 提供了在此程式庫中高效工作所需的一切，而無需不斷澄清。

CLAUDE.local.md 用於個人覆寫設定

有時您有專屬於您而非整個團隊的偏好設定。也許您偏好不同的測試執行器，或者您希望 Claude 始終使用特定模式打開檔案。

在您的專案根目錄中建立 CLAUDE.local.md。Claude 會與主要的 CLAUDE.md 一起讀取它，並且它會自動被 git 忽略，因此您的個人調整永遠不會進入程式庫。

rules/ 資料夾：可擴展的模組化指令

CLAUDE.md 對於單一專案來說效果很好。但一旦您的團隊成長，您最終會得到一個 300 行的 CLAUDE.md，沒有人維護，也沒有人理會。

rules/ 資料夾解決了這個問題。

.claude/rules/ 內部每個 Markdown 檔案都會自動與您的 CLAUDE.md 一起載入。您無需一個巨大的檔案，而是可以按關注點拆分指令：

.claude/rules/
├── code-style.md
├── testing.md
├── api-conventions.md
└── security.md

每個檔案都保持專注且易於更新。負責 API 慣例的團隊成員編輯 api-conventions.md。負責測試標準的人編輯 testing.md。沒有人會互相干擾。

真正的力量來自於路徑範圍規則。在規則檔案中添加一個 YAML 前置資料區塊，它只會在 Claude 處理匹配檔案時啟用：

---
paths:
  - "src/api/**/*.ts"
  - "src/handlers/**/*.ts"
---
# API Design Rules

- All handlers return { data, error } shape
- Use zod for request body validation
- Never expose internal error details to clients

當 Claude 編輯 React 元件時，它不會載入此檔案。它只會在處理 src/api/ 或 src/handlers/ 內部時載入。沒有 paths 欄位的規則會在每個會話中無條件載入。

一旦您的 CLAUDE.md 開始感到擁擠，這就是正確的模式。

commands/ 資料夾：您的自訂斜線命令

開箱即用，Claude Code 具有內建的斜線命令，例如 /help 和 /compact。commands/ 資料夾讓您可以添加自己的命令。

您放入 .claude/commands/ 的每個 Markdown 檔案都會變成一個斜線命令。

名為 review.md 的檔案會建立 /project:review。名為 fix-issue.md 的檔案會建立 /project:fix-issue。檔案名稱就是命令名稱。

這是一個簡單的範例。建立 .claude/commands/review.md：

---
description: Review the current branch diff for issues before merging
---
## Changes to Review

!`git diff --name-only main...HEAD`

## Detailed Diff

!`git diff main...HEAD`

Review the above changes for:
1. Code quality issues
2. Security vulnerabilities
3. Missing test coverage
4. Performance concerns

Give specific, actionable feedback per file.

現在在 Claude Code 中運行 /project:review，它會自動將實際的 git diff 注入到提示中，然後 Claude 才會看到它。!反引號語法會執行 shell 命令並嵌入輸出。這就是這些命令真正有用而非僅僅是儲存的文字的原因。

傳遞參數給命令

使用 $ARGUMENTS 在命令名稱後傳遞文字：

---
description: Investigate and fix a GitHub issue
argument-hint: [issue-number]
---
Look at issue #$ARGUMENTS in this repo.

!`gh issue view $ARGUMENTS`

Understand the bug, trace it to the root cause, fix it, and write a
test that would have caught it.

運行 /project:fix-issue 234 會將問題 234 的內容直接輸入到提示中。

個人命令與專案命令

.claude/commands/ 中的專案命令會被提交並與您的團隊共享。對於您希望在所有專案中都可用的命令，請將它們放入 ~/.claude/commands/ 中。這些命令會改為顯示為 /user:command-name。

一個有用的個人命令可以是：每日站立會議助手、用於根據您的慣例產生提交訊息的命令，或快速安全掃描。

skills/ 資料夾：隨需可重複使用的工作流程

您現在知道命令是如何運作的。技能表面上看起來相似，但觸發方式本質上不同。在我們進一步探討之前，這裡先區分一下：

技能是 Claude 可以自行調用的工作流程，無需您輸入斜線命令，當任務與技能的描述匹配時。命令等待您。技能則監控對話並在適當時機採取行動。

每個技能都位於其自己的子目錄中，並帶有一個 SKILL.md 檔案：

.claude/skills/
├── security-review/
│   ├── SKILL.md
│   └── DETAILED_GUIDE.md
└── deploy/
    ├── SKILL.md
    └── templates/
        └── release-notes.md

SKILL.md 使用 YAML 前置資料來描述何時使用它：

---
name: security-review
description: Comprehensive security audit. Use when reviewing code for
  vulnerabilities, before deployments, or when the user mentions security.
allowed-tools: Read, Grep, Glob
---
Analyze the codebase for security vulnerabilities:

1. SQL injection and XSS risks
2. Exposed credentials or secrets
3. Insecure configurations
4. Authentication and authorization gaps

Report findings with severity ratings and specific remediation steps.
Reference @DETAILED_GUIDE.md for our security standards.

當您說「審查此 PR 以查找安全問題」時，Claude 會讀取描述，識別它匹配，並自動調用該技能。您也可以使用 /security-review 明確呼叫它。

與命令的關鍵區別：技能可以將支援檔案與其捆綁在一起。上面 @DETAILED_GUIDE.md 的參考引入了一個詳細文件，該文件就位於 SKILL.md 旁邊。命令是單一檔案。技能是套件。

個人技能位於 ~/.claude/skills/ 中，並可在您的所有專案中使用。

agents/ 資料夾：專業子 Agent 角色

當一個任務足夠複雜，需要一個專門的專家時，您可以在 .claude/agents/ 中定義一個子 Agent 角色。每個 Agent 都是一個 Markdown 檔案，擁有自己的系統提示、工具存取權限和模型偏好：

.claude/agents/
├── code-reviewer.md
└── security-auditor.md

以下是 code-reviewer.md 的樣子：

---
name: code-reviewer
description: Expert code reviewer. Use PROACTIVELY when reviewing PRs,
  checking for bugs, or validating implementations before merging.
model: sonnet
tools: Read, Grep, Glob
---
You are a senior code reviewer with a focus on correctness and maintainability.

When reviewing code:
- Flag bugs, not just style issues
- Suggest specific fixes, not vague improvements
- Check for edge cases and error handling gaps
- Note performance concerns only when they matter at scale

當 Claude 需要進行程式碼審查時，它會在自己的獨立上下文視窗中生成此 Agent。該 Agent 完成其工作，壓縮發現，並回報。您的主會話不會被數千個 token 的中間探索內容弄得雜亂無章。

tools 欄位限制了 Agent 可以做什麼。安全審計師只需要 Read、Grep 和 Glob。它沒有寫入檔案的權限。這種限制是有意的，並且值得明確說明。

model 欄位讓您可以使用更便宜、更快的模型用於專注任務。Haiku 能夠很好地處理大多數唯讀探索。將 Sonnet 和 Opus 保留給真正需要它們的工作。

個人 Agent 位於 ~/.claude/agents/ 中，並可在所有專案中使用。

settings.json：權限和專案配置

.claude/ 內部的 settings.json 檔案控制著 Claude 允許和不允許做什麼。您可以在此定義 Claude 可以執行哪些工具、可以讀取哪些檔案，以及在執行某些命令之前是否需要詢問。

完整的檔案如下所示：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Read",
      "Write",
      "Edit"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

以下是每個部分的作用。

$schema 行啟用 VS Code 或 Cursor 中的自動完成和行內驗證。請務必包含它。

允許清單包含無需 Claude 確認即可運行的命令。對於大多數專案，一個好的允許清單涵蓋：

• Bash(npm run *) 或 Bash(make *)，以便 Claude 可以自由運行您的腳本

• Bash(git *) 用於唯讀 git 命令

• Read、Write、Edit、Glob、Grep 用於檔案操作

拒絕清單包含無論如何都會被完全阻止的命令。一個合理的拒絕清單會阻止：

• 破壞性 shell 命令，例如 rm -rf

• 直接網路命令，例如 curl

• 敏感檔案，例如 .env 和 secrets/ 中的任何內容

如果某個內容既不在允許清單也不在拒絕清單中，Claude 會在繼續之前詢問。這種中間地帶是有意的。它為您提供了一個安全網，而無需預先預測所有可能的命令。

settings.local.json 用於個人覆寫設定

與 CLAUDE.local.md 的想法相同。建立 .claude/settings.local.json 用於您不想提交的權限變更。它會自動被 git 忽略。

全域 ~/.claude/ 資料夾

您不常與此資料夾互動，但了解其中內容很有用。

~/.claude/CLAUDE.md 會載入到每個 Claude Code 會話中，跨所有專案。這是放置您的個人程式撰寫原則、偏好風格或任何您希望 Claude 記住的內容的好地方，無論您在哪個程式庫中。

~/.claude/projects/ 儲存每個專案的會話記錄和自動記憶。Claude Code 在工作時會自動為自己儲存筆記：它發現的命令、觀察到的模式、架構洞察。這些會跨會話持續存在。您可以使用 /memory 瀏覽和編輯它們。

~/.claude/commands/ 和 ~/.claude/skills/ 儲存跨所有專案可用的個人命令和技能。

您通常不需要手動管理這些。但了解它們的存在在 Claude 似乎「記住」了您從未告訴過它的東西時，或者當您想清除專案的自動記憶並重新開始時，會很有用。

完整圖景

以下是所有內容如何結合在一起：

your-project/
├── CLAUDE.md                  # Team instructions (committed)
├── CLAUDE.local.md            # Your personal overrides (gitignored)
│
└── .claude/
    ├── settings.json          # Permissions + config (committed)
    ├── settings.local.json    # Personal permission overrides (gitignored)
    │
    ├── commands/              # Custom slash commands
    │   ├── review.md          # → /project:review
    │   ├── fix-issue.md       # → /project:fix-issue
    │   └── deploy.md          # → /project:deploy
    │
    ├── rules/                 # Modular instruction files
    │   ├── code-style.md
    │   ├── testing.md
    │   └── api-conventions.md
    │
    ├── skills/                # Auto-invoked workflows
    │   ├── security-review/
    │   │   └── SKILL.md
    │   └── deploy/
    │       └── SKILL.md
    │
    └── agents/                # Specialized subagent personas
        ├── code-reviewer.md
        └── security-auditor.md

~/.claude/
├── CLAUDE.md                  # Your global instructions
├── settings.json              # Your global settings
├── commands/                  # Your personal commands (all projects)
├── skills/                    # Your personal skills (all projects)
├── agents/                    # Your personal agents (all projects)
└── projects/                  # Session history + auto-memory

一個實用的入門設定

如果您從頭開始，這裡有一個運作良好的進程。

步驟 1. 在 Claude Code 中運行 /init。它會透過讀取您的專案生成一個入門級 CLAUDE.md。將其編輯為必需品。

步驟 2. 添加 .claude/settings.json，其中包含適合您技術堆疊的允許/拒絕規則。至少，允許您的運行命令並拒絕 .env 讀取。

步驟 3. 為您最常做的工作流程建立一兩個命令。程式碼審查和問題修復是很好的起點。

步驟 4. 隨著您的專案成長和 CLAUDE.md 變得擁擠，開始將指令拆分到 .claude/rules/ 檔案中。在有意義的地方按路徑設定其範圍。

步驟 5. 添加一個 ~/.claude/CLAUDE.md，其中包含您的個人偏好設定。這可能類似於「總是在實作之前撰寫型別」或「偏好函數式模式而非基於類別的模式」。

對於 95% 的專案來說，這確實是您所需要的一切。技能和 Agent 在您有值得打包的重複複雜工作流程時才會派上用場。

關鍵洞察

.claude 資料夾實際上是一個協議，用於告訴 Claude 您是誰、您的專案做什麼以及它應該遵循哪些規則。您定義得越清楚，您花在糾正 Claude 上的時間就越少，它花在做有用工作上的時間就越多。

CLAUDE.md 是您最高槓桿的檔案。首先把它弄對。其他一切都是優化。

從小處著手，邊做邊改進，並像對待專案中任何其他基礎設施一樣對待它：一旦正確設定，每天都會帶來回報。

---

到此結束！

如果您喜歡這篇文章。

找到我 → @akshay_pachaar ✔️

每天，我都會分享關於人工智慧、機器學習和氛圍程式撰寫最佳實踐的教學和見解。