aid-tech-spec
AID Phase 2 - Technical Specification. Use for system architecture, API contracts, data models, security architecture, transitioning from PRD to implementation.
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.
| name | aid-tech-spec |
|---|---|
| description | AID 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
- Tech Spec Document - Implementation-ready design
- Architecture Diagram - Components and interactions
- API Contracts - Endpoints, schemas, errors
- 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`