CLAUDE 配置说明

CLAUDE.md 配置文件说明

文件位置及作用

文件	位置	作用	是否提交
`CLAUDE.md`	项目根目录	项目级文档，AI 每次启动自动读取	✅
`.claudeignore`	`.claude/.claudeignore`	排除无关文件，类似 `.gitignore`	✅
`.claude/settings.json`	`.claude/settings.json`	团队共享配置：权限规则 + Hooks 注册	✅
`.claude/settings.local.json`	`.claude/settings.local.json`	个人本地配置：权限白名单	❌
`.claude/commands/`	`.claude/commands/`	项目级自定义命令（如 `/full-review`）	✅
`.claude/skills/`	`.claude/skills/`	项目级技能包，团队共享	✅
`.claude/rules/`	`.claude/rules/`	编码规范，按需加载	✅
`.claude/hooks/`	`.claude/hooks/`	自动化脚本，事件触发执行	✅
`.claude/memory/`	`.claude/memory/`	自动记忆：MEMORY.md + 分类记忆	❌
`.claude/mcp.json`	`.claude/mcp.json`	MCP 服务器配置	✅

1. CLAUDE.md

位置: 项目根目录

作用: 为 Claude Code 提供项目核心信息，包括构建命令、架构结构、配置说明

配置内容详解

markdown 复制代码

# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

标准前缀，标识这是 Claude Code 的引导文档

项目说明

markdown 复制代码

## 项目说明

**技术栈**: Spring Boot 3.5.14 + MyBatis Plus + MySQL 8.0 + Java 18

项目技术栈概述

核心命令

bash 复制代码

mvn clean install -DskipTests

跳过测试编译所有模块

bash 复制代码

mvn test

运行所有测试

bash 复制代码

mvn spring-boot:run

启动 Spring Boot 应用

项目结构

plain 复制代码

rice-grain (parent)
├── common/     # 通用工具类、常量、枚举
├── dao/        # 数据访问层 (mapper/)
├── service/    # 业务逻辑层
└── controller/ # Web 层，REST API 入口 (应用主入口)

多模块 Maven 项目结构

规范

markdown 复制代码

- 接口遵循 RESTful 风格
- 统一使用 `Result<T>` 包装返回值
- 分页使用 `PageRequest` 对象

开发和设计规范

2. .claudeignore

位置 : .claude/.claudeignore

作用: 排除无关文件，让 Claude Code 忽略构建产物、IDE 配置等

配置示例

plain 复制代码

# Maven 构建产物
target/
.mvn/
*.class
*.jar
*.war

# 日志文件
*.log

# IntelliJ IDEA
*.iml
*.iws
*.ipr
.idea/

# VS Code
.vscode/

# Eclipse/STS
.classpath
.project
.settings/
.apt_generated
.factorypath
.springBeans
.sts4-cache

# NetBeans
nbproject/
nbbuild/
dist/
nbdist/
.nb-gradle/
build/

# 其他
node_modules/
npm-debug.log
yarn-error.log

配置说明

模式	说明
`target/`	Maven 构建输出目录
`*.class`	Java 编译产物
`*.jar`	打包文件
`*.log`	日志文件
`.idea/`	IntelliJ IDEA 配置
`.vscode/`	VS Code 配置

3. settings.json

位置 : .claude/settings.json

作用: 团队共享配置，包括权限规则、Hooks 注册、MCP 服务器配置

配置示例

json 复制代码

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "memory": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  },
  "permissions": {
    "allow": [
      "Bash(mvn *)",
      "Bash(npm run dev)",
      "Bash(npx *)",
      "WebFetch(domain:github.com)",
      "Bash(timeout 3 node \"~/.claude/plugins/claude-hud/dist/index.js\")"
    ]
  },
  "hooks": {
    "beforeToolUse": {
      "Bash(rm * *)": ".claude/hooks/dangerous-command-check.sh",
      "Bash(git push --force)": ".claude/hooks/pre-push-check.sh"
    },
    "afterToolUse": {
      "Write(*.java)": ".claude/hooks/java-format.sh"
    },
    "beforeFinalResponse": {
      "*": ".claude/hooks/unit-test-check.sh"
    }
  }
}

配置说明

mcpServers

服务器	说明
`context7`	实时库/框架文档查询
`memory`	跨会话持久化记忆

permissions.allow

规则	说明
`Bash(mvn *)`	允许所有 Maven 命令
`Bash(npm run dev)`	允许启动开发服务器
`WebFetch(domain:github.com)`	允许访问 GitHub

