title: "Anti-Pattern: Empty CLAUDE.md" last_updated: 2026-03-21 status: proven difficulty: beginner prerequisites:

  • Basic experience with Claude Code or similar agentic tool

Empty CLAUDE.md

What It Looks Like

You use Claude Code daily but have never created a CLAUDE.md file. Every session, you re-explain your project structure, coding conventions, test commands, and deployment process. The agent asks the same clarifying questions each time.

Why Developers Do This

It doesn't seem important at first. The agent works fine without it. Writing project documentation feels like overhead. "I'll set it up later" becomes never.

Why It Fails

Without CLAUDE.md (or AGENTS.md for Codex CLI), every session starts from zero. The agent has no memory of your project's conventions, architecture decisions, or preferred patterns. You burn context tokens and time re-establishing basics. Worse, the agent may make inconsistent choices across sessions because it has no stable reference.

The Symptoms

  • Repeating the same instructions every session
  • Agent using different coding styles across sessions
  • Agent running the wrong test command or build tool
  • Inconsistent file organization in generated code

What to Do Instead

Create a CLAUDE.md in your project root with essential project context.

<!-- Wrong: no CLAUDE.md at all, or an empty one -->

<!-- Right: CLAUDE.md with practical project context -->
# Project: Acme API

## Build & Test
- `npm run build` to compile TypeScript
- `npm test` runs Jest; `npm run test:e2e` for integration tests
- Always run tests before suggesting a task is complete

## Conventions
- Use TypeScript strict mode; no `any` types
- Error handling: use Result<T, E> pattern, never throw
- File naming: kebab-case for files, PascalCase for components

## Architecture
- src/routes/ — Express route handlers
- src/services/ — Business logic
- src/db/ — Prisma schema and migrations

Start small. Add conventions as you notice the agent getting things wrong. Your CLAUDE.md will grow organically into the most useful file in the repo.