aid-tech-spec

AID Phase 2 - Technical Specification. Use for system architecture, API contracts, data models, security architecture, transitioning from PRD to implementation.

⭐5stars🔀0forks📁View on GitHub🕐Updated Jan 8, 2026

When & Why to Use This Skill

The aid-tech-spec Claude skill streamlines the critical transition from Product Requirement Documents (PRD) to technical implementation. It provides a structured framework for designing robust system architectures, defining precise API contracts, and modeling complex data structures, ensuring developers have an unambiguous blueprint that addresses security, performance, and scalability from the start.

Use Cases

  • System Architecture Blueprinting: Generating comprehensive component diagrams and data flow maps to visualize how different services interact within a complex system.
  • API Contract Specification: Defining standardized request/response schemas and error handling protocols to ensure seamless integration between frontend and backend teams.
  • Data Modeling and Schema Design: Creating detailed entity-relationship models and type constraints to ensure data integrity and database scalability.
  • Technical Risk Assessment: Identifying and mitigating potential architectural pitfalls such as tight coupling, over-engineering, or security vulnerabilities before coding begins.
  • PRD to Implementation Handoff: Converting high-level business requirements into actionable technical tasks with clear success criteria and non-functional requirements.
nameaid-tech-spec
descriptionAID Phase 2 - Technical Specification. Use for system architecture, API contracts, data models, security architecture, transitioning from PRD to implementation.

Tech Spec Phase Skill

Phase Overview

Purpose: Design technical solution. Create blueprint developers can follow without ambiguity.

Entry: PRD approved, requirements clear, dependencies identified Exit: Tech spec complete, architecture documented, API contracts defined, data models specified

Deliverables

  1. Tech Spec Document - Implementation-ready design
  2. Architecture Diagram - Components and interactions
  3. API Contracts - Endpoints, schemas, errors
  4. Data Models - Schemas, types, constraints

Common Pitfalls

Pitfall Fix
Over-engineering Design for current needs
Missing error handling Define errors upfront
Tight coupling Design for testability
Ignoring non-functionals Address performance, security
Unclear contracts APIs unambiguous with examples

Phase Gate Checklist

  • Tech spec complete
  • Architecture diagram created
  • All API contracts defined
  • Data models specified
  • Error handling strategy defined
  • Security considerations addressed
  • Performance requirements addressed
  • Tech lead approved

Tech Spec Template

# [Feature] Technical Specification

## 1. Overview
### Problem Summary
### Proposed Solution
### Key Decisions
| Decision | Choice | Rationale |

## 2. Architecture
### System Diagram
[Mermaid or image]

### Component Breakdown
| Component | Responsibility | Dependencies |

### Data Flow

## 3. API Design
### POST /api/[resource]
**Request:**
```json
{ "field": "type" }

Response (200):

{ "id": "string" }

Errors: | Code | Error | Description |

4. Data Model

Entity: [Name]

| Field | Type | Constraints | Description |

5. Security

Authentication

Authorization

Data Protection

6. Error Handling

| Scenario | Response | Recovery |

7. Non-Functional Requirements

| Requirement | Target | Measurement |

8. Risks & Mitigations

| Risk | Impact | Mitigation |


## Role Guidance

| Role | Focus |
|------|-------|
| PM | Validate approach addresses requirements |
| Dev | Own spec, design for testability |
| QA | Review testability, integration points |
| Tech Lead | Review architecture, approve direction |

## Handoff to Implementation

- Approved tech spec
- API contracts
- Data models
- Architecture decisions with rationale
- Spike/POC results (if any)

Save to: `docs/tech-spec/YYYY-MM-DD-[feature].md`