Context Engineering: Why AI Coding Sessions Quietly Fail

The Day I Stopped Blaming the Prompt

For weeks, I thought I just needed a better prompt. I would ask my AI coding tool to add a new DEX adapter, and it would hand back something that looked plausible: imports that did not exist in the workspace, account orderings borrowed from a different protocol, and a math expression vaguely resembling the constant product formula but missing the fee adjustment that this particular venue uses. I would tweak the wording. I would rewrite the request as a story. I would beg, in plain English, for it to read the file first. The output got prettier. It did not get more correct.

The shift happened the morning I gave it almost no prompt at all — three words, basically — but pointed it at a small, hand-picked bundle of files, an architecture note, and a list of constraints I had been keeping in my head. The result was not just better. It was the kind of better that made me realize I had been holding the steering wheel from the wrong side of the car. The work I had been doing on the prompt was not where the leverage was. The leverage was in everything else the model saw.

From Prompt Engineering to Context Engineering

There is a useful reframe going around the industry right now, and once I saw it I could not unsee it. The Anthropic engineering blog puts the shift bluntly in Effective Context Engineering for AI Agents: building with language models, they argue, is becoming "less about finding the right words and phrases for your prompts, and more about answering the broader question of 'what configuration of context is most likely to generate our model's desired behavior?'" That single sentence reorganized my mental model of what I was actually doing when I sat down to code with an AI.

Andrej Karpathy, formerly Tesla's director of AI, frames the same idea with an analogy I keep coming back to in The AI Corner's Context Engineering Guide 2026: the model is the CPU, the context window is RAM, and you, the developer, are the operating system. Your job is to load the right pages into RAM at the right moment. If you stuff the address space with junk, the CPU does not care how clever your instructions are. It is computing on whatever is in memory.

Thoughtworks engineer Bharani Subramaniam, writing on martinfowler.com, strips it down even further: context engineering is "curating what the model sees so that you get a better result." Curating, not prompting. Curating, not engineering some magic sentence that unlocks the model's hidden brilliance. The brilliance was always conditional on what was in the room.

This is the shift I had been refusing to make. I had been treating the prompt as the artifact and the rest of the conversation as noise. The reality is closer to the opposite. The prompt is a finger pointing at the moon; the moon is the rest of the context.

Why a Context-Blind Model Sounds Smart and Acts Dumb

Once you understand why this matters, the failures stop feeling random. They start feeling like physics.

Attention is not free

The Anthropic engineering post linked above describes the underlying mechanism cleanly. Transformers compute pairwise attention across every token in the context window. That is an n-squared relationship. As context grows, the attention budget gets diluted across more and more token pairs. Capability does not vanish off a cliff — it leaks out as a gradient. The model still sounds confident. It just has less and less of any particular piece of information left to lean on.

This is exactly the failure mode I was hitting. The AI would produce code that read like the work of someone who had skimmed the whole codebase and remembered the vibe of it but not the specifics. That is essentially what was happening. With too much in the window and no real curation, every detail got a thin smear of attention and none of them got the focus they needed.

Lost in the middle

There is a related effect that I think every developer working with AI tools should internalize. Faros.ai's writeup on context engineering for developers cites Stanford and UC Berkeley research showing that model accuracy starts to fall off around the 32,000-token mark, and — more painfully — that models pay strongest attention to information at the beginning and end of the window. Anything you cram into the middle becomes a marsh of half-heard signals. Faros reports a specific case where teams moved coding standard rules from the middle of the context to the beginning and watched code style violations drop by 35 to 40 percent. Same model. Same rules. Different placement.

Let that sink in. The rules were already in the context. The model was already reading them. They just happened to be in the part of the window where attention falls apart. Move them three paragraphs up the page and a problem that looked like a model capability issue turned out to be a seating chart issue.

Instruction capacity is finite

HumanLayer's engineering blog on writing a good project instruction file lays out a number that has stuck with me ever since I read it: a frontier model can reliably follow somewhere in the neighborhood of 150 to 200 distinct instructions. That sounds like a lot until you start counting. The system prompt for an industrial AI coding tool burns through dozens of those slots before you have typed a character. The project context file inherits the rest. Once you have spent your instruction budget, additional rules do not become more rules. They become noise that crowds out the rules you actually care about.

