Skip to main content
Two people read a spec. The reviewer, who wants to know why you did not just do the obvious thing, and the engineer who picks it up on Monday and finds the one interesting question still open. Write it from what customers said and what the repo already does:
Every line points at something: a customer who said it, or a file that already does it.

​
The format is Google’s design doc

Context and scope, goals and non-goals, the design, alternatives considered. That is the shape Google’s engineers write in, and one rule is what makes it a format rather than a template: document trade-offs, not steps. If a decision had no real alternative, skip it and write the code. The payoff is not the document. Problems surface while they are still cheap to fix, because the argument happens before the code exists. The people who would have blocked you in review argue in the doc instead, and the argument is written down. Security, privacy and observability get decided rather than discovered. And when someone inherits the system a year from now, the first thing they go looking for is the design doc. Alternatives Considered is the section that earns its keep, and the one most templates drop. It answers “why didn’t you just…” before anyone says it out loud, which is the question that turns a thirty-minute review into a second meeting. The rest is what a spec needs to survive your codebase: acceptance criteria in the style your tests already use, edge cases only where the answer changes what gets built, rollout, and the questions genuinely still open.

​
It reads your repo first

Before designing anything it finds the files of the same shape as the thing you are building, your data model and migration conventions, your route handlers, and the way your tests are written, so the acceptance criteria come out in the format your team already uses. You pick which repos it searches.

​
It will not fill a gap with a guess

If a question can be answered by reading the code, it gets answered with a line number instead of landing in Open Questions. If the feature has no customer evidence behind it at all, the skill stops and tells you, rather than writing a confident spec on an empty PRD reference. The two rules that catch the most in review: a content type a customer could reasonably expect and is not getting becomes an explicit non-goal rather than a buried edge case, and any step sitting between “connected” and “data appears” has to show up in the system flow. That second one is where first-time users land on an empty screen with nothing telling them they still need to invite a bot.