Claude Code上下文工程实战：精准操控Token与对话流

┌──────────────────────────────────────────┐
│           Claude Code 上下文窗口          │
├──────────────────────────────────────────┤
│  系统提示词 (System Prompt)              │ ← 固定，不可控
│  全局 CLAUDE.md (~/.claude/CLAUDE.md)    │ ← 你控制
│  项目 CLAUDE.md (项目根目录)              │ ← 你控制
│  目录 CLAUDE.md (当前工作子目录)          │ ← 你控制
│  .claude/rules/*.md (规则文件)           │ ← 你控制
│  /memory 内容                            │ ← 你控制
│  对话历史 (Conversation History)          │ ← 动态增长
│  工具调用结果 (Tool Results)             │ ← 动态增长
│  当前用户消息                             │ ← 即时输入
└──────────────────────────────────────────┘

# Global Preferences

## Language
- 默认使用中文回复，代码注释用英文
- 变量命名和函数名保持英文

## Code Style
- 优先使用函数式编程风格
- 使用 const 而非 let，禁止 var
- 单引号优先，行末不加分号（JavaScript）
- 最大行宽 100 字符

## Safety Rules
- NEVER commit .env, credentials, secrets
- NEVER use `any` type in TypeScript
- ALWAYS check for null/undefined before access

## Workflow
- 修改代码后主动运行相关测试
- 不自动 commit，等我确认
- 优先编辑现有文件而非创建新文件

# Project: E-Commerce Platform

## Tech Stack
- Framework: Next.js 15 (App Router)
- Language: TypeScript 5.4 (strict mode)
- Database: PostgreSQL 16 + Prisma ORM
- Auth: NextAuth.js v5
- Testing: Vitest + Playwright
- Styling: Tailwind CSS + shadcn/ui

## Architecture

## Conventions
- API routes: app/api/[resource]/route.ts
- Components: PascalCase files, named exports
- Server actions: co-locate with page, name as actions.ts
- Database queries: always through Prisma, never raw SQL
- Error handling: use Result<T, E> pattern from lib/result.ts

## Critical Rules
- DO NOT modify files in components/ui/ (managed by shadcn)
- ALWAYS use server-side validation with zod schemas
- Payment logic in server/payment/ — ask before modifying
- Run `pnpm test` before suggesting completion

# UI Components (shadcn/ui managed)
- 这些组件由 shadcn CLI 管理
- 只通过 `npx shadcn@latest add <component>` 修改
- 如需自定义样式，在 components/features/ 中创建包装组件

# Payment Module - HIGH SECURITY
- 所有金额计算使用 decimal.js，禁止浮点数
- 退款逻辑必须经过双人审查
- 测试覆盖率要求：100%
- 修改前必须先阅读 README-security.md

.claude/
├── rules/
│   ├── typescript.md      # 所有.ts/.tsx文件操作时加载
│   ├── testing.md         # 涉及测试文件时加载
│   └── database.md        # 涉及prisma/sql文件时加载

- 使用 `interface` 定义对象类型，`type` 用于联合类型和工具类型
- Props 必须用显式 interface 定义，禁止 inline type
- 使用 Zod schema 验证所有外部输入

┌─────────────────────────────────────────────────┐
│             对话复杂度分级模型                      │
│                                                   │
│  Level 1: 单轮指令     (1-3 轮)                   │
│  ├── 修个 typo                                     │
│  ├── 加个 console.log                              │
│  └── 格式化代码                                    │
│                                                   │
│  Level 2: 聚焦任务     (5-15 轮)                   │
│  ├── 实现一个新 API endpoint                       │
│  ├── 修复一个有明确报错的 bug                       │
│  └── 重构一个函数                                  │
│                                                   │
│  Level 3: 探索性任务   (15-40 轮)                  │
│  ├── 实现一个新功能模块                             │
│  ├── 跨文件重构                                    │
│  └── 性能优化                                      │
│                                                   │
│  Level 4: 架构任务     (拆分为多个 Level 2-3)       │
│  ├── 新增一个完整特性                               │
│  ├── 数据库迁移 + API + UI 全链路                   │
│  └── 模块间接口重构                                 │
└─────────────────────────────────────────────────┘

# 好的单轮指令示例
"在 src/api/auth.ts 第42行，将错误日志级别从 warn 改为 error，同时添加错误码 E0042"

# 坏的单轮指令示例
"帮我改一下那个文件"

我需要给商品详情页添加一个"相似商品推荐"模块。
数据源是 /api/recommendations API。
要求：卡片式布局，最多显示6个商品，支持懒加载。

1. 创建 RecommendationCard 组件 (src/components/features/)
2. 创建 useRecommendations hook (src/hooks/)
3. 在 ProductDetail 页面集成 (src/app/(shop)/products/[id]/page.tsx)
4. 添加加载骨架屏
5. 编写单元测试

# 错误做法：一个Session搞定全部
"帮我实现用户注册功能，包括表单验证、API端点、数据库表、邮件通知和单元测试"
（消耗 8万+ Token，上下文严重污染，后期质量骤降）

# 正确做法：拆分为5个独立Session
Session 1: "设计用户注册的数据库Schema（Prisma migration）"
Session 2: "实现 /api/auth/register POST端点，含输入验证"
Session 3: "创建注册表单组件，含客户端验证"
Session 4: "集成邮件通知服务（欢迎邮件）"
Session 5: "为以上所有模块编写测试"

flowchart TD
    A[接收复杂任务] --> B{复杂度评估}
    B -->|Level 1-2| C[直接执行<br/>单Session完成]
    B -->|Level 3| D[Plan Mode<br/>先规划后执行]
    B -->|Level 4| E[任务分解]

    E --> F[拆分为3-5个<br/>独立子任务]
    F --> G[每个子任务<br/>独立Session]

    G --> H[Session 1:<br/>数据层]
    G --> I[Session 2:<br/>API层]
    G --> J[Session 3:<br/>UI层]
    G --> K[Session 4:<br/>集成测试]

    H --> L[用 --resume 继续]
    I --> L
    J --> L
    K --> L

    L --> M[最终集成<br/>验收]

    C --> N{质量检查}
    D --> N
    M --> N

    N -->|通过| O[✅ 完成]
    N -->|失败| P[定位问题<br/>开新Session修复]
    P --> O

    style E fill:#f9f,stroke:#333
    style G fill:#bbf,stroke:#333
    style N fill:#bfb,stroke:#333

# ❌ 浪费：读取整个大文件
"读一下 src/api/auth.ts"

# ✅ 高效：指定行范围
"读 src/api/auth.ts 第30-50行，只看 validateToken 函数"

# ❌ 浪费：全项目搜索
"搜索所有包含 'user' 的文件"

# ✅ 高效：限定目录和文件类型
"在 src/api/ 目录的 .ts 文件中搜索 'validateToken' 函数定义"

/compact

/clear
现在开始实现用户列表页面UI。根据 src/types/user.ts 中的 User interface...

# ❌ 可能返回海量结果
"搜索所有TODO注释"

# ✅ 限制数量
"搜索TODO注释，只看前10条结果"

Token 预算分配（200K 总量）
├── 系统提示词        ≈ 10K   (5%)    [固定]
├── CLAUDE.md 全层级   ≈ 4K    (2%)    [精简配置]
├── /memory            ≈ 2K    (1%)    [关键决策]
├── 对话历史           ≤ 80K   (40%)   [/compact 控制]
├── 工具调用结果       ≤ 60K   (30%)   [精确指令控制]
└── 留给模型推理       ≥ 44K   (22%)   [必须保障的空间]

flowchart LR
    A[claude] --> B[Session 1<br/>数据库设计]
    B --> C{完成?}
    C -->|是| D[/compact<br/>保存关键决策]

    D --> E[claude<br/>Session 2<br/>API开发]
    E --> F{需要回看<br/>Session 1?}
    F -->|是| G[claude --resume<br/>选择Session 1]
    F -->|否| H[继续Session 2]

    G --> I[复制需要的<br/>上下文信息]
    I --> E

    H --> J{完成?}
    J -->|是| K[/compact]

    K --> L[claude<br/>Session 3<br/>UI开发]
    L --> M[...重复流程]

    style A fill:#e1f5fe
    style D fill:#fff3e0
    style G fill:#fce4ec
    style K fill:#fff3e0

# 在Session 1中（数据库设计完成后）
/memory
添加以下内容：
- 用户表使用 UUID 主键，非自增ID
- 所有时间字段使用 TIMESTAMPTZ 类型
- Prisma schema 位于 prisma/schema.prisma

# /memory 内容示例

## Architecture Decisions
- [ADR-001] UUID as primary key for all user-facing tables
- [ADR-002] Event-driven architecture for order processing
- [ADR-003] Redis for session cache, PostgreSQL for persistence

## API Conventions
- RESTful endpoints: /api/v1/{resource}
- Error format: { code: string, message: string, details?: object }
- Pagination: cursor-based for lists > 100 items

## Current Sprint Focus
- Feature: User notification system
- Priority: Real-time via WebSocket > Email > SMS
- Deadline: Sprint ends 2026-05-30

## Payment Module
- Provider: Stripe (use official stripe npm package)
- Currency: CNY (人民币)
- Testing: Use Stripe test mode with test keys
- Security: Payment logic in server/payment/ ONLY
- NEVER log full card numbers or payment tokens

claude

我需要设计支付相关的数据库Schema（使用Prisma）。
包含以下实体：
1. PaymentMethod - 用户保存的支付方式
2. Payment - 支付记录
3. Refund - 退款记录

要求：
- 使用 UUID 主键
- 所有金额用 BigInt 存储（单位：分）
- 状态字段用 Enum
- 创建必要的索引

claude

基于以下 Prisma schema（提供Session 1的产出），
实现 Stripe 支付集成层：
1. src/server/payment/stripe-client.ts - Stripe客户端初始化
2. src/server/payment/create-payment.ts - 创建支付Intent
3. src/server/payment/confirm-payment.ts - 确认支付
4. src/server/payment/webhook-handler.ts - Webhook处理

参考 /memory 中的架构决策。
所有金额从分转换为Stripe要求的最小单位。

claude

实现支付相关的API路由（Next.js App Router）：
1. POST /api/v1/payments/create - 创建支付
2. POST /api/v1/payments/{id}/confirm - 确认支付
3. GET /api/v1/payments/{id}/status - 查询状态
4. POST /api/v1/payments/stripe-webhook - Webhook回调

要求：
- 使用 zod 验证所有输入
- 错误格式遵循项目约定（见CLAUDE.md）
- Webhook需要验证Stripe签名

claude --continue   # 延续Session 3，因为需要API接口上下文

基于刚创建的API端点，实现前端支付流程：
1. PaymentMethodSelector 组件 - 选择支付方式
2. PaymentForm 组件 - 输入支付信息
3. PaymentStatus 组件 - 实时状态展示
4. PaymentErrorBoundary - 支付错误处理

使用 shadcn/ui 组件库。
移动端优先的响应式设计。

claude

为支付模块编写完整的测试套件：
1. 测试文件结构镜像 src/ 目录
2. 单元测试：stripe-client, create-payment, confirm-payment
3. API集成测试：使用 Vitest + MSW mock
4. E2E测试场景：完整支付流程（Playwright）

Stripe mock 使用官方 @stripe/stripe-js 的测试工具。
覆盖率目标：90%+

claude

支付模块各层已开发完成。请执行以下集成检查：
1. 运行 pnpm test 确认所有测试通过
2. 运行 pnpm build 确认编译无错误
3. 运行 pnpm lint 确认代码风格一致
4. 检查是否有TODO或临时hack需要清理
5. 验证 Webhook URL 配置正确

请先阅读以下文件，理解当前代码结构：
- src/types/index.ts
- src/lib/utils.ts
- CLAUDE.md

然后用一句话总结你理解的项目架构。

# Round 1: 探索
"分析 src/api/orders/ 目录，列出所有现有的订单相关端点及其功能"

# Round 2: 设计
"基于现有端点，设计一个订单退款API。只给出接口设计，不写代码"

# Round 3: 确认
"接口设计看起来不错。现在实现 POST /api/v1/orders/{id}/refund 端点"

# Round 4: 验证
"运行相关测试，确认退款逻辑正确处理了边界情况"

# Session A 结束前
/compact
请将以下关键信息保存到上下文摘要中：
1. 支付模块使用了Event Sourcing模式
2. OrderEvents表记录所有状态变更
3. Query端通过materialized view读取
4. 当前已完成写入端，读取端待开发

# Session B 开始时
claude --continue
继续开发支付模块的读取端。根据 /compact 摘要中的架构说明...

# 在主分支处理紧急hotfix
claude "修复用户登录的空指针异常"
# → 在main分支上工作

# 同时在worktree中开发新功能
claude worktree add feature-payment
cd .claude/worktrees/feature-payment
claude "实现支付模块"
# → 在独立分支上工作，上下文完全隔离

# ❌ 低效
"之前你写的那个用户验证函数..."

# ✅ 高效
"参考 src/lib/auth.ts 中的 validateSession 函数的模式，为支付验证写一个类似的函数"