product-mode

Give your coding agent product judgment before it starts building.

Sohaib Thiab Subscribe
Star on GitHub Full rules
Install 
if [ -e CLAUDE.md ]; then
  echo "CLAUDE.md already exists. Merge the guidelines into it instead."
else
  curl -fL https://raw.githubusercontent.com/sohaibt/product-mode/main/CLAUDE.md -o CLAUDE.md
fi

Run it from the project root. It refuses to overwrite an existing file. For an agent that reads AGENTS.md, change both CLAUDE.md to AGENTS.md.

Then start a fresh agent session and try

Add a dashboard to our SaaS app. Before coding, help me frame the problem, surface unknowns, choose the smallest useful scope, and define how we'll know it worked.

Source sohaibt/product-mode

What it does

product-mode is a drop-in CLAUDE.md / AGENTS.md for Claude Code, Cursor, Codex, and any coding agent that reads one. It targets the mistake that costs product teams most: shipping the wrong thing, well.

Karpathy's guidelines fix how agents write code. product-mode adds the missing layer: problem framing, scope discipline, tradeoffs, outcome measurement, and decision logging, applied before the code gets written.

#PrincipleWhat it prevents
1Frame the Problem Before the SolutionBuilding for the wrong user
2Make Assumptions & Unknowns VisibleSilent guessing
3Ship the Minimum Viable ChangeScope creep, gold-plating
4Name the TradeoffsInvisible costs, political decisions
5Define Done by Outcome, Not Output"Merged" mistaken for "done"
6Instrument Before You ShipShipping blind
7Log the Decision, Flag ReversibilityRepeating mistakes, calcifying defaults

Before any non-trivial change, the agent fills a five-box pre-flight checklist: Problem, Why now, Scope, Primary metric, and Reversibility. If a box is empty, it fills it or says out loud that it is going ahead without it.

The full rules live in one file: CLAUDE.md on GitHub.

When to reach for it

Not every change needs all seven principles. The file opens with this table, so the agent scales the rigor to the change:

Change typeApply
Typo, comment, obvious one-linerNone. Just do it.
Bug fix, small internal refactorPrinciples 2, 3, 5
New user-facing featureAll seven
Architecture, pricing, public API, data modelAll seven + explicit one-way-door sign-off

The goal is fewer costly mistakes on non-trivial work, not ceremony on trivial work.

What it looks like

Three worked examples. They are authored teaching scenarios, not model transcripts or measured results.

Add a dashboard

Request
"Add a dashboard to our SaaS app with charts, filters, and export."
Asks first
Which user needs this, and what decision will they make after looking at it?
Smallest scope
A list of overdue jobs, sorted by age, linking to the existing job detail page.

Full example

Build a complete referral system

Request
"Build referrals with invite codes, credits, leaderboards, fraud detection, and an admin dashboard."
Asks first
What evidence says customers want to refer others, and what is the smallest pilot that would test it?
Smallest scope
A small, opt-in referral pilot with a simple way to record introductions. No rewards engine yet.
Illustrative referral pilot: start with the feature request, identify unknown demand, run an opt-in pilot, and measure referred-team activation.
Test referral demand before building rewards infrastructure. Authored example, not a model transcript or measured outcome.

Full example

Add an onboarding checklist

Request
"Add an onboarding checklist so more users activate."
Asks first
What observable action means the user received value, and how often does it happen today?
Smallest scope
Guide users to one existing action that represents first value, with a way to resume it later.

Full example

It's working if

  • Fewer rebuilds because "we shipped the wrong thing."
  • Assumptions get challenged before code, not in review.
  • Tradeoffs appear in writing, not just in Slack threads.
  • Every shipped feature has a metric attached, checked on a date.
  • The decision log is the first thing new teammates read, and it's useful.

Common questions

Do I need to install anything?
No. The instructions are a text file your agent reads. The CLI is optional. It saves checklists and decision logs, and needs Node.js 20.19 or newer.
I already have a CLAUDE.md. Will this overwrite it?
No. The install command refuses to overwrite an existing file. Copy the guidelines you need into your file and resolve any conflicts. The merge guide walks through it.
Which agents does it work with?
Claude Code, Cursor, Codex, and any coding agent that reads CLAUDE.md or AGENTS.md. Both files have the same content.
Will it slow down small changes?
It should not. Typos and one-liners skip the rigor. The optional product-mode trivial command checks your changes and tells you if the full checklist applies.
Are the examples real results?
No. They are authored scenarios. To test it on your own work, send the same request in fresh sessions with and without the guidelines. Here is the comparison protocol.
Is it free?
Yes. MIT license. Fork it, adapt it, make it your team's own.

Where it fits

product-mode is the thinking layer. It decides what is worth building. These open-source tools are the doing layers:

strategy-mcp
MCP server that gives Claude 12 product strategy frameworks as tools (RICE, JTBD, assumption mapping, TAM/SAM/SOM, Wardley).
founder-mode
Claude Code plugin that turns it into an AI co-founder: strategy review, competitor scan, stress-test, stakeholder updates.
agent-pm
Claude Code plugin with 12 commands for building AI agent products, from "should this even be an agent?" to production readiness.

Want your team working like this? Book a workshop.