How to Write an AI-Ready PRD That Doesn't Suck

Let me share a quick story. A few weeks ago, I started building a user management dashboard for my sister. I was in a rush, so I did not write any specifications. I just opened my AI editor and asked: "Create a data grid using Kendo UI in Angular to display a list of users."

At first, it was perfect. By Wednesday, the basic grid was live, the mock data was set up, and it looked great. I was happy, and while the first feature was being validated, I moved on to a different feature.

But two weeks later, my sister came back. She wanted a new business rule: before a user can see the "Delete" button in the grid, the system must check if their role is "Admin", and we must save the grid filter state in the URL.

I opened my AI editor, started a new chat session, and asked it to add this logic. The result? Total chaos. The AI broke my Angular routing, used the wrong Kendo Grid directives, and ruined the working table.

Why did this happen? Simple. It teaches us that AI needs boundaries. When you open a new chat session, the AI starts from zero. It has no memory of the architecture decisions you made two weeks ago. To build stable features, we need a single source of truth. And that starts with writing an AI-ready Product Requirements Document (PRD).

Enter Spec-Driven Development

In this post, we will look at how to write an AI-ready PRD that actually works. We will base our approach on Chapters 3, 4, and 5 of the book Spec-Driven Development by Bezael Pérez. We will see how a PRD acts as the source of truth, and how to structure it using the eight sections the book recommends. Finally, we will use an agentic tool like Antigravity CLI powered by Gemini to turn that PRD into clean, working code. So, let's start by looking at our target project.

1. Quick Win: The Admin Dashboard

Before we look at the theory, let's see our target. We want our AI tool to implement a complex user management dashboard using an Angular Kendo UI Grid, complete with role-based access control (RBAC).

To build this dashboard successfully without the AI making up its own rules, we need a structured plan. Let's see how to design that spec.

2. The Spec as the Source of Truth

In traditional programming, the code is the source of truth. The documentation is secondary. In Spec-Driven Development (SDD), this relationship is reversed. The spec is the source of truth, and the code serves the spec.

A good spec must be a Living Spec. This means:

• It lives in the same repository as your code.
• It is versioned using Git.
• When the requirements change, you update the spec first, and then the AI updates the code.

Also, the spec should focus on behavior, not architecture. Instead of telling the AI: "Use RxJS BehaviorSubject for the grid state", tell it: "The grid filter state must reflect in the URL query parameters." This gives the AI the freedom to write the best technical implementation while following the business rules. But what are the steps to actually build software with AI?

3. The 7 Phases of AI Development

Before we write our spec, let's understand where it fits. Chapter 4 of the book introduces the 7 phases of writing software with AI:

1. Idea: Describe what you want in two clear sentences.
2. Research: Search for unknown APIs first.
3. Prototype: Build a quick, temporary prototype to test your ideas.
4. PRD: Write the behavior spec.
5. Kanban: Break the PRD into independent tasks.
6. Execution Loop: The AI reads the tasks and writes the code.
7. QA: Run manual or automated tests.

So far we have done the brainstorming and initial research. Now let's move to writing the actual PRD. You can skip research or prototyping if you already know the technologies. But you can never skip the PRD, the Kanban board, the execution loop, or QA. Once we are ready to write our spec, we need to follow a very specific structure.

4. The 8 Parts of an AI-Ready PRD

Now we are ready to write the PRD. Chapter 5 teaches us that a PRD must have exactly eight specific sections. No more, no less.

Here are the eight sections:

1. Problem Statement: One or two sentences explaining what is broken and why it matters.
2. Solution: A description of the destination, not the path. What must be true when the feature is done.
3. User Stories: User actions in the format: As a [role], when [action], then [expected result].
4. Constraints: Non-negotiable restrictions (for example, "Must use Angular Signals").
5. Acceptance Criteria: Verifiable checkboxes that can pass or fail.
6. Out of Scope: What explicitly does not belong in this cycle. This prevents the AI from adding extra features you did not ask for.
7. Assumptions: What you take for granted about the system (for example, "AuthService is already provided").
8. Implementation Notes: Suggestions that the AI can choose to follow or ignore.

