Claude Code 最佳实践

本文要解决什么

团队 3 人以上同时用 Claude Code 协作一个代码库，往往会踩到三个坑：Prompt 风格不统一、AI 改动互相冲突、约定难以传承。本文给出我们在多个项目里验证过的答案。

一、项目结构层面

1.1 分层 CLAUDE.md

一个仓库可以有多个 CLAUDE.md，优先级从低到高：

子级覆盖父级同名条目。

1.2 `.claude/` 作为团队知识沉淀

.claude/
├── commands/         # 团队共享的 slash 命令
├── agents/           # 自定义子代理
├── settings.json     # 项目级 hooks 与权限
└── prompts/          # prompt 模板库

二、Prompt 协作范式

2.1 三段式模板

团队内强制要求所有 prompt 按以下结构写：

1. 目标：这次要解决什么（一句话）
2. 边界：只改哪些文件，不能动什么
3. 验收：怎么判断完成

示例：

目标：给 /api/login 加限流

边界：只改 routes/auth.ts 和 middleware/rateLimit.ts

验收：同一 IP 60 秒内超过 5 次返回 429

2.2 反模式

• ❌ "帮我优化一下这个函数"（目标模糊）
• ❌ "把项目重构成微服务"（边界失控）
• ❌ "看看代码有没有问题"（验收不明）

三、协作流程层面

3.1 单人单任务单分支

AI 改动频繁，多人共用一个分支必撞车。约定：

• 每个 Claude session 开独立分支
• < 30 分钟的任务完成即合并
• > 30 分钟的任务先开 draft PR，边推进边看 diff

3.2 评审分工

• AI 负责：语法、类型、显式逻辑错误
• 人负责：需求理解、业务约束、长期维护性

四、常见反模式速查

本文为骨架版，第二阶段将补充：真实项目的 CLAUDE.md 示例、PR 评审 checklist、团队培训材料。