This is the part that made me throw away my first attempt at a project instruction file. I had treated it like a wishlist. I was paying for that wishlist in attention every single session.

Capability degrades long before the window fills

My intuition had been that as long as I was nowhere near the model's maximum context size, I had headroom. That intuition was wrong. Multiple practitioners report that quality starts dropping when the window is only 20 to 40 percent full, well before any technical limit. The number you pay attention to is not the spec sheet ceiling. It is the point where signal-to-noise quietly tips.

The Instruction File as an Onboarding Doc

One mental model finally made the project instruction file click for me. Think of it as the onboarding document the new hire reads on their first morning at the company — except the new hire is the AI, and every session is the first morning. There is no break room conversation. There is no peer who saw the same architecture meeting last week. The model walks in cold, every single time, and the only orientation it gets is whatever you wrote down.

When you frame it that way, the questions you ask about that file change. You stop asking "what would be cool to put in here" and start asking "what would I want a sharp new engineer to know about this codebase before they touch a single line."

The answers cluster into three buckets — what the EclipseSource blog on mastering project context files calls a WHY / WHAT / HOW framework. WHY is the purpose: what this project is for, what each major component does, what success looks like. WHAT is the inventory: the tech stack, the structure of the repo, where to find what. HOW is the operational layer: the actual commands to build the thing, run the tests, ship the code. Most of the bad instruction files I have written, including my own first attempt, were heavy on WHAT and almost empty on WHY and HOW.

The Google Cloud engineering blog post from Kari Loftesness and Jason Davenport (Five Best Practices for Using AI Coding Tools) describes a team practice I have stolen wholesale. At the end of each working day during a sprint, the team stores the day's key learnings in the project context file and instructs the AI to read it first the next morning. The file becomes a living artifact, like a chef's mise en place: when you walk into the kitchen, your stations are already set.

And there is one statistic from the EclipseSource piece that stopped me cold. They compare an auto-generated project context file at 280 lines against a hand-refined one at 85 lines. The shorter file outperformed. A practitioner they cite said his success rate jumped to roughly 90 percent — that AI coding had gone from a lottery to a predictable, high-value tool. Eighty-five lines, doing more work than 280. That is not a function of how much you write. That is a function of how much of what you write the model is actually given the budget to absorb.

Five Moves That Actually Move the Needle

Having messed this up enough times, the moves that consistently work for me have collapsed down to five. None of them are clever. All of them require discipline I did not know I needed.

Select, do not dump

The instinct, when an AI gets something wrong, is to give it more. More files. More documentation. More background. The instinct is almost always wrong. The Anthropic engineering team describes what they call a just-in-time approach: keep lightweight pointers like file paths and queries in the agent's working memory, and let the agent pull in detail through tools when it actually needs that detail. Their description of how this works in their own AI coding tool is straightforward — a high-level project context file is provided up front, and the agent explores deeper via grep and glob when a question requires more.

Addy Osmani, who leads developer relations for Google Chrome, writes in his Medium post about his LLM coding workflow going into 2026 about using tools like gitingest or repo2txt to bundle portions of a codebase into text and then selectively choose only what the current task needs. The verb is selectively. Not "feed it the whole repo and hope." Whole-repo dumping is the AI equivalent of handing someone a binder of every meeting note ever taken at the company and asking them to fix a bug.

Put the important stuff at the top

This is the cheapest, highest-return change I have ever made to how I work with AI tools. Core rules first. Available tools second. General context third. Recent changes after that. The specific task you are asking about, last. The Faros.ai 35–40 percent style-violation drop comes from this single change. If I get nothing else right on a given day, I make sure the things I cannot afford to have ignored are not buried in the middle of the page.

Compress, do not regenerate

Long sessions accumulate sediment. Old debug output, dead branches the conversation already abandoned, large data structures that have already served their purpose. The Anthropic blog calls the remedy compaction: when you start hitting limits, summarize what matters — architectural decisions, open questions, what has been tried and ruled out — and restart with that summary as your new baseline. Throw away the rest.

There is real data behind this. Kubiya.ai's writeup on context engineering for reliable AI agents cites an October 2025 paper from Stanford and SambaNova called ACE, which reports that incremental, structured context updates reduced drift and latency by up to 86 percent compared with either static prompts or full regeneration. That is not a marginal improvement. That is the difference between a tool that gets worse the longer you use it and a tool that holds its sharpness across a full afternoon.

