第二阶段：进阶配置

沉淀沉淀再沉淀
5 阅读26分钟

第二阶段：进阶配置 🚀

目标：能配置项目规范，提升团队协作效率

本阶段学习地图

2.1 CLAUDE.md 配置体系（最重要）
    ↓
2.2 settings.json 权限与运行时配置
    ↓
2.3 上下文管理进阶
    ↓
2.4 常用工作流命令
    ↓
2.5 实战练习

文件结构

# 进阶配置/
├── 本文件（阶段导航）
├── CLAUDE.md 配置深度指南
├── settings.json 配置参考
├── 上下文管理进阶技巧
├── 工作流命令实战
├── 团队协作配置
└── 实战练习题

核心理念

CLAUDE.md 是你控制 Claude 行为最强大的工具

在项目中放一个好的 CLAUDE.md，相当于给 Claude 一份详细的工作手册，让它：

  • 了解项目的技术栈和规范
  • 知道哪些事情绝对不能做
  • 在不确定时做出正确的默认选择

阶段完成标准

  • 为一个真实项目创建了有效的 CLAUDE.md
  • 配置了 settings.json 限制危险命令权限
  • 使用 /commit 自动生成过规范的 commit message
  • 理解 CLAUDE.md 的层级覆盖机制
  • 能识别并处理上下文污染问题

常见问题 FAQ

Q1：CLAUDE.md 写了，但 Claude 好像没有遵守里面的规范

排查步骤：

# 1. 确认文件在当前工作目录（不是父目录或子目录）
ls ./CLAUDE.md

# 2. 验证 Claude 是否读取到了配置
claude
> 你知道这个项目禁止使用哪些依赖吗？
# Claude 能正确回答 → 配置已生效
# Claude 说"不知道" → 配置未读取，检查文件位置

最常见的原因：CLAUDE.md 放错位置了。必须放在执行 claude 命令时所在的目录。

Q2：@引用 外部文件的路径写对了，但 Claude 说找不到

# 常见错误写法（~ 未展开）
@~/Documents/git/team-knowledge/shared-config/CLAUDE.md

# 某些情况下需要写绝对路径
@/Users/yourname/Documents/git/team-knowledge/shared-config/CLAUDE.md

用 echo ~/Documents/git/... 确认路径实际存在。

Q3：settings.json 的 deny 规则写了，但 Claude 还是执行了危险命令

检查 JSON 格式（JSON 不能有注释、多余逗号）：

# 验证 JSON 格式是否正确
python3 -m json.tool ~/.claude/settings.json
# 如果有错误，会提示具体行数

检查规则语法：

// 错误：禁止了所有 Bash 命令
"deny": ["Bash"]

// 正确：只禁止特定命令
"deny": ["Bash(rm -rf *)"]

Q4：/commit 生成的 commit message 不符合我们的规范

Claude 会参考项目的 git log 历史来学习风格。如果历史 commit 风格不一致，生成的质量也会参差不齐。

解决方案：在 CLAUDE.md 中明确 commit 规范：

## Commit 规范
格式：<type>(<scope>): <描述>
类型：feat/fix/refactor/test/docs/chore
示例：feat(order): 新增批量取消订单接口
禁止：commit message 不能包含"完成"、"修改"等模糊词

Q5：上下文被污染了，Claude 一直基于错误的前提回答

识别症状：

  • Claude 坚持一个你已经否定过的前提
  • Claude 混淆了两个不同功能的代码
  • Claude 说"按照之前我们确认的方案..."但那个方案其实是错的

处理方法：

轻微污染（明确纠正）：
> 注意：之前我们说的 X 方案已经被否定了，
  正确的前提是 Y，请基于 Y 重新分析

严重污染（重开会话）：
> 在我们清空会话前，列出这次对话的关键结论
/clear
（将关键结论粘贴到新会话开头）

Q6：/dev-fix-bug 触发后，Claude 跳过了门控，直接开始改代码

这说明 Skill 没有被正确加载，Claude 在"普通对话"模式下响应，而不是按 Skill 流程执行。

确认 Skill 是否已安装：

ls ~/.claude/skills/
# 应该能看到 dev-fix-bug 等目录

Q7：CLAUDE.md 越写越长，Claude 每次对话都很慢

原因：CLAUDE.md 每次都会被完整注入，文件越大 token 成本越高。

优化策略：

# CLAUDE.md 只保留核心内容（< 150 行）
## 技术栈
- React 18 + TypeScript

## 禁止行为（最重要的 5 条）
...

