团队宪法:CLAUDE.md 和rule使用技巧与复利模式

引言

你有没有遇到过这样的场景?

场景 1: 规范执行靠"吼"

• 代码评审时:"这个命名不符合规范啊,改一下"

• 提交代码时:"提交信息格式不对,重新写"

• 写完功能后:"测试呢?单元测试写了吗?"

• 每次都要提醒,每次都要返工
  场景 2: AI 助手"不听话"

• Claude Code 生成的代码风格乱七八糟

• 函数命名有时驼峰有时下划线

• 注释写得像天书,或者干脆不写

• 每次都要手动修改,效率大打折扣

传统团队靠"人盯人"执行规范,效率低、成本高、容易遗漏。而 AI 辅助开发时代,如果没有明确的规范,AI 生成的代码质量参差不齐,反而增加了维护负担。

答案是 : 团队宪法 --- CLAUDE.md + rules/

就像国家需要宪法来规定基本原则,团队也需要一套"宪法"来定义:

• 项目的技术栈和常用命令是什么?（CLAUDE.md）
• 我们的编码规范和安全底线是什么?（rules/ 目录）

团队宪法是区别草台班子和正规军的分水岭。

本文将深入探讨如何通过 CLAUDE.md + rules/ 建立团队规范,并通过复利模式让这份宪法不断演进,让 Claude Code 成为越来越资深的队友。

阅读本文后,你将学会:

• 理解团队宪法的目录结构和各部分的职责
• 正确使用 CLAUDE.md 存放项目事实,使用 rules/ 存放底线规则
• 建立复利思维:发现问题 → 更新宪法 → 全员受益
• 掌握让 AI 理解和遵守规范的技巧

---

一、为什么需要"团队宪法"?

1.1 传统团队的规范问题

在没有自动化工具之前,团队规范靠什么维护?

方式 1: 文档 + 口头传承

某公司编码规范.docx (上次更新: 3年前)
  - 第 3 章 命名规范
  - 第 5 章 注释规范
  - 第 8 章 异常处理
  ...

现实:
  - 新人入职不知道这份文档
  - 老员工也不记得具体内容
  - 规范更新后没人通知

方式 2: Code Review 人肉检查

评审者:"这里应该用 Optional 而不是 null"
开发者:"哦,好的" (心里想:又是这个问题,上次也提过)
评审者:"下次注意" (心里想:已经说了 N 遍了)

下周:
  同样的问题再次出现...

方式 3: Lint 工具 + Git Hooks

# .eslintrc.js
rules: {
  'semi': ['error', 'always'],
  'quotes': ['error', 'single'],
  ...100+ 条规则
}

问题:
  - 只能检查语法,不能检查逻辑
  - 配置复杂,维护困难
  - 无法覆盖架构层面的规范

共同的痛点:

• ❌ 规范执行不一致 - 靠人工检查,难免遗漏
• ❌ 新人学习成本高 - 需要阅读大量文档
• ❌ 规范更新难同步 - 改了文档,代码不一定改
• ❌ 违规发现太晚 - 代码写完才发现问题

在我们公司，我已经在Gerrit上部署了AI CodeReview系统，能抓出很多人工写的代码不按照公司规范来的情况，并且在AI都提示出来的情况下还不修改。

1.2 AI 辅助开发的新挑战

引入 AI 后,问题不仅没有减少,反而增加了新的挑战:

挑战 1: AI 不知道你的团队规范

// 你希望的代码风格
export async function getUserById(id: string): Promise<User | null> {
  try {
    const user = await db.users.findOne({ id });
    return user ?? null;
  } catch (error) {
    logger.error('Failed to get user', { id, error });
    throw new DatabaseError('User query failed', { cause: error });
  }
}

// AI 默认生成的代码(没有规范约束)
export function getUserById(id) {
  return db.users.findOne({ id }).catch(e => {
    console.log(e)
    return null
  })
}

差异:

• ❌ 缺少类型标注
• ❌ 使用 console.log 而不是 logger
• ❌ 错误处理不规范
• ❌ 没有异常抛出和上下文信息

