Working with Claude Code: 2. CLAUDE.md

Here is a complete guide on how to manage CLAUDE.md and optimize your context.

1. Why CLAUDE.md is your best friend

When you start a session, Claude Code automatically reads CLAUDE.md. Instead of having to paste your project rules, tech stack, and file structure into the chat every single time, Claude just knows it. This saves massive amounts of context space for your actual task.

2. How to edit CLAUDE.md

You have two ways to edit it:

• Method A: Manually (Recommended for structure) Simply open CLAUDE.md in your text editor (VS Code, Vim, etc.) and write it like standard Markdown.
• Method B: Ask Claude (Great for updates) While in Claude Code, you can say: "We just refactored the authentication system to use JWT. Please update CLAUDE.md to reflect this new architecture." Claude will propose the edits, you approve them, and the memory is updated.

3. What to put in CLAUDE.md (and what to leave out)

A good CLAUDE.md is concise and directive. Think of it as a cheat sheet for a new developer.

Include:

• Tech Stack: "Python 3.11, FastAPI, PostgreSQL, SQLAlchemy."
• Commands: How to run, test, and lint. (npm run dev, pytest, npm run lint).
• Architecture/Structure: A brief tree of important directories.
• Conventions/Rules: "Always use functional React components. Do not use default exports. Use TypeScript interfaces."
• Current State: "We are currently migrating the user auth module. Do not touch the legacy_auth/ folder."

Do NOT include:

• Huge code blocks: Don't paste entire files in here. It wastes context.
• Transient info: Don't put your current specific bug in here (e.g., "Fix the typo on line 45 of app.js"). Put that in the chat prompt.
• Massive READMEs: Keep it under ~100 lines if possible.

Example of a Perfect CLAUDE.md:

# Project: Web Scraper API

## Tech Stack
- Python 3.11, FastAPI, BeautifulSoup4, Uvicorn
- Database: SQLite (for now)

## Commands
- Run server: `uvicorn main:app --reload`
- Install deps: `pip install -r requirements.txt`
- Run tests: `pytest`

## Project Structure
- `/routers` - API route definitions
- `/scrapers` - BeautifulSoup logic
- `/models` - Pydantic models

## Coding Conventions
- Use `async/await` for all routes.
- Always add type hints to function signatures.
- Do not create new requirements files; update `requirements.txt` directly.

4. Other Ways to Keep Context Optimal

Aside from CLAUDE.md, here are the golden rules for context management inside the Claude Code CLI:

A. Use /clear religiously

Claude Code keeps a running history of your conversation. If you have spent 30 minutes fixing a CSS bug, and you now want to write a new database migration, all that CSS history is still in Claude's context, slowing it down and distracting it.

• Action: When you finish a logical chunk of work and are moving to a new task, type /clear in the Claude prompt. This wipes the conversation history. Don't worry, Claude will re-read CLAUDE.md and your files, so it won't forget the project rules—only the irrelevant chat history.

B. Let Claude explore, don't paste files

A common beginner mistake is copying a file's code from the editor and pasting it into the Claude Code prompt.

• Instead: Say "Look at src/components/Header.tsx and fix the bug where the logo isn't loading." Claude will use its tools to open the file, read it, and fix it. This is much more context-efficient than pasting raw text.

C. Scope your requests

Instead of saying: "Build a user authentication system with login, signup, password reset, and profile editing." Say: "Let's build the user auth system. First, let's just set up the database model and the signup endpoint." Smaller, scoped tasks keep the context focused on one file or module at a time, resulting in fewer errors.

D. Rely on your .gitignore

Claude Code respects .gitignore. If you have massive folders of logs, build artifacts, or dependencies (like node_modules or venv), make sure they are in .gitignore. Claude won't try to read them, which saves context and prevents it from hallucinating based on third-party library code.

Summary Checklist for Optimal Context:

1. Write a concise, helpful CLAUDE.md and update it as the project evolves.
2. Type /clear between distinct tasks.
3. Tell Claude to read files using file paths; don't paste code into the chat.
4. Break large features down into smaller, step-by-step prompts.

ai

Back