# How to Write a Spec With an AI Coding Agent (No Code) > Not sure what you want built yet? Let the AI coding agent interview you, write a one-page spec, then check the finished work against it. A plain guide. Canonical: https://bridge-terminal.com/atlas/blog/write-spec-with-ai-coding-agent-plain-guide/ Last updated: 2026-11-04 Published 4 November 2026 · Plain English · How-to · 8 min read ## The short version - You do not need a finished spec to start: ask the AI coding agent to interview you, and it will write the spec from your answers. - A useful spec is about a page and says what done looks like, which unusual situations matter and what is out of scope. - Build from the written spec in a fresh session, so the work starts clean with a written definition of done. - Afterwards, ask a reviewer that did not write the code to check the work against the spec, and ask for evidence, not just 'all tests pass'. - Plan mode in Claude Code lets you read the agent's proposed approach before it edits anything, a cheap place to catch a misunderstanding. If you are not sure exactly what you want built, you do not have to work it all out alone before you start. You can ask an AI coding agent to interview you, turn your answers into a short written spec, and then build from that spec. This guide shows how, and how to use the spec afterwards to judge whether the work is any good. The examples use Claude Code, Anthropic's AI coding tool, because its documentation describes this routine directly. The idea works with any coding agent. ## What is a spec, and why does an AI agent need one? A spec (short for specification) is a written description of what you want: what the thing should do, what counts as finished, and what it should not do. It is not a technical document. If you can write a clear email to a colleague, you can write or review a spec. An AI coding agent can read your existing code. What it cannot read is anything that was never written down: a decision made in a meeting, a detail you forgot to mention, or how much you were hoping for. Anthropic's best-practice guide for Claude Code lists this as a common reason a session goes wrong: Claude built something different from what you had in mind because it is missing information it cannot get from reading the project. The guide also says Claude tends to read a request conservatively and build the smallest thing that satisfies it, because it cannot see how much you were hoping for. So if you only say "add a reminder email", you may get the bare minimum. The usual result of skipping the spec is not a broken product. It is a working product that is not the one you had in mind, and you find out after the money is spent. ## Can the AI agent write the spec for me? Yes, and this is often the best route when your idea is still fuzzy. Claude Code's guide suggests asking the agent to interview you. Its example request is: > I want to add rate limiting to the public API but haven't thought it through yet. Interview me until you could write the spec, then write it to SPEC.md. (Rate limiting means capping how many requests one user can make.) According to the guide, Claude comes back with multiple-choice questions about the parts you have not pinned down, such as per-user versus per-key limits, what happens to requests over the limit, and what is out of scope. It keeps asking until the answers add up to a spec. The same approach works for any feature. Say you want a customer reminder email. A good interview would ask: - Who gets the reminder, and who must not? - How many days before the due date, and can the customer change that? - What happens if the email fails to send? - Should staff be able to switch it off for one customer? - Is a text message part of this, or a later job? You answer in plain words. You do not need technical vocabulary. If you do not know an answer, say so and ask the agent to explain the options and what each would cost you in time and complexity. ## What should a good spec contain? Keep it to about a page. A spec nobody reads is worse than none. These parts earn their place: 1. **The goal in one or two sentences.** Who is this for and what problem does it solve? 2. **What done looks like.** Concrete, checkable statements. "A customer who has not paid receives one reminder three days before the due date" is checkable. "Reminders work well" is not. 3. **Edge cases that matter.** These are the unusual situations you already know about: a customer with no email address, a due date on a weekend, two invoices due on the same day. 4. **What is out of scope.** This is the most underrated part. It stops the agent, and later you, from quietly growing the job. 5. **Choices you care about.** If you prefer one reasonable approach over another, say so. The agent cannot guess a preference. 6. **How to check it.** If you can name a way to check the work, such as a test, a screen to compare against a mockup, or a sample file, write it down. If you want the fuller version of a feature rather than the smallest one, say so in the spec. The guide suggests literally telling the agent to be ambitious and listing what you mean. Its example asks for empty and error states and a working save flow, not just the layout. The guide's point is that this is a statement about scope, which only you know. ## How do I use the spec once it exists? Three steps. ### 1. Read it before anything is built Read the spec as the person who knows the business. This is where your judgment is worth the most. Look for a missing rule, a wrong assumption or something you never meant to promise. Changing a sentence now costs seconds. Changing the same thing in finished software costs a task, a review and a retest. ### 2. Ask for a plan, then read that too Claude Code has a plan mode. In plan mode the agent reads the project and writes a plan, but it does not edit your files until you approve the plan. When the plan is ready, Claude asks how to proceed. You can approve it and let the work run, approve it but check each edit yourself, or choose "No, keep planning" and tell the agent what to change. You can also open the plan in a text editor and change it directly before the agent goes ahead. For a founder, this is a low-cost checkpoint: you see the approach in words before any of it exists as code. Not every task needs this. In our view, a small, clear change such as fixing a typo on a page does not need a spec or a plan. Use the full routine for work that has several parts, touches money or customer data, or that you could not describe in one sentence. ### 3. Build from the spec in a fresh session A session is one running conversation with the agent. The guide recommends starting a fresh session once the spec file exists, so the build begins with a clean slate and a written definition of done. The conversation that produced the spec was for exploring; the build is for delivering. The spec file is also what you point the reviewer at later. ## How do I check the finished work against the spec? This is where the spec pays you back. Do not just ask the agent whether it is finished. The guide notes that Claude stops when the work looks done, so give it something that comes back pass or fail, such as a test, and ask for evidence: the command it ran and its output, or a screenshot. "All tests pass" on its own tells you very little. Then bring in a second pair of eyes. The guide shows a review request that compares the work against the spec: check that every requirement is implemented and the listed edge cases have tests, report gaps that affect correctness, and skip style. It explains why the last part matters. A reviewer asked to find problems will always find something, and if you fix every finding you end up with extra layers of code and tests for cases that cannot happen. The guide also says the reviewer is more useful when it has not seen how the code was written. Claude Code can run this kind of review in a separate helper session that never saw your conversation. Another way is to open a second session yourself, give it the spec, and carry its findings back to the first. You can also do a version of this without reading any code. Go down your "done looks like" list and ask the agent, for each line, to show you where it is done and how it was checked. ## What does Atlas do about specs today? [Atlas](https://bridge-terminal.com/atlas/) is a team of AI engineers built on Claude Code. You describe the work to PA, your project assistant, in plain words, and PA shares it out to specialists who design, build, test and security-check it. Some of the checking this guide asks for is already part of how Atlas works. Building waits for an approved architecture, a signed-off design and failing tests. Every build is reviewed as it finishes, and the review either passes it as releasable or files fix tasks to the engineer who built it. "Done" is refused until the work is on the main version of the project or queued to land there, a screen has its test cases and screenshots, and the product's rules pass. What Atlas does not do today is interview you into a spec, or check each build requirement by requirement against a spec you wrote. That is coming to Atlas, built in, so it will need no setup on your side. Until then, write your spec with the steps above, paste it into the chat with PA, and ask PA to treat it as the definition of done. ## Common mistakes - **Writing a spec that is really a wish.** "Fast and easy to use" cannot be checked. - **Leaving out-of-scope empty.** Everything not excluded is fair game. - **Treating the spec as untouchable.** If the build teaches you something, update the spec and note what changed. - **Never reading the plan.** If you skip both spec and plan, the first time you see a misunderstanding is when the work is finished. ## Conclusion A spec turns your idea into something the agent can build and you can check. You do not need to write it from nothing: let the agent interview you, trim the result to a page, read it as the person who knows the business, and build from it in a fresh session. Then judge the work against the same page, asking for evidence and for a reviewer that did not write the code. A few minutes on the spec is usually cheaper than one round of rework. ## Questions people ask ### Can an AI coding agent write a spec for me? Yes. Claude Code's guide suggests asking the agent to interview you until it could write the spec, then save it to a file. It comes back with multiple-choice questions about the parts you have not decided and keeps asking until the answers add up to a spec. ### How long should a spec for an AI coding agent be? About a page. It should hold the goal, what done looks like in checkable terms, the unusual situations that matter, what is out of scope and any choices you care about. A longer spec is less likely to be read carefully. ### Do I need a spec for every task? No. In our view a small, clear change such as fixing a typo does not need one. Use a spec and a plan for work with several parts, work touching money or customer data, or anything you cannot describe in one sentence. ### What is plan mode in Claude Code? In plan mode the agent reads the project and writes a plan but does not edit your files until you approve. You can approve it, approve it and review each edit yourself, or keep planning and tell it what to change. You can also edit the plan in a text editor first. ### How do I check the finished work matches my spec? Ask for evidence, such as the check that was run and its output or a screenshot, and have a reviewer that did not write the code compare the work to the spec. Tell it to report gaps that affect correctness and skip style. ## About Atlas: Specs and Atlas: what exists today With Atlas, PA takes your request in plain words, building waits for an approved architecture, a signed-off design and failing tests, and every build is reviewed. A spec interview and a requirement-by-requirement check against your spec are coming to Atlas, built in, with no setup. Until then, paste your spec to PA as the definition of done. — https://bridge-terminal.com/atlas/ ## Sources - [Best practices for Claude Code](https://code.claude.com/docs/en/best-practices) - [Choose a permission mode (plan mode)](https://code.claude.com/docs/en/permission-modes) - [Common workflows: plan before editing](https://code.claude.com/docs/en/common-workflows) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [Does an AI Coding Agent Share Your Code? Plain Guide](https://bridge-terminal.com/atlas/blog/does-ai-coding-agent-share-your-code-privacy/) - [How to Report a Bug to an AI Coding Agent](https://bridge-terminal.com/atlas/blog/how-to-report-a-bug-to-ai-coding-agent/) - [Can an AI Coding Agent Work Overnight? A Plain Guide](https://bridge-terminal.com/atlas/blog/can-ai-coding-agent-work-overnight-unattended/)