aid-tech-spec

ilandahan 的头像作者 ilandahan

AID 第 2 阶段 - 技术规范。用于系统架构、API 合约、数据模型、安全架构、从 PRD 到实施的过渡。

📖 中文导读:AID 第 2 阶段 - 技术规范。用于系统架构、API 合约、数据模型、安全架构、从 PRD 到实施的过渡。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

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

  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`