2.4 项目规则配置 🟡

title: "2.4 项目规则配置"
description: "CLAUDE.md 和项目规则文件，让 AI 理解项目规范"
chapter: "第二章"
priority: ""​

2.4 项目规则配置

阅读完本节后，你将会收获：

• 理解项目配置文件的作用和使用场景
• 掌握 CLAUDE.md 和 settings.json 的配置方法
• 学会团队协作/多机开发的配置共享方案
• 了解如何处理配置中的敏感信息

本节通常可以跳过。个人开发时，AI 能从对话和项目文档中理解项目，无需额外配置。

团队协作/多机开发：需要统一环境、规范、MCP、插件等配置时，本节内容非常有用。

::: warning 个人开发通常不需要配置

在折腾配置文件之前，请先了解：

1. AI 有记忆：对话中告诉 AI 的偏好，它会记住
2. 项目文档足够：README + 第三章的项目文档通常能让 AI 理解项目
3. 配置是补充：只有在 AI 反复忘记某些规则时，才考虑写入配置文件

:::

什么时候需要配置

场景：AI 又忘了

你第 5 次提醒 AI："不要用 npm，用 pnpm"。它还是用了 npm。

你意识到：口头提醒不靠谱，需要写成规则。

决策流程：

快速判断：

本节重点：团队协作/多机开发时，配置文件让所有人用同一套规则。

:::

更简单的方法：让 AI 自己写

场景：要写配置文件，但不知道格式

你打开文档，看到一堆配置项。头大。

直接让 AI 生成：

请根据《AI 调教指南》2.4 节的内容，为我的团队项目创建配置文件。

项目信息：
- Next.js 16 + TypeScript
- 使用 shadcn/ui 组件库
- 用 pnpm 包管理器
- 5人团队，需要统一规范

请生成：
1. CLAUDE.md 项目说明
2. .claude/settings.json 权限配置
​

30 秒后，AI 给你完整的配置文件，直接复制粘贴。

为什么比自己写快：

前提：给 AI 足够的项目信息（技术栈、团队规模、特殊需求）。

AI 知道如何写配置文件，你只需要提供项目信息即可。

:::

配置文件的本质

核心原则：配置文件、README、项目文档——本质上都是让 AI 理解项目的方式。

::: tip 关键洞察

项目配置文件（无论叫什么名字）本质相同：

• 都是写给 AI 看的项目说明书
• 核心内容：技术栈 + 编码规范 + 禁止行为
• 只是不同工具用不同文件名

:::

CLAUDE.md 模板

如果确实需要配置文件，越简洁越好：

# 项目：[项目名称]

## 技术栈
Next.js 16 + TypeScript + Tailwind + shadcn/ui

## 规范
- 禁止 any，严格模式
- PascalCase 命名组件
- 用 pnpm

## 禁止
- 不装新依赖
- 不改 .env
​

创建方式：

• Claude Code：在项目根目录创建 CLAUDE.md
• Cursor/Qoder/Trae：在 IDE 设置中配置规则文件

::: details 完整模板

# 项目说明

## 项目概述
[一句话说明项目做什么]

## 技术栈
- **框架**: Next.js 16 (App Router)
- **语言**: TypeScript (严格模式)
- **数据库**: Drizzle ORM + PostgreSQL
- **样式**: Tailwind CSS
- **组件**: shadcn/ui

## 编码规范
- 禁止 `any` 类型
- 组件用 PascalCase，函数用 camelCase
- 使用 pnpm（不要用 npm/yarn）

## 禁止行为
- ❌ 不要安装新依赖除非明确要求
- ❌ 不要修改 .env 文件
- ❌ 不要删除测试文件

## 目录结构
app/         # 页面和 API
components/  # 组件
lib/         # 工具函数
​

:::

CLAUDE.md 进阶用法 ⭐

::: tip 本节重点

掌握 CLAUDE.md 的高级特性，让项目配置更模块化、更易维护。

:::

记忆命令：让 AI 自动更新配置

在对话中使用 # 前缀，Claude Code 会自动将内容写入 CLAUDE.md：

# 对话中输入：
"# 本项目使用 pnpm 作为包管理器，不要使用 npm"
"# 数据库用 PostgreSQL + Drizzle ORM"
"# 组件库用 shadcn/ui，不要安装其他 UI 库"

# Claude Code 会自动追加到 CLAUDE.md，无需手动编辑
​

::: warning 注意
记忆命令写入的内容会追加到 CLAUDE.md 末尾。如果积累太多，建议定期整理归类。
:::

模块化规则：.claude/rules/ 目录

当 CLAUDE.md 变得很长时，可以拆分到 .claude/rules/ 目录：

.claude/
├── CLAUDE.md              # 项目概述和核心规则
└── rules/
    ├── coding-style.md    # 代码风格规范
    ├── git-workflow.md    # Git 工作流
    ├── testing.md         # 测试要求
    └── security.md        # 安全规则
​

Claude Code 会自动加载 rules/ 目录下的所有 .md 文件，与 CLAUDE.md 合并生效。

何时用 rules/ 目录 vs 单个 CLAUDE.md：

构建/测试/Lint 命令

::: warning 重要

在 CLAUDE.md 中声明项目的构建命令，是避免 AI "猜错包管理器"的关键手段。

:::

## 常用命令
- 安装依赖：`pnpm install`
- 开发服务器：`pnpm dev`
- 构建：`pnpm build`
- 测试：`pnpm test`
- Lint：`pnpm lint`
- 类型检查：`pnpm typecheck`
​

如果不声明，AI 可能会用 npm run build 或 yarn test——在 pnpm 项目中这会导致依赖解析错误。

