Claude Code高级技巧：上下文管理与性能优化完全指南

# 步骤1：开始一个复杂任务前，先检查当前状态
/cost

# 步骤2：如果已用超过60%，先压缩
/compact

# 步骤3：如果方向完全改变，彻底清空
/clear

# 步骤4：重新开始时，给Claude一个简洁的任务摘要
# 不要重复之前的完整历史，只说当前目标

# Global Preferences

## Language & Style
- 默认使用中文回复
- 回复简洁明了

## General Rules
- 不要自动commit
- 始终先读取文件再编辑
- 优先编辑现有文件而非创建新文件

# Project: My SaaS Backend

## Tech Stack
- Node.js 20 + TypeScript 5.x
- Express + Prisma ORM
- PostgreSQL 16

## Architecture
- src/routes/ - API路由定义
- src/services/ - 业务逻辑层
- src/models/ - Prisma数据模型
- src/middleware/ - 中间件

## Coding Conventions
- 使用Zod做输入验证
- Service层返回Result<T, E>类型
- 错误统一用AppError类

# Routes Module

## Patterns
- 每个路由文件对应一个resource
- 使用express.Router()
- 中间件顺序：auth -> validate -> handler

graph TB
    subgraph 优化前：单一CLAUDE.md
        A1[CLAUDE.md 200行] --> B1[所有内容每次都加载]
        B1 --> C1["~8K Tokens/次"]
    end

    subgraph 优化后：模块化AGENTS.md
        A2[CLAUDE.md 30行] --> B2["~1.2K Tokens/次"]
        A2 --> C2[AGENTS.md x5]
        C2 --> D2[按需加载 ~2K/模块]
        D2 --> E2["每次仅加载1-2个模块"]
        E2 --> F2["~3-4K Tokens/次"]
    end

    style C1 fill:#f66,stroke:#333
    style F2 fill:#6f6,stroke:#333

# 1. 将CLAUDE.md精简到核心规则（<50行）
# 2. 在各模块目录创建AGENTS.md
mkdir -p src/auth src/billing src/notifications
cat > src/auth/AGENTS.md << 'EOF'
# Auth Module
- JWT + Refresh Token双令牌模式
- 密码用bcrypt cost=12
- 所有路由需要AuthMiddleware
- 测试用testcontainers运行真实PostgreSQL
EOF

cat > src/billing/AGENTS.md << 'EOF'
# Billing Module
- Stripe API集成
- 所有金额以分为整数存储
- 幂等键防止重复扣费
- Webhook需要签名验证
EOF

cat > src/notifications/AGENTS.md << 'EOF'
# Notifications Module
- 基于事件驱动架构
- 使用Bull队列异步处理
- 模板用Handlebars渲染
- 优先级：critical > high > normal > low
EOF

使用Task工具，同时启动3个子Agent：
1. subagent_type=general-purpose：重构 src/auth/ 下的所有文件，将callback改为async/await
2. subagent_type=general-purpose：重构 src/billing/ 下的所有文件，将callback改为async/await  
3. subagent_type=general-purpose：重构 src/notifications/ 下的所有文件，将callback改为async/await

请分析 src/ 目录下所有文件的import依赖关系，找出哪些文件
相互引用，哪些是完全独立的。输出一个依赖图。

我需要将整个项目从Express迁移到Hono。请使用Task工具并行启动3个子Agent：

Agent 1（description: "migrate routes"）：
- 搜索 src/routes/ 下所有 .ts 文件
- 将 express.Router() 改为 new Hono()
- 将 req/res/next 改为 c (Hono的Context对象)
- 将 router.get('/path', handler) 改为 app.get('/path', handler)
- 保持业务逻辑不变

Agent 2（description: "migrate middleware"）：
- 搜索 src/middleware/ 下所有 .ts 文件
- 将 (req, res, next) => {} 改为 async (c, next) => {}
- 将 res.status(401).json() 改为 c.json({error}, 401)
- 将 next() 改为 await next()

Agent 3（description: "migrate utils"）：
- 搜索 src/utils/ 下所有 .ts 文件
- 移除所有 express 类型导入
- 将 Request/Response 类型替换为 Context

每个Agent使用 isolation: "worktree" 运行，避免冲突。
完成后报告各自的修改文件列表。

所有Agent都完成了迁移。现在请：
1. 安装 hono 依赖：npm install hono
2. 更新 src/index.ts 作为Hono应用入口
3. 运行 TypeScript 编译检查：npx tsc --noEmit
4. 报告所有类型错误，逐个修复

# Claude Code内置worktree支持
# 在对话中直接使用 EnterWorktree 工具
# 或通过命令行：

# 创建隔离工作区
git worktree add ../feature-auth refactor/auth-module
git worktree add ../feature-billing refactor/billing-module

# 在两个终端分别启动Claude Code
cd ../feature-auth && claude
cd ../feature-billing && claude

# 完成后合并
git checkout main
git merge refactor/auth-module
git merge refactor/billing-module

# 清理worktree
git worktree remove ../feature-auth
git worktree remove ../feature-billing

# 差：读取整个文件
请读取 src/services/userService.ts 并修改 createUser 方法

# 好：只读取相关部分
请读取 src/services/userService.ts 的第45-80行（createUser方法）并修改

# 更好：直接描述修改
在 src/services/userService.ts 的 createUser 方法中，
将第52行的 const user = await prisma.user.create({data})
改为 const user = await prisma.user.create({data, select: {id: true, email: true}})

