claude-token-efficient

You can apply token-efficient rules to your project using one of three methods. The recommended method for regular work is to use a CLAUDE.md file in your project root, which Claude will automatically read on every message.

Option 1: Universal (Quickest)

Download the base CLAUDE.md directly into your project root using curl:

curl -o CLAUDE.md https://raw.githubusercontent.com/drona23/claude-token-efficient/main/CLAUDE.md

Option 2: Use a specialized profile

Clone the repository and copy a specific profile (e.g., for coding) to your project root:

git clone https://github.com/drona23/claude-token-efficient
cp claude-token-efficient/profiles/CLAUDE.coding.md your-project/CLAUDE.md

Option 3: Manual

Copy the contents of the CLAUDE.md file from this repository and paste them into a new file named CLAUDE.md in your project root.

To ensure data integrity during analysis, follow these hallucination prevention rules:

• No fabrication: Never fabricate data points, statistics, or citations.
• Grounding: If a claim cannot be directly grounded in the provided data, do not make it.
• Inference vs. Fact: Clearly distinguish between what the data shows and what is inferred. Label inferences explicitly (e.g., "Based on the trend..." instead of stating it as a fact).

To reproduce the token benchmarks using the project's harness, use the benchmark/run.py script. You can specify the number of runs (-n) and the target model. The harness uses the claude -p --output-format json engine over OAuth. Each prompt runs in a fresh /tmp directory to ensure isolation.

Note: This benchmark measures token efficiency for one-shot Q&A prompts, not agentic or coding loops.

python3 benchmark/run.py -n 5 --model {haiku,sonnet,opus}

When writing solutions, ensure you explicitly handle the following edge cases to ensure robustness:

• null values
• Empty strings
• Type mismatches

When deciding how to provide instructions to an AI agent, consider the following trade-offs:

• CLAUDE.md (Recommended): Automatically included on every message and cached efficiently. It is more cost-effective (benchmarks show ~30% less cost) and requires no manual copy-pasting.
• Rules in prompt (Alternative): Useful for one-off tasks or environments where you cannot modify the project structure. It is clearer which rules apply specifically to the current session but is more expensive in terms of token usage.

When working with WebSockets, follow these specific patterns for reliable communication and testing:

• Client Tracking: Track clients manually using a Set. Do not rely on pub/sub channels for broadcasting.
• Broadcast Sequence: Send a confirmation to the original sender first, then broadcast the message to all other connected clients.
• Testing Synchronization: Use setTimeout(0) to allow test listeners sufficient time to register before a broadcast event fires.

Claude reads multiple CLAUDE.md files simultaneously. You can use this to manage scope and avoid bloating a single file:

• Global level (~/.claude/CLAUDE.md): Use for general preferences like tone, format, and ASCII rules.
• Project level (your-project/CLAUDE.md): Use for project-specific constraints (e.g., "never modify /config without confirmation").
• Subdirectory level (your-project/src/api/CLAUDE.md): Use for task-specific rules relevant only to that part of the codebase.

The project provides different profiles for CLAUDE.md to balance token savings against model behavior:

1. Minimal Profile (Current CLAUDE.md): Provides modest token reductions (e.g., ~-18% for Sonnet). Best for general use where you want to reduce verbosity without significant risk to output quality.
2. Aggressive Profile (profiles/CLAUDE.compressed.md): Provides significant token reductions (e.g., up to -62% for Opus). This profile drops fabrication and re-read guards. Use this only when token cost dominates and the workload is low-risk.

To maintain efficiency and avoid common pitfalls, avoid the following practices:

• Writing code before reading existing files
• Hardcoding absolute paths
• Not testing before declaring a task done
• Re-reading files unnecessarily
• Over-engineering simple solutions

To ensure outputs remain concise and avoid common AI-generated patterns, adhere to these formatting constraints:

• Tone: Output should sound human and avoid typical AI-generated markers.
• Punctuation: Never use em-dashes or replacement hyphens.
• Sentence Structure: Avoid parenthetical clauses entirely.
• Hyphen Usage: Use hyphens only for standard grammar.

When generating analytical content, adhere to these formatting and accuracy standards:

Output Structure

• Lead with findings: State the primary finding first, followed by context and methodology.
• Visuals over prose: Use tables and bullet points instead of long prose paragraphs.
• Explicit units: Always include units with numbers; avoid ambiguous values.

Accuracy Standards

• Source attribution: Never state a number without providing its source or derivation.
• Missing data: If data is missing, explicitly state it. Do not perform silent estimations.
• Confidence levels: If confidence in a finding is low, state it explicitly and provide a reason.
• Precision: Do not round numbers aggressively; preserve all meaningful precision.

Adopt these patterns to ensure high-quality and maintainable code:

• Read first, then write: Understand the context before implementation.
• Test after every significant change: Ensure stability incrementally.
• Use relative paths: Maintain portability across environments.
• Keep solutions minimal: Avoid unnecessary complexity.
• Handle edge cases in data: Explicitly manage null values, empty strings, and type mismatches.