Claude Code 综合实战:企业级最佳实践指南
课程信息
-
作者:老金
-
GitHub:https://github.com/KimYx0207
-
公众号:老金带你玩AI
-
X(Twitter):老金带你玩AI
-
个人博客:https://aiking.dev
-
预计学时:2-3小时
-
难度等级:⭐⭐⭐ 进阶
-
更新日期:2026年10月3日
-
适用版本:Claude Code v2.1.270(原参考基线);2026-10-03 补核当前权限行为,不代表本章全部示例都在 v2.1.288 实跑
📚 本课学习目标
我做综合实战不喜欢堆功能清单,真实项目里最值钱的是需求、代码、测试和交付之间能连起来。
完成本课学习后,你将能够:
-
建立团队协作规范:标准化项目结构、CLAUDE.md规范、代码审查流程
-
配置CI/CD集成:GitHub Actions配置、安全审查、自动化流水线
-
实施安全与合规:权限系统、白名单配置、审计日志、合规检查
-
优化性能与成本:上下文管理、调试技巧、成本控制
术语表(小白必读)
术语
英文全称
通俗解释
CI/CD
Continuous Integration/Continuous Deployment
持续集成/持续部署,自动化代码测试和发布的流程
GitHub Actions
GitHub提供的自动化工作流服务
PR
Pull Request
代码合并请求,用于代码审查
MCP
Model Context Protocol
模型上下文协议,扩展AI能力的接口标准
白名单
Whitelist/Allowlist
明确允许执行的工具或命令列表
审计日志
Audit Log
记录所有操作的日志,用于安全追踪
Token
AI处理文字的计费单位
上下文窗口
Context Window
AI单次对话能处理的最大信息量
Skill
Skill
Claude Code的可复用能力模块(通过SKILL.md定义)
Forked Context
Skills的独立上下文模式,通过context: fork启用,在子代理中运行不影响主会话
Hot Reload
Skills修改后自动重新加载,无需重启Claude Code
目录
-
团队协作规范
-
CI/CD集成
-
安全与合规
-
性能优化
-
综合练习
1. 团队协作规范
1.1 为什么需要团队规范
当Claude Code从个人工具演变为团队基础设施时,缺乏统一规范会导致严重问题:
典型混乱场景:
-
开发者A的CLAUDE.md有500行自定义规则,开发者B完全没有
-
代码审查时AI生成的代码风格与团队标准完全不同
-
敏感API密钥被AI意外提交到代码仓库
-
不同项目的MCP配置互相冲突导致工具失效
即使只有一个人,密钥泄露或越权修改也值得提前防范。多人共用仓库时,再把配置、审查和责任分工写清楚,减少彼此依赖的隐含假设。
1.2 项目结构标准化
1.2.1 推荐的目录结构
企业级项目应该采用统一的目录结构,让团队成员和AI助手都能快速定位文件:
project-root/
├── .claude/ # Claude Code专用配置
│ ├── settings.json # 权限和工具配置
│ ├── settings.local.json # 本地覆盖(不入库)
│ ├── commands/ # 自定义Slash命令
│ │ ├── 01-dev.md # 开发相关命令
│ │ ├── 02-test.md # 测试相关命令
│ │ └── 03-deploy.md # 部署相关命令
│ ├── hooks/ # 生命周期钩子
│ │ ├── pre-commit.sh # 提交前检查
│ │ └── post-review.sh # 审查后处理
│ └── skills/ # 技能包
│ └── project-specific/ # 项目特定技能
│ └── SKILL.md # 技能定义(Markdown格式)
├── .github/ # GitHub集成
│ ├── workflows/ # CI/CD工作流
│ │ └── claude-review.yml # Claude自动审查
│ └── CODEOWNERS # 代码所有者
├── docs/ # 项目文档
│ └── ai-context/ # AI上下文文档
│ ├── project-structure.md # 项目结构说明
│ ├── coding-standards.md # 编码规范
│ └── architecture.md # 架构设计
├── src/ # 源代码
├── tests/ # 测试代码
├── CLAUDE.md # 主配置文件
├── .mcp.json # MCP服务器配置
├── .gitignore # Git忽略规则
└── README.md # 项目说明
1.2.2 目录职责划分
.claude/ 目录:Claude Code的"控制中心"
子目录/文件
职责
入库策略
settings.json
团队统一配置
✅ 必须入库
settings.local.json
个人本地配置
❌ 禁止入库
commands/
团队共享命令
✅ 必须入库
hooks/
自动化钩子
✅ 必须入库
skills/
项目技能包
✅ 必须入库
docs/ai-context/ 目录:AI理解项目的"说明书"
这个目录专门存放帮助AI理解项目的文档,不是给人看的README,而是给AI看的上下文:
# docs/ai-context/project-structure.md 示例
## 项目技术栈
- 前端:React 18 + TypeScript 5.0 + Vite 5
- 后端:Node.js 20 + Fastify 4
- 数据库:PostgreSQL 15 + Prisma ORM
- 缓存:Redis 7
- 部署:Docker + Kubernetes
## 核心模块
### 用户模块 (src/modules/user/)
- 负责用户注册、登录、权限管理
- 依赖:JWT认证、bcrypt加密
### 订单模块 (src/modules/order/)
- 负责订单创建、支付、状态管理
- 依赖:用户模块、支付网关
## 代码生成约定
- 所有API响应使用统一格式:{ data, error, meta }
- 数据库操作必须使用Prisma Client
- 所有日期时间使用UTC时区
1.2.3 命名规范
命令文件命名:{序号}-{功能域}.md
序号规则:
-
00-09:基础设施命令(help、setup)
-
10-19:开发命令(dev、build)
-
20-29:测试命令(test、lint)
-
30-39:部署命令(deploy、release)
-
40-49:数据命令(migrate、seed)
-
90-99:工具命令(debug、monitor)
技能包命名:{项目名}-{功能}
示例:
-
ecommerce-checkout:电商结算流程
-
cms-content-workflow:CMS内容工作流
-
analytics-report-generator:分析报告生成器
1.3 CLAUDE.md规范
1.3.1 CLAUDE.md层级结构
下面先看三种常见的指令位置。CLAUDE.md 提供模型上下文,并不是按优先级强制执行的权限配置;互相矛盾的指令仍需人工整理。组织托管指令、个人项目指令及 AGENTS.md 的加载方式也要按当前设置核对:
- 全局配置 (~/.claude/CLAUDE.md)
-
适用于所有项目
-
存放个人偏好、通用规则
- 项目配置 (项目根目录/CLAUDE.md)
-
团队共享,入库管理
-
存放项目特定规则、技术栈说明
- 子目录配置 (子目录/CLAUDE.md)
-
读取该子目录文件时,按需加载模块级指令
-
例如:src/legacy/CLAUDE.md 存放遗留代码的特殊处理规则
1.3.2 项目CLAUDE.md模板
# [项目名称] - Claude Code配置
## 1. 项目概览
- **项目描述**:[一句话描述项目用途]
- **技术栈**:[主要技术栈列表]
- **当前阶段**:[开发/测试/生产]
## 2. 代码规范
### 通用规则
- 所有代码必须有类型注解
- 函数不超过50行,类不超过300行
- 禁止使用any类型(特殊情况需注释说明)
### 命名约定
- 文件名:kebab-case(如 user-service.ts)
- 类名:PascalCase(如 UserService)
- 函数/变量:camelCase(如 getUserById)
- 常量:UPPER_SNAKE_CASE(如 MAX_RETRY_COUNT)
### 文档要求
- 所有公共API必须有JSDoc/TSDoc注释
- 复杂业务逻辑必须有流程说明
- 使用中文注释,代码用英文
## 3. 安全规则
### 禁止行为
- 禁止在代码中硬编码敏感信息
- 禁止提交.env文件到仓库
- 禁止在日志中输出用户隐私数据
### 必须行为
- 所有输入必须验证和消毒
- 数据库查询必须使用参数化
- API必须有速率限制
## 4. 测试要求
- 新功能必须有单元测试
- 核心逻辑测试覆盖率>80%
- 集成测试必须覆盖主要用户流程
## 5. Git规范
### 分支命名
- feature/xxx:新功能
- fix/xxx:bug修复
- refactor/xxx:重构
- docs/xxx:文档更新
### 提交信息
格式:`<type>(<scope>): <description>`
类型:feat、fix、docs、style、refactor、test、chore
## 6. 项目特殊说明
[项目特有的规则和注意事项]
1.3.3 全局CLAUDE.md模板
# 全局Claude Code配置
## 个人偏好
- 使用中文回复
- 代码注释使用中文
- 偏好简洁的代码风格
## 通用安全规则
- 永远不要在代码中包含真实的API密钥
- 敏感操作需要二次确认
- 不自动执行rm -rf或DROP TABLE等危险命令
## 工具偏好
- Git操作:优先使用命令行而非GUI
- 代码格式化:保存时自动格式化
- 测试:修改代码后自动运行相关测试
1.4 代码审查流程
1.4.1 AI辅助代码审查流程
┌─────────────────────────────────────────────────────────────┐
│ AI辅助代码审查流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 开发者提交PR │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ CI触发自动 │ │
│ │ Claude审查 │ │
│ └─────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Claude Code审查内容: │ │
│ │ 1. 代码风格是否符合CLAUDE.md规范 │ │
│ │ 2. 是否有潜在的安全漏洞 │ │
│ │ 3. 是否有性能问题 │ │
│ │ 4. 测试覆盖是否充分 │ │
│ │ 5. 文档是否完整 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 自动添加审查评论到PR │
│ │ │
│ ▼ │
│ 人工审查员复核 │
│ │ │
│ ▼ │
│ 合并或请求修改 │
│ │
└─────────────────────────────────────────────────────────────┘
1.4.2 代码审查Slash命令
创建 .claude/commands/team-review.md,在会话中用 /team-review 调用,避免与捆绑的 /code-review Skill 混淆:
---
description: 按团队标准只读审查当前 Git 变更
---
# 代码审查
先只读查看当前 Git diff;没有未提交变更时,询问要审查的分支或提交范围。不要自动修改文件。按以下维度报告有依据的问题:
## 审查维度
### 1. 代码质量
- 代码是否清晰可读
- 命名是否表意
- 是否有重复代码
- 函数/类是否过长
### 2. 安全性
- 输入验证是否充分
- 是否有SQL注入风险
- 是否有XSS风险
- 敏感数据处理是否安全
### 3. 性能
- 是否有N+1查询问题
- 循环内是否有不必要的计算
- 是否使用了适当的数据结构
### 4. 测试
- 是否有对应的测试
- 测试覆盖是否充分
- 边界情况是否考虑
### 5. 文档
- 公共API是否有文档
- 复杂逻辑是否有注释
- README是否需要更新
## 输出格式
## 审查结果
### 必须修改 (Blocking)
- [问题描述]
- 位置:[文件:行号]
- 建议:[修改建议]
### 建议修改 (Suggestion)
- [问题描述]
- 位置:[文件:行号]
- 建议:[修改建议]
### 表扬 (Praise)
- [做得好的地方]
请开始审查...
1.4.3 审查清单
检查项
通过条件
优先级
代码风格
符合CLAUDE.md规范
P0
安全检查
无高危漏洞
P0
测试覆盖
新代码有测试
P1
文档完整
API有注释
P1
性能考量
无明显性能问题
P2
1.5 团队协作最佳实践
1.5.1 配置同步策略
入库配置(团队共享):
# .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
1.5.2 配置冲突解决
个人项目设置可放在 .claude/settings.local.json。普通设置按相应规则合并,权限数组也会合并;下面只是增加预批准操作,不会撤销团队或托管策略中的拒绝规则:
// .claude/settings.local.json(不入库,增加个人预批准项)
{
"permissions": {
"allow": [
"Bash(npm run dev)",
"Bash(npm run test)"
]
}
}
1.5.3 新成员入职流程
## Claude Code新成员入职清单
### 第1步:环境准备
- [ ] 安装Claude Code CLI
- [ ] 配置全局CLAUDE.md
- [ ] 选择团队批准的订阅登录、API 密钥或云供应商认证方式
### 第2步:项目配置
- [ ] 克隆项目仓库
- [ ] 运行 `claude` 初始化
- [ ] 检查MCP服务器是否正常
### 第3步:熟悉规范
- [ ] 阅读项目CLAUDE.md
- [ ] 运行 `/help` 查看可用命令
- [ ] 尝试运行一次代码审查
### 第4步:验证配置
- [ ] 运行测试命令确认配置正确
- [ ] 提交一个测试PR验证CI流程
2. CI/CD集成
2.1 GitHub Actions集成概述
Claude Code可以深度集成到GitHub Actions中,实现:
-
自动代码审查
-
PR评论交互
-
安全扫描
-
文档生成
2.1.1 官方Action介绍
Anthropic提供了官方的GitHub Action:anthropics/claude-code-action
主要功能:
-
在PR上自动运行Claude Code审查
-
响应Issue评论中的指令
-
执行自定义命令
2.2 GitHub Actions配置详解
2.2.1 基础配置
创建 .github/workflows/claude-review.yml:
name: Claude Code Review
on:
pull_request:
types: [opened, synchronize, reopened]
issue_comment:
types: [created]
# 权限配置:授予必要的GitHub权限
permissions:
id-token: write
contents: read
pull-requests: write
issues: write
jobs:
claude-review:
# 条件:PR事件 或 Issue评论中包含@claude
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 # 获取完整历史,用于diff比较
- name: Run Claude Code Review
uses: anthropics/claude-code-action@v1
with:
# API密钥(必须在仓库Secrets中配置)
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
# CLI 选项统一放到 claude_args;Action v1 没有这里的独立 model/max_tokens/timeout 输入
claude_args: "--model sonnet --max-turns 10"
prompt: "审查本次 PR 的改动,指出具体问题与验证方法。"
2.2.2 高级配置:多场景工作流
name: Claude Code CI/CD Integration
on:
pull_request:
types: [opened, synchronize, reopened]
issue_comment:
types: [created]
push:
branches: [main, develop]
permissions:
id-token: write
contents: read
pull-requests: write
issues: write
actions: read
env:
# 共享环境变量
CLAUDE_MODEL: claude-sonnet-5
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: Get changed files
id: changed-files
uses: tj-actions/changed-files@v40
- name: Claude Code Review
uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
claude_args: "--model ${{ env.CLAUDE_MODEL }} --max-turns 10"
prompt: |
请审查以下代码变更:
变更文件:${{ steps.changed-files.outputs.all_changed_files }}
审查要点:
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 }}
claude_args: "--model ${{ env.CLAUDE_MODEL }} --max-turns 10"
prompt: |
请对本次PR进行安全扫描,检查:
1. 硬编码的敏感信息(API密钥、密码等)
2. SQL注入漏洞
3. XSS漏洞
4. 不安全的依赖
5. 权限配置问题
如果发现问题,请标记为 [SECURITY] 并说明风险等级。
# ========== 交互式命令处理 ==========
interactive:
name: Interactive Commands
if: |
github.event_name == 'issue_comment' &&
contains(github.event.comment.body, '@claude')
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Process Claude Command
uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
claude_args: "--model ${{ env.CLAUDE_MODEL }} --max-turns 10"
# 从评论中提取命令
prompt: ${{ github.event.comment.body }}
# ========== 文档生成(push到main时) ==========
docs:
name: Generate Documentation
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Generate API Docs
uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
claude_args: "--model ${{ env.CLAUDE_MODEL }} --max-turns 10"
prompt: |
请扫描src/目录下的代码,生成可审阅的API文档草稿,不提交或推送变更。
文档格式要求:
1. Markdown格式
2. 包含函数签名、参数说明、返回值
3. 包含使用示例
输出到docs/api/目录。
- name: Upload API docs draft
uses: actions/upload-artifact@v4
with:
name: api-docs-draft
path: docs/api/
if-no-files-found: error
文档草稿保存在本次运行的 api-docs-draft artifact 中。下载后人工核对内容,再决定是否提交到仓库;只在 runner 中写文件不会让草稿自动出现在项目里。
2.2.3 配置Secrets
在GitHub仓库设置中添加以下Secrets:
Secret名称
说明
获取方式
ANTHROPIC_API_KEY
Anthropic API密钥
console.anthropic.com
GITHUB_TOKEN
GitHub Token
自动提供(默认)
配置路径:Settings > Secrets and variables > Actions > New repository secret
2.3 /security-review命令
2.3.1 创建安全审查命令
创建 .claude/commands/team-security-audit.md,用 /team-security-audit 调用。本例是自定义检查清单,后面的 /security-review 则使用内置安全审查入口:
---
description: 按团队检查清单只读审查安全风险
---
# 安全代码审查
## 审查范围
对指定文件或整个项目进行安全审查。
## 检查清单
### 1. 认证与授权
- [ ] 密码存储是否使用安全哈希(bcrypt/argon2)
- [ ] JWT密钥是否足够复杂
- [ ] 会话管理是否安全
- [ ] 权限检查是否完整
### 2. 输入验证
- [ ] 所有用户输入是否验证
- [ ] 是否防止SQL注入
- [ ] 是否防止XSS攻击
- [ ] 是否防止命令注入
### 3. 敏感数据
- [ ] API密钥是否硬编码
- [ ] 数据库凭据是否安全存储
- [ ] 日志是否泄露敏感信息
- [ ] 错误信息是否泄露内部细节
### 4. 配置安全
- [ ] HTTPS是否强制
- [ ] CORS是否正确配置
- [ ] 安全头是否设置
- [ ] Cookie是否安全配置
### 5. 依赖安全
- [ ] 是否有已知漏洞的依赖
- [ ] 依赖版本是否及时更新
- [ ] 是否使用可信的包源
## 输出格式
# 安全审查报告
## 概要
- 审查时间:[时间]
- 审查范围:[范围]
- 风险等级:[高/中/低]
## 发现的问题
### 高危 (Critical)
**问题**:...
**位置**:...
**描述**:...
**修复建议**:...
### 中危 (Medium)
**问题**:...
### 低危 (Low)
**问题**:...
## 最佳实践建议
[改进建议]
## 执行
请开始安全审查...
2.3.2 在CI中集成安全审查
# .github/workflows/security.yml
name: Security Review
on:
pull_request:
paths:
- 'src/**'
- 'package.json'
- 'package-lock.json'
permissions:
contents: read
pull-requests: read
id-token: write
jobs:
security:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Run Security Review
uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
claude_args: "--model sonnet --max-turns 10"
prompt: |
审查当前 PR 的安全风险,不修改业务代码。
把结果写入 security-review.json:
{"critical": false, "findings": []}
critical 必须是布尔值;发现高危问题时设为 true。
findings 中逐项列出文件、位置、原因和修复建议。
- name: Validate Report and Check Critical Issues
run: |
set -euo pipefail
test -s security-review.json
jq -e 'type == "object" and (.critical | type == "boolean") and (.findings | type == "array")' security-review.json > /dev/null
if jq -e '.critical == true' security-review.json > /dev/null; then
echo "::error::模型审查报告包含高危问题,请人工检查"
exit 1
fi
此处是模型辅助审查门禁:报告缺失或格式错误也会失败,避免空结果被当成通过。它仍不能代替确定性的测试、依赖扫描或人工审查;fork PR 的 Secret 与 GitHub App 权限也要按仓库策略配置。
2.4 /install-github-app命令
2.4.1 GitHub App 与 Action 的安装关系
官方 GitHub App 提供仓库授权,Action 在你的 GitHub 工作流中运行 Claude Code;两者是配套部件,不是二选一的自动化系统。
快速安装需要仓库管理员权限,且适用于 github.com:先安装 GitHub CLI 并完成 gh auth login,然后在目标仓库的 Claude Code 会话中运行 /install-github-app,按提示选择仓库、认证方式和工作流。该流程可能保存 Secret、推送工作流分支并准备 PR,请查看完成提示,审阅工作流 PR 后再合并。
手动安装时:
-
从 官方安装说明 打开 Claude GitHub App 的安装链接,选择组织及允许的仓库。
-
查看并接受官方 App 当前的完整权限集。不能在安装时把 Contents 等权限单独改成只读;需要更窄授权的组织应按 Action 官方 setup 指南创建自有 App。
-
添加认证 Secret:API 密钥使用 ANTHROPIC_API_KEY;订阅 token 使用 CLAUDE_CODE_OAUTH_TOKEN,并在工作流中选择对应输入。
-
复制并审阅官方工作流,确认事件、仓库权限和 Secret 配置后,再在测试 Issue 或 PR 中用 @claude 验证。
安装官方 App 不需要你填写自己的 Webhook URL,也不会自动给所有仓库生成工作流。跨仓库推广时,可以共享组织 Secret,但每个目标仓库仍需工作流或调用可复用工作流。
2.5 多阶段CI/CD流水线骨架
这是按阶段组织的架构示例。构建和测试命令要适配你的项目;部署阶段尚未接入实际平台,下面会主动失败,避免只有一条 echo 也被报告为部署成功。补齐部署脚本、凭据、环境审批和结果校验后,再启用对应分支的部署流程。
2.5.1 多阶段流水线
# .github/workflows/full-pipeline.yml
name: Full CI/CD Pipeline with Claude
on:
push:
branches: [main, develop]
pull_request:
branches: [main]
env:
NODE_VERSION: '20'
CLAUDE_MODEL: claude-sonnet-5
permissions:
contents: read
pull-requests: write
issues: write
id-token: write
jobs:
# ===== 阶段1:代码检查 =====
lint:
name: Lint & Format
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ env.NODE_VERSION }}
- run: npm ci
- run: npm run lint
- run: npm run format:check
# ===== 阶段2:单元测试 =====
test:
name: Unit Tests
runs-on: ubuntu-latest
needs: lint
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ env.NODE_VERSION }}
- run: npm ci
- run: npm test -- --coverage
- uses: codecov/codecov-action@v3
# ===== 阶段3:Claude代码审查(仅PR) =====
claude-review:
name: Claude Code Review
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
needs: test
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Get PR Diff
id: diff
run: |
git diff origin/main...HEAD > pr_diff.txt
echo "diff_size=$(wc -l < pr_diff.txt)" >> $GITHUB_OUTPUT
- name: Claude Review
if: steps.diff.outputs.diff_size > 0
uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
claude_args: "--model ${{ env.CLAUDE_MODEL }} --max-turns 10"
prompt: |
请审查这个PR的代码变更:
1. 代码质量评估
2. 潜在bug分析
3. 性能建议
4. 安全检查
请给出具体的改进建议。
# ===== 阶段4:安全扫描 =====
security:
name: Security Scan
runs-on: ubuntu-latest
needs: test
steps:
- uses: actions/checkout@v4
- name: Install dependencies
run: npm ci
- name: Run npm audit
run: npm audit --audit-level=high
- name: Claude Security Scan
uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: "/security-review"
# ===== 阶段5:构建 =====
build:
name: Build
runs-on: ubuntu-latest
needs: [test, security]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ env.NODE_VERSION }}
- run: npm ci
- run: npm run build
- uses: actions/upload-artifact@v4
with:
name: build-output
path: dist/
# ===== 阶段6:部署到Staging(仅develop分支) =====
deploy-staging:
name: Deploy to Staging
if: github.ref == 'refs/heads/develop'
runs-on: ubuntu-latest
needs: build
environment: staging
steps:
- name: Download build
uses: actions/download-artifact@v4
with:
name: build-output
- name: Deploy to Staging
run: |
echo "尚未配置 Staging 部署脚本,请按目标平台补齐并验证"
exit 1
# ===== 阶段7:部署到Production(仅main分支) =====
deploy-production:
name: Deploy to Production
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
needs: build
environment: production
steps:
- name: Download build
uses: actions/download-artifact@v4
with:
name: build-output
- name: Deploy to Production
run: |
echo "尚未配置 Production 部署脚本,请按目标平台补齐并验证"
exit 1
- name: Claude Deployment Report
uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: |
根据本次工作流中真实部署步骤及其校验结果生成报告,不要仅根据任务名称断言成功:
- 版本:${{ github.sha }}
- 分支:${{ github.ref }}
- 触发者:${{ github.actor }}
3. 安全与合规
3.1 权限系统详解
Claude Code采用三级权限模型:Allow(允许)、Ask(询问)、Deny(拒绝)
3.1.1 权限级别说明
Allow(允许):
-
工具可以直接执行,无需确认
-
适用于低风险、频繁使用的操作
-
示例:读取文件、搜索代码
Ask(询问):
-
执行前需要用户确认
-
适用于有一定风险的操作
-
示例:修改文件、执行命令
Deny(拒绝):
-
完全禁止执行
-
适用于高风险或违反政策的操作
-
示例:访问敏感目录、执行危险命令
3.1.2 权限配置文件
// .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(git reset --hard)", // 禁止硬重置
"Bash(sudo *)", // 禁止sudo命令
"Bash(curl * | bash)" // 禁止远程脚本执行
]
}
}
说明:permissions 支持 allow、ask、deny 列表。未命中规则的调用继续按权限模式和工具默认行为处理;部分只读操作无需询问。匹配的 deny 优先,但命令字符串规则不能代替文件系统或网络隔离。
3.1.3 运行时权限覆盖
# 临时放宽权限(单次会话)
claude --dangerously-skip-permissions
# 临时使用计划模式(需审批后才执行)
claude --permission-mode plan
# 查看当前认证状态
claude auth status
# 在交互会话里用 /config 看设置,用 /permissions 看权限
# 或在REPL中使用 /permissions 查看权限详情
3.1.4 Sandbox沙箱配置详解
在 Claude Code 会话中运行 /sandbox 打开面板,选择模式并确认,或在设置中启用。OS 沙箱限制 shell 命令及子进程,文件工具、MCP、Hook 不在这层边界内。默认可读取机器上的多数文件,可写启动目录和指定临时目录;下面是新增路径与拒绝路径的合并片段,不是完整的文件白名单:
Linux(v2.1.92,摘自 release):Linux sandbox now ships the apply-seccomp helper in both npm and native builds, restoring unix-socket blocking for sandboxed commands。即在 Linux 上,沙箱附带 apply-seccomp 辅助组件;具体启用方式与排障以官方文档及 claude /sandbox 提示为准,本处不臆造命令行开关组合。
// .claude/settings.json
{
"sandbox": {
"enabled": true,
"filesystem": {
"allowWrite": ["/tmp", "./src"],
"allowRead": ["./", "/usr/lib"],
"denyRead": [".env", "credentials.json"]
}
}
}
权限字段说明:
字段
作用
示例
allowWrite
在默认可写路径之外增加允许路径
["/tmp", "./src", "./tests"]
allowRead
在较宽拒绝路径内重新开放较窄的读取路径
["./", "/usr/lib"]
denyRead
拒绝读取相应路径;重叠规则还要比较路径范围
["./.env", "./credentials.json", "./secrets/**"]
注意:普通 sandbox 读取规则重叠时,更窄的路径范围生效:宽范围允许不能重新暴露窄范围拒绝的文件,窄范围允许可以重新开放宽范围拒绝目录中的一部分。组织托管的拒绝读取规则另有约束,项目设置不能用更窄的允许路径重新开放它,也不能扩大管理员的严格允许名单。先核对设置来源,再判断例外是否生效;这一边界见官方 v2.1.285 策略变化。OS sandbox 仅支持 macOS、Linux 和 WSL2,原生 Windows 的命令不受此沙箱保护。
3.2 用权限规则预批准常用操作
3.2.1 正确的 settings.json 结构
allowedTools / disallowedTools 是 CLI / SDK 的选项名称。设置文件使用 permissions.allow、permissions.ask 和 permissions.deny,不要把那两个选项直接写成顶层字段。
{
"permissions": {
"allow": [
"Read",
"Glob",
"Grep",
"Bash(npm test)",
"Bash(npm run lint)",
"Bash(git status)",
"Bash(git diff *)"
],
"ask": ["Bash(git push *)"],
"deny": [
"Read(./.env)",
"Read(./secrets/**)",
"Bash(sudo *)"
]
}
}
3.2.2 规则的实际含义
-
allow 让匹配的调用免审批,不会移除列表之外的工具,也不等于所有其他操作都被禁止。
-
deny、ask、allow 按这一顺序处理;匹配的拒绝规则优先于允许规则。
-
Bash(npm test) 是一个具体入口;Bash(npm *) 会放宽到许多 npm 操作,不能因为它包含“测试”就当成只读。
-
文件工具规则和 shell / MCP 的访问路径不同。只拒绝 Read(./.env),不代表其他工具无法读到该文件。
-
精确命令模式会按命令写法匹配。别把少量危险字符串的黑名单当成完整系统防护。
3.2.3 团队与个人配置
团队共享规则放 .claude/settings.json,个人项目设置放 .claude/settings.local.json,用户偏好放 ~/.claude/settings.json。权限数组会合并:项目级增加一份较窄的 allow 列表,不会自动撤回用户级已经批准的 Bash(*)。需要组织统一限制时,用托管策略并核对它的适用范围。
3.3 MCP服务器安全管理
3.3.1 MCP配置规范
项目 MCP 服务器可写在 .mcp.json。本例展示 stdio 类型的 command、args、env;HTTP 类型使用 type、url 等字段。内部服务脚本必须先实现,示例服务名和路径不会自动生成服务器。
// .mcp.json — 标准MCP配置格式
{
"mcpServers": {
// 内部API服务器
"internal-api": {
"command": "node",
"args": ["./mcp-servers/internal-api/index.js"],
"env": {
"API_KEY": "${INTERNAL_API_KEY}"
}
},
// 第三方文档服务器
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp"]
},
// 外部工具
"external-tool": {
"command": "npx",
"args": ["-y", "external-mcp-tool"],
"env": {
"TIMEOUT": "30000"
}
}
}
}
注意:先核对服务器来源、启动命令或 URL,再审批项目 .mcp.json 的连接。permissions 控制工具调用的审批,不会把服务器进程限制成文件系统沙箱;配置中的地址、凭据与依赖也需要审查。
3.3.2 通过权限系统管理MCP安全
使用settings.json的权限规则控制MCP工具的使用范围:
// .claude/settings.json
{
"permissions": {
"allow": [
// 预批准 Context7 服务器工具;不是只允许这些工具的白名单
// 若只批准单个工具,先在 /mcp 查看当前精确工具名称再写规则
"mcp__context7__*"
],
"deny": [
// 禁止危险的MCP操作
"mcp__*__delete_*",
"mcp__*__drop_*"
]
}
}
3.3.3 MCP安全最佳实践
环境变量隔离:
{
"mcpServers": {
"my-server": {
"command": "node",
"args": ["server.js"],
"env": {
// 使用环境变量引用,不硬编码
"API_KEY": "${MCP_API_KEY}",
"DB_URL": "${MCP_DB_URL}"
}
}
}
}
通过Hooks监控MCP调用:
下面用 PreToolUse 记录即将发起的 MCP 工具调用。事件数据通过 stdin JSON 传入;该记录表示调用请求已到达 Hook,不代表工具已经成功执行。
先创建项目的 .claude/hooks/ 目录,把下面的 Python 3 脚本保存为 .claude/hooks/log-tool-event.py。它先创建日志目录,再用 JSON 编码器写入 UTF-8 JSONL,每行一条记录,文件路径中的引号、反斜杠和换行都会正确转义:
import json
import sys
from datetime import datetime, timezone
from pathlib import Path
data = json.load(sys.stdin)
entry = {
"timestamp": datetime.now(timezone.utc).isoformat(),
"hook_event_name": data["hook_event_name"],
"session_id": data["session_id"],
"tool_use_id": data["tool_use_id"],
"tool_name": data["tool_name"],
}
# 文件路径属于具体工具的输入;不是通用环境变量。
tool_input = data.get("tool_input", {})
if data["tool_name"] == "Write" and isinstance(tool_input, dict):
file_path = tool_input.get("file_path")
if isinstance(file_path, str):
entry["file_path"] = file_path
for optional_field in ("duration_ms", "is_interrupt"):
if optional_field in data:
entry[optional_field] = data[optional_field]
log_path = Path(sys.argv[1])
log_path.parent.mkdir(parents=True, exist_ok=True)
with log_path.open("a", encoding="utf-8", newline="\n") as log_file:
log_file.write(json.dumps(entry, ensure_ascii=False) + "\n")
把下面的事件配置合并进 .claude/settings.json 现有的 hooks 对象。command 应指向本机的 Python 3 可执行文件;-X utf8 让 Python 按 UTF-8 读取 stdin。使用 args 时,${CLAUDE_PROJECT_DIR} 由 Claude Code 展开为项目根目录,每个路径作为完整参数传入:
{
"hooks": {
"PreToolUse": [
{
"matcher": "^mcp__.*",
"hooks": [
{
"type": "command",
"command": "python",
"args": [
"-X",
"utf8",
"${CLAUDE_PROJECT_DIR}/.claude/hooks/log-tool-event.py",
"${CLAUDE_PROJECT_DIR}/logs/mcp-calls.jsonl"
]
}
]
}
]
}
}
安全建议:
-
定期审查.mcp.json中配置的服务器列表
-
使用permissions.deny禁止MCP服务器中的危险操作
-
通过环境变量传递所有敏感凭证,不要硬编码
-
使用Hooks记录MCP工具调用日志
3.4 审计日志
3.4.1 通过Hooks实现审计日志
复用 3.3.3 节的 log-tool-event.py,把以下事件合并到 .claude/settings.json 的 hooks 对象中。PostToolUse 记录成功执行后的工具事件;PostToolUseFailure 记录已开始执行但失败的工具事件。这里监控 Bash 和 Write,并把记录追加到同一个 JSONL 文件:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Bash|Write",
"hooks": [
{
"type": "command",
"command": "python",
"args": [
"-X",
"utf8",
"${CLAUDE_PROJECT_DIR}/.claude/hooks/log-tool-event.py",
"${CLAUDE_PROJECT_DIR}/logs/claude-audit.jsonl"
]
}
]
}
],
"PostToolUseFailure": [
{
"matcher": "Bash|Write",
"hooks": [
{
"type": "command",
"command": "python",
"args": [
"-X",
"utf8",
"${CLAUDE_PROJECT_DIR}/.claude/hooks/log-tool-event.py",
"${CLAUDE_PROJECT_DIR}/logs/claude-audit.jsonl"
]
}
]
}
]
}
}
日志从 stdin 读取 tool_name、hook_event_name、会话/调用 ID,以及 Write 的 tool_input.file_path;事件提供时还记录 duration_ms 和 is_interrupt。Claude Code 不会自动把这些字段导出成 $CLAUDE_TOOL_NAME、$CLAUDE_TOOL_EXIT_CODE 或 $CLAUDE_FILE_PATHS。PostToolUse 的 tool_response 结构随工具变化,失败事件的 error 是说明字符串,因此脚本按事件名保留结果类别,不猜测统一的工具退出码或返回结构。
这份日志不包含命令正文、文件内容或工具返回全文。权限拒绝发生在执行前,不会触发 PostToolUseFailure;需要审计此类拒绝时,应另配 PermissionDenied。输入契约见 官方 PostToolUse 和 PostToolUseFailure。
3.4.2 审计日志格式
上面的 Hook 直接生成逐行 JSONL。下方是团队自行设计的每日汇总格式,示例文件为 logs/claude-audit/2025-01-15.json,也是 3.4.3 节分析脚本要求的输入。使用前需要另外完成 JSONL 到该格式的转换和字段映射;userId、分支、差异统计及权限拒绝记录需要各自的数据来源,不由上面的 Hook 自动补齐。
{
"entries": [
{
"timestamp": "2025-01-15T10:30:45.123Z",
"sessionId": "sess_abc123",
"userId": "[email protected]",
"event": "tool_use",
"tool": "Bash",
"command": "npm test",
"status": "success",
"duration": 5432,
"context": {
"workingDir": "/project",
"branch": "feature/auth"
}
},
{
"timestamp": "2025-01-15T10:31:00.456Z",
"sessionId": "sess_abc123",
"userId": "[email protected]",
"event": "file_access",
"tool": "Edit",
"path": "src/auth/login.ts",
"action": "modify",
"status": "success",
"diff": {
"linesAdded": 15,
"linesRemoved": 3
}
},
{
"timestamp": "2025-01-15T10:32:00.789Z",
"sessionId": "sess_abc123",
"userId": "[email protected]",
"event": "permission_denied",
"tool": "Read",
"path": ".env.production",
"reason": "Path in denied list",
"status": "blocked"
}
]
}
3.4.3 审计日志分析
创建审计分析脚本:
#!/usr/bin/env python3
# scripts/analyze-audit.py
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": [],
"errors": [],
"users": Counter(),
"sensitive_access": []
}
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, encoding="utf-8") 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)
if entry.get("event") == "error":
stats["errors"].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("")
report.append(f"总事件数:{stats['total_events']}")
report.append("")
report.append("工具使用统计:")
for tool, count in stats["tool_usage"].most_common(10):
report.append(f" - {tool}: {count}次")
report.append("")
report.append("用户活动统计:")
for user, count in stats["users"].most_common(10):
report.append(f" - {user}: {count}次")
report.append("")
if stats["denied_access"]:
report.append(f"权限拒绝事件:{len(stats['denied_access'])}次")
for entry in stats["denied_access"][:5]:
report.append(f" - {entry['timestamp']}: {entry.get('path', 'N/A')}")
report.append("")
if stats["errors"]:
report.append(f"错误事件:{len(stats['errors'])}次")
for entry in stats["errors"][:5]:
report.append(f" - {entry['timestamp']}: {entry.get('message', 'N/A')}")
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))
3.5 合规性检查清单
3.5.1 数据保护合规
下面是团队核查事项,不是产品对“零上传、零留存”的承诺。数据政策取决于账号、供应商和组织合同;以 官方数据使用说明 及本团队实际配置为依据。
## GDPR/个人信息保护合规检查
### 数据收集
- [ ] 已核对账号、供应商、合同和训练设置,明确允许发送的数据类型
- [ ] 已核对会话留存、遥测、反馈及第三方服务的数据流;需要 ZDR 时确认已实际启用
- [ ] API密钥通过环境变量传递,不硬编码
### 数据处理
- [ ] 已明确审查中哪些代码与提示词会发送到模型服务,并按团队批准范围控制输入
- [ ] 敏感文件的文件工具、shell、MCP 和 Hook 访问路径已分别限制和验证
- [ ] 审计日志中脱敏处理
### 数据存储
- [ ] 本地日志有访问控制
- [ ] 日志保留期限符合政策
- [ ] 定期清理过期数据
3.5.2 访问控制合规
## 访问控制检查清单
### 身份认证
- [ ] API密钥安全存储
- [ ] 密钥定期轮换
- [ ] 不同环境使用不同密钥
### 权限管理
- [ ] 最小权限原则
- [ ] 权限配置入库管理
- [ ] 权限变更有审批流程
### 审计追踪
- [ ] 所有敏感操作有日志
- [ ] 日志防篡改
- [ ] 异常行为有告警
4. 性能优化
4.1 上下文管理
4.1.1 上下文窗口理解
Claude Code使用的模型有上下文窗口限制,理解并优化上下文使用是提升性能的关键:
上下文组成:
┌─────────────────────────────────────────────────────────────┐
│ 上下文窗口构成 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ │
│ │ 系统提示词 │ ~2,000 tokens │
│ │ (System Prompt) │ │
│ └─────────────────┘ │
│ │ │
│ ┌─────────────────┐ │
│ │ CLAUDE.md │ ~1,000-5,000 tokens │
│ │ 项目配置 │ │
│ └─────────────────┘ │
│ │ │
│ ┌─────────────────┐ │
│ │ 对话历史 │ 动态增长 │
│ │ (History) │ │
│ └─────────────────┘ │
│ │ │
│ ┌─────────────────┐ │
│ │ 工具结果 │ 动态增长 │
│ │ (Tool Results) │ │
│ └─────────────────┘ │
│ │ │
│ ┌─────────────────┐ │
│ │ 当前消息 │ 用户输入 │
│ │ (Current) │ │
│ └─────────────────┘ │
│ │
│ 总计:取决于当前模型、账号权限和 Claude Code 版本 │
│ │
└─────────────────────────────────────────────────────────────┘
4.1.2 上下文优化策略
策略1:精简CLAUDE.md
# 优化前(冗长)
## 代码规范
我们的团队使用以下代码规范。首先,所有代码必须使用TypeScript编写。
其次,我们要求所有函数都有JSDoc注释。另外,变量命名必须遵循
camelCase规范。还有,类名必须使用PascalCase...
(继续500字)
# 优化后(精简)
## 代码规范
- 语言:TypeScript
- 注释:JSDoc必需
- 命名:变量camelCase,类PascalCase
- 行数:函数<50行,类<300行
策略2:使用文件引用而非内联
# 不推荐:在CLAUDE.md中内联大量内容
## API文档
{大量JSON内容...}
# 推荐:引用外部文件
## API文档
详见 `docs/api-reference.md`
策略3:分层配置
项目根目录/CLAUDE.md # 核心规则(<1000 tokens)
├── src/CLAUDE.md # 模块规则(如 src 目录,<500 tokens)
├── tests/CLAUDE.md # 测试规则(<500 tokens)
└── docs/CLAUDE.md # 文档规则(<300 tokens)
4.1.3 对话管理
定期清理对话:
# 当对话过长时,使用/clear清理
/clear
# 或创建新会话
claude
# 跨设备继续会话
/teleport # 把符合条件的 Web 会话接到本地 CLI(也可用 /tp);不是双向传送
分解大任务:
# 不推荐:一次性大任务
"重构整个项目的所有模块,包括用户模块、订单模块、支付模块..."
# 推荐:分步骤小任务
1. "先分析用户模块的当前结构"
2. "基于分析结果,提出重构方案"
3. "执行用户模块重构"
4. "验证用户模块重构结果"
5. "继续处理订单模块..."
💡 Shift+Enter换行
-
在对话框中按 Shift+Enter 可以换行而不发送消息
-
支持情况取决于终端;VS Code、Cursor 等需先运行 /terminal-setup。通用替代是 Ctrl+J 或输入反斜杠后按 Enter
-
适合输入多行指令或复杂提示词
4.2 --verbose调试
4.2.1 启用详细日志
# 启用verbose模式(CLI标志,不是配置文件选项)
claude --verbose
# 同时启用debug模式获取更详细信息
claude --verbose --debug
# 保存调试日志排查问题(先注意日志中可能包含项目内容)
claude --debug-file ./claude-debug.log
4.2.2 verbose输出解读
下方是为了讲解而编写的示意日志,不是当前 CLI 的稳定输出格式。实际排障先看本机生成的 debug 日志,不要按这些虚构字段编写解析器。
[DEBUG] 2025-01-15 10:30:45.123 Session started: sess_abc123
[DEBUG] 2025-01-15 10:30:45.125 Loading CLAUDE.md from /project/CLAUDE.md
[DEBUG] 2025-01-15 10:30:45.130 CLAUDE.md tokens: 1,234
[DEBUG] 2025-01-15 10:30:45.135 Loading .claude/settings.json
[DEBUG] 2025-01-15 10:30:45.140 MCP servers: 3 configured
[DEBUG] 2025-01-15 10:30:45.200 MCP server 'context7' connected
[DEBUG] 2025-01-15 10:30:45.300 MCP server 'exa' connected
[DEBUG] 2025-01-15 10:30:45.400 MCP server 'task-master' connected
[INFO] User message received: "帮我分析src/auth目录的代码结构"
[DEBUG] 2025-01-15 10:30:46.000 Context size: 5,432 tokens
[DEBUG] 2025-01-15 10:30:46.001 Available context: 194,568 tokens
[DEBUG] 2025-01-15 10:30:46.002 Model: claude-sonnet-5
[DEBUG] 2025-01-15 10:30:46.100 Tool call: Glob
[DEBUG] 2025-01-15 10:30:46.101 Pattern: src/auth/**/*
[DEBUG] 2025-01-15 10:30:46.150 Result: 12 files found
[DEBUG] 2025-01-15 10:30:46.151 Tokens used: 234
[DEBUG] 2025-01-15 10:30:46.200 Tool call: Read
[DEBUG] 2025-01-15 10:30:46.201 Path: src/auth/index.ts
[DEBUG] 2025-01-15 10:30:46.250 Result: 156 lines, 2,345 tokens
[DEBUG] 2025-01-15 10:30:47.000 API request sent
[DEBUG] 2025-01-15 10:30:47.001 Input tokens: 8,011
[DEBUG] 2025-01-15 10:30:47.002 Max output tokens: 4,096
[DEBUG] 2025-01-15 10:30:52.000 API response received
[DEBUG] 2025-01-15 10:30:52.001 Output tokens: 1,234
[DEBUG] 2025-01-15 10:30:52.002 Latency: 5,000ms
[DEBUG] 2025-01-15 10:30:52.003 Cost: $0.0234
4.2.3 性能瓶颈定位
常见瓶颈及解决方案:
症状
可能原因
解决方案
响应慢
上下文过大
清理对话,精简CLAUDE.md
工具调用失败
MCP服务器问题
检查MCP配置和网络
频繁token超限
单次请求过大
分解任务
成本过高
无效调用多
优化提示词,减少迭代
4.3 成本控制
4.3.1 成本计算公式
单次对话成本 = (输入tokens / 1M * 输入价格) + (输出tokens / 1M * 输出价格)
示例(请替换成你当前模型价格):
- 输入:$X/百万tokens
- 输出:$Y/百万tokens
- 一次10K输入+2K输出:(10,000/1M * X) + (2,000/1M * Y)
输出 token 提醒:不同模型、账号和 provider 的最大输出长度不同,且会随 release 更新。大规模生成代码或文档时,先用当前 /status、模型设置、官方价格页和 release notes 确认上限与计费,不要把旧数字当固定事实。
4.3.2 成本优化策略
策略1:选择合适的模型
任务类型
推荐选择
原因
简单代码生成
当前可用的低成本/快速模型
成本低,速度快
代码审查
当前可用的平衡模型
兼顾质量和成本
架构设计
当前可用的高能力模型
复杂推理能力更强
策略2:批量处理
# 不推荐:逐个文件处理
claude "检查src/a.ts的代码质量"
claude "检查src/b.ts的代码质量"
claude "检查src/c.ts的代码质量"
# 推荐:批量处理
claude "检查src/目录下所有.ts文件的代码质量,生成汇总报告"
策略3:利用API层面的Prompt Caching
Claude API支持Prompt Caching,可大幅降低重复上下文的成本:
Prompt Caching 演示算例(假设以下费率,不代表当前模型报价):
- 正常输入:$3.0/百万tokens
- 缓存写入:$3.75/百万tokens(1.25倍)
- 缓存读取:$0.30/百万tokens(0.1倍)
场景:重复使用5000 tokens的系统提示
- 无缓存:每次 $0.015
- 有缓存:首次 $0.01875,缓存命中时后续重复输入每次 $0.0015
- 90% 是本算例中后续缓存输入的降幅,不是完整调用或总账单的保证;还要计算缓存有效期、新输入和输出费用
注意:Prompt Caching在API层面自动管理,Claude Code CLI用户无需手动配置。对于使用Agent SDK构建应用的开发者,可以在API调用中利用此特性。
4.3.3 成本监控
创建成本估算脚本并保存为 scripts/monitor-cost.py。它读取你自行整理的 <日期>.json 中的 entries、model、tokens.input/output,不是 Claude Code 客户端原生日志解析器。上文 MCP 审计日志没有这些 token 字段,不能直接拿来计算费用;缺数据时应报告无法估算,最终消费以供应商账单为准。
#!/usr/bin/env python3
# scripts/monitor-cost.py
import json
from pathlib import Path
from datetime import datetime, timedelta
# 仅供演示的费率(美元/百万 tokens),不是现行报价。
# 运行前按所用供应商核价并替换;本示例未计缓存、折扣和地区附加费。
PRICING = {
"claude-sonnet-5": {"input": 3.0, "output": 15.0},
"claude-haiku-4-5-20251001": {"input": 1.0, "output": 5.0},
"claude-opus-4-8": {"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():
raise FileNotFoundError(f"缺少 token 用量文件,无法估算费用:{log_file}")
with open(log_file, encoding="utf-8") as f:
data = json.load(f)
total_cost = 0
details = []
for entry in data.get("entries", []):
if "tokens" not in entry:
continue
model = entry.get("model")
if model not in PRICING:
raise ValueError(f"请先为模型 {model!r} 配置核实过的费率")
prices = PRICING[model]
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
details.append({
"time": entry.get("timestamp"),
"model": model,
"input_tokens": input_tokens,
"output_tokens": output_tokens,
"cost": cost
})
if not details:
raise ValueError("没有可估算的 token 用量记录,不能将缺数据报告为零消费")
return {
"date": date,
"total_cost": total_cost,
"details": details
}
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}")
4.3.4 成本控制实践
Claude Code 的非交互 -p / --print 模式支持 --max-budget-usd,可以给单次运行设置 API 花费上限。例如:
claude -p --max-budget-usd 5.00 "概括当前项目的目录结构"
v2.1.217+ 会把子代理花费计入上限,并在达到上限后阻止继续派生、停止仍在运行的后台子代理。这个参数只适用于 print 模式,不是所有交互会话的月度账单硬上限;组织级消费仍应在 Console 或网关配置。来源:CLI 参考(核查日:2026-09-14)。
日常还可以从下面几处控制成本:
方法1:API层面设置用量限制
在 Anthropic Console 中设置:
-
每月消费上限(Spend Limits)
-
用量通知阈值
方法2:使用环境变量控制模型选择
# 简单任务使用 Haiku,具体价格按当前供应商核对
export ANTHROPIC_MODEL=haiku
# 代码审查使用 Sonnet
export ANTHROPIC_MODEL=sonnet
# 架构设计使用 Opus
export ANTHROPIC_MODEL=opus
方法3:通过脚本监控使用量
结合上一节的成本监控脚本,定期检查使用量并设置告警。
4.4 性能基准测试
以下数值是练习用的监控目标示例,不是厂商承诺或实测结果。实际阈值应在同一模型、网络和任务规模下测量后调整。
4.4.1 响应时间基准
操作类型
预期响应时间
实际监控阈值
简单问答
<2秒
5秒告警
代码生成(<100行)
<5秒
10秒告警
代码审查(<500行)
<10秒
20秒告警
大文件分析
<30秒
60秒告警
4.4.2 吞吐量基准
指标
基准值
说明
日均请求数
<500
单用户
日均token消耗
<100K
单用户
并发会话
<5
单用户
5. 综合练习
5.1 练习1:配置企业级项目结构
目标:为一个新的企业项目配置完整的Claude Code环境
要求:
-
创建标准目录结构
-
编写项目CLAUDE.md
-
配置权限白名单
-
设置MCP服务器
步骤提示:
# 1. 创建目录结构
mkdir -p .claude/{commands,hooks,skills}
mkdir -p docs/ai-context
touch CLAUDE.md .mcp.json
# 2. 编写配置文件
# 参考本章模板
# 3. 验证配置
claude auth status
# 在交互会话里用 /config 看设置,用 /permissions 看权限
验收标准:
5.2 练习2:配置CI/CD流水线
目标:为GitHub仓库配置Claude Code自动审查
要求:
-
创建GitHub Actions工作流
-
配置PR自动审查
-
配置安全扫描
-
设置评论交互
步骤提示:
# .github/workflows/claude.yml
name: Claude CI
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
steps:
# 参考本章配置示例
验收标准:
5.3 练习3:安全加固
目标:为现有项目进行安全加固
要求:
-
审计当前权限配置
-
识别并修复安全风险
-
配置审计日志
-
创建安全检查清单
步骤提示:
# 1. 检查当前权限配置
cat .claude/settings.json
# 2. 识别风险配置
# 检查 permissions.allow 与现有其他范围的预批准是否过于宽松
# 检查是否有敏感路径暴露
# 3. 配置审计日志
# 参考本章审计配置
# 4. 在 Claude Code 会话中运行内置安全审查
# /security-review
/security-review 是会话命令,不能直接粘贴进 Bash 执行。运行后仍需按问题依据人工复核。
验收标准:
5.4 练习4:性能优化
目标:优化现有项目的Claude Code使用性能
要求:
-
分析当前性能瓶颈
-
优化上下文使用
-
配置成本监控
-
建立性能基准
步骤提示:
# 1. 启用verbose模式分析
claude --verbose
# 2. 检查CLAUDE.md大小
wc -c CLAUDE.md
# 目标:<5000字符
# 3. 检查对话上下文
# 关注context size日志
# 4. 配置成本监控
# 参考本章监控脚本
验收标准:
5.5 综合实战:从零搭建企业级环境
场景:你是一家创业公司的技术负责人,需要为团队(10人)搭建Claude Code企业级开发环境。
任务清单:
## 第一阶段:基础设施(第1周)
### 任务1.1:标准化项目模板
- [ ] 创建项目模板仓库
- [ ] 包含标准目录结构
- [ ] 包含基础CLAUDE.md
- [ ] 包含.claude/配置目录
### 任务1.2:配置管理
- [ ] 建立全局配置规范
- [ ] 建立项目配置模板
- [ ] 配置Git钩子同步配置
## 第二阶段:CI/CD集成(第2周)
### 任务2.1:GitHub Actions
- [ ] 配置自动代码审查
- [ ] 配置安全扫描
- [ ] 配置文档生成
### 任务2.2:工作流优化
- [ ] 创建团队共享命令
- [ ] 配置自动化钩子
- [ ] 建立审查规范
## 第三阶段:安全合规(第3周)
### 任务3.1:权限管理
- [ ] 定义权限策略
- [ ] 配置分环境权限
- [ ] 配置审计日志
### 任务3.2:合规检查
- [ ] 创建合规检查清单
- [ ] 配置自动合规扫描
- [ ] 建立异常告警
## 第四阶段:监控优化(第4周)
### 任务4.1:成本管控
- [ ] 配置成本监控
- [ ] 设置成本预警
- [ ] 建立成本分析报告
### 任务4.2:性能优化
- [ ] 建立性能基准
- [ ] 优化上下文使用
- [ ] 配置性能监控
交付物:
-
项目模板仓库
-
CI/CD配置文件
-
安全策略文档
-
监控仪表盘
-
团队培训材料
总结
本章介绍了Claude Code在企业环境中的最佳实践,涵盖:
-
团队协作规范:标准化项目结构、CLAUDE.md规范、代码审查流程
-
CI/CD集成:GitHub Actions配置、安全审查、自动化流水线
-
安全与合规:权限系统、白名单配置、审计日志、合规检查
-
性能优化:上下文管理、调试技巧、成本控制
掌握这些内容后,你将能够:
-
为团队建立统一的Claude Code使用规范
-
实现自动化的代码审查和安全扫描
-
建立可核对的权限、审查和记录流程,支持团队判断风险与合规要求
-
有效控制使用成本并优化性能
版本历史:
-
V1.3.2 (2026-04-05):分层配置示例将 src/CLAUDE.md 注释由「源码规则」改为「模块规则」,避免与「仓库目录规则」混淆
-
V1.3.1 (2026-04-05):Sandbox 小节增补 v2.1.92 官方 release 中 Linux apply-seccomp helper 的原文引用(不编造用法)
-
V1.3.0 (2026-03-18):新增Sandbox沙箱配置详解(filesystem权限控制)、128K输出token说明、更新适用版本至v2.1+
-
V1.2.0 (2026-03-18):全面审核修正——修复MCP虚构配置字段(trust/network/limits)、移除虚构settings.json字段(audit/cache/costControl/verbose)、修正分环境配置为标准三级层次、修正CLI命令(permission-mode strict→plan)、更新定价信息
-
V1.1.0 (2026-01-19):更新至Claude Code 2.1.12,新增Skills和Hooks frontmatter说明、通配符权限、Shift+Enter换行等新特性
-
V1.0.0 (2025-12-24):初始版本,基于企业级最佳实践指南创建
最后更新:2026年9月14日 | 版本:V1.3.4