hooks

事件	触发时机
`beforeToolUse`	工具使用前
`afterToolUse`	工具使用后
`beforeFinalResponse`	最终响应前

4. settings.local.json

位置 : .claude/settings.local.json

作用: 个人本地配置，不提交到版本库

配置示例

json 复制代码

{
  "permissions": {
    "allow": [
      "Bash(whoami)",
      "Bash(cd *)",
      "Bash(ls *)",
      "Bash(cat *)",
      "Read(*)",
      "Glob(*)",
      "Grep(*)"
    ]
  },
  "theme": "dark",
  "fontFamily": "JetBrains Mono"
}

配置说明

配置	说明
`permissions.allow`	个人权限白名单
`theme`	界面主题
`fontFamily`	字体偏好

5. commands/

位置 : .claude/commands/

作用 : 项目级自定义命令，通过 /命令名 调用

示例：full-review.md

markdown 复制代码

# /full-review

对当前分支进行全面代码审查：

1. 运行 `git diff main` 获取变更
2. 检查代码规范符合性
3. 检查潜在安全问题
4. 检查测试覆盖率
5. 生成审查报告

示例：api-doc.md

markdown 复制代码

# /api-doc

生成 API 文档：

1. 扫描所有 `@RestController` 类
2. 提取 `@RequestMapping` 路径
3. 整理参数和响应类型
4. 输出 Markdown 格式文档

可用命令列表

命令	作用
`/full-review`	全面代码审查
`/api-doc`	生成 API 文档
`/test-coverage`	分析测试覆盖率

6. skills/

位置 : .claude/skills/

作用: 项目级技能包，定义可复用的工作流程

示例：mybatis-generator.md

markdown 复制代码

---
name: mybatis-generator
description: 使用 MyBatis Plus 代码生成器创建 CRUD
---

## 步骤

1. 确认数据库连接配置
2. 选择目标表
3. 运行代码生成器
4. 生成 Entity、Mapper、Service、Controller
5. 验证生成的代码

示例：integration-test.md

markdown 复制代码

---
name: integration-test
description: 创建集成测试
---

## 步骤

1. 确定测试场景
2. 准备测试数据
3. 编写 `@SpringBootTest` 测试类
4. 使用 `@MockBean` 模拟依赖
5. 验证业务逻辑

可用技能列表

技能	作用
`mybatis-generator`	MyBatis 代码生成
`integration-test`	集成测试创建

7. rules/

位置 : .claude/rules/

作用: 编码规范，按需加载

示例：01-architecture.md

markdown 复制代码

# Architecture Rules

## 模块依赖层次

**必须严格遵守:**

controller → service → dao → common

plain 复制代码