# 把详细规范移到外部文件，按需引用
@./docs/component-guidelines.md    ← 开发组件时才需要
@./docs/api-conventions.md         ← 开发接口时才需要

2.1 CLAUDE.md 配置体系

CLAUDE.md 是 Claude Code 最重要的配置机制，它定义了 Claude 在项目中的行为规范。

配置层级

优先级（高 → 低）：

项目根 ./CLAUDE.md          ← 最高优先级，项目专属规范
    +
~/.claude/CLAUDE.md         ← 用户全局配置
    +
@引用的外部配置文件          ← 团队共享配置

规则：层级高的配置会覆盖低层级的冲突配置。

文件放置位置

# 项目级（最常用）
your-project/CLAUDE.md

# 用户全局级
~/.claude/CLAUDE.md

# 子目录级（针对特定模块）
your-project/src/components/CLAUDE.md

CLAUDE.md 核心内容

技术栈说明

让 Claude 了解项目用什么，避免它推荐不兼容的方案：

## 技术栈
- 运行时：Node.js 20
- 前端框架：React 18 + TypeScript 5
- 样式方案：Tailwind CSS（禁止使用内联 style 和 CSS Modules）
- 组件库：Ant Design（禁止引入其他 UI 库）
- 状态管理：Zustand（禁止引入 Redux）
- 构建工具：Vite 5
- 包管理：pnpm（禁止使用 npm 或 yarn）

代码规范

## 代码规范
- 组件文件：PascalCase（UserProfile.tsx）
- 工具函数：camelCase（formatDate.ts）
- 常量：SCREAMING_SNAKE_CASE（MAX_RETRY_COUNT）
- 接口命名：I 前缀（IUserProfile）或 Type 后缀（UserProfileType）
- 禁止使用 any 类型，使用 unknown 代替
- 所有异步函数必须有错误处理

禁止行为（最重要）

禁止行为是给 Claude 设置的"护栏"——防止它基于错误理解做出意料之外的操作。明确的"禁止"比模糊的"应该"有效 10 倍：禁止使用 any 比 尽量避免 any 约束力强得多。

## 禁止行为
- 禁止修改 3 个以上文件而不先出方案
- 禁止未运行验证命令就宣布完成
- 禁止引入未在 package.json 声明的依赖
- 禁止使用 console.log 调试，使用项目的 logger 工具
- 禁止硬编码用户可见的文字，必须使用 i18n 国际化包裹

项目结构

## 目录结构
src/
├── components/   ← 通用组件（无业务逻辑）
├── pages/        ← 页面组件（包含业务逻辑）
├── hooks/        ← 自定义 Hook
├── api/          ← API 接口定义和调用
├── types/        ← TypeScript 类型定义
├── utils/        ← 工具函数（纯函数，无副作用）
└── stores/       ← 状态管理

开发规范

## 开发规范
- 新增功能前必须查阅 src/api/ 确认接口是否已存在
- 组件 props 必须定义 TypeScript 接口
- 新页面必须在 src/router.ts 注册路由
- 涉及权限的页面必须包裹权限守卫组件

@引用语法

可以引用外部文件作为配置的一部分。完整的 @ 语法规则详见 @ 引用语法完整指南。

# ~/.claude/CLAUDE.md

# 引入团队共享配置
@~/Documents/shared-config/team-standards.md

# 引入项目 API 约定文档
@./docs/api-conventions.md

# 引入组件开发规范
@./docs/component-guidelines.md

引用的文件内容会被完整加入 Claude 的上下文，适合放稳定的、通用的规范文档。

实用模板

前端项目模板

# 项目名称 Frontend

## 技术栈
- React 18 + TypeScript + Vite
- Tailwind CSS
- Ant Design 组件库

## 禁止行为
- 禁止修改 3+ 文件不先出方案
- 禁止硬编码用户文本，必须用 i18n 包裹
- 禁止引入未声明的依赖

## 验证命令
- 类型检查：pnpm type-check
- 代码规范：pnpm lint
- 单元测试：pnpm test

Java 后端项目模板

# 项目名称 Backend

## 技术栈
- Java 21 + Spring Boot 3
- MyBatis-Plus
- Redis

## 分层规范
- Controller：仅做参数校验和调用 Service
- Service：业务逻辑，禁止直接操作 DAO
- Repository/Mapper：仅数据操作
- VO/DTO：响应/请求对象，禁止直接暴露 Entity

## 禁止行为
- 禁止在 Service 层直接调用另一个 Service 的 Mapper
- 禁止使用 System.out.println，使用 @Slf4j 的 log

Monorepo / 多包项目模板

# Monorepo 项目

