.claude/ 项目配置教程
CLAUDE.md、自定义命令、技能、代理及权限的完整指南，以及如何正确进行配置。
⭕
.claude 文件夹是 Claude 在您的项目中行为方式的控制中心。它存储着您的指令、自定义命令、权限规则，甚至包括 Claude 在各会话之间的记忆。一旦您清楚各项内容的存放位置及其原因，便可以将 Claude Code 配置为完全符合您团队的需求。
Claude Code 存在两级 .claude 目录，分工明确：
项目级.claude：纳入Git管理，存储团队统一配置，实现全员共享规则、自定义指令与权限策略；
全局~/.claude/：存放本机个人偏好、会话历史、本地记忆等私有配置，不参与代码提交。
✨核心配置文件 CLAUDE.md 优先级极高：启动会话时Claude会优先加载该文件内容并入系统提示词，全程生效，文件内定义的规范将被持续执行。
✨支持多层级配置叠加：可在项目根目录、全局目录、子目录分别建立CLAUDE.md，所有规则自动合并生效。
CLAUDE.md 撰写规范：
✅ 适合写入：构建/测试/校验脚本、核心架构方案、开发隐性约束、代码导入与命名规范、错误处理准则、目录结构约定。
❌ 不适合写入：格式化/代码检查工具已有配置、可外部跳转查阅的完整文档、长篇理论阐述。
⚠️ 关键约束：文件尽量控制在200行以内；篇幅过长会挤占上下文窗口，降低模型遵循指令的效果。
代码块
Markdown
# 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
.claude/文件夹的五层构成
CLAUDE.local.md（个人覆盖配置）
项目根目录下的 CLAUDE.local.md 为个人私有规则文件，可写入仅适用于自身的偏好（测试工具、文件打开习惯等）。文件自动纳入 .gitignore，不会提交代码仓库；加载时和公共 CLAUDE.md 合并，实现个人规则覆盖团队规范。
.claude/rules/：模块化规则管理
解决单份 CLAUDE.md 臃肿难维护问题。.claude/rules/ 下所有 Markdown 文件会自动并入全局指令；支持按领域拆分规范（API、测试规范等），由对应负责人独立维护。配套路径作用域规则，实现不同目录差异化约束。
代码块
Haskell
钩子 Hooks：确定性流程管控
普通 CLAUDE.md 指令属于模型软性约束，执行存在不确定性；钩子是事件驱动处理器，在指定工作节点强制运行 Shell 脚本，行为可预测。
配置存放于 .claude/settings.json 的 hooks 字段：
•
会话启动时快照配置；触发时接收 JSON 载荷，依靠退出码控制流程：
◦
0：执行成功，继续运行
◦
1：发生错误，仅告警、不阻塞流程
◦
2：阻断后续操作，返回错误信息交由 Claude 自主修正
支持事件：PreToolUse（工具执行前安全校验）、PostToolUse（执行后代码格式化/静态检查）、Stop（任务收尾质量门禁）、UserPromptSubmit、通知、会话启停等；可通过正则匹配限定生效工具（文件编辑、Shell 命令等），不填则匹配全部工具。
代码块
Python
.claude/
├── settings.json # hooks config lives here, under the "hooks" key
└── hooks/ # your hook scripts (convention, not required)
├── bash-firewall.sh # PreToolUse: blocks dangerous commands
├── auto-format.sh # PostToolUse: runs formatter on edited files
└── enforce-tests.sh # Stop: ensures tests pass before finishing
技能 skills/：可复用自主工作流
技能为可封装的标准化业务流程，Claude 会实时理解对话上下文，任务匹配描述时自动调用，适合封装高频复杂工作流。
代码块
Haskell
.claude/skills/
├── security-review/
│ ├── SKILL.md
│ └── DETAILED_GUIDE.md
└── deploy/
├── SKILL.md
settings.json：项目权限总控
.claude/settings.json 承载项目核心配置：钩子定义、工具黑白名单、文件读写权限、高危命令二次确认策略。推荐基础配置：开放命令执行权限，禁止直接读取 .env 密钥文件。
CLAUDE.md 要素全貌
代码块
Python
your-project/
├── CLAUDE.md # Team instructions (committed)
├── CLAUDE.local.md # Your personal overrides (gitignored)
│
└── .claude/
├── settings.json # Permissions, hooks, config (committed)
├── settings.local.json # Personal permission overrides (gitignored)
│
├── hooks/ # Hook scripts referenced by settings.json
│ ├── bash-firewall.sh # PreToolUse: block dangerous commands
│ ├── auto-format.sh # PostToolUse: format files after edits
│ └── enforce-tests.sh # Stop: ensure tests pass before finishing
│
推荐的入门方案
执行 /init 自动生成初始 CLAUDE.md，删减冗余内容，只保留核心规范；
创建 settings.json，配置工具权限、文件访问策略；
预置高频自定义指令，优先从代码评审、缺陷修复场景切入；
项目迭代、主配置文件膨胀后，将规则拆分至 .claude/rules/，并按需配置路径生效范围；
在全局目录 ~/.claude/CLAUDE.md 写入通用个人编码偏好。
适用边界：绝大多数项目完成以上配置即可满足需求；仅存在大量重复复杂流程时，再引入技能模块做进阶封装。