DEV Community: Eli A

How to Effectively Use Claude Code to Build the Right Product

Eli A — Fri, 26 Jun 2026 01:47:40 +0000

Claude Code can build fast.

That is not the problem.

The problem is that fast coding can still build the wrong product.

A vague request like this:

Improve the onboarding flow.

can produce clean code, nice UI, passing tests, and still miss the actual business goal.

Because Claude Code does not only need repository context.

It needs product context.

Not a 40-page PRD.
Not a strategy essay.
Not a giant prompt.

It needs a sharp brief that answers:

Who is this for?
What product outcome matters?
What is in scope?
What is explicitly out of scope?
How do we know this change worked?
What should Claude avoid “helpfully” adding?

That is the difference between AI-assisted coding and product-centric AI coding.

The dangerous default: “make it better”

Claude Code is strong enough to turn vague ambition into code.

That is exactly why you need discipline.

If you ask:

Make the customer dashboard better.

Claude may add filters, cards, charts, empty states, settings, exports, summary blocks, or layout changes.

Some of that may be good.

Some of it may be product bloat.

A better request is:

Improve the dashboard so a restaurant manager can identify which three menu items caused the biggest margin drop this week.

Do not redesign the dashboard.
Do not add new analytics categories.
Do not add export features.
Do not change navigation.
Focus only on the weekly margin insight.

Now Claude has a product target.

Not just a coding task.

Start with CLAUDE.md, but do not overload it

For Claude Code, CLAUDE.md is the durable instruction file.

Use it for stable project guidance:

# CLAUDE.md

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Lint: `pnpm lint`

## Coding rules
- Keep diffs small and reviewable.
- Prefer existing components before creating new ones.
- Do not introduce new dependencies without asking.
- Do not change database schema unless explicitly requested.

## Workflow
- For non-trivial work, propose a plan before editing.
- Explain tradeoffs before changing architecture.
- Run relevant tests before final response.
- Summarize changed files and remaining risks.

Keep this file stable.

It should not become a dumping ground for every temporary product decision.

The rule is simple:

CLAUDE.md = how Claude should work in this repo.
Task brief = what Claude should build right now.

If you use AGENTS.md, import it correctly

If your repo already has AGENTS.md, do not duplicate the same instructions.

Create a CLAUDE.md that imports it:

# CLAUDE.md

@AGENTS.md

## Claude Code-specific rules
- Use plan mode before changing architecture.
- Ask before running destructive commands.
- Prefer minimal diffs over broad rewrites.

That gives you shared agent instructions plus Claude-specific behavior.

But again, this is still not enough.

The repo can be perfectly documented and Claude can still build the wrong product slice.

Add a product brief for every meaningful task

Before asking Claude to build, create a short task brief.

Use a neutral file name:

TASK_BRIEF.md

Example:

# TASK_BRIEF.md

## Product outcome
Help a returning customer complete a booking in fewer steps.

## User
A repeat customer booking a routine appointment from mobile.

## Current problem
The current flow asks for account details too early and causes drop-off before time selection.

## Scope
- Move time selection earlier in the flow.
- Keep contact confirmation after time selection.
- Preserve the current visual system.
- Improve mobile clarity.

## Non-goals
- No payments.
- No admin scheduling tools.
- No calendar integration.
- No redesign of the whole booking page.
- No new account system.

## Success criteria
- Returning customer can choose service, time, and confirm contact details.
- Form errors are clear.
- The flow works on mobile.
- Existing tests still pass.

This is not a feature spec.

It is a product boundary.

It tells Claude what “better” means.

Prompt Claude like a product reviewer, not a code generator

Do not start with:

Read the brief and implement it.

That skips the most valuable step.

Start with:

Read CLAUDE.md and TASK_BRIEF.md.

Then inspect the current booking flow.

Before editing, respond with:
1. the user journey you think matters
2. the files you expect to touch
3. the smallest implementation plan
4. what you will not change
5. any unclear product decision

Do not write code until I approve the plan.

This makes Claude show its product understanding before it edits files.

