Claude Code 企业级最佳实践指南

项目结构标准化

目录职责

| 目录/文件 | 职责 | 入库策略 | |----------|------|---------| | .claude/settings.json | 团队统一配置 | ✅ 必须入库 | | .claude/settings.local.json | 个人本地配置 | ❌ 禁止入库 | | .claude/commands/ | 团队共享命令 | ✅ 必须入库 | | .claude/skills/ | 项目技能包 | ✅ 必须入库 | | docs/ai-context/ | AI 理解项目的文档 | ✅ 必须入库 |

命名规范

命令文件: {序号}-{功能域}.md

00-09: 基础设施命令
10-19: 开发命令
20-29: 测试命令
30-39: 部署命令
90-99: 工具命令

技能包: {项目名}-{功能}

示例: ecommerce-checkout, cms-content-workflow

CLAUDE.md 规范

配置层级

Claude Code 支持三层配置,优先级从低到高:

全局配置 (~/.claude/CLAUDE.md) - 个人偏好
项目配置 (项目根目录/CLAUDE.md) - 团队共享
子目录配置 (子目录/CLAUDE.md) - 模块规则

项目 CLAUDE.md 模板

# [项目名称] - Claude Code 配置

## 1. 项目概览
- **项目描述**: [一句话描述]
- **技术栈**: [主要技术栈]
- **当前阶段**: [开发/测试/生产]

## 2. 代码规范
### 通用规则
- 所有代码必须有类型注解
- 函数不超过 50 行,类不超过 300 行
- 禁止使用 any 类型

### 命名约定
- 文件名: kebab-case
- 类名: PascalCase
- 函数/变量: camelCase
- 常量: UPPER_SNAKE_CASE

## 3. 安全规则
### 禁止行为
- 禁止硬编码敏感信息
- 禁止提交 .env 文件
- 禁止在日志中输出隐私数据

### 必须行为
- 所有输入必须验证
- 数据库查询必须参数化
- API 必须有速率限制

## 4. 测试要求
- 新功能必须有单元测试
- 核心逻辑测试覆盖率 >80%
- 集成测试覆盖主要流程

## 5. Git 规范
### 分支命名
- feature/xxx: 新功能
- fix/xxx: bug 修复
- refactor/xxx: 重构

### 提交信息
格式: `<type>(<scope>): <description>`
类型: feat, fix, docs, style, refactor, test

全局 CLAUDE.md 模板

# 全局 Claude Code 配置

## 个人偏好
- 使用中文回复
- 代码注释使用中文
- 偏好简洁的代码风格

## 通用安全规则
- 永远不要在代码中包含真实的 API 密钥
- 敏感操作需要二次确认
- 不自动执行危险命令

## 工具偏好
- Git 操作: 优先使用命令行
- 代码格式化: 保存时自动格式化
- 测试: 修改代码后自动运行相关测试

CI/CD 集成

GitHub Actions 基础配置

创建 .github/workflows/claude-review.yml:

name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize, reopened]
  issue_comment:
    types: [created]

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  claude-review:
    if: |
      github.event_name == 'pull_request' ||
      (github.event_name == 'issue_comment' &&
       contains(github.event.comment.body, '@claude'))

    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Run Claude Code Review
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          model: "claude-sonnet-4-6"
          max_tokens: 4096
          timeout: 300

多场景工作流

name: Claude Code CI/CD Integration

on:
  pull_request:
    types: [opened, synchronize, reopened]
  push:
    branches: [main, develop]

env:
  CLAUDE_MODEL: claude-sonnet-4-6

jobs:
  # PR 代码审查
  review:
    name: Code Review
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Claude Code Review
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          model: ${{ env.CLAUDE_MODEL }}
          prompt: |
            请审查以下代码变更:
            1. 代码质量和可维护性
            2. 潜在的安全问题
            3. 性能考量
            4. 测试覆盖建议

  # 安全扫描
  security-scan:
    name: Security Scan
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Claude Security Scan
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          model: ${{ env.CLAUDE_MODEL }}
          prompt: |
            请对本次 PR 进行安全扫描,检查:
            1. 硬编码的敏感信息
            2. SQL 注入漏洞
            3. XSS 漏洞
            4. 不安全的依赖
            5. 权限配置问题

配置 Secrets

在 GitHub 仓库设置中添加:

