Skip to content
Back to search

product-mode

The most expensive bug in AI-assisted building is shipping the wrong thing, well. A CLAUDE.md for PM + eng teams using Claude Code- 7 principles for problem framing, scope, tradeoffs, and outcome measurement. Built on @karpathy's observations.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/sohaibt/product-mode with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/sohaibt/product-mode'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sohaibt--product-mode/badge.svg)](/listings/sohaibt--product-mode)

HTML

<a href="/listings/sohaibt--product-mode"><img src="/api/listings/sohaibt--product-mode/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

No npm install is needed for the instruction files.

**If you already have a `CLAUDE.md` or `AGENTS.md`:** open [CLAUDE.md](./CLAUDE.md) or [AGENTS.md](./AGENTS.md), copy the guidelines you need into your existing file, and resolve any conflicting instructions. Keep your project context and coding conventions. Commit or back up your current file before editing.

**For a project without `CLAUDE.md`:** run this from the project root. It refuses to overwrite an existing file.

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

For an agent that reads `AGENTS.md`, use the same command with both occurrences of `CLAUDE.md` changed to `AGENTS.md`. Check your agent's instructions for supported file names and locations.

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.

Look for an explicit user and problem, visible assumptions, a limited first step, a success measure, and a reversibility check. Supply missing evidence; the file cannot know your users or business on its own.

