来源：https://github.com/datawhalechina/vibe-vibe

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

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

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

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

什么时候需要配置

场景：AI 又忘了

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

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

决策流程：

graph TB
    A[开始使用 AI] --> B{个人/团队?}
    B -->|个人| C[对话中说明偏好]
    B -->|团队/多机| D[需要配置]

    C --> E{AI 记住了?}
    E -->|是| F[无需配置]
    E -->|否| G[再次提醒]
    G --> H{多次仍忘记?}
    H -->|否| F
    H -->|是| I[考虑配置文件]

    D --> J[统一配置]
    J --> K[提交到 Git]
    K --> L[所有人拉取后自动生效]

    style F fill:#c8e6c9
    style I fill:#fff3e0
    style D fill:#e3f2fd
    style J fill:#e3f2fd

快速判断：

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

:::

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

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

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

直接让 AI 生成：

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

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

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

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

为什么比自己写快：

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

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

:::

配置文件的本质

graph LR
    A[配置文件] --> B[AI 读取]
    B --> C[理解项目]
    C --> D[生成符合规范的代码]

    E[无配置] --> F[AI 猜测]
    F --> G[风格不一致]

    H[README] --> C
    I[项目文档] --> C

    style H fill:#e3f2fd
    style I fill:#e3f2fd

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

CLAUDE.md 模板

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

# 项目：[项目名称]

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

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

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

创建方式：

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

# 项目说明

CLAUDE.md 进阶用法 ⭐

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

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

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

# Claude Code 会自动追加到 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 命令

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

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

团队协作配置 ⭐

提交哪些配置到 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）：不提交，包含个人密钥

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

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

settings.json 配置详解

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

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

{
  "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}"
      }
    }
  }
}

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

团队配置模板

// .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"]
    }
  }
}

// .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"
      }
    }
  }
}

团队协作工作流

flowchart TD
    A[团队讨论规范] --> B[创建配置文件]
    B --> C[提交到 Git]
    C --> D[团队成员拉取]
    D --> E[AI 自动读取配置]
    E --> F[所有人行为一致]

    G[新成员加入] --> D

    style C fill:#e3f2fd
    style E fill:#c8e6c9
    style F fill:#c8e6c9

实际操作：

# 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 自动读取，无需额外操作

核心理念

配置是手段，不是目的

graph LR
    A[目标: AI 理解项目] --> B[方式1: 对话]
    A --> C[方式2: README]
    A --> D[方式3: 配置文件]
    A --> E[方式4: 项目文档]

    B --> F[选择最简单的方式]
    C --> F
    D --> F
    E --> F

    G[团队协作] --> D
    H[多机开发] --> D

    style B fill:#c8e6c9
    style C fill:#c8e6c9
    style D fill:#e3f2fd

记住：

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文档驱动开发