Context Engineering for Python Codebases

Curate: Choose What Goes Into the Context

This context-engineering strategy is where you’ll spend most of your time as a Python developer. The Curate strategy is about deciding exactly what the agent should see to successfully accomplish the task in front of you. Your prompt matters, which is why prompt engineering exists, but the surrounding context matters just as much. The two work together.

The most common place to start is an instruction file. Auto-loaded files like AGENTS.md, CLAUDE.md, Cursor rules, or Copilot instructions get pulled into every turn, so they’re the right home for project-wide conventions.

A short, focused AGENTS.md for a Python service might look like this:

- Python version: 3.14. Don't assume newer syntax than that.
- Dependency manager: `uv`. Never use `pip`.
- Tests: `uv run pytest -q`. Add a test for every new function.
- Lint and format: `ruff check` and `ruff format`.
- Type checking: `mypy --strict`. Type-hint all public functions.
- Use Google-style docstrings.
- Don't add new dependencies without asking.

A short AGENTS.md is plenty. Long instruction files can become a context-bloat problem, and the agent tends to ignore any single rule when there are thirty of them.

Beyond instruction files, a few more curation tactics are worth applying:

• Just-in-time file loading: Let the agent search and open files as it needs them with tools like grep, glob, and file readers, instead of dumping the whole repo into the prompt up front. The agent’s own searches pull in only the relevant slice.

• Skills: A skill is a description of a workflow that the agent loads only when relevant for a given task. Skills keep the window light when most tasks don’t need all the skills. For example, a refactor skill loads only when the agent detects a refactoring task in your prompt.

• Retrieval-augmented generation (RAG): For docs, knowledge bases, and large codebases, you can use RAG to pull only the chunks that match the query instead of concatenating entire documents.

• MCP servers: Each connected MCP server drops its tool catalog, including names, descriptions, and schemas, into the window up front. Deliberately pick the servers to use in the current project. Connecting all of them bloats the catalog and makes the agent worse at picking the right tool for the task.

If you want to see these tactics applied in a real session, Real Python’s Getting Started With Claude Code video course walks through setting up a CLAUDE.md file and shipping a project from start to finish.

As you already know, the context window has limited space, so fill it for the task at hand, not for every possible task.

Distill: Shrink What’s Already in the Window

Long conversations may cover many different topics and fill the context window with both useful and irrelevant information.

The Distill strategy allows you to shrink or trim what’s already in the context so your rules and the relevant decisions don’t get crowded out. You don’t have to wait until you’re at the cap to clean the context window.

Here’s what to reach for when you notice the window is getting cluttered and the agent is losing track of the important details:

• Summarize on demand: Replace a long back-and-forth with a short recap of decisions and open work. Agents do this automatically when the window fills, but with today’s long context windows, quality degrades well before that point. Trigger compaction yourself at natural break points like finishing a sub-task or switching files. Use Claude Code’s /compact, Cursor’s /compress, or a similar command with a custom prompt for what to keep.

• Drop old or unneeded tool output: Big tool results like full file dumps, long search results, and verbose tracebacks take up a lot of space and rarely need to be re-read. Ask the agent to summarize or drop earlier tool outputs before pruning the conversation itself.

• Trim turns that no longer matter: When you’ve moved on to a new feature or switched to a bug fix, older turns about the previous work mostly add noise. Trim them to free up room for more relevant information.

• Rewind to an earlier turn: Some agents let you jump back and continue from a previous point in the conversation. For example, in Claude Code, you can press Esc twice to open the rewind menu. That’s useful when the recent few turns went sideways and you want to drop them without restarting the whole conversation.

During compaction, the agent itself summarizes the conversation and continues with that summary. Think of every distill technique as a smaller, cheaper compaction you trigger yourself, before you need the expensive one.

Sometimes it’s also necessary to completely restart the context, which you can do with /clear or a similar command, depending on the tool you’re using.

When the agent is lost, the conversation has gone off the rails, or you’re switching to an unrelated task, a fresh start is the way to go. Make sure to save any important information to disk first, since it won’t survive the restart. Check out the Externalize strategy for instructions on how to do this.

Delegate: Split Work Across Separate Context Windows

Sometimes the right approach is to use more than one context window instead of trying to fit everything into just one.

The Delegate strategy consists of assigning a focused task to a subagent with its own clean context window. The subagent works through the task, loads whatever context it needs, and returns a short summary to the main agent. The main window stays lean, and the subagent’s exploration never has to compete for attention with your top-level conversation.

Here are a few common paths that you can follow when delegating to subagents:

• Subagents for focused tasks: A main agent delegates a job like “Write the test file for users.py” or “Audit this module for typing gaps” to a subagent. The subagent reads the relevant files, does the work, and returns a concise result. The main agent doesn’t have to see the subagent’s intermediate work, just the final answer.

• Wrappers around noisy tools: When a tool returns more data than the main agent needs, hand the call to a subagent. The subagent processes the response and returns only the relevant slice. This is useful for long file dumps, database queries, raw browser HTML, and similar.

• Sandboxed code execution: Run code in an isolated sandbox so only the result enters the agent’s window. Intermediate state, prints, and full tracebacks never reach the main context.

If your agent supports subagents, pick one big chunk of your next task and delegate it. For example, you could trigger a subagent for a task like “Read the codebase and summarize the authentication flow.” The main agent then gets a paragraph instead of five hundred lines of source code.

Externalize: Save Context the Agent Can Read Later

The Externalize strategy puts information outside the context window in files that the agent can read on demand. The agent only loads what it needs, when it needs it. This strategy is especially useful for long-running work that requires multiple sessions, since the context you save to disk survives compactions and restarts.

The following actions cover most of what you’ll do here:

• Plan files: A plan.md file (or similar) on disk survives compaction and fresh sessions. The agent can re-read it on demand to refresh its memory about what you’re working on.

• Notes and scratchpads: The agent jots down decisions, open questions, or a file inventory as it works. A fresh session can pick up where the last one left off by reading the notes back in.

• Persistent memory: Some agents auto-capture running facts about your project across sessions, like preferred libraries or tricky setup steps. Cursor calls this Memories, separate from its rules. Claude Code calls it auto memory and stores it in a MEMORY.md file, separate from CLAUDE.md. If your agent has no built-in memory, then use a custom file.

The smallest possible version of this strategy is a one-sentence prompt:

Write a short plan for this task into plan.md before you start,
and then update plan.md after each step.

That’s it! The plan will live on your disk, get versioned with your repo, and survive any number of compactions or sessions.

For longer-running work, treat the scratchpad like a structured note-taking system. Group sections by Decisions, Open Questions, and Next Steps, like in this small example:

## Decisions

- Validate email syntax with a regex.
- Verify the domain via DNS.

## Open Questions

Should `validate_email()` live in `users.py` or move to `validators.py`?

## Next Steps

- Add tests for the email validator.
- Work the validator into the `User` class.

This structure makes it easier for the agent to re-read selectively instead of dragging the whole file back in.