Context Engineering for Python Codebases

Context engineering is the practice of curating the content that goes into an AI agent’s context window. In Python projects, that may mean pinning your dependency manager in an instruction file, trimming irrelevant history, delegating heavy tasks to subagents, and more.

By the end of this tutorial, you’ll understand that:

• The context window holds everything the agent sees on a single turn, not just your latest prompt.
• Most agent failures come from bad context, not a bad model.
• Bigger context windows don’t fix poor curation—they only delay the symptoms.
• Instruction files like AGENTS.md keep your Python conventions in front of the agent.
• Curate, Distill, Delegate, and Externalize are strategies that can help you manage the agent’s context.

Modern AI coding agents, such as Claude Code, Codex CLI, Cursor, Copilot CLI, and Antigravity CLI, work with a fixed-size context window. Once you know what’s in that window and decide what belongs there for the task at hand, you’ll spend less time arguing with your agent and more time shipping quality Python code.

Take the Quiz: Test your knowledge with our interactive “Context Engineering for Python Codebases” quiz. You’ll receive a score upon completion to help you track your learning progress:

---

Interactive Quiz

Context Engineering for Python Codebases

Build a working framework to manage your AI coding agent's context window using four practical strategies for Python projects.

Prerequisites

Before you start learning about context engineering, you should already have:

• Hands-on experience with at least one AI coding agent, such as Claude Code, Codex CLI, Cursor, Copilot CLI, or Antigravity CLI.
• Comfort working from a terminal and editing plain-text configuration files like .md, .toml, or .yaml.
• A basic understanding of large language models (LLMs) and concepts like tokens, prompts, and chat history.
• Working knowledge of Python and its ecosystem.

To learn more about these and other related topics, you can check out the resources in this Real Python learning path:

Learning Path

Python Coding With AI

9 Resources ⋅ Skills: Claude Code, Cursor, Gemini CLI, AI-Assisted Development

You don’t need any prior exposure to context engineering itself. The whole point of this tutorial is to give you a working framework to effectively manage your agent’s context window.

With that distinction in mind, the next section opens up the context window so you can see exactly what’s competing for space on every turn.

Defining Context for AI Coding Agents

The context window is everything the agent sees on a single turn. Your most recent prompt is only the last item on the list. On any given turn, whenever you write a prompt and press Enter, the agent’s window typically holds the following layers of content:

1. System prompt: The agent’s built-in role and rules, typically set by the vendor.
2. Instruction files: Files like AGENTS.md, CLAUDE.md, Cursor rules, or Copilot instructions, auto-loaded into every turn. Skill descriptions also live in this layer. The agent loads a skill’s full body only when it picks the skill for the task.
3. Tool definitions: Names, short descriptions, and JSON Schema definitions for every tool the agent can call, including MCP server tools and, in some frameworks, any subagent the main agent can delegate to.
4. Opened files: Source files, configuration files, or docs the agent has read in this session.
5. Search results: Results from web searches, internal RAG queries, or file searches.
6. Conversation history: Earlier prompts, replies, and tool outputs from the same session.
7. Your new prompt: The prompt you just typed, plus any attachments.

In practice, all of this content lives inside the context window. The layers are listed separately here to clarify what’s consuming your context budget. The diagram below shows how all seven layers come together as the context window the agent reads before producing a reply:

For a more concrete example, below is a snapshot of what a single turn in a Claude Code session might look like:

[system prompt]        You are Claude Code, an interactive CLI...
[CLAUDE.md]            Use uv. Python 3.14. Run tests with uv run pytest -q.
[tool catalog]         Read, Edit, Bash, Grep, WebFetch, ...
[opened file]          src/api/users.py  (340 lines)
[history turn 1]       User: Add an email validator to the User class.
[history turn 2]       Assistant: <edits users.py>
[tool result turn 2]   Bash: uv run pytest -q -> 3 failed
[history turn 3]       User: Fix the failing tests.