Build software with
an AI coding agent.

Create a file called doc/idea-v0.md and write what you want to build as if you were explaining it to a capable friend. What it is, who it is for, why it should exist, what a good result looks like, and anything it must never do. A few paragraphs is enough.

Do not describe how it should be built, and do not ask for any code yet. The purpose of this file is to record the intent and the reason behind it, so every later step has something to refer back to.

Open the agent in the project folder and give it the prompt below. It will restate the goal, list what it is assuming and what it does not know, and ask you questions. Answer every one. “I don’t know yet” is a fine answer; it gets recorded as an open decision rather than guessed.

This step is allowed to take time. Most projects that go wrong go wrong here, long before any code exists, and a question answered now costs a sentence rather than a rebuild.

Where there is more than one sensible way to build something, you want to see the options before one gets chosen for you. This prompt asks the agent to propose several approaches with trade-offs: simple or flexible, connect to an existing system or replace it, a person approves every action or only the exceptions.

Read the options, push back, and pick one on purpose. Note which one you chose; the next prompt refers to it by name.

The chosen approach becomes a specification: what it does, what it deliberately does not do, what data it uses and who owns it, the interfaces it exposes, and the acceptance criteria that will decide whether it works.

Replace “strategy A” in the prompt with the approach you picked. When the spec comes back, read the acceptance criteria out loud. If you cannot tell whether one has been met, ask for it to be rewritten until you can.

A spec is too big to build in one go. This prompt breaks it into small, ordered tickets that can each be built, tested, and committed on their own, with dependencies and acceptance criteria per ticket. Each ticket becomes a file in doc/tickets, numbered so the order is obvious.

Skim the list. The first ticket should set up the project and prove the test setup works. If a ticket looks like it would take days, ask for it to be split.

Before any code, have the spec and tickets reviewed by specialist personas: an architect for how the pieces fit, a security engineer for access and data, and a product manager for whether this is what you actually asked for. Each returns concerns and recommendations.

Fold the ones you agree with back into the spec and tickets, and say so in the decisions file. After a big change, run the review again. A mistake caught here costs a conversation.

Now the code. The prompt tells the agent to work through the tickets in order, ask when something is unclear, run a code review after each ticket, and commit after each reviewed ticket. Tests are written first and the code is written to pass them.

After each ticket, look at what changed and, where you can, open the thing and use it. If the agent stops partway through the list, tell it to continue with the remaining tickets; that is normal on a long build.

Passing a code review is not the same as meeting the acceptance criteria. This prompt runs the full test suite, exercises the real end-to-end flows, and checks every acceptance criterion from the spec against evidence. Do not skip it because the build “looks fine”.

Release the first version, ideally to a small group first, and watch what happens. Then do the thing that makes the next build faster: rewrite the idea file with every decision folded in, as doc/idea-v2.md. The answers arrive with the questions next time instead of being rediscovered.

When you have new ideas for version two, start this guide again from step two, with idea-v2.md as the input.