No.7

来源: https://x.com/akshay_pachaar/status/2035341800739877091

作者: Akshay 🚀 (@akshay_pachaar)

发布时间: 2026年3月21日

摘要

这是一份关于 Claude Code 配置文件夹 .claude/ 的完整指南。文章详细介绍了 CLAUDE.md、自定义命令、技能(skills)、代理(agents)和权限配置的设置方法。核心要点：.claude 文件夹是控制 Claude 在项目中的行为的控制中心，包含指令、自定义命令、权限规则和跨会话记忆。项目级配置提交到 git，全局配置 ~/.claude/ 存放个人偏好和机器本地状态。

核心内容

两个文件夹，不是一个

实际上有两个 .claude 目录：

项目级文件夹 - 存放团队配置，提交到 git
全局 ~/.claude/ 文件夹 - 存放个人偏好和机器本地状态（会话历史、自动记忆等）

CLAUDE.md：Claude 的指令手册

这是整个系统中最重要的文件。Claude Code 会话启动时，首先读取的就是 CLAUDE.md，直接加载到系统提示中，并在整个对话中保持记忆。

简单说：你在 CLAUDE.md 中写的任何东西，Claude 都会遵循。

应该写什么：

构建、测试和 lint 命令（npm run test, make build 等）
关键架构决策（"我们使用 Turborepo 的 monorepo"）
不明显的陷阱（"TypeScript 严格模式开启，未使用变量是错误"）
导入约定、命名模式、错误处理风格
主要模块的文件和文件夹结构

不应该写什么：

属于 linter 或 formatter 配置的内容
已经可以链接到的完整文档
解释理论的长段落

保持 CLAUDE.md 在 200 行以内。超过这个长度的文件会消耗太多上下文，Claude 的指令遵循度实际上会下降。

示例（约20行）：

# Project: Acme API

## Commands
npm run dev    # 启动开发服务器
npm run test   # 运行测试 (Jest)
npm run lint   # ESLint + Prettier 检查
npm run build  # 生产构建

## Architecture
- Express REST API, Node 20
- PostgreSQL via Prisma ORM
- 所有 handlers 在 src/handlers/
- 共享类型在 src/types/

## Conventions
- 在每个 handler 中使用 zod 进行请求验证
- 返回格式总是 { data, error }
- 永远不要向客户端暴露堆栈跟踪
- 使用 logger 模块，而不是 console.log

## Watch out for
- 测试使用真实本地数据库，不是 mock。先运行 `npm run db:test:reset`
- 严格 TypeScript：不允许未使用的导入

CLAUDE.local.md：个人覆盖

有时你有一个只针对你个人的偏好，不是整个团队的。创建 CLAUDE.local.md 在项目根目录，Claude 会 alongside 主 CLAUDE.md 读取它，并且它会自动被 gitignore，所以你的个人调整永远不会进入仓库。

rules/ 文件夹：可扩展的模块化指令

CLAUDE.md 对单个项目很有效。但一旦团队壮大，你会得到一个 300 行的 CLAUDE.md，没人维护，大家都忽略。

rules/ 文件夹解决了这个问题。

.claude/rules/ 中的每个 markdown 文件都会自动 alongside 你的 CLAUDE.md 加载。

按关注点拆分指令：

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

每个文件保持专注且易于更新。拥有 API 约定的团队成员编辑 api-conventions.md。拥有测试标准的编辑 testing.md。没人互相踩脚。

路径限定规则：添加 YAML frontmatter 块，只在 Claude 处理匹配文件时激活：

---
paths:
  - "src/api/**/*.ts"
  - "src/handlers/**/*.ts"
---
# API Design Rules
- 所有 handlers 返回 { data, error } 格式
- 使用 zod 进行请求体验证
- 永远不要向客户端暴露内部错误详情

Claude 在编辑 React 组件时不会加载这个文件。只在它在 src/api/ 或 src/handlers/ 中工作时加载。没有 paths 字段的规则无条件加载，每个会话都加载。

commands/ 文件夹：自定义斜杠命令

开箱即用，Claude Code 有内置斜杠命令如 /help 和 /compact。commands/ 文件夹让你添加自己的。

你放入 .claude/commands/ 的每个 markdown 文件都变成一个斜杠命令。

review.md 创建 /project:review
fix-issue.md 创建 /project:fix-issue

文件名就是命令名。

示例：.claude/commands/review.md

