Context engineering for solo developers

A few months ago I asked Claude to tighten up an error path in the billing webhook handler. Claude wrote a clean patch, submitted it, and walked off into the sunset. A week later I realised the patch had silently undone a retry behaviour I had spent half a day adding in the previous sprint. The original fix was correct for the problem in front of it. It was wrong for the problem I had solved the week before, which Claude had no way of knowing about.

That was the tax I paid for sloppy context. The prompt itself was fine; the problem was that the knowledge the model needed to answer well was scattered across four places, none of which the model could see.

Context engineering, in one paragraph

The term comes from a Tobi Lütke tweet in 2025 that Andrej Karpathy then amplified and sharpened into its widely-cited form: "context engineering is the delicate art and science of filling the context window with just the right information for the next step." The distinction is a useful one. Prompt engineering is the craft of how you ask a model a question; context engineering is the craft of curating what the model knows when you ask. Prompting is the top of the iceberg, and context is the rest of it: system instructions, relevant files, prior decisions, project conventions, examples of good output, the current state of the thing you are working on.

A model with a mediocre prompt and rich context will outperform a model with a polished prompt and no context, almost every time. The skill is less about wordsmithing and more about running an information supply chain well.

Most of the writing on context engineering is aimed at enterprise teams: retrieval pipelines, vector stores, embedding strategies, evaluation harnesses, production-grade context management. That writing is fine, and if you are at a company with a dedicated platform team it probably applies to you. It does not apply to me, and it probably does not apply to you if you are reading this.

The audience nobody is writing for

If you are a solo developer or part of a two-person team, you are the context engineering team. There is no platform group building retrieval infra for your side project, and there is no ontology committee. There is you, a laptop, a rotating cast of AI models, and whatever notes you have not forgotten to write down.

This is the audience the current writing on context engineering mostly ignores, and it is also the audience that needs the discipline most, because we have the least slack. A big team can absorb a day of an engineer redoing work because the context was bad, and a solo dev cannot. Every hour spent relitigating a decision you already made is an hour not spent on the next decision.

The other awkward truth: without a team, your project context lives almost entirely in your head. Nobody else is repeating your architecture decisions in standups, and nobody else is typing up ADRs so they can onboard a new hire. You are the only source of truth, which means your AI agents have no source of truth except what you remember to tell them in the current session. And you will forget.

Three layers a solo dev has to maintain

I have come to think of a solo dev's context work as three layers. They compound on each other, and most failures come from neglecting one of them.

The version with no tooling, honestly

Here is what context engineering looks like for most solo devs right now, including me before I got serious about it.

You have a README that was accurate six months ago. You have a notes folder with a handful of markdown files, three of which are dated and contradict each other. You have a TODO.md you stopped updating when the list got embarrassing. You have twelve Claude threads from the last month, each containing some combination of insight and wrong turn, none of them searchable in any serious way. You have your own memory, which is excellent on the projects you worked on this week and unreliable on anything older.

When you start a new AI session, you paste a few files into the context, describe the problem from memory, and hope. Sometimes the agent does great work, and sometimes it does confident wrong work because you forgot to mention the thing that would have changed the answer. You correct it, you move on, and you do not write down the correction, because you are in the middle of shipping.

This is not a moral failing; it is the default. The tools do not make writing things down easy, and the reward for doing it is delayed and diffuse. Most solo devs are operating this way, and most of them would be substantially more effective if they were not.

What deliberate practice actually looks like

The habits that make the difference, in my experience, are less exciting than any tool.

Write decisions down as you make them, not after.

The instinct is to wait until the decision is "final," but by then you have forgotten the alternatives you rejected and why. A short note written in the moment ("picked X over Y because Y does not handle the null case") is worth more than a polished ADR written three weeks later that smooths over the messy parts. I still catch myself telling Claude I will "clean this up properly later," which is the lie that kills the whole practice.

Be specific about the problem statement.

Most bad agent output traces back to a fuzzy problem. If you cannot write down in two sentences what success looks like, the model cannot infer it, and the fault sits with you. Forcing yourself to write the problem statement before you open a Claude tab catches maybe a third of bad ideas before they cost anything, which is a better hit rate than most linters.

Let the agents write back.

This is the habit that took me longest to internalise. Your context store is not a read-only briefing you prepare for the model; it is a shared workspace. If the agent finds something surprising, makes a decision on your behalf, or tries an approach that fails, it should be able to record that so the next agent (or the next you) benefits. A write-only-by-humans system wastes most of what your models know, and once you let the agents write back you stop feeling like the secretary for your own project.

How I ended up with Workunit

I built Workunit partly because I was tired of losing context between models. My workflow involves Codex for UI, Claude for code and copy, and Gemini for analysis, and all three need the same project context while none of them can see each other's conversations.

Workunit is my attempt at a shared workspace they can all read and write to, with the three layers above baked in: a workunit has a problem statement and success criteria (persistent context), it has typed context atoms that record decisions with their justifications and supersede earlier atoms when decisions change, and it has tasks with status (active state). The MCP server exposes all of this to any model that speaks MCP. When I pick up a workunit with Claude, it sees what Codex did yesterday. When I switch to Gemini, it sees both.

I am not going to pretend this is the only way to solve the problem; plenty of people do fine with a disciplined docs folder and good commit hygiene. The point is less the tool and more the shape of the solution: one place, structured, writable by agents, and durable across sessions. But none of that matters until the habit comes first. Context engineering at our scale is mostly a discipline problem and partly a tooling problem, in that order, and the best tool in the world will not save you if you do not write your decisions down. Build the habit, and the tooling question answers itself.