Claude Code：项目目录结构

时效说明：本文内容以 2026 年 3 月为基准。

8.1 项目目录结构一览

一个充分利用Claude Code能力的项目，目录结构大概是这样：

code

your-project/
├── CLAUDE.md                    # 团队共享的项目说明，提交到Git
├── CLAUDE.local.md              # 个人偏好覆盖，不提交Git（加入.gitignore）
└── .claude/
    ├── settings.json            # 团队共享的权限配置，提交到Git
    ├── settings.local.json      # 个人权限覆盖，不提交Git
    ├── commands/                # 自定义斜杠命令
    │   ├── review.md            # → /project:review
    │   └── fix-issue.md         # → /project:fix-issue
    ├── rules/                   # 模块化规则文件（被CLAUDE.md引用）
    │   ├── code-style.md        # 代码风格规范
    │   └── api-conventions.md   # 接口设计规范
    ├── skills/                  # 自动调用的工作流
    │   └── security-review/
    │       └── SKILL.md
    └── agents/                  # 子代理角色定义
        └── code-reviewer.md

提交到Git的文件（团队共享）：CLAUDE.md、.claude/settings.json、.claude/commands/目录。

不提交Git的文件（个人使用）：CLAUDE.local.md、.claude/settings.local.json。记得把它们加到.gitignore里。

8.2 settings.json：完整字段说明

settings.json不只是权限配置，它是Claude Code项目级配置的核心文件，控制的范围比大多数人以为的要广得多。

8.2.1 完整的settings.json结构

json

{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(mvn *)",
      "Bash(npm *)",
      "Bash(grep *)",
      "Bash(find *)",
      "Bash(cat *)",
      "Bash(ls *)",
      "Bash(echo *)",
      "WebFetch(domain:docs.spring.io)",
      "WebFetch(domain:maven.apache.org)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl * | bash *)",
      "Bash(wget * | bash *)",
      "Bash(sudo *)",
      "Bash(chmod 777 *)",
      "WebFetch(domain:*.internal-corp.com)",
      "WebFetch(domain:*.internal-infra.net)"
    ]
  },
  "env": {
    "JAVA_HOME": "/usr/local/opt/openjdk@17",
    "MAVEN_OPTS": "-Xmx2g -XX:+TieredCompilation",
    "APP_ENV": "local",
    "LOG_LEVEL": "DEBUG"
  },
  "trust": {
    "allowedDirectories": [
      "/Users/dev/projects/order-service",
      "/tmp/claude-workspace"
    ]
  },
  "model": "claude-opus-4-5",
  "maxTokens": 8192
}

下面逐个字段详细说明。

8.2.2 permissions字段

权限控制是最常用的字段。

allow数组：列出允许自动执行的操作（不需要每次确认）。支持通配符：

* 匹配任意字符（包括路径分隔符）
不加通配符表示精确匹配

json

"allow": [
  "Bash(git *)",          // 允许所有git命令
  "Bash(mvn test)",       // 只允许 mvn test，不允许 mvn deploy
  "Bash(mvn test *)",     // 允许 mvn test 和 mvn test -Dtest=xxx
  "Bash(cat src/*)",      // 只允许读取src目录下的文件
  "WebFetch(domain:docs.spring.io)"  // 只允许访问Spring官方文档
]

deny数组：列出明确禁止的操作，即使在allow里也不行（deny优先）：

json

"deny": [
  "Bash(rm -rf *)",              // 禁止递归删除
  "Bash(git push --force *)",    // 禁止强制推送
  "Bash(git push * production)", // 禁止推送到生产分支
  "Bash(mysql * -e \"DROP *\")", // 禁止删库操作
  "Bash(kubectl delete *)"       // 禁止删除K8s资源
]

实用的权限配置模板——Java后端项目：

json

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git log *)",
      "Bash(git diff *)",
      "Bash(git blame *)",
      "Bash(git show *)",
      "Bash(mvn *)",
      "Bash(grep *)",
      "Bash(find *)",
      "Bash(cat *)",
      "Bash(ls *)",
      "Bash(pwd)",
      "Bash(whoami)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push *)",
      "Bash(git reset --hard *)",
      "Bash(mvn deploy *)",
      "Bash(curl * | bash *)",
      "Bash(wget * | bash *)"
    ]
  }
}

这个配置的设计思路：允许所有"只读"操作和本地构建/测试，禁止所有"不可逆"操作（删除、强推、部署）。

8.2.3 env字段：配置环境变量

这是很多人忽视的字段。在settings.json里配置env，Claude Code在执行Bash命令时会自动注入这些环境变量。

什么时候有用：

你的项目构建需要特定的环境变量，比如JAVA_HOME指向特定版本的JDK：

json