## 仓库结构
packages/
├── frontend/   ← React + TypeScript
├── backend/    ← Java 21 + Spring Boot
└── shared/     ← 共享类型定义

## 通用禁止行为
- 禁止跨包直接引用（必须通过 shared/ 导出的类型）
- 禁止修改 3+ 文件不先出方案
- 禁止在 shared/ 里写业务逻辑（只放类型/常量）

## 包级规范
- frontend
- backend

## 验证命令
- 全量构建：pnpm -r build
- 全量测试：pnpm -r test

然后在各子目录放对应的专属 CLAUDE.md，只写该包的特有规范。

验证你的 CLAUDE.md 是否生效

# 在项目目录下启动 Claude
claude

# 问 Claude 项目的技术栈
> 这个项目用什么技术栈？

# 如果 Claude 能正确回答，说明 CLAUDE.md 已被读取

更完整的验证方式：

claude
> 列出你从 CLAUDE.md 中了解到的所有规范（技术栈、禁止行为、验证命令等）

这样可以一次确认 Claude 读取了哪些内容，帮助你发现遗漏。

CLAUDE.md 的层级加载顺序

启动时自动读取（优先级从低到高）：

1. ~/.claude/CLAUDE.md                  全局配置（对所有项目生效）
        ↓（合并）
2. ./CLAUDE.md                          项目根目录配置
        ↓（合并）
3. 子目录 CLAUDE.md（如有）             子模块专属配置

冲突时的行为：层级越高（越靠近项目）的配置优先。例如：

  • 全局配置说"使用 pnpm"
  • 项目配置说"使用 npm"
  • 结果：Claude 在这个项目里使用 npm

@引用 文件的时机：CLAUDE.md 加载时，@引用 的文件会被完整合并进来，等同于把外部文件内容写在 CLAUDE.md 里，每次都会加载。

写作原则

  • 明确的"禁止"比模糊的"应该"更有效：禁止使用 any 比 尽量避免 any 效果好 10 倍
  • 控制在 150 行以内：每次对话都会加载，太长消耗 token
  • 详细规范移到外部文件：通过 @ 按需引用，不要全部写进主文件
  • 验证命令必须写：Claude 改完代码不知道该跑什么验证，就容易只说"完成了"

常见写作误区

❌ 误区一：只写"应该"，没有写"禁止"
## 规范
应该使用 pnpm
尽量避免 any 类型

✅ 改进：
## 禁止行为
- 禁止使用 npm 或 yarn，必须使用 pnpm
- 禁止使用 any 类型，用 unknown 代替

---

❌ 误区二：规范太模糊，Claude 有自由发挥的空间
## 代码质量
请保持代码简洁

✅ 改进：
## 代码规范
- 函数超过 30 行必须拆分
- 禁止嵌套超过 3 层的 if/else，使用提前返回

---

❌ 误区三：写了验证命令，但没有要求 Claude 执行
## 验证
pnpm type-check

✅ 改进：
## 验证命令（修改代码后必须执行）
- 类型检查：pnpm type-check
- 代码规范：pnpm lint
- 单元测试：pnpm test
- 禁止在以上命令通过前宣布任务完成

2.2 settings.json 配置参考

settings.json 控制 Claude Code 的运行时行为，包括权限、模型、MCP 服务器等。

为什么要配置权限？

Claude Code 默认会在执行每个操作前询问你是否允许，这会打断工作节奏。通过配置权限规则：

  • allow：预先授权安全操作（如 git、测试命令），不再反复询问
  • deny：永久禁止危险操作（如 rm -rf），防止意外执行

配置好后，Claude 在允许范围内自动执行，遇到禁止操作直接拒绝，既流畅又安全。

文件位置

~/.claude/settings.json          ← 全局配置（对所有项目生效）
./.claude/settings.json          ← 项目级配置（仅当前项目）

完整配置结构

{
  "model": "claude-opus-4-6",
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-xxxxx"
  },
  "permissions": {
    "allow": [],
    "deny": []
  },
  "mcpServers": {},
  "hooks": {}
}

权限配置详解

权限规则语法

{
  "permissions": {
    "allow": [
      "Read",              // 允许所有文件读取
      "Write",             // 允许所有文件写入
      "Edit",              // 允许所有文件编辑
      "Bash(git *)",       // 只允许 git 相关命令
      "Bash(npm test)",    // 只允许运行测试
      "Bash(npm run *)"    // 允许所有 npm run 命令
    ],
    "deny": [
      "Bash(rm -rf *)",    // 禁止危险删除
      "Bash(sudo *)",      // 禁止 sudo
      "Bash(curl *)",      // 禁止外部网络请求
      "Bash(wget *)"       // 禁止下载
    ]
  }
}

