很多人使用 Claude Code、Trae、Cursor 这类 Agent 工具时，最开始都习惯直接提需求：

帮我加一个接口。
帮我改一下页面。
帮我修这个 bug。

刚开始确实很爽。但用久了会发现一个问题：AI 的能力很强，行为却不一定稳定。

同一个项目里，它这次可能遵循分层架构，下次就把 SQL 写进 handler；这次会用中文注释，下次又混进英文说明；这次知道 Windows 要用 PowerShell，下次又写出 sed、awk、tail 这些 Unix 命令。

这不是模型不会，而是你没有给它一份稳定的“项目上下文”和“行为边界”。

要让 AI 真正像团队里的工程师一样工作，不能只靠临时 Prompt。更好的做法是把项目规则、技术栈约束、工作流、目录结构、测试方式和禁止事项沉淀到配置文件里，让 Agent 每次进入项目都能读取同一套规则。

本文基于 Claude全局配置约束规则.md 整理，讲一套适合 Windows 开发环境的 Claude 项目级配置方法，并以 Gin、React、FastAPI 三类常见项目为例，说明如何把团队工程规范写成 AI 可执行的约束。

---

一、为什么需要 Claude 项目配置？

如果没有项目配置，AI 每次工作都像新来的外包同学：它知道很多通用知识，但不知道你的团队习惯。

比如它不知道：

• 这个项目接口错误响应是不是统一 { "code": "...", "message": "..." }
• 后端是否允许 handler 直接访问数据库
• 前端服务端状态是用 Zustand 还是 TanStack Query
• Python 项目用 pip、poetry 还是 uv
• Windows 环境里能不能调用 sed、awk
• 是否允许直接 git push 或 git reset --hard

这些规则如果每次都靠口头提醒，很快就会漏。

项目配置的价值就在于：把“每次都要说”的话，变成 Agent 每次都能读到的规则。

可以这样理解：

临时 Prompt：解决当前这一次对话
CLAUDE.md：约束整个项目里的长期行为
.claude/：扩展项目级上下文、命令、hooks、skills、agents

当规则沉淀下来后，AI 不再只是“能写代码”，而是开始按照团队的工程边界写代码。

---

二、推荐的项目根目录结构

一个比较完整的 Claude 项目根目录可以这样组织：

your-project/
├── CLAUDE.md
├── CLAUDE.local.md
├── .gitignore
├── .mcp.json
└── .claude/
    ├── hooks/
    │   ├── PostToolUse.sh
    │   ├── SessionStart.sh
    │   └── PreCompact.sh
    ├── commands/
    │   └── cinjp.md
    ├── skills/
    │   ├── carousel/
    │   └── drill/
    ├── agents/
    │   ├── code-reviewer.md
    │   ├── researcher.md
    │   └── log-analyzer.md
    ├── output-styles/
    │   └── terse.md
    ├── plugins/
    │   └── vercel/
    ├── rules/
    │   └── api.md
    ├── statusLine
    ├── settings.json
    └── settings.local.json

这些文件可以分成几类：

文件或目录	作用
CLAUDE.md	项目主规则，建议控制在 200 行以内
CLAUDE.local.md	个人本地偏好，通常加入 .gitignore
.mcp.json	MCP 配置，必须放在项目根目录
.claude/hooks/	在特定时机自动触发脚本
.claude/commands/	自定义快捷命令
.claude/skills/	可随时调用的具体 Skill
.claude/agents/	子 Agent，每个 Agent 有独立上下文窗口
.claude/rules/	按路径匹配加载的局部规则
.claude/settings.json	权限、模型、hooks 注册中心
.claude/settings.local.json	本地个人设置，通常不提交

这套结构的重点不是“文件越多越专业”，而是把不同类型的信息放到正确位置。

CLAUDE.md 放全局、稳定、团队共享的规则；CLAUDE.local.md 放个人偏好；.claude/rules/ 放局部约束；.claude/agents/ 放专职子 Agent；.claude/skills/ 放可复用能力。

---

三、CLAUDE.md 应该写什么？

CLAUDE.md 是最核心的文件。它不应该写成一篇长文，而应该是一组简短、明确、可执行的规则。

一个 Windows 版本的 CLAUDE.md 可以包含这些部分：

# 开发者配置

高级全栈工程师。主要语言：TypeScript、Python、Go。

## 语言

- 所有对话、文档、注释、提交信息使用简体中文
- 唯一例外：代码标识符遵循项目既有命名约定

## 思考先行

- 实现前陈述假设；不确定就问，不沉默选择
- 存在多种解读时全部列出，不擅自决定
- 存在更简单方案时指出并说明理由

