Context engineering: stop explaining your project to Claude every time

Context is more than a prompt

A prompt is only the current instruction.

Context is everything the model currently has access to when making decisions:

current instruction
+ earlier conversation
+ project instructions
+ files read
+ command results
+ tool call results
+ documentation

This leads to an important shift in thinking.

We no longer ask only:

How do I write a better prompt?

We ask:

How do I make sure Claude has the right information at the right moment?

This is context engineering.

CLAUDE.md: README for a collaborator, not a dump for prompts

The simplest upgrade is CLAUDE.md.

Example:

# Architecture

- Business logic belongs in services.
- HTTP handlers only validate input and map responses.
- Database access goes through repositories.

# Verification

Run:

make test
make lint
make verify

Schema changes additionally require:

make test-integration

# Rules

- Never modify generated files manually.
- Every schema change requires a migration.
- Do not make production changes without explicit approval.

The point is not to paste everything you know about the project into that file.

CLAUDE.md should mostly contain information that is:

• frequently needed,
• stable,
• important for many tasks,
• costly when omitted.

If you have 300 lines describing one subsystem, it probably should not be loaded into every task.

The repository is also part of context engineering

A good repository for a developer is often also good for an agent.

Compare:

"To run tests, enter packages/api,
load .env.dev, start the database container,
then run..."

with:

make test

The more deterministic the basic entrypoints are, the less the agent has to guess.

It is worth having explicit commands such as:

make dev
make test
make lint
make verify

or their equivalents in package.json, taskfile, justfile or whatever tool the project uses.

This is not preparing a repository "for AI".

It is simply good developer experience that the agent can also use.

Claude should not have everything in the context window

The natural reaction after discovering CLAUDE.md is adding more things to it.

After a few weeks you can end up with:

CLAUDE.md
-> architecture
-> conventions
-> API documentation
-> deployment history
-> 15 runbooks
-> description of every module
-> every edge case

That is the wrong direction.

The context window is a resource.

A large amount of low-relevance information makes it harder to find what matters for the current task.

It is better to think in layers:

CLAUDE.md
= knowledge needed often

repo
= source of truth about code

docs/
= detailed knowledge to find when needed

current instruction
= goal of the current task

tool results
= dynamic information gathered during work

Search and retrieval are part of the puzzle

If Claude needs to learn how a particular module works, you often do not need any special RAG system.

It can use:

• grep,
• glob,
• symbol search,
• git history,
• repository search.

For code, exact search is often better than semantic search.

The question:

Where is PaymentService used?

is a natural candidate for grep or symbol search.

There is no reason to immediately build a vector DB.

When does RAG start making sense?

The problem appears when knowledge lives outside the code or there is a lot of it:

• ADRs,
• wiki,
• runbooks,
• earlier incidents,
• platform documentation,
• tickets,
• project decisions.

Then you need a mechanism:

large body of knowledge
|
v
search / retrieval
|
v
most relevant fragments
|
v
Claude context

This is the general idea of RAG: retrieval-augmented generation.

You do not have to start with embeddings.

In practice, retrieval can combine:

• full-text search,
• metadata filtering,
• semantic/vector search,
• reranking.

The pattern matters more than the specific technology:

Do not put everything into context. Give the agent the ability to fetch information when it is needed.

In the next article, we will go one step further and let Claude use systems outside the repository as well.

What does this change in SDLC?

Feature implementation

Claude starts by:

1. reading CLAUDE.md,
2. finding similar code,
3. learning the relevant tests,
4. making the change,
5. running the defined verification.

You do not have to list these steps every time.

Review

A reviewer can learn:

• conventions,
• security constraints,
• Definition of Done,

without having them explained again in the prompt.

Debugging

Claude can find:

• the implementation location,
• tests,
• git history,
• subsystem documentation.

Context becomes part of the repository and environment, not a one-off developer message.

Implement this today

1. Open a few recent conversations with Claude

Find instructions that repeated more than once.

For example:

• how tests are run,
• what the architecture looks like,
• what should not be changed,
• what the Definition of Done is.

2. Create or simplify CLAUDE.md

Start with at most a dozen truly important rules.

Do not create an encyclopedia.

3. Standardize basic entrypoints

Claude should be able to easily run:

test
lint
verify

without reconstructing the procedure from README.

4. Separate "always" knowledge from "sometimes" knowledge

CLAUDE.md:

• general rules.

Documentation:

• details of specific subsystems.

Repository search:

• knowledge that comes directly from the code.

5. Repeat the previous task in a fresh session

Do not do onboarding.

Check whether Claude can correctly discover the way of working using only the repository and CLAUDE.md.

Level complete

The level is complete if you can open a fresh Claude Code session and assign a typical task without explaining again:

• architecture,
• basic conventions,
• testing approach,
• Definition of Done.

At the next level we stop manually providing Claude with information from GitHub, CI, documentation and other systems used in the SDLC.

Materials

• Give Claude context: CLAUDE.md and better prompts
• Steering Claude Code: CLAUDE.md, skills, hooks, subagents and more
• Claude Code power user tips