Claude Code 官方 .claude 目录配置指南

2026/5/4大约 7 分钟

Claude Code 官方 .claude 目录配置指南

.claude 目录配置结构概览：

一、.claude 目录核心定位

.claude 目录是 Claude Code 的核心配置载体，用于统一管理项目指令、工具权限、自定义能力、会话规则与持久记忆，是实现 AI 编码行为标准化、团队协作配置共享、个人偏好隔离的核心入口。Claude Code 启动会话时会自动读取该目录下的配置文件，无需手动重复注入项目规则与指令，大幅提升编码协作效率。

绝大多数日常场景仅需编辑 CLAUDE.md 与 settings.json 两个核心文件，其余扩展模块（skills、rules、agents 等）按需启用即可，无需全量配置。

二、双层作用域：项目级与全局级

Claude Code 采用项目级+全局级双层配置作用域，兼顾团队共享与个人定制，两者配置自动合并生效，优先级遵循项目优先、本地覆盖规则。

项目级配置
存储于代码仓库根目录的 .claude/ 文件夹，可提交至 Git 共享给团队成员，统一项目编码规范、工具命令、架构约束，确保团队内 Claude 行为一致。
全局级配置
存储于用户主目录 ~/.claude（Windows 系统对应 %USERPROFILE%.claude），属于个人专属配置，作用于所有项目，用于存放个人偏好、全局技能、插件数据等。

若配置环境变量 CLAUDE_CONFIG_DIR，所有 ~/.claude 路径将自动指向该自定义目录，满足个性化路径管理需求。

三、标准目录与文件结构

3.1 项目根目录完整结构

your-project/
├── CLAUDE.md                # 项目核心指令（会话自动加载）
├── .mcp.json                # 项目级 MCP 外部工具配置
├── .worktreeinclude         # 工作树同步忽略文件配置
└── .claude/                 # 项目级配置主目录
    ├── settings.json        # 项目基础设置
    ├── settings.local.json  # 本地个人覆盖配置（Git 忽略）
    ├── rules/               # 主题化路径门控规则
    ├── skills/              # 可复用自定义技能
    ├── commands/            # 快捷自定义命令
    ├── output-styles/       # 响应格式化规则
    ├── agents/              # 专项子代理定义
    └── agent-memory/        # 子代理持久内存

3.2 全局 ~/.claude 目录核心结构

~/.claude/
├── settings.json        # 全局默认配置
├── rules/               # 全局通用规则
├── skills/              # 全局复用技能
├── agents/              # 全局子代理
├── plugins/             # 已安装插件数据
├── history.jsonl        # 历史提示记录（向上箭头回忆）
├── stats-cache.json     # 令牌用量统计
└── projects/            # 各项目会话运行数据

四、核心配置文件详解

4.1 CLAUDE.md：项目上下文总入口

CLAUDE.md 是每次会话启动必加载的核心指令文件，相当于 Claude 的项目“入职手册”，决定其对项目的基础认知与行为范式。

加载时机：会话初始化时自动载入上下文
核心用途：声明技术栈、构建/测试/格式化命令、编码规范、架构约束、团队约定
编写规范：建议控制在 200 行内，过长文件会降低 Claude 遵循度；专项任务规则建议拆分至 skills 或 rules，避免占用全局上下文
快捷操作：会话内执行 /memory 可直接编辑；也可存放于 .claude/CLAUDE.md，保持项目根目录整洁

示例（TypeScript+React 项目）

# Project conventions
## Commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`
## Stack
- TypeScript strict mode
- React 19 纯函数组件
## Rules
- 仅具名导出，禁用默认导出
- 测试文件与源码同级：foo.ts → foo.test.ts
- API 路由统一返回 { data, error } 结构