You open Claude Code on a new project. You ask it to fix a bug. It changes the wrong file. It uses the wrong architecture pattern. It runs the wrong build command.

Not because Claude is bad. Because it doesn’t know your project.

That is what context files solve. A CLAUDE.md or AGENTS.md file tells the AI everything it needs to know about your project before it starts working. It is the single most impactful thing you can do to improve AI coding agent output.

What Are Context Files?

A context file is a markdown file at the root of your project that describes:

  • What the project is
  • How to build and test it
  • What architecture and patterns you use
  • What rules to follow
  • What to avoid

When Claude Code starts, it reads CLAUDE.md automatically. Other agents (Codex, Cursor, Copilot) are adopting similar standards with AGENTS.md.

Think of it like onboarding a new developer. Instead of spending 30 minutes explaining your project every time, you write it down once and the AI reads it every session.

The Difference Without and With Context Files

Without CLAUDE.md

You: "Add a new API endpoint for getting user settings"

Claude Code:
- Doesn't know your framework (Express? FastAPI? Ktor?)
- Doesn't know your folder structure
- Doesn't know your naming conventions
- Creates files in the wrong location
- Uses patterns that don't match your codebase
- You spend 10 minutes fixing what it generated

With CLAUDE.md

You: "Add a new API endpoint for getting user settings"

Claude Code:
- Knows you use Ktor with the repository pattern
- Knows endpoints go in routes/ folder
- Knows to use suspend functions and Flow
- Knows your naming convention for routes
- Creates the endpoint exactly where it should be
- Code matches your existing patterns perfectly

Same prompt. Completely different result.

CLAUDE.md — The Complete Guide

Where to Put It

Put CLAUDE.md in the root of your project:

my-project/
├── CLAUDE.md          ← here
├── src/
├── build.gradle.kts
└── ...

Claude Code reads this file automatically when you run claude in the project directory.

What to Include

A good CLAUDE.md has five sections:

  1. Project overview — what the project is and does
  2. Tech stack — languages, frameworks, libraries
  3. Build commands — how to build, test, lint, run
  4. Project structure — where things live
  5. Rules and conventions — how code should be written

Template: Android / Kotlin Project

# Project Overview

A task management app built with Kotlin and Jetpack Compose.
Users can create, edit, and delete tasks with categories and due dates.

## Tech Stack

- Language: Kotlin
- UI: Jetpack Compose with Material 3
- Architecture: MVI (Model-View-Intent)
- Database: Room
- Networking: Retrofit + Kotlin Serialization
- DI: Hilt
- Navigation: Jetpack Navigation Compose (type-safe)
- Minimum SDK: 24

## Commands

- Build: `./gradlew build`
- Test: `./gradlew test`
- Lint: `./gradlew lint`
- Run: `./gradlew installDebug`
- Clean: `./gradlew clean`

## Project Structure

- `app/src/main/java/com/example/taskapp/`
  - `ui/` — Compose screens and components
  - `ui/theme/` — Colors, typography, theme
  - `domain/` — Use cases and business logic
  - `data/` — Repository, Room database, API
  - `data/local/` — Room entities, DAOs
  - `data/remote/` — Retrofit API interfaces
  - `di/` — Hilt modules
  - `navigation/` — Routes and NavHost

## Rules

- Use StateFlow in ViewModels, never LiveData
- Use sealed interface for UI state and intents
- One state data class per screen
- Composables should not know about ViewModel directly — use callbacks
- Use .copy() for state updates, never mutate
- Every ViewModel must have unit tests
- Use Material 3 theme colors, never hardcode colors
- Write comments in English

Template: Python / FastAPI Project

# Project Overview

A REST API for managing a bookstore inventory.
Built with FastAPI and PostgreSQL.

## Tech Stack

- Language: Python 3.12
- Framework: FastAPI
- Database: PostgreSQL with SQLAlchemy
- Migrations: Alembic
- Testing: pytest
- Linting: ruff
- Type checking: mypy

## Commands

