claude-md-manager

buvis's avatarfrom buvis

Build and maintain effective CLAUDE.md files that improve Claude Code efficiency. Use when creating a new CLAUDE.md file, auditing/improving an existing one, setting up progressive disclosure with agent documentation, or optimizing context window usage for Claude Code projects.

⭐2stars🔀0forks📁View on GitHub🕐Updated Jan 4, 2026

When & Why to Use This Skill

The CLAUDE.md Manager is a specialized developer tool designed to optimize the interaction between Claude Code and your codebase. It focuses on building and maintaining high-quality CLAUDE.md files that maximize AI efficiency by providing essential project context—such as tech stacks, core commands, and project structures—without bloating the context window. By implementing the 'Progressive Disclosure' pattern and adhering to strict line limits, this skill ensures that Claude receives 100% universal instructions, preventing the AI from ignoring critical project data and significantly improving the accuracy of code generation and debugging.

Use Cases

  • New Project Onboarding: Automatically generating a lean, structured CLAUDE.md file for new repositories to ensure Claude Code understands the tech stack and commands immediately.
  • Context Window Optimization: Auditing existing, overstuffed documentation files to extract non-essential information into an 'agent_docs/' directory, reducing token usage and preventing instruction loss.
  • Workflow Standardization: Establishing a consistent 'WHAT, WHY, HOW' framework across multiple team projects to provide a unified interface for AI agents.
  • Technical Debt Reduction: Identifying and removing stale code snippets or style guidelines from agent-facing docs, replacing them with dynamic file pointers and linter configurations.
  • Complex Architecture Mapping: Setting up progressive disclosure indexes that guide Claude to specific documentation for databases, testing, or deployment only when needed.
nameclaude-md-manager
descriptionBuild and maintain effective CLAUDE.md files that improve Claude Code efficiency. Use when creating a new CLAUDE.md file, auditing/improving an existing one, setting up progressive disclosure with agent documentation, or optimizing context window usage for Claude Code projects.

CLAUDE.md Manager

Build and maintain high-quality CLAUDE.md files that maximize Claude Code efficiency.

Core Principle

LLMs are stateless. CLAUDE.md is the only file that goes into every conversation with Claude Code. It must onboard Claude to your codebase efficiently without bloating the context window.

Critical insight: Claude Code's system prompt tells Claude to ignore CLAUDE.md contents if deemed irrelevant. Overstuffed files with non-universal instructions get ignored entirely.

Three Pillars of a Good CLAUDE.md

Every CLAUDE.md should answer three questions concisely:

  1. WHAT - Tech stack, project structure, key directories
  2. WHY - Project purpose, what each part does
  3. HOW - Essential commands, verification steps, workflows

Hard Constraints

Constraint Limit Rationale
Total lines < 300 (ideal: < 100) Context window is shared with system prompt, conversation, tools
Instructions < 100 Frontier models reliably follow ~150-200 instructions; system prompt uses ~50
Applicability 100% universal Non-universal instructions cause entire file to be ignored

What NOT to Include

  • Code style guidelines - Use linters/formatters instead. LLMs learn from codebase patterns.
  • One-off task instructions - Put in slash commands or separate docs
  • Code snippets - Become stale; use file:line pointers instead
  • Auto-generated content - /init output is generic; craft manually
  • Conditional instructions - Use progressive disclosure instead

Progressive Disclosure Pattern

Keep CLAUDE.md lean by pointing to detailed docs:

project/
├── CLAUDE.md              # Core onboarding only (<100 lines)
└── agent_docs/            # Detailed docs loaded on demand
    ├── building.md
    ├── testing.md
    ├── database_schema.md
    ├── architecture.md
    └── deployment.md

In CLAUDE.md, include a brief index:

## Documentation

Read relevant docs from `agent_docs/` before starting work:
- `building.md` - Build commands and dependencies
- `testing.md` - Test execution and coverage
- `database_schema.md` - Table schemas and relationships
- `architecture.md` - Service structure and communication
- `deployment.md` - Deployment procedures and environments

Prefer pointers to copies - Reference file:line instead of embedding code.

CLAUDE.md Template Structure

See references/template.md for a complete template.

Minimal structure:

# Project Name

Brief one-line description.

## Stack

- Language/Framework: X
- Database: Y
- Key dependencies: Z

## Project Structure

app/          - Main application code
lib/          - Shared utilities
tests/        - Test suite

## Commands

Build:  `command here`
Test:   `command here`
Lint:   `command here`

## Documentation

Read from `agent_docs/` as needed:
- `file.md` - Description

Creating a New CLAUDE.md

  1. Analyze the project - Identify stack, structure, key workflows
  2. Start minimal - Begin with <50 lines covering essentials
  3. Create agent_docs/ - Move detailed documentation there
  4. Add pointers - Reference agent_docs from CLAUDE.md
  5. Validate - Run checklist from references/checklist.md

Auditing an Existing CLAUDE.md

  1. Count lines - Flag if >300 lines
  2. Check universality - Every instruction should apply to every task
  3. Find embedded code - Replace with file:line pointers
  4. Identify style rules - Move to linter config
  5. Extract conditionals - Move to agent_docs/
  6. Validate - Run checklist from references/checklist.md

Integrations

Hooks (for formatting/linting)

Instead of style instructions, configure a stop hook:

{
  "hooks": {
    "stop": [{
      "command": "npm run lint:fix && npm run format",
      "description": "Auto-fix formatting issues"
    }]
  }
}

Slash Commands (for specific workflows)

Create .claude/commands/ for task-specific instructions that shouldn't bloat CLAUDE.md.

Reference Files

  • references/template.md - Complete CLAUDE.md template with examples
  • references/checklist.md - Validation checklist for auditing
  • references/progressive-disclosure.md - Guide for organizing agent_docs/