Before the Coding Agent: Build the Project Context First

When I start a new coding project with AI, Codex usually isn't the first agent I speak to.

Quite often, the first step is much less formal. I might be out walking, headphones in, talking an idea through with ChatGPT.

At that stage I am not trying to produce a technical specification. I am trying to get the idea out of my own head.

What am I actually trying to build? What could be difficult? Which parts am I unsure about? Is the whole idea even sensible?

Only once those questions start to settle do I want a coding agent anywhere near the code.

Use chat as the messy planning space

My normal workflow moves gradually from conversation into implementation.

The first chat can be loose. If the idea survives that, I'll usually come back to it at my desk and start taking it more seriously.

This is where I explore the areas I don't understand particularly well.

I don't come from a programming background, so there will often be questions around architecture, file structure, technology choices or how different parts of a system should fit together. For a website, I might also start working through the design direction and rough structure of the site.

The important thing is that none of this needs to be clean yet.

A planning conversation is a good place for uncertainty because you can change your mind without having to undo any code.

Starting implementation before you have resolved the important questions can feel quicker, but I think it is usually a false economy. You end up burning tokens building something and then burning more pulling it apart again.

You also get the considerably less enjoyable job of trying to stitch everything back together once you realise the original direction was wrong.

Give the project some structure before you build it

Once the plan is reasonably settled, I like to create the first .md files before asking Codex to build anything substantial.

For me, that normally starts with something like:

• PROJECT-OVERVIEW.md
• AGENTS.md

The exact filenames are less important than what they achieve.

The project overview gives the agent the wider picture: what the project is, where it is heading, the broad structure and, where relevant, the design direction.

The agent guidance covers the rules of the road: standards, guardrails, things it should preserve and expectations about how it should work inside the repository.

I think of these files a bit like the formwork around concrete.

Before you pour the concrete, you put something in place to give it shape. Otherwise you just end up with a pile of concrete.

The .md files are not the building, and they should not try to contain every detail of it. They simply provide enough structure that when the coding agent starts producing the real implementation, it has something to build within.

Your planning chat can know more than your coding agent

One distinction I have found useful is that the planning conversation and the repository do not need to contain the same amount of information.

My ChatGPT conversation might know a great deal about where I eventually want the project to go.

Codex doesn't necessarily need all of that yet.

If I were building an online shop, for example, decisions about payments and security may affect how the site needs to be built and therefore belong in the technical context.

A future social-media marketing plan probably doesn't.

This sounds obvious, but it matters because it is easy to confuse more context with better context.

Modern models can deal with a lot of information, and they are getting better at finding what matters within it.

But why create the noise?

Give the coding agent what helps it make better decisions about the work it is actually doing.

Then keep the first coding task focused

Once that initial structure exists, I can open the project in VS Code and give Codex its first real task.

This connects directly with iteration discipline.

The immediate prompt does not need to explain the entire project again because the wider context already exists in the repository.

Instead, the prompt can concentrate on what I want done now.

The agent can see the destination without being asked to build all of it in one push.

That separation is useful:

Planning chat: explore the wider problem.

Repository guidance: preserve the important project context.

Coding prompt: define the current piece of work.

Each has a different job.

The documentation needs to move with the project

There is one fairly big catch with this approach.

Those .md files can become stale.

I have had projects where the work moved on but the guidance did not. The current prompt was effectively telling the coding agent one thing while an old project file was still telling it something else.

From my own experience, the agent seemed to perform markedly better once those files were brought back up to date.

I can't prove exactly how much of the improvement came from that change, but the conflicting context certainly wasn't helping.

A sensible habit is to treat documentation maintenance as part of moving between project phases.

If phase one is effectively complete and you are about to move into a substantially different area, review the core .md files.

What is now true?

What is no longer relevant?

What decisions have become established?

What should the agent know for the next phase?

This does not have to become another large documentation exercise. Your planning chat has probably followed most of those decisions already. It can help you review the existing files and bring them into line with where the project actually is.

Add documentation when it earns its place

I don't think a new project needs ten source-of-truth files before a line of code exists.

Start with enough structure for the work in front of you.

If a project later develops a substantial content system, data model, design system or another area that genuinely needs its own persistent guidance, give it a dedicated file then.

That is very different from documenting every future possibility on day one.

The aim is not to create a beautifully documented empty repository.

It is to give the coding agent enough reliable context to do good work, while keeping the project understandable as it grows.

For me, the workflow is fairly simple:

Talk it through → resolve the important unknowns → put the useful decisions into the repo → give the coding agent a focused task → update the guidance as the project evolves.

The coding agent still does the coding.

I just prefer to put the formwork up before we start pouring concrete.