When you learn to build software with an AI agent, the code arrives faster than the understanding does. You accept a suggestion, it works, you move on. Two weeks later you cannot explain why the project is structured the way it is — because you never decided it, you accepted it.
A decision log fixes that without slowing you down much.
One entry per accepted suggestion that changed structure
Not every edit. Only the ones that set a direction: the data shape, where state lives, which library got pulled in, how errors travel. Those are the choices you will have to defend or undo later.
Four fields, one or two lines each
- What the agent proposed, in your own words rather than pasted code.
- Why you accepted it — "it was the suggestion" is an honest and useful answer here.
- What you did not understand at the moment you accepted it.
- How you would notice this was wrong later.
The third field is the one that turns a log into a study plan. Collect a week of them and you have a list of exactly the gaps that are blocking you, ranked by how often they appear.
Write it before you run the code
Once the code works, the reasoning evaporates. Thirty seconds before the test run is the only moment the uncertainty is still visible to you.
Re-read the log before asking the agent a big question
Pasting two or three past entries into the conversation is far more useful than describing the project from scratch. You are handing over the constraints you already committed to, which is the context the agent cannot infer from the file tree.
Keep it in the repository
A note-taking app separates the log from the code it describes. A plain file in the repo moves with branches and shows up in diffs, so it stays honest.
I put together Japanese learning material for building real apps with AI coding agents at AI Craft Campus, and this habit is the one that separates learners who can modify their project from ones who can only regenerate it.
Top comments (0)