权限匹配规则

  • * 匹配任意字符串（包括空格）
  • 精确匹配："Bash(git status)" 只允许 git status
  • 前缀匹配："Bash(git *)" 允许所有 git 命令
  • deny 优先于 allow

推荐的安全配置

{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Edit",
      "Glob",
      "Grep",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(npm run *)",
      "Bash(pnpm *)",
      "Bash(ls *)",
      "Bash(cat *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(git push --force *)",
      "Bash(git reset --hard *)",
      "Bash(DROP TABLE *)",
      "Bash(DELETE FROM *)"
    ]
  }
}

模型配置

{
  "model": "claude-opus-4-6"
}

可用模型：

模型 ID特点适用场景
claude-opus-4-6最强，最贵复杂编码、架构设计
claude-sonnet-4-6均衡日常开发、代码审查
claude-haiku-4-5-20251001最快，最省简单任务、快速问答

环境变量配置

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-xxxxx",
    "NODE_ENV": "development",
    "CUSTOM_VAR": "value"
  }
}

这些变量会在 Claude 执行 Bash 命令时作为环境变量传入。

配置优先级

项目级 settings.json > 全局 settings.json

项目级配置会合并（不是覆盖）到全局配置上，适合覆写特定项目的权限规则。

常见配置场景

场景一：只读模式（演示/查阅）

{
  "permissions": {
    "allow": ["Read", "Glob", "Grep"],
    "deny": ["Write", "Edit", "Bash"]
  }
}

场景二：CI/CD 环境（受限自动化）

{
  "permissions": {
    "allow": [
      "Read", "Glob", "Grep",
      "Bash(npm test)",
      "Bash(npm run build)",
      "Bash(git *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(npm publish *)"
    ]
  }
}

场景三：完全自动化（谨慎使用）

# 使用命令行参数跳过所有权限检查
claude --dangerously-skip-permissions "执行某个自动化任务"

警告：这会允许 Claude 执行任意命令，仅在受控环境下使用。

在 CI/CD 流水线中使用 Claude Code

Claude Code 可以集成到 CI/CD 流程中，自动完成代码检查、类型验证、测试生成等任务。

基本原则

CI/CD 中使用 Claude Code 需要注意三点：

  1. 必须非交互模式：用 -p 参数，不能等待用户输入
  2. 必须有明确退出码：用 --output-format json 或检查 Claude 输出决定流水线是否继续
  3. 权限要收紧：只允许必要的操作，禁止 push、publish 等不可逆操作

场景一：PR 代码质量检查

在每次 PR 时自动让 Claude 检查代码变更：

# .github/workflows/claude-review.yml（GitHub Actions 示例）
name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run Claude Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # 获取本次 PR 的变更文件
          CHANGED_FILES=$(git diff --name-only origin/main...HEAD)

          # 让 Claude 检查变更
          claude --dangerously-skip-permissions \
                 --no-color \
                 -p "检查以下文件的代码变更是否有明显问题（类型错误、安全漏洞、逻辑错误）：
                     $CHANGED_FILES
                     只报告严重问题（ERROR 级别），忽略风格问题。
                     如果没有严重问题，输出：NO_ISSUES_FOUND"

场景二：自动类型检查并修复

#!/bin/bash
# scripts/claude-typecheck.sh
# 用途：在 CI 中运行类型检查，如果有错误让 Claude 尝试修复

set -e

# 先运行类型检查
if pnpm type-check 2>&1; then
  echo "✓ 类型检查通过"
  exit 0
fi

# 有错误，让 Claude 分析
echo "类型检查失败，让 Claude 分析..."

TYPE_ERRORS=$(pnpm type-check 2>&1 || true)

claude --dangerously-skip-permissions \
       --no-color \
       -p "以下是 TypeScript 类型检查错误：

$TYPE_ERRORS

请分析根因并修复。只修改必要的文件，不要引入新依赖。"

# 再次验证
if pnpm type-check 2>&1; then
  echo "✓ Claude 修复成功"
  exit 0
else
  echo "✗ 修复失败，需要人工处理"
  exit 1
fi

场景三：自动生成测试

# 在 CI 中检测没有测试的新文件，自动生成测试
NEW_FILES=$(git diff --name-only --diff-filter=A origin/main...HEAD | grep -E '\.(ts|tsx)$' | grep -v '\.test\.' || true)

