AI System Design Doc Generator

There is a particular failure mode in software projects that nobody catches early because nobody is looking for it: the design that was never written down. The team agreed on the broad shape of the system in a meeting, the engineer who took notes wrote a summary in a document nobody opened, and then everyone started implementing against the version of the design that was in their own head. Six weeks later, the system that emerges does not match anyone's mental model exactly. The frontend assumes one shape of API, the backend assumes another, the data team assumed a different write pattern, and the integration phase reveals that everyone was building toward a different system. The cost of this drift is paid in integration debt, redo work, and the kind of grumpy compromise that ships features that satisfy no one.

The remedy is the system design document, written before implementation begins, reviewed by everyone who will build against it, and accepted as the source of truth for the system being built. The discipline is well-known and rarely practiced for the same reason scoping and threat modeling are rarely practiced: the cost is high (someone has to write the document), the immediate reward is invisible (the document is not a feature), and the value only shows up later when the integration phase goes smoothly because everyone built against the same spec. Mainstream AI coding tools make this skip easier because they let teams jump straight to code. The /spine-design skill is built to make the design discipline cheap enough that skipping it stops being the default.

Why generalist AI skips the design step

Ask Cursor or ChatGPT to design a service and you get something that resembles a design but is shaped by chat conventions. The output reads like a list: "the service has three components, here is each component, here is the API." The list is not wrong; it is also not a design document, because a design document is the thing you can hand to four engineers on different teams and have them build compatible parts in parallel. The chat output is missing the parts of a design document that take the most thought: the failure modes (what happens when a dependency is slow, what happens when a deploy is in progress, what happens when the database is at saturation), the consistency boundaries (where eventual consistency is acceptable and where strong consistency is required), the scaling behavior (which dimensions the system can grow along and which require redesign), and the explicit non-goals (what the design is choosing not to do, and why).

These omissions are not accidents. The chat format favors the parts of a design that are easy to enumerate (components, APIs, data shapes) over the parts that require reasoning under uncertainty (failure modes, capacity planning, evolution paths). The omitted parts are the ones that determine whether the system survives contact with reality, which is why a senior engineer's design document looks different from a generalist tool's output. The senior engineer asks "what could go wrong" before "what does the happy path look like"; the generalist tool answers the second question because that is what the prompt asked for.

What a system design document actually requires

A useful system design document has six sections. First, the problem statement: what is the system being designed for, what are the constraints, what success looks like. Second, the component breakdown: what services or modules exist, what each one owns, what its interfaces are. Third, the data flow: how information moves through the components, where it is stored, where it crosses consistency or trust boundaries. Fourth, the API contracts between components: not full specs (those come later) but enough to confirm the components can interoperate. Fifth, the failure modes: what happens when each dependency is slow, unavailable, or returning errors, what the fallback behavior is, what is logged and alerted. Sixth, the scaling and evolution strategy: what dimensions the design supports growth in, what dimensions require redesign, and what the migration path is for the redesigns the team can already foresee.

The design document is not the implementation. It is the artifact that lets multiple engineers implement compatible parts in parallel without re-aligning every day. It is also the artifact that gets reviewed and challenged before code is written, which is the cheapest moment to find the design problem. A failure mode caught at design review costs an hour of discussion. The same failure mode caught after implementation costs the rewrite. The discipline of writing the document before the code is the discipline of catching problems while they are still cheap.

How /spine-design works

Step one: clarify the problem

Before producing any design, /spine-design asks for the problem statement in concrete terms: what is the system supposed to do, who uses it, what are the constraints (latency, throughput, consistency, cost), and what does success look like. The constraints become the input to the design choices. A system that needs sub-100ms p99 latency has different design constraints from one where p99 of one second is fine. A system that has to be strongly consistent has different storage choices from one where eventual consistency works. The skill is opinionated about not designing past underspecified constraints; if a constraint is unclear, it is surfaced as a question before the design proceeds.

Step two: components and data flow

With the problem statement in hand, /spine-design produces the component breakdown and the data flow. The components are presented with their responsibilities, their interfaces, and their dependencies. The data flow shows how information moves through the components, where each piece of data is stored, and where it crosses consistency or trust boundaries. The output is a Mermaid diagram for the components and the data flow, paired with the prose explanation of each. The diagram is generated from the design rather than separately, so it stays consistent with the rest of the document.

Step three: failure modes

The failure mode section walks through each dependency and asks what happens when it degrades. "What happens when the payment provider is slow" gets an explicit answer ("the payment route returns 202 with a job ID; the job is processed asynchronously and the user is notified on completion; if the provider is down for more than 10 minutes, the SLO alert fires and on-call investigates"). "What happens when the database is at saturation" gets an explicit answer. "What happens during a deploy of the upstream service" gets an explicit answer. The failure mode section is often the longest part of the document because it is the part where the most design thought is actually visible; a system without thought-out failure modes is a system that will surprise its operators on the day it matters.

