Claude Was Getting Slower

I noticed that Claude Code was taking longer to respond and sometimes giving answers that didn’t match what I was working on. It would reference parts of my project that weren’t relevant to the current task.

I checked my project documentation files:

  • CLAUDE.md: 500+ lines
  • CLAUDE_StoryPack.md: 450+ lines
  • 100_Days_Plan.md: 400+ lines

Every time I started a conversation with Claude Code, it was loading all of this into context. That’s about 7,500 tokens of documentation before even starting the actual conversation.

Too Much Context

The problem was that I had been adding everything to CLAUDE.md thinking more documentation would help Claude understand my project better.

But the opposite happened. Too much irrelevant information made Claude’s responses less focused.

When I’m working on Korean translation, I don’t need all the details about the story pack generator architecture. When I’m fixing a CSS bug, I don’t need the complete 100-day project plan.

I was wasting tokens on context that didn’t matter for the current task.

Reorganizing Documentation

I split the documentation into smaller, focused files:

CLAUDE.md (always loaded) - Just a summary:

  • What is What If Classics
  • Current project status
  • Links to other documentation files
  • Quick command reference

Specialized files (loaded only when needed):

  • CLAUDE_Architecture.md - Technical details about Astro, build process, deployment
  • CLAUDE_i18n.md - Korean translation workflow
  • CLAUDE_ContentFactory.md - Story pack generator details
  • CLAUDE_StoryPack.md - Archived (not loaded by default)

Then I created a .claudeignore file (like .gitignore but for Claude Code):

# Always exclude
100_Days_of_Building_in_Public.md
CLAUDE_StoryPack.md

# Load only when needed
CLAUDE_Architecture.md
CLAUDE_i18n.md
CLAUDE_ContentFactory.md

Now Claude loads only 400 tokens by default (the summary). When I’m working on translation, I uncomment CLAUDE_i18n.md in the ignore file and Claude loads 1,200 tokens total.

That’s a 95% reduction in token usage for typical coding sessions.

Better Responses

After reorganizing, Claude’s responses got noticeably better:

  • Faster responses
  • More focused on the actual task
  • Doesn’t reference irrelevant parts of the project
  • Can have longer conversations without hitting token limits

The key was treating documentation like code—don’t load everything, only load what you need.

For Other Claude Code Users

If you’re building a project with Claude Code and your CLAUDE.md file is getting big, consider splitting it:

  1. Keep CLAUDE.md short (under 200 lines)
  2. Move detailed documentation to separate files
  3. Use .claudeignore to control what loads
  4. Load specialized docs only when working on those features

I went from 7,500 tokens per conversation to 400 tokens. Your mileage may vary, but even a 50% reduction would be worth it.

To be continued…