重要前提
安装AI Skills的关键前提是:必须科学上网,且开启TUN模式,这一点至关重要,直接决定安装能否顺利完成,在此郑重提醒三遍:科学上网,科学上网,科学上网。查看完整安装教程 →
npx skills add https://github.com/jasonkneen/kiro --skill design-documentation创建连接需求与实现的技术蓝图。本技能教授如何记录架构决策、组件设计和系统交互。
在以下情况使用设计文档:
# 设计文档:[功能名称]
## 概述
[功能的高级摘要和实现方法]
## 架构
[系统架构和组件概述]
## 组件与接口
[详细的组件描述和交互]
## 数据模型
[数据结构和关系]
## 错误处理
[错误场景和应对策略]
## 测试策略
[测试方法和质量保证]
在设计之前,确保您理解:
分析问题:
确定需要研究的领域:
研究文档:
## 研究发现
### [主题]
**来源:** [链接/参考资料]
**关键见解:**
- [发现 1]
- [发现 2]
**对设计的影响:** [这如何影响我们的方法]
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
记录高层结构:
## 架构
### 系统概述
[整个系统如何工作]
### 组件架构
[主要组件及其职责]
### 数据流
[信息如何在系统中流动]
### 技术决策
[关键技术选择及其理由]
架构图 (Mermaid):
graph TD
A[Client] --> B[API Gateway]
B --> C[Auth Service]
B --> D[Feature Service]
D --> E[Database]
D --> F[Cache]
对于每个主要组件:
## 组件与接口
### [组件名称]
**目的:** [此组件的作用]
**职责:**
- [职责 1]
- [职责 2]
**接口:**
- 输入:[它接收什么]
- 输出:[它产生什么]
- 依赖项:[它需要什么]
**API 定义:**
```typescript
interface ComponentName {
method(input: InputType): Promise<OutputType>;
}
记录所有数据结构:
## 数据模型
### [实体名称]
**目的:** [此实体代表什么]
**属性:**
| 字段 | 类型 | 必填 | 描述 |
|-------|------|----------|-------------|
| id | string | 是 | 唯一标识符 |
| name | string | 是 | 显示名称 |
| createdAt | Date | 是 | 创建时间戳 |
**验证规则:**
- [规则 1]
- [规则 2]
**关系:**
- [与其他实体的关系]
**示例:**
```json
{
"id": "abc123",
"name": "Example",
"createdAt": "2024-01-15T10:30:00Z"
}
记录错误场景:
## 错误处理
### 错误类别
1. **验证错误:** 无效的用户输入
2. **认证错误:** 未经授权的访问
3. **外部服务错误:** 第三方故障
4. **系统错误:** 内部故障
### 错误响应策略
| 错误类型 | HTTP 代码 | 用户消息 | 系统操作 |
|------------|-----------|--------------|---------------|
| 验证 | 400 | 具体字段错误 | 记录日志,返回详情 |
| 认证 | 401 | "请登录" | 重定向到登录页 |
| 未找到 | 404 | "资源未找到" | 记录日志,返回错误 |
| 服务器 | 500 | "出错了" | 记录日志,告警,重试 |
### 恢复机制
- [重试策略]
- [回退行为]
- [熔断器模式]
## 测试策略
### 单元测试
- **覆盖率目标:** 80%+
- **重点领域:** [关键业务逻辑]
- **模拟策略:** [模拟什么]
### 集成测试
- **范围:** [要测试的组件交互]
- **环境:** [测试环境设置]
- **数据策略:** [测试数据方法]
### 端到端测试
- **关键路径:** [要测试的用户旅程]
- **工具:** [测试工具]
### 性能测试
- **负载目标:** [预期负载]
- **基准:** [性能要求]
使用此模板记录关键决策:
### 决策:[简短标题]
**背景:** [需要决策的情况]
**考虑的选项:**
**选项 1:[名称]**
- 优点:[好处]
- 缺点:[弊端]
- 工作量:[低/中/高]
**选项 2:[名称]**
- 优点:[好处]
- 缺点:[弊端]
- 工作量:[低/中/高]
**决策:** [选择的选项]
**理由:** [为何选择此选项]
**影响:** [这对实现意味着什么]
### 决策:API 架构
**选项:**
1. **REST API** - 标准 HTTP 方法,易于理解
2. **GraphQL** - 灵活的查询,单一端点
3. **RPC 风格** - 直接操作映射
**决策:** REST API
**理由:** 标准 CRUD 操作,团队熟悉,工具支持良好
### 决策:数据库选择
**选项:**
1. **PostgreSQL** - ACID 合规性,复杂查询
2. **MongoDB** - 模式灵活,水平扩展
3. **Redis** - 高性能,查询有限
**决策:** 带 JSON 列的 PostgreSQL
**理由:** 数据一致性需求 + 用户偏好的灵活性
### 决策:身份验证策略
**选项:**
1. **基于会话** - 服务器控制,简单
2. **JWT 令牌** - 无状态,可扩展
3. **OAuth 2.0** - 外部提供商,无需密码管理
**决策:** 带刷新令牌轮换的 JWT
**理由:** 可扩展性要求,API 优先架构
在最终确定设计之前:
完整性:
清晰度:
可行性:
可追溯性:
# 设计文档:用户资料管理
## 概述
使用户能够查看和编辑其个人资料信息,包括个人详细信息、偏好设置和头像。
## 架构
### 组件架构
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ Client │────▶│ Profile API │────▶│ Database │
└─────────────┘ └──────────────┘ └─────────────┘
│
▼
┌──────────────┐
│ Image Store │
└──────────────┘
### 技术栈
- API: Node.js with Express
- Database: PostgreSQL
- Image Storage: S3-compatible object storage
- Cache: Redis for session data
## 组件
### ProfileService
**目的:** 管理用户资料的 CRUD 操作
**接口:**
```typescript
interface ProfileService {
getProfile(userId: string): Promise<UserProfile>;
updateProfile(userId: string, data: ProfileUpdate): Promise<UserProfile>;
uploadAvatar(userId: string, image: File): Promise<string>;
deleteAvatar(userId: string): Promise<void>;
}
| 字段 | 类型 | 必填 | 验证 |
|---|---|---|---|
| id | UUID | 是 | 自动生成 |
| string | 是 | 有效的电子邮件格式 | |
| displayName | string | 是 | 2-50 个字符 |
| bio | string | 否 | 最多 500 个字符 |
| avatarUrl | string | 否 | 有效的 URL |
| preferences | JSON | 否 | 有效的 JSON 对象 |
| updatedAt | timestamp | 是 | 自动更新 |
| 场景 | 响应 | 操作 |
|---|---|---|
| 资料未找到 | 404 | 返回错误消息 |
| 无效的更新数据 | 400 | 返回验证错误 |
| 图片过大 | 413 | 返回大小限制错误 |
| 未授权 | 401 | 重定向到登录页 |
完成设计后:
每周安装量
66
仓库
GitHub 星标数
591
首次出现
2026年1月22日
安全审计
安装于
opencode58
codex56
gemini-cli55
github-copilot51
cursor49
claude-code42
Create technical blueprints that bridge requirements and implementation. This skill teaches how to document architecture decisions, component design, and system interactions.
Use design documentation when:
# Design Document: [Feature Name]
## Overview
[High-level summary of the feature and approach]
## Architecture
[System architecture and component overview]
## Components and Interfaces
[Detailed component descriptions and interactions]
## Data Models
[Data structures and relationships]
## Error Handling
[Error scenarios and response strategies]
## Testing Strategy
[Testing approach and quality assurance]
Before designing, ensure you understand:
Analysis Questions:
Identify areas needing research:
Research Documentation:
## Research Findings
### [Topic]
**Sources:** [Links/references]
**Key Insights:**
- [Finding 1]
- [Finding 2]
**Impact on Design:** [How this affects our approach]
Document the high-level structure:
## Architecture
### System Overview
[How the overall system works]
### Component Architecture
[Major components and their responsibilities]
### Data Flow
[How information moves through the system]
### Technology Decisions
[Key technology choices and rationale]
Architecture Diagram (Mermaid):
graph TD
A[Client] --> B[API Gateway]
B --> C[Auth Service]
B --> D[Feature Service]
D --> E[Database]
D --> F[Cache]
For each major component:
## Components and Interfaces
### [Component Name]
**Purpose:** [What this component does]
**Responsibilities:**
- [Responsibility 1]
- [Responsibility 2]
**Interfaces:**
- Input: [What it receives]
- Output: [What it produces]
- Dependencies: [What it requires]
**API Definition:**
```typescript
interface ComponentName {
method(input: InputType): Promise<OutputType>;
}
### Step 5: Define Data Models
Document all data structures:
```markdown
## Data Models
### [Entity Name]
**Purpose:** [What this entity represents]
**Properties:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | string | Yes | Unique identifier |
| name | string | Yes | Display name |
| createdAt | Date | Yes | Creation timestamp |
**Validation Rules:**
- [Rule 1]
- [Rule 2]
**Relationships:**
- [Relationship to other entities]
**Example:**
```json
{
"id": "abc123",
"name": "Example",
"createdAt": "2024-01-15T10:30:00Z"
}
### Step 6: Plan Error Handling
Document error scenarios:
```markdown
## Error Handling
### Error Categories
1. **Validation Errors:** Invalid user input
2. **Authentication Errors:** Unauthorized access
3. **External Service Errors:** Third-party failures
4. **System Errors:** Internal failures
### Error Response Strategy
| Error Type | HTTP Code | User Message | System Action |
|------------|-----------|--------------|---------------|
| Validation | 400 | Specific field error | Log, return details |
| Auth | 401 | "Please log in" | Redirect to login |
| Not Found | 404 | "Resource not found" | Log, return error |
| Server | 500 | "Something went wrong" | Log, alert, retry |
### Recovery Mechanisms
- [Retry strategies]
- [Fallback behaviors]
- [Circuit breaker patterns]
## Testing Strategy
### Unit Testing
- **Coverage Target:** 80%+
- **Focus Areas:** [Critical business logic]
- **Mocking Strategy:** [What to mock]
### Integration Testing
- **Scope:** [Component interactions to test]
- **Environment:** [Test environment setup]
- **Data Strategy:** [Test data approach]
### End-to-End Testing
- **Critical Paths:** [User journeys to test]
- **Tools:** [Testing tools]
### Performance Testing
- **Load Targets:** [Expected load]
- **Benchmarks:** [Performance requirements]
Document key decisions using this template:
### Decision: [Brief Title]
**Context:** [Situation requiring a decision]
**Options Considered:**
**Option 1: [Name]**
- Pros: [Benefits]
- Cons: [Drawbacks]
- Effort: [Low/Medium/High]
**Option 2: [Name]**
- Pros: [Benefits]
- Cons: [Drawbacks]
- Effort: [Low/Medium/High]
**Decision:** [Chosen option]
**Rationale:** [Why this option was selected]
**Implications:** [What this means for implementation]
### Decision: API Architecture
**Options:**
1. **REST API** - Standard HTTP methods, well-understood
2. **GraphQL** - Flexible queries, single endpoint
3. **RPC-style** - Direct operation mapping
**Decision:** REST API
**Rationale:** Standard CRUD operations, team familiarity, good tooling support
### Decision: Database Choice
**Options:**
1. **PostgreSQL** - ACID compliance, complex queries
2. **MongoDB** - Schema flexibility, horizontal scaling
3. **Redis** - High performance, limited queries
**Decision:** PostgreSQL with JSON columns
**Rationale:** Data consistency needs + flexibility for user preferences
### Decision: Authentication Strategy
**Options:**
1. **Session-based** - Server-controlled, simple
2. **JWT tokens** - Stateless, scalable
3. **OAuth 2.0** - External provider, no password management
**Decision:** JWT with refresh token rotation
**Rationale:** Scalability requirements, API-first architecture
Before finalizing design:
Completeness:
Clarity:
Feasibility:
Traceability:
# Design Document: User Profile Management
## Overview
Enable users to view and edit their profile information, including personal details, preferences, and profile picture.
## Architecture
### Component Architecture
┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │ Client │────▶│ Profile API │────▶│ Database │ └─────────────┘ └──────────────┘ └─────────────┘ │ ▼ ┌──────────────┐ │ Image Store │ └──────────────┘
### Technology Stack
- API: Node.js with Express
- Database: PostgreSQL
- Image Storage: S3-compatible object storage
- Cache: Redis for session data
## Components
### ProfileService
**Purpose:** Manage user profile CRUD operations
**Interface:**
```typescript
interface ProfileService {
getProfile(userId: string): Promise<UserProfile>;
updateProfile(userId: string, data: ProfileUpdate): Promise<UserProfile>;
uploadAvatar(userId: string, image: File): Promise<string>;
deleteAvatar(userId: string): Promise<void>;
}
| Field | Type | Required | Validation |
|---|---|---|---|
| id | UUID | Yes | Auto-generated |
| string | Yes | Valid email format | |
| displayName | string | Yes | 2-50 characters |
| bio | string | No | Max 500 characters |
| avatarUrl | string | No | Valid URL |
| preferences | JSON | No | Valid JSON object |
| updatedAt | timestamp | Yes | Auto-updated |
| Scenario | Response | Action |
|---|---|---|
| Profile not found | 404 | Return error message |
| Invalid update data | 400 | Return validation errors |
| Image too large | 413 | Return size limit error |
| Unauthorized | 401 | Redirect to login |
Unit tests for validation logic
Integration tests for API endpoints
E2E test for profile edit flow
After completing design:
Weekly Installs
66
Repository
GitHub Stars
591
First Seen
Jan 22, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode58
codex56
gemini-cli55
github-copilot51
cursor49
claude-code42
论文复现上下文解析器 - 解决AI论文复现中的关键信息缺口与冲突检测
20,800 周安装
design-delight - 提升代码编辑器设计体验的配置工具,优化开发工作流
1 周安装
design-colorize 代码着色工具 - 提升代码可读性的设计插件 | derklinke/codex-config
1 周安装
design-clarify - 代码配置与设计澄清工具,提升开发效率与代码质量
1 周安装
API网关配置指南:Kong、Nginx、AWS实战与微服务架构最佳实践
63 周安装
design-article-integration:代码库配置工具,实现设计与文章集成
1 周安装
design-animate 动画设计工具 - 代码配置与动画生成技能
1 周安装