Claude Code 大型代码库最佳实践培训指南
本指南基于 Anthropic 官方博客文章改编，旨在为团队提供系统化的 Claude Code 学习和培训材料。
适用于技术负责人、开发工程师、DevOps 工程师以及负责 Claude Code 部署和推广的团队成员。
目录
- 快速入门
- 概述与核心概念
- Claude Code 的工作原理
- 扩展点详解
- 配置模式与最佳实践
- 上下文管理高级技巧
- 完整工作流示例
- 组织管理与推广策略
- 实战案例与示例
- 安全最佳实践
- 故障排除与性能优化
- 常见反模式与错误
- 检查清单
- 常见问题解答
- 附录
1. 快速入门
1.1 安装 Claude Code
# 使用 npm 安装
npm install -g @anthropic-ai/claude-code
# 或使用 yarn
yarn global add @anthropic-ai/claude-code
# 验证安装
claude --version
1.2 基础配置
配置文件位置
用户级配置：
~/.claude/settings.json # 全局设置
~/.claude/commands/ # 全局命令
项目级配置：
<project-root>/.claude/settings.json # 项目设置
<project-root>/.claude/commands/ # 项目命令
<project-root>/CLAUDE.md # 根目录上下文
<project-root>/<subdir>/CLAUDE.md # 子目录上下文
最小配置示例
创建 .claude/settings.json：
{
"permissions": {
"allow": [
{
"path": "src/**",
"description": "允许编辑源代码目录"
}
],
"deny": [
{
"path": "node_modules/**",
"reason": "依赖文件无需查看"
}
]
}
}
1.3 第一个会话
# 进入项目目录
cd my-project
# 启动 Claude Code
claude
# 询问项目结构
> 帮我分析这个项目的架构
# 让 Claude 执行任务
> 在 src/components 目录创建一个 Button 组件
1.4 快速进阶
# 使用斜杠命令
/help # 获取帮助
/clear # 清空上下文
/compact # 压缩对话历史
# 使用 @ 引用文件或目录
> 请参考 @src/utils/helpers.ts 中的函数
> 查看 @tests 目录的测试结构
1.5 常用命令速查表
斜杠命令
| 命令 |
说明 |
示例 |
/help |
显示帮助信息 |
/help |
/clear |
清空当前会话上下文 |
/clear |
/compact |
压缩对话历史，节省上下文 |
/compact |
/context |
显示当前上下文使用情况 |
/context |
/cost |
显示当前会话的 token 消耗 |
/cost |
/model |
切换模型 |
/model claude-sonnet-4-6 |
/permissions |
管理权限设置 |
/permissions |
/mcp |
管理 MCP 服务器 |
/mcp list |
常用提示词模式
| 场景 |
提示词示例 |
| 代码生成 |
在 src/auth 目录创建用户登录功能 |
| 代码解释 |
解释 @src/utils/auth.ts 中的认证逻辑 |
| Bug 修复 |
修复登录接口返回 500 错误的问题 |
| 代码重构 |
重构 @src/api/users.ts，提取公共逻辑 |
| 测试编写 |
为 @src/services/user.ts 编写单元测试 |
| 文档生成 |
为 @src/api/endpoints 生成 API 文档 |
| 代码审查 |
审查 @src/auth/login.ts 的安全性 |
| 性能优化 |
分析并优化 @src/utils/heavy-computation.ts |
文件引用技巧
# 引用单个文件
> 请查看 @src/index.ts
# 引用目录
> 分析 @src/components 目录的结构
# 引用多个文件
> 比较 @src/v1/api.ts 和 @src/v2/api.ts 的差异
# 使用通配符
> 检查 @src/**/*.test.ts 中的所有测试文件
高效提示词技巧
-
明确范围：指定具体的目录和文件
# 不好的提示词
> 修复 bug
# 好的提示词
> 修复 @src/auth/login.ts 中处理登录请求时的空指针异常
-
提供上下文：解释背景和约束
> 我们正在将 Express 4 升级到 Express 5，
> 请帮我更新 @src/api/routes.ts 中的路由定义，
> 确保兼容新版本的路由语法
-
分步骤：复杂任务分解
> 第一步：分析 @src/utils/data-processor.ts 的性能瓶颈
> 第二步：提出优化方案
> 第三步：实现优化
2. 概述与核心概念
2.1 什么是大型代码库
"大型代码库"是一个广泛的概念，涵盖以下场景：
| 类型 |
特征 |
示例 |
典型规模 |
| 单体仓库（Monorepo） |
统一版本控制，多项目共存 |
Google、Meta 内部仓库 |
百万-十亿行代码 |
| 遗留系统 |
数十年历史，技术栈陈旧 |
银行核心系统、企业 ERP |
复杂度高，文档少 |
| 分布式架构 |
多个微服务，跨多个仓库 |
电商、SaaS 平台 |
数十-数百服务 |
| 多语言代码库 |
包含多种编程语言 |
游戏、嵌入式系统 |
语言差异大 |
2.2 Claude Code 的核心优势
Claude Code 采用智能体搜索（Agentic Search）而非传统的 RAG 方法：
┌─────────────────────────────────────────────────────────────┐
│ 传统 RAG 方法 │
├─────────────────────────────────────────────────────────────┤
│ 代码库 → 嵌入索引 → 向量数据库 → 查询检索 → 结果 │
│ ↑ │
│ 需要持续维护，容易过时 │
│ 可能返回已删除/重命名的代码 │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Claude Code 方法 │
├─────────────────────────────────────────────────────────────┤
│ 实时代码库 ← 直接访问 ← Claude Code │
│ ↑ │
│ 无需索引，始终最新 │
│ 运行在开发者机器上 │
└─────────────────────────────────────────────────────────────┘
关键洞察：Claude Code 像软件工程师一样工作——遍历文件系统、读取文件、使用 grep 搜索、跟踪引用。它运行在开发者的机器上，不需要构建或维护代码库索引。
2.3 Harness 框架的重要性
关于 Claude Code 能力最常见的误解之一是它完全由所使用的模型决定。实际上，围绕模型的生态系统——即"Harness"——比模型本身更能决定 Claude Code 的表现。
┌─────────────────────────────────────────────────────────────┐
│ Claude Code 架构 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ │
│ │ Claude 模型 │ │
│ └──────┬──────┘ │
│ │ │
│ ┌──────────────┼──────────────┐ │
│ │ │ │ │
│ ┌────────▼────────┐ │ ┌────────▼────────┐ │
│ │ CLAUDE.md │ │ │ Hooks │ │
│ │ (上下文层) │ │ │ (自动化层) │ │
│ └─────────────────┘ │ └─────────────────┘ │
│ │ │
│ ┌────────────────┐ │ ┌────────────────┐ │
│ │ Skills │ │ │ Plugins │ │
│ │ (技能层) │ │ │ (分发层) │ │
│ └────────────────┘ │ └────────────────┘ │
│ │ │
│ ┌────────────────┐ │ ┌────────────────┐ │
│ │ MCP Servers │ │ │ LSP/子智能体 │ │
│ │ (集成层) │────┴───│ (增强层) │ │
│ └────────────────┘ └────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
2.4 扩展点优先级与构建顺序
团队构建这些扩展点的顺序很重要，因为每一层都构建在前一层之上：
| 优先级 |
扩展点 |
必要性 |
构建成本 |
预期收益 |
| 1 |
CLAUDE.md |
必需 |
低 |
高 |
| 2 |
钩子（Hooks） |
推荐 |
中 |
高 |
| 3 |
技能（Skills） |
推荐 |
中 |
高 |
| 4 |
LSP 集成 |
推荐 |
中 |
高 |
| 5 |
MCP 服务器 |
可选 |
高 |
中-高 |
| 6 |
插件（Plugins） |
可选 |
高 |
高 |
| 7 |
子智能体 |
可选 |
高 |
中 |
建议构建路径：
第 1 周：CLAUDE.md + 基础钩子
↓
第 2-4 周：技能开发 + LSP 集成
↓
第 2-3 月：MCP 服务器 + 插件
↓
长期：子智能体优化
3. Claude Code 的工作原理
3.1 智能体搜索 vs RAG
| 特性 |
RAG（检索增强生成） |
智能体搜索（Claude Code） |
| 索引方式 |
预先嵌入整个代码库 |
无需索引，实时访问 |
| 时效性 |
可能过时（小时到周） |
始终反映当前状态 |
| 维护成本 |
需要持续更新索引 |
无额外维护 |
| 准确性 |
可能返回已删除/重命名的代码 |
始终最新 |
| 资源需求 |
需要服务器资源 |
本地运行 |
| 规模扩展 |
索引构建时间线性增长 |
无额外开销 |
3.2 上下文管理的重要性
Claude 的导航质量取决于代码库配置的质量。关键原则：
如果你要求 Claude 在十亿行代码中查找某种模糊模式的所有实例，你在工作开始前就会触及上下文窗口限制。
这意味着需要通过 CLAUDE.md 文件和技能来分层提供上下文：
上下文层次结构：
┌─────────────────────────────────────────────────────────────┐
│ 根目录 CLAUDE.md ← 全局概览（200 行以内） │
│ │ │
│ ├── services/CLAUDE.md ← 服务层约定 │
│ │ │ │
│ │ ├── auth/CLAUDE.md ← 认证服务特定配置 │
│ │ └── payment/CLAUDE.md ← 支付服务特定配置 │
│ │ │
│ ├── frontend/CLAUDE.md ← 前端约定 │
│ │ └── components/CLAUDE.md ← 组件约定 │
│ │ │
│ └── 技能加载 ← 按需加载专业知识 │
│ │ │
│ ├── 安全审查技能 ← 安全相关任务时加载 │
│ ├── 数据库迁移技能 ← 数据库操作时加载 │
│ └── 部署技能 ← 部署相关任务时加载 │
└─────────────────────────────────────────────────────────────┘
4. 扩展点详解
4.1 CLAUDE.md 文件
4.1.1 核心概念
CLAUDE.md 是 Claude 在每次会话开始时自动读取的上下文文件。它们为 Claude 提供无需任何额外操作即可掌握的代码库知识。
关键特性：
- 会话开始时自动加载
- 无需开发者手动配置
- 支持分层结构
- 跟随版本控制共享
4.1.2 分层架构
my-project/
├── CLAUDE.md # 根目录：全局概览、关键注意事项
├── frontend/
│ └── CLAUDE.md # 前端：React 约定、组件结构
├── backend/
│ └── CLAUDE.md # 后端：API 约定、数据库模式
├── services/
│ ├── auth/
│ │ └── CLAUDE.md # 认证服务：特定配置
│ └── payment/
│ └── CLAUDE.md # 支付服务：特定配置
└── tests/
└── CLAUDE.md # 测试：测试约定和覆盖规则
4.1.3 CLAUDE.md 最佳实践
应该包含的内容：
- 项目概述和架构图
- 关键技术栈
- 常用命令（构建、测试、运行）
- 编码约定
- 重要的配置说明
- 导航指针（指向其他 CLAUDE.md）
不应该包含的内容：
- 每个文件的结构（可以动态发现）
- 详细实现细节
- 经常变化的信息
- 重复的全局信息
行数建议：
| 位置 |
建议行数 |
重点 |
| 根目录 |
100-200 行 |
概览、指针、关键约定 |
| 子目录 |
50-150 行 |
本地约定、特定命令 |
| 子子目录 |
30-100 行 |
极度具体的约定 |
4.1.4 示例：根目录 CLAUDE.md
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## 项目概述
这是一个电商平台的单体仓库，采用前后端分离架构。
- 核心业务：商品管理、订单处理、支付结算、用户管理
- 开发团队：30+ 工程师，5 个子团队
## 技术栈
- 前端：React 18 + TypeScript + Tailwind CSS
- 后端：Node.js + Express + PostgreSQL
- 基础设施：Docker + Kubernetes
- 监控：Datadog + Sentry
## 常用命令
### 开发环境
```bash
# 安装依赖
pnpm install
# 启动开发服务器（前端 + 后端）
pnpm dev
# 仅启动前端
pnpm dev:frontend
# 仅启动后端
pnpm dev:backend
测试
# 运行所有测试
pnpm test
# 运行特定模块测试
pnpm test:auth
pnpm test:payment
# 运行单个测试文件
pnpm test -- --grep "test name"
构建和部署
# 构建生产版本
pnpm build
# Docker 构建
docker build -t my-app .
# 部署到开发环境
pnpm deploy:dev
架构说明
/frontend - React 前端应用/backend - Node.js API 服务/shared - 共享类型和工具/infra - 基础设施配置
编码约定
- 使用 TypeScript 严格模式
- 遵循 ESLint 推荐规则
- 测试覆盖率不低于 80%
- Git 提交信息遵循 Conventional Commits
重要提示
- 修改 API 时同步更新
/shared/types
- 数据库迁移文件放在
/backend/migrations
- 前端组件放在
/frontend/src/components
导航
- 后端开发：查看
/backend/CLAUDE.md
- 前端开发：查看
/frontend/CLAUDE.md
- 数据库操作：查看
/backend/migrations/CLAUDE.md
4.1.5 示例：子目录 CLAUDE.md
# 前端模块说明
## 目录结构
- `/components` - 可复用 UI 组件
- `/pages` - 页面级组件
- `/hooks` - 自定义 React Hooks
- `/utils` - 工具函数
- `/api` - API 调用层
## 组件约定
- 组件使用 PascalCase 命名
- 每个组件包含自己的样式和测试
- 使用 React.forwardRef 暴露 DOM 引用
- Props 接口定义在组件文件顶部
## 状态管理
- 全局状态：使用 Zustand
- 服务端状态：使用 React Query
- 表单状态：使用 React Hook Form
## 常用命令
```bash
# 运行前端开发服务器
pnpm dev:frontend
# 运行前端测试
pnpm test:frontend
# 构建前端
pnpm build:frontend
# Lint 检查
pnpm lint:frontend
注意事项
- 新组件必须包含 stories 和测试
- 使用 CSS-in-JS 而非全局样式
- 避免在组件中直接调用 API
4.1.6 示例：代码库地图
对于目录结构复杂的代码库，在根目录 CLAUDE.md 中添加代码库地图：
## 代码库地图
| 目录 | 描述 | 维护团队 | 技术栈 |
|------|------|---------|--------|
| `/apps/web` | 用户端 Web 应用 | 前端团队 | React, TypeScript |
| `/apps/admin` | 管理后台 | 前端团队 | Vue, JavaScript |
| `/services/api` | API 网关 | 平台团队 | Go, gRPC |
| `/services/auth` | 认证服务 | 安全团队 | Node.js, OAuth |
| `/services/payment` | 支付服务 | 金融团队 | Java, Spring |
| `/libs/shared` | 共享库 | 平台团队 | TypeScript |
| `/infra` | 基础设施 | DevOps | Terraform, K8s |
| `/data` | 数据管道 | 数据团队 | Python, Spark |
4.2 钩子（Hooks）
4.2.1 核心概念
钩子是在特定事件发生时自动执行的脚本。它们可以：
- 阻止或修改操作
- 执行自动化任务
- 记录和监控活动
- 强制执行团队规范
4.2.2 钩子类型详解
| 钩子类型 |
触发时机 |
用途 |
示例 |
PreToolUse |
工具执行前 |
验证输入、阻止危险操作 |
检查敏感信息、验证路径 |
PostToolUse |
工具执行后 |
格式化输出、记录日志 |
代码格式化、生成文档 |
Notification |
发送通知时 |
自定义通知处理 |
发送 Slack 通知 |
Stop |
会话结束时 |
清理、总结、建议改进 |
更新 CLAUDE.md |
4.2.3 钩子环境变量
钩子可以访问以下环境变量：
| 变量名 |
说明 |
CLAUDE_TOOL_NAME |
当前工具名称 |
CLAUDE_TOOL_INPUT |
工具输入（JSON 格式） |
CLAUDE_FILE_PATH |
被操作的文件路径 |
CLAUDE_PROJECT_DIR |
项目根目录 |
4.2.4 钩子配置示例
在 .claude/settings.json 中配置：
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "echo '[PRE-CHECK] 验证 Bash 命令...'"
}
]
}
],
"PostToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "prettier --write \"$CLAUDE_FILE_PATH\""
}
]
}
],
"Stop": [
{
"type": "command",
"command": "echo '[会话结束] 请检查本次更改的文件'"
}
]
}
}
4.2.5 实用钩子示例
示例 1：自动格式化代码
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
}
]
}
]
}
}
示例 2：防止提交敏感信息
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE '(password|secret|api_key|token)'; then echo '警告：可能包含敏感信息'; exit 1; fi"
}
]
}
]
}
}
示例 3：记录所有文件修改
#!/bin/bash
# hooks/log-changes.sh
LOG_FILE="$HOME/.claude/changes.log"
echo "$(date): Modified $CLAUDE_FILE_PATH" >> "$LOG_FILE"
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "bash hooks/log-changes.sh"
}
]
}
]
}
}
示例 4：Perforce 集成
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "p4 edit \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
}
]
}
],
"Stop": [
{
"type": "command",
"command": "echo '建议：运行 p4 submit 提交更改'"
}
]
}
}
示例 5：会话结束建议更新 CLAUDE.md
{
"hooks": {
"Stop": [
{
"type": "command",
"command": "echo '建议：如果有新的约定或模式，请更新 CLAUDE.md 文件'"
}
]
}
}
4.3 技能（Skills）
4.3.1 核心概念
技能是按需加载的专业化工作流，实现了渐进式披露——只有当任务需要时才加载，避免每个会话都加载所有上下文。
4.3.2 技能的优势
┌─────────────────────────────────────────────────────────────┐
│ 无技能：全量加载 │
├─────────────────────────────────────────────────────────────┤
│ 会话开始 → 加载所有上下文 → 上下文膨胀 → 性能下降 │
│ → 响应变慢 → 消耗更多 token │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ 有技能：按需加载 │
├─────────────────────────────────────────────────────────────┤
│ 会话开始 → 加载核心上下文 → 需要时加载技能 → 高效运行 │
│ → 响应快速 → 节省 token │
└─────────────────────────────────────────────────────────────┘
4.3.3 技能配置示例
示例：安全审查技能
在 .claude/skills/security-review.md 中：
# 安全审查技能
## 触发条件
当用户请求安全审查或代码涉及敏感操作时自动加载。
## 审查清单
- [ ] 输入验证
- [ ] SQL 注入防护
- [ ] XSS 防护
- [ ] CSRF 防护
- [ ] 敏感数据处理
- [ ] 认证和授权
- [ ] 依赖安全
## 常见漏洞模式
### SQL 注入
```javascript
// 危险
const query = `SELECT * FROM users WHERE id = ${userId}`;
// 安全
const query = 'SELECT * FROM users WHERE id = ?';
db.query(query, [userId]);
XSS
// 危险
element.innerHTML = userInput;
// 安全
element.textContent = userInput;
// 或使用 DOMPurify
element.innerHTML = DOMPurify.sanitize(userInput);
敏感数据暴露
// 危险
console.log('User password:', password);
// 安全
console.log('User authenticated:', !!user);
报告格式
## 安全审查报告
### 发现的问题
| 严重程度 | 文件 | 行号 | 描述 |
|---------|-----|-----|------|
| 高 | auth.js | 42 | SQL 注入风险 |
| 中 | utils.ts | 15 | 敏感数据暴露 |
| 低 | api.ts | 89 | 缺少输入验证 |
### 修复建议
1. auth.js:42 - 使用参数化查询
2. utils.ts:15 - 移除敏感日志
3. api.ts:89 - 添加输入验证中间件
**示例：数据库迁移技能**
在 `.claude/skills/db-migration.md` 中：
```markdown
# 数据库迁移技能
## 触发条件
当处理数据库迁移、模式变更相关任务时加载。
## 迁移文件命名规范
YYYYMMDDHHMMSS_.sql
示例：`20240115120000_add_users_table.sql`
## 迁移文件模板
```sql
-- 迁移：添加用户表
-- 创建时间：2024-01-15
-- 作者：xxx
-- Up
CREATE TABLE users (
id SERIAL PRIMARY KEY,
email VARCHAR(255) UNIQUE NOT NULL,
name VARCHAR(100) NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX idx_users_email ON users(email);
-- Down
DROP INDEX IF EXISTS idx_users_email;
DROP TABLE IF EXISTS users;
迁移最佳实践
- 始终提供 Up 和 Down 迁移
- 大表修改分批进行（使用 pt-online-schema-change 等工具）
- 迁移前备份数据
- 测试环境验证后再上生产
- 避免在迁移中执行业务逻辑
命令
# 创建迁移
pnpm db:migrate:create --name add_users_table
# 运行所有待执行迁移
pnpm db:migrate:up
# 回滚上一次迁移
pnpm db:migrate:down
# 查看迁移状态
pnpm db:migrate:status
注意事项
- 不要修改已发布的迁移文件
- 生产环境迁移需要双人审批
- 涉及数据删除的迁移必须先备份
示例：部署技能
在 .claude/skills/deployment.md 中：
# 部署技能
## 触发条件
当处理部署、发布相关任务时加载。
## 部署流程
1. 代码审查通过
2. CI/CD 流水线通过
3. 部署到开发环境
4. 冒烟测试通过
5. 部署到预发布环境
6. 集成测试通过
7. 部署到生产环境
## 命令
```bash
# 部署到开发环境
pnpm deploy:dev
# 部署到预发布环境
pnpm deploy:staging
# 部署到生产环境
pnpm deploy:prod
# 回滚
pnpm deploy:rollback --version <version>
部署检查清单
- [ ] 所有测试通过
- [ ] 代码审查完成
- [ ] 数据库迁移已准备
- [ ] 配置已更新
- [ ] 监控已配置
- [ ] 回滚计划已准备
常见问题
- 部署失败：检查 CI/CD 日志
- 数据库迁移失败：回滚迁移后重试
- 健康检查失败：检查服务日志
示例：测试技能
在 .claude/skills/testing.md 中：
# 测试技能
## 触发条件
当编写或运行测试时加载。
## 测试约定
- 单元测试：测试单个函数/组件
- 集成测试：测试模块间交互
- E2E 测试：测试完整用户流程
## 测试文件命名
/
├── __tests__/
│ ├── unit/
│ │ └── .test.ts
│ └── integration/
│ └── .test.ts
└── .ts
```
## 命令
```bash
# 运行所有测试
pnpm test
# 运行单元测试
pnpm test:unit
# 运行集成测试
pnpm test:integration
# 运行特定文件测试
pnpm test -- src/__tests__/auth.test.ts
# 查看测试覆盖率
pnpm test:coverage
# 监听模式
pnpm test:watch
```
## Mock 约定
- 外部 API 使用 Mock
- 数据库使用 Mock 或测试数据库
- 时间相关使用 Mock 时间
## 断言约定
- 使用 expect 进行断言
- 描述测试行为，而非实现
- 每个测试只测试一个行为
```
#### 4.3.4 路径限定技能
技能可以限定在特定路径上激活：
```json
{
"skills": {
"payment-skill": {
"path": "services/payment/**",
"description": "支付服务专用技能"
}
}
}
```
---
### 4.4 插件（Plugins）
#### 4.4.1 核心概念
插件将技能、钩子和 MCP 配置打包成可分发的包，解决大型代码库中"部落化知识"的问题。
#### 4.4.2 插件的价值
```
传统方式（部落化知识）：
┌─────────────────────────────────────────────────────────────┐
│ 工程师A的配置 ──────► 仅工程师A可用 │
│ 工程师B的配置 ──────► 仅工程师B可用 │
│ 新工程师 ────────────► 需要从头配置 │
│ → 上手慢，效率低 │
└─────────────────────────────────────────────────────────────┘
插件方式（知识共享）：
┌─────────────────────────────────────────────────────────────┐
│ 团队插件 ────────────► 所有工程师立即可用 │
│ 组织市场 ────────────► 跨团队共享最佳实践 │
│ 新工程师 ────────────► 安装插件即可开始工作 │
│ → 上手快，效率高 │
└─────────────────────────────────────────────────────────────┘
```
#### 4.4.3 插件结构示例
```
my-org-claude-plugin/
├── plugin.json # 插件元数据
├── README.md # 插件说明
├── skills/
│ ├── code-review.md
│ └── deployment.md
├── hooks/
│ └── settings.json # 钩子配置
├── mcp/
│ └── servers.json # MCP 服务器配置
└── commands/
└── deploy.md # 自定义命令
```
**plugin.json 示例：**
```json
{
"name": "my-org-claude-plugin",
"version": "1.0.0",
"description": "组织标准 Claude Code 配置",
"author": "Platform Team",
"skills": [
"skills/code-review.md",
"skills/deployment.md"
],
"hooks": "hooks/settings.json",
"mcpServers": "mcp/servers.json",
"commands": [
"commands/deploy.md"
],
"dependencies": []
}
```
#### 4.4.4 插件安装与管理
```bash
# 安装本地插件
claude plugin install /path/to/plugin
# 安装远程插件
claude plugin install https://github.com/org/plugin-repo
# 列出已安装插件
claude plugin list
# 更新插件
claude plugin update
# 卸载插件
claude plugin uninstall
```
---
### 4.5 MCP 服务器
#### 4.5.1 核心概念
MCP（Model Context Protocol）服务器将 Claude 连接到原本无法触及的内部工具、数据源和 API。
#### 4.5.2 常见 MCP 服务器用途
| 用途 | 描述 | 示例 |
|------|------|------|
| **内部文档** | 连接公司知识库、Wiki | Confluence、Notion |
| **票务系统** | 项目管理和问题跟踪 | Jira、Linear、GitHub Issues |
| **分析平台** | 数据分析、监控仪表板 | Datadog、Grafana |
| **数据库** | 直接查询内部数据库 | PostgreSQL、MySQL |
| **版本控制** | 非 Git 版本控制 | Perforce、SVN |
| **内部工具** | 自定义内部工具 | 自研系统 |
#### 4.5.3 MCP 服务器配置示例
```json
{
"mcpServers": {
"internal-docs": {
"command": "node",
"args": ["./mcp-servers/docs-server/index.js"],
"env": {
"DOCS_API_URL": "https://docs.internal.company.com/api"
}
},
"jira": {
"command": "node",
"args": ["./mcp-servers/jira-server/index.js"],
"env": {
"JIRA_URL": "https://company.atlassian.net",
"JIRA_TOKEN": "${JIRA_API_TOKEN}"
}
},
"analytics": {
"command": "python",
"args": ["./mcp-servers/analytics-server/main.py"],
"env": {
"ANALYTICS_DB_URL": "${ANALYTICS_DB_URL}"
}
}
}
}
```
#### 4.5.4 MCP 服务器示例
**Node.js MCP 服务器示例：**
首先安装 MCP SDK：
```bash
npm install @modelcontextprotocol/sdk
```
```javascript
// mcp-servers/docs-server/index.js
const { Server } = require('@modelcontextprotocol/sdk');
const { StdioServerTransport } = require('@modelcontextprotocol/sdk');
const axios = require('axios');
const server = new Server({
name: 'internal-docs',
version: '1.0.0'
});
server.setRequestHandler('tools/list', async () => ({
tools: [
{
name: 'search_docs',
description: '搜索内部文档',
inputSchema: {
type: 'object',
properties: {
query: {
type: 'string',
description: '搜索关键词'
},
limit: {
type: 'number',
description: '返回结果数量',
default: 5
}
},
required: ['query']
}
}
]
}));
server.setRequestHandler('tools/call', async (request) => {
if (request.params.name === 'search_docs') {
const { query, limit } = request.params.arguments;
const results = await searchInternalDocs(query, limit);
return {
content: [
{
type: 'text',
text: JSON.stringify(results, null, 2)
}
]
};
}
});
async function searchInternalDocs(query, limit) {
const response = await axios.get(`${process.env.DOCS_API_URL}/search`, {
params: { q: query, limit }
});
return response.data;
}
async function main() {
const transport = new StdioServerTransport();
await server.connect(transport);
}
main().catch(console.error);
```
**Python MCP 服务器示例：**
首先安装 MCP SDK：
```bash
pip install mcp
```
```python
# mcp-servers/analytics-server/main.py
from mcp.server import Server
from mcp.server.stdio import stdio_server
import asyncio
import os
server = Server("analytics")
@server.list_tools()
async def list_tools():
return [
{
"name": "query_metrics",
"description": "查询性能指标",
"inputSchema": {
"type": "object",
"properties": {
"metric": {
"type": "string",
"description": "指标名称"
},
"time_range": {
"type": "string",
"description": "时间范围（如 1h, 24h, 7d）",
"default": "24h"
}
},
"required": ["metric"]
}
}
]
@server.call_tool()
async def call_tool(name: str, arguments: dict):
if name == "query_metrics":
metric = arguments["metric"]
time_range = arguments.get("time_range", "24h")
results = await fetch_metrics(metric, time_range)
return {"content": results}
async def fetch_metrics(metric: str, time_range: str):
# 实现指标查询逻辑
return f"指标 {metric} 在过去 {time_range} 的数据..."
async def main():
async with stdio_server() as (read_stream, write_stream):
await server.run(read_stream, write_stream)
if __name__ == "__main__":
asyncio.run(main())
```
---
### 4.6 LSP 集成
#### 4.6.1 核心概念
LSP（语言服务器协议）让 Claude 具备与开发者在 IDE 中相同的导航能力：**转到定义**和**查找所有引用**。
#### 4.6.2 LSP 的价值
```
┌─────────────────────────────────────────────────────────────┐
│ 无 LSP：文本搜索 │
├─────────────────────────────────────────────────────────────┤
│ 搜索 "getUser" → 返回 1,234 个匹配 │
│ 需要逐个检查 → 消耗大量上下文 │
│ 可能混淆同名函数（不同模块的同名函数） │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ 有 LSP：符号搜索 │
├─────────────────────────────────────────────────────────────┤
│ 搜索 "getUser" → 返回定义 + 相关引用 │
│ 精确区分同名符号（不同模块的同名函数） │
│ 节省上下文空间 │
└─────────────────────────────────────────────────────────────┘
```
#### 4.6.3 配置 LSP
**TypeScript/JavaScript：**
```json
{
"languages": {
"typescript": {
"lsp": {
"command": "typescript-language-server",
"args": ["--stdio"]
}
},
"javascript": {
"lsp": {
"command": "typescript-language-server",
"args": ["--stdio"]
}
}
}
}
```
**Python：**
```json
{
"languages": {
"python": {
"lsp": {
"command": "pylsp",
"args": []
}
}
}
}
```
**Go：**
```json
{
"languages": {
"go": {
"lsp": {
"command": "gopls",
"args": []
}
}
}
}
```
**Java：**
```json
{
"languages": {
"java": {
"lsp": {
"command": "jdtls",
"args": []
}
}
}
}
```
#### 4.6.4 LSP 安装指南
```bash
# TypeScript/JavaScript
npm install -g typescript-language-server typescript
# Python
pip install python-lsp-server
# Go
go install golang.org/x/tools/gopls@latest
# Java (需要 JDK 17+)
# 下载 jdtls: https://github.com/eclipse/eclipse.jdt.ls
```
#### 4.6.5 多语言代码库的 LSP 投资价值
对于多语言代码库，LSP 是最具价值的投资之一：
- 一家大型软件公司在全面推广 Claude Code 之前，**在全公司范围内集成了 LSP**，专门用于 C 和 C++ 的大规模导航
- 这使得 Claude 能够精确跟踪函数调用、区分同名符号，避免文本匹配的歧义
---
### 4.7 子智能体（Subagents）
#### 4.7.1 核心概念
子智能体是拥有独立上下文窗口的隔离 Claude 实例，承担任务、完成工作，仅将最终结果返回给父智能体。
#### 4.7.2 使用场景
```
┌─────────────────────────────────────────────────────────────┐
│ 主智能体工作流 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 启动子智能体 A（只读）→ 探索认证模块 → 返回摘要 │
│ 2. 启动子智能体 B（只读）→ 探索支付模块 → 返回摘要 │
│ 3. 主智能体 ────────────────► 综合分析并进行编辑 │
│ │
│ 优势： │
│ - 分离探索与编辑 │
│ - 避免上下文污染 │
│ - 并行处理 │
│ - 保持主上下文清洁 │
└─────────────────────────────────────────────────────────────┘
```
#### 4.7.3 子智能体配置示例
```json
{
"subagents": {
"codebase-explorer": {
"type": "read-only",
"description": "探索代码库，返回摘要",
"tools": ["Glob", "Grep", "Read"],
"output": "markdown-file"
},
"test-runner": {
"type": "isolated",
"description": "运行测试并返回结果",
"tools": ["Bash", "Read"],
"output": "test-results"
}
}
}
```
#### 4.7.4 子智能体最佳实践
1. **只读探索**：使用只读子智能体探索代码库，避免污染主上下文
2. **任务分解**：将大任务分解为多个子任务，分配给不同子智能体
3. **结果汇总**：子智能体返回结构化结果，便于主智能体处理
4. **错误处理**：设置超时和错误处理机制
---
## 5. 配置模式与最佳实践
### 5.1 三种核心配置模式
#### 模式一：分层 CLAUDE.md
```
代码库根目录/
├── CLAUDE.md # 全局概览，仅包含指针和关键注意事项
├── service-a/
│ └── CLAUDE.md # 服务 A 的特定配置
├── service-b/
│ └── CLAUDE.md # 服务 B 的特定配置
└── shared/
└── CLAUDE.md # 共享代码的说明
```
**最佳实践：**
- 根目录文件保持在 200 行以内
- 子目录文件专注于本地约定
- 避免重复内容
- 使用导航指针连接各层级
#### 模式二：子目录初始化
**推荐做法：** 在子目录中启动 Claude Code，而不是在代码库根目录。
```bash
# 不推荐：在根目录启动
cd /monorepo
claude
# 推荐：在工作目录启动
cd /monorepo/services/auth-service
claude
```
**原因：**
- 限制上下文范围
- 提高响应速度
- 减少无关信息
- 避免上下文污染
#### 模式三：按子目录限制命令
在子目录 CLAUDE.md 中指定特定命令：
```markdown
# 认证服务
## 测试命令
仅运行本服务的测试：
```bash
pnpm test --filter=auth-service
```
## 构建命令
```bash
pnpm build --filter=auth-service
```
## 数据库操作
```bash
# 运行迁移
pnpm db:migrate:up
# 生成迁移文件
pnpm db:migrate:create --name add_users_table
```
## 注意事项
- 不要运行全局测试套件（会超时）
- 数据库迁移使用本服务的配置
- 避免修改共享代码
```
### 5.2 忽略文件配置
使用 `.ignore` 文件排除不需要的文件：
```gitignore
# .ignore
# 构建产物
dist/
build/
*.min.js
*.min.css
*.bundle.js
# 依赖
node_modules/
vendor/
.venv/
__pycache__/
# 生成的文件
*.generated.*
*.pb.go
*.pb.ts
*.proto.ts
# 文档
docs/api/generated/
# 第三方代码
third_party/
external/
# 大文件
*.zip
*.tar.gz
*.pdf
*.png
*.jpg
# 测试覆盖率
coverage/
.nyc_output/
# IDE 配置
.idea/
.vscode/
*.swp
```
在 `.claude/settings.json` 中配置权限：
```json
{
"permissions": {
"deny": [
{
"path": "node_modules/**",
"reason": "依赖文件无需查看"
},
{
"path": "*.generated.*",
"reason": "生成文件不直接编辑"
},
{
"path": ".env*",
"reason": "环境变量文件敏感"
}
]
}
}
```
### 5.3 完整 settings.json 模板
```json
{
"permissions": {
"allow": [
{
"path": "src/**",
"description": "允许编辑源代码目录"
},
{
"path": "tests/**",
"description": "允许编辑测试文件"
},
{
"path": "docs/**",
"description": "允许编辑文档"
}
],
"deny": [
{
"path": "node_modules/**",
"reason": "依赖文件无需查看"
},
{
"path": "*.generated.*",
"reason": "生成文件不直接编辑"
},
{
"path": ".env*",
"reason": "环境变量文件敏感"
},
{
"path": "dist/**",
"reason": "构建产物不直接编辑"
}
]
},
"hooks": {
"PostToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
}
]
}
]
},
"mcpServers": {},
"languages": {
"typescript": {
"lsp": {
"command": "typescript-language-server",
"args": ["--stdio"]
}
}
}
}
```
### 5.4 维护策略
**审查周期：** 每 3-6 个月进行一次配置审查。
**审查清单：**
- [ ] CLAUDE.md 是否还有必要？
- [ ] 指令是否与新模型冲突？
- [ ] 钩子是否仍然需要？
- [ ] 技能是否过时？
- [ ] MCP 服务器是否正常运行？
- [ ] LSP 配置是否需要更新？
**更新原则：**
- 移除对新模型不必要的指令
- 简化过度详细的配置
- 保持与代码库演变同步
- 记录配置变更历史
---
## 6. 上下文管理高级技巧
### 6.1 理解上下文窗口
Claude 的上下文窗口是有限的资源。有效管理上下文是高效使用 Claude Code 的关键。
```
上下文窗口构成：
┌─────────────────────────────────────────────────────────────┐
│ 系统提示 + CLAUDE.md + 技能 + 对话历史 + 工具结果 │
│ ↓ │
│ 总计不超过上下文窗口限制 │
└─────────────────────────────────────────────────────────────┘
```
### 6.2 上下文优化策略
#### 策略一：精简 CLAUDE.md
**原则：** 每个字都要有价值
```markdown
# 不推荐：冗长的描述
## 数据库配置
我们的项目使用 PostgreSQL 数据库，版本是 15.2。
数据库服务器运行在内部网络上，地址是 10.0.0.100。
端口是标准的 5432。数据库名称是 myapp_production。
用户名是 myapp_user，密码存储在环境变量 DB_PASSWORD 中。
连接池使用 pg-pool，最大连接数是 20...
（继续 100 行）
# 推荐：精炼的要点
## 数据库
- PostgreSQL 15，连接配置见 .env
- ORM: Prisma，schema: prisma/schema.prisma
- 迁移: `pnpm db:migrate`
```
#### 策略二：使用 /compact 命令
当对话变长时，使用 `/compact` 压缩历史：
```bash
# 长对话后压缩
> /compact
# 带指令压缩（保留重要上下文）
> /compact 保留我们讨论的 API 设计决策
```
#### 策略三：分阶段对话
```
阶段 1：探索和理解
> 分析 @src/auth 模块的架构
> （Claude 读取文件，消耗上下文）
阶段 2：使用 /compact 压缩
> /compact 保留架构分析结果
阶段 3：执行任务
> 基于刚才的分析，重构认证逻辑
```
### 6.3 上下文使用监控
```bash
# 查看当前上下文使用情况
/context
# 查看 token 消耗
/cost
# 查看详细统计
/context --verbose
```
### 6.4 避免上下文污染
**问题：** 不相关的文件读取会浪费上下文
```bash
# 不推荐：让 Claude 搜索整个代码库
> 找到所有处理用户认证的代码
# 推荐：指定范围
> 在 @src/auth 目录找到处理用户认证的代码
```
**问题：** 过大的文件会消耗大量上下文
```bash
# 不推荐：读取整个大文件
> 读取 @src/generated/types.ts 并解释
# 推荐：只读取需要的部分
> 在 @src/generated/types.ts 中找到 User 相关的类型定义
```
### 6.5 上下文管理检查清单
```markdown
## 上下文管理检查
### 每次会话前
- [ ] 确定工作目录（使用子目录初始化）
- [ ] 准备好需要引用的文件路径
### 会话中
- [ ] 定期检查 /context 使用情况
- [ ] 长对话后使用 /compact
- [ ] 避免让 Claude 读取不必要的大文件
### 会话后
- [ ] 记录有用的上下文到 CLAUDE.md
- [ ] 总结关键决策供下次会话使用
```
---
## 7. 完整工作流示例
### 7.1 新功能开发工作流
```
用户请求：添加用户注册功能
Claude Code 工作流：
┌─────────────────────────────────────────────────────────────┐
│ 1. 读取 CLAUDE.md → 了解项目架构和约定 │
│ 2. 探索代码库 → 找到相关模块（auth 模块） │
│ 3. 读取 auth/CLAUDE.md → 了解认证模块约定 │
│ 4. 加载安全审查技能 → 检查安全要求 │
│ 5. 编写代码 → 创建注册 API、前端表单、数据库迁移 │
│ 6. 运行测试 → 确保功能正常 │
│ 7. 格式化代码 → 自动格式化（通过钩子） │
│ 8. 提交代码 → 创建有意义的提交 │
└─────────────────────────────────────────────────────────────┘
```
**实际会话示例：**
```bash
# 用户输入
> 在 auth 模块添加用户注册功能，包括邮箱验证
# Claude Code 自动执行
1. 读取 CLAUDE.md
2. 探索 /services/auth 目录
3. 读取 /services/auth/CLAUDE.md
4. 加载安全审查技能
5. 创建以下文件：
- /services/auth/src/controllers/register.ts
- /services/auth/src/services/email.ts
- /services/auth/migrations/20240115120000_add_users_table.sql
6. 更新相关测试
7. 运行 pnpm test:auth
8. 格式化代码
```
### 7.2 Bug 修复工作流
```
用户请求：修复登录时的 500 错误
Claude Code 工作流：
┌─────────────────────────────────────────────────────────────┐
│ 1. 读取 CLAUDE.md → 了解项目架构 │
│ 2. 加载调试技能 → 查看错误日志 │
│ 3. 探索代码库 → 找到登录相关代码 │
│ 4. 分析问题 → 定位到具体函数 │
│ 5. 修复代码 → 应用修复 │
│ 6. 编写测试 → 确保问题不会再次发生 │
│ 7. 运行测试 → 验证修复 │
└─────────────────────────────────────────────────────────────┘
```
**实际会话示例：**
```bash
# 用户输入
> 登录接口返回 500 错误，请帮我定位并修复
# Claude Code 自动执行
1. 读取 CLAUDE.md
2. 加载调试技能
3. 搜索登录相关代码
4. 分析错误日志
5. 定位问题：password 比较逻辑错误
6. 修复代码
7. 添加回归测试
8. 运行 pnpm test:auth
```
### 7.3 代码审查工作流
```
用户请求：审查这个 PR
Claude Code 工作流：
┌─────────────────────────────────────────────────────────────┐
│ 1. 读取 CLAUDE.md → 了解代码约定 │
│ 2. 加载代码审查技能 → 应用审查规则 │
│ 3. 检查变更 → 分析代码质量、安全性、性能 │
│ 4. 生成报告 → 列出问题和建议 │
│ 5. 提供修复建议 → 给出具体修改方案 │
└─────────────────────────────────────────────────────────────┘
```
---
## 8. 组织管理与推广策略
### 8.1 推广三阶段
```
┌─────────────────────────────────────────────────────────────┐
│ 第一阶段：试点 │
├─────────────────────────────────────────────────────────────┤
│ - 选择 1-2 个团队试点 │
│ - 专门的基础设施投入 │
│ - 预配置工具和插件 │
│ - 收集反馈并迭代 │
│ - 时长：1-2 个月 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 第二阶段：推广 │
├─────────────────────────────────────────────────────────────┤
│ - 基于试点经验优化配置 │
│ - 创建标准插件和技能包 │
│ - 建立内部知识库 │
│ - 培训和支持 │
│ - 时长：2-3 个月 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 第三阶段：全面部署 │
├─────────────────────────────────────────────────────────────┤
│ - 组织范围推广 │
│ - 建立治理流程 │
│ - 持续监控和改进 │
│ - 社区和最佳实践分享 │
│ - 持续进行 │
└─────────────────────────────────────────────────────────────┘
```
### 8.2 角色定义
#### 智能体经理（Agent Manager）
这是一个新兴角色，混合 PM/工程师职能：
**职责：**
- 管理 Claude Code 生态系统
- 维护 CLAUDE.md 约定
- 审批技能和插件
- 协调跨团队配置
- 培训和支持团队
**技能要求：**
- 理解 AI 工具能力
- 软件工程背景
- 跨团队沟通能力
- 文档和培训能力
#### 最小可行方案
对于没有专门团队的组织：
**DRI（直接负责人）：** 一个人拥有：
- Claude Code 配置所有权
- 设置审批权
- 权限策略控制
- 更新责任
### 8.3 治理框架
#### 技能和插件管理
```json
{
"governance": {
"approvedSkills": [
"security-review",
"code-review",
"deployment"
],
"approvedPlugins": [
"org-standard-tools"
],
"approvalProcess": {
"submitter": "开发者",
"reviewer": "智能体经理",
"criteria": [
"安全性审查",
"性能影响评估",
"业务价值评估"
]
}
}
}
```
#### 代码审查流程
```
┌─────────────────────────────────────────────────────────────┐
│ AI 代码审查流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ AI 生成代码 ────► 自动化检查 ────► 人工审查 │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ Lint │ │
│ │ 测试 │ │
│ │ 安全扫描 │ │
│ └──────────┘ │
│ │
│ 关键原则：AI 生成的代码经过与人类代码相同的审查流程 │
└─────────────────────────────────────────────────────────────┘
```
### 8.4 跨职能工作组
建议早期建立的代表：
| 代表 | 关注点 | 交付物 |
|------|--------|--------|
| 工程团队 | 技术可行性、开发体验 | CLAUDE.md 约定、技能 |
| 信息安全 | 安全策略、数据保护 | 安全审查技能、权限策略 |
| 合规/治理 | 监管要求、审计痕迹 | 审计日志、合规检查 |
| 法务 | 知识产权、许可 | 许可证合规、数据处理 |
---
## 9. 实战案例与示例
### 9.1 案例：大型电商平台
**背景：**
- 单体仓库
- 5M+ 行代码
- 多团队协作
- 技术栈：Java、TypeScript、Python
**配置策略：**
```
repo/
├── CLAUDE.md # 全局架构概览
├── .claude/
│ ├── settings.json # 全局设置
│ ├── skills/
│ │ ├── java-backend.md
│ │ ├── react-frontend.md
│ │ ├── data-pipeline.md
│ │ ├── security-review.md
│ │ └── deployment.md
│ └── hooks/
│ └── settings.json # 自动化钩子
├── backend/
│ ├── CLAUDE.md # Java 服务配置
│ └── services/
│ ├── order/
│ │ └── CLAUDE.md # 订单服务配置
│ └── inventory/
│ └── CLAUDE.md # 库存服务配置
├── frontend/
│ └── CLAUDE.md # React 前端配置
└── data/
└── CLAUDE.md # 数据管道配置
```
**根目录 CLAUDE.md：**
```markdown
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## 代码库概述
大型电商平台单体仓库，包含后端服务、前端应用和数据管道。
## 架构
- **后端**：Java 17 + Spring Boot，微服务架构
- **前端**：React 18 + TypeScript
- **数据**：Python + Spark + Airflow
- **基础设施**：Kubernetes + AWS
## 技术栈详情
| 层级 | 技术 | 版本 |
|------|------|------|
| 后端 | Java | 17 |
| 框架 | Spring Boot | 3.x |
| 前端 | React | 18 |
| 数据库 | PostgreSQL | 15 |
| 缓存 | Redis | 7 |
## 重要约定
- API 版本化：`/api/v1/...`
- 所有 API 变更需要更新 OpenAPI 规范
- 数据库迁移必须可逆
- 前端组件测试覆盖率 > 70%
## 导航
- 后端开发：查看 `/backend/CLAUDE.md`
- 前端开发：查看 `/frontend/CLAUDE.md`
- 数据管道：查看 `/data/CLAUDE.md`
- 安全审查：加载安全审查技能
- 部署：加载部署技能
```
### 9.2 案例：遗留银行系统
**背景：**
- 20+ 年历史
- COBOL + Java + C# 混合
- Perforce 版本控制
- 受监管行业
**特殊配置：**
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "p4 edit \"$CLAUDE_FILE_PATH\""
}
]
}
]
},
"mcpServers": {
"perforce": {
"command": "node",
"args": ["./mcp-servers/perforce-server/index.js"]
},
"mainframe-docs": {
"command": "python",
"args": ["./mcp-servers/mainframe-docs/main.py"]
}
}
}
```
**COBOL 专用技能：**
```markdown
# COBOL 开发技能
## 触发条件
处理 `.cbl`、`.cpy` 文件时加载。
## COBOL 编码约定
- 遵循 ANSI COBOL 85 标准
- 使用有意义的变量名
- 每段代码添加注释
## 常见模式
### 文件处理
```cobol
OPEN INPUT CUSTOMER-FILE.
READ CUSTOMER-FILE INTO WS-CUSTOMER-RECORD
AT END SET WS-EOF TO TRUE
END-READ.
CLOSE CUSTOMER-FILE.
```
### 数据库访问
```cobol
EXEC SQL
SELECT CUSTOMER_NAME, BALANCE
INTO :WS-NAME, :WS-BALANCE
FROM CUSTOMERS
WHERE CUSTOMER_ID = :WS-CUST-ID
END-EXEC.
```
## 调试指南
1. 检查 JCL 作业日志
2. 验证文件分配
3. 检查数据格式转换
## 测试策略
1. 单元测试：使用 COBOL 测试框架
2. 集成测试：使用 JCL 作业测试
3. 端到端测试：使用生产数据子集
```
---
## 10. 安全最佳实践
### 10.1 敏感信息保护
#### 环境变量管理
```json
{
"permissions": {
"deny": [
{
"path": ".env*",
"reason": "环境变量文件包含敏感配置"
},
{
"path": "**/credentials*",
"reason": "凭证文件不应被访问"
},
{
"path": "**/*.pem",
"reason": "私钥文件敏感"
}
]
}
}
```
#### 钩子安全检查
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE '(curl|wget).*(password|secret|token)'; then echo '警告：检测到可能的敏感信息传输'; exit 1; fi"
}
]
},
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "if echo \"$CLAUDE_FILE_PATH\" | grep -qE '(\\.env|credentials|secrets)'; then echo '警告：尝试写入敏感文件'; exit 1; fi"
}
]
}
]
}
}
```
### 10.2 代码安全审查
#### 安全检查清单
在 CLAUDE.md 中添加安全要求：
```markdown
## 安全要求
### 代码审查要点
- [ ] 所有用户输入必须验证
- [ ] SQL 查询使用参数化查询
- [ ] 敏感数据不记录到日志
- [ ] API 密钥使用环境变量
- [ ] 密码使用 bcrypt 等安全哈希
- [ ] 文件上传限制大小和类型
- [ ] CORS 配置正确
- [ ] 依赖项无已知漏洞
### 禁止事项
- 禁止硬编码密码或 API 密钥
- 禁止使用 eval() 或 exec()
- 禁止禁用 SSL 验证
- 禁止在前端暴露后端逻辑
```
### 10.3 权限控制
#### 最小权限原则
```json
{
"permissions": {
"allow": [
{
"path": "src/**",
"description": "仅允许编辑源代码"
},
{
"path": "tests/**",
"description": "仅允许编辑测试文件"
}
],
"deny": [
{
"path": "src/**/config/**",
"reason": "配置文件需要特殊审批"
},
{
"path": "src/**/secrets/**",
"reason": "敏感文件禁止直接编辑"
}
]
}
}
```
### 10.4 审计日志
记录所有 Claude Code 操作：
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "echo \"$(date -u +%Y-%m-%dT%H:%M:%SZ) WRITE $CLAUDE_FILE_PATH $(whoami)\" >> ~/.claude/audit.log"
}
]
},
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "echo \"$(date -u +%Y-%m-%dT%H:%M:%SZ) BASH $(echo $CLAUDE_TOOL_INPUT | head -c 100) $(whoami)\" >> ~/.claude/audit.log"
}
]
}
]
}
}
```
---
## 11. 故障排除与性能优化
### 11.1 常见问题及解决方案
| 问题 | 原因 | 解决方案 |
|------|------|---------|
| Claude 响应缓慢 | 上下文过长 | 减少 CLAUDE.md 长度，使用技能按需加载 |
| 找不到文件 | 目录结构复杂 | 创建代码库地图，使用 @ 引用 |
| 生成错误代码 | 缺少上下文 | 完善 CLAUDE.md，添加更多约定 |
| 钩子不执行 | 配置错误 | 检查 settings.json 格式，查看日志 |
| LSP 不工作 | 未安装服务器 | 安装对应语言服务器 |
| MCP 连接失败 | 服务器未启动 | 检查服务器配置和日志 |
### 11.2 性能优化建议
1. **优化 CLAUDE.md 长度**
- 根目录：100-200 行
- 子目录：50-150 行
- 避免重复内容
2. **使用 .ignore 排除无关文件**
- 构建产物
- 依赖目录
- 生成的文件
3. **配置 LSP**
- 提高搜索精度
- 减少上下文消耗
4. **使用技能按需加载**
- 避免每个会话加载所有上下文
- 只在需要时加载专业知识
5. **配置子目录初始化**
- 限制上下文范围
- 提高响应速度
### 11.3 调试技巧
1. **查看钩子日志**
```bash
# 启用详细日志
claude --verbose
```
2. **检查配置文件**
```bash
# 验证 settings.json 格式
cat .claude/settings.json | jq .
```
3. **测试 MCP 连接**
```bash
# 测试 MCP 服务器
claude mcp test
```
4. **查看上下文使用情况**
```bash
# 查看当前会话上下文大小
/context
```
### 11.4 故障排除清单
```markdown
## 故障排除清单
### Claude 响应缓慢
- [ ] 检查 CLAUDE.md 长度
- [ ] 检查是否加载了过多技能
- [ ] 检查 .ignore 配置
- [ ] 检查 LSP 是否正常运行
### 找不到文件
- [ ] 检查当前工作目录
- [ ] 检查 CLAUDE.md 中的导航指针
- [ ] 检查 .ignore 配置
- [ ] 使用 @ 引用文件
### 生成错误代码
- [ ] 检查 CLAUDE.md 中的编码约定
- [ ] 检查技能是否正确加载
- [ ] 检查 LSP 是否正常运行
- [ ] 提供更多上下文信息
### 钩子不执行
- [ ] 检查 settings.json 格式
- [ ] 检查钩子命令语法
- [ ] 检查文件权限
- [ ] 查看 Claude Code 日志
```
### 11.5 Claude Code 的限制与边界
了解 Claude Code 的局限性有助于合理规划使用场景，避免在不适合的任务上浪费时间。
#### 不擅长处理的任务类型
| 任务类型 | 原因 | 替代方案 |
|---------|------|---------|
| **模糊的全局搜索** | "在十亿行代码中找到所有类似模式"会触及上下文限制 | 使用 @ 引用限定范围，或分阶段搜索 |
| **大规模重构** | 跨数百个文件的重构超出上下文容量 | 分批次执行，每次处理一个模块 |
| **无上下文的遗留代码** | 缺少文档和约定的代码难以理解 | 先构建 CLAUDE.md 和技能，再执行任务 |
| **视觉/UI 设计** | Claude 主要处理文本，视觉理解有限 | 提供详细的文字描述或使用截图 |
| **实时调试运行程序** | Claude 无法直接调试运行中的程序 | 使用日志分析、添加调试代码 |
| **复杂的数学/算法** | 需要多次迭代验证，一次性完成困难 | 分步骤验证，提供中间检查点 |
| **多语言实时翻译** | 需要语言专业知识 | 提供术语表和翻译指南 |
#### 大型代码库中的特殊限制
```
┌─────────────────────────────────────────────────────────────┐
│ Claude Code 在大型代码库中的边界 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 边界 1：上下文窗口 │
│ ───────────────────────── │
│ - 无法一次性理解整个代码库 │
│ - 需要通过 CLAUDE.md 分层引导 │
│ - 子目录初始化比根目录初始化更有效 │
│ │
│ 边界 2：导航能力 │
│ ───────────────────── │
│ - 没有 LSP 时只能文本搜索 │
│ - 文本搜索在大型代码库返回大量结果 │
│ - 需要人工筛选或 LSP 精确导航 │
│ │
│ 边界 3：知识时效 │
│ ───────────────────── │
│ - CLAUDE.md 可能反映过时的约定 │
│ - 需要定期审查和更新 │
│ - 模型能力提升后某些限制可能不再必要 │
│ │
│ 边界 4：并行工作 │
│ ───────────────────── │
│ - 单个会话无法同时处理多个独立模块 │
│ - 需要多个子智能体或分开会话 │
│ - 复杂任务需要分阶段执行 │
│ │
└─────────────────────────────────────────────────────────────┘
```
#### 正确使用 Claude Code 的原则
1. **限定范围**：始终指定具体目录或文件，避免全局搜索
2. **分层上下文**：使用 CLAUDE.md 分层提供信息，而非一次性全部加载
3. **分步执行**：复杂任务分解为多个步骤，每步完成后验证
4. **提供验证点**：要求 Claude 在关键步骤后停下来让你检查
5. **使用工具辅助**：LSP、MCP 服务器扩展 Claude 的能力边界
### 11.6 错误恢复策略
当 Claude Code 遇到障碍或产生错误时，以下策略可以帮助恢复：
#### 常见障碍类型及恢复方法
| 障碍类型 | 恢复策略 |
|---------|---------|
| **上下文过载** | 使用 `/compact` 压缩历史，或开始新会话 |
| **找不到相关代码** | 提供更精确的路径引用，检查 .ignore 配置 |
| **生成的代码不符合约定** | 完善 CLAUDE.md 约定，提供正确的代码示例 |
| **理解偏差** | 用更明确的指令重新描述需求，提供示例 |
| **工具执行失败** | 检查错误信息，修复环境问题后重试 |
| **钩子阻止操作** | 检查钩子配置，理解阻止原因，必要时调整 |
#### 分层恢复策略
```
┌─────────────────────────────────────────────────────────────┐
│ 错误恢复层级 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 第 1 层：会话内调整 │
│ ───────────────────── │
│ - 重新表述需求 │
│ - 提供更多上下文 │
│ - 使用 /compact 压缩 │
│ - 指定更精确的范围 │
│ │
│ 第 2 层：配置调整 │
│ ───────────────────── │
│ - 更新 CLAUDE.md │
│ - 调整技能配置 │
│ - 修改钩子规则 │
│ - 更新 .ignore 排除规则 │
│ │
│ 第 3 层：环境调整 │
│ ───────────────────── │
│ - 切换工作目录 │
│ - 检查 LSP/MCP 状态 │
│ - 修复工具链问题 │
│ - 开始新会话 │
│ │
└─────────────────────────────────────────────────────────────┘
```
#### 错误恢复流程示例
**场景：Claude 生成的代码不符合团队约定**
```bash
# 第 1 步：识别问题
> Claude 生成的代码使用了 var 而不是 const，不符合我们的约定
# 第 2 步：提供正确示例
> 请使用 const 和 let，示例：
> const user = { name: 'Alice' };
> let count = 0;
# 第 3 步：如果重复出现，更新 CLAUDE.md
# 在 CLAUDE.md 中添加：
## 编码约定
- 使用 const 和 let，禁止使用 var
# 第 4 步：验证修复
> 重新生成代码，检查是否遵守约定
```
**场景：Claude 找不到需要的文件**
```bash
# 第 1 步：检查 .ignore 配置
> 检查 .ignore 文件是否排除了目标文件
# 第 2 步：使用 @ 引用
> 查看 @src/services/auth/login.ts
# 第 3 步：如果仍找不到，检查路径
> 确认文件路径是否正确
# 第 4 步：更新 CLAUDE.md 导航指针
# 添加：
## 导航
- 认证服务：/services/auth/
```
**场景：钩子阻止了必要的操作**
```bash
# 第 1 步：理解阻止原因
> 钩子显示：检测到敏感信息传输
# 第 2 步：评估是否真的包含敏感信息
> 检查命令内容
# 第 3 步：如果是误判，调整钩子规则
# 在 settings.json 中修改钩子条件
# 第 4 步：如果确实需要，使用其他方式
> 通过其他安全渠道处理敏感信息
```
#### 预防性措施
```markdown
## 预防错误的最佳实践
### 会话前
- [ ] 明确任务范围和预期结果
- [ ] 准备必要的文件路径引用
- [ ] 检查 CLAUDE.md 是否有相关约定
### 会话中
- [ ] 关键步骤后要求 Claude 停下来验证
- [ ] 定期检查 /context 使用情况
- [ ] 遇到问题立即调整，不要累积
### 会话后
- [ ] 记录遇到的问题和解决方案
- [ ] 更新 CLAUDE.md 防止重复问题
- [ ] 分享经验给团队
```
---
## 12. 常见反模式与错误
### 12.1 常见反模式
#### 反模式 1：CLAUDE.md 过于冗长
**错误做法：**
```markdown
# CLAUDE.md（2000 行）
## 数据库配置
- 服务器地址：10.0.0.100
- 端口：5432
- 数据库名：myapp_production
- 用户名：admin
- 密码：xxx（见环境变量）
- 连接池大小：20
- 超时时间：30 秒
- ...（继续 500 行配置细节）
```
**正确做法：**
```markdown
# CLAUDE.md（150 行）
## 数据库
- PostgreSQL 15，配置见 .env
- ORM: Prisma
- 迁移: `pnpm db:migrate`
```
#### 反模式 2：让 Claude 搜索整个代码库
**错误做法：**
```bash
> 找到所有处理用户认证的代码
（Claude 会搜索整个项目，消耗大量上下文）
```
**正确做法：**
```bash
> 在 @src/auth 目录找到处理用户认证的代码
（限定范围，高效搜索）
```
#### 反模式 3：忽略子目录 CLAUDE.md
**错误做法：**
```
项目根目录/
├── CLAUDE.md（包含所有细节）
├── frontend/
├── backend/
└── services/
```
**正确做法：**
```
项目根目录/
├── CLAUDE.md（概览和指针）
├── frontend/CLAUDE.md（前端细节）
├── backend/CLAUDE.md（后端细节）
└── services/CLAUDE.md（服务细节）
```
#### 反模式 4：不使用 .ignore 排除无关文件
**错误做法：**
- 让 Claude 读取 node_modules
- 让 Claude 读取构建产物
- 让 Claude 读取生成的文件
**正确做法：**
```gitignore
# .ignore
node_modules/
dist/
build/
*.generated.*
```
#### 反模式 5：频繁切换任务而不压缩上下文
**错误做法：**
```bash
# 任务 A
> 实现用户注册功能
# ... 执行 10 分钟 ...
# 任务 B（不压缩，直接开始）
> 修复登录 bug
（上下文已经很长，性能下降）
```
**正确做法：**
```bash
# 任务 A
> 实现用户注册功能
# ... 执行 10 分钟 ...
# 压缩上下文
> /compact 保留用户注册功能的实现细节
# 任务 B
> 修复登录 bug
（上下文清爽，性能良好）
```
### 12.2 常见错误及解决方案
| 错误 | 原因 | 解决方案 |
|------|------|---------|
| "上下文已满" | CLAUDE.md 或对话历史过长 | 使用 /compact，精简 CLAUDE.md |
| "找不到文件" | 路径错误或文件不存在 | 使用 @ 引用，检查路径 |
| "钩子执行失败" | 命令语法错误或权限问题 | 检查命令，验证权限 |
| "MCP 连接失败" | 服务器未启动或配置错误 | 检查服务器状态和配置 |
| "LSP 不工作" | 未安装语言服务器 | 安装对应的 LSP 服务器 |
| "代码生成错误" | 缺少上下文或约定 | 完善 CLAUDE.md，提供更多上下文 |
### 12.3 调试流程
```mermaid
graph TD
A[发现问题] --> B{问题类型}
B -->|上下文问题| C[检查 CLAUDE.md 长度]
B -->|配置问题| D[检查 settings.json]
B -->|钩子问题| E[检查钩子日志]
B -->|MCP 问题| F[检查 MCP 服务器]
C --> C1[使用 /compact]
C --> C2[精简 CLAUDE.md]
D --> D1[验证 JSON 格式]
D --> D2[检查权限配置]
E --> E1[查看日志文件]
E --> E2[测试钩子命令]
F --> F1[检查服务器状态]
F --> F2[验证连接配置]
```
---
## 13. 检查清单
### 13.1 初始设置检查清单
```markdown
## Claude Code 初始设置检查清单
### 基础配置
- [ ] 创建根目录 CLAUDE.md
- [ ] 创建 .claude/settings.json
- [ ] 配置 .ignore 文件
- [ ] 设置 LSP 集成
- [ ] 配置基础钩子
### 技能设置
- [ ] 识别核心工作流
- [ ] 创建相应的技能文件
- [ ] 配置技能触发条件
- [ ] 测试技能加载
### 团队配置
- [ ] 定义编码约定
- [ ] 配置共享钩子
- [ ] 设置代码审查流程
- [ ] 文档化最佳实践
### 高级配置（可选）
- [ ] 配置 MCP 服务器
- [ ] 设置子智能体
- [ ] 创建组织插件
- [ ] 建立内部技能市场
```
### 13.2 定期维护检查清单
```markdown
## 季度维护检查清单
### CLAUDE.md 审查
- [ ] 内容是否仍然相关？
- [ ] 是否有冗余信息？
- [ ] 技术栈是否更新？
- [ ] 命令是否仍然有效？
### 钩子审查
- [ ] 是否有不再需要的钩子？
- [ ] 新的自动化机会？
- [ ] 性能影响评估
### 技能审查
- [ ] 技能是否过时？
- [ ] 是否需要新增技能？
- [ ] 触发条件是否准确？
### MCP 服务器审查
- [ ] 服务器是否正常运行？
- [ ] 是否有新的集成需求？
- [ ] 安全性审查
### 模型适配
- [ ] 评估新模型能力
- [ ] 调整过于详细的指令
- [ ] 移除不必要的限制
```
### 13.3 新项目设置检查清单
```markdown
## 新项目 Claude Code 设置
### 第一天
- [ ] 创建基础 CLAUDE.md
- [ ] 配置 LSP
- [ ] 设置基础钩子（格式化、lint）
- [ ] 配置 .ignore
### 第一周
- [ ] 完善架构文档
- [ ] 添加项目特定技能
- [ ] 配置 MCP 服务器（如需要）
- [ ] 创建子目录 CLAUDE.md
### 第一个月
- [ ] 评估使用效果
- [ ] 收集团队反馈
- [ ] 迭代优化配置
- [ ] 建立维护流程
```
---
## 14. 常见问题解答
### Q1: CLAUDE.md 应该有多长？
**回答：** 根目录 CLAUDE.md 应该保持在 100-200 行以内。关键原则是：
- 包含指针和关键注意事项
- 避免详细实现
- 详细信息放在子目录 CLAUDE.md 中
### Q2: 如何处理多语言代码库？
**回答：**
1. 使用 LSP 集成支持多语言
2. 为每种语言创建专用技能
3. 在子目录中配置语言特定的 CLAUDE.md
### Q3: 钩子会影响性能吗？
**回答：** 会。建议：
- 只配置必要的钩子
- 使用异步钩子处理耗时操作
- 定期审查和清理钩子
### Q4: 如何在团队中推广 Claude Code？
**回答：**
1. 从试点团队开始
2. 提供预配置的插件和技能
3. 建立内部文档和培训
4. 指定 DRI 负责维护
5. 定期分享最佳实践
### Q5: 如何处理 Perforce 等非 Git 版本控制？
**回答：**
1. 使用钩子在写入前执行 `p4 edit`
2. 构建 MCP 服务器连接 Perforce
3. 考虑使用 Git p4 桥接
### Q6: 如何衡量 Claude Code 的效果？
**回答：** 建议跟踪：
- 开发者满意度调查
- 代码审查时间
- 功能交付周期
- 问题修复时间
- 新工程师入职时间
### Q7: 如何保护敏感信息？
**回答：**
1. 使用 .ignore 文件排除敏感文件
2. 配置权限拒绝规则
3. 使用钩子检测敏感信息
4. 教育开发者最佳实践
### Q8: 模型更新后如何调整配置？
**回答：**
1. 重大模型发布后进行配置审查
2. 移除不再需要的变通方案
3. 简化过度详细的指令
4. 测试现有配置的兼容性
### Q9: 如何处理大型 monorepo？
**回答：**
1. 使用分层 CLAUDE.md
2. 配置子目录初始化
3. 使用 .ignore 排除无关文件
4. 考虑使用代码库地图
### Q10: 如何处理遗留代码？
**回答：**
1. 创建遗留系统专用技能
2. 配置非 Git 版本控制支持
3. 添加系统特定文档
4. 逐步改进，避免大规模重写
### Q11: Claude Code 有哪些任务不适合处理？
**回答：**
以下任务类型不适合：
- 模糊的全局搜索（"在十亿行代码中找所有类似模式"）
- 跨数百个文件的大规模重构
- 缺少文档和约定的遗留代码理解
- 视觉/UI 设计类任务
- 实时调试运行中的程序
替代方案：
- 使用 @ 引用限定范围
- 分批次执行，每次处理一个模块
- 先构建 CLAUDE.md 和技能再执行任务
### Q12: 当 Claude 遇到障碍时如何恢复？
**回答：**
分层恢复策略：
**第 1 层（会话内）：**
- 重新表述需求
- 提供更多上下文
- 使用 /compact 压缩
- 指定更精确的范围
**第 2 层（配置）：**
- 更新 CLAUDE.md
- 调整技能或钩子配置
- 更新 .ignore 排除规则
**第 3 层（环境）：**
- 切换工作目录
- 检查 LSP/MCP 状态
- 开始新会话
### Q13: 如何判断上下文是否过载？
**回答：**
使用 `/context` 命令检查。以下迹象表明过载：
- Claude 响应明显变慢
- 返回不完整或截断的响应
- 开始遗忘早期的讨论内容
- 找不到之前已读取的文件信息
解决方法：
- 使用 /compact 压缩历史
- 开始新会话处理新任务
- 精简 CLAUDE.md 长度
---
## 15. 附录
### 15.1 CLAUDE.md 模板
```markdown
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## 项目概述
[一句话描述项目]
## 技术栈
- 前端：[技术栈]
- 后端：[技术栈]
- 数据库：[技术栈]
- 基础设施：[技术栈]
## 常用命令
### 开发
```bash
# 安装依赖
[命令]
# 启动开发服务器
[命令]
```
### 测试
```bash
# 运行测试
[命令]
# 运行特定测试
[命令]
```
### 构建
```bash
# 构建生产版本
[命令]
```
## 架构说明
[描述主要架构和模块]
## 编码约定
- [约定 1]
- [约定 2]
- [约定 3]
## 重要提示
- [提示 1]
- [提示 2]
## 导航
- [子模块 A]：查看 `/path/to/CLAUDE.md`
- [子模块 B]：查看 `/path/to/CLAUDE.md`
## 相关文档
- [文档链接 1]
- [文档链接 2]
```
### 15.2 技能模板
```markdown
# [技能名称]
## 触发条件
[描述何时应该加载此技能]
## 概述
[技能的简要描述和用途]
## 详细指南
[详细的操作指南和最佳实践]
## 代码示例
```[语言]
[代码示例]
```
## 常见问题
[常见问题和解决方案]
## 相关资源
[相关文档和资源链接]
```
### 15.3 钩子配置模板
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "[工具名称]",
"hooks": [
{
"type": "command",
"command": "[命令]"
}
]
}
],
"PostToolUse": [
{
"matcher": "[工具名称]",
"hooks": [
{
"type": "command",
"command": "[命令]"
}
]
}
]
}
}
```
### 15.4 术语表
| 术语 | 定义 |
|------|------|
| **Harness** | Claude Code 的生态系统，包括 CLAUDE.md、钩子、技能、插件、MCP 服务器等 |
| **Agentic Search** | 智能体搜索，Claude Code 使用的实时搜索方法 |
| **RAG** | 检索增强生成，传统的代码库搜索方法 |
| **MCP** | Model Context Protocol，Claude 连接外部工具的协议 |
| **LSP** | 语言服务器协议，提供代码导航能力 |
| **Skills** | 技能，按需加载的专业化工作流 |
| **Hooks** | 钩子，在特定事件发生时自动执行的脚本 |
| **Plugins** | 插件，可分发的技能、钩子和 MCP 配置包 |
| **Subagents** | 子智能体，拥有独立上下文的隔离 Claude 实例 |
| **DRI** | 直接负责人，对 Claude Code 配置拥有所有权的个人 |
| **Monorepo** | 单体仓库，多个项目共享一个版本控制仓库 |
### 15.5 IDE 集成
#### VS Code 集成
1. **安装 Claude Code 扩展**
```bash
# 在 VS Code 中安装
code --install-extension anthropic.claude-code
```
2. **配置 settings.json**
```json
{
"claude-code.enableTelemetry": false,
"claude-code.defaultModel": "claude-sonnet-4-6"
}
```
3. **使用方式**
- 命令面板：`Ctrl+Shift+P` → "Claude Code: Open"
- 快捷键：`Ctrl+Shift+C` 打开 Claude Code 面板
- 右键菜单：选中代码 → "Ask Claude about this"
#### JetBrains 集成
1. **安装 Claude Code 插件**
- 打开 Settings → Plugins
- 搜索 "Claude Code"
- 安装并重启 IDE
2. **配置**
- Settings → Tools → Claude Code
- 设置 API 密钥和模型
3. **使用方式**
- 工具窗口：View → Tool Windows → Claude Code
- 快捷键：`Ctrl+Shift+A` → "Claude Code"
- 右键菜单：选中代码 → "Claude Code: Explain"
### 15.6 自定义斜杠命令
#### 创建自定义命令
在 `.claude/commands/` 目录创建 Markdown 文件：
```markdown
# .claude/commands/review.md
## 代码审查命令
请对 @{{file}} 进行代码审查，检查以下方面：
1. 代码质量和可读性
2. 潜在的 bug 和错误
3. 性能问题
4. 安全漏洞
5. 测试覆盖
请提供具体的改进建议。
```
#### 使用自定义命令
```bash
# 在 Claude Code 中使用
> /review src/auth/login.ts
# 带参数的命令
> /review {{文件路径}}
```
#### 命令模板变量
| 变量 | 说明 |
|------|------|
| `{{file}}` | 当前选中的文件 |
| `{{selection}}` | 当前选中的代码 |
| `{{directory}}` | 当前目录 |
| `{{project}}` | 项目根目录 |
### 15.7 成本估算
#### Token 消耗参考
| 操作类型 | 大约 Token 消耗 | 说明 |
|---------|----------------|------|
| 读取 CLAUDE.md | 500-2000 | 取决于文件大小 |
| 读取单个文件 | 200-1000 | 取决于文件大小 |
| 生成代码 | 500-3000 | 取决于复杂度 |
| 代码审查 | 1000-5000 | 取决于代码量 |
| 完整会话 | 5000-50000 | 取决于任务复杂度 |
#### 成本优化建议
1. **精简 CLAUDE.md**：减少每次会话的基础消耗
2. **使用子目录初始化**：限制上下文范围
3. **使用 /compact**：压缩对话历史
4. **使用 .ignore**：排除无关文件
5. **分阶段对话**：避免一次加载过多内容
### 15.8 团队培训要点
#### 基础培训（第 1 天）
- Claude Code 安装和基础使用
- CLAUDE.md 概念和分层配置
- 上下文管理基础（/compact、@ 引用）
- 实际操作练习
#### 进阶培训（第 2-3 天）
- 扩展点详解（钩子、技能、MCP）
- 大型代码库配置模式
- 安全最佳实践
- 故障排除和错误恢复
#### 专家培训（后续）
- 自定义扩展开发
- 组织治理框架
- 最佳实践制定和分享
### 15.9 学习路径概览
```
基础阶段（1-2 周）
├── 安装配置、基本命令
├── CLAUDE.md 编写
├── 上下文管理技巧
└── 日常任务处理
进阶阶段（1-2 月）
├── 钩子和技能开发
├── MCP 服务器集成
├── 大型代码库配置策略
├── 安全和治理
专家阶段（长期）
├── 组织级部署
├── 自定义扩展开发
├── 团队培训和指导
└── 最佳实践制定
```
### 15.10 参考资源
- [Claude Code 官方文档](https://claude.ai/code/docs)
- [Anthropic API 文档](https://docs.anthropic.com)
- [MCP 协议规范](https://modelcontextprotocol.io)
- [LSP 规范](https://microsoft.github.io/language-server-protocol/)
- [Claude Code GitHub](https://github.com/anthropics/claude-code)
### 15.11 远程开发环境使用
Claude Code 支持多种远程开发环境，这对于大型代码库的分布式团队很重要。
#### SSH 远程连接
```bash
# 通过 SSH 在远程服务器使用 Claude Code
ssh user@remote-server
# 在远程服务器上启动
cd /path/to/repo
claude
# 注意事项：
# - 需要在远程服务器上安装 Claude Code
# - API 密钥需要在远程服务器配置
# - 文件编辑在远程服务器上进行
```
#### Docker 容器环境
```bash
# 在 Docker 容器中使用 Claude Code
docker run -it \
-v /path/to/repo:/workspace \
-v ~/.claude:/root/.claude \
node:18 \
/bin/bash
# 容器内安装 Claude Code
npm install -g @anthropic-ai/claude-code
# 在容器内启动
cd /workspace
claude
```
#### WSL (Windows Subsystem for Linux)
```bash
# 在 WSL 中使用 Claude Code
# 进入 WSL
wsl
# 安装 Claude Code
npm install -g @anthropic-ai/claude-code
# 配置 Windows 文件访问
cd /mnt/c/Users/username/project
claude
```
#### 远程环境注意事项
| 环境 | 特殊配置 | 注意事项 |
|------|---------|---------|
| **SSH** | API 密钥配置 | 网络延迟可能影响响应速度 |
| **Docker** | 挂载卷配置 | 确保工作目录和配置正确挂载 |
| **WSL** | Windows 路径映射 | 使用 /mnt/c/ 访问 Windows 文件 |
| **远程桌面** | 无特殊配置 | 与本地使用体验一致 |
### 15.12 团队协作场景
大型代码库中多人协作的典型场景和最佳实践。
#### 场景 1：共享 CLAUDE.md 配置
```
┌─────────────────────────────────────────────────────────────┐
│ 团队配置共享流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 团队负责人创建 CLAUDE.md 模板 │
│ ↓ │
│ 2. 提交到版本控制（Git） │
│ ↓ │
│ 3. 所有成员拉取最新配置 │
│ ↓ │
│ 4. 成员可根据本地需求添加个人配置 │
│ （在 ~/.claude/settings.json） │
│ │
│ 关键：项目级配置版本控制，用户级配置本地 │
└─────────────────────────────────────────────────────────────┘
```
**配置层级原则：**
| 配置类型 | 存储位置 | 版本控制 | 适用范围 |
|---------|---------|---------|---------|
| 项目约定 | 项目 CLAUDE.md | 是 | 全团队 |
| 共享技能 | `.claude/skills/` | 是 | 全团队 |
| 共享钩子 | 项目 settings.json | 是 | 全团队 |
| 个人偏好 | `~/.claude/settings.json` | 否 | 个人 |
#### 场景 2：多人同时编辑同一模块
```markdown
## 协作最佳实践
### 避免冲突的方法
1. **明确分工**：在 CLAUDE.md 中记录各模块负责人
2. **小批量修改**：每次会话只处理少量文件
3. **及时同步**：频繁提交和拉取更改
4. **代码审查**：AI 生成的代码同样需要审查
### 处理流程
1. 开始会话前：git pull 获取最新代码
2. 会话中：Claude Code 编辑文件
3. 会话后：git commit + git push
4. 如遇冲突：手动解决或重新生成
```
#### 场景 3：跨团队知识共享
```json
// 组织级插件配置示例
{
"name": "org-shared-skills",
"skills": [
"security-review.md", // 安全团队贡献
"database-migration.md", // DBA 团队贡献
"api-conventions.md" // 平台团队贡献
],
"distribution": {
"method": "internal-marketplace",
"updateFrequency": "monthly"
}
}
```
#### 场景 4：新成员快速上手
```
新成员入职第一天：
┌─────────────────────────────────────────────────────────────┐
│ 1. 安装 Claude Code │
│ 2. 安装组织插件（包含团队约定） │
│ 3. 拉取项目代码（包含 CLAUDE.md） │
│ 4. 在子目录启动 Claude Code │
│ 5. 请求 Claude 解释项目架构 │
│ 6. 使用 Claude 生成的代码作为学习参考 │
│ │
│ 预期效果：半天内理解项目结构，一天内开始贡献 │
└─────────────────────────────────────────────────────────────┘
```
### 15.13 版本兼容性说明
不同版本 Claude Code 的主要差异和升级注意事项。
#### 主要版本特性
| 版本 | 主要特性 | 配置变化 |
|------|---------|---------|
| **最新版** | 支持最新模型、MCP、子智能体 | 无重大变化 |
| **早期版本** | 基础功能、CLAUDE.md、钩子 | 可能缺少新特性 |
#### 升级建议
```bash
# 检查当前版本
claude --version
# 升级到最新版
npm update -g @anthropic-ai/claude-code
# 升级后检查配置兼容性
claude config check
```
#### 配置向后兼容
```markdown
## 保持配置兼容性的建议
1. **使用标准配置格式**
- 遵循官方文档的配置格式
- 避免使用实验性特性
2. **版本控制配置文件**
- 配置变更时记录版本
- 升级后可回退配置
3. **定期审查配置**
- 新版本发布后检查配置
- 移除已弃用的配置项
```
---
## 总结
成功部署 Claude Code 的关键因素：
1. **分层配置**：根目录提供概览，子目录提供细节
2. **渐进式披露**：使用技能按需加载专业知识
3. **自动化**：使用钩子强制执行规则，减少记忆负担
4. **知识共享**：使用插件分发最佳实践
5. **持续维护**：定期审查配置，适应模型发展
6. **组织支持**：指派负责人，建立治理流程
7. **了解边界**：理解 Claude Code 的限制，合理规划任务
8. **错误恢复**：掌握恢复策略，快速应对障碍
9. **团队协作**：配置共享、明确分工、及时同步
10. **环境适配**：支持远程开发、容器环境等多种场景
遵循本指南的模式和实践，团队可以充分发挥 Claude Code 在大型代码库中的潜力。记住：**有效的 Harness 配置比模型本身更能决定 Claude Code 的表现**。
---
*本指南基于 Anthropic 官方博客文章改编，并添加了详细示例和实践指南。*
*原文链接：https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start*
悬浮的青春 1 年前
流动人口 1 年前
DADA 2 年前
五点五 3 年前
听风 4 年前