团队协作配置 ⭐

::: tip 本节重点

团队协作/多机开发是配置文件最重要的使用场景。通过提交配置到 Git，确保所有成员的 AI 行为一致。

:::

提交哪些配置到 Git

# ✅ 应该提交
.claude/settings.json      # 项目级系统配置（不含敏感信息）
.mcp.json                   # MCP 服务器配置（不含敏感信息）
CLAUDE.md                  # 项目说明（Claude Code）
.cursorrules               # 编码规范（Cursor）
.iderules                  # 编码规范（Qoder/Trae）
.claude/skills/            # 团队 Skills（见 2.3 节）

# ❌ 不应该提交
.env                       # 环境变量（包含密钥）
node_modules/              # 依赖包
~/.claude/settings.json    # 用户级配置（个人密钥）
​

处理敏感信息

方法：分层配置

• 项目级配置（.claude/settings.json）：提交到 Git，不含密钥
• 用户级配置（~/.claude/settings.json）：不提交，包含个人密钥

::: details 配置示例

用户级配置（~/.claude/settings.json，不提交）：

{
  "env": {
    "GITHUB_TOKEN": "ghp_xxx",
    "OPENAI_API_KEY": "sk_xxx"
  }
}
​

项目级配置（.claude/settings.json，提交到 Git）：

{
  "permissions": {
    "defaultMode": "plan"
  }
}
​

:::

::: tip 安全原则

• ✅ 项目配置：提交到 Git，不含密钥
• ✅ 用户配置：不提交，包含个人密钥
• ❌ 不要把任何密钥写进项目配置文件

:::

settings.json 配置详解

::: details 什么是 settings.json

settings.json 是 Claude Code 的系统配置文件，控制权限模式、环境变量、Hooks、MCP 服务器等。

与 CLAUDE.md 的区别：

• CLAUDE.md：写给 AI 看的项目说明书
• settings.json：控制工具行为的系统配置

配置文件位置：

优先级规则：本地级 > 项目级 > 用户级。

:::

::: details 配置结构

{
  "permissions": {
    "defaultMode": "plan"
  },
  "hooks": {},
  "env": {}
}
​

权限模式选择：

:::

::: details Hooks 配置

Hooks 在特定事件时自动执行脚本，详见 2.2 VibeCoding 工作流 - Hooks 自动化 (./02-vibecoding-workflow.md)。

基本结构：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format.sh"
          }
        ]
      }
    ]
  }
}
​

常用事件：

:::

::: details MCP 服务器配置

MCP 服务器配置让 AI 能够连接外部服务。

项目级配置（.mcp.json，推荐）：

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}
​

settings.json 中的配置（旧方式，仍支持）：

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}
​

常用 MCP 服务器：

:::

团队配置模板

::: details 前端团队模板

// .claude/settings.json
{
  "permissions": {
    "defaultMode": "acceptEdits",
    "disallowedTools": ["Bash(rm -rf:*)", "Bash(write .env:*)"]
  },
  "env": {
    "PACKAGE_MANAGER": "pnpm"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "pnpm format --write \"$CLAUDE_PROJECT_DIR\"/@file_path"
          }
        ]
      }
    ]
  }
}
​

// .mcp.json
{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "$CLAUDE_PROJECT_DIR"]
    }
  }
}
​

:::

::: details 后端团队模板

// .claude/settings.json
{
  "permissions": {
    "defaultMode": "plan",
    "disallowedTools": ["Bash(DROP TABLE:*)", "Bash(DELETE FROM:*)"]
  }
}
​

// .mcp.json
{
  "mcpServers": {
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}",
        "PG_READONLY": "true"
      }
    }
  }
}
​

:::

团队协作工作流

实际操作：

# 1. 团队负责人创建配置
vim CLAUDE.md
vim .claude/settings.json
vim .mcp.json

# 2. 提交到 Git
git add CLAUDE.md .claude/ .mcp.json
git commit -m "docs: 添加团队 AI 配置"
git push origin main

# 3. 团队成员拉取
git pull origin main

# 4. AI 自动读取，无需额外操作
​

核心理念

配置是手段，不是目的

记住：

1. 对话优先：先沟通，再配置
2. 文档为主：README 和项目文档更完整
3. 配置为辅：团队协作时才必需
4. 让 AI 帮你：把文档给 AI，让它自己生成配置

常见问题

Q1: CLAUDE.md 和 .cursorrules 有区别吗？

A: 本质一样，只是文件名不同。

核心内容都是：技术栈 + 编码规范 + 禁止行为

Q2: settings.json 修改后不生效？

A: 检查以下几点：

1. JSON 格式：确保格式正确
2. 文件位置：确认是项目级还是用户级
3. 优先级：本地级会覆盖项目级

Q3: 团队协作如何统一配置？

A: 提交到 Git，所有人拉取后自动生效。

# 提交配置
git add CLAUDE.md .claude/settings.json .mcp.json
git commit -m "docs: 添加团队 AI 配置"
git push

# 成员拉取
git pull
​

Q4: 如何处理个人密钥？

A: 使用分层配置。

• 项目级 (.claude/settings.json)：提交到 Git，不含密钥
• 用户级 (~/.claude/settings.json)：不提交，包含个人密钥
• 使用 ${VAR_NAME} 引用环境变量

相关内容

• 前置：2.2 VibeCoding工作流详解
• 详见：2.3 MCP、插件与 Skills
• 详见：10.10 Skills 团队知识共享
• 详见：10.11 Agent Skills 团队协作
• 后续：第三章 PRD文档驱动开发