Design doc google style
Skill Amey-Thakur/AI-SKILLS/skills/big-tech-processes/design-doc-google-style
Plug-and-play skills and prompts for every AI coding agent
npx -y skills add Amey-Thakur/AI-SKILLS --skill design-doc-google-styleAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- 19 days oldThe repository was created 19 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
- 4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Write a Google-style design doc that argues a decision through context, goals, and rejected alternatives before code is written. Use when a change is large enough that picking the wrong approach is expensive to undo.
SKILL.md
3.0 KB, as published. Nobody here has run it
Google-style design doc
At Google the design doc is where an engineer reasons in prose before touching code, and where reviewers kill a flawed approach while changing it is still cheap. A doc that lists only the chosen design, skipping the argument for it, is a status update in a decision's clothing: no reader can tell whether the author weighed anything else or simply picked the first idea that compiled.
Method
- Open with context, hold back the solution. The first section states the problem, who has it, and what exists today. An engineer three teams away should grasp why the work matters before meeting a single class name. If you cannot describe the problem without naming your fix, you have not understood it yet.
- Split goals from non-goals in plain lists. Write what the design must achieve, then the tempting adjacent problems you are deliberately leaving alone. Non-goals are the section reviewers cite most: they stop scope creep and keep each meeting from relitigating the boundary.
- Argue the alternatives considered, do not list them. Give each serious option a subsection: how it works and the specific reason you rejected it. Two options waved off in one line each signal an author who decided first and documented after. Include "do nothing" whenever it is plausible.
- Make the chosen design concrete enough to attack. Data model, API shapes, the failure and rollback path, and the migration from today's state. Vague designs pass review and fail in code because reviewers had nothing sharp to push against.
- Budget the cross-cutting costs up front. Add a short pass on security, privacy, latency, and on-call load. Reviewers from those areas read straight to their paragraph, and a missing one bounces the doc back before the design is even discussed.
- Circulate for comment, then hold the review. Share the doc days ahead, let reviewers leave inline comments, and resolve each in the doc before or during a scheduled review with the tech lead and affected teams. Approval is an owner marking it LGTM, not silence on a thread.
Litmus tests
- Could a reviewer who dislikes your choice find the paragraph that answers their objection, or would they have to raise it live?
- Does every rejected alternative carry a reason specific to it, not boilerplate that would fit any option?
- Are the non-goals load-bearing, so that deleting one would widen scope?
Boundaries
A one-day bug fix needs no doc: the ritual pays off only when a wrong approach costs more than writing the argument does. Follow the team's template and approval convention where one exists, and defer to the rfc-process skill when the decision needs a wider, time-boxed audience than a single review can gather.