Claude Code成本优化与Token精算全实战

# 查看当前会话的Token使用情况
> /cost

# 输出示例：
# Session tokens: 45,230 input / 3,120 output
# Estimated cost: $0.38
# Cache hit rate: 62%

flowchart TD
    A[用户发送消息] --> B{缓存是否命中?}
    B -->|命中: 成本降低90%| C[仅计算新增Token]
    B -->|未命中: 全量计算| D[系统提示 + 全部历史 + 新消息]
    C --> E[正常价格 × 0.1]
    D --> F[正常价格 × 1.0]

    G[保持会话连续<br/>5分钟内回复] --> B
    H[频繁切换/重启<br/>打破缓存] --> B

    style G fill:#4ade80,stroke:#16a34a
    style H fill:#f87171,stroke:#dc2626

# 查看当前使用的模型
> /model

# 切换到更经济的模型（简单任务用Haiku）
> /model haiku

# 切换回Sonnet（日常开发推荐）
> /model sonnet

# 基本压缩——自动总结当前会话
> /compact

# 带自定义指令的压缩——保留特定关注点
> /compact 保留数据库schema变更记录和未完成的TODO列表

# 压缩前后对比：
# 压缩前: 45,000 tokens (12轮完整对话)
# 压缩后: 8,000 tokens (精炼摘要)
# 节省: ~82%

# ❌ 低效模式：一个会话做所有事
Session 1: 修复bug → 添加功能 → 重构 → 写测试 → 部署
Token消耗: 120K+，后期极度低效

# ✅ 高效模式：每个任务独立会话
Session 1: 修复登录bug (15K tokens)
Session 2: 添加用户导出功能 (20K tokens)
Session 3: 重构认证模块 (18K tokens)
Session 4: 编写集成测试 (12K tokens)
Token总计: 65K，节省约45%

# 使用-p模式快速启动独立任务（非交互式，自动结束）
claude -p "修复 src/auth/login.ts 中的空指针异常"

# 使用--resume恢复之前的会话（不重新发送历史）
claude --resume

# ❌ 臃肿的CLAUDE.md（200+行，约3000 tokens）
# 包含大量示例、详细架构说明、历史变更记录...

# ✅ 精简的CLAUDE.md（50行，约800 tokens）
# 项目：TaskManager（Next.js 15 + TypeScript）
# 数据库：PostgreSQL + Prisma
# 命令：npm run dev / npm test / npm run build
# 规则：
# - TypeScript严格模式，禁止any
# - 组件用函数式+命名导出
# - API遵循RESTful，返回{data, error}格式
# - 测试用Vitest，覆盖率目标80%

flowchart LR
    subgraph "会话成本随时间变化"
        A[第1轮<br/>~10K tokens] --> B[第5轮<br/>~30K tokens]
        B --> C[第10轮<br/>~60K tokens]
        C --> D[第15轮<br/>~100K tokens]
    end

    subgraph "优化后（压缩+分会话）"
        E[第1轮<br/>~10K] --> F[第5轮<br/>~25K<br/>compact]
        F --> G[新会话<br/>~10K] --> H[第5轮<br/>~20K<br/>compact]
    end

    style D fill:#f87171,stroke:#dc2626
    style H fill:#4ade80,stroke:#16a34a

flowchart TD
    A[任务输入] --> B{任务复杂度判断}
    B -->|简单/重复性| C[Haiku 4.5]
    B -->|中等/标准编码| D[Sonnet 4.6]
    B -->|复杂/架构级| E[Opus 4.8]

    C --> C1["✅ 添加注释/文档"]
    C --> C2["✅ 格式化/重命名"]
    C --> C3["✅ 简单bug修复"]
    C --> C4["✅ 生成boilerplate"]

    D --> D1["✅ 功能开发"]
    D --> D2["✅ 代码重构"]
    D --> D3["✅ 调试排障"]
    D --> D4["✅ 编写测试"]

    E --> E1["✅ 架构设计"]
    E --> E2["✅ 跨模块重构"]
    E --> E3["✅ 安全审查"]
    E --> E4["✅ 性能优化"]

    style C fill:#86efac,stroke:#16a34a
    style D fill:#93c5fd,stroke:#2563eb
    style E fill:#fbbf24,stroke:#d97706

# 低effort——简洁输出，省Token
> /effort low
# 适合：快速查询、简单修改、确认性问题

# 中等effort（默认）
> /effort medium

# 高effort——详细分析和多方案对比
> /effort high
# 适合：复杂bug分析、架构决策、代码审查

