Decisions
User Tasks
Summary
Add explicit token efficiency guidelines to CLAUDE.md to minimize token waste across sessions.
Problem / Motivation
- Every session costs tokens; small savings compound over time
- Without explicit guidelines, default behavior tends toward verbosity
- No systematic rules for efficient tool usage patterns
Proposed Solution
Add a “Token Efficiency” section to CLAUDE.md with rules:
- Be concise — no preamble, no restating questions
- Parallel tool calls — batch independent operations
- Use memory — check MEMORY.md before re-exploring known paths
- Use skills — prefer existing skills over manual multi-step workflows
- Don’t re-read files just written
- Targeted searches — specific globs/greps with limits
- Skip obvious confirmations — “Done.” suffices for low-risk actions
Reference: vault/20_knowledge/ai/token-efficiency-patterns.md for full patterns.
Phase Overview
| Phase | Description | Status |
|---|
| Phase 1 | Draft and add section to CLAUDE.md | — |
| Phase 2 | Ensure knowledge base reference exists | — |
Phase 1: Add CLAUDE.md section —
Goal: Insert token efficiency guidelines into CLAUDE.md.
| File / Feature | Details | Owner | Status |
|---|
CLAUDE.md | Add Token Efficiency section | opus | — |
Phase 2: Knowledge base reference —
Goal: Ensure vault/20_knowledge/ai/token-efficiency-patterns.md exists with full patterns.
| File / Feature | Details | Owner | Status |
|---|
vault/20_knowledge/ai/token-efficiency-patterns.md | Full reference doc | opus | — |
Test
Manual tests
| Test | Expected | Owner | Actual | Last |
|---|
| CLAUDE.md contains Token Efficiency section | Section present | opus | pending | - |
| Knowledge base file exists and is referenced | File exists | opus | pending | - |
AI-verified tests
| Scenario | Expected behavior | Verification method |
|---|
| … | … | … |
E2E tests
Integration tests
Unit tests
| Component | Tests | Coverage |
|---|
| … | … | … |
History
| Date | Event | Details |
|---|
| 2026-03-12 | Created | From proposal proposal-token-efficiency-guidelines.md |
References
vault/90_inbox/proposals/proposal-token-efficiency-guidelines.md