ZenifyKit

Appearance

Ngân sách context ​

Tổng quan ​

Chi phí một session Claude Code không nằm ở số chữ model viết ra mà ở khối context được đọc lại mỗi turn. Đo trên một workspace trong 30 ngày (zenify cost): 95% token là cache read, context của phiên chính median 186k token mỗi turn, và thứ lấp đầy nó là kết quả tool (45%), trong đó Read chiếm 61%. Mọi kết quả đã vào context nằm lại đó cho đến /clear.

Context lớn không chỉ đắt. Các phép đo độc lập (Context Rot, NoLiMa) cho thấy độ chính xác giảm rõ khi context vượt vài chục nghìn token. Giữ context nhỏ là chuyện chất lượng trước, tiền sau.

Kit có bốn cơ chế cho việc này. Ba cái đầu là cơ học, cái cuối là quy tắc.

read-guard: chặn Read quá lớn ​

Hook PreToolUse trên tool Read. Nó từ chối, kèm gợi ý, khi:

  • file text trên 200 KB mà lệnh Read không có cả offset và limit;
  • file .pdf không có pages;
  • ảnh (png, jpg, jpeg, gif, webp) trên 300 KB.

Khi bị chặn, agent thấy một dòng bắt đầu bằng znf read-guard: nêu kích cỡ và cách đọc lại: đọc theo lát với offset + limit, đọc PDF theo pages, hoặc giao một subagent tóm tắt và trả về vài dòng. Ảnh lớn nên để znf:ui-verifier xem và trả verdict.

Hook fail-open: file không tồn tại, payload lạ, hay lỗi bên trong đều cho qua. Nó chỉ chặn đúng ba trường hợp trên. Không có cờ bỏ qua trong prompt; nếu thật sự cần đọc nguyên file, bạn đọc thay bằng ! cat <file> trong session, hoặc tắt hook trong ~/.claude/settings.json. Số lần chặn được ghi vào meter của session dưới tên Read:denied, tách khỏi tổng tool-out và không tính vào ngưỡng session nặng.

Meter: hỏi một lần khi session nặng ​

Hook PostToolUse đo byte kết quả tool. Một kết quả trên 50 KB sinh một dòng nhắc chuyển output ra file. Khi tổng trong session vượt 2 MB, meter yêu cầu agent hoàn tất bước đang làm đến ranh giới file gần nhất (spec, plan, ledger) rồi hỏi bạn một câu: /clear và vào lại bằng đường dẫn file đó, hay tiếp tục. Câu này chỉ hỏi một lần cho mỗi session; sau đó meter im lặng.

Statusline: ctx% đổi màu ​

zenify observe statusline in ctx N% theo context_window.used_percentage của Claude Code: thường dưới 50%, vàng từ 50%, đỏ từ 80%. Đỏ là lúc /clear ở ranh giới file gần nhất. Nếu bạn đã có statusline riêng, kit không ghi đè; dùng --segment để ghép hai segment của kit vào dòng của bạn.

Quy tắc trả về của subagent ​

znf:discipline §10: mọi dispatch ghi rõ cap trả về, tối đa 40 dòng. Bảng, danh sách dài, log ghi ra file và trả đường dẫn. Đây là quy tắc bằng chữ, không có hook chặn; tin nhắn agent trả về là nguồn lớn thứ hai lấp context sau kết quả tool.

Task list của harness: tắt ​

Kit không dùng TodoWrite/TaskCreate. Đo trên bốn phiên (2026-09-20): mỗi lệnh task list là một lượt API riêng, không lượt nào gộp cùng tool khác, và các lượt đó chiếm 7 đến 18% chi phí lượt tool (đọc cache cộng token suy nghĩ), trong khi nội dung bảng chỉ dưới 3% byte. Tiến độ nằm trong ledger file mà skill đặt tên: progress.md của SDD, board của ship, scope block của research. Agent im lặng vẫn hiện là dòng chưa tick trong file, và file sống qua compaction. Sau khi compact hoặc quay lại sau khi nghỉ, /znf:where đọc lại các ledger này cùng branch, worktree và PR để tóm tắt task tới đâu. Đừng đặt CLAUDE_CODE_ENABLE_TODO_TOOLS=1 trong settings.

Việc bạn tự làm ​

  • Chạy /context một lần trên máy mình. MCP server nào bạn không dùng trong workspace này thì tắt; mỗi server chiếm vài nghìn token schema ở mọi turn.
  • Auto-compact: kit không đặt ngưỡng. Trên model 1M, mặc định nổ ở khoảng 967k; /autocompact 300k hay thấp hơn là lựa chọn cá nhân, cân giữa số lần compact và kích cỡ context.
  • /clear giữa hai việc không liên quan là miễn phí và hiệu quả nhất.

Kiểm tra bằng zenify doctor ​

Các check đo phần context nạp mọi phiên, không phụ thuộc runtime:

  • context-budget: cộng byte của CLAUDE.md workspace, ~/.claude/CLAUDE.md và các rule không có paths: trong .claude/rules/ của workspace lẫn ~/.claude/rules/. Cảnh báo khi tổng vượt 32 KiB hoặc CLAUDE.md workspace vượt 8 KiB. Với mỗi repo trong manifest, in byte và số dòng của CLAUDE.md, cảnh báo khi vượt 8 KiB, vượt 200 dòng, hoặc có cây thư mục (├──, └──).
  • workspace-root: liệt kê entry ở root workspace và dưới docs/ nằm ngoài quy ước thư mục; chỉ báo, không dọn.
  • memory-index: cảnh báo khi MEMORY.md gần trần nạp mỗi phiên (200 dòng / 25 KB; phần vượt bị cắt âm thầm).
  • shadow: liệt kê rule cá nhân trong ~/.claude/rules trùng tên với rule của workspace. Bản cá nhân nạp cạnh bản workspace nên context nhân đôi; xoá hoặc đổi tên bản cá nhân. Check này chỉ so rule: skill của plugin znf luôn mang tiền tố znf: nên không xung đột với skill cá nhân.