"env": {
  "JAVA_HOME": "/usr/local/opt/openjdk@17",
  "PATH": "/usr/local/opt/openjdk@17/bin:${PATH}"
}

或者你有多个项目，每个项目用不同的本地服务端口：

json

"env": {
  "DB_HOST": "localhost",
  "DB_PORT": "3306",
  "DB_NAME": "order_dev",
  "REDIS_PORT": "6379",
  "APP_PORT": "8080"
}

注意：不要把密码和密钥放在settings.json里——这个文件要提交到Git。敏感信息放在settings.local.json里。

settings.local.json里的env配置示例（不提交Git）：

json

{
  "env": {
    "DB_PASSWORD": "your-local-password",
    "REDIS_PASSWORD": "your-redis-password",
    "JWT_SECRET": "your-dev-jwt-secret"
  }
}

8.2.4 trust字段：可信目录

trust字段控制Claude Code被允许操作的目录范围：

json

"trust": {
  "allowedDirectories": [
    "/Users/dev/projects/order-service",
    "/tmp/claude-workspace"
  ]
}

默认情况下，Claude Code只能操作启动时的项目目录及其子目录。如果你的项目依赖了项目目录外的文件（比如一个共享的配置仓库），可以用这个字段扩展允许的目录范围。

安全提醒：不要把系统目录（如 /etc、/usr）加入allowedDirectories。

8.2.5 model字段

指定这个项目使用的Claude模型：

json

"model": "claude-opus-4-5"

不同项目可以用不同模型。日常开发用能力稍弱但速度更快的模型，对代码质量要求高的关键项目用最强的模型。

8.3 commands/目录：自定义斜杠命令

.claude/commands/目录里的每个.md文件，会自动变成一个/project:文件名命令。

比如创建.claude/commands/review.md，内容如下：

markdown

请对以下改动做代码审查：

$ARGUMENTS

审查维度：
1. 是否有安全漏洞（SQL注入、XSS、权限绕过）
2. 异常处理是否完整
3. 是否有明显的性能问题
4. 是否符合项目代码规范（见CLAUDE.md）

用中文给出具体的改进建议，标注严重程度（P0/P1/P2）。

这样在对话里输入/project:review就能直接触发这个审查流程。$ARGUMENTS是一个占位符，你在命令后面跟的内容会替换进去：

code

/project:review UserController.java中新增的登录方法

Claude会把"UserController.java中新增的登录方法"代入$ARGUMENTS，然后执行审查。

8.3.1 $ARGUMENTS的高级用法

$ARGUMENTS 不仅能接收文本，还能接收文件名和路径，Claude会自动读取对应的文件内容：

markdown

# .claude/commands/add-test.md
为以下方法生成单元测试：

$ARGUMENTS

要求：
- 使用 JUnit 5 + Mockito
- 覆盖正常路径和异常路径
- 测试方法名格式：should_[预期行为]_when_[条件]
- 用 @DisplayName 加中文描述

使用时：

code

/project:add-test OrderService.java 中的 createOrder 方法

Claude会先读取OrderService.java，找到createOrder方法，然后生成针对这个方法的测试。

也可以在命令模板里设计多参数格式：

markdown

# .claude/commands/migrate.md
生成数据库迁移脚本。

目标表：$ARGUMENTS 中的第一个词
改动描述：$ARGUMENTS 中的其余内容

要求：
- 使用 Flyway 格式（V{版本号}__{描述}.sql）
- 包含回滚脚本
- 对大表的ALTER操作加 ALGORITHM=INPLACE

使用时：

code

/project:migrate orders 新增 is_deleted 软删除字段

8.3.2 实用命令示例

deploy-check.md：部署前检查清单

markdown

# .claude/commands/deploy-check.md
部署前检查，目标环境：$ARGUMENTS

请依次检查以下内容，用 [✓] 或 [✗] 标注：

## 代码质量
- [ ] 运行 `mvn test` 并确认全部通过
- [ ] 检查是否有 TODO 或 FIXME 注释未处理
- [ ] 确认没有调试代码（System.out.println、hardcoded 测试数据）

## 配置检查
- [ ] 检查 application-prod.yml 中的连接信息是否正确
- [ ] 确认环境变量在目标环境已配置
- [ ] 检查数据库迁移脚本是否需要执行

## 依赖检查
- [ ] `mvn dependency:check` 确认无高危漏洞
- [ ] 检查新增的第三方依赖是否经过安全审查

## 回滚准备
- [ ] 确认当前版本的 Git tag 已打
- [ ] 回滚步骤已记录在 DEPLOY.md 中

给出最终的部署建议：可以部署/需要先解决以下问题。

generate-changelog.md：自动生成变更日志

markdown