Split the work across separate brains

For anything genuinely complex — and most of my MEV work qualifies — the move that has been making the biggest difference is splitting the task across separate, specialized contexts. One agent investigates account layouts. Another reads pool math. Another reviews the diff. Each one returns a compact summary, typically a thousand to two thousand tokens of the part that mattered, and the main thread does the synthesis. This is the same idea the Anthropic blog describes for sub-agent isolation: detailed retrieval gets done somewhere else, in a clean window, and only the conclusion crosses back. The main context never has to host the full investigation. It just has to consume the headline.

The mental shift is from one model trying to hold everything to a small team of models each holding one thing well. Like a NASCAR pit crew: nobody changes all four tires. Each role is specialized, and the lap time comes from the choreography, not from any one heroic move.

Format matters more than it should

This one annoys me because it feels superficial, but it is empirically real. How you format information changes how the model handles it. Markdown headers help. Code blocks help. Excessive emphasis hurts. ALL-CAPS injunctions and language like "YOU MUST" turn out to be counterproductive in practice — Faros.ai describes them as triggering an overreaction that degrades output quality, the AI equivalent of someone who can't focus when you yell at them. The strongest project context files I have read look less like a contract and more like a well-written README: confident, structured, but quiet.

What I've Started Refusing to Include

The more interesting list, honestly, is what I have started leaving out. HumanLayer's piece on writing a good project instruction file enumerates anti-patterns that map almost perfectly onto mistakes I made personally.

Linting and formatting rules do not belong in there. Deterministic tools handle deterministic problems better than language models do. Spending precious instruction slots on "use single quotes" is paying steak prices for a vending machine job. Let a code formatter handle code formatting.

Embedded full documents through @-style file references look like a free way to inject a manual into every session. They are not free. The whole document gets pulled in every time, eating attention you wanted reserved for the actual task. Two or three of these and your effective context is dominated by reference material that may not be relevant to today's work.

Inline code snippets rot. The repo moves; the snippet does not. Within a couple of weeks the example in the instruction file disagrees with the codebase, and now the AI has a confidently stated falsehood as a guide. Pointing at the file and the line where the canonical version lives is almost always better than pasting the canonical version into a doc that no one will remember to keep updated.

One-off task instructions are the easiest trap. You start writing "oh and for today's work, do X." That instruction now sits in every future session, slowly nudging the model in a direction that no longer applies. A project instruction file is for things that are universally true. Today's specifics belong in today's prompt or today's spec.

What tends to remain after this pruning is short. Surprisingly short. HumanLayer's own file, the post mentions, runs under sixty lines. The recommendation across multiple sources is to stay under roughly three hundred. The EclipseSource case I keep returning to has the hand-refined version at eighty-five lines outperforming the auto-generated one at nearly three hundred. The discipline is not in what you can fit in. It is in what you have the nerve to leave out.

Spec-Driven Coding, in Small Bites

A second layer of context lives outside the instruction file: the per-task setup.

Addy Osmani's workflow, which I have largely adopted, opens any non-trivial change with a spec.md. Requirements, architecture sketch, data model, testing strategy. He quotes the developer Les Orchard's description of this approach as "waterfall in fifteen minutes," which captures something important — you are not running a six-month BDUF process, you are doing the same thinking front-loading, compressed into a quick exercise that produces a document the AI can read. Then the spec gets broken into an implementation plan: small milestones, sequenced prompts, explicit gates.

The Google Cloud engineering team adds a wrinkle that I now build in by default: instruct the AI to request approval at each milestone. Not because the model cannot keep going. Because I need to stay in the loop. The discipline of a milestone gate keeps me from the failure mode where the AI hands me 800 lines of code that look fine, build clean, and contain three architectural decisions I never explicitly endorsed.

The other piece of this is task size. Osmani is emphatic about it. Implement one function at a time. Asking for a large monolithic output produces, in his words, a "jumbled mess." The same point appears in the Google Cloud post about migrations: do one service, not the whole portfolio at once. "Scope management is everything" is not just good engineering advice. It is the user-facing manifestation of the attention-dilution problem from earlier in this article. A big task is a context-hungry task. A context-hungry task starves itself.