That is where you catch drift.

Not after the diff is already large.

Use non-goals aggressively

Non-goals are not optional.

They are the strongest defense against AI-generated bloat.

Bad non-goal:

Do not overcomplicate it.

Good non-goals:

## Non-goals

- Do not add payments.
- Do not add team accounts.
- Do not add analytics.
- Do not change navigation.
- Do not modify unrelated routes.
- Do not introduce new dependencies.
- Do not create a new design system.

Claude Code is often helpful enough to fill gaps.

Non-goals tell it where helpfulness becomes damage.

Write acceptance checks before implementation

Claude should know how the change will be judged.

Create:

ACCEPTANCE_CHECKS.md

Example:

# ACCEPTANCE_CHECKS.md

## Product behavior
- A returning customer can complete the booking flow from mobile.
- The service/time choice is visible before contact confirmation.
- The user is never asked to create an account during the flow.

## Engineering behavior
- Existing tests pass.
- No unrelated files are changed.
- No new dependencies are added.
- The diff can be reviewed in one pass.

## Review notes
- List anything intentionally left out.
- List any product assumption that remains unvalidated.

That last line is important.

Claude Code should not only report what it built.

It should report what is still uncertain.

Use .claude/rules for scoped technical rules

For larger projects, avoid stuffing everything into CLAUDE.md.

Use path-specific rules.

Example:

.claude/
  rules/
    frontend.md
    api.md
    tests.md

Frontend rule:

---
paths:
  - "src/components/**/*.tsx"
  - "src/app/**/*.tsx"
---

# Frontend rules

- Reuse existing components before creating new ones.
- Keep accessibility attributes intact.
- Do not introduce inline styles.
- Preserve responsive behavior.

API rule:

---
paths:
  - "src/api/**/*.ts"
  - "src/server/**/*.ts"
---

# API rules

- Validate inputs at the boundary.
- Return typed errors.
- Do not log secrets.
- Keep handlers small.

This keeps Claude’s context cleaner.

Claude gets the rules that matter for the files it is touching.

Separate product judgment from technical enforcement

Memory files guide Claude.

They do not enforce behavior.

If something must never happen, use actual enforcement:

permissions
settings
hooks
CI checks
tests
code review
branch protection

Use CLAUDE.md for guidance.

Use tooling for guardrails.

For example:

Guidance:
"Do not introduce new dependencies without asking."

Enforcement:
CI fails if package files change without approval.

That distinction saves pain.

The product-centric Claude Code loop

Use this loop for meaningful product work:

1. Write the product outcome.
2. Define the user journey.
3. Name non-goals.
4. Write acceptance checks.
5. Ask Claude for a plan.
6. Approve or correct the plan.
7. Let Claude implement the smallest useful slice.
8. Review against product intent, not only tests.

The key is step eight.

A passing test does not prove the product decision was right.

It only proves the code did what the test expected.

A better file set

For serious Claude Code work, use this structure:

CLAUDE.md
Durable project instructions.

.claude/rules/
Scoped technical rules.

TASK_BRIEF.md
Current product outcome, user, scope, non-goals.

ACCEPTANCE_CHECKS.md
Product and engineering checks for this slice.

This is enough for most teams.

Do not start with a huge agent operating manual.

Start with clean context.

The missing upstream step

There is still one question this workflow cannot answer by itself:

Is this the right product slice to build?

Claude Code can help implement a slice.

It should not be responsible for deciding whether the slice is strategically correct.

That decision should come from product work before coding:

idea validation
market intelligence
buyer clarity
strategy
roadmap sequencing
execution plan

This is where Gaplyze fits into the workflow. A founder or team can use Gaplyze to turn a validated product bet into an AI-native prompt pack, then bring that focused context into Claude Code instead of starting from a vague “build this app” prompt.

The better chain is:

validated product bet
→ strategy
→ execution roadmap
→ prompt pack
→ Claude Code implementation

Not:

idea
→ Claude Code
→ hope

The rule

Claude Code is not just a faster way to write code.