- Run: `uvicorn app.main:app --reload`
- Test: `pytest`
- Lint: `ruff check .`
- Format: `ruff format .`
- Type check: `mypy app/`
- Migrate: `alembic upgrade head`
- New migration: `alembic revision --autogenerate -m "description"`

## Project Structure

- `app/`
  - `main.py` — FastAPI app entry point
  - `routers/` — API route handlers
  - `models/` — SQLAlchemy database models
  - `schemas/` — Pydantic request/response schemas
  - `services/` — Business logic
  - `database.py` — Database connection
- `tests/` — pytest test files
- `alembic/` — Database migrations

## Rules

- Always use type hints for function parameters and return values
- Use Pydantic models for all request/response data
- Use dependency injection for database sessions
- Never use raw SQL — always use SQLAlchemy ORM
- Write docstrings for all public functions
- Every router must have corresponding tests
- Use async/await for all database operations

Template: TypeScript / Next.js Project

# Project Overview

A SaaS dashboard for analytics.
Built with Next.js 15, TypeScript, and Tailwind CSS.

## Tech Stack

- Language: TypeScript (strict mode)
- Framework: Next.js 15 (App Router)
- Styling: Tailwind CSS
- Database: Prisma + PostgreSQL
- Auth: NextAuth.js
- Testing: Vitest + Testing Library

## Commands

