product-mode

Give your coding agent product judgment before it starts building.

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.

The PM-team counterpart to andrej-karpathy-skills. Credit to @karpathy for naming the failure modes that inspired this work.

Recent improvements

• 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.
• 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.
• Checks you can inspect: six authored evaluation cases for the product guidance, plus CI 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.

The updated instruction files are available now through the quick start below. The CLI fixes are merged on GitHub; see CLI release availability before installing from npm.

Quick start: add the instructions

No npm install is needed for the instruction files.

If you already have a CLAUDE.md or AGENTS.md: open CLAUDE.md or 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 to preserve conventions, resolve conflicts, and test the result.

See the thinking in practice

These are illustrative worked examples, not model transcripts or measured performance claims.