# 不要等到上下文告急
# 在每个阶段性任务完成后主动压缩
/compact 已完成用户模块的重构，接下来处理订单模块

# 在压缩时给Claude一个摘要提示
# 这样压缩后的摘要会保留关键决策

# 查看（当前安装了哪些Skills）
ls ~/.claude/skills/

# 禁用不需要的Skills（在.claude/settings.json中）
{
  "skills": {
    "disabled": ["heavy-skill-you-dont-need"]
  }
}

# 方式一：通过/effort命令
/effort high    # 使用更强的推理（更多思考Token）
/effort medium  # 默认平衡
/effort low     # 快速响应（更少思考Token）

# 方式二：在Task工具中指定模型
# 对于子Agent，直接指定model参数
# model: "haiku" 用于简单搜索
# model: "sonnet" 用于编码任务
# model: "opus" 用于复杂推理

# 方式三：环境变量
export CLAUDE_MODEL=claude-haiku-4-5-20251001  # 全局切换

src/
├── routes/
│   ├── userRoutes.ts
│   ├── orderRoutes.ts
│   └── productRoutes.ts
├── services/
│   ├── userService.ts
│   ├── orderService.ts
│   └── productService.ts
├── middleware/
│   ├── auth.ts
│   └── errorHandler.ts
├── models/
│   └── index.ts
└── index.ts

# 精简根目录CLAUDE.md（<30行）
cat > CLAUDE.md << 'EOF'
# E-Commerce Backend

## Stack
- TypeScript 5.x + Node.js 20
- Express 4.x + Prisma 6.x
- PostgreSQL 16

## Rules
- 使用中文回复
- 不要自动commit
- 先读文件再修改
- 保持现有业务逻辑不变
- 修改后运行 npx tsc --noEmit 验证类型
EOF

# 创建模块级AGENTS.md
cat > src/services/AGENTS.md << 'EOF'
# Services Module
- 所有方法必须返回 Promise
- 错误统一抛 AppError(code, message)
- 输入验证使用 Zod schema
- 数据库操作使用 Prisma client
EOF

cat > src/routes/AGENTS.md << 'EOF'
# Routes Module  
- 每个 resource 一个路由文件
- 使用 express.Router()
- 中间件顺序：auth -> validate -> handler
- 响应格式统一 { success: boolean, data?, error? }
EOF

我需要重构 src/services/ 下的三个文件，将所有callback风格的
异步方法改为async/await。请使用Task工具并行处理：

Agent 1（description: "refactor userService"）：
读取 src/services/userService.ts，将所有使用callback的函数
改为async/await模式。保持函数签名和返回类型不变。

Agent 2（description: "refactor orderService"）：
同上，处理 src/services/orderService.ts

Agent 3（description: "refactor productService"）：
同上，处理 src/services/productService.ts

所有Agent完成后，运行 npx tsc --noEmit 检查类型错误。

现在统一错误处理：
1. 创建 src/utils/AppError.ts，定义统一的错误类
2. 更新 src/middleware/errorHandler.ts 使用新的AppError
3. 更新所有Service文件中的错误抛出方式
4. 运行 npx tsc --noEmit 验证

完成后 /compact 保存进度

为所有Service的公共方法添加Zod输入验证。请并行处理：

Agent 1（description: "add user validation"）：
在 src/services/userService.ts 中：
- 为 createUser 添加用户名/邮箱/密码的Zod schema
- 为 updateUser 添加部分更新的Zod schema
- 在方法开头调用 schema.parse(input)

Agent 2（description: "add order validation"）：
在 src/services/orderService.ts 中添加对应的Zod验证

Agent 3（description: "add product validation"）：
在 src/services/productService.ts 中添加对应的Zod验证

完成后运行 npx tsc --noEmit

请执行最终检查：
1. npx tsc --noEmit — 类型检查
2. npm test — 运行所有测试
3. 报告所有修改文件的列表和变更摘要
4. /compact 所有重构完成，项目从callback迁移到async/await，统一了错误处理和输入验证

graph TD
    START[启动新会话] --> CHECK[/cost 检查上下文]
    CHECK --> PLAN[制定任务计划]
    PLAN --> SPLIT{任务可并行？}

    SPLIT -->|可以| PARALLEL[Task工具启动子Agent]
    SPLIT -->|不可以| SEQUENTIAL[顺序执行]

    PARALLEL --> MERGE[主Agent汇总结果]
    SEQUENTIAL --> VERIFY[验证结果]
    MERGE --> VERIFY

    VERIFY --> TEST[运行测试]
    TEST --> MORE{还有任务？}

    MORE -->|有| COMPACT[/compact 压缩]
    COMPACT --> CHECK
    MORE -->|没有| DONE[完成]

    DONE --> COST[/cost 最终报告]

    style START fill:#69f,stroke:#333
    style DONE fill:#6f6,stroke:#333
    style COMPACT fill:#f96,stroke:#333

/cost          # 查看当前会话Token和费用
/compact       # 压缩对话历史（可附带摘要提示）
/clear         # 清空会话历史
/rewind        # 回退到之前的状态
/effort high   # 提升思考深度
/effort low    # 降低思考深度（节省Token）
/help          # 查看所有可用命令

CLAUDE_MODEL              # 默认模型
CLAUDE_CODE_MAX_TOKENS    # 最大输出Token数
CLAUDE_CODE_BUDGET_TOKENS # 上下文窗口大小
DISABLE_PROMPT_CACHING    # 禁用缓存（调试用）