Back to Details

performance-optimization

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Performance Optimization Skill

性能优化技能

Comprehensive guidance for optimizing Claude Code performance. This skill covers storage management, context window optimization, and troubleshooting common performance issues.
本技能为Claude Code性能优化提供全面指导，涵盖存储管理、上下文窗口优化以及常见性能问题的故障排查。

When to Use This Skill

适用场景

Keywords: slow, performance, lag, storage, cleanup, cache, context, compact, clear, sessions, agents, bloat, optimization, speed
Use this skill when:
  • Claude Code is running slowly
  • Storage is accumulating
  • Context window is getting full
  • Planning performance maintenance
  • Learning best practices for efficient usage
关键词： 缓慢、性能、延迟、存储、清理、缓存、上下文、压缩、清空、会话、Agent、冗余、优化、速度
在以下场景使用本技能：
  • Claude Code运行缓慢
  • 存储不断累积
  • 上下文窗口即将占满
  • 规划性能维护工作
  • 学习高效使用的最佳实践

Quick Reference

快速参考

Immediate Actions for Slowdowns

运行缓慢的即时处理方案

SymptomQuick FixCommand
General slownessClean storage
/cleanup-sessions 7
Input lagReset context
/clear
API errorsCheck status
/check-api-status
Unknown causeFull diagnostic
/diagnose-performance
症状快速修复方法命令
整体运行缓慢清理存储
/cleanup-sessions 7
输入延迟重置上下文
/clear
API错误检查状态
/check-api-status
原因不明全面诊断
/diagnose-performance

Performance Commands

性能相关命令

CommandPurpose
/check-claude-storage
Analyze storage usage
/cleanup-sessions [days]
Remove old session files
/cleanup-agents [days]
Remove old agent files
/prune-cache [days]
Comprehensive cleanup
/diagnose-performance
Full diagnostic
/list-sessions
View recent sessions
/session-stats
Session statistics
/check-api-status
API status check
/check-context
Context window analysis
命令用途
/check-claude-storage
分析存储使用情况
/cleanup-sessions [days]
删除旧会话文件
/cleanup-agents [days]
删除旧Agent文件
/prune-cache [days]
全面清理缓存
/diagnose-performance
全面性能诊断
/list-sessions
查看近期会话
/session-stats
会话统计信息
/check-api-status
API状态检查
/check-context
上下文窗口分析

Core Concepts

核心概念

1. Storage Management

1. 存储管理

Claude Code stores conversation history in 
~/.claude/
:
text
~/.claude/
├── projects/           # Session history (can grow large!)
│   └── {project-hash}/
│       ├── {session-id}.jsonl     # Conversation transcripts
│       └── agent-{id}.jsonl       # Subagent transcripts
├── todos/              # Todo state
├── statsig/            # Analytics cache
└── history.jsonl       # Command history
Key insight: The 
projects/
folder grows indefinitely with usage. Heavy users can accumulate 1GB+ of session data.
See: 
references/storage-management.md
for detailed guidance.
Claude Code将会话历史存储在
~/.claude/
目录下：
text
~/.claude/
├── projects/           # 会话历史（可能会变得很大！）
│   └── {project-hash}/
│       ├── {session-id}.jsonl     # 会话记录
│       └── agent-{id}.jsonl       # 子Agent会话记录
├── todos/              # 待办事项状态
├── statsig/            # 分析缓存
└── history.jsonl       # 命令历史
关键提示： 
projects/
文件夹会随着使用不断增大，重度用户可能会累积1GB以上的会话数据。
参考： 详细指导请查看
references/storage-management.md
。

2. Context Window Management

2. 上下文窗口管理

Claude Code uses a 200K token context window. Performance degrades as it fills:
UsageStatusAction
< 50%HealthyNo action
50-75%MonitorConsider compacting
75-85%WarningRun /compact or /clear
> 85%CriticalImmediate action
Key commands:
  • /clear
    - Complete context reset
  • /compact
    - Intelligent summarization
  • /cost
    - View token usage
See: 
references/context-management.md
for detailed guidance.
Claude Code使用200K token的上下文窗口，当窗口被占满时性能会下降：
使用占比状态操作建议
< 50%健康无需操作
50-75%监控考虑压缩上下文
75-85%警告运行/clear或/compact命令
> 85%严重立即采取行动
关键命令：
  • /clear
    - 完全重置上下文
  • /compact
    - 智能摘要压缩
  • /cost
    - 查看Token使用情况
参考： 详细指导请查看
references/context-management.md
。

3. Known Issues

3. 已知问题