挑战 2: 每次对话都要重复说明规范

你: "帮我实现用户登录功能"
AI: [生成代码,不符合规范]

你: "记得使用 logger 而不是 console.log"
AI: [修改代码]

你: "还要加上类型标注"
AI: [再次修改]

你: "异常处理要抛出 CustomError"
AI: [又一次修改]

效率大打折扣!

挑战 3: AI 生成的代码风格不一致

第一次对话:

function addUser(name: string) { ... }  // 驼峰命名

第二次对话:

function delete_user(id: string) { ... }  // 下划线命名

第三次对话:

async function GetUserList() { ... }  // 大写开头

同一个项目,三种命名风格混杂,维护噩梦!

1.3 claude.md 的定位与价值

团队宪法是什么?

团队宪法是一套完整的配置体系,包括 CLAUDE.md（项目事实）和 .claude/ 目录下的 rules/ 规则文件,共同定义了 AI 在工作时应该遵守的规范和约束。

核心价值:

1. 自动加载,无需重复 - Claude Code 启动时自动读取配置,每次对话都生效
2. 职责分离,易于维护 - CLAUDE.md 存项目事实,rules/ 存底线规则,结构清晰
3. 可版本管理 - 和代码一起提交到 Git,团队共享
4. 可持续改进 - 发现问题就更新,形成复利效应

类比理解:

团队宪法就像国家的"宪法体系"
  ├─ CLAUDE.md: 项目事实(技术栈、常用命令、约束)
  ├─ rules/: 底线规则(编码规范、测试要求、安全规范)
  └─ 可以修正和完善(宪法修正案)

对比传统方式:

维度	传统规范文档	Lint 工具	claude.md
自动执行	❌ 靠人工	✅ 自动检查	✅ AI 自动遵守
覆盖范围	✅ 全面	⚠️ 仅语法层面	✅ 全面(语法+逻辑+架构)
学习成本	❌ 需要阅读大量文档	⚠️ 需要理解规则	✅ AI 直接理解并应用
实时生效	❌ 写完代码才发现	⚠️ 提交时检查	✅ 生成时就符合规范
版本管理	⚠️ 文档独立管理	✅ 配置文件管理	✅ 和代码一起管理
可演进性	❌ 更新困难	⚠️ 需要改配置	✅ 随时更新,立即生效

"claude.md 不是约束 AI 的枷锁,而是让 AI 成为资深队友的训练手册"

---

二、claude.md 文件详解

2.1 配置层级与工作原理

Claude Code 支持两级配置 ,优先级规则: 项目配置 > 全局配置 > Claude 默认行为

1. 项目级配置(优先级最高)
   路径: <项目根目录>/CLAUDE.md
   作用域: 当前项目

2. 全局配置(默认配置)
   路径: ~/.claude/CLAUDE.md
   作用域: 所有项目

图2: claude.md 配置层级与加载机制,项目配置优先级高于全局配置

工作原理: claude.md 的内容会被插入到每次 API 调用的系统提示词中,作为团队宪法让 AI 自动遵守。项目配置会覆盖全局配置中的同名规则,未覆盖的规则会继承。

示例:

# 全局配置: 使用双引号、末尾分号、2空格缩进
# 项目配置: 使用单引号(覆盖)、4空格缩进(覆盖)

# 最终生效: 单引号、末尾分号(继承)、4空格缩进

2.2 团队宪法的目录结构

根据 Claude 中文社区的官方实践，团队宪法应该采用以下目录结构（建议放进仓库，团队共享）：

your-repo/
├─ CLAUDE.md              # 项目事实（技术栈、常用命令、约束）
└─ .claude/
   └─ rules/              # 底线规则（拆成小文件）
      ├─ security.md      # 安全底线
      ├─ testing.md        # 测试底线
      └─ coding-style.md  # 代码风格底线

CLAUDE.md 的定位：存放"项目事实"

CLAUDE.md 的重点是写可执行、可验证的信息，而不是详细的规则：