Already have project instructions? Follow the [step-by-step merge guide](./guides/add-to-existing-instructions.md) to preserve conventions, resolve conflicts, and test the result.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 274 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # product-mode
  2. ![product-mode](./banner.png)
  3. **Give your coding agent product judgment before it starts building.**
  4. Free, MIT-licensed instructions for framing the problem, cutting scope, naming tradeoffs, and defining success. A drop-in `CLAUDE.md` / `AGENTS.md` for Claude Code, Cursor, Codex, and any coding agent that reads one. The CLI is optional.
  5. The PM-team counterpart to [andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills). Credit to [@karpathy](https://x.com/karpathy) for naming the failure modes that inspired this work.
  6. ## Recent improvements
  7. - **Slash commands in the agent chat (1.1.0):** `product-mode init` installs `/preflight` and `/decision`, so the agent drafts the checklist or decision record from the conversation and saves it to `.product-mode/`. Works in Claude Code, Codex (`$preflight`), and Cursor. See [Usage](#initialize-once-per-project).
  8. - **Questions that move the work forward:** inspect existing context first, ask about material decisions, and match unknowns to evidence, a decision, a prototype, or an experiment. Continue authorized, reversible work once the next useful step is clear.
  9. - **More conservative CLI advice:** only small edits to existing ordinary documentation can automatically qualify as trivial. Code and agent instructions require review; failed commands return a nonzero status, and interactive commands explain when a terminal is required.
  10. - **Checks you can inspect:** [six authored evaluation cases](./examples/uncertainty.md) for the product guidance, plus [CI](./.github/workflows/ci.yml) covering lint, instruction-file consistency, and CLI/package tests on Node 20.19, 22, and 24. The cases are prompts for comparison, not measured evidence of better agent decisions.
  11. The updated instruction files are available through the quick start below. The CLI fixes ship in `product-mode@1.0.3` on npm.
  12. ---
  13. ## Quick start: add the instructions
  14. No npm install is needed for the instruction files.
  15. **If you already have a `CLAUDE.md` or `AGENTS.md`:** open [CLAUDE.md](./CLAUDE.md) or [AGENTS.md](./AGENTS.md), copy the guidelines you need into your existing file, and resolve any conflicting instructions. Keep your project context and coding conventions. Commit or back up your current file before editing.
  16. **For a project without `CLAUDE.md`:** run this from the project root. It refuses to overwrite an existing file.
  17. ```bash
  18. if [ -e CLAUDE.md ]; then
  19. echo "CLAUDE.md already exists. Merge the guidelines into it instead."
  20. else
  21. curl -fL https://raw.githubusercontent.com/sohaibt/product-mode/main/CLAUDE.md -o CLAUDE.md
  22. fi
  23. ```
  24. For an agent that reads `AGENTS.md`, use the same command with both occurrences of `CLAUDE.md` changed to `AGENTS.md`. Check your agent's instructions for supported file names and locations.
  25. Start a fresh agent session and try:
  26. > 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.
  27. Look for an explicit user and problem, visible assumptions, a limited first step, a success measure, and a reversibility check. Supply missing evidence; the file cannot know your users or business on its own.
  28. Already have project instructions? Follow the [step-by-step merge guide](./guides/add-to-existing-instructions.md) to preserve conventions, resolve conflicts, and test the result.
  29. ## See the thinking in practice
  30. These are **illustrative worked examples**, not model transcripts or measured performance claims.
  31. | Request | What the example works through |
  32. |---|---|
  33. | [“Add a dashboard”](./examples/dashboard.md) | Clarify whose decision the dashboard supports before choosing charts. |
  34. | [“Build a complete referral system”](./examples/referrals.md) | Separate testing referral demand from building rewards infrastructure. |
  35. | [“Add an onboarding checklist”](./examples/onboarding.md) | Define activation and measurement before treating checklist completion as success. |
  36. [Run your own comparison](./examples/README.md) using the same request in fresh sessions with and without the guidelines.
  37. ## Resolve uncertainty without getting stuck
  38. Product-mode checks existing context before asking questions. It asks about decisions that change the work, groups independent questions, and waits for prerequisite answers before discussing dependent choices.
  39. Different unknowns need different next steps: missing facts need evidence, product choices need a decision, UX questions may need a prototype, and outcome hypotheses need an experiment. Once the next useful step is clear, proceed with authorized, reversible work and record how remaining assumptions will be tested.
  40. Use the [evaluation cases](./examples/uncertainty.md) to check whether your agent makes those distinctions, avoids invented evidence, and keeps routine work moving. These are authored cases, not measured results. Deeper product challenge sessions should be requested explicitly.
  41. ---
  42. ## The Two Problems
  43. Karpathy named the problem for engineers working with LLMs:
  44. > "The models make wrong assumptions on your behalf and just run along with them... They don't manage their confusion, don't seek clarifications, don't surface inconsistencies, don't present tradeoffs, don't push back when they should."
  45. His CLAUDE.md fixes this for solo engineers. It's excellent.
  46. But there's a failure mode it doesn't touch, the one that kills product teams:
  47. > **Shipping the wrong thing, well.**
  48. A beautifully implemented feature for a problem that doesn't matter is still waste. And in mixed PM + engineering teams working with Claude Code, that's the more expensive mistake.
  49. **product-mode** adds the missing layer: problem framing, scope discipline, tradeoff articulation, outcome measurement, and decision logging, applied *before* the code gets written.
  50. ---
  51. ## The Seven Principles
  52. | # | Principle | What it prevents |
  53. |---|---|---|
  54. | 1 | **Frame the Problem Before the Solution** | Building for the wrong user |
  55. | 2 | **Make Assumptions & Unknowns Visible** | Silent guessing |
  56. | 3 | **Ship the Minimum Viable Change** | Scope creep, gold-plating |
  57. | 4 | **Name the Tradeoffs** | Invisible costs, political decisions |
  58. | 5 | **Define Done by Outcome, Not Output** | "Merged" mistaken for "done" |
  59. | 6 | **Instrument Before You Ship** | Shipping blind |
  60. | 7 | **Log the Decision, Flag Reversibility** | Repeating mistakes, calcifying defaults |
  61. Plus a **pre-flight checklist** (5 questions before any non-trivial change) and a **when-to-skip-this-rigor** table: because not every typo needs a decision log.
  62. Full file: [`CLAUDE.md`](./CLAUDE.md). Same file, other name: [`AGENTS.md`](./AGENTS.md).
  63. ---
  64. ## Optional CLI: save checklists and decisions
  65. The instruction files work on their own. The CLI provides interactive commands that save checklists and decision logs in your project.
  66. ### Installation
  67. ```bash
  68. # Run without installing
  69. npx product-mode init
  70. # Or install it globally
  71. npm install -g product-mode
  72. ```
  73. Requires Node.js 20.19 or newer.
  74. ### Usage
  75. #### Initialize (once per project)
  76. ```bash
  77. product-mode init
  78. ```
  79. Creates `.product-mode/checklist/` and `.product-mode/decisions/`, and appends a "Prior Decisions & Checklists" section to your `CLAUDE.md` / `AGENTS.md` (if present) so agents read existing decisions before starting non-trivial work. Safe to re-run.
  80. `init` sets up artifact storage and references. Add the product guidelines separately using the quick start above.
  81. `init` also installs three slash commands for your agent chat. It never overwrites a command that already exists.
  82. | Command | What the agent does |
  83. |---|---|
  84. | `/preflight [work]` | Drafts the pre-flight checklist from the conversation, asks only about missing answers, and saves it to `.product-mode/checklist/` |
  85. | `/decision [title]` | Drafts a decision record from the conversation and saves it to `.product-mode/decisions/` |
  86. | `/product-review [plan, file, or PR]` | Checks a plan or code change against the seven principles and reports each gap with its evidence and smallest fix. Read-only |
  87. The commands are installed in `.claude/skills/` (Claude Code) and `.agents/skills/` (Codex and Cursor). In Codex, type `$` instead of `/` (for example, `$preflight`). Commit them so your team gets them too.
  88. #### Pre-flight Checklist
  89. Run before starting any non-trivial work:
  90. ```bash
  91. product-mode checklist
  92. # Or with work description
  93. product-mode checklist "Add user profile feature"
  94. ```
  95. This will prompt you through the 5-question pre-flight checklist and save your answers to `.product-mode/checklist/`.
  96. #### Decision Logging
  97. Log important decisions following Principle #7:
  98. ```bash
  99. product-mode decision
  100. # Or with title
  101. product-mode decision "Choose database technology"
  102. ```
  103. Creates a structured decision log in `.product-mode/decisions/`.
  104. #### Trivial Change Detection
  105. Check if your changes are trivial (can skip full rigor):
  106. ```bash
  107. product-mode trivial
  108. # Or check specific files
  109. product-mode trivial src/app.js src/utils.js
  110. ```
  111. Only small edits to existing ordinary documentation (`.md`, `.txt`, `.rst`, `.adoc`; at most 10 added/deleted lines across the diff) can qualify for lighter rigor. Code, executable Markdown (`.mdx`), agent instructions, sensitive files, new/deleted files, renames, mode changes, binary files, and unsupported diffs require review. Even a short string edit or whitespace change can alter behavior.
  112. Checks staged changes first, or unstaged changes if no matching changes are staged. Explicit file paths use the same rule. Untracked files are not included. The result is advisory: use the guidelines' change-type table to choose the appropriate rigor. A small bug fix can use Principles 2, 3, 5; new features and costly commitments need the full checklist.
  113. `checklist` and `decision` require an interactive terminal. Agents can write Markdown entries directly in the same folders. Command failures exit with a nonzero status; a successful `trivial` assessment exits with zero for either recommendation.
  114. ### Example Workflow
  115. ```bash
  116. # 1. Think about starting work
  117. product-mode checklist "Implement dark mode toggle"
  118. # → Answers questions and saves checklist
  119. # 2. Do the work
  120. # ... write code ...
  121. # 3. Check if changes are trivial before committing
  122. product-mode trivial
  123. # → If non-trivial, consider running checklist again
  124. # → If trivial, you can proceed with lighter rigor
  125. # 4. Log important decisions
  126. product-mode decision "Dark mode implementation approach"
  127. # → Logs your choice of CSS variables vs separate stylesheet, etc.
  128. ```
  129. ---
  130. ## Who This Is For
  131. - **PMs who vibe-code** with Claude Code, Cursor, or Lovable and want their AI to think like a product partner
  132. - **Engineering teams** working alongside product, tired of re-shipping because the problem was wrong
  133. - **Solo founders** building SaaS who want guardrails against their own scope creep
  134. If you're shipping with AI and your bottleneck is *what to build*, not *how to build it*, this is for you.
  135. ---
  136. ## Why This Exists
  137. I've spent 20+ years in product leadership (Booking.com, Foodics, Eneco, Tamatem Games). I am now building products, one specifically to help solve the problem of not building the right thing (not announced yet) and write about Product Management and AI-assisted product building at [Mastering Product HQ](https://masteringproducthq.substack.com).
  138. Every week I see the same pattern: teams using Claude Code to ship faster, and shipping the wrong thing faster. Karpathy nailed the engineering half. This file tries to nail the product half.
  139. From Karpathy: *"LLMs are exceptionally good at looping until they meet specific goals… Don't tell it what to do, give it success criteria and watch it go."*
  140. From product: *the hardest bug to fix is shipping the wrong thing, well.*
  141. ---
  142. ## How to Know It's Working
  143. - Fewer rebuilds because "we shipped the wrong thing."
  144. - Assumptions get challenged *before* code, not in review.
  145. - Tradeoffs appear in writing, not just in Slack threads.
  146. - Every shipped feature has a metric attached, checked on a date.
  147. - The decision log is the first thing new teammates read - and it's useful.
  148. ---
  149. ## Customization
  150. These principles are meant to be merged with your project's own CLAUDE.md. Add project-specific context below the seven principles:
  151. ```markdown
  152. ## Project-Specific Context
  153. - Our primary user is [X]
  154. - Success metric for this quarter is [Y]
  155. - We intentionally avoid [Z]
  156. ```
  157. ---
  158. ## Tradeoff Note
  159. These guidelines scale review to the cost of being wrong. Routine fixes can proceed with lighter rigor; new features and costly commitments need more evidence and explicit tradeoffs. Use the file's *when to skip this rigor* table, and stop questioning once the next authorized, useful step is clear.
  160. The uncertainty guidance draws on Matt Pocock's [grill-me / grilling skills](https://github.com/mattpocock/skills) and [explanation of when to prototype](https://www.aihero.dev/skills-grill-me), adapted for product evidence, scope, and outcome validation.
  161. ---
  162. ## More From the Same Author
  163. product-mode is the *thinking* layer. These are the *doing* layers:
  164. | Tool | What it does |
  165. |---|---|
  166. | [strategy-mcp](https://github.com/sohaibt/strategy-mcp) | MCP server that gives Claude 12 product strategy frameworks as tools (RICE, JTBD, assumption mapping, TAM/SAM/SOM, Wardley) |
  167. | [founder-mode](https://github.com/sohaibt/founder-mode) | Claude Code plugin that turns it into an AI co-founder: strategy review, competitor scan, stress-test, stakeholder updates |
  168. | [agent-pm](https://github.com/sohaibt/agent-pm) | Claude Code plugin with 12 commands for building AI agent products, from "should this even be an agent?" to production readiness |
  169. ---
  170. ## License
  171. MIT. Fork, adapt, make it your team's own. If it helps, a star is appreciated.
  172. ---
  173. *Inspired by [andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) and [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls.*

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.