---
description: 在合并前审查当前分支差异中的问题
---
## Changes to Review
!`git diff --name-only main...HEAD`

## Detailed Diff
!`git diff main...HEAD`

审查上述更改：
1. 代码质量问题
2. 安全漏洞
3. 缺失的测试覆盖
4. 性能问题

给出具体的、可操作的反馈，每个文件都要有。

现在运行 /project:review，它会自动将真实的 git diff 注入到 Claude 看到的提示之前。! 反引号语法运行 shell 命令并嵌入输出。这就是让这些命令真正有用而不只是保存文本的原因。

传递参数：使用 $ARGUMENTS 传递命令名后的文本：

---
description: 调查并修复 GitHub issue
argument-hint: [issue-number]
---
查看这个仓库中的 issue #$ARGUMENTS。
!`gh issue view $ARGUMENTS`
理解 bug，追溯到根本原因，修复它，并写一个本可以捕获它的测试。

运行 /project:fix-issue 234 会将 issue 234 的内容直接输入到提示中。

个人 vs 项目命令：

项目命令在 .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 frontmatter 描述何时使用它：

---
name: security-review
description: 全面安全审计。在审查代码漏洞、部署前或用户提到安全时使用。
allowed-tools: Read, Grep, Glob
---
分析代码库的安全漏洞：
1. SQL 注入和 XSS 风险
2. 暴露的凭证或密钥
3. 不安全的配置
4. 认证和授权缺口

报告发现，带严重性评级和具体修复步骤。
参考 @DETAILED_GUIDE.md 了解我们的安全标准。

当你说"审查这个 PR 的安全问题"时，Claude 读取描述，识别匹配，并自动调用技能。你也可以用 /security-review 显式调用它。

关键区别：技能可以捆绑支持文件。上面提到的 @DETAILED_GUIDE.md 引用拉入一个与 SKILL.md 相邻的详细文档。命令是单个文件。技能是包。

个人技能放在 ~/.claude/skills/，在所有项目中可用。

agents/ 文件夹：专业化子代理角色

当任务复杂到需要专门专家时，你可以在 .claude/agents/ 中定义子代理角色。每个代理是一个 markdown 文件，有自己的系统提示、工具访问和模型偏好：

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

示例：code-reviewer.md

---
name: code-reviewer
description: 专家代码审查员。在审查 PR、检查 bug 或在合并前验证实现时主动使用。
model: sonnet
tools: Read, Grep, Glob
---
你是一个专注于正确性和可维护性的高级代码审查员。审查代码时：
- 标记 bug，不只是风格问题
- 建议具体修复，不是模糊的改进
- 检查边界情况和错误处理缺口
- 只在规模相关时指出性能问题

当 Claude 需要做代码审查时，它会在自己的隔离上下文窗口中生成这个代理。代理完成工作，压缩发现，并报告回来。你的主会话不会被数千 token 的中间探索弄得杂乱。

tools 字段限制代理能做什么。安全审计员只需要 Read、Grep 和 Glob。它不应该写文件。这个限制是故意的，值得明确说明。

model 字段让你为专注任务使用更便宜、更快的模型。Haiku 处理大多数只读探索很好。把 Sonnet 和 Opus 留给真正需要它们的工作。

个人代理放在 ~/.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 中的自动完成和内联验证。总是包含它。
allow 列表 - 包含 Claude 无需询问即可运行的命令。对于大多数项目，一个好的 allow 列表覆盖：
- Bash(npm run *) 或 Bash(make *) 让 Claude 自由运行你的脚本
- Bash(git *) 用于只读 git 命令
- Read, Write, Edit, Glob, Grep 用于文件操作
deny 列表 - 包含无论什么情况都被完全阻止的命令。一个合理的 deny 列表阻止：
- 破坏性 shell 命令如 rm -rf
- 直接网络命令如 curl
- 敏感文件如 .env 和 secrets/ 中的任何内容

如果某物不在任一列表中，Claude 会在继续前询问。这个中间地带是故意的。它给你一个安全网，而不必预先预见每一个可能的命令。

settings.local.json：与 CLAUDE.local.md 相同的想法。创建 .claude/settings.local.json 用于你不想提交的权限更改。它会自动被 gitignore。

全局 `~/.claude/` 文件夹

你不经常与这个文件夹交互，但知道里面有什么很有用。

