先说结论：Claude Code 本身已经足够好用，但要让它的战斗力翻倍，关键在于学会摆弄 .claude/ 这个目录。你可以把它理解为你和 Claude 之间的一份"秘密协议"——项目规范、自定义工具、工作流自动化，全都在这里落地。

目录结构总览

your-project/
├── .claude/
│   ├── settings.json              # 权限、MCP、环境变量配置
│   ├── settings.local.json        # 本地私有配置（不提交 git）
│   ├── rules/                     # 自动加载的规则文件（补充 CLAUDE.md）
│   │   ├── security.md
│   │   └── style.md
│   ├── commands/                  # 斜杠命令（简单指令）
│   │   ├── commit.md
│   │   └── test.md
│   └── skills/                    # 斜杠命令（复杂工作流）
│       ├── review.md
│       └── deploy.md
└── CLAUDE.md                      # 项目说明书（自动加载）

CLAUDE.md — 项目说明书

CLAUDE.md 是整个系统的核心文件。每次启动 Claude Code，它都会自动读取这个文件，无需额外调用。

不妨把它理解为一份"写给 AI 的 README"——你希望 Claude 始终知道的那些信息，无论是项目背景还是避坑指南，都放在这里。

写什么？

# 项目名称
## 技术栈
- React 18 + TypeScript + Vite
- 包管理器：pnpm（不要用 npm 或 yarn）
- 样式：Tailwind CSS
## 常用命令
pnpm dev         # 启动开发服务器（端口 3000）
pnpm build       # 构建生产版本
pnpm lint        # 代码检查
## 代码规范
- 组件文件：PascalCase（Button.tsx）
- 工具函数：camelCase（formatDate.ts）
- 新页面必须使用 React.lazy() 懒加载
- 禁止使用 any 类型
## 架构说明
- components/common/     → 通用基础组件
- components/features/   → 业务功能组件
- pages/                 → 页面（懒加载）
## 注意事项
- 提交前必须通过 pnpm lint
- 不要修改 tailwind.config.js 的颜色变量

最佳实践

• 写"不要做什么"往往比"要做什么"更有效——Claude 的默认行为已经挺好了，主要靠 CLAUDE.md 来纠偏
• 保持简洁，超过 200 行会被截断，重点突出才管用
• 用代码块展示命令，Claude 会直接复用这些命令
• 说明项目特殊约定——常规项目不用多说，但你项目里的那些"特殊规则"一定要写明白

.claude/rules/ — 自动加载的补充规则

rules/ 目录里的所有 .md 文件都会自动加载，和 CLAUDE.md 一样不用手动调用。

和 CLAUDE.md 有什么区别？

这里最大的优势其实是拆分——当规则多起来的时候，按主题分文件管理，比把所有内容都堆在 CLAUDE.md 里要清晰得多，维护起来也更顺手。

示例：security.md

# Security Rules
- 所有用户输入必须经过验证和转义，防止 XSS
- 禁止在客户端代码中硬编码 API Key 或密码
- SQL 查询必须使用参数化查询，禁止字符串拼接
- 敏感数据（密码、token）禁止写入 console.log
- fetch 请求必须处理错误状态码

示例：style.md

# Code Style Rules
- 函数超过 50 行必须拆分
- 禁止嵌套超过 3 层的 if/else，使用提前返回
- React 组件 props 必须用 interface 定义类型
- 禁止使用魔法数字，提取为具名常量
- 注释只写"为什么"，不写"是什么"

何时用 rules/，何时用 CLAUDE.md？

• CLAUDE.md 更适合放项目介绍、技术栈、目录结构、常用命令这些偏"说明"的内容
• rules/ 则适合放强制性的约束和禁令，偏"规则"，尤其是团队需要统一强调的东西

当然，两者内容都会被 Claude 读取，实际上写在哪里效果是一样的，按团队习惯选就行。

.claude/commands/ — 轻量斜杠命令

commands/ 目录专门存放那些简单、单一职责的指令。文件名就是命令名：commit.md 对应 /commit。

示例：/commit

# Commit
分析暂存区的改动，生成符合 Conventional Commits 规范的提交信息并提交。
## 步骤
1. 运行 `git diff --staged` 查看改动
2. 根据改动类型选择 type：feat / fix / style / refactor / docs / chore
3. 用中文写 subject，不超过 50 字
4. 执行 git commit

示例：/test

# Test
运行测试套件并报告结果。
- 执行 `pnpm test`
- 如有失败，分析原因并给出修复建议
- 不要自动修改测试文件，先询问用户

调用方式

在对话框直接输入：

/commit
/test
/commit 只提交 src/ 目录的改动

命令名后面还能直接接自然语言说明，Claude 会结合命令定义和你的补充来执行。灵活度很高。

.claude/skills/ — 复杂工作流

skills/ 和 commands/ 在功能上完全一样，但按惯例用于更复杂、多步骤的工作流。

