Skip to content

skillDocumentation

Design Doc Writing

Drafts a design doc with goals, non-goals, alternatives considered and a rollout plan, grounded in the current code before proposing anything.

npx workspacetemplates add design-doc-writing --tool claude-code

Writes 1 file to .claude/skills/design-doc-writing/

.claude/skills/design-doc-writing/SKILL.md29 lines · 1.6 KBFile
---
name: design-doc-writing
description: Drafts a design doc with goals, non-goals, alternatives considered and a rollout plan, grounded in the current code before proposing anything.
---

# Design doc writing

A design doc is a decision record, not a sales pitch. Make the trade-offs visible.

## Steps

1. Restate the problem in two sentences with who is affected and the evidence it is real (an incident, a metric, a support count). Ask the user for anything you cannot find.
2. Read the current implementation of the area. Summarize how it works today with file references; do not propose from assumptions.
3. Write **Goals** and **Non-goals**. Non-goals must be things a reader might reasonably expect, such as "no migration of historical data".
4. Write **Proposal**: the design in enough detail to estimate it. Cover data model, interfaces, failure modes, security and privacy impact, and effect on performance and cost.
5. Write **Alternatives considered**: at least two real options, including "do nothing", each with the reason it lost.
6. Write **Rollout**: phases, feature flag, migration steps, how to measure success, the rollback trigger and the rollback steps.
7. Close with **Open questions** and **Risks**, each with an owner or a way to resolve it.

## Rules

- Quantify where possible (requests per second, rows, latency, cost).
- Keep it to 2 to 4 pages; move detail into an appendix.
- Do not hide a weakness; state it and say how you would handle it.
- Never mark a question as resolved without evidence.

## Report

The doc path, the decisions you need from the user, and the claims you could not verify.

What it does

A design doc earns its keep by forcing the hard questions before the code exists. This skill makes the agent study the present system first, then lay out the problem, the options and the cost of each, instead of defending the first idea.

The draft names what it will not do, shows at least two real alternatives, and ends with a rollout and rollback plan a reviewer can poke at.

Example

you › Write a design doc for moving session storage from cookies to Redis

agent › Drafted docs/design/session-store.md (3 pages). Goals: revocable sessions, under 5 ms lookup. Non-goals: moving to JWT. Alternatives: signed cookies, Postgres table, do nothing. Rollout: dual-write for one week behind a flag. Needs your input: expected peak concurrent sessions, which I could not find.

Questions

Does it pick the winning option for me?
It recommends one and shows why, but the alternatives stay in the doc so reviewers can disagree with the reasoning.
How long will the document be?
Two to four pages by default. Longer detail goes to an appendix so the decision stays readable.
  • API Documentation

    SkillDocumentation

    Free
  • Architecture Decision Records

    SkillDocumentation

    Free
  • Code Comments Docstrings

    SkillDocumentation

    Free
  • Diagram as Code

    SkillDocumentation

    Free