这几条看似简单，但很有用。

比如“实现前陈述假设”，能避免 AI 在需求不清楚时直接开写；“所有对话、文档、注释、提交信息使用简体中文”，能保证团队输出风格一致；“代码标识符遵循项目既有命名约定”，又避免把变量名也强行中文化。

我更建议把 CLAUDE.md 写成“行为约束”，而不是“愿景文档”。

坏写法：

请写出高质量、优雅、可维护的代码。

好写法：

- 函数不超过 30 行
- 使用描述性变量名，除了循环计数器外不用单字母
- 注释描述意图和约束，不重复代码逻辑
- 禁止“修改说明”式注释，变更信息由版本控制承担

前者听起来正确，但很难执行；后者可以检查，也更容易让 AI 稳定遵守。

---

四、几条真正有用的全局约束

1. 简单性原则

AI 很容易“顺手发挥”：多抽一层、多封装一个类、多加几个配置项，看起来很工程化，实际上把问题复杂化了。

可以在 CLAUDE.md 里明确写：

## 简单性原则

- 单一职责：每个函数或类只承担一个责任
- 三次法则：重复出现三次以上再考虑通用化
- 可读性优先：禁止“聪明”技巧
- 两种方案犹豫时，选择更简单的那个
- 不做未请求的功能、抽象、配置

这几条的作用，是把 AI 从“展示能力”拉回“解决问题”。

2. 手术式修改

Agent 写代码时，最怕它顺手改一片。

比如你让它修一个参数校验，它顺便格式化整个文件、重命名几个变量、调整相邻函数结构。最后 diff 很大，review 成本也高。

所以建议加上：

## 手术式修改

- 不“改善”相邻代码、注释或格式
- 不重构没坏的东西
- 匹配既有风格，即使你不会那样写
- 每一行改动都应能追溯到用户请求

这条规则对真实项目很重要。AI 不是没有能力重构，而是默认不应该扩大修改范围。

3. 目标驱动执行

让 AI 做复杂任务时，不要只让它“努力完成”，而要让它围绕可验证目标循环：

## 目标驱动执行

- 将任务转化为可验证目标，循环直到验证通过
- “添加验证” → 写无效输入测试，再让测试通过
- “修复 bug” → 写重现测试，再让测试通过
- “重构 X” → 确保前后测试都通过
- 连续三次验证失败，暂停实现，回到需求和设计阶段复盘

这里的关键是“验证”。没有验证，AI 很容易在看起来合理的答案里结束任务。

---

五、Windows 环境要单独写清楚

如果你在 Windows 上使用 Claude Code 或类似 Agent，强烈建议把操作系统和 Shell 规则写进配置。

比如：

## 环境

- 操作系统：Windows 11
- Shell：PowerShell（`pwsh`/`powershell`） Git
- 包管理器：前端项目使用 npm，Python 必须使用 uv 创建虚拟环境

## Windows 注意事项

- 不在 PowerShell 中调用 Unix 文本工具（`sed`/`awk`/`cut`/`head`/`tail`）
- 使用 PowerShell 原生命令：
  - `head` → `Select-Object -First N`
  - `tail` → `Get-Content -Tail N`
  - 替换 → `-replace` 配合 `Get-Content`/`Set-Content`

这能减少很多低级错误。

比如 AI 常写：

cat app.log | tail -n 100

但在 PowerShell 项目里，更合适的是：

Get-Content app.log -Tail 100

还有服务进程管理也要写清楚：

## 服务进程管理

- 启动开发服务必须用后台模式
- 测试完毕后立即关闭进程
- 对话结束前，检查并清理本对话启动的残留服务进程
- 禁止启动服务后放任不管，导致端口占用影响后续手动测试

这是很多 Agent 使用体验变差的来源：端口被占用、后台服务没关、下次调试莫名失败。

---

六、把技术栈规则写成“局部项目手册”

全局规则解决的是通用行为，但不同技术栈还需要不同约束。

素材里给了三类项目规则：Gin RESTful API、React 前端项目、FastAPI RESTful API。它们很适合放到 CLAUDE.md 的项目模板里，或者拆到 .claude/rules/ 里按路径加载。

1. Gin RESTful API 项目

Gin + GORM 项目的重点是分层清楚：

cmd/server/
internal/
├── handler/
├── service/
├── repository/
├── model/
│   ├── entity/
│   └── dto/
├── middleware/
└── config/
migrations/

关键约束：