示例：/review（代码审查）

# Code Review
对当前改动进行全面的代码审查。
## 审查维度
### 1. 正确性
- 逻辑是否正确？边界条件是否处理？
- 有无潜在的 null/undefined 错误？
### 2. 安全性
- 是否存在 XSS、SQL 注入等风险？
- 用户输入是否经过验证？
### 3. 性能
- 是否有不必要的重渲染？
- 大列表是否做了虚拟化？
### 4. 可维护性
- 函数是否单一职责？
- 命名是否清晰？
## 输出格式
用 Markdown 表格列出问题，包含：文件、行号、问题描述、严重程度（高/中/低）、修复建议。

示例：/deploy（部署流程）

# Deploy
执行完整的部署流程。
1. 运行 `pnpm lint` — 有错误则停止，不自动修复
2. 运行 `pnpm build` — 确认构建成功
3. 运行 `pnpm test` — 测试通过才继续
4. 询问用户确认：是否部署到生产环境？
5. 执行部署命令
6. 验证部署结果，访问健康检查接口

commands/ vs skills/：怎么选？

二者功能完全相同，只是约定俗成的分工：

所以不用纠结，选哪个目录都行，甚至统一用一个更好。

.claude/settings.json — 权限与配置

这个文件控制 Claude 可以执行哪些操作，以及配置 MCP Server、环境变量等。

权限配置分为两个文件：

• settings.json — 提交 git，团队共享的基础权限
• settings.local.json — 不提交 git，个人本地权限（API Key、私有工具）

权限语法

"Bash(pnpm *)"                    # 允许所有 pnpm 命令
"Bash(git add:*)"                  # 允许 git add（: 后为参数通配）
"WebFetch(domain:github.com)"      # 只允许访问指定域名
"Skill(commit)"                    # 允许调用指定 skill
"mcp__ide__getDiagnostics"         # 允许调用指定 MCP 工具

实际配置示例（settings.local.json）

以下是一个真实前端项目的配置：

{
  "permissions": {
    "allow": [
      "Bash(pnpm install:*)",
      "Bash(pnpm dev:*)",
      "Bash(pnpm build:*)",
      "Bash(pnpm lint:*)",
      "Bash(pnpm add:*)",
      "Bash(pnpm tsc:*)",
      "Bash(git add:*)",
      "Bash(git commit:*)",
      "Bash(git push:*)",
      "Bash(git rm:*)",
      "Bash(git mv:*)",
      "Bash(npx playwright:*)",
      "WebSearch",
      "WebFetch(domain:api.github.com)",
      "mcp__ide__getDiagnostics",
      "mcp__context7__query-docs",
      "Skill(update-config)"
    ]
  }
}

配置建议

• 最小权限原则：只开放项目实际用到的命令，不要写 "Bash(*)" 一口气放开所有权限
• 危险命令不授权：像 rm -rf、git push --force、git reset --hard 这类操作，让 Claude 每次都弹确认最好
• MCP 工具按需开放：用哪个 MCP 就开放哪个工具，不用的不授权
• 本地 vs 团队：CI/CD 相关权限放 settings.json，个人工具和 Key 放 settings.local.json

完整工作流示例

假设你的项目配置了这样的 .claude/ 目录：

.claude/
├── settings.json
├── commands/
│   ├── commit.md  →  /commit
│   └── lint.md    →  /lint
└── skills/
    ├── review.md  →  /review
    └── deploy.md  →  /deploy

那么一个典型的开发工作流就会变成这样：

你：帮我实现用户登录功能
Claude：（读取 CLAUDE.md 了解项目规范，按规范实现代码）
你：/review
Claude：（按 review.md 的维度进行代码审查，输出问题列表）
你：/lint
Claude：（运行 pnpm lint，修复发现的问题）
你：/commit
Claude：（分析改动，生成规范提交信息，执行 git commit）

整个过程行云流水，Claude 就像一个熟悉项目的老队友，你只需要给出简单的斜杠命令，它就能按你的配置完成一系列操作。

快速上手模板

最后，给你一个最小化模板，直接复制到你的项目里就能用：

CLAUDE.md

# 项目名
## 包管理器
pnpm（禁止使用 npm/yarn）
## 常用命令
pnpm dev / pnpm build / pnpm lint
## 规范
- TypeScript，禁止 any
- 组件 PascalCase，工具函数 camelCase
- 提交前必须通过 lint

.claude/commands/commit.md

# Commit
查看 git diff --staged，生成 Conventional Commits 格式提交信息（中文 subject），执行提交。

.claude/commands/lint.md

# Lint
运行 pnpm lint，自动修复可修复的问题，不可修复的列出并解释原因。

小结

花 30 分钟把这些文件配置好，Claude Code 就能真正理解你的项目，像一个熟悉代码库的老队友一样高效地工作。这 30 分钟的投入，回报率相当可观。