- **controller/**: REST API 端点，禁止包含业务逻辑
- **service/**: 业务逻辑实现
- **dao/**: 数据访问层，MyBatis Mapper
- **common/**: 工具类、常量，禁止依赖其他模块

## 禁止行为

- ❌ 跨层调用（Controller 直接调用 Mapper）
- ❌ 循环依赖
- ❌ common 模块依赖业务模块

示例：02-api-design.md

markdown 复制代码

# API Design Rules

## RESTful 规范

### URL 设计
- 使用名词复数：`/api/users`
- 避免动词：使用 HTTP 方法表达操作
- 资源层级：`/api/users/{id}/orders`

### 响应格式
- 成功：`{ "code": 200, "data": T, "message": "success" }`
- 失败：`{ "code": 400, "data": null, "message": "error" }`

### 状态码
- 200: 成功
- 400: 请求参数错误
- 401: 未授权
- 403: 禁止访问
- 404: 资源不存在
- 500: 服务器内部错误

示例：03-database.md

markdown 复制代码

# Database Rules

## MyBatis Plus 规范

### Entity
- 使用 `@TableName` 指定表名
- 主键使用 `@TableId(type = IdType.AUTO)`
- 逻辑删除使用 `@TableLogic`

### Mapper
- 继承 `BaseMapper<T>`
- 自定义方法使用 XML

### 分页
- 统一使用 `PageRequest` 对象
- 返回 `Page<T>` 类型

规范文件列表

文件	作用
`01-architecture.md`	架构分层规范
`02-api-design.md`	API 设计规范
`03-database.md`	数据库规范

8. hooks/

位置 : .claude/hooks/

作用: 自动化脚本，在特定事件触发时执行

示例：dangerous-command-check.sh

bash 复制代码

#!/bin/bash
# 危险命令检查

COMMAND="$1"

if [[ "$COMMAND" == *"rm -rf"* ]]; then
    echo "⚠️  检测到危险命令：rm -rf"
    echo "请确认目标目录是否在白名单中"
    exit 1
fi

exit 0

示例：pre-push-check.sh

bash 复制代码

#!/bin/bash
# 推送前检查

echo "🔍 执行推送前检查..."

# 检查是否有未提交的更改
if ! git diff --quiet; then
    echo "⚠️  存在未暂存的更改，请先提交"
    exit 1
fi

# 运行测试
mvn test -q
if [ $? -ne 0 ]; then
    echo "⚠️  测试失败，请修复后推送"
    exit 1
fi

echo "✅ 检查通过"
exit 0

示例：java-format.sh

bash 复制代码

#!/bin/bash
# Java 代码格式化

FILE="$1"

if [[ "$FILE" == *.java ]]; then
    echo "格式化：$FILE"
    # 调用格式化脚本
fi

示例：unit-test-check.sh

bash 复制代码

#!/bin/bash
# 单元测试检查

echo "📋 检查新增代码的单元测试..."

# 检查是否有新测试类
NEW_TESTS=$(git diff --name-only HEAD~1 | grep "*Test.java" | wc -l)

if [ "$NEW_TESTS" -eq 0 ]; then
    echo "⚠️  未检测到新增测试"
fi

exit 0

Hooks 脚本列表

脚本	作用
`dangerous-command-check.sh`	危险命令拦截
`pre-push-check.sh`	推送前检查
`java-format.sh`	Java 格式化
`unit-test-check.sh`	单元测试检查

9. memory/

位置 : .claude/memory/

作用: 跨会话持久化记忆

目录结构

plain 复制代码

memory/
├── MEMORY.md           # 记忆索引
├── user/               # 用户相关记忆
│   ├── preferences.md
│   └── role.md
├── feedback/           # 反馈记忆
│   ├── coding-style.md
│   └── testing.md
├── project/            # 项目相关记忆
│   ├── milestones.md
│   └── decisions.md
└── reference/          # 引用资源
    ├── links.md
    └── documentation.md

MEMORY.md 示例

markdown 复制代码

# 记忆索引

## 用户记忆
- [preferences.md](user/preferences.md) --- 编码偏好
- [role.md](user/role.md) --- 角色信息

## 反馈记忆
- [coding-style.md](feedback/coding-style.md) --- 代码风格要求
- [testing.md](feedback/testing.md) --- 测试规范

## 项目记忆
- [milestones.md](project/milestones.md) --- 项目里程碑
- [decisions.md](project/decisions.md) --- 重要决策

## 参考资源
- [links.md](reference/links.md) --- 常用链接
- [documentation.md](reference/documentation.md) --- 文档索引

记忆类型

类型	说明
`user/`	用户偏好、角色、知识
`feedback/`	用户反馈、修正建议
`project/`	项目进度、决策、事件
`reference/`	外部资源链接

10. mcp.json

位置 : .claude/mcp.json

作用: MCP 服务器配置

配置示例

json 复制代码

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "description": "实时库/框架文档"
    },
    "memory": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "description": "持久化记忆"
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "description": "文件系统访问"
    }
  }
}

MCP 服务器列表

服务器	作用
`context7`	库/框架文档查询
`memory`	跨会话记忆
`filesystem`	文件系统访问

总结：完整文件结构

plain 复制代码

项目根目录/
├── CLAUDE.md                        # 项目说明（AI 自动读取）
├── .claudeignore                    # 排除文件
└── .claude/
    ├── settings.json                # 团队配置：权限 + Hooks
    ├── settings.local.json          # 个人配置（不提交）
    ├── mcp.json                     # MCP 服务器配置
    ├── commands/
    │   └── full-review.md           # 自定义命令
    ├── skills/
    │   ├── mybatis-generator.md     # 项目技能
    │   └── integration-test.md
    ├── rules/
    │   ├── 01-architecture.md       # 架构规范
    │   ├── 02-api-design.md         # API 规范
    │   └── 03-database.md           # 数据库规范
    ├── hooks/
    │   ├── dangerous-command-check.sh
    │   ├── pre-push-check.sh
    │   ├── java-format.sh
    │   └── unit-test-check.sh
    └── memory/
        ├── MEMORY.md
        ├── user/
        ├── feedback/
        ├── project/
        └── reference/

文档最后更新：2026-04-29