Claude Code has taken the development community by storm, and it's now one of the most popular AI coding agents.

Anthropic says that as much as 90% of their code is now written with Claude Code, a statistic that was unthinkable even 12 months ago.

Why vibe-coding with AI Agents?

At Makerkit, I believe that AI Agents can help us build better SaaS faster, while we, developers, steer AI in the right direction, reviewing, understanding requirements and translating them into code.

It's a tool that empowers us to do more in less time, but that still requires us at the driving seat.

The latest improvements to Makerkit and AI Agents

One of the latest improvements we added to Makerkit is helping AI Agents provide more accurate answers and better agentic results.

We have achieved great results with the following optimizations:

• Detailed agent rules (CLAUDE.md, AGENTS.md, Cursor's files): we have added a lot of detailed rules to help AI Agents understand the codebase and the business logic
• Optimized nested rules: by splitting the rules into nested files, AI Agents use less context and only read the required rules when traversing the sub-directory tree
• MCP Server: we have added an MCP Server to the Makerkit codebase that helps AI Agents understand the codebase and work with it in a more efficient way

In this post, I want to show you the best practices to vibe-coding with Claude Code and Makerkit to build a SaaS faster, and with better results with AI Agents.

Introduction to PRDs

Product Requirements Documents (PRDs) are a great way to help AI Agents understand the requirements of a specific task, splitting the requirements into smaller, more manageable tasks, which in turn help AI Agents structure their work and understand the requirements.

Makerkit's version 2.15.0 introduced a lightweight PRD functionality that helps you create PRDs for your project, and helps AI Agents read and manage PRDs using the MCP Server.

Taskmaster AI

There are many more sophisticated tools such as Taskmaster AI; however - this tool requires no setup, it's simple to use, and a good way to get started with PRDs.

You should definitely consider graduating to these more complex and fully-featured tools as needed.

How to use PRDs with Claude Code?

First of all, you're required to set up the MCP Server for Claude Code. You can find the instructions here in the documentation.

Once the MCP Server is setup, you can start creating PRDs for your project.

Creating a PRD

From within Claude Code, you can ask it to create a PRD with your requirements. The MCP Server will tell Claude how to do that.

It needs to be emphasized: add as many details as you can. Rich details help Claude create good-quality PRDs that will be fundamental when implementing the code required to meet the requirements of the PRD.

Core Requirements

Our requirement is simple, but still complex enough to be worth a PRD:

1. Feedback Widget: We want to ask Claude to create a quick feedback tool for users to submit feedback on the app
2. Super Admin Dashboard: We want to ask Claude to create a dashboard for super-admins to manage the feedback

The Prompt to Create a PRD

We proceed by asking Claude to create a PRD with the following requirements:

Create a PRD for a user feedback widget.
All authenticated users should be able to:
- Click a button to submit feedback
- Choose a category (bug, feature request, other)
- Add a description
- Submit the feedback
- Button is visible in the bottom right corner of the page in authed pages only (no need to show it in the public pages)
- Cannot submit feedback if they're not authenticated
- Cannot perform any other action than submitting feedback
Super Admin should be able to:
- View all feedback in a simple dashboard in the Super Admin section
- Mark feedback as "new", "reviewing", or "done"
- Delete feedback
- Dispatch an email to CONTACT_EMAIL when a new feedback is submitted

The PRD Response from Claude

Claude will then create a PRD in the .prds directory. This is Claude's response:

Perfect! I've created a comprehensive PRD for the user feedback widget with the following structure:
PRD Created: user-feedback-widget.json
Key Features:
- Floating feedback button (bottom-right corner, authenticated pages only)
- Categorized feedback submission (bug, feature request, other)
- Super Admin dashboard for feedback management
- Automated email notifications to CONTACT_EMAIL
User Stories Added:
1. US001 (P0): Authenticated users can submit feedback through floating widget
2. US002 (P1): Unauthenticated users are prevented from submitting feedback
3. US003 (P0): Super Admins can view and manage all feedback in dashboard
4. US004 (P1): Super Admins receive automatic email notifications for new feedback
The PRD is now ready and includes all the requirements you specified. You can view the full PRD details or export it as markdown if needed

We create the PRD using JSON because it's the easiest way to read and write to the file system. While Markdown is the easiest to read for us humans, editing JSON files is easier for AI Agents.

To helps us visualize it, we have added a simple UI to the Dev Tools application that uses the MCP Server.

You can see the PRD in the UI, and you can export it as markdown if needed.

Read and revise the PRD

Take a few minutes to read the PRD and revise it if needed. Claude may have missed some steps, or added some steps that are not required. Make sure to adjust it as required.

You can always ask Claude to revise the PRD if needed or you can manually update the JSON file.

Example of a redundant task

For example the second task is redundant, as the Makerkit utilities will ensure that only authenticated users can submit feedback (it's the default behavior of the enhanceAction function).

You can ask Claude to remove the task if it's redundant - and you should probably do so, otherwise it will waste time and resources.

Getting Started with PRD-driven development with Claude Code

Now that we have created a PRD with Claude Code for the SaaS functionality we want to build, we can start building the code required to meet the requirements of the PRD.

US001: Getting Started with the first task

You can ask Claude Code to start building the next task with natural language. For example:

Get Started with the first task in the PRD

The above sentence is enough for Claude Code to start building the code required to meet the requirements of the PRD.

Pro Tip 💡: Ensure the TODO is limited to the task it's being tasked to complete

When Claude starts a task, make sure its TODO is limited to the task it's being tasked to complete.

If the TODO has too many items, ask Claude to focus on the current task, or break down a task further. Too many todos can clutter the context window and result in poorer code.

Submitting the first task: the user feedback widget implementation

Let's start with the first task. We want to create the user feedback widget.

We go ahead and ask Claude to start building the code required to meet the requirements of the PRD:

Get Started with the first task in the PRD

After a couple of minutes, Claude successfully completed the following tasks:

1. Database Schema: create the database schema for the user feedback widget
2. Migration: it created a declarative schema for Supabase and applied the migration. Then, it generated the types for the database schema.
3. Components: it created the components for the user feedback widget.
4. i18n: it created the i18n files for the user feedback widget and added a new namespace to the i18n settings.
5. Server Actions: it created the server actions for the user feedback widget to store the feedback in the database.
6. Added widget to the page: it added the widget to the layout components which were asked to be updated, without adding the widget to the page in the public pages (as per the PRD).

After it completed the task, it automatically updated the PRD to reflect the changes made to the code.

Pro Tip 💡: This doesn't always happen, so make sure to update the PRD manually if needed or simply ask Claude to do it.

Above and Beyong

Claude did also implement the fourth task of the PRD, i.e. the email notifications for super-admins. I would have preferred to have a separate task for this, but it's not a big deal, as it was less than 30 lines of code and implemented perfectly. We will therefore skip the fourth task.

Reviewing the code

In general, Claude did remarkably well, and the code is good-quality. However, there are a few things that could be improved:

1. Database Schema: the database schema adds user_id and account_id to the feedback table. This is a bit useless because the user ID and the account ID are the same ones when concerning personal accounts.
2. Server Actions: due to the issue above, the Server Actions queries the personal account ID using the user ID. Furthermore, makes a useless call to getUser. The user is already authenticated, so we don't need to call the getUser function when using the enhanceAction function.

I asked Claude to fix these issues. As you can see, it's still important to review the code manually after every task for ensuring the best practices are always met, and this requires understanding your codebase, which is something I recommend you don't skip.

Using a Claude Code sub-agent to review the code

After every task, it's a good idea to ask Claude Code to review the code it wrote.

The best way to do this is to spawn the @code-quality-review Claude sub-agent that the kit provides for you.

@code-quality-review perform a review on the first task of the PRD

This agent reviews code and provides quality feedback. It runs quality checks using the kit's commands and will attempt to fix all the issues it finds.

Below is the response from the @code-quality-review Claude sub-agent:

As you can see, it's a bit nitpicky sometimes, but it's good at finding possible edge-cases or issues that will be useful to fix.

Whether its recommendations are worth following is up to you, but it's a good way to ensure the code is of high quality.

Feedback Widget dialog

This is the dialog that appears when a user clicks the feedback widget button at the bottom right corner of the page.

When the user submits the feedback, the feedback is stored in the database and the user is redirected to the dashboard.

This worked flawlessly as expected.

Second Task: Create the user feedback dashboard

The second task of the PRD is to create a dashboard to manage the feedback, only accessible to super-admins.

They will be able to view all the feedback, mark it as "new", "reviewing", or "done", and delete it.

We proceed by asking Claude to start building the code required to meet the requirements of the PRD:

Get Started with the second task in the PRD

Claude did 99% of the work flawlessly, minus some minor UI/UX issues that were quickly fixed with a few simple edits.

Below is the dashboard it created in the Super Admin sections, which allows admins to change the status of the feedback or delete it:

Pro Tip 💡: ask Claude to perform a review of the code after every task. This will help you ensure the code is of high quality and that you're following best practices.

Best Practices for vibe-coding with AI Agents

1. Use PRDs: PRDs are a great way to help AI Agents understand the requirements and the codebase. They help AI Agents structure their work and understand the requirements better. There are many tools out there to help you define PRDs in your AI workflow.
2. Split Tasks into smaller tasks: This helps AI Agents structure their work and understand the requirements better. Don't let AI Agents take on too many tasks at once, as it will result in poorer results.
3. Use the Makerkit MCP Server: The MCP Server in Makerkit helps AI Agents understand and navigate the codebase and work with it in a more efficient way.
4. Use Claude Code sub-agents to perform specialized tasks: The Claude Code sub-agents included in Makerkit allow it to perform specialized tasks, each with their own context window. In this post, we used the @code-quality-review sub-agent to review the code after every task - which is a good practice to ensure the code is of high quality and secure
5. Self-review the code: Perform your own review of the code after every task, and try to absorb as much as you can from the changes made by AI Agents.

Conclusion

In this post, we have seen how to use PRDs with Claude Code and Makerkit to build a SaaS faster, and with better results with AI Agents.

We have added a functionality that touched many parts of the codebase in only a handful of prompts and minor manual edits.

The included PRD tool in the Makerkit MCP Server helped Claude understand the requirements and the codebase, and helped it write the code in a more efficient way.

AI Agents are still a work in progress, and they're not perfect. They still make mistakes, and they still need to be reviewed and improved. However, they're a great tool to help you build a SaaS faster, with great results.

Happy coding!