I spent two weeks debugging an agent that wrote mediocre client reports. The prompts were tight. The model was the best available. I rewrote the prompt four times, added examples, tried different temperatures. The output improved maybe 10%.
Then I changed what the agent could see. I gave it the client's brand guidelines, their last three months of performance data, and a two-paragraph briefing on what the client actually cared about. Same prompt. Same model. The output went from "needs heavy editing" to "send as-is."
That's AI context engineering. And it's the single most underrated skill in the operator's toolkit.
Most operators I talk to spend 90% of their time wordsmithing prompts and 10% thinking about everything else the agent receives. The operators who are actually shipping — running agents in production, saving 20+ hours a week, operating businesses at a fraction of the expected headcount — have flipped that ratio entirely.
What Is AI Context Engineering?
AI context engineering is the practice of designing what information an AI agent receives, in what format, at what point in its workflow, to maximize output quality and consistency.
It is not prompt engineering. Your prompt is the instruction — "write a client report," "analyze this listing," "draft a response to this email." Context engineering is everything the agent sees alongside that instruction: the files it can read, the tools it can use, the history it remembers, the persistent instructions that shape every interaction, the domain knowledge it draws from.
Think of it this way: a prompt is what you ask. Context is what the agent knows when you ask it. And what the agent knows determines whether you get a generic answer or a genuinely useful one.
Why Prompt Engineering Hit a Ceiling
I'm not saying prompts don't matter. They do. A clear instruction beats a vague one every time. But we've reached diminishing returns.
The difference between a good prompt and a great prompt is maybe 15% improvement in output quality. I've measured this across hundreds of agent runs. You can spend an hour perfecting the phrasing of a prompt and get marginally better results.
The difference between good context and bad context is the difference between an agent that's useful and an agent that's useless. No prompt can compensate for an agent that doesn't have the information it needs. "Write a detailed client performance report" will always produce garbage if the agent can't see the performance data, doesn't know the client's goals, and has no idea what format the client expects.
This is where I see most operators stall. They'll try Claude, ChatGPT, or whatever model is new this week, get mediocre results, and conclude that AI isn't ready for their use case. Nine times out of ten, the model was fine. The context was the problem.
The Four Layers of AI Context Engineering
Every agent interaction has four layers of context. Most operators only think about one of them. Here's the full stack.
Layer 1: System Instructions — The Agent's Operating Manual
System instructions are the persistent directives that shape every interaction with an agent. In Claude Code, this is your CLAUDE.md file. In other tools, it's the system prompt, the custom instructions, or whatever the platform calls its persistent configuration.
This is the highest-leverage context you can build. A well-structured set of system instructions means every single interaction with that agent starts from a baseline of useful context — your conventions, your constraints, your domain knowledge, your output format expectations.
I'll go deeper on the CLAUDE.md pattern below, because it's the single most important context engineering investment an operator can make.
Layer 2: Retrieved Knowledge — What the Agent Pulls at Task Time
This is dynamic context — information that gets pulled into the agent's context window at the moment it needs it. It comes from your second brain (Obsidian, Notion, whatever you use), from files in your repo, from databases, from APIs.
The key word here is pulled. Not dumped. The mistake most operators make is stuffing everything into the context window and hoping the model sorts it out. That's like handing someone a filing cabinet and asking them to write a memo. Instead, you want to retrieve only what's relevant to the specific task.
I run an agent that analyzes Amazon product listings across categories. When it analyzes a supplement listing, it pulls in supplement-specific compliance rules, top competitor data for that sub-category, and our historical performance benchmarks for supplements. When it analyzes an electronics listing, it pulls a completely different context package. Same agent, same prompt, radically different context — and radically better output because of it.
Layer 3: Tool Context — Defining What the Agent Can Do
This one surprises people: your tool descriptions are context. When you give an agent access to a tool — an MCP server, a function call, an API — the description of that tool shapes how the agent thinks and acts.
A tool described as "searches the database" will get used differently than one described as "searches the product catalog by ASIN, category, or keyword, returning title, price, BSR, and review count for the top 20 results, sorted by relevance." The second description tells the agent exactly what it can get and how to ask for it.
I've seen agents fail to use perfectly good tools simply because the tool descriptions were vague. The fix wasn't changing the prompt or changing the tool — it was rewriting three lines of tool description. That's context engineering.
Layer 4: Conversation State — What the Agent Remembers
The fourth layer is what persists across interactions. What does the agent remember from the last time you used it? What results from previous tasks does it carry forward?
In short-lived interactions (single prompts, one-off tasks), this barely matters. But for agents running production workflows — daily briefings, weekly reports, ongoing monitoring — conversation state is critical. An agent that remembers last week's metrics can flag anomalies. An agent that doesn't will just report numbers with no interpretation.
This is where context engineering meets agent memory. I've written about memory systems before, but the context engineering angle is specific: it's about what you inject from memory and when. Not everything the agent has ever seen, but the compressed, relevant subset that makes this particular task better.
The CLAUDE.md Pattern: Your Agent's Operating Manual
If you do one thing after reading this post, write a CLAUDE.md file for your most-used agent workflow. This is the single highest-ROI context engineering investment I've found.
A CLAUDE.md file is a persistent instruction set that Claude Code reads at the start of every session in a project. It's your agent's operating manual. Here's the structure I use:
# Project Identity
What this project is. Who it serves. What matters.
# Conventions
- Output format: always use [format]
- Tone: [specific voice description]
- When uncertain: ask, don't guess
# Domain Knowledge
Key facts the agent needs for every task:
- Our target CAC is under $X
- Product margin threshold is Y%
- Client reporting cadence: weekly on Mondays
# Available Tools and When to Use Them
- Use [tool A] for pricing data (always check before quoting)
- Use [tool B] for competitor analysis
- Never use [tool C] for client-facing output
# Constraints
- Never mention competitor names in client reports
- Always include data sources
- Flag any metric that moves more than 15% week-over-week
This file isn't long. Mine are usually 40-80 lines. But those 40-80 lines shape every single interaction with the agent. They prevent the same mistakes I used to correct manually. They encode the judgment calls I'd otherwise have to make in real time.
And here's the compounding effect: every time I notice the agent doing something wrong, I add a line to the CLAUDE.md. Every correction becomes permanent. After three months, my agents rarely make mistakes I've seen before. That's context engineering doing what prompt engineering never could — accumulating institutional knowledge.
AI Context Engineering That Compounds vs. Context That Burns
There are two kinds of context work. One builds an asset. The other doesn't.
Compounding context includes:
CLAUDE.mdfiles and system instructions that persist across sessions- Skill definitions — reusable, parameterized workflows your agents can execute
- Structured memory — decision logs, client preferences, performance baselines stored where agents can retrieve them
- Tool configuration — well-described MCP servers, curated tool sets per workflow
- Context templates — pre-built context packages for recurring task types (weekly report context, listing audit context, client onboarding context)
Every one of these gets better over time. You build it once, refine it as you go, and every future agent interaction benefits.
Burning context is the alternative:
- Pasting instructions into the chat window every time
- Manually assembling background information before each task
- Re-explaining conventions and constraints in every prompt
- Copy-pasting from previous outputs to give the agent history
Burning context takes the same effort every single time. No accumulation. No compounding. It's the operator equivalent of typing the same email from scratch every morning instead of using a template.
The shift from burning to compounding context is the shift from using AI as a tool to running AI as infrastructure. The first scales with your time. The second scales on its own.
Five AI Context Engineering Mistakes That Kill Agent Output
After running 30+ agents in production across four businesses, these are the context mistakes I see most — in my own work and in the operators I advise.
1. Stuffing the Context Window
More context is not better context. Every model has a finite context window, and even within that window, relevance drops as volume increases. I've tested this repeatedly: an agent with 2,000 words of highly relevant context outperforms an agent with 20,000 words of loosely relevant context on the same task.
Be surgical. What does the agent need for this specific task? Include that. Leave out everything else.
2. Using Static Context for Dynamic Tasks
A single CLAUDE.md file for every task type is a good start. A set of context configurations that match different task types is better.
When my research agent runs a competitive analysis, it gets different context than when it drafts a content brief. Same agent, different context packages. If you're using the same static context for tasks that require different knowledge, your agent is always either missing information or drowning in irrelevant information.
3. Ignoring Tool Descriptions
I said it above and I'll say it again: tool descriptions are context. If your agent has access to a tool with a one-line description, it will misuse that tool or not use it at all. Spend fifteen minutes rewriting your tool descriptions to be specific about inputs, outputs, and when to use them. The ROI on those fifteen minutes is absurd.
4. No Context Hierarchy
Not all context is equally important. Your agent needs to know that "never mention competitor names in client reports" is a hard constraint, not a suggestion. It needs to know that output format requirements outweigh stylistic preferences.
Structure your context with clear priority signals. Put constraints at the top. Put nice-to-haves at the bottom. Use clear language: "always," "never," and "must" for hard rules. "Prefer" and "try to" for soft guidance.
5. Never Updating Your Context
Context that doesn't evolve becomes stale and eventually wrong. Your business changes. Your clients' needs shift. New tools become available. If your CLAUDE.md file looks the same as it did three months ago, it's not doing its job.
I review my agent configurations every two weeks. Not a full rewrite — just a scan for anything that's outdated, any new patterns I've noticed, any mistakes that keep recurring. Fifteen minutes of context maintenance saves hours of correcting bad output.
Frequently Asked Questions About AI Context Engineering
How is context engineering different from prompt engineering?
Prompt engineering is about crafting the instruction — the specific ask you give an AI agent. Context engineering is about everything else: the background information, persistent instructions, available tools, retrieved knowledge, and conversation history that surround that instruction. A great prompt in poor context produces mediocre results. A decent prompt in excellent context produces great results.
How much context should I give an AI agent?
Only what's relevant to the current task. I aim for the minimum effective context — the smallest amount of information that produces the output quality I need. For most tasks, that's a well-structured CLAUDE.md (40-80 lines), task-specific retrieved context (500-2,000 words), and clear tool descriptions. Start lean and add context only when you identify gaps in output quality.
What's the fastest way to start with AI context engineering?
Write a CLAUDE.md file for one agent workflow you use daily. Include three sections: project identity (what this is and who it's for), conventions (output format, tone, recurring rules), and constraints (things the agent must always or never do). Use it for a week, then add lines every time you correct the agent. You'll see output quality improve within days.
Does context engineering work with every AI model?
Yes. Every language model — Claude, GPT, Gemini, Llama, whatever comes next — performs better with structured, relevant context. The specific file formats differ (CLAUDE.md is specific to Claude Code; other platforms have their own configuration patterns), but the principles are universal: give the agent the right information, in the right format, at the right time.
How does AI context engineering relate to building a second brain?
Your second brain is the storage layer — where your knowledge lives. Context engineering is the retrieval and formatting layer — how that knowledge gets into the AI agent's context window when it's needed. They're complementary systems. A second brain without context engineering is a library with no librarian. Context engineering without a second brain means you're re-creating context from scratch every time.
Three Actions to Start Context Engineering This Week
AI context engineering is the skill that separates operators who get consistent, production-quality output from everyone who's still guessing. It's not about finding the perfect prompt. It's about building the information layer that makes every prompt work better.
Here's where to start:
-
Write one CLAUDE.md file this week. Pick your most-used agent workflow. Document the identity, conventions, and constraints in 40-80 lines. Use it for a week and add a line every time you correct the agent.
-
Audit your current context. For your next three agent tasks, pause before you run them and ask: what does this agent actually see right now? What's missing? What's there but irrelevant? You'll find the gaps fast.
-
Build one compounding context asset. A skill file, a context template for a recurring task, a set of tool descriptions you can reuse. Something that makes every future interaction better without extra effort from you.
The operators who win with AI aren't the ones with the best prompts. They're the ones who built the best context. AI context engineering is how you get there.