# 项目概述
- 技术栈：TypeScript + React 18+ + Next.js 14
- 目录结构入口：src/ 为源代码目录

## 常用命令（必须准确）
- 安装依赖：`pnpm install`
- 运行测试：`pnpm test`
- 构建：`pnpm build`
- 代码格式化：`pnpm format`
- 静态检查：`pnpm lint`

## 约束（团队共识）
- 默认先用 Plan Mode 分析，再动代码
- 任何会影响行为的改动：必须补测试/补文档
- 涉及凭证/权限：先安全审查，再合并

rules/ 目录：存放"底线"规则

规则应该拆成可组合、可审查的小文件：

• rules/security.md：密钥与输入校验底线（禁硬编码、边界校验、最小权限）
• rules/testing.md：测试底线（TDD 流程、覆盖率门槛、关键路径必须 E2E）
• rules/coding-style.md：代码组织底线（文件大小、函数长度、错误处理等）

这些规则不要"抄一大段"，而是写成团队真的会执行的清单。

职责分离原则：

• CLAUDE.md：只写项目事实，不写详细规则
• rules/：只写规则约束，不写项目事实
• 两者配合，形成完整的团队宪法

2.3 上下文优先级

CLAUDE.md 和 rules/ 目录中的配置优先级高于对话历史,确保规范始终生效:

优先级排序:
1. CLAUDE.md 和 rules/ 中的规范  [最高优先级]
2. 用户当前输入的指令            [高优先级]
3. 对话历史中的上下文            [中优先级]
4. Claude 的默认行为             [低优先级]

实际效果: 即使之前对话中使用了不符合规范的代码,CLAUDE.md 和 rules/ 中的规范仍会在新代码生成时生效。用户可以在单次对话中临时覆盖规范,但下次对话会自动恢复。

图3: claude.md 工作原理,展示如何被解析并插入到 API 调用的系统提示词中

---

三、团队宪法的内容设计

3.1 CLAUDE.md：项目事实

CLAUDE.md 的定位是"项目记忆"，重点写可执行、可验证的信息：

# 项目概述
- 技术栈：TypeScript + React 18+ + Next.js 14
- 目录结构入口：src/ 为源代码目录，packages/ 为共享包

## 常用命令（必须准确）
- 安装依赖：`pnpm install`
- 运行开发服务器：`pnpm dev`
- 运行测试：`pnpm test`
- 构建：`pnpm build`
- 代码格式化：`pnpm format`
- 静态检查：`pnpm lint`

## 约束（团队共识）
- 默认先用 Plan Mode 分析，再动代码
- 任何会影响行为的改动：必须补测试/补文档
- 涉及凭证/权限：先安全审查，再合并
- 提交前必须通过 lint 和测试

关键点：

• ✅ 写具体的技术栈和版本号
• ✅ 写准确的命令（AI 会直接执行）
• ✅ 写团队共识的约束（不是详细规则）
• ❌ 不要写详细的编码规范（应该放在 rules/ 目录）

3.2 rules/ 目录：底线规则

规则应该拆成可组合、可审查的小文件。以下是三个核心规则文件的示例：

rules/coding-style.md：代码组织底线

# 代码风格规范

## TypeScript 风格
- 严格模式: 启用 `strict: true`
- 类型标注: 所有函数参数和返回值必须标注类型
- 类型断言: 避免使用 `any`,优先使用 `unknown`

## 代码格式
- 缩进: 2 空格
- 引号: 单引号(字符串),双引号(JSX 属性)
- 分号: 必须使用
- 行宽: 最大 100 字符

## 命名约定
- 组件: PascalCase (UserProfile.tsx)
- 函数: camelCase (getUserData)
- 常量: UPPER_SNAKE_CASE (API_BASE_URL)
- 布尔值: is/has/can 开头 (isLoading, hasPermission)

## 注释要求
- ✅ 必须: 复杂逻辑、算法实现、业务规则
- ✅ 推荐: 公共 API、工具函数
- 所有导出的函数/类必须添加 JSDoc

rules/testing.md：测试底线

# 测试规范

