Design Doc Creator Skill

Overview

This skill guides the creation of comprehensive Design Docs optimized for AI agents (especially Claude Code CLI) and human developers. It produces concise, information-dense documentation that serves as the "memory" and "guide" for development without hallucination.

When to Use This Skill

Use this skill when:

• Starting a new feature or module development
• Needing to document a technical solution before implementation
• Creating context for Claude Code to execute development tasks
• Requiring a structured approach to capture requirements and solution design

Workflow

Phase 1: Discovery (Interview)

The AI conducts an iterative interview to gather all necessary information:

1. Initial Scope Question

   • Ask: "What functionality are you documenting? Provide a brief description."

2. Iterative Deep Dive (2-3 questions per block)

   • Context & Purpose:

     • What problem does this solve?
     • Why is this being built now?
     • Who are the primary users/stakeholders?

   • Terminology & Concepts:

     • What specific terms or concepts need definition?
     • Are there domain-specific terms that require clarification?

   • Integrations & Dependencies:

     • What external APIs/services will be used?
     • What are the key endpoints/methods?
     • What authentication is required?

   • CRITICAL - Solution Phases:

     • What are the logical phases of implementation? (e.g., Setup, Backend, Infrastructure)
     • This grouping is essential for task organization

   • Detailed Solution:

     • For each phase, what specific tasks are needed?
     • What are the business rules for each task?
     • What is the input → processing → output for each task?

   • Data Flow:

     • What is the step-by-step flow from user action to system response?
     • What are the critical decision points?

3. Validation Before Generation

   • Before generating the document, confirm you have:
     • Clear context and purpose
     • All key terms defined
     • Integration details documented
     • Tasks grouped into logical phases
     • Detailed business rules for each task
     • Complete data flow mapped
   • Ask: "Is there any additional information needed before I generate the Design Doc?"

Phase 2: Generation (Documentation)

Generate the Design Doc using strictly this template:

Design Doc Template

# [Feature Name] - Design Doc

## 1. Context
> [1-2 paragraph summary: WHAT is the feature and WHY it's being built]

## 2. Glossary
| Term | Description |
|:-----|:------------|
| [Term] | [Clear definition] |

## 3. Integrations and APIs
| API / Service | Usage Description | Key Methods/Endpoints |
|:--------------|:------------------|:----------------------|
| [e.g., Stripe /v1/customers] | [To create users] | [POST /create] |

## 4. Detailed Solution
*Group tasks logically (e.g., Setup, Client Integration, Subscriptions, Extras)*

| Phase | Task | Detailed Behavior Description (Business Rules) | Status |
|:------|:-----|:----------------------------------------------|:-------|
| **Setup** | Configure Credentials | Obtain API keys and save in environment variables. | `DEFINED` |
| **Client Integration** | Customer Creation | When registering user, create Customer in API X and save ID in database. | `DEFINED` |
| **[Category]** | [Task Name] | [Input → Processing → Output] | `UNDEFINED` |

## 5. Data Flow (Step-by-Step)
1. **[Actor]** initiates [Action]
2. **[System]** verifies [Condition]
3. **[System]** executes [Operation]
4. **[System]** returns [Result]
5. **[Actor]** receives [Feedback]

## 6. Technical Considerations
- Performance requirements
- Security considerations
- Error handling strategy
- Scalability concerns

## 7. Success Criteria
- [ ] [Measurable criterion 1]
- [ ] [Measurable criterion 2]
- [ ] [Measurable criterion 3]

Output Format

The skill should create a .md file in the /docs/features/[feature-name] folder with the naming convention: design-doc-[feature-name].md

Best Practices

1. Be Iterative: Don't rush to generate. Gather complete information first.

2. Focus on Behavior: In the Detailed Solution section, describe WHAT happens, not HOW to code it.

3. Group Intelligently: Tasks should be grouped by logical implementation phases, not by technical layers.

4. Be Specific: Avoid vague descriptions like "handle errors" → Instead: "If API returns 429, retry with exponential backoff (max 3 attempts)"

5. Think in Workflows: Data flow should read like a movie script - clear actors and actions.

6. Status Tracking: Use DEFINED, UNDEFINED, IN_PROGRESS, COMPLETED for task status.

Example Usage in Claude Code

# Start the design doc creation process
User: "Create a design doc for user authentication with OAuth"

Claude Code: [Follows discovery phase with targeted questions]

# After gathering information
Claude Code: [Generates design-doc-oauth-authentication.md]

# User can then reference this in subsequent tasks
User: "Implement the tasks from the design doc in order"

Anti-Patterns to Avoid

❌ Generating the document without sufficient detail ❌ Mixing implementation details (code) with design decisions ❌ Creating tasks that are too granular (aim for 30min-2hr chunks) ❌ Forgetting to group tasks into logical phases ❌ Using vague business rules ("validate input" vs "validate email format: RFC 5322 compliant")

Skill Outputs

• Primary: A complete Design Doc markdown file
• Secondary: A clear understanding of the feature scope and implementation approach
• Tertiary: A ready-to-execute task list for Claude Code