CLAUDE.md Is Not Documentation. It Is How Your Repository Teaches AI to Work.

Real Python’s tutorial gets the mechanics right. The more interesting story is that CLAUDE.md is not merely a configuration file—it is the beginning of a repo-level operating model for AI-assisted engineerin

CLAUDE.md Is Not Documentation. It Is How Your Repository Teaches AI to Work.

Claude Code can read thousands of files, trace dependencies, write tests, refactor services, and implement entire features.

But it still does not automatically know how your team wants software delivered.

It does not know that your organization uses uv instead of pip.

It does not know which test command must run before a task is considered complete.

It does not know that migration files must never be edited directly, that a certain service owns a particular business rule, or that your team prefers the smallest possible change over a sweeping refactor.

Claude can inspect the repository.

It cannot reliably infer the operating model behind it.

That is where CLAUDE.md becomes important.

Real Python recently published an excellent practical guide by Ben Batman explaining how to create global, project-level, and local CLAUDE.md files for Python projects. The tutorial covers the mechanics clearly: observe Claude’s mistakes, convert recurring corrections into targeted instructions, keep the files small, and place each rule at the correct level.

But there is a larger enterprise lesson hiding underneath the tutorial:

CLAUDE.md is one of the first places where a software repository begins teaching an AI agent how work is supposed to happen.

That makes it much more than documentation.

It is executable engineering context.

Your Repository Has Code, but Does It Have Instructions?

Traditional repositories contain plenty of technical evidence:

• Source code

• Tests

• Configuration

• Build files

• Deployment manifests

• Architecture diagrams

• Pull-request history

• Jira references

• README files

An experienced developer can study those artifacts and eventually understand how the system works.

An AI coding agent can do the same thing—only much faster.

But neither the developer nor the agent can always determine the team’s intent from code alone.

A repository may reveal that several test commands exist. It may not reveal which one must run before submitting a pull request.

It may show three patterns for error handling. It may not reveal which pattern is current and which two are legacy.

It may contain multiple deployment scripts. It may not explain which one is safe for production.

It may have a technically valid implementation that violates an architectural decision made six months earlier.

The code tells the agent what exists.

CLAUDE.md begins telling the agent how to behave.

Stop Writing Rules Before You Observe the Mistakes

One of the strongest recommendations in the Real Python article is also one of the most frequently ignored:

Do not begin by writing a massive list of everything you believe Claude should know.

Begin by watching it work.

Give Claude Code a small, realistic task. Observe where it makes an incorrect assumption, takes an unnecessarily broad path, skips a required validation, or follows a technically valid pattern that does not match your project.

Then capture the correction.

For example:

Claude’s behavior

Repository instruction

Installs dependencies using pip install

Add project dependencies using uv add

Finishes without running tests

Run uv run pytest before completing a task

Adds temporary print() statements

Use the configured application logger

Refactors unrelated code

Modify only the files required for the requested change

Opens large portions of the repository immediately

Use targeted searches before reading broad source trees

Introduces a new architectural pattern

Match existing project patterns unless a change is explicitly requested

This is a far better model than filling CLAUDE.md with generic programming advice.

Claude already knows Python.

What Claude does not know is where your repository is unusual, constrained, inconsistent, politically sensitive, operationally dangerous, or simply different.

That is what belongs in the file.

Think of CLAUDE.md as a Correction Ledger

The best CLAUDE.md files are built from evidence.

Every important instruction should answer a simple question:

What mistake, wasted action, or undesirable outcome is this rule preventing?

If no one can answer that question, the instruction may not belong there.

This turns CLAUDE.md into a living correction ledger.

Claude makes a repeatable mistake.

The team corrects it.

The correction becomes repository context.

Future Claude sessions inherit the lesson.

Over time, the repository becomes easier for AI agents—and often humans—to operate safely.

This is where the productivity gain begins to compound. The team is no longer paying repeatedly for the same correction.

The repository remembers.

The Three Layers of CLAUDE.md

A useful implementation separates instructions by scope.

1. Global Instructions: How You Prefer to Work