Typing these 8 parts by hand every time takes too much effort. Fortunately, we can let an AI agent automate the writing process for us. Let's see how.

Let the AI Write It: Automating the Spec

In this guide, we will use Antigravity CLI (invoked via the agy command in your terminal) to automate the workflow. You can follow these exact principles using any other AI coding assistant.

If you are using Antigravity CLI, the process is driven by two main commands:

1. /grill-me: Starts an interactive Q&A session in your terminal. The agent asks you about user stories, constraints, and edge cases, then creates a clean 8-part PRD.
2. /goal: Tells the agent to autonomously read the spec, plan the changes, and write the code directly in your project.

Setting Up Antigravity CLI and Running /grill-me

Here is how you set up Antigravity CLI and use /grill-me to build your PRD:

Step 1: Install Antigravity CLI

Run the installation script to download and install the global agy command:

curl -fsSL https://antigravity.google/cli/install.sh | bash

Step 2: Open the Tool in Your Project

Navigate to your project folder and run the CLI:

agy

(On your first launch, this will open a browser window to authenticate with your Google account).

Step 3: Run /grill-me for Brainstorming

Start the interactive brainstorming session inside the tool. Use /grill-me along with a prompt describing what you want to build:

/grill-me "I need to build an admin user management dashboard using Angular and Kendo UI Grid. It must include Role-Based Access Control (RBAC) to hide the delete button from non-admins, and persist the filter state in the URL. Save the final PRD to specs/admin-grid-prd.md"

The agent will now ask you specific questions to flesh out the details. You answer them in plain English. For example, you can clarify the exact roles or what happens when a request fails.

Step 4: Let the Agent Write the PRD

Once the interview is finished, the agent organizes the notes and automatically writes a clean 8-part PRD file to your repository (saved as specs/admin-grid-prd.md):

Here is the exact technical PRD generated by the agent after the /grill-me session:

# PRD: Admin Data Grid with Kendo UI
 
## 1. Problem Statement
Administrators need a fast and reliable way to view and manage users, but the current system lacks advanced filtering and role protection.
 
## 2. Solution
Create an Angular component using Kendo UI Grid that displays users, supports URL state persistence, and hides sensitive actions based on the user role.
 
## 3. User Stories
- As an admin, when I view the grid, then I can see the delete button.
- As a regular user, when I view the grid, then the delete button is hidden.
 
## 4. Constraints
- Must use Angular Signals for state management.
- Grid filter state must reflect in the URL query parameters.
 
## 5. Acceptance Criteria
- [ ] Renders the Kendo UI Grid without console errors.
- [ ] Users without the Admin role cannot see the delete button.
- [ ] Refreshing the page keeps the current grid filters intact.
 
## 6. Out of Scope
- Real backend integration (use local mock data).
- Adding new user creation forms.
 
## 7. Assumptions
- AuthService is already provided in the root module.
 
## 8. Implementation Notes
- Consider using the Kendo Grid state change event to update the router URL.

With a clear spec in place, we can run /goal "Read the PRD and implement the admin grid" in the CLI. The agent will build the files and set up the basic project. Now we need an AI engine capable of reading and executing these complex technical requirements without breaking our code.

5. Introducing Gemini: Our AI Engine

Once we have a complete PRD, we need an AI engine that can execute our specification perfectly. With Antigravity CLI, we leverage Google's Gemini models as the primary execution engine.

Why is Gemini perfect for Spec-Driven Development via Antigravity?

• Massive Context Window: Gemini can read your entire codebase, styles, Angular dependencies, and the PRD at the same time. It never "forgets" architecture rules.
• Agentic Tool Calling: When run inside Antigravity CLI, Gemini does not just suggest code snippets. It can write files, install packages, and check configurations natively.
• Strict Rule Following: Gemini models are highly optimized to follow system instructions. They respect your constraints and out of scope declarations.