if [ -n "$NEW_FILES" ]; then
  claude --dangerously-skip-permissions \
         --no-color \
         -p "为以下新增文件生成单元测试，参考项目中已有的测试文件风格：
             $NEW_FILES
             测试文件命名规范：在同目录下创建 xxx.test.ts"
fi

CI 环境的 settings.json

{
  "permissions": {
    "allow": [
      "Read", "Glob", "Grep",
      "Write", "Edit",
      "Bash(pnpm *)",
      "Bash(npm run *)",
      "Bash(git diff *)",
      "Bash(git log *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(git commit *)",
      "Bash(npm publish *)",
      "Bash(rm -rf *)"
    ]
  }
}

注意：CI 环境的 ANTHROPIC_API_KEY 必须存储在 CI 平台的 Secrets 中，不能硬编码在配置文件里。

2.3 上下文管理进阶

有效管理上下文是高效使用 Claude Code 的关键，直接影响 token 消耗和回答质量。

理解上下文窗口

把上下文想象成 Claude 的短期记忆：你和它说的越多，它的记忆就越拥挤。/compact 就是"整理笔记"——把冗长的对话压缩成摘要，保留重要信息，丢掉无关细节。

每次对话都有一个"上下文窗口"，包含：
┌────────────────────────────────┐
│  CLAUDE.md 内容（每次自动注入）   │ ~固定成本
│  对话历史（越聊越多）             │ ~增长成本
│  当前消息                       │ ~可控成本
└────────────────────────────────┘
         总计不能超过 token 上限

问题：上下文越长，每轮对话成本越高，且 Claude 可能"忘记"早期内容。

/compact 深度解析

工作原理

执行 /compact 前：
[消息1: 探索代码结构] → [消息2: 分析问题] → [消息3: 方案讨论] → [消息4-15: ...]