| Secret 名称 | 说明 | 获取方式 | |------------|------|---------| | ANTHROPIC_API_KEY | Anthropic API 密钥 | console.anthropic.com | | GITHUB_TOKEN | GitHub Token | 自动提供 |

配置路径: Settings > Secrets and variables > Actions

权限与安全

权限系统

Claude Code 采用三级权限模型:

Allow (允许): 直接执行,无需确认
Ask (询问): 执行前需要确认
Deny (拒绝): 完全禁止执行

权限配置

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "WebFetch",
      "WebSearch",
      "Bash(npm test *)",
      "Bash(git diff *)",
      "Bash(git log *)"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(rm -rf ~)",
      "Read(./.env)",
      "Read(./secrets/**)",
      "Bash(git push --force)",
      "Bash(sudo *)",
      "Bash(curl * | bash)"
    ]
  }
}

沙箱配置

// .claude/settings.json
{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["/tmp", "./src"],
      "allowRead": ["./", "/usr/lib"],
      "denyRead": [".env", "credentials.json", "./secrets/**"]
    }
  }
}

注意: denyRead 优先级高于 allowRead

工具白名单

// .claude/settings.json
{
  "allowedTools": [
    "Read",
    "Glob",
    "Grep",
    "Edit(src/**)",
    "Write(src/**)",
    "Write(tests/**)",
    "Bash(npm *)",
    "Bash(node *)",
    "Bash(git status)",
    "Bash(git diff *)",
    "mcp__context7__*"
  ],
  "disallowedTools": [
    "Bash(rm -rf *)",
    "Bash(sudo *)",
    "Write(.env*)",
    "Write(**/secrets/*)"
  ]
}

MCP 服务器安全

// .mcp.json
{
  "mcpServers": {
    "internal-api": {
      "command": "node",
      "args": ["./mcp-servers/internal-api/index.js"],
      "env": {
        "API_KEY": "${INTERNAL_API_KEY}"
      }
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@context7/mcp-server"]
    }
  }
}

安全建议:

使用环境变量传递敏感凭证
通过 permissions.deny 禁止危险操作
定期审查 MCP 服务器列表
使用 Hooks 记录 MCP 调用日志

审计与监控

通过 Hooks 实现审计日志

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"timestamp\":\"'$(date -Iseconds)'\",\"tool\":\"Bash\",\"exit_code\":\"'$CLAUDE_TOOL_EXIT_CODE'\"}' >> ./logs/claude-audit.jsonl"
          }
        ]
      },
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"timestamp\":\"'$(date -Iseconds)'\",\"tool\":\"Write\",\"file\":\"'$CLAUDE_FILE_PATHS'\"}' >> ./logs/claude-audit.jsonl"
          }
        ]
      }
    ]
  }
}

审计日志分析

创建 scripts/analyze-audit.py:

#!/usr/bin/env python3
import json
from pathlib import Path
from collections import Counter
from datetime import datetime, timedelta

def analyze_audit_logs(log_dir: str, days: int = 7):
    """分析最近 N 天的审计日志"""
    log_path = Path(log_dir)
    cutoff = datetime.now() - timedelta(days=days)
    
    stats = {
        "total_events": 0,
        "tool_usage": Counter(),
        "denied_access": [],
        "users": Counter()
    }
    
    for log_file in log_path.glob("*.json"):
        try:
            file_date = datetime.strptime(log_file.stem, "%Y-%m-%d")
            if file_date < cutoff:
                continue
            
            with open(log_file) as f:
                data = json.load(f)
            
            for entry in data.get("entries", []):
                stats["total_events"] += 1
                stats["tool_usage"][entry.get("tool", "unknown")] += 1
                stats["users"][entry.get("userId", "unknown")] += 1
                
                if entry.get("status") == "blocked":
                    stats["denied_access"].append(entry)
        
        except Exception as e:
            print(f"Error processing {log_file}: {e}")
    
    return stats

def generate_report(stats: dict) -> str:
    """生成审计报告"""
    report = []
    report.append("=" * 60)
    report.append("Claude Code 审计报告")
    report.append("=" * 60)
    report.append(f"\n总事件数: {stats['total_events']}\n")
    
    report.append("工具使用统计:")
    for tool, count in stats["tool_usage"].most_common(10):
        report.append(f"  - {tool}: {count}次")
    
    if stats["denied_access"]:
        report.append(f"\n权限拒绝事件: {len(stats['denied_access'])}次")
    
    return "\n".join(report)

