OpenParable
Skip to content
← Back to skills

Technical Design Doc

Documents
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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/majiayu000/claude-skill-registry/blob/HEAD/skills/data/technical-design-doc/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/technical-design-doc, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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.”