Everything Is Context

Why I'm writing this

I build with coding agents pretty much every day now, for client work and for my own side projects. A big part of my work is also internal dev tooling and platforms: getting a team of devs, sometimes a whole org, to work the same way. So I care less about one person's clever prompt and more about what still holds up when a whole team is using it.

Somewhere along the way I realized most of what I know isn't about prompting at all. It's about everything around the prompt.

So this is a series. A way to distill what I've learned into the new disciplines of AI engineering:

• Context engineering => what the model sees, and when
• Harness engineering => the tools, permissions and automation between you and the model
• Loop engineering => making every round of work improve the next one

We start with context, because everything else sits on top of it. And the core idea is simple.

An agent only knows what's in its context window, and that window resets every session. If it matters, it goes on disk.

Working with agents is a loop optimization problem

Here's what people miss. A project with an agent isn't one long conversation. It's a loop: you brief it, it works, you review, the session ends. Then the next session starts from almost nothing.

The quality of every loop comes down to what the agent starts with. Cold start => it re-asks questions you already answered, re-proposes designs you already killed, and slowly drifts off the plan.

Most people try to fix this by writing a better prompt each time. That improves one loop. What you actually want is every loop leaving better context behind for the next one. That compounds.

So before better models, fancier harnesses or multi-agent anything, get a context framework: a habit, and a place, for what the agent should know when it wakes up. That's the first level of improving your agents over time.

Everything is context, so store it on disk

The file system is the memory abstraction. Agents already live in files: they read them, grep them, edit them, diff them. Instruction files like CLAUDE.md and file-based memory tools are all this same idea.

And everything is context. Not just the code, but the plans, the decisions, the assumptions, and where things stand:

Assumptions are the sleeper here. When an agent hands you something confidently wrong, more often than not there's an assumption underneath that nobody wrote down, yours or the model's.

Written down, you can check it. Unwritten, it's a landmine.

Start tracking: three levels

You don't need tooling to start. You need the habit. Then you automate the parts you keep forgetting.

1. L1

   Just remind it. Before you close a session: “Update STATUS.md, log the decisions we made, list the assumptions we're relying on.” Costs nothing. The catch is it depends on you remembering.

2. L2

   Make it a skill. Package that ritual into a skill or command (say /wrap-up) that knows your file layout and format. Now it's the same every session, every project, every teammate.

3. L3

   Hooks. Hooks fire on events: a commit, a session ending, the context getting compacted. The harness nudges the agent for you, e.g. every commit prompts it to log the decision behind the change.

My rule: run level 1 for a week. Whatever you keep repeating => skill. Whatever you still forget => hook.

Every level moves a bit more of the remembering out of your head and into the system. That's pretty much the pattern for this whole series.

Markdown for agents, HTML for humans

Same knowledge, two renderings. One the agent works from, one you think with.

Markdown is for the agent. Cheap on tokens, diffable, greppable, lives in the repo next to the code.

But you're still the reviewer, the guide, the final authority on the project. And you can't review what you can't hold in your head. A folder of markdown files doesn't fit in your head. A rendered page does: a plan with a diagram, a timeline of decisions, a status dashboard.

So get both. Markdown stays the source of truth, and the agent generates the HTML view from it whenever you need to understand or present the project. Don't edit the HTML directly or the two drift.

Better mental model => better collaboration => you become a better guide for your agent. Which brings me to the horse.

The rider and the horse

The fact of the matter is a frontier model is an alien mind with a ridiculous amount of raw intelligence. In its lane, it outruns you the way a horse outruns its rider. Nobody rides a horse because they think they could run faster.

But a horse left alone doesn't go where you want. It wanders, it grazes, it takes the easy way home. Agents do the same. They go aimlessly or lazily: drift from the plan, stub the hard test, call it done early.

The rider's job isn't to run. It's direction, pace, and knowing when to pull up. The mapping holds up pretty well:

• The horsemodelRaw power.
• The tackharnessSome of it you touch: chat, commands, approvals. Some of it is circuitry underneath that you rarely see: tools, permissions, hooks, what context gets loaded.
• The rideryouIntent, judgment, the final call.
• The map in the saddlebagcontext on diskWhat tells the horse where it's been and where it's going.
• Riding lessonsloop engineeringGetting better every ride.

Where the analogy breaks is actually the point of this post. A horse remembers the trail home. A model doesn't. Every session it wakes up on a trail it's never seen, so you carry the map.

And good riders learn to read their horse: when it's about to spook, when it's coasting, when to loosen the reins. That's the next post.

Try it this week

Pick one repo where you work with an agent:

• Create STATUS.md and a decisions/ folder.
• End every session by asking the agent to update both, plus any assumptions.
• On Friday, read what piled up. Then notice how much faster Monday starts.