Don’t Plan It, Document It

The latest AI models are remarkably capable; but they’re not perfect. So how do you use AI for coding without letting it go off the rails?

First, let’s get a few things out of the way. I do not use AI to write my articles for me. I do use AI for coding – but as a collaborator, not as a “vibe coder”. I personally review and understand every line of code deployed to production. Is it perfect? No. But it is a massive time-saver and accelerator.

I use GPT-5.6 extensively for both work and personal coding projects. When I first started (not that long ago – yes I’m a late adopter) I was told to use Plan mode for any non-trivial coding task. That helped a lot because it allowed me to review the changes the AI intended to make before it wasted a lot of tokens building something I didn’t want.

I rarely use Plan mode anymore. Instead, before writing the first line of code, I create a file.

In my repositories, I have a docs folder. Under that, I create a folder for the feature, containing one or more Markdown files. For example:

feature-name.md
design.md
implementation.md
deployment.md

For a relatively simple feature, I might use just one file containing all the details. For more complex features, I’ll use two or more Markdown files.

I start with the feature title, a summary, and whatever ideas I already have in my head. I then ask the AI to read the file and flesh out the details. It has access to the entire repository, including the schema, source code, and APEX applications; so it can design and plan the feature with direct reference to the existing codebase.

The document(s) grow over time, gaining whatever sections the AI or I think are needed, such as:

• Summary
• Requirements
• Current State
• Scope
• Design
• Project Plan
• Technical Implementation
• Open Questions
• … whatever else …

This starts a tight review-and-update loop. I read the changes made to the design doc, ask and answer questions, make adjustments, and commit the documents to the repository in stages. This makes it easy to see what changes the AI is making and revert them if it badly off track.

At any stage I can ask the AI to review the specification:

"is this spec clear, no ambiguities, gaps, or hand-waving"
"are we ready for implementation"

I can also switch to a different model or level of reasoning whenever I need to. A higher-reasoning AI is great for doing a sanity check. The document provides all the context it needs.

One advantage of this approach is that avoids the chat history problem. Long conversations involving design decisions, experiments, discarded ideas, and changes of direction can sometimes lead the AI accidentally down the wrong rabbit hole.

The document is a living specification, but it also serves as a definitive source of truth for the feature. At any point, I can start a new chat and get a fresh perspective without losing the important design decisions that have already been made.

The document also becomes a coordination tool during implementation. I ask the AI to update it with the current status of the feature, the stage we’re at, what has been deployed to development so far, and what the intended next step should be. In many cases, the implementation can proceed without interruption from start to finish. If it gets interrupted (e.g. because I’ve run out of credits) it’s easy to recover later.

In the repository root I have the AGENTS.md file containing instructions such as:

- Store feature artifacts in a folder under `docs`, named after the feature. Create the feature folder if it does not exist.
- If a feature design document does not exist, create one inside the feature folder.

After the feature is complete, I’ll typically keep its documentation. Later, if bugs or further changes arise, those documents provide valuable history and context for the AI, including the design decisions made in the past.

I’m not suggesting this approach is revolutionary or original. It’s just something that works for me, because it provides just the right level of rigour and continuity I need, without any layers of bureaucracy or unnecessary overhead.

Plan mode is wonderful. However, for serious development in collaboration with AI, design documents offer so many benefits that I can’t imagine working without them.