I let an AI agent build without context. It made a mess.

The problem

I wanted the agent to move fast.

So I opened the project and wrote the kind of prompt most of us write when we are excited:

Build the landing page and make it look good.

The agent did build something. That was the problem.

It picked its own structure. It invented copy. It added patterns I did not ask for. A few parts looked nice, but the project already felt less like mine. When I asked for a small change, it touched too many files again.

That is the first trap with AI coding agents: if you do not give them a map, they draw one while driving.

What I tried first

My first fix was to make the prompt longer.

I added more detail. I explained the audience. I listed the sections. I said “keep it simple” and “do not over-engineer it.” The output improved a little, but the same issue came back in a different shape.

The agent still had no stable memory.

Every new run was like hiring a new developer who had never seen the repo before. I was putting project history into a chat box, hoping the agent would keep it all straight.

It did not.

The fix

I stopped treating context like a prompt and started treating it like project infrastructure.

The setup became six small files:

1. project-overview.md explains what the project is and who it is for.
2. architecture.md explains the stack, folders, and rules that should not change.
3. code-standards.md explains how code should be written.
4. ai-workflow-rules.md explains how the agent should behave in the repo.
5. ui-context.md explains the visual system.
6. progress-tracker.md explains what is done, what is in progress, and what is next.

Nothing fancy. Just enough memory to stop the agent from guessing.

Then the prompt changed from “build the landing page” to this:

Read the project context files first. Then implement Unit 03 only. Do not touch files outside the spec. Run the build when done.

That one sentence works because the repo now has something for the agent to read.

The happy path

The agent became more predictable.

Not perfect. Predictable.

It knew the site was static. It knew not to add a database. It knew where content lived. It knew the styling pattern. It knew that one unit meant one unit, not a full redesign because it felt inspired.

That changed the work from “please surprise me” to “please finish this bounded task.”

That is the difference between vibe coding and agentic development.

The small checklist

Before I let an agent code now, I ask:

• Does the repo explain what this product is?
• Does the repo explain what not to change?
• Is there a small spec for this task?
• Can the agent verify the result with one command?
• Will I be able to review the diff without getting lost?

If the answer is no, I do not need a better model yet. I need better context.

Questions people ask

Why not just paste the context into the prompt?

You can, and it works for small one-off tasks. But a repo grows. A git-backed context system gives every agent run the same starting point. It also gives humans a place to update the rules when the project changes.

How long should the context files be?

Short enough that someone will actually read them. The goal is not to document every thought. The goal is to remove the guesses that keep breaking the project.

What should I write first?

Start with the project overview and architecture. Those two files stop most wrong turns. Add code standards and workflow rules when the project begins to repeat patterns.

The lesson

The agent was not trying to make a mess. It was filling empty space.

Once the project had context, the agent had less empty space to fill. That is the boring fix, and it works.