# Technical Design Doc

> Technical Design Doc is an Agent Skill for documents published in the majiayu000/claude-skill-registry repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Generates clear technical design documents with architecture, trade-offs, and rollout plans.

- Skill name: `technical-design-doc`
- Category: [Documents](https://www.openparable.com/skill/documents/1)
- Source: https://github.com/majiayu000/claude-skill-registry/blob/HEAD/skills/data/technical-design-doc/SKILL.md
- Repository: majiayu000/claude-skill-registry (498 GitHub stars when collected)

## SKILL.md

# Technical Design Document Creator

## Purpose

Use this skill to create design docs that:

- Align stakeholders on what is being built and why.
- Capture architecture and trade-offs explicitly.
- Provide a durable reference for implementation and future changes.

---

## When to Use

- Cross-team or cross-service changes.
- New user-facing features with non-trivial backend impact.
- Data model changes, migrations, and new storage systems.
- Major performance, reliability, or security projects.

---

## Design Doc Structure

A good design doc should cover:

1. **Overview**

   - One-paragraph summary of the problem and proposed solution.
   - Expected impact at a high level.

2. **Background and Context**

   - Current behavior and pain points.
   - Relevant metrics, incidents, or user feedback.
   - Links to prior designs or ADRs.

3. **Goals and Non-Goals**

   - Goals: What success looks like.
   - Non-goals: Explicitly out-of-scope aspects to prevent scope creep.

4. **Requirements and Constraints**

   - Functional requirements.
   - Non-functional: performance, availability, security, privacy, compliance, cost, deadlines.

5. **Proposed Solution**

   - Architecture diagrams and component overviews.
   - Data flow and control flow (sequence diagrams where useful).
   - Key algorithms or logic at a high level.

6. **Alternatives Considered**

   - Briefly describe 2–3 options and why they were rejected.
   - Include “do nothing” when relevant.

7. **Impact Analysis**

   - On existing systems, APIs, clients, and data.
   - Operational impact: on-call, runbooks, observability.
   - Risks and mitigations.

8. **Testing and Validation**

   - Unit, integration, and end-to-end testing strategy.
   - Load/performance testing plans.
   - Rollback and failure drills, if applicable.

9. **Rollout Plan**

   - Milestones and phases.
   - Feature flagging or staged rollout strategy.
   - Monitoring during rollout; success criteria.

10. **Open Questions and Future Work**

    - Areas needing further exploration.
    - Potential follow-ups that are explicitly out of the current scope.

---

## Usage Guidance

- Optimize for clarity over completeness. If a section is not applicable, say why.
- Draw diagrams where they clarify non-trivial flows or boundaries.
- Keep the document living: update when significant decisions or constraints change.

---

## Examples of Good Prompts

- “Create a full design doc using this template for the following feature description.”
- “Given this high-level idea, flesh it out into a design doc with at least two alternative solutions.”
- “Review this existing design doc using the template; identify missing sections and key risks.”

---

Source: https://www.openparable.com/skill/documents/technical-design-doc (OpenParable). Cite the canonical URL above.