# 步骤1：用Haiku快速扫描项目结构（低成本）
claude -p --model haiku "列出 src/ 目录下所有未使用TypeScript类型的文件"

# 步骤2：用Sonnet处理具体修改（中等成本）
claude --model sonnet
> 修复刚才列出的文件中的TypeScript类型问题

# 步骤3：用Opus审查修改的影响范围（高成本但精准）
claude -p --model opus "审查最近的TypeScript类型修复是否引入了新的类型安全问题"

# 步骤4：用Haiku运行测试并报告结果
claude -p --model haiku "运行 npm test 并总结失败的测试用例"

# ❌ 避免：读取整个大文件
> 读取 src/database/models.ts
# 如果文件有2000行，约消耗 6000-8000 tokens

# ✅ 推荐：指定行范围读取
> 读取 src/database/models.ts 的第45-80行
# 只消耗约 200-300 tokens

# ✅ 推荐：先用Grep定位
> 搜索 handleUserLogin 函数的定义位置
# 确认位置后再精准读取

# .claudeignore 示例
node_modules/
dist/
build/
*.min.js
*.min.css
*.map
coverage/
.next/
vendor/
*.lock
package-lock.json
yarn.lock

# ❌ 让Claude读取整个README.md（可能很长）
> 先阅读 README.md 了解项目

# ✅ 提供精炼的项目描述
> 这是一个Next.js 15电商项目，使用App Router + Prisma + Stripe。
> 产品表结构：Product(id, name, price, stock, category)。
> 请帮我添加商品搜索功能。