There is one more thing the literature is unanimous about: examples beat descriptions. An examples/ directory full of canonical patterns will outperform a paragraph trying to describe the patterns in prose, every single time. EclipseSource describes this as "particularly crucial." The few-shot guideline is to lean on "diverse, canonical examples" rather than trying to cover every edge case. Two great examples teach a model more than fifteen mediocre ones.

The Numbers That Should Make Every Developer Pause

If you want one number to keep in your pocket as a sanity check, the AI Engineering Report 2026, as summarized by Faros.ai, is worth dwelling on. Seventy-five percent of engineers using AI tools see no measurable improvement in performance. Throughput goes up; so do bugs, incidents, and rework. The net is roughly flat.

That is not a story about model quality. The models are fine. The models are arguably more capable than most of us know how to use. It is a story about context, scope, and verification. "Vague prompts plus no context" produces, as more than one source frames it, plausible-but-wrong code that passes review and breaks production. The cost of getting context wrong is not just a worse session. It is real defects in real systems.

The inverse number is just as striking. The EclipseSource practitioner reporting a ninety-percent success rate did not switch models. He switched practices. He fixed his context.

What This Means for the Bot

For an MEV project — and Solana MEV in particular, where one bad account-ordering choice or one stale assumption about a pool's fee structure cooks an entire arbitrage path — the implications hit hard.

First, the project's instruction file is now treated like part of the code. It gets reviewed. It gets edited when assumptions change. It does not accumulate sediment. When I find myself writing the same correction into a prompt three sessions in a row, that correction belongs in the file, not in my muscle memory.

Second, the spec.md habit has stopped me from building a class of bugs I used to ship constantly: the subtle, downstream-only failures that come from an AI silently filling in a design decision I never thought through. If I cannot write the spec in fifteen minutes, the task is not well-enough understood to start coding, with or without an AI in the loop. That is true whether the next twenty minutes are spent typing by hand or watching a model do it for me.

Third — and this one took the longest to learn — I no longer treat the AI as a junior dev I can hand things off to. I treat it as a confidently wrong entity, in the framing Osmani borrows from developer Simon Willison. The phrase sounds harsh until you realize it is just describing the failure mode honestly. The model will produce something. The something will sound right. Whether it is right is a question the model cannot reliably answer, no matter how well I prompt it. The verification has to come from me. The commits — to borrow Osmani's framing — are save points in a game, made deliberately, never larger than what I can explain in plain English. "Don't commit code you can't explain" is the rule that closes the loop on all of this.

The Anthropic engineering blog on its own internal practice notes that, by their accounting, roughly ninety percent of the code in their own AI coding tool's codebase is written by that tool. That number is easy to misread. It does not mean ninety percent of the thinking has been outsourced. The thinking is in the context. The thinking is in the spec, in the instruction file, in the curated set of files, in the structured plan, in the small, reviewable increments. The model handles the typing. The engineer is still doing the engineering.

Key Takeaways

• The shift from prompt engineering to context engineering reframes the problem. The leverage is in what the model sees, not in how cleverly you ask. Curate the context first, then worry about the prompt.
• Models have real limits — pairwise attention dilutes as context grows, information in the middle of the window gets lost, and instruction-following capacity tops out around 150 to 200 distinct rules. Quality starts degrading well before the technical context limit, often around 20 to 40 percent full.
• A project instruction file works best when treated as an onboarding document the AI reads every morning. WHY, WHAT, HOW. Under roughly 300 lines is the rule of thumb; under 100 lines is often enough. EclipseSource's case study of an 85-line hand-refined file beating a 280-line auto-generated one is a useful gut check.
• Five repeatable moves cover most of the gain: select don't dump, put critical content at the top, compress instead of regenerate, split complex work across specialized sub-agents, and respect format — Markdown structure helps, ALL-CAPS shouting hurts.
• Spec-driven, small-increment work with explicit milestone gates is where the headline statistics — 86 percent reduction in drift and latency from incremental structured updates, 90 percent reported success rate after context cleanup, 35 to 40 percent fewer style violations from a single placement change — all originate. The model is doing what it has always been able to do. The job is to set the conditions where doing it goes well.