- Dev: `npm run dev`
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`
- DB push: `npx prisma db push`
- DB studio: `npx prisma studio`

## Project Structure

- `src/app/` — Next.js App Router pages
- `src/components/` — Reusable React components
- `src/components/ui/` — Base UI components (buttons, inputs)
- `src/lib/` — Utility functions and helpers
- `src/server/` — Server-side logic and API
- `prisma/` — Database schema and migrations

## Rules

- Use server components by default, client components only when needed
- Never use `any` type — always define proper interfaces
- Use Tailwind classes, never inline styles
- Keep components under 100 lines — extract if longer
- Use server actions for mutations, not API routes
- All database queries go through Prisma

AGENTS.md — The Emerging Standard

AGENTS.md is a newer format designed for AI coding agents. While CLAUDE.md is read by Claude Code automatically, AGENTS.md is a community-driven convention that is gaining adoption. Other tools use their own formats too — Cursor uses .cursorrules and some tools use .clinerules. The concept is the same: a file that tells the AI how to work with your project.

Note: Not every agent reads AGENTS.md automatically yet. Check your tool’s documentation. The format and ideas below apply regardless of the filename.

How AGENTS.md Differs from CLAUDE.md

CLAUDE.mdAGENTS.md
Read byClaude CodeAny agent (Codex, Copilot, custom agents)
FocusProject info + rulesAgent behavior + workflow instructions
StandardAnthropic conventionCommunity standard (growing adoption)
Use together?Yes — they complement each other

AGENTS.md Template

# Agent Instructions

## Behavior

- Always run tests after making changes
- Never modify files outside the project directory
- Ask for confirmation before deleting files
- Follow the existing code style — match surrounding code

## Workflow

1. Read the relevant files before making changes
2. Plan the changes before writing code
3. Make changes in small, focused steps
4. Run the linter after every change
5. Run tests after every change
6. Commit with descriptive messages

## Restrictions

- Do not modify the database schema without explicit approval
- Do not change public API endpoints without approval
- Do not add new dependencies without listing them first
- Do not use deprecated APIs or functions

## Code Quality

- Keep functions under 30 lines
- Keep files under 300 lines
- No commented-out code
- No TODO comments without a linked issue
- Every public function needs a docstring
- Error handling is required for all external calls

## Testing

- Every new function needs at least one test
- Every bug fix needs a regression test
- Use meaningful test names: `test_should_return_error_when_input_is_empty`
- Mock external services, never call real APIs in tests

Best Practices for Context Files

1. Be Specific, Not Vague

# BAD — too vague
Use clean architecture.

# GOOD — specific and actionable
Use 3-layer architecture:
- UI layer: Compose screens + ViewModels
- Domain layer: Use cases (one per business action)
- Data layer: Repositories + data sources
ViewModels only depend on use cases, never on repositories directly.

2. Include the Build Commands

This saves the most time. Without build commands, the agent has to figure out how to build your project by reading config files:

## Commands
- Build: `./gradlew build`
- Test: `./gradlew test`

3. List What NOT to Do

Negative rules are as important as positive ones:

## Do NOT
- Do not use LiveData (we migrated to StateFlow)
- Do not create new XML layouts (we use Compose only)
- Do not add suspend functions to DAO interfaces (use Flow)
- Do not put business logic in Composables

4. Keep It Under 200 Lines

The AI reads the entire file on every session. If your CLAUDE.md is 500 lines, you are wasting context window space. Keep it focused:

  • Project overview: 3-5 lines
  • Tech stack: 5-10 lines
  • Commands: 5-10 lines
  • Structure: 10-15 lines
  • Rules: 10-20 lines

5. Update It When Things Change

If you add a new dependency, change the architecture, or adopt a new convention — update the context file. An outdated CLAUDE.md is worse than no CLAUDE.md because it gives the agent wrong information.

6. Use Nested Context Files

For large projects, you can put additional context files in subdirectories:

my-project/
├── CLAUDE.md              ← project-level context
├── backend/
│   └── CLAUDE.md          ← backend-specific rules
├── frontend/
│   └── CLAUDE.md          ← frontend-specific rules
└── mobile/
    └── CLAUDE.md          ← mobile-specific rules

Claude Code reads all of them and combines the context. This keeps each file small and focused.

Common Mistakes

Mistake 1: No Context File at All

The most common mistake. You spend 5 minutes writing a CLAUDE.md and save hours every week.

Mistake 2: Too Much Detail

# BAD — agent doesn't need a history lesson
This project was started in 2023 by our team of 5 developers.
We originally used Java but migrated to Kotlin in 2024.
The previous architecture was MVP but we switched to MVI because...

# GOOD — just the current state
Language: Kotlin
Architecture: MVI
UI: Jetpack Compose

Mistake 3: Forgetting Build Commands

Without commands, the agent guesses. It might run npm test in a Gradle project.

Mistake 4: Not Specifying What to Avoid

If you migrated from LiveData to StateFlow but didn’t tell the agent, it will use LiveData because older patterns appear more frequently in training data.

Quick Reference: What Goes Where

InformationCLAUDE.mdAGENTS.md
Project overviewYesOptional
Tech stackYesOptional
Build commandsYesOptional
Folder structureYesNo
Coding rulesYesYes
Agent behaviorNoYes
Agent workflowNoYes
RestrictionsOptionalYes
Testing rulesOptionalYes

Simplest approach: Start with just CLAUDE.md. Add AGENTS.md when you use multiple agents or need workflow-specific instructions.

Start Now — 5 Minute Setup

  1. Create a CLAUDE.md file in your project root
  2. Copy the template that matches your tech stack from above
  3. Fill in your project name, commands, and folder structure
  4. Add 5-10 rules specific to your project
  5. Run claude and see the difference

That is it. Five minutes of setup. Hours saved every week.

Pro tip: At the start of each session, ask the AI “Summarize the rules from CLAUDE.md” to verify it read and understood your context file correctly.

Frequently Asked Questions

Do I need both CLAUDE.md and AGENTS.md?

No. Start with just CLAUDE.md if you use Claude Code. Add AGENTS.md only if you use multiple agents or need workflow-specific instructions that don’t fit in CLAUDE.md.

What about .cursorrules?

Cursor uses its own format called .cursorrules. The structure and ideas are the same as CLAUDE.md — describe your project, tech stack, and rules. Just use the filename your tool expects.

Does CLAUDE.md work with other AI tools?

CLAUDE.md is automatically read by Claude Code. Other tools won’t read it automatically, but you can paste its contents into their context or instructions. The content is useful regardless of the tool.

How long should the file be?

Under 200 lines. The AI reads it every session, so keep it focused. If you need more detail, use nested CLAUDE.md files in subdirectories.