It is a sharper instrument.

But sharp instruments need a steady hand.

If you give Claude only repository instructions, it may build correctly.

If you give Claude product context, non-goals, and acceptance checks, it is much more likely to build the right thing.

That is the point.

Do not use Claude Code to generate more product-shaped software.

Use it to execute a product decision you have already made carefully.

How to Find Startup Ideas Before You Open Claude Code (Evidence Over Vibes)

Eli A — Fri, 19 Jun 2026 22:13:01 +0000

You can scaffold a working app in a weekend now. Cursor, Claude Code, and Codex have collapsed the cost of building so far that "can I build it?" is barely a question anymore. Which means the only question left is the one most of us skip: should this exist at all?

Here's the uncomfortable part. The most common reason startups fail isn't bad code or slow shipping — it's building something nobody needs. The cheaper building gets, the more dangerous that failure mode becomes, because nothing stops you from shipping a beautiful solution to a problem zero people have.

So before you open your editor, here's how to find startup ideas worth building, in four steps:

Collect problem signals, don't brainstorm. Hunt for recurring complaints, manual workarounds, and rising searches — not whiteboard concepts.
Name the specific gap those signals expose (underserved audience, missing feature, broken workflow, mispricing, trend-driven opening).
Confirm demand is real by triangulating across independent sources. One signal is noise; convergence is evidence.
Pressure-test fit against your actual constraints, then score the survivors so you commit to the strongest opportunity, not the most exciting one.

That's the whole method. The rest of this post is how to run it like an engineer — with provenance, multiple sources, and a bias toward evidence over enthusiasm.

Ideas Are Discovered, Not Invented

The "flash of inspiration" founder myth is mostly survivorship bias. In practice, good ideas are downstream of problems. Someone keeps hitting a painful workflow, builds a hacky workaround, and realizes thousands of other people are duct-taping the same thing. The idea was the answer to a problem they could already see.

This is good news for builders, because it means finding ideas isn't a creativity test — it's a search problem. You're not trying to be clever. You're trying to be observant, then verify. Demand exists before your product does. Your job is to locate it, not conjure it.

Brainstorming fails precisely because it optimizes for novelty instead of need. A whiteboard rewards clever-sounding concepts, but cleverness is uncorrelated with whether anyone will pay. Worse, an idea generated in isolation arrives with zero attached evidence — so you can't tell a real opportunity from a daydream until you've already burned a weekend (or a quarter) building one.

The Gap Categories: Where Opportunities Actually Hide

A "market gap" is just a specific, unmet need inside an existing market — a place where current solutions leave money on the table. Naming the category of gap turns a vague hunch into a thesis you can test. Most startup-sized gaps come in a handful of recognizable shapes:

Underserved-audience gaps — the product serves the mainstream well but ignores a segment with different needs: solo founders, a specific industry, a non-English market, a budget tier nobody bothers with.
Feature gaps — the category exists, customers are vocal about a missing capability, and incumbents are too big or too slow to ship it.
Workflow gaps — people stitch together three tools and a spreadsheet to get one job done. The duct-tape is itself proof of demand.
Positioning and price gaps — a capable tool exists but is mispriced, overbuilt, or aimed at the wrong buyer, leaving room for a focused alternative.
Trend-driven gaps — a new technology, regulation, or behavior shift makes a previously impossible product viable, and the first credible entrant defines the category.
Quality and trust gaps — the category is full of solutions people actively distrust, which is itself an opening.

If you can't name which shape your gap is, you don't have a gap yet — you have a guess.