• handler 只做参数绑定和响应，不含业务逻辑。
• repository 只负责数据访问，不返回 *gorm.DB。
• 跨 repository 操作在 service 层用事务包裹。
• DTO 与 entity 分离，不暴露内部字段。
• 禁止用 200 + 业务错误码 代替正确 HTTP 状态码。

这些规则能有效防止 AI 把代码写成“能跑但分层混乱”的样子。

2. React 前端项目

React + Vite + Ant Design 项目的重点是把页面、组件、API、状态管理分开：

src/
├── pages/
├── components/
├── hooks/
├── api/
├── stores/
├── types/
├── utils/
├── constants/
└── styles/

关键约束：

• pages/ 对应路由，每个页面一个目录。
• components/ 只放跨页面复用组件，页面专属组件放页面目录内。
• api/ 按后端资源分文件，函数只发请求返回数据，不写业务逻辑。
• 服务端状态交给 TanStack Query，Zustand 只管客户端 UI 状态。
• Ant Design 直接使用，不逐个封装代理组件。
• 表格列定义抽成常量数组，不内联 JSX。

这类规则能明显减少前端项目里的“随手堆组件”和“状态管理混用”。

3. FastAPI RESTful API 项目

FastAPI + SQLAlchemy 2.0 项目的重点是 Controller、Service、DAO、Model、Schema 分离：

app/
├── main.py
├── config.py
├── database.py
├── api/
│   ├── controller/
│   ├── service/
│   ├── dao/
│   ├── models/
│   └── schemas/
├── middleware/
├── common/
├── migrations/
├── tests/
└── scripts/

关键约束：

• Controller 只接收和验证请求，调用 Service，返回响应。
• Service 之间可互相调用，DAO 之间不可。
• Schemas 与 Models 严格分离。
• SQLAlchemy 2.0 使用 select()，不用旧的 Query API。
• DAO 方法接收 db: Session，不返回 Session 或 Query 对象。
• 使用 uv 管理依赖。
• Alembic 迁移文件一旦执行，禁止修改。

这些约束能让 AI 生成代码时自动贴近团队架构，而不是按它记忆里的通用示例随意发挥。

---

七、推荐加载方式：全局少，局部准

一个常见误区是把所有规则都塞进 CLAUDE.md。

这会带来两个问题：

• 文件太长，AI 读取成本高。
• 无关规则会干扰当前任务。

更好的方式是分层加载：

建议这样拆：

规则类型	推荐位置
语言、Git、安全边界、Windows 环境	CLAUDE.md
个人偏好、本地路径、本机工具	CLAUDE.local.md
Gin、React、FastAPI 等技术栈规则	.claude/rules/
代码审查、日志分析、调研类专职角色	.claude/agents/
可复用任务能力	.claude/skills/
快捷工作流命令	.claude/commands/

核心原则是：全局规则保持短，局部规则保持准。

---

八、几条落地建议

1. CLAUDE.md 不要超过 200 行

它不是团队 Wiki，而是 Agent 的执行规则。能放局部规则的，不要塞进全局文件。

2. 每条规则都要可执行

少写“高质量”“优雅”“健壮”，多写“handler 不写业务逻辑”“禁止返回 *gorm.DB”“测试文件与源文件同目录”。

3. 禁止事项要写清楚

AI 对“不要做什么”的约束通常更稳定，比如：

• 禁止 git push
• 禁止 git reset --hard
• 禁止 handler 直接写数据库查询
• 禁止用 200 包装业务错误
• 禁止启动服务后不清理进程

4. 把验证命令写进规则

不同项目要明确验证方式：

Gin：go test ./...
React：npm run test / npm run build
FastAPI：pytest --cov=app tests/

这样 AI 完成修改后，才知道该用什么命令证明它没有破坏项目。

5. 本地差异放到 CLAUDE.local.md

个人路径、个人工具、个人偏好不要提交到团队规则里。否则团队规则会越来越乱。

---

九、总结

AI Agent 的代码能力已经很强，但强不等于稳定。真正决定它能否进入日常工程流的，是有没有一套清晰、可执行、可验证的项目规则。

CLAUDE.md 负责定义团队共享的行为边界；.claude/ 目录负责承载 hooks、commands、skills、agents、rules 等扩展能力；局部规则负责约束不同技术栈的架构和编码习惯。

如果你在 Windows 环境开发，还要把 PowerShell、进程管理、包管理器、禁止 Unix 文本工具这些规则写清楚。否则 AI 很容易生成“看起来对，但本机跑不起来”的命令。

最后记住一句话：

不要只把 Claude 当成聊天助手，要把它当成团队工程师来配置。

当你的项目规则足够清楚，AI 才能少猜、少跑偏、少扩大修改范围，真正按照团队的工程方式交付代码。