In short: All the leading tools now recommend the same order: specification first, code second. Claude Code has a plan mode in which it only reads and plans; Lovable has a Plan mode that writes a plan before touching code; GitHub has Spec Kit, which separates what the user needs from how to build it. A good spec for an AI tool contains scope and what is out of scope, user stories with acceptance criteria, a data model, roles and permissions, and how to verify that it works. The tools do not ask for roles and permissions, and that is exactly where vulnerabilities are born.
Why AI needs a specification more than a person does
A human developer who does not know something asks. An AI tool carries on. It picks the most likely guess and builds a screen, a table and an API on it. When the guess turns out wrong, three layers already sit on top of it.
There is also the opposite problem: the tool does exactly what it was asked to do. If the request says an orders list, it builds an orders list. If it was not written that a user must not see other people's orders, it will not be built.
A spec for an AI tool is not a longer document. It is a more explicit one. Everything a person would understand from context has to be written down.
What the tools themselves recommend
| Tool | What it recommends before the code |
|---|
| Claude Code | A plan mode in which the tool only reads and plans. For large features, the documentation suggests letting the tool interview you and write a SPEC.md file, then running the implementation in a fresh session. According to the documentation, a good spec names the files and interfaces involved, states what is out of scope, and ends with an end-to-end verification step. |
| Lovable | A Plan mode that writes a plan before any code: key decisions, assumptions, components, data model, and implementation order. It is recommended for large changes and for database design. |
| Cursor | Project rule files that the tool reads on every request: conventions, architecture, and what not to do. |
| GitHub Spec Kit | A chain of specification, plan, and tasks. The specification describes what users need and why, without referring to technology. Every ambiguity is marked, and none should remain unresolved at the end. |
| Kiro | Three files: requirements with acceptance criteria, a design with architecture and data flow, and trackable tasks |
What belongs in the specification
- What the product is and who it is for. One sentence: who the user is, what problem they have, what the main action is.
- Scope and what is out of scope. What we are building now and, just as explicitly, what we are not. Without the second list, the tool will expand the scope on its own.
- User stories with acceptance criteria. In a testable form: given a state, when the user takes an action, then the system responds like this.
- Data model. Entities, important fields, and the relationships between them. This is the part that is most expensive to change later.
- Roles and permissions. Who can see what, who can change what, and what happens when someone tries to open something that is not theirs.
- Integrations. Which external systems are involved, what passes between them, and which system is the source of each field.
- How we verify. At least one end-to-end scenario for each capability, including a user trying to do something forbidden.
The gap the tools leave
None of the tools' guides gives roles and permissions its own section in the spec. The closest is Lovable, with signed-in and signed-out states. This is not a detail: a vulnerability that lets any user read other users' data is the most common problem in apps built with AI.
So in the specifications we write, permissions are a mandatory section with a table: role, what it can see, what it can change, what is forbidden. And every forbidden row has a test scenario.
How it works in practice
- A requirements conversation: what the business needs, who the users are, and which data is involved.
- A written specification in a format the tool can read: scope, stories, data, permissions, checks.
- The tool plans from the specification, and a person reviews the plan before any code is written.
- The implementation is checked against the acceptance criteria, including the forbidden scenarios.
The specification stays alive: when a requirement changes, it changes in the spec first and in the code second. Otherwise, a month later, the spec describes a different system.
Frequently asked questions
Do you need a specification when working with Lovable or Claude Code?
Yes, even more than usual. An AI tool fills every gap with a guess and builds code on top of it. The tools themselves recommend planning before coding: Claude Code has a plan mode, and Lovable has a Plan mode.
How is a spec for an AI tool different from a regular one?
It has to be more explicit: everything a person would infer from context, such as who can see what, has to be written down. And it has to be in a format the tool can read, with testable acceptance criteria.
What is the most important part of the specification?
The data model and permissions. A wrong data model is the most expensive thing to change later, and permissions that were never written are the most common source of vulnerabilities in apps built with AI.
What is spec driven development?
An approach in which the specification is written before the code, and the plan and tasks are derived from it. GitHub Spec Kit and Kiro are built around it, and Claude Code and Lovable support it through their planning modes.
Who writes the specification, me or the tool?
Both of you. The tool can interview you and draft it, but the decisions, especially who is allowed to do what, have to be made by a person who knows the business.
Where to start
Write one sentence explaining what the product is and who it is for, then list the roles in the system and what each one is allowed to see. Every good specification starts with those two lines.
Talk to me
Related: CRM requirements and development, Architecture review, Why an architect