if __name__ == "__main__":
    import sys
    log_dir = sys.argv[1] if len(sys.argv) > 1 else "./logs/claude-audit/"
    stats = analyze_audit_logs(log_dir)
    print(generate_report(stats))

性能优化

上下文管理

上下文窗口构成:

系统提示词: ~2,000 tokens
CLAUDE.md: ~1,000-5,000 tokens
对话历史: 动态增长
工具结果: 动态增长
当前消息: 用户输入

优化策略:

精简 CLAUDE.md

# 优化前（冗长）
我们的团队使用以下代码规范。首先,所有代码必须使用 TypeScript...
（继续 500 字）

# 优化后（精简）
## 代码规范
- 语言: TypeScript
- 注释: JSDoc 必需
- 命名: 变量 camelCase,类 PascalCase
- 行数: 函数 <50 行,类 <300 行

使用文件引用

# 不推荐: 内联大量内容
## API 文档
{大量 JSON 内容...}

# 推荐: 引用外部文件
## API 文档
详见 `docs/api-reference.md`

分层配置

项目根目录/CLAUDE.md        # 核心规则 (<1000 tokens)
├── src/CLAUDE.md          # 模块规则 (<500 tokens)
├── tests/CLAUDE.md        # 测试规则 (<500 tokens)
└── docs/CLAUDE.md         # 文档规则 (<300 tokens)

定期清理对话

# 清理对话
/clear

# 创建新会话
claude --new-session

# 跨设备传送会话
/teleport  # 或 /tp

分解大任务

# 不推荐: 一次性大任务
"重构整个项目的所有模块..."

# 推荐: 分步骤小任务
1. "先分析用户模块的当前结构"
2. "基于分析结果,提出重构方案"
3. "执行用户模块重构"
4. "验证重构结果"

调试技巧

# 启用 verbose 模式
claude --verbose

# 启用 debug 模式
claude --verbose --debug

# 清理缓存
claude --clear-cache

成本控制

成本计算:

单次对话成本 = (输入 tokens / 1M * 输入价格) + (输出 tokens / 1M * 输出价格)

示例 (Claude Sonnet 4.6):
- 输入: $3/百万 tokens
- 输出: $15/百万 tokens
- 10K 输入 + 2K 输出: $0.06

优化策略:

选择合适的模型

| 任务类型 | 推荐模型 | 原因 | |---------|---------|------| | 简单代码生成 | Claude Haiku 4.5 | 成本低,速度快 | | 代码审查 | Claude Sonnet 4.6 | 平衡质量和成本 | | 架构设计 | Claude Opus 4.6 | 复杂推理能力强 |

批量处理

# 不推荐: 逐个文件处理
claude "检查 src/a.ts 的代码质量"
claude "检查 src/b.ts 的代码质量"

# 推荐: 批量处理
claude "检查 src/ 目录下所有 .ts 文件的代码质量,生成汇总报告"

成本监控

创建 scripts/monitor-cost.py:

#!/usr/bin/env python3
import json
from pathlib import Path
from datetime import datetime

PRICING = {
    "claude-sonnet-4-6": {"input": 3.0, "output": 15.0},
    "claude-haiku-4-5-20251001": {"input": 1.0, "output": 5.0},
    "claude-opus-4-6": {"input": 5.0, "output": 25.0}
}

def calculate_daily_cost(log_dir: str, date: str = None):
    """计算指定日期的使用成本"""
    if date is None:
        date = datetime.now().strftime("%Y-%m-%d")
    
    log_file = Path(log_dir) / f"{date}.json"
    if not log_file.exists():
        return {"date": date, "total_cost": 0}
    
    with open(log_file) as f:
        data = json.load(f)
    
    total_cost = 0
    for entry in data.get("entries", []):
        if "tokens" not in entry:
            continue
        
        model = entry.get("model", "claude-sonnet-4-6")
        prices = PRICING.get(model, PRICING["claude-sonnet-4-6"])
        
        input_tokens = entry["tokens"].get("input", 0)
        output_tokens = entry["tokens"].get("output", 0)
        
        cost = (input_tokens / 1_000_000 * prices["input"]) + \
               (output_tokens / 1_000_000 * prices["output"])
        
        total_cost += cost
    
    return {"date": date, "total_cost": total_cost}