# .claude/commands/generate-changelog.md
根据最近的Git提交记录，生成版本变更日志。

版本范围：$ARGUMENTS（如果没有指定，使用最近20个commit）

格式要求：
## [版本号] - [日期]

### 新功能
- 功能描述（对应commit）

### Bug修复
- 修复描述（对应commit）

### 性能优化
- 优化描述

### 其他
- 其他改动

只保留有业务意义的提交，过滤掉 "fix typo"、"update readme" 等噪音提交。
用中文描述。

fix-security.md：安全漏洞修复辅助

markdown

# .claude/commands/fix-security.md
安全漏洞修复分析：$ARGUMENTS

1. 描述漏洞的危害等级和攻击向量
2. 找出代码中所有受影响的位置
3. 给出修复方案（给出修改后的代码，不要只描述）
4. 给出验证修复效果的测试方法
5. 检查修复是否引入了新的问题

修复原则：最小改动，不引入新风险。

api-doc.md：自动生成API文档

markdown

# .claude/commands/api-doc.md
为以下接口生成API文档：

$ARGUMENTS

文档格式（Markdown）：
## 接口名称

**接口地址**：[METHOD] /path

**功能描述**：

**请求参数**：
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|

**响应格式**：
```json
{
  "code": 0,
  "data": {...}
}

错误码：

错误码	说明

调用示例：

code


**code-explain.md**：代码解释（给新人用）

```markdown
# .claude/commands/code-explain.md
请解释以下代码，解释对象是Java后端新人：

$ARGUMENTS

解释要求：
1. 用通俗语言说明这段代码做了什么
2. 解释关键的设计决策（为什么这么写）
3. 指出需要特别注意的地方（容易出错、有副作用等）
4. 如果有更好的写法，顺带提一下

不需要逐行解释，重点是帮助理解整体逻辑和关键细节。

8.3.3 如何调试自定义命令

命令不工作时，按这个步骤排查：

第一步：确认文件在正确位置

bash

ls .claude/commands/
# 应该能看到你创建的 .md 文件

第二步：确认命令名称

命令名是文件名（不含扩展名）。deploy-check.md → /project:deploy-check，注意连字符。

第三步：验证$ARGUMENTS替换

先用一个最简单的命令测试：

markdown

# .claude/commands/test-cmd.md
这是一个测试命令，参数是：$ARGUMENTS

执行 /project:test-cmd hello world，看Claude是否收到了"hello world"。

第四步：检查命令模板本身

复杂的命令模板在Claude执行时可能因为歧义产生意外结果。用Ask模式先让Claude解释它理解这个命令模板的意思，确认理解正确再投入使用：

code

读一下 .claude/commands/deploy-check.md，告诉我你理解
这个命令的执行逻辑是什么。

8.4 整个.claude/目录的完整字段参考

8.4.1 目录结构和各文件的用途

code

.claude/
├── settings.json              # 核心配置：权限、环境变量、模型设置
├── settings.local.json        # 个人配置覆盖（不提交Git）
│
├── commands/                  # 自定义斜杠命令
│   └── *.md                   # 每个文件对应一个 /project:文件名 命令
│
├── rules/                     # 规则文件（被CLAUDE.md @引用）
│   └── *.md                   # 可以按主题拆分规则，避免CLAUDE.md过长
│
├── skills/                    # 技能：特定触发条件自动激活的工作流
│   └── [skill-name]/
│       └── SKILL.md           # 技能定义文件
│
└── agents/                    # 子代理定义（高级功能）
    └── *.md                   # 定义可被主代理调用的子代理

8.4.2 rules/目录：模块化CLAUDE.md

当CLAUDE.md变得很长时，可以把不同主题的规则拆分到rules/目录下，然后在CLAUDE.md里用@语法引用：

markdown

# CLAUDE.md（精简版）

## 项目概述
订单服务，负责订单全生命周期管理。

## 规范文档

@.claude/rules/code-style.md
@.claude/rules/api-conventions.md
@.claude/rules/testing-standards.md
@.claude/rules/security-checklist.md

这样CLAUDE.md保持简洁，具体规范放在独立文件里，各自维护，互不干扰。

.claude/rules/code-style.md 示例：

markdown

# 代码风格规范

## 分层架构
- Controller：只做参数校验和响应封装
- Service：核心业务逻辑，构造器注入
- Mapper：数据库操作，不含业务判断

## 命名规范
- 接口路径：全小写 + 连字符 /api/order-items
- 方法：动词+名词 createOrder、getOrderById
- 常量：大写下划线，放在Constants类

## 禁止的写法
- 禁止 @Autowired（用构造器注入）
- 禁止 double/float 存金额（用BigDecimal）
- 禁止硬编码魔法数字（用枚举或常量）

.claude/rules/security-checklist.md 示例：

