Splitting CLAUDE.md Didn't Work — GitHub Features Did

In my previous article, I trimmed CLAUDE.md from 273 to 121 lines — extracting templates into separate files and prioritizing guardrails (things Claude tends to get wrong).

Then I tried the same approach on a different project, and ran into a new problem.

The Separated Files Still Don’t Get Read

Following the previous approach, I distributed information like this:

• CLAUDE.md — development rules, guardrails
• docs/claude/handover.md — handover notes
• docs/claude/api-spec.md — API specification
• current-tasks.md — task management

What happened:

1. Separated files bloated too — handover notes accumulated chronologically, handover.md grew to hundreds of lines
2. Claude just doesn’t read them — as the number of files increases, Claude has a harder time finding what it needs
3. Double maintenance — tasks ended up managed in both local MD files and GitHub Issues
4. Stale information persists — completed tasks and resolved incident notes never get cleaned up

I tried moving finished tasks to log.md, but then the log file bloated. Noise in searches, generally in the way.

“Splitting into more files solves it” turned out to be wishful thinking. More documents meant Claude was less likely to read any of them.

The Fix: Delegate to GitHub

Instead of writing to local MD files, I moved responsibilities to GitHub’s built-in features.

Type of information	Before	After
Bugs and tasks	current-tasks.md	GitHub Issues
Progress tracking	Manual MD updates	GitHub Projects
Technical specs	docs/claude/ MD files	GitHub Wiki
Incident lessons	Accumulated in handover MD	Issues (postmortem label)

Why GitHub

1. Searchable — Issues and Wiki support full-text search, easier to find things than in local MD
2. Structured — Labels, milestones, and Projects organize information automatically
3. Automatable — GitHub Actions can route Issues based on labels
4. Closeable — Completed Issues get closed, leaving only active information visible

“Closeable” is the key one. Local MD files can only accumulate — you can only append. Issues have a natural “done, close it” flow. Old information disappears from view automatically.

When you’re in full vibe-coding mode and handing everything off to Claude, this difference becomes obvious. With MD files, it’s hard to tell “what’s been done, what’s still left.” With Issues, everything is visible in a list.

Workflow

1. Plan in Plan mode — have Claude draft an implementation plan
2. If it looks good, create an Issue — turn the plan directly into a GitHub Issue
3. Continue from the Issue in future sessions — even after a session reset, reading the Issue restores context

The Wiki holds a high-level overview of backend and frontend structure. Both humans and Claude can answer “what does this thing do again?” by looking there.

Claude Code has LSP support for function lookup now — if that works properly, it helps too. But regardless of how Claude navigates the code, keeping things documented in a human-readable form is worthwhile anyway.

Letting Claude Clean Up the Docs

Early in development, the documentation grew past 100 files with plenty of duplication. I had Claude clean it up:

1. Have Claude read through the current implementation
2. Compare against existing documentation
3. Remove duplicates and outdated content
4. Register the cleaned-up content in the Wiki

Local MD files tend to become “just append more.” A Wiki migration creates a natural opportunity to audit.

Context Consumption

The biggest problem with local MD files is that just loading them costs context. Reading a task-management MD might burn a few percent of context — wasteful. With GitHub Issues, gh issue list output is all you need.

There’s still the overhead of gh commands, but using an MCP for the same job would involve similar access patterns. This comes down to preference.

If it gets slow in practice, I might build an MCP for document search — but GitHub’s standard tooling has been enough so far.

Personally, I want to limit MCPs to cases where there’s no substitute — Playwright for browser automation, for example. Nothing else can do E2E testing or browser control. For something like document search, gh is fine.

Actual Impact

Since switching to this workflow, Claude asks fewer clarifying questions. When the information is in one place, Claude goes and gets it itself, runs tests, and reports back with results.

That’s exactly what I wanted — I can focus on defining requirements while Claude handles execution.

Implementation Examples

1. Label Schema

bug          - Bug report
task         - Task
handover     - Handover item
postmortem   - Incident lesson
frontend     - Frontend related
backend      - Backend related

Issues with the handover label replace the old handover MD files.

2. Auto-routing with GitHub Actions

# .github/workflows/auto-project.yml
name: Add to Project
on:
  issues:
    types: [opened, labeled]

jobs:
  add-to-project:
    runs-on: ubuntu-latest
    steps:
      - name: Add to Project
        if: contains(github.event.issue.labels.*.name, 'frontend')
        uses: actions/add-to-project@v1.0.2
        with:
          project-url: https://github.com/users/YOUR_USER/projects/1
          github-token: ${{ secrets.PROJECT_TOKEN }}

Issues with specific labels get automatically added to the right Project.

3. Simplified CLAUDE.md

Keep only the essentials in CLAUDE.md:

• Project overview (~10 lines)
• Guardrails (things Claude tends to get wrong)
• Critical rules (must-follow constraints)
• Link list (pointers to Wiki, Issues, Projects)

All detailed specs and procedures move to the Wiki. CLAUDE.md becomes an entry point, not a manual.

Results

Metric	Before	After
CLAUDE.md	386 lines	197 lines
Task management locations	2 (MD + Issues)	1 (Issues)
Handover information	Accumulated in MD	Issues, searchable
Completed tasks	Manual deletion or left in place	Auto-archived on close

Operating Rules

1. Start of work: gh issue list to get current state
2. Found a bug: gh issue create --label bug
3. Handover item: gh issue create --label handover
4. Task done: gh issue close NUMBER --comment "what was done"
5. New technical info: Update Wiki

Claude Code can run gh commands natively, so this workflow fits naturally.

The shift from “split into more files” to “delegate to a system” is what made the difference. Splitting files just spreads the bloat around — a proper system (GitHub) organizes, searches, and self-cleans.