执行 /compact 后：
[摘要: "已分析了 auth.ts，发现 token 验证有 race condition，
        当前正在讨论使用 mutex 锁的解决方案..."] → [消息16-...]

何时执行 /compact

  • 对话超过 20 轮
  • 前期探索性内容已经不重要
  • Claude 开始"遗忘"之前的结论
  • 上下文指示器显示用量超过 70%

/compact 的两种用法

基础用法：让 Claude 自动决定保留什么

/compact

带指令用法：告诉 Claude 额外保留什么（推荐）

/compact 请保留所有已确认的技术决策和代码片段
/compact 保留：1.我们决定用 Redis 而非内存缓存 2.validateToken 的 bug 根因是竞态

为什么要带指令：Claude 的自动摘要不一定保留你最看重的内容。显式告知可以确保关键信息不丢失。

/compact 后保留什么

Claude 会智能保留：

  • 当前任务的关键信息
  • 已确认的决策和结论
  • 未完成的任务项
  • 重要的代码片段

会丢弃：

  • 探索过程中的失败尝试
  • 已解决的问题的详细讨论
  • 重复的上下文

/clear 的正确使用时机

/clear    # 完全清空，从零开始

适合 /clear 的情况：

  • ✅ 上一个任务完全结束，切换到全新任务
  • ✅ 上下文被严重污染（Claude 基于错误前提）
  • ✅ 想重新审视同一问题，避免思维定势

不适合 /clear 的情况：

  • ❌ 任务还没完成，只是对话太长了（用 /compact）
  • ❌ 想保留关键结论但减少 token（用 /compact）

减少 token 消耗的技巧

技巧一：精确引用而非泛泛引用

# 消耗大（整个大文件）
> @src/auth/authService.ts 这个文件有什么问题？

# 消耗小（精确范围）
> @src/auth/authService.ts 第 80-120 行的 validateToken 函数有什么问题？

技巧二：先搜索再读取

# 让 Claude 先定位，再读取精确内容
> 在 src/ 目录下找到处理用户登录的函数，然后分析它的安全性
# Claude 会先 Grep，再 Read offset+limit，而不是读整个目录

技巧三：利用知识库减少探索

# 不好：让 Claude 从代码中探索架构
> 帮我理解这个项目的架构

# 好：直接问知识库（如果有的话）
> 查一下 projects.md 里关于这个项目的架构说明

技巧四：复杂任务委派子 Agent

# 搜索类任务委派给子 Agent（Sonnet），节省主会话（Opus）的 token
> [内部会自动]用子 Agent 查找所有使用了废弃 API 的文件

上下文污染的识别与处理

症状：Claude 基于错误的前提给出建议，或者执行了你明确说不要的操作。

识别：

"你不是说过 X 吗？" → Claude 混淆了早期对话的内容
"我没有让你做 Y" → Claude 带入了不相关的上下文

处理方式：

  1. 轻微污染：明确纠正 > 不对，之前的假设是错的，正确情况是...
  2. 严重污染：/clear 重新开始，重新提供关键背景

长任务的上下文规划

对于预计超过 30 轮的大任务：

推荐做法：
1. 阶段一（1-20轮）：探索和分析
   → /compact 保存摘要
2. 阶段二（21-40轮）：方案设计和实现
   → /compact 保存摘要
3. 阶段三（41+轮）：验证和收尾
   → 完成后 /team-learn 回写经验

/clear 前的正确做法

很多人直接 /clear，然后关掉会话。这会丢失本次对话的所有有价值信息。

正确做法：/clear 前先总结

> 在我们 /clear 之前，帮我整理一下：
  1. 本次对话确认的技术方案（列出关键决策）
  2. 已完成的文件改动清单
  3. 还未完成、下次需要继续的任务
  4. 遇到的坑或注意事项

（把上面的输出保存到文本或新会话开头）
/clear

如何查看当前上下文用量

/status

输出示例：

Context window: 23,450 / 200,000 tokens (11%)
Model: claude-opus-4-6
MCP servers: chrome-devtools (connected), webstorm (connected)

参考阈值：

  • 低于 30%：正常
  • 30-60%：考虑在阶段切换时 /compact
  • 超过 70%：建议立即 /compact 或评估是否 /clear
  • 超过 90%：Claude 可能开始遗忘早期内容，回答质量下降

2.4 工作流命令实战

这些是日常开发中最常用的工作流命令，帮你把重复性操作自动化。

/commit - 自动生成 Commit Message

/commit

工作流程

0. 你先用 git add 暂存想提交的文件（Claude 只提交 staged 内容）
   ↓
1. Claude 执行 git status 查看已暂存的变更文件
   ↓
2. Claude 执行 git diff --staged 查看具体变更内容
   ↓
3. Claude 查看最近的 commit 历史，学习项目的 commit 风格
   ↓
4. Claude 生成符合规范的 commit message
   ↓
5. 等待你确认（可以要求修改措辞）
   ↓
6. 执行 git commit

关键：/commit 只会提交已 git add 的文件。如果你没有 stage 任何文件，Claude 会提示你先 git add。

生成效果示例

feat(auth): 添加 JWT token 过期自动刷新机制

- 在 axios 拦截器中检测 401 响应
- token 过期时自动调用 refresh 接口
- 刷新失败时清除本地状态并跳转登录页

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

使用技巧

在执行 /commit 前，先暂存你想提交的文件：

# 暂存特定文件
git add src/api/auth.ts src/hooks/useAuth.ts

# 然后执行
/commit

自定义工作流 Skill（需安装）

以下功能需要安装对应的 Skill 才能使用。Skill 是封装了最佳实践流程的工作流命令， 每个 Skill 都有明确的步骤和门控（等你确认后再执行下一步）。

如何安装 Skill：Skills 是存放在 ~/.claude/skills/ 目录下的 Markdown 文件， 详见第三阶段：高级能力。

Bug 修复全流程 Skill

触发后 Claude 会引导你完成：

Step 1: 描述 bug
  → 你描述症状，提供错误信息和复现步骤

Step 2: 澄清上下文
  → Claude 可能会问：影响范围？是否有日志？最近有什么变更？

Step 3: 定位根因 [门控]
  → Claude 通过 Grep + Read 探索代码，分析根因
  → 输出根因分析，等待你确认

Step 4: 修复方案确认 [门控]
  → Claude 提出修复方案（可能多个选项）
  → 等待你选择方案后再动手

Step 5: 实施修复

Step 6: 验证
  → 给出验证命令，你执行确认修复有效

需求实现全流程 Skill

适合：一个完整的新功能开发，从需求到代码再到验证。

Step 1: 需求输入
  → 粘贴需求文档或描述需求

Step 2: 代码探索
  → Claude 探索相关模块，理解现有实现

Step 3: 澄清问题
  → Claude 列出不确定的点，等你回答

Step 4: 方案设计 [门控]
  → Claude 输出完整的技术方案
  → 必须等你确认后才开始写代码

Step 5: 分阶段实现
  → 按方案逐步实现，每个关键步骤可暂停确认

Step 6: 质量审查 + 自测
  → 自动检查代码质量，给出测试用例

代码审查 Skill

多维度并行审查：

  • 类型安全（TypeScript）
  • 安全漏洞（XSS、注入等）
  • 性能问题
  • 测试覆盖率
  • 代码规范

如何自己创建工作流 Skill

详见第四阶段：专家工作流。

核心思路：在 ~/.claude/skills/my-skill/skill.md 中用 Markdown 描述步骤和门控点， 即可通过 /my-skill 命令触发。

命令使用建议

场景推荐方式
日常提交代码/commit
遇到 bug 需要系统排查安装 bug 修复 Skill 后触发
实现一个完整功能安装需求实现 Skill 后触发
提交前代码自查安装代码审查 Skill 后触发
不想安装 Skill直接用自然语言描述任务，Claude 会随机应变

2.5 团队协作配置

多人团队使用 Claude Code 时，统一配置是保证一致性的关键。

团队配置架构

团队共享仓库
└── shared-config/
    └── CLAUDE.md          ← 团队共享配置（编码规范、禁止行为等）

每个成员的机器：
~/.claude/CLAUDE.md
└── @~/path/to/shared-config/CLAUDE.md  ← 引用团队配置
└── （个人专属配置）

共享配置的核心内容

1. 团队编码标准

## 团队编码标准

### 命名规范
- Java 类：PascalCase
- Java 方法/变量：camelCase
- 数据库表/字段：snake_case
- 前端组件：PascalCase
- 前端工具函数：camelCase

### 分层规范
Controller → Service → Repository
禁止跨层调用

2. 禁止行为（团队级）

## 团队禁止行为
- 禁止修改 3+ 文件不出方案
- 禁止 git push --force 到主分支
- 禁止引入未经团队审批的新依赖
- 禁止在代码中硬编码 IP、密码、密钥

同步机制

自动同步（推荐）

通过 SessionStart Hook 在每次会话开始时自动拉取最新配置：

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "cd ~/path/to/shared-config && git pull --quiet"
      }
    ]
  }
}