Reading Demand Signals (Like You'd Read Logs)

Once you have a candidate gap, the real question is: is anyone actively trying to solve this problem right now? You answer it by reading demand signals — and the single most important discipline is to never trust one source.

Any single signal can lie to you. A Google Trends spike might be seasonal noise. A loud Reddit thread might be a vocal minority of five people. Heavy VC funding might mean the space is already a knife fight. Convergence across independent sources is what separates a real opportunity from a mirage. Think of it like distributed tracing: one span tells you nothing; the pattern across spans tells you the truth.

Here's what each source actually tells you when you're doing market gap analysis:

Google Trends — whether search demand for the problem is rising. Problem-shaped queries (how do I…, alternative to…, why is X so hard) matter far more than brand awareness.
Reddit — unfiltered pain. The most valuable threads are people describing the manual workaround they built because nothing adequate exists. A workaround is direct evidence of willingness to act. (This is the modern GummySearch alternative workflow — mining community pain instead of paying for a dead tool.)
Product Hunt — what's launching and getting traction, so you can tell a validated category from a saturated one — and spot where launches are thin.
Hacker News — technical critiques of existing tools and early signals of shifts that open new categories. This is where developer-shaped pain shows up first.
VC funding data — where institutional capital is flowing. Rising investment signals validation; over-funding warns of a market that's already overheated.
G2 / Capterra reviews — exactly what users hate about incumbents. Every one-star review naming a missing capability is a feature gap with a name attached.
X (Twitter) — what builders and early adopters are talking about before it goes mainstream.

The power is in the overlap. When rising searches, a recurring Reddit complaint, healthy-but-not-overheated funding, and a wall of one-star competitor reviews all point at the same unmet need, you're not guessing anymore. You're looking at converging evidence that a real audience is actively shopping for a better answer.

The Workaround Test: the strongest demand signal is a workaround. When people are stringing together spreadsheets, copy-paste rituals, and a chain of half-fitting tools, they're already paying for the problem with their time. A product that removes that pain has a buyer waiting. Hunt for "how I hacked together…" and "my current process is…" posts.

If you want the deep-dive on mining communities for these signals, the find startup ideas on Reddit playbook breaks down exactly which threads count as evidence.

Is the Gap Real? (Demand AND Fit)

Finding a gap and confirming it's worth your time are two different jobs. A gap can be real and still be a bad idea for you specifically — too small to sustain a business, too crowded to enter, too cheap to monetize, or a poor fit for your runway and skills.

So "is the gap real?" has to be answered on two axes:

Demand axis — look for three confirmations: people are actively searching for a solution (intent, not just awareness), they're already spending time or money on inadequate alternatives, and the pattern shows up across more than one independent source. If demand only appears in one place, treat it as a hypothesis, not a finding.

Fit axis — be honest about your constraints. A funded YC team and a bootstrapped solo dev should chase completely different gaps in the same market. This is where generic idea tools fail you: they hand the same advice to everyone, regardless of whether you have one weekend or eighteen months of runway.

This second axis is the one builders consistently underweight. You can vibe-code a prototype of almost anything now — but you can't vibe-code distribution, runway, or a market that's a fit for a solo operator. Decide before the build whether this opportunity matches your actual reality.

Turn a Competitor's Website Into a Wedge

Some of the best ideas are hiding in plain sight on a competitor's own homepage. An established product tells you, for free, who the customer is, what the category looks like, and — crucially — what it chooses not to do. The features it omits, the segment it ignores, and the complaints in its reviews are the outline of your wedge: the narrow, specific entry point where you can win before expanding.

This reframes a scary thought into a useful one. "A competitor exists, so the market is taken" becomes "a competitor exists, so the market is validated — and here's precisely where it's weak." A crowded market with a clear wedge is often a far better bet than an empty one, because the demand is already proven; you just need a sharper angle. The full move is broken down in the competitor → wedge walkthrough.

From Ideas to a Scored Shortlist

Here's where I'll show how I run this loop. I built Gaplyze to automate the heavy parts of exactly this method, so the workflow looks like a pipeline:

Generate candidates from real signals. Give it a topic, niche, audience, or even a competitor's URL, and Idea Generation researches the space across seven-plus real sources (Google Trends, Reddit, Product Hunt, Hacker News, VC funding, G2/Capterra, X) and returns six evaluated opportunity candidates, each with estimate scores and a framing dossier. You start from an evidence-backed list, not a blank page.
Read the signals and name the gap. For each candidate, check whether the demand signals converge across sources and identify which gap category it exploits. Candidates whose signals don't converge get cut here, fast.
Mine competitor sites for the wedge. Web Insights takes a competitor URL and turns it into a scored opportunity report with specific, impact-estimated recommendations — surfacing the underserved audiences, missing capabilities, and positioning gaps the incumbent left open. That's how a vague "there's something here" becomes a defensible entry point.
Score every survivor across eight dimensions. PI Scoring rates each idea across eight dimensions — market demand, success probability, competition, innovation, scalability, time to market, cost efficiency, and risk — on a consistent nine-tier scale, with a confidence level and rationale for every score, plus a SWOT, a commercial verdict, and the three-to-five killer assumptions you still have to test.
Rank, compare, and commit. Because every idea is scored on identical criteria, you compare them like a portfolio. The candidate that sounded best in conversation often scores weakest on competition; the one you almost dismissed sometimes has the strongest demand.

The part that'll resonate with engineers: when you go deep, Strategic Vectors adds an evidence ledger that tags every claim as supported (with a source), inferred, or missing proof. It's provenance for your thesis — the same instinct that makes you distrust a function with no tests should make you distrust a business claim with no source. A gap built on supported demand is worth your weekend. A gap built on inferred claims is a research task, not a build task.

And because your constraints shouldn't get lost between steps, Project Framing threads your actual reality — team size, budget, runway, stage, geography — through every artifact, so an opportunity is assessed against your situation, not a hypothetical founder's.

Honest Comparison: Where Gaplyze Fits vs the Alternatives

If you've searched for how to find startup ideas, you've probably met two kinds of tools. Let me be straight about where each one fits.

Curated idea databases — IdeaBrowser is the best-known — publish a daily idea and a big library of pre-researched concepts with validation metrics. They're genuinely useful for inspiration and for seeing how an opportunity gets analyzed. The trade-off is that a database is a fixed catalog: the ideas are generic to the catalog, not generated for your context, your niche, or the competitor you're actually up against — and everyone browsing sees the same entries. Gaplyze works the other way around: it generates and scores opportunities for your input, and shows the multi-source evidence behind each one.

Generic "market gap analysis" and GIS tools dominate those search results, but most of them analyze geographic or retail gaps — where to place a physical store, which territory is underserved on a map. That's a completely different problem from finding a software or business-model opportunity. They won't tell you whether founders are complaining about a missing feature on Reddit, or whether VC money is flowing into a category. If you're trying to find SaaS ideas or find business opportunities in software, map-coordinate tools are the wrong instrument.

The deeper differentiator is the connected journey. Most tools stop at a verdict or a list. Finding the idea is step one of a chain — discovery → validation → strategy → blueprints → roadmap — not a destination.

Beware the "AI said yes" trap. Plenty of tools will validate any idea you give them in a few seconds with no sources — and an idea that passes a credulous checker is more dangerous than no validation at all, because it manufactures false confidence. As builders we already know this instinct: a test that always passes is worse than no test. Insist on seeing the evidence. That's the entire point of an evidence ledger that tags each claim supported / inferred / missing proof — so a "yes" you can't trace never sneaks into your decision.

Make It a Habit, Then Go Build

Finding good ideas isn't a one-time lucky strike — it's a practice that compounds. The more candidates you run through this loop, the faster you recognize converging signals and dismiss noise at a glance. Each pass calibrates your judgment.

So make it a routine. Pick a space you understand. Generate a batch of candidates from real signals. Read where the demand converges. Mine the incumbents for a wedge. Score the survivors. Most candidates die early — that's the point. The few that survive multi-source evidence and an honest fit check are the ones worth opening Cursor for.

The goal isn't to fall in love with the first idea you find. It's to build a pipeline of evidence-backed opportunities and let structured scoring point you to the strongest one — so that when you finally do start vibe-coding, you're building the right thing.

Try it on a space you care about: generate startup ideas from real signals →

This is a syndicated post. The canonical, continuously-updated version lives on Gaplyze.

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.