You Don't Need a CLAUDE.md

Source: Dev.to

How to Manage CLAUDE.md / AGENTS.md Effectively

This article does not cover the usual prompt‑engineering basics (e.g., “avoid negative examples,” “set the LLM role,” “be specific”). If you need that foundation, refer to the official Anthropic or OpenAI documentation.

Instead, I’ll share the practical patterns I’ve honed over months of using Claude Code on real projects. The focus is on organizing documentation so the LLM stays effective as the codebase grows.

My Working Philosophy

• I’m not a “vibe coder.” I never let the LLM run autonomously for hours or days.
• I treat the LLM as a keyboard: it can read and type at super‑human speed, and it can execute actions to verify its work, but I stay in control.
• If a suggestion is too abstract or unclear, I stop it immediately.

Why a Tiny CLAUDE.md?

Every project should have a CLAUDE.md (or AGENTS.md) file that explains:

• What the project does
• How to navigate it
• Available development workflows

As the project matures the file can balloon, eventually exceeding the LLM’s context window. The solution: keep CLAUDE.md under ~30 lines and use it only as an entry point that defines the workflow. The LLM then decides which other docs to read based on the current task.

Example CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## YOUR ROLE
You are a diligent assistant. Pay attention to the task and the code.  
If you encounter a stupid idea, stop and report it.  
Be extremely concise—sacrifice grammar for brevity.

## THE MAIN FLOW
Create the following to‑do list immediately:

1. Analyze the user request.  
2. Run `find docs/ -name "*.md" | sort` to list available docs.  
3. Read docs that may help solve the current task.  
4. Read `tsconfig.app.json` to understand path shortcuts.  
5. Read `package.json` to understand commands.  
6. Analyze examples from the docs.  
7. Revise the execution plan and present it to the user with todo items.  
8. Once the user accepts, create revised todo items.  
9. Start work on the task.  
10. Use skills and commands that may help solve the current task.

**DO NOT EDIT THIS FILE** – it is the final form.

Key point: All detailed guidelines, workflows, and explanations live inside the docs/ folder. The CLAUDE.md merely tells the LLM how to discover and use those files.

Organizing the docs/ Folder

Structure the documentation logically, grouping related files into sub‑folders with descriptive names. Below is a real‑world example:

docs/
├─ backend/
│   ├─ graphql-api-patterns.md
│   ├─ rest-api-patterns.md
│   ├─ service-layer.md
│   ├─ data-layer.md
│   └─ event-system.md
├─ frontend/
│   ├─ actions/
│   │   ├─ create-component.md
│   │   ├─ create-modal.md
│   │   ├─ create-data-form.md
│   │   ├─ create-entity-selection.md
│   │   ├─ create-graphql-service.md
│   │   ├─ create-rest-service.md
│   │   ├─ create-route.md
│   │   └─ create-tree-view.md
│   ├─ architecture.md
│   ├─ design-tokens.md
│   └─ ui-ux.md
├─ build-deployment.md
├─ currency-system.md
├─ documentation.md
├─ error-handling.md
├─ localization.md
├─ security.md
└─ testing.md

• Global docs (e.g., security.md, testing.md) cover high‑level concepts.
• Feature‑specific docs (e.g., frontend/actions/create-component.md) guide concrete actions.

How This Helps

1. Minimal context per task – When the LLM runs find docs/ -name "*.md" | sort, it only sees a list of file names (a few dozen lines).
2. Selective loading – Based on the filenames, the LLM decides which documents are relevant and reads only those.
3. Scalability – You can add unlimited documentation files without worrying about context limits. A front‑end task will never load back‑end or GraphQL docs unless explicitly needed.

Managing the Documentation Set with the LLM

Use the LLM itself to keep the docs tidy:

1. During a task – Continuously monitor the LLM’s actions, note any mistakes, and record how you fixed them.
2. After the task – Run a /refine command (or an equivalent custom command) to consolidate learnings and prune unnecessary content.

