Durable Product Playbook

Durable Product Playbook

How one person (or a small team) plus an AI coding partner can grow an idea into a product that stays coherent, honest, and maintainable across hundreds of sessions — instead of decaying into a heap of contradictory one-off changes that no one, human or AI, can hold in their head.

This is a flexible skill: principles to adapt, not a rigid checklist to obey. The audience is the AI partner doing the building — but everything here is meant to be set up with the human and owned by both.

Why this exists

An AI partner is brilliant per-session and amnesiac across sessions. Each new session starts blind: it can't see last week's reasoning, the dead ends you already ruled out, or the line you swore never to cross. Left alone, this produces drift — the product slowly contradicts itself, re-litigates settled decisions, repeats failed experiments, and quietly overpromises because no single session remembers the promise you made to your users.

The fix is not a smarter model. It is infrastructure that survives context loss: a living manual the AI reads first, a memory of hard-won truths, a definition of "done" with automated guards, and a product spine of boundaries that no session is allowed to bend. Build that scaffolding once and every future session inherits your standards instead of guessing at them.

The playbook has six parts. A-B-D are how you work. C is what you refuse to compromise. E-F keep the surface and the collaboration itself from rotting.

• A. Collaboration infrastructure — the artifacts that make an amnesiac partner effective.
• B. Definition of Done + drift guards — how "finished" stays finished.
• C. Product discipline — honesty over hype; the soul of a tool people trust.
• D. Execution patterns — how features actually get built and shipped.
• E. Design-system consistency — one surface, not fifty hand-rolled ones.
• F. Working with the AI partner — meta-habits that compound.

Read the part you need. The reference files hold copy-paste templates — pull them in only when you're actually setting that piece up.

---

A. Collaboration infrastructure

The single highest-leverage move in AI-assisted development is writing down what the AI must know before it touches anything — and keeping that writing true.

A1. Make the project manual the AI's first read

Most projects have a README aimed at users. You also need a manual aimed at the AI doing the work. Not "what this product is" — but "the rules, the conventions, the map, and the traps." Put the non-negotiable boundaries (Part C) at the very top so no session can miss them.

A good manual answers, in order:

• Red lines — what this product must never do, stated as absolutes (see Part C).
• Conventions — the decisions already made (naming, colors, layout idioms, commit style) so the

AI matches the house style instead of inventing a new one each session.

• Code map — "want to change X? touch these files." This is the difference between a session that

edits the right three files and one that flails through the repo re-deriving the architecture.

• Known traps — the non-obvious gotchas that have already bitten you (a stale proxy env var, a

data source that publishes late, a deploy window you must avoid). Each trap written down is a future session saved from rediscovering it the hard way.

Keep it current. A manual that lies is worse than none — the AI will confidently follow a stale rule. Updating the manual is part of finishing work, not a separate chore (see Part B).

> Template: references/claude-md-template.md

A2. Add a navigation table so onboarding takes minutes

At the top of the manual, a tiny "looking for X? go here" table. New session, new contributor, future you at 2am — all oriented in under a minute. It costs five lines and saves the same fifteen-minute re-exploration every single session.

| Looking for...            | Go to                         |
| Capabilities overview     | README.md                     |
| 30-min onboarding         | docs/ONBOARDING.md            |
| Domain jargon             | docs/GLOSSARY.md              |
| Architecture / data flow  | docs/architecture.md          |
| Progress & TODO           | docs/ROADMAP.md               |

A3. Use memory for truths the code can't show

Some of the most valuable facts are invisible in the code: that you tried approach X and it failed (and why), that a rule exists because of a specific past incident, that a metric looks promising but doesn't survive validation. Code shows what is; memory preserves what you learned and decided.

Write these down as durable notes — one fact per note, with the why. The payoff is enormous:

• No repeated dead ends. "We already tried the aggressive variant; it backtested worse" stops the

AI from cheerfully rebuilding it next month.

• No re-litigating settled calls. A decision with its rationale recorded is a decision that stays

made.

• Negative results become assets. "This doesn't work, here's the evidence" is often more valuable

than another feature — record it with the same care.

Treat memory and the manual as a pair: the manual holds standing rules, memory holds the evidence and history behind them. Cross-link them.

A4. Turn repeated workflows into commands

