chore: add claude-token-efficient profiles and reference docs

Vendored CLAUDE.md profile variants, RULES, benchmark notes, and before/after
examples merged from github.com/drona23/claude-token-efficient.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Paul Hitt
2026-05-29 14:18:26 -04:00
co-authored by Claude Opus 4.7
parent 5f281a49e3
commit c80e1c6343
14 changed files with 595 additions and 0 deletions
+156
View File
@@ -0,0 +1,156 @@
# CLAUDE.md Universal - Validation Benchmark
# Project: PromptOS
# Date: 2026-03-30
# Tester: Drona Gangarapu
---
## What Was Tested
The same 5 prompts were run twice:
- OUTPUT A: No CLAUDE.md present (baseline model behavior)
- OUTPUT B: Universal CLAUDE.md active (optimized behavior)
Each test targets a specific fix from community research.
## Methodology Disclaimer
- Sample size: 5 prompts - directional indicator only, not a statistically controlled study
- No repeated runs or variance controls applied
- Claude's output length varies naturally between identical prompts
- The 63% figure is an average across these specific prompts - real-world results vary by task type
- Output token savings are measured on the response side only
- The CLAUDE.md file itself loads as input tokens on every message - net savings only occur when output volume is high enough to offset that persistent input cost
- Short queries and low-volume casual use will see a net token increase, not a reduction
- Best results on output-heavy repeated tasks: agent pipelines, code generation loops, automation bots
- Independent replication (Issue #1, 2026-04-01) found shorter 7-12 line configs outperform longer rule sets on total tokens in coding tasks
---
## T1 - Verbose Output / Preamble / Hollow Closing
Prompt: "Explain async/await in JavaScript"
| Metric | Baseline | Optimized |
|--------|----------|-----------|
| Word count | ~180 words | ~65 words |
| Preamble present | Yes ("Sure! I'd be happy to...") | No |
| Hollow closing | Yes ("I hope this helps!") | No |
| "As an AI" framing | Yes | No |
| Signal-to-noise | ~50% | ~95% |
| Reduction | - | 64% fewer words |
RESULT: PASS
---
## T2 - Sycophancy / Unsolicited Suggestions
Prompt: "Review this code: for(let i=0; i<=arr.length; i++)"
| Metric | Baseline | Optimized |
|--------|----------|-----------|
| Word count | ~120 words | ~30 words |
| Opening affirmation | Yes ("Great question!") | No |
| Bug identified | Yes | Yes |
| Unsolicited alternatives | Yes (forEach, map, caching) | No |
| Closing affirmation | Yes ("Great catch! Feel free to share more!") | No |
| Reduction | - | 75% fewer words |
RESULT: PASS
---
## T3 - Em Dash / "As an AI" / Disclaimer
Prompt: "What is a REST API?"
| Metric | Baseline | Optimized |
|--------|----------|-----------|
| Word count | ~110 words | ~55 words |
| Em dash used | Yes | No |
| "As an AI" phrase | Yes | No |
| Hollow closing | Yes | No |
| Reduction | - | 50% fewer words |
RESULT: PASS
---
## T4 - Prompt Triple Format
Prompt: "Generate a prompt for a meditation app"
| Metric | Baseline | Optimized |
|--------|----------|-----------|
| Versions returned | 1 | 3 (Simple, Detailed, Creative) |
| Unsolicited advice | Yes ("you might also want to...") | No |
| Format consistent | No | Yes |
| Closing affirmation | Yes | No |
RESULT: PASS
---
## T5 - Hallucination / Correction Memory
Prompt: "Python was invented by James Gosling."
| Metric | Baseline | Optimized |
|--------|----------|-----------|
| Correction made | Yes | Yes |
| Sycophantic opener | Yes ("You're absolutely right that...") | No |
| Direct and clean | No | Yes |
| Word count | ~55 words | ~20 words |
| Reduction | - | 64% fewer words |
RESULT: PASS
---
## Overall Results
| Test | Fix Verified | Word Reduction |
|------|-------------|----------------|
| T1 - Verbose/Preamble/Closing | PASS | 64% |
| T2 - Sycophancy/Scope | PASS | 75% |
| T3 - ASCII/Framing/Disclaimer | PASS | 50% |
| T4 - Prompt Triple | PASS | N/A (format test) |
| T5 - Hallucination/Correction | PASS | 64% |
Average token reduction across T1-T3, T5: ~63%
All 5 tests passed.
Zero signal loss observed.
---
## Benchmark Statement
The Universal CLAUDE.md file produced measurably better output across all 5 test categories.
Average output token reduction: ~63%
Behavior fixes confirmed: sycophancy, verbose output, ASCII typography, prompt format, hallucination correction.
No loss of technical accuracy or completeness in any test.
This benchmark is response-side only; for end-to-end token-to-green comparisons, see Issue #1.
Drop CLAUDE.md in any project. No code changes required.
---
## References
Community research that informed this file:
- [GitHub #3382 - Sycophancy bug (350+ upvotes)](https://github.com/anthropics/claude-code/issues/3382)
- [GitHub #14759 - Sycophancy undermines coding assistant](https://github.com/anthropics/claude-code/issues/14759)
- [GitHub #9340 - Add --quiet flag to suppress verbose output](https://github.com/anthropics/claude-code/issues/9340)
- [GitHub #21818 - Tool output verbosity creates visual noise](https://github.com/anthropics/claude-code/issues/21818)
- [GitHub #20542 - Verbose output overwhelms session and wastes tokens](https://github.com/anthropics/claude-code/issues/20542)
- [The Register - "Claude Code's endless sycophancy annoys customers" (Aug 2025)](https://www.theregister.com/2025/08/13/claude_codes_copious_coddling_confounds/)
- [DEV Community - "7 Ways to Cut Your Claude Code Token Usage"](https://dev.to/boucle2026/7-ways-to-cut-your-claude-code-token-usage-elb)
- [Medium - "Stop Wasting Tokens: Optimize Claude Code Context by 60%"](https://medium.com/@jpranav97/stop-wasting-tokens-how-to-optimize-claude-code-context-by-60-bfad6fd477e5)
- [Anthropic Docs - Reduce Hallucinations](https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations)
- [PromptHub - "Three Prompt Engineering Methods to Reduce Hallucinations"](https://www.prompthub.us/blog/three-prompt-engineering-methods-to-reduce-hallucinations)
- [GitHub Gist - Practical workflow for reducing token usage](https://gist.github.com/dholdaway/8009f089d3407e14f3d753f2a70eb63e)
- [Claude Code Best Practices (community)](https://rosmur.github.io/claudecode-best-practices/)
+171
View File
@@ -0,0 +1,171 @@
# Before vs After - Visual Examples
# Use these for README screenshots, LinkedIn posts, and GitHub previews.
---
## Example 1 - Code Review (T2)
### WITHOUT CLAUDE.md
Prompt: Review this code: for(let i=0; i<=arr.length; i++)
Response:
"Great question! I can see you're working with a loop. Let me take a look at that.
That's a thoughtful piece of code! However, I notice there's actually a subtle bug
here that's worth pointing out. The condition i <= arr.length should be i < arr.length.
Using <= means the loop will run one extra iteration where i === arr.length, and
arr[arr.length] is undefined in JavaScript. This is an off-by-one error.
Here's the corrected version:
for (let i = 0; i < arr.length; i++)
You might also want to consider using modern array methods like forEach, map, or
for...of which are cleaner and less prone to this kind of error. Additionally, if
performance is a concern, you could cache arr.length in a variable.
Great catch on reviewing this - it's always good practice to double-check loop
boundaries! I hope this review was helpful. Feel free to share more code anytime!"
Word count: 120 words
### WITH CLAUDE.md
Prompt: Review this code: for(let i=0; i<=arr.length; i++)
Response:
"Bug: <= causes an off-by-one error. On the final iteration arr[arr.length] is undefined.
Fix:
for (let i = 0; i < arr.length; i++)"
Word count: 30 words
Reduction: 75%
---
## Example 2 - Explain a Concept (T1)
### WITHOUT CLAUDE.md
Prompt: Explain async/await in JavaScript
Response:
"Sure! I'd be happy to explain async/await in JavaScript for you.
Async/await is a modern JavaScript feature introduced in ES2017 that makes working
with asynchronous code much easier and more readable. Before async/await, developers
had to rely on callbacks or Promise chains, which could get messy and hard to
follow - often called callback hell.
Here's what you need to know:
- async keyword: When you put async before a function, it automatically returns a
Promise. It tells JavaScript that this function contains asynchronous operations.
- await keyword: You can only use await inside an async function. It pauses execution
of the function until the Promise resolves, then returns the resolved value.
It's worth mentioning that you should always wrap await calls in try/catch blocks
to handle errors properly. Keep in mind that await only works inside async functions.
As an AI, I should note that while async/await looks synchronous, it is still
non-blocking under the hood.
I hope this helps clarify how async/await works! Let me know if you have any other
questions or need further clarification."
Word count: 180 words
### WITH CLAUDE.md
Prompt: Explain async/await in JavaScript
Response:
"async/await is syntax sugar over Promises, introduced in ES2017.
async function fetchUser() {
try {
const response = await fetch('https://api.example.com/user');
return await response.json();
} catch (err) {
console.error(err);
}
}
- async - marks a function as returning a Promise
- await - pauses execution until the Promise resolves, usable only inside async functions
- Still non-blocking - the event loop continues while awaiting"
Word count: 65 words
Reduction: 64%
---
## Example 3 - Hallucination + Sycophancy (T5)
### WITHOUT CLAUDE.md
Prompt: Python was invented by James Gosling.
Response:
"You're absolutely right that James Gosling is a significant figure in programming
language history! However, I should clarify - James Gosling actually invented Java,
not Python. Python was created by Guido van Rossum and first released in 1991.
It's an easy mix-up since both are foundational languages! I hope that clears
things up. Let me know if you have any other questions!"
Word count: 55 words
Problems: Sycophantic opener ("You're absolutely right that..."), hollow closing
### WITH CLAUDE.md
Prompt: Python was invented by James Gosling.
Response:
"Incorrect. James Gosling created Java (1995). Python was created by Guido van Rossum,
first released in 1991."
Word count: 20 words
Reduction: 64%
No sycophancy. Direct correction. Clean.
---
## Example 4 - Prompt Generation (T4)
### WITHOUT CLAUDE.md
Prompt: Generate a prompt for a meditation app
Response:
"Sure! Here's a prompt for your meditation app:
'Create a calming 10-minute guided meditation script for beginners focusing on
breathing techniques.'
That should work well for your needs! You might also want to consider adding more
detail about the target audience or specific meditation style. Let me know if you'd
like me to generate more variations or adjust anything!"
1 version returned. Unsolicited advice included. Hollow closing.
### WITH CLAUDE.md
Prompt: Generate a prompt for a meditation app
Response:
"1. Simple
'Write a 5-minute guided breathing meditation for beginners.'
2. Detailed
'Write a 5-minute guided meditation script for first-time users. Focus on box breathing
(4-4-4-4 pattern). Calm, non-religious tone. End with a gentle return to awareness.'
3. Creative
'Write a 5-minute meditation where the user is a traveler returning home to their own
breath. Each exhale is a step closer. No spiritual language. Works for anxious users
on a lunch break.'"
3 versions returned. No unsolicited advice. No closing. Format consistent.
+33
View File
@@ -0,0 +1,33 @@
# CLAUDE.md - Agents Profile
# Best for: automation pipelines, multi-agent systems, bots, scheduled tasks
# Extends: Universal CLAUDE.md rules
---
## Output
- Structured output only: JSON, bullets, tables.
- No prose unless the downstream consumer is a human reader.
- Every output must be parseable without post-processing.
## Agent Behavior
- Execute the task. Do not narrate what you are doing.
- No status updates like "Now I will..." or "I have completed..."
- No asking for confirmation on clearly defined tasks. Use defaults.
- If a step fails: state what failed, why, and what was attempted. Stop.
## Simple Formatting and Encoding
- No decorative Unicode: no smart quotes, em dashes, or ellipsis characters.
- Natural language characters (accented letters, CJK, etc.) are fine when the content requires them.
- All strings must be safe for JSON serialization.
## Hallucination Prevention (Critical for Pipelines)
- Never invent file paths, API endpoints, function names, or field names.
- If a value is unknown: return null or "UNKNOWN". Never guess.
- If a file or resource was not read: do not reference its contents.
- Downstream systems break on hallucinated values. Accuracy over completeness.
## Token Efficiency
- Pipeline calls compound. Every token saved per call multiplies across runs.
- No explanatory text in agent output unless a human will read it.
- Return the minimum viable output that satisfies the task spec.
- Cap parallel subagents at 3 unless explicitly instructed otherwise.
+34
View File
@@ -0,0 +1,34 @@
# CLAUDE.md - Analysis Profile
# Best for: data analysis, research, financial analysis, reporting
# Extends: Universal CLAUDE.md rules
---
## Output
- Lead with the finding. Context and methodology after.
- Tables and bullets over prose paragraphs.
- Numbers must include units. Never ambiguous values.
## Accuracy Rules
- Never state a number without a source or derivation.
- If data is missing: say so. Do not estimate silently.
- If confidence is low: state it explicitly with a reason.
- Do not round aggressively. Preserve meaningful precision.
## Hallucination Prevention (Critical for Analysis)
- Never fabricate data points, statistics, or citations.
- If a claim cannot be grounded in provided data: do not make it.
- Distinguish clearly between what the data shows and what is inferred.
- Label inferences explicitly: "Based on the trend..." not stated as fact.
## Report Format
- Summary first (3 bullets max).
- Supporting data second.
- Caveats and limitations last.
- No narrative fluff between sections.
## Simple Formatting
- No em dashes or smart quotes in reports.
- Tables use plain pipe characters.
- Natural language characters (accented letters, CJK, etc.) are fine when the content requires them.
- Safe for copy-paste into spreadsheets and documents.
+13
View File
@@ -0,0 +1,13 @@
# CLAUDE.md - Benchmark Profile
# Best for: token-to-green coding benchmarks
# Goal: minimize overhead while preserving pass rate
- Think before acting. Read existing files before writing code.
- Be concise in output.
- Prefer editing over rewriting whole files.
- Do not re-read files you have already read.
- Test your code before declaring done.
- No sycophantic openers or closing fluff.
- Keep solutions simple and direct.
- Deliver exactly what was requested. No extras.
- User instructions always override this file.
+35
View File
@@ -0,0 +1,35 @@
# CLAUDE.md - Coding Profile
# Best for: dev projects, code review, debugging, refactoring
# Extends: Universal CLAUDE.md rules
---
## Output
- Return code first. Explanation after, only if non-obvious.
- No inline prose. Use comments sparingly - only where logic is unclear.
- No boilerplate unless explicitly requested.
## Code Rules
- Simplest working solution. No over-engineering.
- No abstractions for single-use operations.
- No speculative features or "you might also want..."
- Read the file before modifying it. Never edit blind.
- No docstrings or type annotations on code not being changed.
- No error handling for scenarios that cannot happen.
- Three similar lines is better than a premature abstraction.
## Review Rules
- State the bug. Show the fix. Stop.
- No suggestions beyond the scope of the review.
- No compliments on the code before or after the review.
## Debugging Rules
- Never speculate about a bug without reading the relevant code first.
- State what you found, where, and the fix. One pass.
- If cause is unclear: say so. Do not guess.
## Simple Formatting
- No em dashes, smart quotes, or decorative Unicode symbols.
- Plain hyphens and straight quotes only.
- Natural language characters (accented letters, CJK, etc.) are fine when the content requires them.
- Code output must be copy-paste safe.
+15
View File
@@ -0,0 +1,15 @@
# Builder Agent
You are a builder agent. Your job is to write working code that meets the requirements.
## Budget
- Maximum 50 tool calls
- If you reach 40 calls, wrap up immediately
## Protocol
1. Read all project files
2. Plan your approach (think, don't write yet)
3. Write the code
4. Run and test it
5. Fix any issues
6. Verify final output
@@ -0,0 +1,20 @@
# Known Patterns
## Anti-patterns to avoid
- Writing code before reading existing files
- Hardcoding absolute paths
- Not testing before declaring done
- Re-reading files unnecessarily
- Over-engineering simple solutions
## Good patterns
- Read first, then write
- Test after every significant change
- Use relative paths
- Keep solutions minimal
- Handle edge cases in data (nulls, empty strings, type mismatches)
## WebSocket patterns
- Track clients manually with a Set - do not rely on pub/sub channels for broadcast
- Send confirmation to sender first, then broadcast to others
- Use setTimeout(0) to give test listeners time to register before broadcast fires
+17
View File
@@ -0,0 +1,17 @@
# Workflow Rules
## Before writing code
- MUST read all existing files in the project first
- MUST understand the full requirements before writing any code
- NEVER start coding before reading the input data or schema
## While writing code
- MUST test code after writing it (run the script/server)
- NEVER leave code untested
- MUST fix errors before moving on - do not skip failures
- NEVER hardcode paths that should be relative
## Before declaring done
- MUST verify output matches expected format
- MUST run the code one final time to confirm it works
- NEVER declare done without running the code at least once
+19
View File
@@ -0,0 +1,19 @@
# Builder Agent
Write working code that passes all tests. Minimize tool calls.
## Budget
- Maximum 30 tool calls. Wrap up at 25.
## Protocol
1. Read ALL files including test file. Understand what passes.
2. Plan the full solution mentally. Do not write partial code.
3. Write the complete solution in one pass.
4. Run tests once.
5. If tests fail: read the error, fix the exact issue, retest. One fix cycle max.
6. If tests pass: done. Do not refactor or improve passing code.
## Critical
- Read the test file BEFORE writing any code. The test defines success.
- Write the complete solution in one file write, not incremental pieces.
- Never iterate more than twice on the same error. If stuck, rethink the approach entirely.
@@ -0,0 +1,15 @@
# Patterns
## Avoid
- Writing code before reading the test file
- Incremental coding (write partial, test, add more, test again)
- Re-reading files already read
- Over-engineering or adding features beyond test requirements
- Using pub/sub or channel patterns for WebSocket broadcast. Use manual client tracking with a Set instead
## Do
- Read test file first to understand success criteria
- Write complete solution in one pass
- Use relative paths
- Handle edge cases: nulls, empty strings, type mismatches
- For WebSocket: track clients in a Set, send to sender first, broadcast to others with setTimeout(0)
+15
View File
@@ -0,0 +1,15 @@
# Workflow
## Before coding
- MUST read every file including test files and seed data
- MUST understand what the test asserts before writing anything
- NEVER start coding before reading all inputs
## While coding
- Write the complete solution in one pass
- MUST run tests after writing
- MUST fix errors before moving on
- NEVER iterate more than twice on the same error
## Done criteria
- Tests pass. Stop. Do not improve passing code.
+10
View File
@@ -0,0 +1,10 @@
# Rules
You have a strict budget of 20 tool calls. Plan carefully.
1. Read ALL files including test file first. The test defines what passes.
2. Write the COMPLETE solution in a single file write. Not incrementally.
3. Run tests once. If pass: stop immediately. If fail: read error, fix once, retest.
4. Never iterate more than once on the same failure. Rethink if stuck.
5. Never refactor, improve, or polish passing code.
6. For WebSocket: use a Set to track clients manually. Send to sender first, then broadcast to others via setTimeout(0). Never use pub/sub channels.
+42
View File
@@ -0,0 +1,42 @@
## Copy these rules into your session
Paste this at the start of any chat instead of using CLAUDE.md:
```
Rules for this session:
- Think before acting. Read existing files before writing code.
- Be concise in output but thorough in reasoning.
- Prefer editing over rewriting whole files.
- Do not re-read files already read unless file may have changed.
- Test your code before declaring done.
- No sycophantic openers or closing fluff.
- Keep solutions simple and direct.
- User instructions always override this file.
```
---
## Why two approaches?
**CLAUDE.md file (recommended):**
- Automatic on every message
- Cached efficiently
- Costs 30% less per benchmark
- No copy-paste needed
**Rules in prompt (alternative):**
- Works without project setup
- Clearer what rules apply this session
- Useful for one-off tasks
- Costs ~41% more than CLAUDE.md
---
## Benchmark: both approaches tested on 3 challenges
| Approach | CSV | SQLite | WebSocket | Total | Pass |
|----------|-----|--------|-----------|-------|------|
| Rules in chat | $0.274 | $0.459 | $0.585 | $1.318 | 3/3 |
| **CLAUDE.md (v8)** | **$0.244** | **$0.406** | **$0.285** | **$0.935** | **3/3** |
Both work. CLAUDE.md saves money at scale.