The global file normally lives at:

~/.claude/CLAUDE.md

This is where you place preferences that should apply across most repositories.

Examples include:

# Global Claude Code Instructions

## Working Style

- State important assumptions before editing.

- Prefer the smallest change that satisfies the request.

- Do not refactor unrelated code.

- Modify only files necessary for the task.

- Turn the request into verifiable goals before implementation.

## Context Management

- Search for relevant symbols before opening large files.

- Read only the necessary files and line ranges.

- Review all changes with git diff.

- Avoid loading broad repository context unnecessarily.

## Delivery

- Run the narrowest relevant validation before finishing.

- Explain any validation that could not be completed.

- Call out significant trade-offs or risks.

The global file defines your personal baseline.

It should not contain rules that only make sense for one application, framework, or customer.

2. Project Instructions: How This Repository Works

The project-level CLAUDE.md belongs in the repository and should normally be committed to version control.

This is where the real engineering value appears.

A strong project file might include:

# Project Engineering Instructions

## Build and Validation

- Install dependencies with `uv sync`.

- Run the application with `uv run python -m app`.

- Run unit tests with `uv run pytest`.

- Run a single test with `uv run pytest path/to/test.py::test_name`.

- Run Ruff before completing Python changes.

## Architecture

- Business rules belong in the domain layer.

- API handlers must not access the database directly.

- Repositories own persistence logic.

- Do not create new cross-service dependencies without approval.

## Change Boundaries

- Never edit generated migration files manually.

- Do not rename public API fields without updating the contract tests.

- Preserve backward compatibility unless the intent explicitly authorizes a breaking change.

## Completion Criteria

- Relevant tests pass.

- No unrelated files are modified.

- Public functions include type hints.

- New behavior includes appropriate test coverage.

This file should answer the questions a capable engineer would ask before safely changing the repository.

It does not need to explain every folder.

It does not need to summarize the entire codebase.

It does not need to repeat obvious Python conventions.

Claude can discover those things.

The file should concentrate on what cannot be safely or efficiently inferred.

3. Local Instructions: What Is True on This Machine

Some instructions should not be shared with the entire team.

That is the purpose of:

CLAUDE.local.md

This file can contain:

• Local service URLs

• Machine-specific commands

• Personal testing preferences

• Temporary development constraints

• Local database names

• Worktree-specific notes

It should usually be added to .gitignore.

For example:

# Local Development Notes

- Use http://localhost:8088 for the local mock service.

- Use the development AWS profile named sandbox-dev.

- During local debugging, print the raw Bedrock response to stdout.

The local file allows individual developers to adapt Claude Code without polluting the shared repository instructions.

But it must be used carefully. Claude Code combines instructions as context; it is not a deterministic rules engine. Contradictory instructions can create ambiguous behavior.

A local exception should therefore be intentional, narrow, and temporary whenever possible.

Large CLAUDE.md Files Can Make Claude Worse

The natural enterprise instinct is to keep adding more.

More standards.

More architecture.

More documentation.

More security requirements.

More coding conventions.

More examples.

Eventually, the organization creates a 2,000-line CLAUDE.md and wonders why Claude becomes slower, more expensive, and less predictable.

Every instruction consumes context.

Every repeated paragraph competes for attention.

Every contradiction introduces uncertainty.

Every irrelevant standard distracts the agent from the current intent.

The goal is not to tell Claude everything.

The goal is to tell Claude the small number of things that materially change its behavior.

Real Python emphasizes trimming auto-generated files, removing redundant content, and keeping instructions targeted. That aligns with a fundamental principle of intent-driven engineering:

Context should be introduced at the moment and scope where it becomes relevant.

Rules that apply constantly belong in CLAUDE.md.

Specialized workflows may belong in skills.

Path-specific rules may belong under .claude/rules/.

Task-specific requirements belong in the current intent or feature file.

Enterprise policy may belong in managed organizational instructions.

Do not force one file to carry the entire operating model.

CLAUDE.md Is Context, Not Enforcement

This distinction matters.

CLAUDE.md guides Claude.