Since Antigravity CLI has built-in integration, there is no need to run local model servers. Now let’s see how we use this integration to bring our PRD to life.

6. Executing the PRD with Antigravity CLI

In traditional coding tutorials, this is the part where you would open your terminal, run ng generate component, and spend hours writing code line by line.

But in Spec-Driven Development, we do not do that. The AI agent does the work.

Our role as developers is to act as the architect. We write the PRD, and we hand it over to the agent. In Antigravity CLI, we do this using the /goal command. The Gemini agent reads the PRD, plans the files, runs setup commands, installs packages, and writes the code.

Inside the tool, you simply issue the goal:

/goal "Read the PRD and set up the Admin Grid project. Follow all constraints and out-of-scope sections."

Starting a new project from scratch is straightforward. But what happens when you need to update an existing project weeks later?

7. Adding Real Business Logic to Existing Code

The setup is done, the initial grid is running, and now you need to add new complex business logic to an existing project.

In traditional development, this is where the AI fails. When you return to the project two weeks later, you start a new chat session. The new AI session has no access to the design decisions you made. It starts from zero and starts guessing.

In Spec-Driven Development, we solve this by keeping our specs versioned directly in our repository. We handle this transition by following three simple rules:

Rule 1. Document the Project "Constitution"

Before adding new features, establish the technical rules of the code. You can ask Antigravity CLI to analyze your current code and generate a draft:

"/goal Read the project code and generate a draft constitution capturing the technical decisions that already exist. Save it to CONSTITUTION.md"

This creates a central document (saved as CONSTITUTION.md) capturing your tech stack, coding standards, and security constraints.

Rule 2. Document Only What You Touch

You do not need to specify the entire codebase on day one. When you need to modify a feature, write a short, clear spec of its current behavior first. For example, document how the current grid logic behaves in a specs/admin-grid.md file.

Rule 3. Write Feature-Specific Specs

Once the current state is documented, write a new spec defining the new business logic. You can reference your existing modules directly. Save this file as specs/role-validation.md in your repository. Then, run /goal to let the agent implement the change step by step without breaking the existing features.

Gemini reads the Constitution alongside the new spec, understands the exact folder structure, and writes the validation logic directly into the existing files. Let's see how we can verify the agent's work.

Verifying the Result

Once the Gemini agent completes the implementation, you can verify that everything works as expected. Since the agent took care of setting up the project, you only need to run the project locally:

Step 1: Navigate to the Project

cd admin-dashboard

Step 2: Start the Server

npm start

Step 3: Test the Dashboard

Open your browser and head to http://localhost:4200. Try logging in with a verified admin user and an unverified user to make sure the role-based access check behaves exactly as defined!

8. Key Takeaways

Writing an AI-ready PRD changes how you write software. Here are the main lessons from the book:

• The spec is the primary artifact: It lives in the repository and controls the code.
• Define behavior, not architecture: Tell the AI what must be true, not how to build it.
• Use agentic CLI tools: Tools like Antigravity CLI (agy) backed by Gemini's massive context window do the hard work of project setup.
• SDD works for existing codebases: Using a Project Constitution allows you to make safe updates to existing projects weeks or months later.

Open Challenge for You!

Now that you have a working admin grid, here is your open challenge: extend the validation logic to verify the user role from a real backend API using the new Angular httpResource API. Show an error message to the user if the server request fails.

If you want to master this workflow, I highly recommend reading Spec-Driven Development by Bezael Pérez. It is a fantastic guide that teaches you the foundations you need to build stable applications with AI without ever losing control of your code.

In the next article, we will take this PRD and break it down into small tasks that the AI can build one by one. Stay tuned!

Photo by Alvaro Reyes on Unsplash