~/.claude/CLAUDE.md - 加载到每个 Claude Code 会话中，跨所有项目。适合你的个人编码原则、偏好风格或任何你想让 Claude 记住的东西，无论你在哪个仓库。
~/.claude/projects/ - 按项目存储会话记录和自动记忆。Claude Code 在工作时自动保存笔记给自己：它发现的命令、观察到的模式、架构洞察。这些跨会话持久化。你可以用 /memory 浏览和编辑它们。
~/.claude/commands/ 和 ~/.claude/skills/ - 存放跨所有项目可用的个人命令和技能。

你通常不需要手动管理这些。但知道它们存在很有用，当 Claude 似乎"记住"你从未告诉过它的东西，或者当你想清除项目的自动记忆并重新开始时。

完整图景

your-project/
├── CLAUDE.md              # 团队指令（已提交）
├── CLAUDE.local.md        # 你的个人覆盖（gitignored）
│
└── .claude/
    ├── settings.json      # 权限 + 配置（已提交）
    ├── settings.local.json # 个人权限覆盖（gitignored）
    │
    ├── commands/          # 自定义斜杠命令
    │   ├── review.md      # → /project:review
    │   ├── fix-issue.md   # → /project:fix-issue
    │   └── deploy.md      # → /project:deploy
    │
    ├── rules/             # 模块化指令文件
    │   ├── code-style.md
    │   ├── testing.md
    │   └── api-conventions.md
    │
    ├── skills/            # 自动调用工作流
    │   ├── security-review/
    │   │   └── SKILL.md
    │   └── deploy/
    │       └── SKILL.md
    │
    └── agents/            # 专业化子代理角色
        ├── code-reviewer.md
        └── security-auditor.md

~/.claude/
├── CLAUDE.md              # 你的全局指令
├── settings.json          # 你的全局设置
├── commands/              # 你的个人命令（所有项目）
├── skills/                # 你的个人技能（所有项目）
├── agents/                # 你的个人代理（所有项目）
└── projects/              # 会话历史 + 自动记忆

实用入门设置

如果你从零开始，这里有一个有效的进阶路径：

步骤 1：在 Claude Code 中运行 /init。它会通过读取你的项目生成一个入门 CLAUDE.md。将其编辑到精华。

步骤 2：添加 .claude/settings.json，包含适合你技术栈的 allow/deny 规则。至少允许你的运行命令，并拒绝 .env 读取。

步骤 3：为你最常做的工作流创建一两个命令。代码审查和 issue 修复是好的起点。

步骤 4：随着项目增长和 CLAUDE.md 变得拥挤，开始将指令拆分到 .claude/rules/ 文件中。在有意义的地方按路径限定它们。

步骤 5：添加一个 ~/.claude/CLAUDE.md，包含你的个人偏好。这可能是"总是在实现前写类型"或"偏好函数模式而不是基于类的"。

对于 95% 的项目，这真的就是你所需要的。技能和代理在有值得打包的重复复杂工作流时才出现。

关键洞察

.claude 文件夹实际上是一个协议，用于告诉 Claude 你是谁、你的项目做什么、它应该遵循什么规则。你定义得越清楚，你纠正 Claude 的时间就越少，它做有用工作的时间就越多。

CLAUDE.md 是你最高杠杆的文件。 先把它做好。其他一切都是优化。

从小处开始，边做边完善，像对待项目中任何其他基础设施一样对待它：一旦设置好，每天都会带来回报。

收藏时间：2026-03-24 07:16

.claude/ 文件夹解剖：完整配置指南

AI 核心摘要

摘要

核心内容

两个文件夹，不是一个

CLAUDE.md：Claude 的指令手册

CLAUDE.local.md：个人覆盖

rules/ 文件夹：可扩展的模块化指令

commands/ 文件夹：自定义斜杠命令

skills/ 文件夹：按需可重用工作流

agents/ 文件夹：专业化子代理角色

settings.json：权限和项目配置

全局 `~/.claude/` 文件夹

完整图景

实用入门设置

关键洞察

AI 核心摘要

摘要

核心内容

两个文件夹，不是一个

CLAUDE.md：Claude 的指令手册

CLAUDE.local.md：个人覆盖

rules/ 文件夹：可扩展的模块化指令

commands/ 文件夹：自定义斜杠命令

skills/ 文件夹：按需可重用工作流

agents/ 文件夹：专业化子代理角色

settings.json：权限和项目配置

全局 ~/.claude/ 文件夹

完整图景

实用入门设置

关键洞察

全局 `~/.claude/` 文件夹