Sample Refinement Todo List

- Run `find docs/ -name "*.md" | sort` to see available docs.  
- Review the “How to Write Documentation” guide.  
- Identify outdated or duplicate files.  
- Update file headings for consistency.  
- Add cross‑references where needed.  
- Remove any files that are no longer relevant.  
- Commit the cleaned‑up docs with a concise commit message.  

Reflecting on the Session

This command tells the LLM to reflect on what happened during the session: what kind of errors occurred, how they were overcome, and whether there is something beneficial to add to the documentation so these errors can be avoided in the future.

Prerequisite

You need a markdown file that describes how to write documentation for your project. With this in place, the LLM will:

1. Think about the session.
2. Find an appropriate place inside existing documentation—or create a new document if needed.
3. Elaborate on how to avoid the issue in the future.

This way, your documentation evolves organically based on real problems encountered during development. Every session becomes an opportunity to improve the knowledge base.

Why This Works

• Not just for fixing errors – it applies to any case when you create a new system or discover an important action that you want to ensure is done correctly and consistently.
• Action documents (e.g., create‑modal.md, create‑component.md, create‑service.md) define a strict structure for specific tasks, reducing randomness when the LLM executes CLI commands or follows a precise sequence of steps.

Techniques to Improve Your Workflow with Claude Code

1. Prompt‑First, Refine‑Later

Instead of asking the LLM to perform a task directly, ask it to:

• Investigate the project.
• Read the documentation.
• Find problems in your prompt.
• Extend the prompt to cover all unclear cases.

Benefits

Key tip: Don’t be afraid to discard what the LLM has created and start over.

2. When the Result Isn’t Perfect

1. Stop the current run.
2. Return to your prompt and explain what was wrong.
3. Add missing information or clarify requirements.
4. Clean up the context and start a new session.

The LLM may then ask clarifying questions, suggest a better approach, or provide examples that help you refine the requirements further. The second attempt, armed with lessons from the first, will almost always be closer to what you actually want—and it will be built on a clean foundation rather than a patchwork of fixes.

3. Repeat Actions (Meta‑Prompting)

• After you have a solid prompt, you can meta‑prompt that prompt again.
• If everything is already fine, the LLM will quickly confirm the prompt’s solidity.
• With a fresh context, the LLM might notice something missed the first time.

The same idea applies to implementations:

• Create two implementations and compare them.
• The cost of a second attempt is low, while the benefit of catching issues or discovering a better approach is high.

4. Partial Implementations

1. Build a complete UI with mock data (in‑memory queries, fake API calls).
2. Iterate quickly on structure, flow, and user experience.
3. Once satisfied, replace the mocks with real API calls.

Before Claude Code, this would be tedious—implement, verify, test, repeat.
With Claude Code, you can get a UI with mock data in ~15 minutes and add real database integration in another ~15 minutes. The extra testing effort pays off by delivering a finished product in about an hour with predictable results.

Key Takeaway

• Keep CLAUDE.md minimal; use it as an entry point, not a knowledge dump.
• Store all substantive knowledge in a well‑organized docs/ hierarchy where the LLM can selectively read what it needs.
• This approach scales: you can have dozens of documentation files without hitting context limits.

Ongoing Documentation Maintenance

• Use the LLM itself to maintain and evolve your documentation.
• Every session where you catch and fix an error is an opportunity to improve the knowledge base for future sessions.
• Create action documents for repetitive tasks to eliminate randomness and ensure consistency.

Embrace the speed that Claude Code gives you, and let each interaction make your docs smarter and your workflow smoother.

Tips for Working with Claude Code

• Use meta‑prompting to refine your requirements before implementation.
• Don’t be afraid to throw out code and start fresh.
• Run things twice – a quick second pass often catches hidden issues.
• Build partial implementations with mocks to iterate quickly.
• Embrace repetition: the cost is low, and the benefit of getting exactly what you want is high.

These patterns transformed how I work with Claude Code. I hope they help you too.