Forem: Eli A

Stop Giving Claude Code Your Whole PRD

Eli A — Thu, 21 May 2026 23:56:05 +0000

A PRD is not a good coding-agent task.

It is usually too wide, too mixed, and too full of competing intentions.

A PRD may contain:

product goals
user personas
user stories
edge cases
analytics
technical assumptions
future roadmap ideas
non-functional requirements
launch notes
open questions
design references
success metrics

That is useful context.

But when you paste the whole thing into Claude Code and say:

Implement this.

you are not giving the agent a task.

You are giving it a swamp.

Atlassian describes a PRD as a document that defines the product’s purpose, features, functionality, user needs, and success criteria, helping align stakeholders and teams. That is exactly why a PRD is too broad to become a single implementation prompt. It aligns humans across a product decision; it does not automatically decompose work into safe coding slices. (Atlassian)

The better workflow:

PRD
→ build thesis
→ slices
→ task packets
→ agent plan
→ implementation
→ review

This article is about the middle: turning a PRD into coding-agent tasks without letting the agent inflate scope.

The mistake: treating the PRD like a Jira ticket

A PRD answers:

What are we trying to build and why?

A coding-agent task should answer:

What exact change should be made now, inside which boundary, with which acceptance criteria?

Those are different artifacts.

When founders skip the translation step, the agent has to infer:

what is first
what is optional
what is excluded
what is risky
what should be tested
what should remain untouched

Claude Code can work across a codebase and automate development tasks, but it still needs strong framing and constraints. Anthropic’s Claude Code docs describe it as an agent that understands your codebase and can work across multiple files and tools, which is powerful exactly because vague tasks can spread quickly. (Claude Code)

A broad PRD plus a powerful agent creates one of the most common AI coding problems:

The agent builds a plausible version of the product, not the precise learning slice you needed.

The PRD compiler method

Think of yourself as compiling the PRD into smaller task packets.

A compiler does not throw the whole source into execution blindly.

It parses, resolves, transforms, and emits executable units.

Do the same with your PRD.

1. Extract the product bet
2. Mark the release boundary
3. Split by user journey
4. Convert journeys into task packets
5. Attach acceptance criteria
6. Add explicit non-goals
7. Ask the agent to plan before editing

This is not bureaucracy.

It is scope control.

Step 1: Extract the product bet

Before coding, reduce the PRD to one sentence:

We are building [workflow] for [specific user] so they can [valuable outcome] because [pain] is frequent or costly.

Example:

We are building a report-generation workflow for solo B2B consultants so they can turn raw project updates into client-ready weekly reports because manual reporting wastes billable time.

This sentence becomes the task filter.

Anything that does not support this release should be questioned.

If the PRD contains five possible products, do not ask Claude Code to resolve the strategy while it is also editing files.

Resolve the strategy first.

Step 2: Mark the release boundary

A PRD often describes the vision. A coding task needs the boundary.

Create three boxes:

Now
Not now
Never unless approved

Example:

Now:
- onboarding questions
- raw update input
- generated report output
- copy/export action
- activation event

Not now:
- teams
- integrations
- billing
- custom templates
- admin dashboard

Never unless approved:
- production database reset
- auth model changes
- pricing logic changes
- new external services

That third box matters.

Agentic coding can easily touch sensitive parts of the codebase if the prompt is too broad. Anthropic’s newer Claude Code permission work and auto-mode coverage show the same general concern: autonomy is useful, but risky actions still need safeguards and human review. (The Verge)

Do not rely only on the model “understanding” caution.

Write the boundary.

Step 3: Split the PRD by user journey, not by feature list

Most PRDs break work into features.

For coding agents, journeys are usually better.

Feature split:

authentication
onboarding
report editor
report output
analytics
settings

Journey split:

visitor understands promise
user signs up
user completes setup
user submits raw updates
user receives useful report
user copies/export report
system records activation

The journey split protects product value.

A feature can be technically complete and still fail the user.

A journey either gets the user to value or it does not.

Step 4: Create task packets

