Product Requirements Document (PRD)

In the previous section, we defined what we're building — a JSON Formatter that formats, minifies, validates, and explores JSON data — and why it's useful. We outlined the key features (pretty printing, tree view, real-time validation, file upload, and more) and the quality goals (performance via Web Workers, responsive layout, reliable error handling).

Now it's time to turn those ideas into a Product Requirements Document (PRD) — and we'll use Claude Code to write it. We will use Claude Code by default throughout this tutorial, but if you don't have Claude Code, you can also use Codex.

Why Write a PRD?#

You might wonder: if we already listed the features, why not just start coding? For a small personal project, you often can. But writing a short PRD before coding has real benefits, even for solo projects:

• Forces precision — Vague ideas like "tree view" become concrete decisions: What does expanding a node show? What happens when you click a key? Writing it down exposes gaps in your thinking before they become bugs.
• Creates a shared reference — If you're working with others (or with an AI coding assistant), the PRD is the single source of truth. Everyone builds toward the same target.
• Guides AI code generation — When you ask Claude Code to implement a feature, a clear PRD gives it direction. Instead of "build a JSON formatter," you can point to specific requirements and constraints.
• Prevents scope creep — A PRD draws a clear boundary around what's in scope. Without one, it's easy to keep adding "one more thing" and never finish.

That said, keep your PRD short and concise. You won't get everything right upfront — new requirements always surface during development as you encounter edge cases and rethink interactions. A lean PRD that captures the core intent is more useful than an exhaustive one that tries to anticipate every detail. This is especially true when working with AI coding agents: a long, overly detailed PRD can actually hurt more than it helps, because too much context can mislead the AI or cause it to fixate on low-priority details instead of the things that matter most.

Setting Up the Project#

Before we write the PRD, let's create a Next.js project. Open your terminal and run:

npx create-next-app@latest json-formatter --typescript --tailwind --eslint --app --import-alias "@/*"

This scaffolds a new Next.js project called json-formatter with TypeScript, Tailwind CSS, ESLint, the App Router, and the @/* path alias — everything we'll need for the build.

Once the command finishes, navigate into the project root and create an empty file for our PRD:

cd json-formatter
touch PRD.md

You can also open the project in VS Code:

code .

Alternatively, you can create PRD.md directly in VS Code — right-click in the file explorer on the left and select New File.

Having the PRD as a markdown file in the project root keeps the spec right next to the code — easy to reference, easy to update, and easy to feed back to Claude Code later when we're implementing features.

Write the PRD#

Rather than writing the PRD from scratch ourselves, we'll use Claude Code to draft it. If you're new to Claude Code, check out the Getting Started with Claude Code guide first.

This is a great use case for AI assistance — we have a clear vision of what we want (from the previous section), and we need Claude Code to organize it into a structured, detailed document.

Here's an example of what Claude Code might produce:

Revising the PRD#

Always review the generated PRD carefully and thoroughly. The PRD is the key guideline that AI agents will follow when building the solution — any vague requirement, missing detail, or unnecessary scope in the PRD will directly affect the quality of the generated code. Think of it as programming the AI: the more precise your spec, the better the output.

The generated PRD above is in good shape — it's well-structured, covers the major features, and reads like a real spec. However, we want to focus on the key features and keep the scope tight. Let's remove the unnecessary requirements so we can focus on building rather than specifying.

Here's what we'll remove:

• Statistics (FR-8) — "Total value count" and "Data type breakdown" add complexity without much user value for this tool. We'll keep the essentials: file size, line count, key count, and max nesting depth.
• Accessibility (NFR-2) — Accessibility matters in production apps, but for this tutorial we'll skip it to keep the scope manageable. We can always add it later.
• Out of Scope section — Since we're only building this one version, listing what we're not building is unnecessary overhead. Remove it entirely.

Let's ask Claude Code to make these changes:

Here's the revised PRD:

Reviewing the PRD#

Now that we've revised the PRD, the next step is to let Claude Code review the PRD one more time. Even after our edits, there may be conflicting requirements, ambiguous wording, or gaps that could confuse the AI during implementation. A quick review pass catches these issues before they turn into bugs.

Here's what Claude Code flagged:

These are all valid catches. Let's ask Claude Code to resolve them — keeping the PRD clean and simple rather than adding more detail:

Here's the final PRD with all issues resolved:

You can repeat this review-and-resolve cycle as many times as needed — ask Claude Code to review again, fix what it finds, and review once more until no issues remain. A clean, unambiguous PRD means fewer surprises during implementation.

With the PRD finalized, we're ready to move on. In the next section, we'll use Claude Code to turn this PRD into a technical design — defining the component structure, data flow, and architecture before we write any code.