## 单元测试
- 覆盖率: > 80%
- 框架: Jest + Testing Library
- 每个公共函数必须有测试
- 测试用例命名: `should ... when ...`

## 集成测试
- 工具: Cypress / Playwright
- 覆盖: 关键用户流程
- 运行时机: PR 合并前

## TDD 流程
- RED: 先写失败的测试
- GREEN: 实现最小代码让测试通过
- REFACTOR: 重构优化代码

rules/security.md：安全底线

# 安全规范

## 敏感信息处理
- ❌ 禁止: 将密钥/密码硬编码到代码中
- ✅ 使用: 环境变量 + .env 文件

## 输入验证
- 所有用户输入必须验证和净化
- 使用 Zod / Yup 进行 schema 验证

## XSS 防护
- 使用 React 的自动转义
- 避免 `dangerouslySetInnerHTML`

---

四、复利模式:持续优化的团队宪法

4.1 什么是复利模式?

传统模式:写一次规范,长期不更新,最终过时无用。

复利模式:发现问题 → 更新宪法 → 全员受益 → 持续改进。

类比:

复利模式就像投资理财
  - 初始投入: 编写基础宪法
  - 持续投入: 每次遇到问题就更新
  - 复利收益: 团队整体能力提升,问题逐渐减少

第1周: 发现 10 个规范问题
第2周: 发现 7 个问题(之前的 3 个不再出现)
第3周: 发现 5 个问题
...
第N周: 发现 0-1 个问题(规范已经很完善)

图4: 复利模式的循环流程,展示持续优化如何带来复利收益

4.2 复利模式的工作流程

步骤 1: 发现问题

在 Code Review、Bug 修复、性能优化等场景中发现规范缺失或不明确的地方。

示例场景:

// Code Review 发现的问题
// 开发者 A 的代码:
function processData(data) {
  return data.map(item => {
    // 复杂的业务逻辑,没有注释
    return item.value * 1.1 + (item.bonus ?? 0) - item.discount;
  });
}

// 评审者: "这个计算逻辑是什么意思?为什么乘 1.1?"
// 开发者: "哦,这是加上 10% 的税费"
// 评审者: "这种业务逻辑应该加注释啊"

步骤 2: 分析根因

思考:为什么会出现这个问题?是规范缺失还是规范不够明确?

根因分析:
  - rules/ 目录中没有规定"复杂业务逻辑必须添加注释"
  - 开发者和 AI 都不知道这个规范
  - 导致每次都要在 Code Review 中提醒

步骤 3: 更新宪法

在 rules/ 目录下的相应规则文件中添加或修改规范,明确要求。

# rules/coding-style.md

## 注释要求

### 业务逻辑注释
- ✅ 必须: 所有包含数字常量的计算逻辑必须注释说明含义
- ✅ 必须: 复杂的业务规则必须注释说明原因

