Skip to main content

Engineering and Product Templates

Templates make it easier to think and design clearly, and rule out blind spots. They also introduce new blind spots — the structure itself is an opinion about what matters, and a template tells you what to write about but not what to think. The point of a good template isn't to produce a document; it's to force a specific kind of conversation before work starts.

Why templates work​

Three reasons, in roughly the order I've found them to matter:

  1. They front-load disagreement. Most project failures aren't about execution; they're about two people agreeing on a label (e.g. "ship the payments feature") while silently disagreeing about the content behind it. A filled-in template drags that disagreement into writing, where it's cheap to resolve, before it becomes expensive to unwind in code.
  2. They externalize memory. A year from now, no one will remember why you picked a gRPC transport over REST or why a metric threshold was set at 95% rather than 99%. A template with a "decision drivers" or "alternatives considered" section turns ephemeral debate into searchable history.
  3. They compress onboarding. New hires can read three ADRs and understand more about a system's evolution than from a week of meetings. Every template is a form of institutional knowledge deposit.

When templates hurt​

Templates are a cost, not a free good. They hurt when:

  • The cost of producing the doc exceeds the cost of the decision itself. Writing a 2-page ADR for a 10-line config change is a tax on momentum.
  • The template becomes the goal. If reviewers ask "did you fill in section 4.2?" instead of "is this decision correct?" the ritual has replaced the thinking.
  • The template's opinions don't match the work. An ADR assumes a discrete decision; it's the wrong shape for ongoing trade-offs that get re-litigated every quarter.

Rule of thumb: templates are for decisions that will survive the person who made them. If the decision is yours alone and fully reversible tomorrow, skip the template.

The templates​

1. PRFAQ — Press release and frequently asked questions​

Amazon's mechanism for "working backwards from the customer." You write the press release for a product before you build it. It forces a specific kind of honesty: if the press release is boring, the feature is boring. Use this when you're kicking off a new product or a major feature and need the team aligned on who it's for before anyone writes a spec.

Best for: product kickoff, feature prioritization, go/no-go at the idea stage. Not for: incremental changes to an existing product.

2. ADR — Architecture decision record​

A short, structured note capturing an architectural choice: what the problem was, what options you considered, what you picked, and why. ADRs are cheap to write and enormously valuable six months later when someone asks "why did we do it this way?" They work best when you keep them immutable — if a decision changes, write a new ADR that supersedes the old one.

Best for: any architecture choice that affects more than one team, or one person for more than six months. Not for: routine implementation choices, library selection for a single service, or work that's easily reversible.

3. OKR — Objectives and key results​

The classic goal-setting template popularized by Intel and Google. The structure is deceptively simple — one ambitious objective, three to five measurable key results — but the discipline of writing KRs that are objectively verifiable (no "improve" or "optimize") is where the value lives. OKRs are a forcing function for prioritization; if everything is an OKR, nothing is.

Best for: team-level or company-level quarterly/annual planning. Not for: individual contributor task lists, engineering backlogs, or anything that changes faster than quarterly.

4. Eng Design Doc​

Longer and more free-form than an ADR. Where an ADR captures a decision, a design doc captures a design — the full system diagram, data models, API contracts, failure modes, migration plan, and open questions. I use design docs for any project large enough that I couldn't hold the whole thing in my head at once. The test is: if I got hit by a bus tomorrow, could another engineer continue from this doc? If not, the doc isn't done.

Best for: new services, cross-team integrations, non-trivial refactors, anything involving data migration. Not for: single-pull-request changes or well-understood patterns.

5. GitHub Issue and PR​

The lowest-ceremony templates in this list, but the ones most abused. A good issue template forces a reporter to separate symptoms, reproduction steps, and expected behavior — without which a bug is just vibes. A good PR template asks "what changed, why, and how did you test it?" in that order, because every reviewer I know reads the "what" before the "why" and the "why" before the diff.

Best for: every repo. Even a three-field template (Context, Change, Test Plan) returns its cost on the first review. Not for: personal sandboxes where you're the only contributor.

6. Investment Memo​

Originally a VC artifact; increasingly useful for any significant capital allocation decision inside a company. The discipline is similar to a PRFAQ — write the thesis before the spend — but the structure is heavier: explicit financial scenarios, risk/mitigation pairs, and a post-investment review cadence.

Best for: VC investment decisions, M&A, internal R&D bets, large procurement decisions. Not for: tactical spend decisions or anything under your discretionary authority.

Choosing between them​

A rough decision tree:

  • Is this a new product or major feature? PRFAQ.
  • Is this an architecture choice with long-term consequences? ADR.
  • Is this a multi-month engineering project? Eng Design Doc.
  • Is this a goal for the quarter? OKR.
  • Is this a significant bet of money? Investment Memo.
  • Is this a bug report or code change? Issue / PR template.

The worst thing you can do is use the wrong template — a PRFAQ for a library upgrade, or an ADR for a product kickoff. A mismatched template doesn't just waste time; it quietly pushes the thinking in the wrong direction.

See also​

Want to keep learning more?

About Tian Pan

I'm Tian Pan, an engineer-founder focused on agentic engineering — building autonomous AI systems and scaling engineering teams. I write practical guides on system design, technical leadership, and shipping with AI agents. Previously an early engineer at Uber, Brex, and IoTeX.

Profile image of Tian Pan's dog