Your CLAUDE.md Should Start with Product Reality, Not Just Code Rules

Most CLAUDE.md files begin too late.

They start with:

md
Run pnpm install.
Use TypeScript strict mode.
Run pnpm test before committing.
Components live in /components.
API routes live in /app/api.

Useful, yes.

Enough, no.

For AI-native SaaS building, the most important thing an agent needs to know is not only how the codebase works. It also needs to know what the product is trying to become, who it serves, what must not be built, and what evidence the next release is supposed to produce.

Claude Code’s memory documentation describes CLAUDE.md files as persistent instructions loaded at the start of sessions, while also noting that they are context rather than hard enforcement. The docs recommend keeping instructions specific, concise, structured, and ideally under about 200 lines per file. (Claude)

That detail matters.

If CLAUDE.md is context, then the first context should not be only code style.

It should be product reality.

---

The problem: coding agents execute scope before they understand strategy#

AI coding agents are good at turning instructions into implementation. That is also why they are dangerous.

If your repository memory says only:

md
Use Next.js.
Use Tailwind.
Run tests.
Keep components reusable.

the agent can still build the wrong thing very cleanly.

It may add:

• enterprise features before the wedge works
• dashboards before activation is proven
• team roles before a solo workflow is validated
• integrations before the core job is sharp
• analytics before the user has a reason to return
• polish before willingness to pay is tested

The agent is not “wrong” in the narrow coding sense. It is operating without product judgment.

That is the real issue.

A coding agent without product memory tends to optimize for visible completeness. A founder needs it to optimize for evidence, constraint, and wedge.

Decision matrix

Use when

agents need to preserve strategic intent across implementation tasks.

Avoid when

the memory file is only a dumping ground for every preference and process.

Tradeoff

product memory adds upfront discipline, but prevents generic SaaS expansion.

Risk

a technically obedient agent building against an undefined business bet.

---

The better mental model: two memories#

A serious AI-native project needs two different memories.

Most teams write the second.

The best teams write both.

Claude Code supports project, user, local, and managed memory locations; project memory can be shared through version control, while local memory can remain private. The docs also explain that CLAUDE.md can import files such as AGENTS.md, and that larger projects can move scoped rules into .claude/rules/. (Claude)

Codex has a similar concept through AGENTS.md; OpenAI’s documentation says Codex reads AGENTS.md files before doing work, layering global and project-specific guidance so tasks begin with consistent expectations. (OpenAI Developers)

The naming differs.

The principle is the same:

Agents need stable project context before they act.

The missing piece is that “project context” should include product strategy, not just repository instructions.

---

Product reality comes first because it constrains everything else#

Consider the same feature request:

“Build onboarding.”

That means very different things depending on the product reality.

The code task is the same phrase.

The product task is completely different.

This is why CLAUDE.md should begin with the project’s operating reality.

Flow

Product reality

Product memory

Engineering memory

Scoped agent plan

Implementation

Evidence update

---

The Product Reality Block#

Every serious CLAUDE.md should start with a compact block like this:

md
# Product Reality

## Product thesis
We are building [product] for [target customer] because [pain/job] is urgent enough to justify switching or paying.

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

## Reality envelope
[side hustle / bootstrap SaaS / VC-scale startup / internal product / expansion]

## Target customer
Primary user:
Economic buyer:
Decision maker:
Current alternative:

## Current wedge
The first version focuses only on:
We are deliberately not serving:

## Monetization hypothesis
Initial pricing model:
Expected willingness-to-pay signal:
Gross margin or support risks:

## Evidence goal for current roadmap
The next release must help us learn:

## Must build now
- ...

## Must not build yet
- ...

This is not a business plan.

It is an execution constraint.

It tells Claude Code, Codex, Cursor, Copilot, or any coding agent:

“When you write code, do not optimize for generic SaaS completeness. Optimize for this specific product bet.”

---

The most important section: “Must not build yet”#

The must-not-build list is one of the highest-leverage parts of agent memory.

AI agents are helpful, but they are also eager. They often complete the implicit pattern of a SaaS app:

• add settings
• add admin panels
• add team support
• add charts
• add notifications
• add exports
• add roles
• add integrations

Those features may be valuable later. Early, they may be poison.

A good must-not-build section looks like this:

md
## Must not build yet

- Do not build enterprise team management.
- Do not add role-based permissions beyond owner/user.
- Do not add advanced analytics until activation is validated.
- Do not build integrations before the core workflow retains users.
- Do not add AI automation that increases unit cost before pricing is tested.
- Do not optimize for multiple ICPs.
- Do not expand beyond the current wedge without explicit approval.

This turns strategy into a boundary the agent can understand.

It also protects the founder from themselves.

Scorecard

3/5 complete

• ICP stated
• Wedge stated
• Must-not-build list written
• Pricing evidence captured
• Roadmap tied to one evidence goal

---

Product memory should change how agents plan#

A strong agent should not jump from task to code.

For every meaningful feature, it should first restate:

1. the target ICP
2. the current wedge
3. the evidence goal
4. the relevant must-not-build items
5. the smallest implementation slice
6. the tests needed to protect the journey

Example prompt:

text
Before coding, read the Product Reality section.

Then summarize:
1. which customer this feature serves,
2. which wedge it supports,
3. which must-not-build constraints apply,
4. the smallest implementation slice,
5. which user journey should be tested.

Do not implement until the plan is approved.

