How I Cut This Site's CLAUDE.md by More Than Half

This blog’s CLAUDE.md had grown to 273 lines. Template code and reference material had piled up, hurting token efficiency. Time to clean it up.

The Problems

1. Embedded template code: A full page template (~80 lines), HTML snippets, and similar content were written directly in the file.
2. Mixed guardrails and manual content: “Things Claude gets wrong” and “reference information” were scattered in the same place with no clear separation.
3. Poor token efficiency: Every session loaded unnecessary implementation details into the context.

Cleanup Approach

Applied the “guardrails-first” principle from my previous article to my own repository:

• CLAUDE.md focuses on “things Claude tends to get wrong”
• Detailed templates move to separate files, referenced by pointer

What I Did

1. Extracting Templates

Item	Action	Lines removed
Page template (80 lines)	Replaced with a reference to an existing file	-80 lines
HTML snippets (15 lines)	Moved to .claude/templates/	-15 lines
Embedded code example (8 lines)	Auto-handled, no explanation needed — deleted	-8 lines

Before: Template code embedded directly

### Page Template

Create at `src/pages/example.astro`:

---
import Layout from '@/layouts/Layout.astro';
// ... 80 lines of template code
---

After: Pointer to an existing file

### Page Template
See existing file: `src/pages/example.astro`

2. A Dedicated Guardrails Section

Created a clear section for things Claude tends to get wrong:

## Guardrails (Things Claude Gets Wrong)

### Styling: CSS for dynamically generated content
Framework-scoped CSS doesn't apply to DOM elements created by JavaScript.
→ Use global CSS or an external stylesheet.

### Markdown: Bold text and Japanese brackets
Combining `**bold**` with Japanese brackets can break rendering.
→ Use Japanese 「」 quotes instead.

This makes “what to avoid” and “what to do instead” immediately clear.

Result

Metric	Before	After
CLAUDE.md	273 lines	121 lines
Reduction	—	56% smaller

What I Learned

• Template code doesn’t need to live in CLAUDE.md. “See existing file: X” is enough — Claude will read it when needed.
• Separating guardrails (things to avoid) from manual content (reference info) keeps critical warnings from getting buried.
• Pairing “avoid X” with “do Y instead” makes it easier for Claude to take the right action.

What I Still Need to Verify

The cleanup is done, but I haven’t actually tested it on tasks that use those templates yet (this is a blog, so a lot of the work is writing articles rather than scaffolding pages). Next time I use a template or one of the extracted snippets, I’ll check:

• Whether the separated files are referenced correctly
• Whether token consumption has actually dropped
• Whether unintended context compression is happening

Checking Context Usage

Claude Code 1.0.86 and later have a /context command to get a detailed breakdown of context usage:

• System prompt / System tools token counts
• MCP tools / Custom agents consumption
• Memory files (CLAUDE.md, etc.) footprint
• Messages (conversation history) accumulation
• Free space remaining

The effect of trimming CLAUDE.md should show up in the “Memory files” section of this command.