Prompt cache trong Claude Code: thao tác nào làm vỡ cache, thao tác nào an toàn

Bạn đang làm việc trơn tru thì đổi /model sang Opus, và lượt tiếp theo bỗng chậm hẳn, usage nhảy vọt. Hay sửa CLAUDE.md giữa phiên mà Claude vẫn làm theo bản cũ. Cả hai đều do prompt caching: Claude Code tự động cache phần đầu mỗi request, và có những thao tác làm cache "vỡ". Tài liệu mới của Claude Code liệt kê đầy đủ thao tác nào phá cache, thao tác nào an toàn, và cách đo tỷ lệ trúng cache. Biết những điều này là cách tiết kiệm token rẻ nhất.

Cache được tổ chức thế nào?

Mỗi lượt, Claude Code gửi lại toàn bộ ngữ cảnh. API so khớp phần đầu (prefix) với nội dung vừa xử lý; khớp chính xác thì đọc từ cache với giá rẻ, chỗ nào khác thì tính lại từ đó trở đi.

Thao tác làm vỡ cache

• Đổi model: mỗi model có cache riêng, nên lượt sau đọc lại toàn bộ hội thoại không trúng cache. opusplan đổi model mỗi lần vào/ra plan mode; skill có trường model khác cũng tính là đổi model.
• Đổi effort: phá cache trên phần lớn model. Riêng Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.1 (dùng API key hoặc gói Claude) thì giữ được cache.
• Bật/tắt fast mode: hai tốc độ dùng cache riêng; nên bật ngay đầu phiên.
• Thêm/bớt MCP server, deny cả một tool: phá cache khi tool được nạp sẵn; nếu tool search đang hoạt động (mặc định trên model hỗ trợ) thì cache được giữ.
• /compact: thay lịch sử bằng bản tóm tắt nên lớp hội thoại phải dựng lại. Compact khi cache còn ấm thì rẻ; compact phiên cũ đã nguội thì đắt nhất.
• Nhiều ảnh: vượt giới hạn, Claude Code bỏ một loạt ảnh cũ và tính lại từ đó.
• Nâng cấp Claude Code: phiên đầu tiên sau nâng cấp dựng cache từ đầu.

Thao tác an toàn

• Sửa file trong repo (Claude được nhắc file đã đổi, đọc lại nếu cần).
• Sửa CLAUDE.md giữa phiên: cache giữ nguyên, nhưng bản sửa chưa có hiệu lực cho tới /clear, /compact hoặc khởi động lại.
• Đổi permission mode, đổi output style, gọi skill/lệnh, /recap.
• /rewind: cắt về một prefix đã có sẵn trong cache, rẻ hơn compact khi bạn muốn bỏ hẳn một hướng đi.
• Gọi subagent: cache của phiên chính không bị ảnh hưởng.

Thời gian sống của cache

API có hai mức TTL: 5 phút và 1 giờ (ghi cache đắt hơn). Theo mặc định, gói Claude (trong hạn mức) dùng 1 giờ cho hội thoại chính; API key và cloud provider dùng 5 phút. Bạn tự chọn bằng promptCacheTtl (hội thoại chính) và subagentPromptCacheTtl, giá trị 5m hoặc 1h.

// ~/.claude/settings.json: dùng API key nhưng hay nghỉ giữa chừng
{ "promptCacheTtl": "1h" }

Đo tỷ lệ trúng cache

• /usage có dòng Prompt cache (main): tỷ lệ trúng, số lần trượt, cache còn ấm không, và nguyên nhân có thể của lần trượt gần nhất.
• Statusline đọc cache_read_input_tokens và cache_creation_input_tokens: đọc nhiều, ghi ít là tốt; ghi cao liên tục nghĩa là prefix đang bị đổi.

Rủi ro và lưu ý

• Gateway nuốt marker cache: nếu gateway xoá cache_control, toàn bộ hội thoại bị tính giá chưa cache ở mọi lượt.
• TTL 1 giờ không phải lúc nào cũng rẻ hơn: làm liên tục, không nghỉ quá 5 phút thì phí ghi cao hơn là lãng phí.
• Cache gắn với máy và thư mục: phiên ở thư mục khác không dùng chung cache.

Áp dụng thế nào?

• Dev: Chọn model, effort, fast mode ngay đầu phiên; compact ở điểm nghỉ giữa các task; muốn bỏ hướng sai thì /rewind thay vì compact.
• Tech Lead: Kiểm tra gateway nội bộ có chuyển tiếp nguyên cache_control và header beta không.
• PM: Khi usage bất thường, xem dòng Prompt cache (main) trong /usage trước khi kết luận cần gói lớn hơn.