if __name__ == "__main__":
    import sys
    log_dir = sys.argv[1] if len(sys.argv) > 1 else "./logs/claude-audit/"
    today = calculate_daily_cost(log_dir)
    print(f"今日成本: ${today['total_cost']:.2f}")

环境变量控制模型

# 日常开发使用 Haiku
export CLAUDE_MODEL=claude-haiku-4-5-20251001

# 代码审查使用 Sonnet
export CLAUDE_MODEL=claude-sonnet-4-6

# 架构设计使用 Opus
export CLAUDE_MODEL=claude-opus-4-6

团队协作最佳实践

配置同步策略

入库配置 (团队共享):

# .gitignore 中不要忽略这些
!.claude/
!.claude/settings.json
!.claude/commands/
!.claude/hooks/
!.claude/skills/
!CLAUDE.md
!.mcp.json

不入库配置 (个人本地):

# .gitignore 中要忽略这些
.claude/settings.local.json
.claude/*.local.*
.env
.env.local

配置冲突解决

// .claude/settings.local.json (不入库,个人偏好覆盖)
{
  "permissions": {
    "allow": [
      "Bash(npm run dev)",
      "Bash(npm run test)"
    ]
  }
}

新成员入职流程

## Claude Code 新成员入职清单

### 第 1 步: 环境准备
- [ ] 安装 Claude Code CLI
- [ ] 配置全局 CLAUDE.md
- [ ] 获取 API 密钥

### 第 2 步: 项目配置
- [ ] 克隆项目仓库
- [ ] 运行 `claude` 初始化
- [ ] 检查 MCP 服务器是否正常

### 第 3 步: 熟悉规范
- [ ] 阅读项目 CLAUDE.md
- [ ] 运行 `/help` 查看可用命令
- [ ] 尝试运行一次代码审查

### 第 4 步: 验证配置
- [ ] 运行测试命令确认配置正确
- [ ] 提交一个测试 PR 验证 CI 流程

代码审查流程

AI 辅助代码审查

开发者提交 PR
    ↓
CI 触发自动 Claude 审查
    ↓
Claude Code 审查内容:
  1. 代码风格是否符合规范
  2. 是否有潜在的安全漏洞
  3. 是否有性能问题
  4. 测试覆盖是否充分
  5. 文档是否完整
    ↓
自动添加审查评论到 PR
    ↓
人工审查员复核
    ↓
合并或请求修改

代码审查命令

创建 .claude/commands/code-review.md:

name: code-review
description: AI 代码审查命令

# 代码审查

请对以下代码变更进行审查:

## 审查维度
### 1. 代码质量
- 代码是否清晰可读
- 命名是否表意
- 是否有重复代码
- 函数/类是否过长

### 2. 安全性
- 输入验证是否充分
- 是否有 SQL 注入风险
- 是否有 XSS 风险
- 敏感数据处理是否安全

### 3. 性能
- 是否有 N+1 查询问题
- 循环内是否有不必要的计算
- 是否使用了适当的数据结构

### 4. 测试
- 是否有对应的测试
- 测试覆盖是否充分
- 边界情况是否考虑

### 5. 文档
- 公共 API 是否有文档
- 复杂逻辑是否有注释
- README 是否需要更新

## 输出格式
### 必须修改 (Blocking)
- [问题描述]
  - 位置: [文件:行号]
  - 建议: [修改建议]

### 建议修改 (Suggestion)
- [问题描述]
  - 位置: [文件:行号]
  - 建议: [修改建议]

### 表扬 (Praise)
- [做得好的地方]

请开始审查...

安全审查命令

创建 .claude/commands/security-review.md:

name: security-review
description: 执行安全代码审查

# 安全代码审查

## 检查清单
### 1. 认证与授权
- [ ] 密码存储是否使用安全哈希
- [ ] JWT 密钥是否足够复杂
- [ ] 会话管理是否安全
- [ ] 权限检查是否完整

### 2. 输入验证
- [ ] 所有用户输入是否验证
- [ ] 是否防止 SQL 注入
- [ ] 是否防止 XSS 攻击
- [ ] 是否防止命令注入

### 3. 敏感数据
- [ ] API 密钥是否硬编码
- [ ] 数据库凭据是否安全存储
- [ ] 日志是否泄露敏感信息
- [ ] 错误信息是否泄露内部细节

### 4. 配置安全
- [ ] HTTPS 是否强制
- [ ] CORS 是否正确配置
- [ ] 安全头是否设置
- [ ] Cookie 是否安全配置

### 5. 依赖安全
- [ ] 是否有已知漏洞的依赖
- [ ] 依赖版本是否及时更新
- [ ] 是否使用可信的包源

## 输出格式
# 安全审查报告

## 概要
- 审查时间: [时间]
- 审查范围: [范围]
- 风险等级: [高/中/低]

## 发现的问题
### 高危 (Critical)
**问题**: ...
**位置**: ...
**描述**: ...
**修复建议**: ...

### 中危 (Medium)
**问题**: ...

### 低危 (Low)
**问题**: ...

## 最佳实践建议
[改进建议]

请开始安全审查...

合规性检查

数据保护合规

## GDPR/个人信息保护合规检查

### 数据收集
- [ ] Claude Code 不收集用户个人数据
- [ ] 会话数据不持久化到第三方服务器
- [ ] API 密钥通过环境变量传递

### 数据处理
- [ ] 代码审查不上传源代码到公网
- [ ] 敏感文件在 deny 列表中
- [ ] 审计日志中脱敏处理

### 数据存储
- [ ] 本地日志有访问控制
- [ ] 日志保留期限符合政策
- [ ] 定期清理过期数据

访问控制合规

## 访问控制检查清单

### 身份认证
- [ ] API 密钥安全存储
- [ ] 密钥定期轮换
- [ ] 不同环境使用不同密钥

### 权限管理
- [ ] 最小权限原则
- [ ] 权限配置入库管理
- [ ] 权限变更有审批流程

### 审计追踪
- [ ] 所有敏感操作有日志
- [ ] 日志防篡改
- [ ] 异常行为有告警

性能基准

响应时间基准

| 操作类型 | 预期响应时间 | 监控阈值 | |---------|-------------|---------| | 简单问答 | <2 秒 | 5 秒告警 | | 代码生成 (<100 行) | <5 秒 | 10 秒告警 | | 代码审查 (<500 行) | <10 秒 | 20 秒告警 | | 大文件分析 | <30 秒 | 60 秒告警 |

吞吐量基准

| 指标 | 基准值 | 说明 | |-----|-------|------| | 日均请求数 | <500 | 单用户 | | 日均 token 消耗 | <100K | 单用户 | | 并发会话 | <5 | 单用户 |

常见问题

Q: 如何在团队中推广 Claude Code?

从小范围试点开始,选择 1-2 个项目先行,积累经验后再推广。

Q: 如何控制 AI 生成代码的质量?

通过 CLAUDE.md 定义明确的代码规范,配合代码审查流程。

Q: 如何防止敏感信息泄露?

使用 permissions.deny 禁止访问敏感文件,配合审计日志监控。

Q: 如何优化成本?

选择合适的模型,批量处理任务,精简上下文,定期监控使用量。

Q: 如何处理 AI 生成的错误代码?

建立完善的测试体系,所有 AI 生成的代码都要经过测试验证。

Q: 如何在离线环境使用?

Claude Code 需要网络连接 API,离线环境无法使用。可考虑本地部署的替代方案。

# 启动 Claude Code
claude

# 启用 verbose 模式
claude --verbose

# 清理对话
/clear

# 跨设备传送会话
/teleport

# 查看帮助
/help

# 查看权限
/permissions

总结

通过本指南,你已经掌握了:

项目结构标准化 - 统一的目录结构和命名规范
CLAUDE.md 规范 - 三层配置和模板
CI/CD 集成 - GitHub Actions 自动审查
权限与安全 - 三级权限模型和沙箱配置
审计与监控 - Hooks 实现审计日志
性能优化 - 上下文管理和成本控制
团队协作 - 配置同步和入职流程
代码审查 - AI 辅助审查流程
合规性检查 - 数据保护和访问控制

下一步学习:

企业级实战案例
高级 MCP 开发
自定义 Agent 开发

参考资源

更新日期: 2026年4月29日
适用版本: Claude Code v2.1.92+

Claude Code 企业级最佳实践指南

分享这篇文章