不少人刚用 Claude Code 时，只写一个 CLAUDE.md 就开跑。
前期没问题，项目一复杂就容易乱：文档越来越长、规则到处都是、脚本堆着没人敢改。
这篇讲一套够用、能长期维护的配置方法。
先抓住一个核心：分两层
Claude 配置本质上就两件事：
- 它要知道什么（指导）
- 它能做什么（控制）
对应到文件：
| 文件 | 解决的问题 | 性质 |
|---|---|---|
CLAUDE.md | 这个项目是什么、怎么协作 | 指导 |
.claude/settings.json | 什么操作允许，什么不允许 | 控制 |
这两个先稳定，后面的目录再往上加。
一个实用目录（团队项目）
your-project/
├── CLAUDE.md # 项目主指令（共享）
├── CLAUDE.local.md # 个人覆盖（不提交）
└── .claude/
├── settings.json # 控制层：权限、钩子、项目行为
├── settings.local.json # 个人控制层（不提交）
├── rules/ # 模块化规则
├── hooks/ # 自动化脚本
├── commands/ # 可复用提示词工作流
├── skills/ # 打包的复杂工作流（按需）
└── agents/ # 专用子代理角色（按需）
别急着一次建全。后面我会给你“按阶段加层”的路径。
一、先把地基打好：CLAUDE.md + settings.json
CLAUDE.md 里放什么？
建议只放全局且稳定的信息：
- 技术栈与核心依赖
- 项目结构和职责边界
- 常用开发命令（测试、格式化、迁移等）
- 全局编码约定与禁区
- 团队协作方式（语言、输出风格、决策偏好）
示例（FastAPI 项目）：
# Customer Insights API
## Stack
- FastAPI / PostgreSQL / SQLAlchemy / Pytest
## Structure
- `app/api/` 路由定义
- `app/services/` 业务逻辑
- `app/models/` ORM 模型
- `app/schemas/` 请求与响应 Schema
## Commands
- `pytest` 运行测试
- `alembic upgrade head` 执行迁移
- `ruff check . && ruff format .` 检查与格式化
## Conventions
- 所有请求体使用 Pydantic Schema 验证
- 路由处理器保持精简，业务逻辑放在 services 层
- 不在 API 响应中暴露内部异常细节
settings.json 里放什么？
这里是权限和行为控制层，常见内容：
- Claude 允许执行的命令范围
- 敏感文件访问限制（如
.env） - 钩子配置
- 项目级行为策略（如是否允许某些自动操作）
一句话：CLAUDE.md 负责“怎么做事”，settings.json 负责“能做什么”。
二、别什么都往 CLAUDE.md 里塞
最常见错误：把所有规范都塞进一个文件。
正确做法是分层：
CLAUDE.md：全局指导（项目概览、协作原则、通用约束）.claude/rules/：专项规则（按领域拆分）
适合拆分到 rules/ 的原则：
CLAUDE.md已经明显变长，维护困难- 前后端/数据任务有不同规范
- 不同模块由不同负责人维护
- 某些规则变更频率高
拆分示例：
.claude/rules/
├── frontend.md # UI 组件规范、状态管理原则
├── backend-api.md # API 端点规则、验证要求、分页约定
├── testing.md # 测试编写与运行规范
└── data-pipelines.md # 批处理任务与定时任务约定
拆分收益：
CLAUDE.md保持可读- 单条规则变更不影响整份大文档
- 各模块可由对应负责人独立维护
三、从“说”到“做”：hooks/ 与 commands/
1) hooks/：自动执行的动作
hooks 适合做流程防护和质量保障，例如：
- 拦危险操作
- 自动格式化
- 强制流程校验（比如某阶段跑测试）
.claude/hooks/
├── block-dangerous-commands.sh
├── format-edits.sh
└── run-tests-before-stop.sh
示例（格式化编辑文件）：
#!/usr/bin/env bash
# 从 hook 事件输入中读取文件路径并执行格式化
jq -r '.tool_input.file_path' | xargs ruff format
2) commands/：可复用提示词工作流
commands 不自动执行，它是“高频任务模板库”：
- 审查 Pull Request
- 补测试
- 生成发布说明
- 排查 Bug
.claude/commands/
├── review-pr.md
├── fix-bug.md
├── write-tests.md
└── prepare-release-notes.md
示例（review-pr.md）：
# review-pr
审查当前变更，重点关注：
- 正确性
- 遗漏的边界情况
- API 契约变更
- 测试覆盖缺口
按以下结构输出：
1. 严重问题
2. 中等风险问题
3. 改进建议
你可以把它理解成四层：
| 层级 | 职责 | 性质 |
|---|---|---|
CLAUDE.md | 解释项目和协作原则 | 指导 |
rules/ | 细化专项规范 | 指导 |
hooks/ | 自动执行检查/防护 | 执行 |
commands/ | 复用任务模板 | 执行 |
四、skills/ 与 agents/：按需升级，不要预建
这两层很强，但不是必须一开始就上。
1) 什么时候从 commands 升级到 skills
满足以下条件再考虑：
- 一个流程包含多个步骤（通常超过 3 步）
- 需要配套模板、文档或清单
- 会长期重复使用（例如每周多次）
.claude/skills/
└── release-prep/
├── SKILL.md
└── release-template.md
2) agents/ 用于角色化任务
当你需要 Claude 以固定角色处理专项任务时再引入：
.claude/agents/
├── code-reviewer.md
├── security-auditor.md
└── docs-writer.md
简单决策：
commands/ -> 轻量复用任务（单文件）
skills/ -> 多步骤、带模板的打包流程（目录化）
agents/ -> 需要稳定角色视角的专项任务（角色文件）
原则：能用 commands 解决，就先不要上 skills。
五、团队与个人配置：一定要分开
这是最容易被忽略、但最影响可维护性的部分。
| 层级 | 位置 | 内容 | 提交到 Git |
|---|---|---|---|
| 项目共享 | CLAUDE.md, .claude/settings.json, rules/, hooks/ 等 | 团队统一标准 | 是 |
| 项目本地覆盖 | CLAUDE.local.md, .claude/settings.local.json | 个人在该项目中的偏好 | 否 |
| 全局个人 | ~/.claude/ | 跨项目的个人习惯与模板 | 否 |
判断标准：
- 能让团队协作更一致的，放项目共享层
- 只反映个人习惯的，放 local 或
~/.claude/
六、可直接复用的“全局 CLAUDE.md 骨架”
下面这份可以直接改名填空使用：
## 关于我
[你的名字/身份/职业背景]。
我用 Claude Code 做 [用途1] 和 [用途2]。
## 思维原则
所有决策从问题本质出发，不因惯例照搬。
给我真实判断：方案有问题直接指出，发现更好路径直接说。
## 约束先行
新项目先写 CLAUDE.md，新目录先定结构约定（命名、归档、清理规则）。
已有规范先遵守；要改规范，先改文档再改实践。
## 沟通方式
- 默认中文，代码/命令/变量名用英文
- 结论先行，再给理由
- 遇到模糊需求，先给最合理方案，再问是否调整
## 自主边界（命中后必须先问）
- 删除文件/目录或改写 git 历史
- 修改 .env、密钥、token、CI/CD 配置
- 数据库 schema 变更或数据迁移
- git push / rebase / reset --hard / 强制推送
- 安装新的全局依赖或修改系统配置
- 公开发布（部署生产、发布包、发文章）
## 通用工程纪律
- 改完主动跑验证（命令见项目 CLAUDE.md）
- 不通过“注释报错/绕过校验”来伪修复
- 密钥、token、密码不进代码、不进 commit、不进日志
- 大改动先给方案，确认后实施
说明：建议保持精简，优先保留高约束、高复用信息。内容越长，执行一致性越容易下降。
七、常见错误与修正
| 常见错误 | 后果 | 修正方式 |
|---|---|---|
把所有规则塞进 CLAUDE.md | 文件臃肿、难维护 | 全局留顶层，专项移入 rules/ |
过早创建 skills/、agents/ | 空结构增加认知负担 | 有明确需求再建 |
| 把个人偏好写进共享配置 | 团队配置失真 | 个人偏好放 local 或 ~/.claude/ |
文件命名模糊（如 misc.md） | 无法判断用途 | 用描述性命名 |
| 废弃工作流文件长期留存 | 无法判断哪些还有效 | 定期清理并归档 |
| 与工具配置重复维护规则 | 规则冲突、双份维护 | lint/format 规则留在工具配置，.claude/ 做协作补充 |
自查清单（配置开始膨胀时逐项检查）：
- 每个文件是否只有一个明确用途？
- 它属于共享层还是个人层？
- 它是指导、规则、脚本还是任务模板？
- 文件名是否一眼能看懂？
- 现在是否仍在使用？
八、渐进式搭建路径（最稳妥）
不要一开始追求“完整结构”，按需递进：
阶段 1：CLAUDE.md + settings.json
↓ 指令开始膨胀
阶段 2：加入 rules/
↓ 需要自动化/强制流程
阶段 3：加入 hooks/
↓ 高频任务重复出现
阶段 4：加入 commands/
↓ 工作流多步骤且长期复用
阶段 5：加入 skills/
↓ 需要稳定角色视角
阶段 6：加入 agents/
核心原则只有一句话：不为“看起来完整”而建结构，只为“降低协作成本”而加层级。
结语
高效的 .claude/ 不是“文件夹越多越高级”，而是“每个文件职责清晰、边界明确、维护成本可控”。
当你的配置具备这三个特征：
- Claude 更容易被稳定引导
- 团队协作标准更一致
- 新成员上手速度明显更快
那这套结构就真正开始发挥价值了。
