Generates professional Technical Design Documents following industry-standard engineering practices. This skill activates when the user asks to write a technical design, create an architecture design, draft a design doc, write a technical proposal, do system design, create a technical design document, write an RFC, create a design document, or produce an architecture document. It synthesizes best practices from the Google Design Doc format, the RFC template structure, and Uber/Meta engineering design standards to produce comprehensive, implementable technical designs tailored to the user's project and codebase.
Generates comprehensive Technical Design Documents following industry-standard engineering practices and structured workflows.
npx claudepluginhub tercel/spec-forgeThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/checklist.mdreferences/generation-instructions.mdreferences/template.mdA Technical Design Document (TDD) is the engineering blueprint that translates product requirements into a concrete, implementable architecture. It sits between the Software Requirements Specification (SRS) and the actual code, serving as the contract between the engineering team and the rest of the organization about how a system will be built. A well-crafted TDD reduces implementation risk, surfaces architectural trade-offs early, and provides a lasting record of why specific technical decisions were made.
The Google Design Doc tradition emphasizes that design documents are not just about documenting a decision after the fact -- they are a tool for thinking through a problem rigorously before committing to code. The RFC (Request for Comments) tradition adds the dimension of structured peer review, ensuring that designs benefit from collective expertise. Uber and Meta engineering standards contribute a focus on scalability, operational readiness, and production-grade thinking from day one.
This skill combines all three traditions. Every generated Technical Design Document presents at least two alternative solutions, evaluates them against explicit criteria, and documents the rationale behind the chosen approach. The document covers architecture, API design, data modeling, security, performance, observability, and deployment -- everything an engineering team needs to move from design to implementation with confidence.
Every Technical Design Document generated by this skill follows a disciplined six-step process. Each step must be completed before moving to the next.
Before writing anything, perform a thorough scan of the current project to build deep technical understanding.
**/*.md, **/package.json, **/go.mod, **/Cargo.toml, **/docker-compose.yml, **/Dockerfile, or language-specific manifests to map the landscape.docs/ directory for existing documents, paying special attention to architecture decision records (ADRs), prior design documents, and API documentation.This automated scanning ensures the generated design document is grounded in the real architecture rather than generic assumptions.
Search for matching upstream documents that feed into this design.
docs/*/prd.md related to the feature being designed. Read all found PRD documents to extract product goals, user stories, and success metrics.docs/*/srs.md related to the feature. Read all found SRS documents to extract functional requirements (FR-XXX-NNN), non-functional requirements (NFR-XXX-NNN), data models, and interface definitions.If no upstream documents are found, note this fact and proceed with the information gathered from the codebase scan and user clarification.
Present the user with targeted clarifying questions. These questions fill gaps that cannot be inferred from the codebase or upstream documents. Typical areas include:
Do not proceed to generation until the user has answered enough questions to inform the core design sections.
Using the template at references/template.md, generate the complete Technical Design Document. Key requirements for this step:
If upstream documents (PRD and SRS) were found:
This traceability ensures no requirements fall through the cracks between specification and design.
Validate the completed document against every item in references/checklist.md. Fix any issues before presenting the final document to the user. Summarize the checklist results so the user can see what passed and whether any items were intentionally skipped with justification.
All architecture diagrams follow the C4 model, which provides four levels of abstraction for communicating software architecture.
Level 1 -- Context Diagram. Shows the system as a single box surrounded by the people who use it and the external systems it interacts with. This is the highest-level view and should be understandable by non-technical stakeholders. Use a Mermaid flowchart TB diagram with clear labels for each actor and system.
Level 2 -- Container Diagram. Zooms into the system box and shows the high-level technology building blocks: web applications, APIs, databases, message queues, file storage, and other containers. Each container is labeled with its technology choice. Use a Mermaid flowchart TB diagram with subgraphs to group related containers.
Level 3 -- Component Diagram. Zooms into a single container and shows the major structural components inside it: controllers, services, repositories, domain models, and their relationships. Use a Mermaid flowchart LR or flowchart TB diagram.
Level 4 -- Code Diagram. Typically not included in the design document itself but may be referenced for particularly complex algorithms or data structures. When needed, use Mermaid classDiagram notation.
All Mermaid code blocks must use the ```mermaid fence so they render correctly in GitHub, GitLab, and most Markdown viewers. Every diagram must have a descriptive title, and every node must have a human-readable label.
Every technical design must begin with explicit technology choices. The Technology Stack section requires a table listing every layer of the system (programming language, runtime, framework, ORM, database, cache, message queue, frontend framework, testing framework, build tool, containerization) with the specific version and a rationale explaining why it was chosen. Rationales must be project-specific -- "it's popular" is not sufficient; "Go 1.22 was chosen because the team has 3 years of Go experience and its concurrency model fits our real-time event processing needs" is.
Inconsistent naming across code, APIs, and databases is one of the most common sources of confusion in engineering teams. The design document must define naming conventions at three levels:
Code Naming. Specify conventions for files/modules, classes/structs, interfaces/traits, functions/methods, variables, constants, enums, and test files. Follow the chosen language ecosystem's conventions (e.g., camelCase for JavaScript, snake_case for Python/Rust, PascalCase for Go exported names).
API Naming. Specify conventions for URL path segments (kebab-case plural nouns recommended for REST), query parameters, request/response body fields, custom headers, and error codes. The request and response field conventions must match.
Database Naming. Specify conventions for table names (snake_case plural recommended), column names, primary/foreign keys, index names, constraint names, and enum types. Use a consistent pattern like idx_<table>_<columns> for indexes and fk_<table>_<referenced_table> for foreign keys.
Every parameter that crosses a trust boundary must have explicit validation rules. The design document must include a Validation Rules Matrix table where each row defines: parameter name, type, required/optional, minimum value, maximum value, pattern/format (regex or standard like RFC 5322 for email), default value, sanitization strategy, and the specific error message returned on failure.
Beyond the matrix, the document must define type coercion rules (how strings are parsed to integers, booleans, dates, enums), input sanitization strategy (HTML/XSS, SQL injection, path traversal, command injection, JSON depth limits), and the distinction between null, missing, and empty values.
The design must document every system limit and what happens when it is exceeded. This includes: request body size, string field lengths, array sizes, concurrent connections, rate limits, file upload sizes, JSON nesting depth, pagination result caps, and bulk operation batch sizes. For each limit, specify the exact number, the behavior when exceeded (specific HTTP error code), and the rationale.
Edge cases must be documented in a table covering at minimum: empty string input, unicode/emoji handling, idempotent duplicate requests, behavior during database migration, concurrent update conflicts, referential integrity on delete, timezone handling, numeric overflow, null vs zero semantics, and long-running request timeouts.
All business rules must be documented precisely enough that an engineer can implement them without ambiguity.
State Machines. If entities have lifecycle states, define the state machine using a Mermaid stateDiagram-v2 diagram. For every transition, document: from state, to state, trigger, guard conditions (what must be true), and side effects (what happens as a result).
Computation Rules. For every calculation or derived value, document: a rule ID, description, formula/logic, inputs, output type, numeric precision and rounding strategy, and a worked example with real numbers.
Conditional Logic. For complex branching behavior, document each condition with what happens when true and when false, plus any relevant notes about configurability or thresholds.
Define a comprehensive error taxonomy covering every error category the system can produce. For each category, specify: HTTP status code, error code pattern, whether the client should retry, and the user-facing message. Additionally, define retry and circuit breaker configuration for every external dependency: retry count, backoff strategy, circuit breaker threshold, timeout, and fallback behavior.
The design document must specify API conventions appropriate to the chosen protocol.
RESTful APIs. Follow resource-oriented design. Endpoints use plural nouns (e.g., /api/v1/users, /api/v1/orders/{orderId}/items). Use standard HTTP methods: GET for retrieval, POST for creation, PUT/PATCH for updates, DELETE for removal. Version the API in the URL path (e.g., /api/v1/). Define standard error response shapes with error codes, messages, and request IDs.
GraphQL APIs. Define the schema with queries, mutations, and subscriptions. Document resolver responsibilities and data loader patterns for N+1 prevention. Specify error handling conventions within the GraphQL response structure.
gRPC APIs. Define service and message protobuf schemas. Document streaming patterns (unary, server-streaming, client-streaming, bidirectional). Specify deadline and retry policies.
Regardless of protocol, every API specification must include: endpoint or operation name, authentication requirements, request schema with field types and validation rules, response schema with example payloads, and a complete error code table.
Database design sections must include the following elements.
Schema Design. Define every table or collection with its columns, data types, constraints (primary key, foreign key, unique, not null, defaults), and purpose. Use a table format for clarity.
ER Diagram. Use Mermaid erDiagram syntax to visualize entity relationships. Label every relationship with its cardinality and nature.
Index Strategy. For each table, define the indexes needed: primary indexes, unique indexes, composite indexes for common query patterns, and partial or conditional indexes where appropriate. Document the rationale for each index in terms of the queries it supports.
Migration Strategy. Plan how schema changes will be applied: migration tool selection, forward and backward compatibility, zero-downtime migration techniques (expand-contract pattern), and data backfill procedures.
Every design document must evaluate at least two alternative solutions. The comparison follows a structured methodology.
Security must be treated as a first-class architectural concern, not a bolt-on afterthought.
Authentication. Specify the authentication mechanism (OAuth 2.0, JWT, API keys, mTLS, SAML) and document the token lifecycle including issuance, validation, refresh, and revocation.
Authorization. Define the authorization model (RBAC, ABAC, or hybrid). Document roles, permissions, and access control rules. Specify how authorization is enforced at the API gateway, service, and data layers.
Data Encryption. Specify encryption at rest (algorithm, key management, rotation policy) and encryption in transit (TLS version, certificate management). Document handling of sensitive fields (PII, payment data) including tokenization or field-level encryption where applicable.
Audit Logging. Define what events are logged (authentication attempts, data access, configuration changes), the log format, retention policy, and how audit logs are protected from tampering.
Performance sections must be specific and measurable, not aspirational.
Target Metrics. Define concrete targets: API response time at p50, p95, and p99 percentiles; throughput in requests per second; error rate thresholds; and resource utilization limits.
Caching Strategy. Specify what is cached (query results, computed values, static assets), where caching happens (browser, CDN, application layer, database query cache), cache invalidation strategy (TTL, event-driven, manual), and cache warming procedures.
Optimization Plan. Document specific optimization techniques: query optimization, connection pooling, lazy loading, pagination strategies, batch processing, and async processing for non-critical paths.
The design must plan for production observability from the start.
Logging. Define log levels, structured log format (JSON recommended), correlation ID propagation, and log aggregation destination. Specify what must be logged at each level.
Monitoring and Metrics. Define the key metrics to track: RED metrics (Rate, Errors, Duration) for services, USE metrics (Utilization, Saturation, Errors) for resources, and business metrics. Specify the monitoring tool and dashboard requirements.
Alerting. Define alerting rules with conditions, severity levels, notification channels, and escalation procedures. Include runbook references for each alert.
The deployment section ensures the design is production-ready.
Environments. Define the environment topology (development, staging, production) with purpose, configuration differences, and access controls for each.
CI/CD Pipeline. Describe the pipeline stages: build, unit test, integration test, security scan, artifact creation, deployment, smoke test, and promotion. Specify any gates or approval steps.
Rollback Strategy. Define how to roll back a failed deployment: blue-green switching, canary percentage reduction, feature flag disabling, or database migration reversal. Specify the rollback decision criteria and the maximum time to rollback.
This skill relies on two reference files stored alongside it.
references/template.md -- The full Technical Design Document template with placeholder text for every section. The generated document is built by filling in this template.references/checklist.md -- A quality checklist organized into four categories (Completeness, Quality, Consistency, Format). The checklist is used during Step 6 to validate the finished document.Always read both files before generating a document so that any updates to the template or checklist are picked up automatically.
The finished Technical Design Document is written to:
docs/<feature-name>/tech-design.md
where <feature-name> is a lowercase, hyphen-separated slug derived from the feature name (for example, docs/user-authentication/tech-design.md or docs/payment-processing/tech-design.md). If the docs/<feature-name>/ directory does not exist, create it. If a file with the same name already exists, confirm with the user before overwriting.