A task packet is the smallest useful unit you give the agent.

Use this shape:

# Task Packet

## Objective
What should be true after this task?

## Product reason
Why does this task matter?

## Scope
What is included?

## Non-goals
What must not be added?

## Files to inspect first
Where should the agent look before planning?

## Acceptance criteria
How do we know this is done?

## Tests / verification
What should be run or added?

## Risk notes
What can break?

This is much better than:

Implement onboarding from the PRD.

Example: PRD to Claude Code task

Assume the PRD says:

Users need to enter basic project context before generating their first report.

Do not give that sentence directly to the agent.

Compile it.

# Task Packet: Onboarding Context Step

## Objective

Add a minimal onboarding step that collects the user's business type, client name, project name, and preferred report tone before the first report is generated.

## Product reason

The report generator needs enough context to produce useful output on the first attempt. This task supports the first-value journey.

## Scope

Included:
- onboarding form
- validation
- persistence to user profile or project context
- redirect to report input screen after completion
- loading, empty, and error states

## Non-goals

Do not add:
- team onboarding
- billing
- integrations
- multi-project dashboard
- advanced preferences
- admin settings

## Files to inspect first

- app/onboarding/*
- app/report/*
- lib/db/*
- components/forms/*
- existing validation utilities

## Acceptance criteria

- User cannot continue with required fields empty.
- Valid input is saved.
- Returning users do not see onboarding again.
- User is routed to report input after completion.
- Mobile layout is usable.
- Errors are visible and recoverable.

## Tests / verification

- Unit test validation schema.
- Add/adjust E2E path: signup → onboarding → report input.
- Run typecheck, lint, and relevant tests.

## Risk notes

Do not change auth behavior.
Do not modify existing report generation logic beyond reading onboarding context.

That is an agent-ready task.

It is scoped. It is reviewable. It has product reason. It blocks scope creep.

Step 5: Ask for a plan before edits

Do not let the agent jump straight into implementation.

Use this prompt:

Read the task packet and inspect the listed files.

Do not edit code yet.

Return:
1. what you understand the task to be,
2. the relevant product boundary,
3. files you inspected,
4. implementation plan,
5. likely risks,
6. tests you will run,
7. anything ambiguous.

Wait for approval before coding.

This is especially important for ambiguous or cross-cutting work.

OpenAI’s Codex best-practices guide emphasizes planning, validation, MCP, skills, and reusable guidance as core habits for better results across CLI, IDE, and cloud workflows. (OpenAI Developers)

The lesson generalizes:

Before the agent writes code, make it show the map.

Step 6: Keep reusable guidance out of the task

A task packet should not repeat every repo rule.

Put durable instructions in durable files.

For Codex, OpenAI documents AGENTS.md as a way to give Codex extra instructions and context before it begins work. Codex reads AGENTS.md files before doing any work, allowing global guidance and project-specific overrides. (OpenAI Developers)

For Cursor, project rules serve a similar purpose: Cursor’s docs describe persistent instructions through Project, Team, and User Rules, plus support for AGENTS.md. (Cursor)

A clean setup:

CLAUDE.md                  // Claude Code memory
AGENTS.md                  // Codex-compatible agent guidance
.cursor/rules/product.mdc  // Cursor project rule
docs/tasks/001-onboarding-context.md
docs/tasks/002-report-input.md
docs/tasks/003-report-output.md

Do not bury permanent rules inside one-off prompts.

Do not bury one-off tasks inside permanent rules.

That separation keeps both clean.

The anti-scope-creep checklist

Before sending any PRD-derived task to Claude Code, check:

[ ] The task has one objective.
[ ] The product reason is explicit.
[ ] The user journey is named.
[ ] Included scope is short.
[ ] Non-goals are explicit.
[ ] Sensitive systems are protected.
[ ] Acceptance criteria are testable.
[ ] Verification steps are listed.
[ ] The agent must plan before editing.

If any box fails, the task is not ready.

The PRD should not disappear

Do not confuse decomposition with deletion.

The PRD still matters.

It remains the source for:

product purpose
customer needs
success criteria
stakeholder alignment
open questions
constraints

Atlassian’s PRD template guidance emphasizes consolidating supporting documentation and anticipating open questions and scope creep; that is the right role for the PRD as a context source. (Atlassian)

But the agent does not need to implement the PRD.

The agent needs to implement a slice derived from it.

A practical repo pattern

Use this lightweight folder:

docs/product/
  prd.md
  current-bet.md
  release-boundary.md

docs/tasks/
  001-onboarding-context.md
  002-report-input.md
  003-report-output.md

docs/verification/
  first-value-journey.md

Then the prompt becomes:

Read:
- CLAUDE.md
- docs/product/current-bet.md
- docs/product/release-boundary.md
- docs/tasks/001-onboarding-context.md

Do not edit code yet.

Inspect the relevant files and propose a plan.

This is clean enough for a small founder repo and structured enough to avoid chaos.

If the product context is still not clear enough to create task packets, start upstream. A workspace that can generate roadmap slices from product blueprints is useful at that exact point: not to replace engineering judgment, but to turn messy PRD-level thinking into scoped implementation units before an agent starts editing code.

The final rule

Never ask an AI coding agent to “implement the PRD.”

Ask it to implement one task packet derived from the PRD.

The PRD is the map.
The task packet is the route.
The agent is the driver.
You are still responsible for the destination.

A Better CLAUDE.md Template for SaaS Founders

Eli A — Thu, 21 May 2026 06:05:55 +0000

Your AI coding agent needs product reality, not only repo commands. Here is a practical CLAUDE.md template for SaaS founders using Claude Code.

Most CLAUDE.md files start with the repo.

They explain:

- Use pnpm.
- Run tests before committing.
- Components live in /components.
- API routes live in /app/api.
- Follow TypeScript strict mode.

That is useful.

It is also incomplete.

For a SaaS founder, the biggest risk is not that Claude Code forgets the test command. The bigger risk is that the agent builds the wrong product surface because the product context is missing.

A coding agent can follow repo rules and still create:

dashboards before activation works
team roles before the solo workflow is validated
integrations before retention is proven
pricing pages before willingness to pay is understood
admin panels before the first customer exists
generic SaaS bloat around a weak wedge

The issue is not coding quality.
The issue is missing product memory.

Claude Code’s memory system is designed to keep project context available across sessions through files such as CLAUDE.md. Anthropic’s docs describe this as project memory, and Claude Code also supports hooks, skills, subagents, and other extension points for more advanced workflows. (Claude Code)

The founder mistake is treating memory as only engineering instructions.

A better CLAUDE.md starts with product reality.

The mental model

Think of CLAUDE.md as two files in one:

Product Memory
  +
Engineering Memory

Engineering memory tells Claude how the repo works.

Product memory tells Claude what the product is trying to prove.

Both matter.

Without engineering memory, the agent may break conventions.
Without product memory, the agent may build the wrong thing correctly.

The structure I recommend

Use this order:

1. Product Reality
2. Current Bet
3. Must Build / Must Not Build
4. Evidence Goal
5. Engineering Rules
6. Safety Boundaries
7. Required Workflow

A founder-friendly CLAUDE.md should be short enough to be read often and specific enough to shape behavior.

Template: product-aware CLAUDE.md

# CLAUDE.md

## 1. Product Reality

We are building [PRODUCT] for [SPECIFIC CUSTOMER] because [PAIN / JOB] is frequent, costly, or urgent enough to justify switching or paying.

Current stage:
- [idea / prototype / MVP / post-MVP / growth]

Reality envelope:
- [bootstrap SaaS / VC-scale startup / internal tool / side project / agency spinout]

Primary user:
- [who uses it]

Economic buyer:
- [who pays or approves]

Current alternative:
- [spreadsheet / manual work / agency / incumbent tool / internal process]

Geography or market scope:
- [local / national / global / regulated market / specific region]

This first block prevents the agent from assuming every SaaS is the same.

A bootstrap B2B SaaS for consultants should not be built like a VC-backed enterprise platform. A local regulated workflow should not be built like a global self-serve productivity app.

2. Current Bet

## 2. Current Bet

The current wedge is:
- [one narrow workflow or use case]

The next release must prove:
- [one critical assumption]

The product should optimize for:
- [activation / willingness to pay / retention / workflow completion / demo conversion / first-value moment]

The product should not optimize for yet:
- [scale / enterprise features / deep integrations / automation depth / multi-segment support]

This turns the build into a learning system.

Without this section, Claude may optimize for “complete SaaS app.” That usually means more screens, more settings, more generic features.

The right early product is not the most complete version.

It is the smallest version that can test the current bet.

3. Must Build / Must Not Build

## 3. Must Build Now

- [Core onboarding step]
- [First-value workflow]
- [Critical data model]
- [Activation event tracking]
- [Basic error states]
- [One testable user journey]

## 4. Must Not Build Yet

- Do not add team management unless explicitly requested.
- Do not add role-based permissions beyond the current release scope.
- Do not add integrations before the core workflow is validated.
- Do not add advanced analytics before activation is proven.
- Do not create admin dashboards unless required by the approved task.
- Do not expand to additional ICPs.
- Do not add new pricing tiers without approval.

The Must Not Build Yet section is often more valuable than the Must Build section.

AI agents are good at completing patterns. “SaaS app” is a pattern. The agent may infer billing pages, settings, teams, notifications, analytics, dashboards, and exports.

That can be useful later.

Early, it can bury the wedge.

4. Evidence Goal

## 5. Evidence Goal

This release should help us learn whether:

- [specific user] can reach [specific value] without founder help.
- [buyer] understands why this product is worth paying for.
- [workflow] is frequent enough to support retention.
- [pricing hypothesis] is plausible.
- [technical approach] can deliver value at acceptable cost.

Primary success signal:
- [one measurable signal]

Secondary signal:
- [one backup signal]

Kill or pivot trigger:
- [what would make us change direction]

This is the part most technical instructions omit.

But it is essential for SaaS founders.

The product is not only a code artifact. It is a test of a market assumption.

A tool like Gaplyze’s product validation and roadmap workspace is useful before writing this section because the founder needs to clarify the ICP, wedge, monetization hypothesis, must-not-build boundaries, and first evidence loop before those constraints are handed to Claude Code.

5. Engineering Rules

Now add the repo details.

## 6. Engineering Rules

Stack:
- Framework:
- Language:
- Database:
- Auth:
- Payments:
- Hosting:
- Styling:
- Testing:

Important directories:
- /app:
- /components:
- /lib:
- /db:
- /tests:

Commands:
- Install:
- Typecheck:
- Lint:
- Unit tests:
- E2E tests:
- Build:

Keep this concrete.

Do not write vague rules like:

Write clean code.
Follow best practices.
Make it scalable.

Those are too broad.

Write rules that affect actual decisions:

Prefer server actions for simple mutations.
Use existing UI primitives before adding new components.
Do not introduce new dependencies without explaining the tradeoff.
All customer-visible flows need loading, empty, success, and error states.

6. Safety Boundaries

Claude Code hooks can provide deterministic control by running shell commands at specific lifecycle points, which is different from simply hoping the model remembers a rule. Anthropic’s docs describe hooks as a way to enforce project rules, automate repetitive tasks, and integrate with existing tools. (Claude Code)

So do not rely on CLAUDE.md for everything.

Use memory for context.

Use hooks, permissions, CI, and reviews for enforcement.

Still, the safety section should be explicit:

## 7. Safety Boundaries

Never do the following without explicit approval:

- Modify production database migrations.
- Run destructive database commands.
- Change billing or Stripe logic.
- Alter authentication or authorization behavior.
- Add new environment variables.
- Add new third-party services.
- Change pricing, plan limits, or quota logic.
- Store sensitive data in logs.
- Remove tests to make a build pass.

This section is especially important for SaaS products because early mistakes in auth, billing, tenant isolation, and data handling can become expensive quickly.

7. Required Workflow

## 8. Required Workflow

For any non-trivial change:

1. Read the Product Reality and Current Bet sections.
2. Restate the relevant product constraint.
3. Inspect the relevant files before planning.
4. Propose a short plan.
5. Identify risks and tests.
6. Wait for approval before broad changes.
7. Implement the smallest approved slice.
8. Run required checks.
9. Summarize what changed, what was not changed, and what should be tested manually.

This workflow makes the agent slower at the start and faster overall.

It prevents the common failure mode where the agent begins editing before it understands the product boundary.

A compact full version

Here is the shorter version you can actually paste into a repo and adapt.

# CLAUDE.md

## Product Reality

We are building [PRODUCT] for [SPECIFIC CUSTOMER] because [PAIN] is frequent, costly, or urgent.

Stage:
[idea / prototype / MVP / post-MVP / growth]

Reality envelope:
[bootstrap SaaS / VC-scale startup / internal product / side project]

Primary user:
[...]

Economic buyer:
[...]

Current alternative:
[...]

## Current Bet

Current wedge:
[...]

This release must prove:
[...]

Optimize for:
[...]

Do not optimize for yet:
[...]

## Must Build Now

- [...]
- [...]
- [...]

## Must Not Build Yet

- Do not add team management unless explicitly requested.
- Do not add integrations before the core workflow is validated.
- Do not add advanced analytics before activation is proven.
- Do not expand to additional ICPs.
- Do not change pricing or plan logic without approval.

## Evidence Goal

Primary success signal:
[...]

Secondary signal:
[...]

Kill or pivot trigger:
[...]

## Engineering Rules

Stack:
- Framework:
- Language:
- Database:
- Auth:
- Payments:
- Styling:

Commands:
- Typecheck:
- Lint:
- Test:
- E2E:
- Build:

Architecture rules:
- [...]
- [...]
- [...]

## Safety Boundaries

Never do without approval:
- Modify migrations.
- Run destructive DB commands.
- Change billing logic.
- Change auth/authorization behavior.
- Add dependencies.
- Add environment variables.
- Remove tests to make checks pass.

## Required Workflow

For non-trivial work:
1. Restate the product constraint.
2. Inspect before planning.
3. Propose a plan.
4. Identify risks and tests.
5. Implement only the approved slice.
6. Run checks.
7. Summarize changes and verification.

What should not go into CLAUDE.md

Do not turn this file into a dumping ground.

Avoid:

full PRDs
long market research reports
giant competitor tables
every customer quote
every roadmap item
every design-system token
every security policy
every possible architecture decision

Large, noisy memory files can make the agent less focused.

Put repeatable workflows into skills. Claude Code supports skills as reusable capabilities, and its broader extension system includes subagents, hooks, and MCP servers for more specialized work. (Claude Code)

Use separate docs when needed:

CLAUDE.md                  core product + engineering memory
docs/product/strategy.md   deeper product context
docs/roadmap/current.md    active roadmap slice
docs/security/rules.md     deeper security rules
docs/testing/e2e.md        Playwright journey guidance

The CLAUDE.md file should point to the right context, not contain everything.

A better first prompt after adding CLAUDE.md

After creating the file, do not immediately ask Claude to build.

Start with calibration:

Read CLAUDE.md.

Do not edit code yet.

Summarize:
1. the target customer,
2. the current wedge,
3. the must-not-build constraints,
4. the evidence goal,
5. the engineering safety boundaries.

Then identify any contradictions or missing details that would affect the next implementation task.

This turns memory into an active contract.

The core idea

A good CLAUDE.md is not just a codebase instruction file.

For SaaS founders, it is an alignment file.

It aligns:

customer
  → wedge
  → evidence goal
  → product scope
  → engineering rules
  → safety boundaries

When that alignment is missing, AI coding agents make it easier to build a product that looks complete but teaches the founder very little.

When the alignment is present, Claude Code becomes much more useful because it is executing inside a real product frame.

Build memory before building features.