### 示例:
\`\`\`typescript
// ✅ 正确
function calculateTotalPrice(item: Item): number {
  // 基础价格 + 10% 增值税
  const priceWithTax = item.value * 1.1;

  // 加上奖励积分(如有),减去折扣
  return priceWithTax + (item.bonus ?? 0) - item.discount;
}

// ❌ 错误: 缺少注释
function calculateTotalPrice(item: Item): number {
  return item.value * 1.1 + (item.bonus ?? 0) - item.discount;
}
\`\`\`

注意：规则应该放在 rules/ 目录下，而不是 CLAUDE.md 中。CLAUDE.md 只存放项目事实。

步骤 4: 提交与同步

# 1. 更新规则文件
git add .claude/rules/coding-style.md
git commit -m "docs(claude): add business logic comment requirement"

# 2. 推送到远程仓库
git push origin main

# 3. 团队成员拉取最新代码
# 下次使用 Claude Code 时自动生效

步骤 5: 全员受益

所有团队成员(包括 AI)都自动遵守新规范,类似问题不再出现。

效果:
  - 开发者 A: 下次写代码时,Claude Code 自动添加注释
  - 开发者 B: 第一次接触这个规范,AI 生成的代码已经符合
  - 开发者 C: 维护老代码时,AI 重构时自动加上注释

结果: 团队整体代码质量提升,Code Review 效率提高

4.3 真实案例:从代码缺陷到宪法条款

背景:

某 Android 项目在生产环境出现内存泄漏,排查后发现是因为 Activity 中的匿名内部类持有了外部引用。

问题代码:

// MainActivity.kt
class MainActivity : AppCompatActivity() {
    private var data: String = ""

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // ❌ 问题: 匿名内部类持有 Activity 引用
        button.setOnClickListener(object : View.OnClickListener {
            override fun onClick(v: View?) {
                // 使用了外部类的成员变量
                processData(data)
            }
        })
    }
}

根因分析:

1. 匿名内部类隐式持有外部类引用
2. 如果 listener 的生命周期超过 Activity,会导致内存泄漏
3. 团队之前没有明确的规范来避免这个问题

解决方案:

更新 rules/security.md,添加 Android 内存泄漏防护规范:

# rules/security.md

## Android 内存泄漏防护

#### 避免匿名内部类持有 Activity 引用
- ❌ 禁止: 在 Activity/Fragment 中使用匿名内部类作为长生命周期监听器
- ✅ 使用: Lambda 表达式或静态内部类 + 弱引用

\`\`\`kotlin
// ❌ 错误: 匿名内部类
button.setOnClickListener(object : View.OnClickListener {
    override fun onClick(v: View?) {
        processData(data)  // 持有外部引用
    }
})

// ✅ 正确: Lambda 表达式
button.setOnClickListener { view ->
    processData(data)  // Kotlin 编译器优化,不会泄漏
}

// ✅ 正确: 静态内部类 + 弱引用
class MainActivity : AppCompatActivity() {
    private val clickListener = ClickListener(this)

    override fun onCreate(savedInstanceState: Bundle?) {
        button.setOnClickListener(clickListener)
    }

    private class ClickListener(activity: MainActivity) : View.OnClickListener {
        private val activityRef = WeakReference(activity)

        override fun onClick(v: View?) {
            activityRef.get()?.processData()
        }
    }
}
\`\`\`

#### Handler 使用规范
- 使用静态 Handler + 弱引用
- 在 onDestroy 中移除所有消息

\`\`\`kotlin
// ✅ 正确
class MainActivity : AppCompatActivity() {
    private val handler = MyHandler(this)

    override fun onDestroy() {
        super.onDestroy()
        handler.removeCallbacksAndMessages(null)
    }

    private class MyHandler(activity: MainActivity) : Handler(Looper.getMainLooper()) {
        private val activityRef = WeakReference(activity)

        override fun handleMessage(msg: Message) {
            activityRef.get()?.handleMessage(msg)
        }
    }
}
\`\`\`

效果:

1. immediate(立即生效): 下次使用 Claude Code 生成代码时,自动符合新规范
2. Prevention(预防问题): 类似的内存泄漏问题不再出现
3. Knowledge Transfer(知识传递): 新入职的开发者通过 AI 生成的代码学习最佳实践

关键点 ：这个规范应该放在 rules/security.md 中，而不是 CLAUDE.md。CLAUDE.md 只存放项目事实（如技术栈、常用命令），详细的规则约束都应该放在 rules/ 目录下。

4.4 版本管理:宪法的演进历史

为什么需要版本管理?

• 追溯规范变更的原因和时间
• 回滚不合理的规范修改
• 了解团队规范的演进路径

实践方法:

# 1. CLAUDE.md 和 rules/ 与代码一起提交到 Git
git add CLAUDE.md .claude/rules/
git commit -m "docs(claude): add memory leak prevention rules"

# 2. 查看宪法演进历史
git log --oneline -- CLAUDE.md .claude/rules/

# 输出:
a1b2c3d docs(claude): add memory leak prevention rules
d4e5f6g docs(claude): update naming conventions
g7h8i9j docs(claude): add security guidelines
j0k1l2m docs(claude): initial team constitution

# 3. 查看某次修改的具体内容
git show a1b2c3d

# 4. 回滚到之前的版本(如果需要)
git checkout d4e5f6g -- CLAUDE.md .claude/rules/

版本号管理(可选):

# Team Constitution

**Version**: 2.3.0
**Last Updated**: 2026-01-29
**Changelog**: See CLAUDE_CHANGELOG.md

## Version History
- v2.3.0 (2026-01-29): Add Android memory leak prevention
- v2.2.0 (2026-01-15): Update testing requirements
- v2.1.0 (2026-01-05): Add security guidelines
- v2.0.0 (2025-12-20): Major refactor, adopt Clean Architecture
- v1.0.0 (2025-12-01): Initial team constitution

4.5 团队协作:宪法的共同维护

维护策略:

## 团队宪法维护指南

### 谁可以修改?
- 所有团队成员都可以提出修改建议
- Tech Lead 负责最终审核

### 修改流程
1. 发现问题或改进点
2. 创建 Issue 讨论必要性
3. 提交 PR 修改 CLAUDE.md 或 .claude/rules/ 下的规则文件
4. Tech Lead 审核
5. 合并后全员通知

### 定期回顾
- 每月: 团队会议回顾宪法执行情况
- 每季度: 全面审查和优化

沟通机制:

# 示例: PR 提交说明

## 为什么需要这个修改?
在最近的 Code Review 中,我们发现多个 PR 都出现了日期格式不统一的问题:
- 有的用 `YYYY-MM-DD`
- 有的用 `MM/DD/YYYY`
- 有的用时间戳

这导致前后端对接时经常出错。

## 提议的规范
统一使用 ISO 8601 格式(`YYYY-MM-DDTHH:mm:ssZ`)

## 影响范围
- 前端展示日期时需要格式化
- 后端 API 返回统一格式
- 数据库存储使用 UTC 时间

## 相关讨论
Issue #123: Date format inconsistency

---

五、实战案例:构建 Android 团队的团队宪法

5.1 目录结构

android-project/
├─ CLAUDE.md
└─ .claude/
   └─ rules/
      ├─ security.md
      ├─ testing.md
      └─ coding-style.md

5.2 CLAUDE.md：项目事实

# Android Project - Claude Code Configuration

## 项目概述
- 技术栈：Kotlin 1.9+、Android 14 (API 34)、MVVM + Clean Architecture
- DI：Hilt
- Async：Coroutines + Flow
- UI：Jetpack Compose
- Testing：JUnit5, Mockk, Espresso

## 目录结构入口
- `app/src/main/java/` - 源代码目录
- `app/src/test/java/` - 单元测试目录
- `app/src/androidTest/java/` - UI 测试目录

## 常用命令（必须准确）
- 安装依赖：`./gradlew build`
- 运行测试：`./gradlew test`
- 运行 UI 测试：`./gradlew connectedAndroidTest`
- 构建 APK：`./gradlew assembleDebug`
- 代码格式化：`./gradlew ktlintFormat`
- 静态检查：`./gradlew ktlintCheck`

## 约束（团队共识）
- 默认先用 Plan Mode 分析，再动代码
- 任何会影响行为的改动：必须补测试/补文档
- 涉及凭证/权限：先安全审查，再合并
- ViewModel 不持有 Activity/Fragment 引用
- 网络/数据库操作必须使用 suspend 函数

5.3 rules/coding-style.md：代码风格底线

# Kotlin 代码风格规范

## 命名约定
- 类/接口: PascalCase (UserRepository)
- 函数/属性: camelCase (getUserById)
- 常量: UPPER_SNAKE_CASE (MAX_RETRY_COUNT)
- 包名: 小写,单词间用点分隔 (com.example.app)

## 属性声明
- 优先使用 `val` 而不是 `var`
- 私有属性使用 `private` 显式标记
- 可空类型明确标注 `?`

## 异步编程
- 使用 Coroutines,避免 Callback
- 网络/数据库操作使用 `suspend` 函数
- UI 层使用 `StateFlow` / `SharedFlow`

## 资源命名
- Drawable: `ic_*` (图标), `bg_*` (背景), `img_*` (图片)
- Layout: `activity_*.xml`, `fragment_*.xml`, `item_*.xml`
- String: 模块_功能_描述 (`user_profile_title`)

5.4 rules/testing.md：测试底线

# 测试规范

## 单元测试
- 覆盖率: > 80%
- UseCase 和 Repository 必须有单元测试
- 使用 Mockk 进行 Mock
- 测试用例命名: `should ... when ...`

## UI 测试
- 关键流程必须有 Espresso 测试
- 使用 Hilt Test 进行依赖注入

## TDD 流程
- RED: 先写失败的测试
- GREEN: 实现最小代码让测试通过
- REFACTOR: 重构优化代码

5.5 rules/security.md：安全底线

# 安全规范

## 敏感信息处理
- ❌ 禁止: 将密钥/密码硬编码到代码中
- ✅ 使用: BuildConfig 或 NDK 存储 API Key
- ✅ 使用: EncryptedSharedPreferences 存储用户密码/Token

## 内存泄漏防护
- ViewModel 不持有 Activity/Fragment 引用
- 长生命周期对象使用 ApplicationContext
- 使用 Lifecycle-aware 组件

## 权限请求
- 使用 ActivityResultContracts
- 说明权限用途,提升授权率

---

六、最佳实践与建议

6.1 如何编写有效的宪法条款

原则 1: 具体而非抽象

❌ 不好的例子:

- 代码应该写得清晰
- 注释要写好
- 性能要优化

✅ 好的例子:

- 所有公共 API 必须添加 JSDoc 注释,包含参数说明和示例
- 函数复杂度不超过 15(Cyclomatic Complexity)
- API 响应时间 P95 < 200ms

原则 2: 提供正反示例

### 错误处理

✅ 正确:
\`\`\`typescript
try {
  const data = await fetchData();
  return data;
} catch (error: unknown) {
  if (error instanceof NetworkError) {
    logger.error('Network request failed', { error });
    throw new ServiceUnavailableError('Service temporarily unavailable');
  }
  throw error;
}
\`\`\`

❌ 错误:
\`\`\`typescript
try {
  const data = await fetchData();
  return data;
} catch (e) {
  console.log(e);  // 只打印日志,不处理
  return null;     // 吞掉异常
}
\`\`\`

原则 3: 说明"为什么"

### 优先使用 `const` 而不是 `let`

**原因**:
- 提高代码可读性:变量不可变更,减少认知负担
- 避免意外修改:防止 bug
- 优化性能:编译器可以更好地优化

**例外情况**:
- 循环计数器
- 累加器变量

原则 4: 设置优先级

## 编码规范优先级

### P0 (必须遵守,否则拒绝合并)
- 所有敏感信息不得硬编码
- 必须通过单元测试
- 不得出现 ESLint error

### P1 (强烈建议,Code Review 会提出)
- 公共 API 必须有 JSDoc
- 复杂逻辑必须有注释
- 测试覆盖率 > 80%

### P2 (建议,但不强制)
- 使用 TypeScript 类型推断简化代码
- 优先使用函数式编程

6.2 如何让 AI 理解和遵守规范

技巧 1: 使用清晰的标记

## 规范标记说明

- ✅ **必须**: 强制执行,不可违反
- ⚠️ **推荐**: 强烈建议,有特殊原因可例外
- 💡 **建议**: 最佳实践,可根据情况调整
- ❌ **禁止**: 绝对不允许

技巧 2: 结构化组织

按照官方推荐的目录结构组织：

your-repo/
├─ CLAUDE.md              # 项目事实
└─ .claude/
   └─ rules/              # 底线规则
      ├─ security.md
      ├─ testing.md
      └─ coding-style.md

每个文件职责单一，便于维护和审查。

技巧 3: 使用关键词强调

### 安全规范

⚠️ **CRITICAL**: 绝对不允许将密钥硬编码到代码中

❌ **NEVER** do this:
\`\`\`typescript
const API_KEY = 'sk-1234567890abcdef';
\`\`\`

✅ **ALWAYS** use environment variables:
\`\`\`typescript
const API_KEY = process.env.API_KEY;
\`\`\`

技巧 4: 提供决策树

### 何时使用缓存?

\`\`\`
数据是否频繁读取?
  ├─ 是 → 数据是否经常变化?
  │       ├─ 是 → 使用短 TTL 缓存(5分钟)
  │       └─ 否 → 使用长 TTL 缓存(1小时)
  └─ 否 → 不使用缓存,直接查询
\`\`\`

6.3 团队推广策略

阶段 1: 试点项目(第1周)

1. 选择一个小型项目作为试点
2. 编写基础的 CLAUDE.md（项目事实）和 rules/ 目录（核心规范）
3. 团队成员轮流使用 Claude Code
4. 收集反馈,快速迭代

阶段 2: 规范完善(第2-4周)

1. 根据实际使用发现的问题更新规范
2. 添加更多示例和说明
3. 组织团队培训,讲解规范的价值
4. 建立规范更新机制

阶段 3: 全面推广(第5-8周)

1. 在所有项目中启用 claude.md
2. 将 claude.md 检查加入 CI/CD 流程
3. 定期回顾和优化规范
4. 分享成功案例和数据

阶段 4: 持续改进(长期)

1. 建立复利模式:发现问题 → 更新宪法
2. 跟踪指标:代码质量、Code Review 时间、Bug 数量
3. 定期团队分享:最佳实践、踩坑经验
4. 版本管理:重大更新时升级版本号

推广技巧:

### 让团队接受 claude.md 的技巧

1. **展示收益,不是约束**
   - "这能让 Code Review 时间减少 50%"
   - "新人上手速度提升 3 倍"
   - "Bug 数量下降 40%"

2. **从痛点出发**
   - "还记得上周那个低级 Bug 吗?如果有规范就能避免"
   - "每次 Code Review 都在说同样的问题,累不累?"

3. **小步快跑**
   - 不要一次性写 100 条规范
   - 从 3-5 条核心规范开始（放在 rules/ 目录）
   - 逐步完善,让团队适应

4. **让大家参与**
   - 规范不是 Tech Lead 一个人定的
   - 鼓励所有人提出改进建议
   - 定期讨论和投票决定重要条款

---

七、总结与行动指南

7.1 核心要点回顾

通过本文,我们深入探讨了 claude.md 作为"团队宪法"的价值:

1. 为什么需要团队宪法?

• 传统规范靠人肉执行,效率低、易遗漏
• AI 辅助开发需要明确规范,否则代码质量参差不齐
• claude.md 是自动化、统一、可演进的解决方案

2. claude.md 的工作机制

• 两级配置:全局 + 项目,项目配置覆盖全局配置
• 作为系统提示词注入到每次 AI 调用,优先级高于对话历史

3. 团队宪法的内容设计

• CLAUDE.md：项目事实（技术栈、常用命令、约束）
• rules/ 目录：底线规则（security.md、testing.md、coding-style.md）

4. 复利模式:持续演进

• 发现问题 → 更新宪法 → 全员受益
• 版本管理:Git 跟踪规范演进
• 团队协作:共同维护,定期回顾

5. 实战案例:Android 团队

• 完整的 CLAUDE.md 和 rules/ 目录示例
• 职责分离：CLAUDE.md 存项目事实，rules/ 存规则约束
• 数据证明:Code Review 时间减少 80%

---

💡 思考题: 你的团队目前有哪些规范执行不到位的问题?如果用 CLAUDE.md 和rule来解决,你会先写哪 3 条规范?

🔗 相关文章:

• 上一篇: 深入理解 Claude Code

---

📥 下载资源:

• Awesome AI Coding - 覆盖大部分开发领域的规则集合

如果这篇文章对你有帮助,欢迎点赞、收藏、分享!有任何问题或建议,欢迎在评论区留言讨论。让我们一起学习,一起成长!

也欢迎访问我的个人主页发现更多宝藏资源