Several GitHub issues document known performance problems:
Note: Issue numbers below are point-in-time references and may have been closed, merged, or superseded. For current issues, spawn the 
claude-code-issue-researcher
agent or query 
docs-management: "performance issues"
for updated tracking.
IssueDescriptionWorkaround
#10881Performance degrades in long sessionsRestart periodically
#14552Input lag at high contextUse /clear at 75%
#14476Regression even at 30k tokensUpdate to latest version
#1497Keyboard responsiveness issuesRestart Claude Code
See: 
references/known-issues.md
for detailed tracking.
多个GitHub问题记录了已知的性能问题：
注意： 以下问题编号为当前时间点的参考，可能已被关闭、合并或替代。如需了解最新问题，请启动
claude-code-issue-researcher
Agent，或查询
docs-management: "performance issues"
获取更新的跟踪信息。
问题编号描述临时解决方案
#10881长会话中性能下降定期重启
#14552高上下文占比时输入延迟占比达75%时使用/clear命令
#14476即使在30k Token时也出现性能倒退更新至最新版本
#1497键盘响应问题重启Claude Code
参考： 详细跟踪请查看
references/known-issues.md
。

Best Practices

最佳实践

Daily Maintenance

日常维护

  1. Start fresh when possible - New session = fresh context
  2. Use /clear between major tasks - Don't let context rot
  3. Monitor storage periodically - Run 
    /check-claude-storage
    weekly
  1. 尽可能开启新会话 - 新会话意味着全新的上下文
  2. 在主要任务之间使用/clear命令 - 避免上下文冗余堆积
  3. 定期监控存储 - 每周运行
    /check-claude-storage

Heavy Usage Patterns

重度使用场景

  1. Use subagents for large operations - Isolates context bloat
  2. Break large tasks into sessions - Smaller = faster
  3. Clean storage weekly - 
    /cleanup-sessions 7
  1. 使用子Agent处理大型操作 - 隔离上下文冗余
  2. 将大型任务拆分为多个会话 - 会话越小速度越快
  3. 每周清理存储 - 运行
    /cleanup-sessions 7

Performance Optimization

性能优化技巧

  1. Keep CLAUDE.md lean - Large memory files slow startup
  2. Use progressive disclosure - Load context on-demand
  3. Prefer focused queries - Specific > broad
  1. 保持CLAUDE.md文件精简 - 大内存文件会拖慢启动速度
  2. 使用渐进式披露 - 按需加载上下文
  3. 优先使用精准查询 - 具体查询优于宽泛查询

Troubleshooting Flowchart

故障排查流程图

text
Claude Code is slow
        │
        ├─> Check storage: /check-claude-storage
        │   └─> If >500MB: /cleanup-sessions 7
        │
        ├─> Check context: /check-context
        │   └─> If WARNING+: /clear or /compact
        │
        ├─> Check API: /check-api-status
        │   └─> If degraded: Wait or reduce load
        │
        └─> Full diagnostic: /diagnose-performance
            └─> Follow recommendations
text
Claude Code运行缓慢
        │
        ├─> 检查存储：/check-claude-storage
        │   └─> 如果超过500MB：/cleanup-sessions 7
        │
        ├─> 检查上下文：/check-context
        │   └─> 如果处于警告及以上状态：/clear或/compact
        │
        ├─> 检查API状态：/check-api-status
        │   └─> 如果状态降级：等待或降低负载
        │
        └─> 全面诊断：/diagnose-performance
            └─> 按照建议操作

Related Skills

相关技能

SkillRelationship
docs-management
For official Claude Code documentation
memory-management
For CLAUDE.md optimization
技能关联关系
docs-management
用于获取官方Claude Code文档
memory-management
用于CLAUDE.md文件优化

References

参考资料

Load these for detailed guidance:
  • references/context-management.md
    - Context window optimization
  • references/storage-management.md
    - Storage cleanup strategies
  • references/known-issues.md
    - GitHub issues and workarounds
加载以下文档获取详细指导：
  • references/context-management.md
    - 上下文窗口优化
  • references/storage-management.md
    - 存储清理策略
  • references/known-issues.md
    - GitHub问题及临时解决方案

Version History

版本历史

  • v1.0.0 (2025-12-26): Initial release
    • Core performance guidance
    • Command reference
    • Best practices
    • Reference documents
  • v1.0.0 (2025-12-26): 初始版本
    • 核心性能指导
    • 命令参考
    • 最佳实践
    • 参考文档

Last Updated

最后更新

Date: 2025-12-26 Model: claude-opus-4-5-20251101
日期： 2025-12-26 模型： claude-opus-4-5-20251101