This changes the agent from a code generator into a scoped execution partner.

Not a strategist.

A disciplined implementer constrained by strategy.

---

What belongs in CLAUDE.md vs rules, hooks, and skills#

Do not put everything into CLAUDE.md.

Claude’s docs explicitly distinguish between memory, rules, skills, hooks, and settings. CLAUDE.md is context, not enforcement; hooks can execute commands at lifecycle points and provide more deterministic control; skills are better for repeatable workflows that should load only when relevant. (Claude)

Use the right layer:

Codex skills follow a similar idea of reusable workflows: OpenAI describes skills as packages of instructions, resources, and optional scripts that Codex loads when the task matches the skill, rather than keeping every workflow fully loaded all the time. (OpenAI Developers)

The rule:

Keep durable identity in memory. Put procedures in skills. Put enforcement in hooks/settings.

Do

• keep product thesis, ICP, wedge, and evidence goals in durable memory.
• move repeatable procedures into skills.
• use hooks/settings for enforcement.

Don't

• expect CLAUDE.md to block dangerous actions by itself.
• turn memory into a 1,000-line policy dump.

---

The ideal memory hierarchy#

For a serious AI-native SaaS project:

text
Product framing memory
        ↓
CLAUDE.md / AGENTS.md
        ↓
Path-scoped rules
        ↓
Skills for repeatable workflows
        ↓
Hooks/settings for enforcement
        ↓
CI/review gates for release control

This hierarchy matters because each layer has a different job.

• Product framing memory defines what deserves to be built.
• CLAUDE.md / AGENTS.md gives durable agent context.
• Rules provide local instructions by file/path.
• Skills encode repeatable workflows.
• Hooks/settings enforce non-negotiables.
• CI/review gates prevent unsafe release.

Do not ask memory to enforce what hooks should block. Do not ask hooks to explain product strategy. Do not ask skills to carry the project thesis.

Each layer should do its own job.

---

Where Gaplyze fits#

Gaplyze should sit before CLAUDE.md.

The founder may begin with a messy idea, partial PRD, competitor URL, internal note, or long strategy document. Gaplyze’s role is to turn that input into a structured project memory:

• stage
• reality envelope
• ICP and buyer
• target geography
• monetization posture
• evidence maturity
• strategic risks
• must-do and must-not-do conditions
• scoring
• strategic vectors
• blueprints
• roadmap

That memory can then become the foundation for the coding-agent context.

A natural workflow:

text
Raw idea / PRD / notes
        ↓
[Gaplyze](https://gaplyze.com) project framing + scoring
        ↓
Strategic vectors + blueprint
        ↓
Product Reality block in CLAUDE.md / AGENTS.md
        ↓
Claude Code / Codex implementation
        ↓
Playwright journey tests
        ↓
Evidence update
        ↓
Updated project memory and roadmap

This is the correct order.

Do not ask Claude Code to discover your business strategy by accidentally building too much.

---

A better CLAUDE.md template for founders#

md
# Product Reality

## Product thesis
[One paragraph: product, customer, pain, why now.]

## Stage and reality envelope
Stage:
Business ambition:
Funding posture:
Team/resource constraints:
Geography:

## Customer and buyer
Primary user:
Economic buyer:
Current alternative:
Switching trigger:

## Wedge
Current wedge:
Expansion later:
Not serving yet:

## Monetization
Pricing hypothesis:
Unit-cost risks:
Support burden risks:

## Evidence goal
This roadmap must validate:

## Must build now
- ...

## Must not build yet
- ...

# Engineering Reality

## Stack
- ...

## Commands
Typecheck:
Test:
Build:
E2E:

## Architecture rules
- ...

## Database rules
- ...

## Security rules
- ...

## Agent rules
- Plan before coding.
- Do not modify migrations without approval.
- Do not change billing logic without approval.
- Do not add dependencies without explaining why.
- Do not expand scope beyond Product Reality.

This is short enough to remain usable, but strong enough to shape behavior.

---

The anti-patterns#

The worst version of CLAUDE.md is not empty.

It is confidently detailed about code while silent about product reality.

---

Maintenance ritual: update memory when strategy changes#

A memory file is dangerous if it becomes stale.

Update product memory when:

• ICP changes
• pricing changes
• roadmap changes
• a feature is intentionally killed
• validation contradicts the original thesis
• a new constraint appears
• a customer segment is rejected
• the product moves from validation to growth
• the founder chooses bootstrap vs VC path

Do not update it for every small feature.

Update it when the agent’s future decisions should change.

That is the test.

---

The deeper principle#

AI coding agents do not only need instructions.

They need a hierarchy of truth.

At the top of that hierarchy should be product reality:

Who is this for? What pain matters? What are we trying to learn? What is the wedge? What must we not build? What constraints are real?

Only after that should come:

Which framework? Which folder? Which command? Which style rule?

A founder who writes only engineering memory gets faster implementation.

A founder who writes product memory gets more focused implementation.

That is the difference.

---

Closing#

Your CLAUDE.md is not just a developer convenience.

It is one of the first places where strategy becomes executable.

If it begins with code rules, the agent may build well but aim poorly. If it begins with product reality, every implementation plan has a better chance of serving the actual business bet.

The future of AI-native building will not belong only to founders who know how to use Claude Code or Codex.

It will belong to founders who know how to encode judgment into the systems that build for them.

Start with product reality.

Then let the agents code.