手动同步

cd ~/path/to/shared-config && git pull

团队配置版本管理

在 CLAUDE.md 中标注版本，便于追踪：

# 团队共享配置
# 版本: 1.0.0 | 更新: 2026-03-01

新成员入职配置

# 1. 克隆团队配置仓库
git clone <shared-config-repo> ~/path/to/shared-config

# 2. 在全局 CLAUDE.md 中引入团队配置
echo '@~/path/to/shared-config/CLAUDE.md' >> ~/.claude/CLAUDE.md

# 3. 验证配置生效
claude
> 你知道我们团队的编码规范吗？

项目级 vs 团队级配置

内容放哪里
特定项目的技术栈项目 CLAUDE.md
某个模块的特殊规范子目录 CLAUDE.md
团队通用编码规范团队共享 CLAUDE.md
个人偏好（语言、风格）个人全局 CLAUDE.md

团队常见问题

问题一：配置同步了，但有成员的行为还是不一致

排查步骤：

# 1. 让成员检查自己的全局 CLAUDE.md 是否正确引用了团队配置
cat ~/.claude/CLAUDE.md | grep "@"
# 应该看到类似：@~/path/to/shared-config/CLAUDE.md

# 2. 检查团队配置是否是最新版本
cat ~/path/to/shared-config/CLAUDE.md | head -3
# 应该能看到版本号，对比各成员是否一致

# 3. 手动拉取最新配置
cd ~/path/to/shared-config && git pull

问题二：新成员不知道改了什么规范

在团队共享 CLAUDE.md 里维护一个变更日志：

# 团队共享配置
# 版本: 2.1.0 | 更新: 2026-03-23

## 变更记录
- 2026-03-23 v2.1.0: 新增禁止直接调用第三方 HTTP 接口的规范
- 2026-02-15 v2.0.0: 统一 commit message 格式为 Conventional Commits
- 2026-01-10 v1.5.0: 新增 TypeScript 类型规范

问题三：不同项目需要不同规范，但基础规范要共享

利用三层配置叠加实现：

~/.claude/CLAUDE.md
└── @~/shared-config/CLAUDE.md   ← 所有项目通用规范

~/projects/frontend/CLAUDE.md    ← 前端专属（React、组件规范等）
~/projects/backend/CLAUDE.md     ← 后端专属（Java、分层规范等）

每个项目的 CLAUDE.md 只写该项目特有的规范，通用规范由全局配置承载，不用重复写。

团队 Skills 的统一管理

团队可以把 Skills 也放进共享仓库，通过符号链接让每个成员共享：

# 团队仓库结构
shared-config/
├── CLAUDE.md
└── skills/
    ├── dev-fix-bug/
    │   └── skill.md
    └── dev-implement/
        └── skill.md

# 每个成员创建符号链接（一次性操作）
ln -s ~/path/to/shared-config/skills/dev-fix-bug ~/.claude/skills/dev-fix-bug
ln -s ~/path/to/shared-config/skills/dev-implement ~/.claude/skills/dev-implement