Step four: scaling and evolution

The final section addresses the future. Which dimensions of growth does the design support naturally (more users, more requests per user, more regions)? Which dimensions require redesign (new product line, new compliance regime, new latency target)? What is the migration path for the redesigns the team can already foresee? The discipline is to make the future-proofing decisions explicit rather than assume the design will scale forever. A design that names its limits is a design that the next team can extend confidently; a design that hides its limits is a design that surprises the next team at the worst possible moment.

Tonone's /spine-design skill produces a system design document with components, data flow, API contracts, failure modes, and scaling strategy, written to be reviewed before any code.

When to use /spine-design, and when not to

/spine-design is the right call when architecting a new system or feature that involves multiple services, significant complexity, or coordination across teams. The signal is when more than one engineer will build against the design, when the design touches more than one service, or when stakeholders outside the implementation team need to understand and review the design. The skill is also the right call for designing significant changes to an existing system: a major refactor, a migration, a new architectural pattern.

Skip the skill for single-service features that one engineer will implement end-to-end (use /spine-api for API design within a service). For project scoping that precedes design (deciding what to build), /apex-plan is the right call; once the project is scoped, /spine-design is the next step. For pure architecture mapping of an existing system, /atlas-map produces the C4-style diagram without redesigning.

A worked example: designing a billing service

Suppose the brief is: design the billing service that will handle subscriptions, invoices, and payments. Run /spine-design and the document outline starts with the problem statement, then the component breakdown, then the data flow, then the failure modes.

# Billing Service Design

## Problem

Provide subscription billing for the application. Handle plan
changes, invoice generation, payment collection via Stripe, and
dunning when payments fail.

### Constraints
- p99 latency for the customer dashboard's invoice list: 250ms
- Strong consistency for payment state (no double-charges)
- Multi-currency support (USD, EUR, GBP at launch)
- Audit log retained for 7 years (compliance)

### Non-goals
- Tax calculation (handled by Stripe Tax)
- Quote-to-cash beyond subscriptions
- Per-seat metering at v1 (deferred to v2)

## Components

```mermaid
flowchart LR
  CW[Customer dashboard] --> API[billing-api]
  ADMIN[Admin tool] --> API
  API --> DB[(billing-db Postgres)]
  API --> STRIPE[Stripe API]
  STRIPE -- webhooks --> WH[webhook-handler]
  WH --> DB
  CRON[dunning-cron] --> DB
  CRON --> STRIPE
```

- **billing-api**: REST API, owns invoice + subscription state.
- **webhook-handler**: idempotent ingest of Stripe events.
- **dunning-cron**: scheduled job, retries failed payments per policy.

## Data flow

Invoice creation: customer subscribes -> billing-api creates Invoice
in status=open -> Stripe charge -> webhook event payment.succeeded
-> webhook-handler transitions Invoice to status=paid.

## Failure modes

- **Stripe slow**: billing-api uses 5s timeout, returns 202 with job
  ID. UI polls for completion. SLO: 99.5% of charges complete <30s.
- **Stripe down**: queue charges in billing-db with status=pending,
  dunning-cron retries when Stripe recovers. Alert on >5min outage.
- **billing-db saturated**: billing-api falls back to read-only mode
  for dashboard endpoints (cached invoices). Writes return 503.
- **Webhook duplicates**: webhook-handler is idempotent on
  Stripe event ID; deduplicates in a 30-day window.
- **Webhook missed**: dunning-cron reconciles every hour by polling
  Stripe for events since last seen.

## Scaling

- Reads: scaled by read replicas of billing-db. Cap at 6 replicas
  before reconsidering caching layer.
- Writes: single primary. Capacity planning shows sufficient at
  100x current load. Beyond that, consider sharding by customer_id.
- Multi-region: not at v1. The migration path involves switching
  billing-db to a multi-region primary (e.g. Aurora Global) and
  pinning customers to a home region.
- Currencies beyond launch set: storage already supports any ISO 4217
  code; UI requires a localization pass.

The document is reviewable in one sitting and challengeable in a design review meeting. Each section can be questioned independently. The failure modes are the section that usually gets the most pushback, which is exactly the right outcome: the team is finding the design problems while they are still cheap.

Related skills

/spine-design produces the design document. Once the design is approved, /spine-api produces the API contracts in detail and /spine-service produces the service scaffolding. For project scoping that precedes design, /apex-plan is the right entry point. For mapping an existing system without redesigning, /atlas-map produces the C4 diagram.

Install

/spine-design ships with the Spine agent in the Tonone for Claude Code package. Install Tonone, invoke /spine-design from any Claude Code session, and the skill produces a structured design document with components, data flow, failure modes, and scaling strategy.

Designs that survive contact with reality are the ones that named their failure modes before they shipped. The skill is built to make the design discipline cheap enough to apply on every system that warrants it, which is most systems with more than one component.