# 批量处理：用shell脚本驱动多个-p任务
for file in src/components/*.tsx; do
  claude -p --model haiku "为 $file 添加PropTypes类型检查，只输出修改后的代码"
done

# 自动化代码格式化
claude -p --model haiku "将 src/utils/ 下所有文件改为使用ES模块语法"

# 批量生成测试
find src -name "*.ts" -not -name "*.test.ts" | while read f; do
  claude -p --model sonnet "为 $f 生成Vitest单元测试"
done

# 设置每轮最大输出Token
claude --max-tokens 4096

# 使用budget参数控制单轮开销
claude -p --budget 50000 "重构认证模块"
# 当Token消耗接近50K时，Claude会自动收尾

{
  "budget": {
    "maxTokensPerTurn": 8192,
    "maxTokensPerSession": 200000
  }
}

# 技巧1：保持会话活跃（5分钟内发送下一条消息）
# Claude Code会话中的缓存TTL为5分钟

# 技巧2：CLAUDE.md放在项目根目录而非频繁修改
# 每次修改CLAUDE.md都会打破缓存

# 技巧3：使用--resume恢复会话而非新建
claude --resume
# 恢复会话时，缓存仍然有效

# 技巧4：避免频繁切换模型
# 每次切换模型都可能导致缓存失效

# 使用Explore代理进行只读搜索（消耗更少的Token）
> /agent Explore "搜索项目中所有与支付相关的API端点"

# 使用Plan代理进行架构规划（结构化输出，减少冗余）
> /plan "设计新的缓存层架构"

flowchart TB
    subgraph "传统方式：主会话处理所有任务"
        A[主会话<br/>上下文窗口: 200K] --> B[搜索文件<br/>+15K tokens]
        B --> C[分析代码<br/>+25K tokens]
        C --> D[生成报告<br/>+10K tokens]
        D --> E[主会话总消耗<br/>~50K tokens<br/>且上下文被污染]
    end

    subgraph "优化方式：子代理分担"
        F[主会话<br/>上下文窗口: 200K] --> G[子代理搜索<br/>独立上下文]
        G --> H[返回精炼结果<br/>~2K tokens]
        H --> I[主会话总消耗<br/>~5K tokens<br/>上下文干净]
    end

    style E fill:#f87171,stroke:#dc2626
    style I fill:#4ade80,stroke:#16a34a

# 第一步：查看历史会话的成本分布
> /cost history

# 输出示例：
# 本周会话统计：
# - 总会话数: 47
# - 平均每会话成本: $3.40
# - 最贵会话: $28.50 (会话 #23, 持续2.5小时)
# - Token分布: 输入82% / 输出18%
# - 缓存命中率: 35%

# CLAUDE.md (优化后, 42行)
## 项目
- Next.js 15 App Router + TypeScript + Prisma + PostgreSQL
- 测试: Vitest | Lint: ESLint | 格式: Prettier

## 命令
- npm run dev / npm test / npm run build / npm run lint

## 规则
- 组件: 函数式 + 命名导出 + Props接口
- API: RESTful + {data, error} 响应格式
- 数据库: Prisma migrate dev 部署变更
- 禁止: any类型 / default导出 / inline样式

## 架构
- /app — 路由和布局
- /components — UI组件
- /lib — 工具函数和共享逻辑
- /services — 业务逻辑层
- /prisma — 数据库Schema

# .claudeignore
node_modules/
.next/
dist/
coverage/
*.min.js
*.min.css
*.map
public/assets/
prisma/migrations/

# team-rules.sh — 团队共享的成本控制规范

# 简单任务（预期<5分钟）
alias claude-quick='claude -p --model haiku --max-tokens 2048'

# 标准开发任务
alias claude-dev='claude --model sonnet'

# 复杂架构决策
alias claude-arch='claude --model opus --max-tokens 8192'

# 代码审查
alias claude-review='claude -p --model opus /review'

# 在CLAUDE.md中添加提醒
# 工作流：
# - 每8轮对话执行 /compact
# - 切换任务时开新会话
# - 简单查询用 -p 模式

graph LR
    subgraph "月成本对比"
        A["优化前<br/>$800/月"]
        B["优化后<br/>$310/月"]
        C["节省<br/>$490/月<br/>61%"]
    end

    subgraph "Token分布优化"
        D["Haiku: 5%→40%"]
        E["Sonnet: 70%→50%"]
        F["Opus: 25%→10%"]
    end

    style A fill:#f87171,stroke:#dc2626
    style B fill:#4ade80,stroke:#16a34a
    style C fill:#fbbf24,stroke:#d97706

// ~/.claude/settings.json — 全局成本控制配置
{
  "model": "sonnet",
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Read",
      "Grep",
      "Glob"
    ]
  },
  "hooks": {
    "preToolUse": [{
      "command": "echo '[$(date)] Tool: $TOOL_NAME, File: $FILE_PATH' >> ~/.claude/usage.log"
    }]
  }
}

# 创建简单的使用日志分析脚本
# analyze-usage.sh
#!/bin/bash

LOG_FILE="$HOME/.claude/usage.log"

echo "=== Claude Code 使用报告 ==="
echo "总调用次数: $(wc -l < $LOG_FILE)"
echo "最常用工具: $(awk '{print $5}' $LOG_FILE | sort | uniq -c | sort -rn | head -5)"
echo "今日使用: $(grep "$(date +%Y-%m-%d)" $LOG_FILE | wc -l) 次"
echo "高频文件: $(awk '{print $NF}' $LOG_FILE | sort | uniq -c | sort -rn | head -5)"

# 检查缓存状态
> /cost

# 如果命中率<40%，尝试：
# 1. 减少CLAUDE.md修改频率
# 2. 使用 --resume 而非新开会话
# 3. 将动态信息放到消息中，而非系统提示

# 策略1：使用Grep定向搜索
> 搜索所有包含 "use server" 的文件

# 策略2：使用Glob缩小范围
> 列出 src/api/ 目录下所有 .ts 文件

# 策略3：指定读取行范围
> 只读取 app/layout.tsx 的第1-30行

# 策略4：使用Explore子代理
> 用Explore代理搜索项目中所有数据库模型定义

# GitHub Actions 中的成本控制示例
- name: AI Code Review
  run: |
    # 使用-p模式，限制最大Token
    claude -p \
      --model sonnet \
      --max-tokens 4096 \
      "审查本次PR的代码变更，输出5条以内的关键发现"

flowchart TD
    Start([任务开始]) --> TaskType{任务类型判断}

    TaskType -->|简单查询<br/>格式化/注释| H[Haiku模型]
    TaskType -->|标准开发<br/>功能/调试/测试| S[Sonnet模型]
    TaskType -->|复杂决策<br/>架构/审查/优化| O[Opus模型]

    H --> P1[-p 模式执行]
    S --> Interactive{需要交互?}
    O --> Interactive

    Interactive -->|是| Session[开启交互会话]
    Interactive -->|否| P2[-p 模式执行]

    Session --> Work[执行开发任务]
    Work --> Rounds{对话超过8轮?}
    Rounds -->|是| Compact[/compact 压缩]
    Compact --> Work
    Rounds -->|否| Done{任务完成?}
    Done -->|是| End([结束会话])
    Done -->|否| NewTask{需要切换任务?}
    NewTask -->|是| NewSession[开启新会话]
    NewSession --> Start
    NewTask -->|否| Work

    P1 --> End
    P2 --> End

    style Start fill:#60a5fa,stroke:#2563eb
    style End fill:#4ade80,stroke:#16a34a
    style Compact fill:#fbbf24,stroke:#d97706