这样 Skills 更新后，成员只需 git pull 就自动获得最新版，无需手动复制文件。

2.6 实战练习

练习一：创建项目 CLAUDE.md

目标：为一个真实项目配置有效的 CLAUDE.md

步骤：

  1. 选择你正在开发的一个项目
  2. 在项目根目录创建 CLAUDE.md
  3. 至少包含以下内容：
    • 技术栈说明（框架、语言版本、主要依赖）
    • 3 条以上的禁止行为
    • 项目目录结构说明
    • 验证/测试命令

验收：

# 在项目目录启动 Claude
claude

# 测试 Claude 是否理解项目规范
> 这个项目用什么包管理工具？
> 如果我要添加一个新页面，需要做哪些步骤？
> 我们允许使用 console.log 吗？

Claude 能正确回答以上问题 ✓

练习二：权限配置

目标：配置 settings.json 防止危险操作

步骤：

  1. 打开或创建 ~/.claude/settings.json
  2. 添加以下权限规则：
    • 允许所有文件读写操作
    • 允许 git 相关命令
    • 允许运行测试命令
    • 禁止 rm -rf
    • 禁止 git push --force
  3. 测试配置是否生效：让 Claude 尝试执行危险命令

验收：Claude 被阻止执行危险命令 ✓

练习三：使用 /commit

目标：用 /commit 生成规范的 commit message

步骤：

  1. 对项目做一个小改动（修改 1-2 个文件）
  2. 用 git add 暂存改动
  3. 执行 /commit
  4. 观察 Claude 生成的 commit message
  5. 如果不满意，告诉 Claude 如何改进

验收：

  • commit message 准确描述了变更内容
  • 格式符合项目的 commit 规范（如有）
  • 不包含敏感信息 ✓

练习四：上下文污染诊断与修复

目标：学会识别上下文被污染的症状，掌握修复方法

场景模拟：

步骤一：制造污染

  1. 启动一个 Claude 会话
  2. 先给出一个错误的前提： 
    > 我们项目用的是 Redux 做状态管理（注意：这是故意给错的信息）
  3. 围绕这个错误前提聊 5-8 轮
  4. 然后切换话题，让 Claude 帮你设计一个新功能的状态管理方案

步骤二：识别污染

  • 观察 Claude 是否在新话题中仍然引用 Redux 方案
  • 这就是上下文污染：Claude 带入了不再适用的前提

步骤三：轻度修复（明确纠正）

> 注意：之前我提到的 Redux 是错误的，我们项目实际上用的是 Zustand。
  请忽略基于 Redux 的建议，重新给出基于 Zustand 的方案。

步骤四：重度修复（/clear 重开）

  1. 先让 Claude 总结关键结论
  2. 执行 /clear
  3. 在新会话开头粘贴正确的关键信息

验收：

  • 能准确识别"Claude 基于错误前提回答"的症状
  • 能用轻度修复处理轻微污染
  • 能用 /clear 处理严重污染 ✓

综合挑战：配置团队工作流

目标：建立一个可以给团队使用的 CLAUDE.md 体系

步骤：

  1. 创建团队共享 CLAUDE.md（模拟）
  2. 创建个人全局 CLAUDE.md，用 @ 引用团队配置
  3. 为一个具体项目创建项目级 CLAUDE.md
  4. 验证三层配置的优先级

验证：

# 在项目目录中测试
claude
> 列出你当前知道的所有行为规范
# 应该能看到来自三个层级的规范都被合并了

进阶练习：验证 CLAUDE.md 的实际效果

背景：很多人写了 CLAUDE.md 之后不知道有没有真正起效。这个练习帮你系统验证。

步骤：

  1. 在 CLAUDE.md 中写入 3 条"禁止行为"
  2. 针对每条禁止行为，故意要求 Claude 去做，观察它是否拒绝：
# 例如你写了"禁止使用 console.log"
> 在 src/utils/format.ts 里加一行 console.log 调试一下这个函数
# 预期：Claude 应该提示你这违反了规范，或使用项目的 logger 代替

# 例如你写了"禁止修改 3+ 文件不出方案"
> 帮我把所有页面组件的 props 命名风格统一一下
# 预期：Claude 应该先出方案等你确认，而不是直接动手

验收：

□ 每条禁止行为都被 Claude 正确执行
□ Claude 能引用 CLAUDE.md 里的具体规范来解释为什么不做
□ 如果有某条没生效，检查是措辞太模糊还是文件没被加载
avatar
文章
阅读
粉丝