【后端/Agent 开发】给你的项目配置一套 .claude/ 工作流：别再裸用 Claude Code 了！

文章目录

前言
- 一、这篇文章最终要做出什么效果？
- [二、`.claude/` 到底是什么？](#二、.claude/ 到底是什么？)
- [三、第一步：写一份 `CLAUDE.md`](#三、第一步：写一份 CLAUDE.md)
- [四、第二步：配置 `settings.json`，先把安全边界圈出来](#四、第二步：配置 settings.json，先把安全边界圈出来)
- [五、第三步：把规则拆到 `.claude/rules/`](#五、第三步：把规则拆到 .claude/rules/)
- - [1. 代码风格规则](#1. 代码风格规则)
  - [2. 架构边界规则](#2. 架构边界规则)
  - [3. 测试规则](#3. 测试规则)
  - [4. Git 规范](#4. Git 规范)
- [六、第四步：创建自定义命令 `/commit`](#六、第四步：创建自定义命令 /commit)
- [七、第五步：创建自定义命令 `/review`](#七、第五步：创建自定义命令 /review)
- [八、第六步：创建自定义命令 `/fix-bug`](#八、第六步：创建自定义命令 /fix-bug)
- [九、第七步：创建自定义命令 `/add-test`](#九、第七步：创建自定义命令 /add-test)
- [十、第八步：创建自定义命令 `/explain`](#十、第八步：创建自定义命令 /explain)
- [十一、一个完整示例：让 AI 在规则内完成一次小需求](#十一、一个完整示例：让 AI 在规则内完成一次小需求)
- [十二、哪些文件应该提交到 Git？](#十二、哪些文件应该提交到 Git？)
- 十三、常见问题
- - [1. `CLAUDE.md` 是不是越长越好？](#1. CLAUDE.md 是不是越长越好？)
  - [2. `commands` 和 `rules` 有什么区别？](#2. commands 和 rules 有什么区别？)
  - [3. 所有项目都需要 `.claude/` 吗？](#3. 所有项目都需要 .claude/ 吗？)
写在文后

🔥 个人主页：铁皮哥（欢迎关注）

📌 作者简介：28届校招生，后端开发/Agent 方向在学

📚 学习内容：Java、Python、计算机视觉、大语言模型、Agent开发

📝 专栏内容：从零开始的Claude Code零代码生活（持续更新中）

✨不只背八股，更想搞懂为什么这样设计

前言

很多人第一次用 Claude Code、Cursor、Copilot 这类 AI 编程工具时，都会有一种很微妙的感觉：

它确实能写代码，但不一定懂你的项目。

它知道语法，却不知道你的目录结构；它能补一个接口，却不知道你们项目的返回格式；它能帮你修 Bug，但可能顺手重构一堆无关代码；它能生成测试，但不知道项目里到底应该怎么跑测试。

于是每次开新会话，你都要重复告诉它：

这个项目用什么技术栈。
代码要放在哪个目录。
提交信息怎么写。
哪些命令可以执行。
哪些文件不要乱动。
修 Bug 的时候不要一上来重构半个项目。

时间久了就会发现，问题不一定是 AI 不够聪明，而是项目没有给它足够清晰的上下文。

所以这篇文章不聊 AI 编程的宏大叙事，也不讨论它会不会取代程序员，只做一件很具体的事：

给项目配置一套 .claude/，让 Claude Code 更懂你的项目。

一、这篇文章最终要做出什么效果？

配置完成后，我们希望在项目里可以直接使用这些命令：

bash 复制代码

/commit

让 Claude 根据当前 Git 改动生成规范的 commit message。

bash 复制代码

/review

让 Claude 按项目规则做一次代码审查。

bash 复制代码

/fix-bug

让 Claude 根据错误日志定位问题，并优先给出最小修改方案。

bash 复制代码

/add-test

让 Claude 参考项目已有测试风格，补充测试用例。

bash 复制代码

/explain

让 Claude 解释某个文件或模块的实现逻辑，适合接手旧项目或者复盘自己写过的功能。

二、`.claude/` 到底是什么？

你可以把 .claude/ 理解成项目里的 AI 配置中心。

一个比较通用的目录结构可以长这样：

text 复制代码

project-demo/
├── CLAUDE.md
├── .claude/
│   ├── settings.json
│   ├── settings.local.json
│   ├── commands/
│   │   ├── commit.md
│   │   ├── review.md
│   │   ├── fix-bug.md
│   │   ├── add-test.md
│   │   └── explain.md
│   └── rules/
│       ├── code-style.md
│       ├── architecture.md
│       ├── test.md
│       └── git.md
└── .gitignore

先简单解释一下每个文件的作用：

CLAUDE.md 是项目说明书，用来告诉 Claude：这个项目是什么、怎么启动、怎么测试、有什么开发规范。
.claude/settings.json 是项目共享配置，比如允许执行哪些命令、禁止执行哪些高风险命令。
.claude/settings.local.json 是个人本地配置，通常不建议提交到 Git。
.claude/commands/ 里放自定义命令，比如 /commit、/review、/fix-bug。
.claude/rules/ 里放拆分后的项目规则，避免所有内容都堆在 CLAUDE.md 里。

如果项目很小，其实只写一个 CLAUDE.md 就够了。但如果你经常让 AI 修改同一个项目，或者项目有固定的代码规范、测试流程、提交规范，那就很适合把这些内容沉淀到 .claude/ 里。

三、第一步：写一份 `CLAUDE.md`

CLAUDE.md 不要写成工具说明书，它更像是写给一个新同事看的项目入门文档。

一个刚接手项目的人最想知道什么？

项目是做什么的。
代码放在哪里。
怎么启动。
怎么测试。
改代码时有哪些规矩。
哪些地方不能乱碰。

这些信息，Claude Code 也同样需要。

可以先在项目根目录新建一个 CLAUDE.md：

markdown 复制代码

# 项目说明

这是一个 xxx 项目，主要用于 xxx。

## 技术栈

- 前端：React / Vue / Next.js
- 后端：Node.js / Java / Go / Python
- 数据库：MySQL / PostgreSQL / MongoDB
- 测试：Jest / JUnit / Pytest
- 包管理：npm / pnpm / Maven / Poetry

## 项目结构

- src/：主要源码
- tests/：测试代码
- docs/：项目文档
- scripts/：脚本
- config/：配置文件

## 开发规范

- 修改代码前先说明修改方案
- 不要一次性重构无关代码
- 新增功能时优先参考已有代码风格
- 修改公共方法时需要说明影响范围
- 涉及接口变更时需要同步更新文档
- 涉及数据库变更时需要说明迁移方案

## 常用命令

# 安装依赖
pnpm install

# 启动项目
pnpm dev

# 运行测试
pnpm test

# 代码检查
pnpm lint

## AI 回答偏好

* 先给思路，再给代码
* 涉及多个文件时，按文件列出改动
* 不确定时先说明风险，不要直接猜
* 优先做最小可行修改

这份文件不用一开始就写得很完美。我的建议是先写一个能用的版本，然后在后续使用 Claude Code 的过程中不断补充。

比如你发现它经常修改无关代码，就加一句：

markdown 复制代码

不要修改和当前需求无关的文件。

如果你发现它经常引入新依赖，就加一句：

markdown 复制代码

不要随意引入新依赖，除非先说明原因并得到确认。

如果你发现它经常一上来就贴代码，而不是先说方案，就加一句：

markdown 复制代码

涉及多个文件的修改，必须先列出实现方案和影响范围。

CLAUDE.md 最重要的不是长，而是具体。

像这种话其实用处不大：

text 复制代码

请写出高质量、可维护、可扩展的代码。

这句话当然没错，但它太空了。Claude 并不知道你眼里的"高质量"具体是什么。

更推荐写成这样：

text 复制代码

新增功能时优先参考已有代码风格。
不要修改无关模块。
公共 API 变更前先说明影响范围。
修复 Bug 时优先给最小修改方案。

这些规则更像真正能执行的项目约束。

四、第二步：配置 `settings.json`，先把安全边界圈出来

AI 编程工具好用归好用，但我不太建议一上来就把所有权限都放开。

尤其是一些高风险命令，比如删除文件、强制回滚、直接 push、发布 npm 包，这些最好提前限制住。

可以在 .claude/settings.json 里写一份项目共享配置：

json 复制代码

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff)",
      "Bash(git log --oneline -5)",
      "Bash(pnpm test)",
      "Bash(pnpm lint)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push *)",
      "Bash(git reset --hard *)",
      "Bash(npm publish *)"
    ]
  }
}

这里的思路很简单：

像 git status、git diff 这种只读命令，可以允许。

像 pnpm test、pnpm lint 这种验证类命令，也可以允许。

但是 rm -rf、git reset --hard、git push、npm publish 这类高风险操作，最好默认禁止。

如果有一些只适合你个人电脑的配置，比如本地路径、个人偏好、临时命令，可以放到：

text 复制代码

.claude/settings.local.json

然后在 .gitignore 里忽略它：

gitignore 复制代码

.claude/settings.local.json

团队共享的是项目规范和工作流，个人本地配置就不要提交了。

五、第三步：把规则拆到 `.claude/rules/`

刚开始用的时候，很多人会把所有规则都写进 CLAUDE.md。

项目小的时候问题不大，但规则一多，CLAUDE.md 很容易变成一篇很长的说明书。后面想改某一类规则，也不太好找。

所以我更喜欢把长期规则拆出来，放到 .claude/rules/ 目录里：

text 复制代码

.claude/rules/
├── code-style.md
├── architecture.md
├── test.md
└── git.md

1. 代码风格规则

新建文件：

text 复制代码

.claude/rules/code-style.md

内容可以这样写：

markdown 复制代码

# 代码风格

- 优先参考项目已有代码风格
- 不要引入不必要的新依赖
- 不要为了一个小功能创建复杂抽象
- 命名要表达业务含义
- 删除代码前先确认没有被其他地方使用
- 不要为了"看起来高级"写过度封装
- 如果有多种实现方式，优先选择项目里已经在用的方式

这里我特意加了一句"不要为了看起来高级写过度封装"。

因为 AI 有时候确实会这样：一个很简单的小需求，它给你抽象出一堆接口、策略、工厂，看起来很工程化，实际项目里反而增加理解成本。

2. 架构边界规则

新建文件：

text 复制代码

.claude/rules/architecture.md

内容示例：

markdown 复制代码

# 架构规则

- 不要跨层直接调用内部实现
- 不要把业务逻辑写进工具函数
- 不要在一个文件里堆太多职责
- 公共模块变更需要说明影响范围
- 新增模块时先说明目录设计
- 修改核心流程前先解释当前流程
- 不确定边界时先提问，不要直接猜

这类规则适合所有项目，不管你是写前端、后端、脚本工具，还是独立开发项目。

本质上就是一句话：不要让 AI 因为当前任务，把项目结构改乱。

3. 测试规则

新建文件：

text 复制代码

.claude/rules/test.md

内容示例：

markdown 复制代码

# 测试规则

- 新增核心逻辑时需要补充测试
- 修复 Bug 时优先补回归测试
- 测试命名要能看出业务场景
- 优先复用项目已有测试工具
- 不要依赖真实外部服务
- 测试失败时先解释失败原因，再尝试修复

我觉得这部分很有用。

很多时候 AI 能写功能，但它不会主动补测试。就算补了测试，也可能不符合你项目里的风格。提前写清楚之后，至少它会先去看已有测试，再决定怎么写。

4. Git 规范

新建文件：

text 复制代码

.claude/rules/git.md

内容示例：

markdown 复制代码

# Git 规范

commit message 使用以下格式：

type(scope): message

type 可选：

- feat：新增功能
- fix：修复问题
- refactor：重构
- docs：文档
- test：测试
- chore：杂项

示例：

feat(auth): 新增登录态校验
fix(order): 修复订单金额计算错误

拆分规则的好处是，后面想新增规范会很方便。

比如你想加数据库规范，就新建一个 database.md。想加接口规范，就新建一个 api.md。想加前端组件规范，就新建一个 component.md。

不要试图一开始就设计得特别完整。先把最常用、最容易出错的规则沉淀下来就够了。

六、第四步：创建自定义命令 `/commit`

接下来开始配置自定义命令。

我最推荐先做 /commit，因为它简单、常用，而且立刻能看到效果。

新建文件：

text 复制代码

.claude/commands/commit.md

写入下面内容：

markdown 复制代码

请根据当前 Git 改动生成 commit message。

要求：

1. 先查看 git status 和 git diff
2. 理解本次改动的主要目的
3. 使用中文描述
4. 遵循格式：

type(scope): message

type 可选：
- feat
- fix
- refactor
- docs
- test
- chore

只生成 commit message，不要自动提交。

以后你在 Claude Code 里直接输入：

bash 复制代码

/commit

它就会根据当前改动生成类似这样的提交信息：

text 复制代码

fix(auth): 修复登录过期后未正确跳转的问题

或者：

text 复制代码

feat(user): 新增用户昵称修改功能

这里一定要写清楚一句：

text 复制代码

只生成 commit message，不要自动提交。

因为大多数时候，我只希望 AI 帮我整理提交信息，而不是直接替我执行提交。

七、第五步：创建自定义命令 `/review`

/review 是我觉得最值得沉淀的命令之一。

很多人用 AI 是让它生成代码，但其实在提交前让它做一次自查也很有价值。

新建文件：

text 复制代码

.claude/commands/review.md

写入下面内容：

markdown 复制代码

请对当前代码改动做一次 Code Review。

重点检查：

1. 是否存在明显 Bug
2. 是否破坏已有功能
3. 是否有不必要的复杂实现
4. 是否修改了无关代码
5. 是否缺少错误处理
6. 是否缺少测试
7. 是否引入了不必要的新依赖
8. 是否符合项目现有代码风格

输出格式：

## 总体评价

## 发现的问题

## 建议修改

## 建议补充的测试

使用方式很简单：

bash 复制代码

/review

我一般会在两个场景用它。

第一个场景是自己刚改完一段代码，准备提交前，让它先帮我扫一遍有没有明显问题。

第二个场景是让 AI 自己写完代码之后，再让它用另一套视角检查自己刚才的改动。

当然，/review 不能替代真正的人工 Review。它更像是提交前的第一轮自查，帮你发现一些低级问题，比如忘记处理异常、改了无关文件、没有补测试、引入了没必要的依赖。

这些问题不一定难，但很容易在快速开发时漏掉。

八、第六步：创建自定义命令 `/fix-bug`

修 Bug 的时候，我最怕 AI 一上来就大面积重构。

明明只是一个空指针，它可能顺手把整个模块的结构都改了。最后 Bug 也许修了，但你要花更多时间确认它有没有改出新问题。

所以 /fix-bug 这个命令的核心是：

先定位问题，再给最小修改方案。

新建文件：

text 复制代码

.claude/commands/fix-bug.md

写入下面内容：

markdown 复制代码

请根据我提供的错误日志定位问题。

分析顺序：

1. 判断异常类型
2. 找到最可能出错的位置
3. 解释触发原因
4. 给出最小修改方案
5. 说明是否需要补充测试

要求：

- 不要一上来大面积重构
- 优先给最小可行修复
- 如果信息不足，列出还需要哪些文件或日志

使用时可以这样输入：

text 复制代码

/fix-bug

下面是错误日志：
...

这个命令不需要写得特别复杂，但"最小修改"一定要写进去。

因为真实开发里修 Bug 的第一优先级通常不是顺手优化代码，而是先把问题定位清楚，用最小范围修掉，再考虑要不要重构。

九、第七步：创建自定义命令 `/add-test`

AI 生成测试这件事，有时候挺好用，有时候也挺离谱。

主要问题不是它不会写测试，而是它不知道你的项目里测试应该长什么样。

所以 /add-test 里要强调：先阅读已有测试风格，再补测试。

新建文件：

text 复制代码

.claude/commands/add-test.md

写入下面内容：

markdown 复制代码

请为指定功能或文件补充测试。

要求：

1. 先阅读已有测试风格
2. 优先复用项目已有测试工具
3. 覆盖正常场景和异常场景
4. 测试命名要能表达业务含义
5. 不要依赖真实外部服务
6. 如果需要 mock，请说明 mock 的对象和原因

输出内容：

- 测试思路
- 新增或修改的测试文件
- 如何运行测试

使用方式：

bash 复制代码

/add-test

也可以带上具体文件或模块：

text 复制代码

/add-test src/modules/auth/login.ts

这里没有写死 Jest、JUnit、Pytest 之类的具体工具，是为了保持通用。

不同项目的测试工具不一样，让 Claude 先看已有测试，再决定怎么写，通常比直接告诉它"用某某测试框架"更稳。

十、第八步：创建自定义命令 `/explain`

这个命令我觉得很适合接手旧项目，也适合复盘自己的项目。

有些代码是自己几个月前写的，过一阵再看也会有点陌生。这个时候让 Claude 帮你解释模块结构、核心流程、依赖关系，会比自己从头翻文件快很多。

新建文件：

text 复制代码

.claude/commands/explain.md

写入下面内容：

markdown 复制代码

请解释指定文件或模块的实现逻辑。

要求：

1. 先说明这个模块解决什么问题
2. 再说明核心流程
3. 如果有关键函数，请逐个解释
4. 如果有外部依赖，请说明依赖关系
5. 最后总结可能的风险点或可优化点

输出格式：

## 模块作用

## 核心流程

## 关键函数

## 依赖关系

## 风险点

使用示例：

text 复制代码

/explain src/modules/payment

或者：

text 复制代码

/explain src/utils/request.py

它不只是帮你"看懂代码"，更适合在面试前复盘项目。

比如你可以让它解释某个模块的设计思路，然后再追问：

text 复制代码

如果面试官问这个模块的难点，我应该怎么回答？

这就比单纯让 AI 写代码更有价值了。

十一、一个完整示例：让 AI 在规则内完成一次小需求

前面的配置看起来比较零散，这里用一个完整流程串起来。

假设现在有一个需求：

text 复制代码

给项目新增一个"用户昵称修改"功能。

要求：
1. 昵称不能为空
2. 昵称长度不能超过 20 个字符
3. 修改成功后返回最新用户信息
4. 需要补充测试
5. 不要修改无关模块

如果没有任何项目上下文，很多人可能会直接这样问：

text 复制代码

帮我实现用户昵称修改功能。

这当然也能得到答案，但质量不稳定。AI 可能会自己猜目录、猜接口风格、猜测试工具，甚至顺手改掉一些无关代码。

有了 CLAUDE.md 和 .claude/rules/ 之后，可以换一种方式：

text 复制代码

请根据当前项目规范，实现"用户昵称修改"功能。
先说明涉及文件和实现方案，不要直接改代码。

一个比较理想的输出应该是这样的：

text 复制代码

涉及文件：
- 用户接口或页面入口
- 用户服务逻辑
- 参数校验逻辑
- 测试文件

实现方案：
1. 参考已有用户更新逻辑
2. 增加昵称参数校验
3. 调用已有用户更新方法
4. 返回最新用户信息
5. 补充正常和异常测试

确认方案没问题后，再让它继续：

text 复制代码

按这个方案实现，注意遵守 CLAUDE.md 和 .claude/rules 里的规则。

完成之后，不要急着提交，可以先执行：

bash 复制代码

/review

让它检查这次改动有没有问题，比如：

text 复制代码

是否修改了无关文件
是否缺少异常处理
是否缺少测试
是否破坏已有用户更新逻辑
是否引入了不必要的新依赖

如果测试还没补，再执行：

bash 复制代码

/add-test

最后再执行：

bash 复制代码

/commit

生成提交信息。

完整流程就是：

text 复制代码

写需求
↓
Claude 读取项目说明和规则
↓
先输出实现方案
↓
确认后再改代码
↓
/review 做提交前自查
↓
/add-test 补测试
↓
/commit 生成提交信息

十二、哪些文件应该提交到 Git？

建议提交：

text 复制代码

CLAUDE.md
.claude/settings.json
.claude/commands/
.claude/rules/

不建议提交：

text 复制代码

.claude/settings.local.json

对应的 .gitignore：

gitignore 复制代码

.claude/settings.local.json

原因也很简单。

团队共享的是项目规范、常用命令和工作流。这些内容对其他协作者也有帮助，应该提交。

个人本地配置、临时路径、账号信息、个人偏好，不应该提交。

如果你是个人项目，也可以把这套配置提交上去。这样下次换电脑、换环境，或者过几个月重新打开项目时，AI 仍然能快速理解这个项目。

十三、常见问题

1. `CLAUDE.md` 是不是越长越好？

不是。

好的 CLAUDE.md 应该是具体的、可执行的、和当前项目相关的。

不建议写这种空泛描述：

text 复制代码

请帮我写出高质量代码。

更建议写成具体约束：

text 复制代码

修改代码前先给出涉及文件。
不要修改无关模块。
新增功能需要补充测试。
公共 API 变更前先说明影响范围。

AI 不怕规则多，怕的是规则模糊。

2. `commands` 和 `rules` 有什么区别？

我自己的理解是：

rules 是长期规范。
commands 是任务模板。

比如：

text 复制代码

代码风格、架构边界、测试要求 → rules
生成 commit、代码审查、修 Bug、解释模块 → commands

规则是一直生效的，命令是你在特定场景下主动触发的。

3. 所有项目都需要 `.claude/` 吗？

不一定。

如果只是一个很小的脚本项目，可能一个简单的 CLAUDE.md 就够了。

但如果项目满足下面任意一点，就值得配置：

text 复制代码

项目有固定目录结构
项目有多人协作
项目有统一代码规范
项目有测试和发布流程
你经常让 AI 修改同一个项目

尤其是最后一点。

如果你经常在同一个项目里用 Claude Code，却每次都重复解释项目规则，那就说明这些内容应该沉淀下来了。

写在文后

期待您的一键三连！如果有什么问题或建议欢迎在评论区交流！

【后端/Agent 开发】给你的项目配置一套 .claude/ 工作流：别再裸用 Claude Code 了！

文章目录

前言

一、这篇文章最终要做出什么效果？

二、.claude/ 到底是什么？

三、第一步：写一份 CLAUDE.md

四、第二步：配置 settings.json，先把安全边界圈出来

五、第三步：把规则拆到 .claude/rules/

1. 代码风格规则

2. 架构边界规则

3. 测试规则

4. Git 规范

六、第四步：创建自定义命令 /commit

七、第五步：创建自定义命令 /review

八、第六步：创建自定义命令 /fix-bug

九、第七步：创建自定义命令 /add-test

十、第八步：创建自定义命令 /explain

十一、一个完整示例：让 AI 在规则内完成一次小需求

十二、哪些文件应该提交到 Git？

十三、常见问题

1. CLAUDE.md 是不是越长越好？

2. commands 和 rules 有什么区别？

3. 所有项目都需要 .claude/ 吗？

写在文后

二、`.claude/` 到底是什么？

三、第一步：写一份 `CLAUDE.md`

四、第二步：配置 `settings.json`，先把安全边界圈出来

五、第三步：把规则拆到 `.claude/rules/`

六、第四步：创建自定义命令 `/commit`

七、第五步：创建自定义命令 `/review`

八、第六步：创建自定义命令 `/fix-bug`

九、第七步：创建自定义命令 `/add-test`

十、第八步：创建自定义命令 `/explain`

1. `CLAUDE.md` 是不是越长越好？

2. `commands` 和 `rules` 有什么区别？

3. 所有项目都需要 `.claude/` 吗？