Anything you explain more than twice — onboarding, the test routine, the deploy sequence, a "summarize where we are" recap — should become a named command (a slash command, a script, a make target). Encoding the workflow once means every future run is consistent and you stop paying the re-explanation tax. Good candidates: onboard, test, deploy (with preflight checks), recap, summary, and project-specific scaffolds ("add a new ").

---

B. Definition of Done + drift guards

A change isn't done when the code works. It's done when the project is still coherent after the change. Make that explicit, and automate the parts a machine can check.

B1. Write an explicit Definition of Done

State what "finished" means and make every session self-check against it before wrapping up. A typical bar:

1. Code + tests — new behavior has tests; the suite is green; if the UI changed, it builds.
2. Docs follow the code — added a scheduled job / data table / API / command? The docs that list

those are updated in the same change.

1. Roadmap updated — finished a unit of work? Tick it off, bump the milestone, adjust the TODO.
2. Commit cleanly — message in the house style, with whatever attribution convention you use.

The point isn't ceremony. It's that half-done work is invisible later — a feature with no test, a table with no doc entry, a finished task still marked open. Each of those is a small lie the next session will trip over.

> Full template: references/definition-of-done.md

B2. Separate machine-checkable facts from judgment, and automate the first kind

Some "done" criteria are mechanical: does every scheduled job appear in the schedule doc? Does every API route appear in the API doc? Does every data table have a doc entry? These you can verify with a script — a "docs doctor" that diffs reality against the docs and flags drift. Run it at the end of every change; wire it into a pre-commit hook that reminds (don't make it block — a guard that blocks on a false positive teaches people to bypass it).

Other criteria need judgment: is the roadmap honestly updated? Is this feature actually good? Those stay human/AI discipline — but at least you've shrunk the surface that relies on vigilance.

> Drift-guard setup (docs-doctor concept + pre-commit hook): references/definition-of-done.md

B3. Periodic self-audit

Drift accumulates slowly. A recurring "summarize what changed, what's the current state, where did docs drift, what's next" pass catches the slow leaks before they compound. Make it a command (A4) so it actually happens.

---

C. Product discipline — honesty over hype

This is the soul of the playbook. Tools people trust are built by teams that decided, up front, what they would never do — and held the line even when a feature request, or the AI's own helpfulness, pushed against it.

C1. Define the boundary first, and make it immutable

Before features, write down what the product refuses to do. State it as an absolute and put it at the top of the manual where no session can miss it.

> Example (a market-observation tool): "Only observe and notify. Never emit buy/sell signals, never > place orders, never claim an edge. The decision belongs to the user."

The boundary is what makes the product honest. It's also what makes it designable — a clear "no" turns a thousand fuzzy feature debates into a single test: does this cross the line?

C2. Reframe requests into the boundary — don't bend the boundary

Users (and the AI eager to please) will ask for things just past the line. The skill is to find the honest version that delivers the underlying value without crossing it — not to quietly relax the rule.

> Example: a user asks for "predict tomorrow's winners." Prediction crosses the line (it implies a > signal/edge). The honest reframe: show the observable structure — what's actually happening now, > ranked and explained — and let the user draw conclusions. Same value (insight), boundary intact.

When you reframe, say so plainly: "X would cross our line because…; here's Y, which gives you the same thing honestly." That transparency is itself trust-building.

C3. Quality gate over output volume — "an honest blank beats a padded page"

Set the bar for what's worth showing, and hold it even when that means showing nothing. Zero honest results is a feature, not a failure — it means the filter works. The failure mode is loosening the rule to fill space, which trains users to distrust everything you show.

When you return little or nothing, frame it as discipline, not breakage: "nothing cleared the bar today" reads as integrity; "the system found nothing" reads as malfunction. Same fact, opposite trust outcome.

C4. Earn claims with evidence

Don't claim a capability, an "edge", or a result until it's actually validated — and be loud about what doesn't work. An unproven claim is a debt that comes due the moment a user relies on it. Record negative results (Part A3) so the whole team, including future AI sessions, stops chasing what's already been disproven. "We looked; here's what we found, including the parts that failed" is more credible than any polished promise.

C5. Value-forward, honesty-as-footnote tone

Honest products often over-correct into apology — so hedged and disclaimered that users feel the tool doesn't believe in itself. The fix is ordering, not dishonesty:

• Lead with what the system did for the user — the work it did on their behalf, concretely.
• Demote caveats to a footnote — present, findable, but not the headline.
• Never use a fear posture. A blank result is "held to the standard," not "the system gave up."
• And never soften the actual boundary. Value-forward tone changes emphasis and order, never the

red line itself. If a thing is unproven, it still says so — just not as the first and loudest word.

The test: a user should finish reading feeling served and respected, not warned and scolded — and should still come away with an accurate picture of the limits.

---

D. Execution patterns

D1. Spec → Plan → Execute, sized to the task

For anything non-trivial, separate the thinking from the typing:

1. Brainstorm to a spec — agree on what and why before how. Cheap to change here.
2. Write a plan — bite-sized, ordered tasks with exact files and test-first steps.
3. Execute — one task at a time, tests first, review between tasks.

This keeps the AI from sprinting confidently in the wrong direction, and it gives you natural checkpoints. But size the process to the work (see D3).

D2. Fresh context per feature unit

Long-running sessions accumulate noise that degrades quality. For a substantial feature, prefer giving the work a clean, well-briefed context (a fresh session or a delegated sub-task) with exactly the information it needs — rather than piling it onto a context already crowded with unrelated history. You reason best about what you can hold in view at once.

D3. Calibrate process weight to the change

The full spec→plan→execute→review machinery is right for features. It is overkill for a one-line copy fix or a color tweak, and forcing it there just makes the human wait. Read the situation: heavy process for heavy changes, a lean fast path for small ones. Let the human steer the dial — some explicitly prefer the lean path and resent ceremony.

D4. Document the deploy runbook — including what not to do

Shipping is where tacit knowledge hides and bites. Write the exact steps down: build, transfer, restart, verify. Crucially, capture the timing constraints and footguns:

• Windows to avoid — if a scheduled job fires at a set time and won't back-fill, don't redeploy

across that window or you silently drop that run.

• Secrets handling — never paste passwords, keys, or root credentials into the conversation.

Read them on the server, don't print them. State this rule in the manual so every session inherits it.

• Verification — the one command that proves the deploy actually worked.

> Template: references/deploy-runbook-template.md

---

E. Design-system consistency

A product's surface rots the same way its code does — one bespoke layout, one off-palette color at a time. A little structure keeps it coherent.

E1. Single source of truth for design tokens

Colors, spacing, radii, typography — define them in one place and have everything consume them. Change the token, the whole surface follows. The anti-pattern is design values sprinkled across dozens of components, where "make the brand color warmer" becomes a scavenger hunt.

E2. Respect domain semantic conventions — don't let framework defaults override meaning

Many domains carry color/semantic conventions that mean something specific to users, and a UI framework's defaults may contradict them. Pin the domain meaning explicitly and keep it separate from incidental UI semantics.

> Example: in Chinese markets, up is red and down is green — the opposite of many Western > frameworks. Price direction must follow the domain convention; meanwhile the framework's own > success-green / danger-red (for buttons, errors, status) is a different axis and must not get > entangled with price color. Two conventions, both consistent, never crossed.

E3. Name your layout idioms and reuse them

When you find a layout pattern that works (an equal-height board of scrollable cards, a pinned toolbar, a standard page header), give it a name and a reusable implementation, then use it everywhere. Hand-rolling each page's layout from scratch guarantees they drift apart and that "make every page consistent" becomes an endless retrofit. A named idiom is a decision you make once.

E4. Honest hierarchy applies to the visual layer too

Part C's "value-forward, caveats demoted" isn't only about words — it's about visual weight. A disclaimer rendered in alarming blood-red at the top of the page shouts; the same words as a calm footnote inform. Match the visual emphasis to the honest priority.

---

F. Working with the AI partner

Meta-habits that make the human↔AI loop tighter. These are as much for the human to know as the AI.

F1. Tell the AI where it's blind

The AI can't see what it can't see — rendered output, a screenshot it wasn't given, the state of a machine it can't reach. When a task depends on something outside the AI's view, say so and set up the hand-off: *"I can't see the rendered page — after each change, I'll ask you to con

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wuzefang
• Source: wuzefang/claude-skills
• License: MIT
• Homepage: https://github.com/wuzefang/claude-skills

Install and usage instructions live in the source repository linked above.