markdown

# 安全规范

## 输入验证
- 所有外部输入必须用 @Valid + JSR-303 注解校验
- SQL参数必须用MyBatis #{}（不能用${}）
- 文件上传必须校验类型和大小

## 认证授权
- 所有需要登录的接口必须有 @RequiresLogin 注解
- 涉及用户数据的接口必须校验数据归属（不能只验登录）
- 管理员接口放在独立的 /admin/* 路径下，网关层面拦截

## 敏感数据
- 手机号、身份证号在日志里打印时必须脱敏
- 密码字段在响应里必须过滤掉（用 @JsonIgnore 或 DTO）
- 不要在URL参数里传Token（放在Header里）

8.4.3 skills/目录的工作方式

Skills是比commands更智能的一层——它们不需要你手动调用，当满足特定条件时会自动激活。

例如，你可以创建一个"security-review" skill，让它在Claude修改了安全相关代码时自动触发安全检查：

code

.claude/skills/security-review/SKILL.md

markdown

# Security Review Skill

## 触发条件
当以下任一条件满足时自动激活：
- 修改了 AuthController、LoginController、TokenService 等认证相关文件
- 修改了涉及SQL查询的Mapper或Service
- 新增了文件上传接口

## 执行内容
在完成代码修改后，自动运行以下检查：

1. SQL注入检查：扫描新增代码里是否有字符串拼接的SQL
2. 权限检查：确认新增的接口有对应的权限注解
3. 输入验证检查：确认外部参数有@Valid校验

## 输出格式
给出检查结论：通过 / 发现问题。
发现问题时列出具体位置和修复建议。

Skills的详细用法会在后续章节介绍，这里先了解它的位置和基本概念。

8.5 .gitignore的配置

确保正确的文件被Git忽略，在项目根目录的.gitignore里添加：

gitignore

# Claude Code 个人配置（不提交）
CLAUDE.local.md
.claude/settings.local.json

# Claude Code 缓存（自动生成，不需要提交）
.claude/cache/
.claude/tmp/

提交到Git的内容：

code

CLAUDE.md                      ✓ 提交
.claude/settings.json          ✓ 提交
.claude/commands/*.md          ✓ 提交
.claude/rules/*.md             ✓ 提交
.claude/skills/*/SKILL.md      ✓ 提交（视情况）

8.6 一个完整的配置示例

假设你要从零开始为一个Java微服务项目配置Claude Code，完整的操作流程如下：

第一步：创建目录结构

bash

mkdir -p .claude/commands .claude/rules
touch .claude/settings.json
touch CLAUDE.md CLAUDE.local.md

第二步：配置settings.json

json

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git log *)",
      "Bash(git diff *)",
      "Bash(mvn clean *)",
      "Bash(mvn test *)",
      "Bash(mvn package *)",
      "Bash(mvn spring-boot:run *)",
      "Bash(grep -r *)",
      "Bash(find . *)",
      "Bash(cat *)",
      "Bash(ls *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push *)",
      "Bash(mvn deploy *)",
      "Bash(curl * | bash *)"
    ]
  },
  "env": {
    "JAVA_HOME": "/usr/local/opt/openjdk@17",
    "MAVEN_OPTS": "-Xmx2g"
  }
}

第三步：写基础CLAUDE.md

bash

# 用 /init 生成草稿，然后手动补充重要背景
/init

编辑生成的草稿，补充"重要背景"和"不要做的事"两节。

第四步：创建常用命令

bash

# 创建代码审查命令
cat > .claude/commands/review.md << 'EOF'
对以下代码做审查：

$ARGUMENTS

关注点：安全漏洞、异常处理、性能问题、代码规范。
给出优先级标注（P0/P1/P2）和具体改进建议。
EOF

# 创建生成测试命令
cat > .claude/commands/add-test.md << 'EOF'
为以下方法生成单元测试：

$ARGUMENTS

要求：JUnit 5 + Mockito，覆盖正常路径和边界情况。
EOF

第五步：提交到Git

bash

git add CLAUDE.md .claude/settings.json .claude/commands/
git commit -m "chore: 初始化 Claude Code 配置"

第六步：把个人文件加入.gitignore

bash

echo "CLAUDE.local.md" >> .gitignore
echo ".claude/settings.local.json" >> .gitignore
git add .gitignore
git commit -m "chore: 忽略 Claude Code 个人配置文件"

到这里，你的项目就有了一个可以团队共享的Claude Code配置，每个人在克隆项目后，Claude Code就能自动读取这些配置投入工作。

到这里，你应该对Claude Code的工作机制有了比较完整的认识。接下来讲进阶的工程化集成——包括 Hooks 事件钩子、MCP 外部工具连接、Skills 和子代理。