It does not guarantee compliance.

A sentence such as:

- Make sure everything works.

is weak because it is subjective and unverifiable.

A stronger instruction is:

- Before completing a backend change, run `uv run pytest tests/backend`.

The second instruction names an action and creates observable evidence.

For anything that must be enforced, pair AI instructions with deterministic controls:

• CI pipelines

• Branch protections

• Linters

• Static analysis

• Security scanning

• Contract tests

• Policy checks

• Required reviewers

• Deployment gates

The agent receives the intent.

The pipeline verifies the result.

That combination is far more dependable than either one alone.

The File Should Evolve With the Repository

A CLAUDE.md file should never be treated as finished.

As the system evolves, some rules will become obsolete.

Claude models will improve.

Old architectural patterns will disappear.

Commands will change.

Tests will move.

New tools will become standard.

The team should regularly prune instructions that no longer prevent real mistakes.

A useful maintenance cycle is simple:

1. Observe a repeated failure or correction.

2. Identify the correct scope.

3. Add one precise instruction.

4. Run another realistic task.

5. Confirm that the instruction changes behavior.

6. Remove or revise rules that no longer provide value.

This makes the file an engineering artifact rather than a documentation dumping ground.

It is versioned.

It is reviewed.

It is tested through use.

It improves as the team learns.

From Python Tutorial to Enterprise Operating Model

The Real Python article focuses appropriately on Python projects, with examples involving uv, testing, logging, AWS Bedrock, global and local instructions, and Claude Code’s /memory command.

But the pattern extends far beyond Python.

A Node.js repository may specify:

- Use pnpm, not npm or yarn.

- Run `pnpm test` and `pnpm lint` before completing changes.

- Do not place business logic inside Express route handlers.

A Spring Boot repository may specify:

- Use constructor injection.

- Keep controllers thin.

- Do not access repositories outside the service layer.

- Run the targeted Maven test suite before completing changes.

A Kubernetes repository may specify:

- Never modify production values directly.

- Validate Helm templates before opening a pull request.

- Do not change resource limits without documenting the operational reason.

An enterprise integration repository may specify:

- Preserve canonical event schemas.

- Do not create point-to-point integrations.

- All retry behavior must be idempotent.

- Changes to external contracts require compatibility validation.

The language changes.

The operating principle does not.

Every repository needs a concise way to communicate:

• How work begins

• What boundaries must be respected

• Which commands matter

• What evidence proves completion

• What the agent must never assume

• What the team has already learned the hard way

CLAUDE.md Is the Repository’s First AI Employee Handbook

That may be the simplest way to understand it.

A new developer joining a team needs more than source code.

They need to know how the team works.

Which shortcuts are dangerous.

Which conventions matter.

Which commands are trusted.

Which architectural decisions are intentional.

Which mistakes have already been made.

An AI coding agent needs the same thing.

CLAUDE.md is not the complete answer. It does not replace intent files, architecture, automated governance, skills, hooks, agents, tests, or human judgment.

But it is one of the foundational artifacts.

It converts tribal knowledge into persistent context.

It reduces repeated correction.

It creates continuity between sessions.

It aligns the agent with the repository.

And most importantly, it begins transforming AI-assisted coding from a personal experiment into a repeatable engineering system.

Final Thought

The weakest way to use Claude Code is to open a repository and hope the model figures everything out.

The next level is to give it a large document containing everything anyone knows.

The better approach is more disciplined:

Observe the work.

Capture repeated corrections.

Place each instruction at the correct scope.

Keep the context small.

Make completion verifiable.

Allow the repository to teach the agent how engineering is done.

That is what a good CLAUDE.md file really represents.

Not documentation.

Not a prompt collection.

Not another README.

It is the beginning of an AI operating model—implemented directly inside the repository where the work happens.

Inspired by Ben Batman’s Real Python tutorial, “How to Write a CLAUDE.md File for Claude Code,” updated July 15, 2026. The original tutorial provides a detailed hands-on walkthrough for Python developers, including global, project-level, and local instruction files.

:::