夜雨聆风这是本系列的第4篇，本篇的目标，是把 Claude Code 从“能用”提升到“适合团队长期协作”。
如果说基础用法解决的是“怎么让 AI 开始干活”，那么进阶配置解决的就是：
怎么让它稳定遵守项目规范
怎么让它在不同目录下理解不同职责
怎么让它和 Git 工作流配合得更顺手
怎么让它尽量少问废话，直接产出可用结果
本篇内容较长，如果你认真读完，并应用到开发工作中，一定会大有裨益。
01
CLAUDE.md：项目的“永久系统提示”
CLAUDE.md是放在项目根目录的 Markdown 文件。每次启动 Claude Code，它都会自动读取这个文件，把它当成项目上下文的一部分。你可以把它理解为：
一个“不会忘记的项目说明书”
一份“团队统一口径”
一套“写代码前必须先读的项目规则”
它的价值不在于写得多，而在于写得准、稳、可执行。
写得好的CLAUDE.md，会显著减少来回追问，让 AI 直接按你的项目风格干活。
1.1 为什么要写 CLAUDE.md？
很多人第一次用 AI 写代码，最大的问题不是“不会生成代码”，而是“生成的代码不符合项目习惯”。
例如：
组件命名风格不一致
API 返回格式和现有项目不统一
数据库操作写在了不该写的地方
测试、错误处理、日志风格和项目现状冲突
AI 每次都重新猜测项目结构，浪费时间
有了CLAUDE.md之后，Claude Code 会优先遵循你写进去的约定，比如：
项目用什么框架
组件怎么拆
接口怎么返回
业务逻辑放哪里
什么文件不能动
什么命令是标准操作
这样一来，AI 不再“凭感觉写代码”，而是“按你的项目规则写代码”。
1.2 一个好用的 CLAUDE.md 应该写什么？
建议至少包含下面这些内容。
1）项目概述
用一两句话说明项目是做什么的，面向谁，核心目标是什么。
项目概述这是一个面向中小企业的合同管理系统，主要用于合同录入、审批流转、到期提醒和归档查询。
这一段非常重要，因为它决定了 AI 对项目业务场景的理解。如果项目目标不清晰，AI 很容易把功能写成“通用版”，而不是“业务版”。
2）技术栈
写清楚前后端、数据库、测试、部署等关键技术。
技术栈前端：Next.js 14 (App Router), React 18, Tailwind CSS后端：Next.js API RoutesORM：Prisma数据库：PostgreSQL 15测试：Jest + React Testing Library + Playwright部署：Vercel + Railway
尽量不要只写“React + Node.js”这种过于笼统的描述。越具体，AI 越容易生成能直接落地的代码。
3）代码规范
这部分是CLAUDE.md的核心。建议写成“明确的硬规则”，不要写成模糊建议。
代码规范组件只允许使用函数式组件 + Hooks，禁止 Class Component所有新代码必须使用 TypeScript公共函数必须补充参数和返回值类型页面组件尽量保持轻量，业务逻辑下沉到 services/API 统一返回格式：{ success: boolean, data?: T, error?: string }所有异常统一通过 AppError 处理，禁止直接抛出裸字符串样式优先使用 Tailwind，少量场景可使用 CSS Module
建议把“不要做什么”也写进去。AI 对“禁止事项”非常敏感，能明显减少跑偏。
4）目录结构
这部分不是为了“好看”，而是为了让 AI 知道代码应该放哪里。
# 目录结构src/app/ # 页面路由、布局、页面级逻辑components/ # 可复用 UI 组件features/ # 按业务域划分的功能模块services/ # 业务逻辑与数据访问lib/ # 工具函数、通用封装types/ # TypeScript 类型定义hooks/ # 自定义 Hooksstyles/ # 全局样式
如果你的项目没有这么分，也没关系。关键是：写成真实结构，不要写理想结构。AI 会按照你写的目录去判断文件应该放哪。
5）命令清单
把常用命令写进去，能让 AI 更容易给出正确的操作建议。
## 常用命令- 启动开发：`npm run dev`- 运行单元测试：`npm test`- 运行 E2E：`npx playwright test`- 类型检查：`npx tsc --noEmit`- 数据库迁移：`npx prisma migrate dev`- 数据库初始化：`npx prisma db push`- 代码格式化：`npm run format`
这部分的价值很大。当 AI 需要执行命令、建议你怎么验证改动时，它会优先参考这里，避免“凭空捏造命令”。
6）边界约束与危险区域
这是很多人容易忽略的一块，但非常重要。
## 重要约定-禁止直接修改 src/generated/ 目录-禁止删除未确认用途的 migration 文件-新增 API 路由必须同步补充类型定义-涉及权限、支付、用户数据时，必须先说明修改思路再动手-任何破坏性操作（删除、清空、覆盖）都必须先确认
这部分能有效防止 AI 做出“看起来很聪明、实际很危险”的操作。尤其是团队项目、生产环境项目、带数据库迁移的项目，一定要写。
1.3 推荐的 CLAUDE.md 模板
下面是一个更完整、适合实际项目使用的版本。你可以直接作为模板，再按项目情况调整。
# 项目名称## 项目概述[一句话描述项目是什么、为谁服务、核心目标是什么]## 技术栈- 前端：- 后端：- 数据库：- 缓存：- 测试：- 部署：## 业务背景[简要说明这个项目解决什么问题，核心业务流程是什么]## 代码规范- [明确的命名规则]- [组件/模块拆分规则]- [类型定义规则]- [错误处理规则]- [日志规则]- [测试规则]## 目录结构[按真实项目结构列出关键目录，并解释每个目录的职责]## 常用命令- 启动开发：- 运行测试：- 类型检查：- 数据库迁移：- 构建发布：## 数据与接口规范- API 返回格式：- 分页规则：- 时间格式：- 错误码规范：- 鉴权方式：## 重要约定- 哪些目录不能修改- 哪些文件是生成的- 哪些操作必须先确认- 哪些流程必须做测试## 常见任务说明- 新增页面时要遵守什么规则- 新增接口时要遵守什么规则- 新增数据库字段时要注意什么- 发布前要检查什么
1.4 CLAUDE.md 的写法技巧
先写“硬规则”，再写“软建议”。所谓硬规则，就是不遵守会出问题的要求，比如：
接口必须统一返回格式
数据库访问必须放在 service 层
不允许直接修改自动生成文件
软建议则是偏风格类，比如：
组件尽量小而清晰
注释保持简洁
优先复用现有逻辑
AI 更容易执行硬规则。
所以CLAUDE.md应该优先写硬规则，风格建议放后面。
用“可执行语言”而不是“形容词”。不要只写：
“代码要优雅”
“结构要合理”
“风格要统一”
这些话 AI 很难具体落实，更好的写法是：
“页面级组件不超过 200 行，复杂逻辑拆到 hooks 或 services”
“所有接口必须返回 success/data/error 三段式结构”
“列表页必须支持分页，不允许一次性加载全部数据”
这类描述更容易被模型执行。
保持 CLAUDE.md 可维护，CLAUDE.md不是一次性文件，而是会随着项目演进不断更新的。建议每次发生以下情况时同步更新：
新增技术栈
调整目录结构
增加新的开发规范
更换测试方式
引入新的生成目录或脚手架工具
如果CLAUDE.md长期不更新，它会逐渐失去价值，甚至误导 AI。
1.5 多层级 CLAUDE.md：适合大型项目
对于 Monorepo 或复杂项目，可以在不同目录放多个CLAUDE.md。
project/CLAUDE.md ← 全局：项目概述、通用规范frontend/CLAUDE.md ← 前端专属：组件规范、样式约定backend/CLAUDE.md ← 后端专属：API 设计、数据库规范scripts/CLAUDE.md ← 脚本专属：执行环境、危险操作说明
这种方式的好处是：
全局规则统一
局部规则更精准
复杂项目里，AI 更容易理解不同目录的职责边界
1.6 一个实用判断标准
你可以用下面这几个问题来判断CLAUDE.md是否写得足够好：
新人进项目后，能不能只看它就知道大致结构？
AI 看完后，能不能少问 50% 以上的重复问题？
项目的关键约束有没有明确写出来？
代码应该放哪里、不能放哪里，是否一目了然？
出现常见任务时，AI 是否能直接按规范产出？
如果这些问题大多回答“是”，说明CLAUDE.md已经开始发挥作用了。
02
settings.json：把“能做什么”和“不能做什么”写死
.claude/settings.json用来控制 Claude Code 的行为。如果说CLAUDE.md更像“项目说明书”，那么settings.json更像“操作权限表”。它负责告诉 Claude Code：
哪些操作可以直接做
哪些操作要先询问
哪些操作永远禁止
默认使用哪个模型
2.1 为什么需要 settings.json？
很多项目里，AI 最容易出问题的不是写错逻辑，而是“做了不该做的事”，例如：
误删文件
改动生成目录
盲目执行危险命令
在没确认的情况下修改数据库迁移
频繁询问本来就很安全的操作，影响效率
settings.json的作用，就是把这些边界提前固定下来。这样可以减少人工反复确认，提高执行效率，也更安全。
2.2 典型配置示例
{"model":"claude-sonnet-4-5","permissions":{"allow":["Read(*)","Bash(npm test)","Bash(npx prisma*)","Bash(npm run build)","Write(src/**)","Edit(src/**)"],"deny":["Bash(rm -rf*)","Bash(git push*)","Write(src/generated/**)","Write(dist/**)"]}}
2.3 allow、deny 分别怎么理解？
allow：预先批准的操作，写进allow的内容，Claude Code 执行时不需要再逐条确认。适合放这些类型：
只读操作
常规测试
常规构建
安全的局部代码修改
项目内受控路径的写入
例如：
Read(*)
Bash(npm test)
Bash(npx prisma*)
Write(src/**)
deny：永远禁止的操作，写进deny的内容，属于高风险行为，应该强约束。例如：
Bash(rm -rf*)
Bash(git push*)
Write(src/generated/**)
尤其是：
删除类命令
破坏性 Git 命令
覆盖生成目录
写入打包产物目录
这些最好直接禁掉。
2.4 配置时的实践建议
不要一上来就放太多权限。很多人喜欢一次性把所有 Bash 都放行，这样虽然省事，但风险很高。更好的做法是：
先放最常用、最安全的命令
运行一段时间后再逐步扩展
保留高风险操作的确认门槛
允许路径要尽量具体，例如：
Write(src/**)比Write(*)安全得多
Bash(npm test)比Bash(*)安全得多
路径和命令写得越具体，越不容易误伤。
将生成目录列入黑名单，很多项目都有自动生成目录，比如：
src/generated/
dist/
build/
coverage/
node_modules/
这些目录一般不应该由 AI 直接修改。
如果放开权限，容易出现“看似成功，实际下次构建又被覆盖”的问题。
2.5 settings.json 的常见使用场景
场景一：开发阶段
开发阶段可以适当放宽常用权限，例如：
读文件
改业务代码
跑测试
执行迁移命令
这样 Claude Code 能更顺畅地完成日常开发任务。
场景二：多人协作项目
多人协作项目里，建议增加保护：
禁止直接改自动生成目录
禁止危险删除命令
禁止无确认的数据库破坏操作
必要时限制某些目录写入权限
场景三：脚本和运维目录
对于scripts/、ops/之类目录，建议单独更严格地配置，因为里面经常涉及：
数据备份
清理脚本
部署脚本
运维命令
这些地方最容易出事故。
2.6 一个简单的判断原则
你可以这样衡量权限是否合适：
常规开发任务是否基本不用反复确认？
危险操作是否仍然会被拦住？
AI 是否能顺利完成“读、改、测”的日常流程？
是否把不该自动执行的命令锁住了？
如果“效率”和“安全”都还可以，说明权限配置比较平衡。
03
与 Git 工作流深度集成
Claude Code 的强项之一，是能够理解当前仓库的变更状态。
这意味着它不只是“写新代码”，还可以很好地参与：
提炼 commit message
生成 PR 描述
辅助 code review
帮你整理 merge conflict
生成 release note
也就是说，AI 不只在“编码阶段”有用，在“协作阶段”同样有用。
3.1 自动生成 Commit Message
当你写完功能后，可以让 Claude Code 根据git diff生成合适的 commit message。
示例提示词：
分析当前 git diff，生成符合 Conventional Commits 规范的 commit message。要求：1. 第一行简洁、准确2. 说明这次提交的核心变化3. 如果有副作用或注意事项，也一起写出来
可能生成的结果：
feat(auth): add refresh token rotation- Implement refresh token rotation to reduce replay risk- Invalidate old refresh tokens after successful use- Add token reuse detection logic
为什么这样做有价值？
好的 commit message 不是“好看”，而是能帮助以后维护。它至少能解决这几个问题：
回溯历史时快速知道改了什么
方便生成 release note
方便排查 bug 时定位可疑提交
方便团队协作时统一写法
Conventional Commits 的常见类型
你可以在CLAUDE.md或团队规范里顺便说明这些类型：
feat：新功能
fix：修复 bug
refactor：重构
docs：文档修改
test：测试相关
chore：杂项、构建、工具链
perf：性能优化
style：格式调整，不改逻辑
这样 AI 生成的提交信息会更稳定。
3.2 生成 PR 描述：把“改了什么”讲清楚
PR 描述的最大问题通常不是内容太少，而是结构不清楚。Claude Code 很适合把零散改动整理成可读的 PR 说明。
示例提示词：
根据这次的 git log 和 diff，生成一份详细的 PR 描述：- 改动摘要（3行以内）- 详细改动说明- 影响范围- 测试方式- 需要注意的风险点- 可能的回滚方式
一个比较完整的 PR 描述通常应该包含：
改动摘要,用很短的话告诉读者“这次 PR 是干什么的”。
详细改动说明,分模块说明，例如：
新增了什么
调整了什么
删除了什么
为什么要这样改
影响范围,说明改动会影响哪些模块、页面、接口、数据库、用户流程。
测试方式,明确写出：
本地怎么验证
跑了哪些测试
哪些边界情况覆盖了
风险点与回滚方式，如果这次 PR 有风险，最好提前说明：
是否涉及数据库变更
是否影响线上兼容
是否容易回滚
回滚时需要注意什么
这样不仅方便 reviewer，也能降低沟通成本。
3.3 Code Review 辅助：让 AI 先帮你找问题
Claude Code 很适合做“第一轮 review”，尤其适合在你提交 PR 前先快速扫一遍问题。
示例提示词：
请以 senior engineer 的视角 review 这次 PR，重点检查：1. 安全漏洞（SQL 注入、XSS、权限绕过）2. 性能问题（N+1 查询、大量循环、重复请求）3. 错误处理是否完善4. 是否有遗漏的边界情况5. 命名、结构、可读性是否合理下面是 diff：[粘贴 diff]
推荐的 review 维度
AI review 最有价值的地方，不是“挑语法错”，而是帮你发现这几类问题：
逻辑是否完整
是否遗漏边界条件
是否引入性能隐患
是否违反项目约定
是否存在安全风险
是否可以拆得更清晰
使用建议
AI review 适合做“前置筛查”，但不应该替代人工 review。最好的方式是：
先让 AI 看一遍
再让熟悉业务的人复核
对高风险模块再做更严格检查
这样效率和质量都更稳。
3.4 解决 Merge Conflict：先理解意图，再合并代码
当两个分支同时修改了同一文件时，Claude Code 可以帮你梳理冲突内容，先理解双方意图，再完成合并。
示例提示词：
帮我解决这个 merge conflict。请先理解 main 分支和 feature 分支各自想表达什么，再在保留两边意图的前提下进行合理合并。main 分支：重构了错误处理逻辑feature 分支：新增了字段校验逻辑[粘贴冲突内容]
很多冲突不是简单的“保留 A 或保留 B”，而是要判断：
两边是不是解决了不同层面的问题
是否可以组合成一个更完整的方案
是否存在重复逻辑
是否有一边已经过时
Claude Code 在这里的价值，是帮你先读懂上下文，减少“机械合并”。
合并完成后，建议至少检查：
编译是否通过
单测是否通过
逻辑是否重复
错误处理是否一致
是否破坏了原有接口
3.5 自动生成 Release Note
在发版前，你可以让 Claude Code 帮你从一段时间内的提交中整理 release note。
示例提示词：
读取从 v1.2.0 到 HEAD 的所有 git log，生成面向用户的 Release Notes，分类为：新功能、改进、Bug 修复、Breaking Changes，过滤掉 chore/docs/test 类型提交。
好的 release note 能帮助：
运营和产品理解版本变化
测试人员确认重点回归区域
用户知道这次版本有哪些新东西
运维和开发快速定位风险点
建议一般可以分成：
新功能
功能优化
问题修复
性能提升
兼容性变化
已知问题
如果有破坏性变更，一定要单独标出来。
- END -
如果你在使用工具过程中有独特的实践经验，欢迎在评论区分享！
欢迎点赞、红心、转发一键三连，关注本账号，以免错过后续内容更新。