Project Planner Skill

This skill provides templates and guidance for generating comprehensive project planning documents that serve as blueprints for AI-assisted implementation.

该Skill可为生成用作AI辅助实施蓝图的综合性项目规划文档提供模板与指导。

Quick Start

快速开始

When a user wants to start a new project, generate three core documents:

Requirements Document - User stories with acceptance criteria
Design Document - Technical architecture and component specifications
Implementation Plan - Hierarchical task breakdown with requirement tracing

当用户想要启动新项目时，生成三份核心文档：

需求文档 - 带有验收标准的User Story
设计文档 - 技术架构与组件规格说明
实施计划 - 具备需求追溯功能的分层任务拆解

Why Explicit Architectural Planning Works

明确架构规划为何有效

Setting clear roles, responsibilities, and deliverables upfront dramatically improves project outcomes:

提前设定清晰的角色、职责与交付成果可显著提升项目成效：

Benefits of Upfront Definition

提前定义的优势

Component Clarity - Defining all system components first prevents scope creep and ensures complete coverage
Data Flow Visibility - Mapping data movement early reveals integration complexities and performance bottlenecks
Integration Planning - Identifying all touchpoints upfront prevents surprise dependencies during implementation
Clear Boundaries - Explicitly stating what's in/out of scope focuses effort and prevents feature drift
Measurable Success - Specific goals and constraints enable objective progress tracking

组件清晰度 - 先定义所有系统组件可防止范围蔓延，确保覆盖完整
数据流可视性 - 提前映射数据流向可发现集成复杂度与性能瓶颈
集成规划 - 提前识别所有交互点可避免实施过程中出现意外依赖
明确边界 - 清晰说明纳入/排除范围可聚焦工作，防止功能偏离
可衡量的成功 - 具体目标与约束可实现客观进度跟踪

The Architect Mindset

架构师思维模式

When acting as a Project Architect, approach planning with:

Systems Thinking - See the whole before diving into parts
Interface-First Design - Define contracts between components before internals
Traceability Focus - Every requirement maps to design elements and tasks
Constraint Awareness - Acknowledge limitations upfront to guide decisions
Deliverable Orientation - Know exactly what artifacts you're producing

当担任Project Architect角色时，规划需遵循：

系统思维 - 先着眼整体再深入细节
接口优先设计 - 先定义组件间的契约再开发内部逻辑
可追溯性聚焦 - 每个需求都需映射到设计元素与任务
约束意识 - 提前承认限制以指导决策
交付成果导向 - 明确知道要产出哪些工件

Document Generation Workflow

文档生成工作流

1. Project Architect Role Definition

1. Project Architect角色定义

When starting a project, explicitly establish Claude as the Project Architect with clear responsibilities:

Role: System Architect and Planning Specialist Responsibilities:

Define complete system architecture with all components
Map data flow between system elements
Identify all integration points and interfaces
Establish clear project boundaries and constraints
Create traceable requirements to implementation tasks

启动项目时，需明确将Claude设定为Project Architect，并清晰界定职责：

**角色：**系统架构师与规划专家 职责：

定义包含所有组件的完整系统架构
映射系统元素间的数据流
识别所有集成点与接口
建立清晰的项目边界与约束
创建可追溯至实施任务的需求

2. Initial Project Understanding

2. 初始项目理解

Before generating documents, gather key information and architectural elements:

Required Project Information:
- Project name and purpose
- Target users (single-user local, multi-tenant SaaS, etc.)
- Core functionality (3-5 main features)
- Technical preferences (languages, frameworks, deployment)
- Non-functional requirements (performance, security, scalability)

Required Architectural Elements (define upfront):
- System Components: All major modules/services and their purposes
- Data Flow: How data moves through the entire system
- Integration Points: All external APIs, services, databases
- System Boundaries: What's in scope vs out of scope
- Constraints: Technical, business, and resource limitations
- Success Metrics: Clear, measurable goals for the system

生成文档前，收集关键信息与架构元素：

Required Project Information:
- Project name and purpose
- Target users (single-user local, multi-tenant SaaS, etc.)
- Core functionality (3-5 main features)
- Technical preferences (languages, frameworks, deployment)
- Non-functional requirements (performance, security, scalability)

Required Architectural Elements (define upfront):
- System Components: All major modules/services and their purposes
- Data Flow: How data moves through the entire system
- Integration Points: All external APIs, services, databases
- System Boundaries: What's in scope vs out of scope
- Constraints: Technical, business, and resource limitations
- Success Metrics: Clear, measurable goals for the system

3. Deliverable Definition (Set Upfront)

3. 交付成果定义（提前设定）

Define all deliverables explicitly before starting documentation:

Standard Deliverables Package:
1. Requirements Document
   - User stories with measurable acceptance criteria
   - Complete glossary of terms
   - Traceable requirement IDs
   
2. System Design Document  
   - Component architecture diagram
   - Data flow diagrams for all major processes
   - Integration point specifications
   - API/Interface contracts
   - Performance and scaling targets
   
3. Implementation Plan
   - Hierarchical task breakdown
   - Requirement-to-task mapping
   - Dependency graph
   - Phase-based delivery schedule

Optional Deliverables (specify if needed):
- API Documentation
- Database Schema Design
- Security Threat Model
- Deployment Guide
- Testing Strategy Document

开始文档编写前明确所有交付成果：

Standard Deliverables Package:
1. Requirements Document
   - User stories with measurable acceptance criteria
   - Complete glossary of terms
   - Traceable requirement IDs
   
2. System Design Document  
   - Component architecture diagram
   - Data flow diagrams for all major processes
   - Integration point specifications
   - API/Interface contracts
   - Performance and scaling targets
   
3. Implementation Plan
   - Hierarchical task breakdown
   - Requirement-to-task mapping
   - Dependency graph
   - Phase-based delivery schedule

Optional Deliverables (specify if needed):
- API Documentation
- Database Schema Design
- Security Threat Model
- Deployment Guide
- Testing Strategy Document

4. Generate Requirements Document

4. 生成需求文档

Use the requirements template to create user-focused specifications:

python

undefined

使用需求模板创建以用户为中心的规格说明：

python

undefined

Execute this to generate requirements structure

requirements = { "introduction": "System purpose and scope", "glossary": "Domain-specific terms", "requirements": [ { "id": "REQ-X", "user_story": "As a [role], I want [feature], so that [benefit]", "acceptance_criteria": [ "WHEN [condition], THE system SHALL [behavior]", "WHERE [context], THE system SHALL [behavior]", "IF [condition], THEN THE system SHALL [behavior]" ] } ] }

undefined

requirements = { "introduction": "System purpose and scope", "glossary": "Domain-specific terms", "requirements": [ { "id": "REQ-X", "user_story": "As a [role], I want [feature], so that [benefit]", "acceptance_criteria": [ "WHEN [condition], THE system SHALL [behavior]", "WHERE [context], THE system SHALL [behavior]", "IF [condition], THEN THE system SHALL [behavior]" ] } ] }

undefined

5. Generate Design Document

5. 生成设计文档

Create technical specifications with explicit architectural elements:

python

undefined

创建包含明确架构元素的技术规格说明：

python

undefined

Execute this to generate comprehensive design structure

design = { "overview": "High-level system description", "architecture": { "diagram": "ASCII or visual representation of all components", "components": [ { "id": "COMP-1", "name": "Component Name", "type": "Frontend/Backend/Service/Database", "responsibility": "Single clear purpose", "boundaries": "What it does and doesn't do" } ] }, "data_flow": { "primary_flows": [ { "name": "User Registration Flow", "steps": [ "1. User submits form → Frontend", "2. Frontend validates → API Gateway", "3. API Gateway → Auth Service", "4. Auth Service → User Database", "5. Response flows back" ], "data_transformations": "How data changes at each step" } ] }, "integration_points": [ { "name": "External Payment API", "type": "REST/GraphQL/WebSocket/Database", "purpose": "Process payments", "interface": "API contract definition", "authentication": "Method used", "error_handling": "Retry/fallback strategy" } ], "components_detail": [ { "name": "Component Name", "responsibility": "What it does", "key_classes": ["Class descriptions"], "interfaces": "API/method signatures", "dependencies": "What it needs to function", "performance": "Targets and constraints" } ], "data_models": "Entity definitions with relationships", "system_boundaries": { "in_scope": ["What the system handles"], "out_of_scope": ["What it delegates or ignores"], "assumptions": ["External dependencies assumed available"] }, "error_handling": "Strategies for failures", "testing_strategy": "Unit, integration, performance", "deployment": "Docker, environment, configuration" }

undefined

design = { "overview": "High-level system description", "architecture": { "diagram": "ASCII or visual representation of all components", "components": [ { "id": "COMP-1", "name": "Component Name", "type": "Frontend/Backend/Service/Database", "responsibility": "Single clear purpose", "boundaries": "What it does and doesn't do" } ] }, "data_flow": { "primary_flows": [ { "name": "User Registration Flow", "steps": [ "1. User submits form → Frontend", "2. Frontend validates → API Gateway", "3. API Gateway → Auth Service", "4. Auth Service → User Database", "5. Response flows back" ], "data_transformations": "How data changes at each step" } ] }, "integration_points": [ { "name": "External Payment API", "type": "REST/GraphQL/WebSocket/Database", "purpose": "Process payments", "interface": "API contract definition", "authentication": "Method used", "error_handling": "Retry/fallback strategy" } ], "components_detail": [ { "name": "Component Name", "responsibility": "What it does", "key_classes": ["Class descriptions"], "interfaces": "API/method signatures", "dependencies": "What it needs to function", "performance": "Targets and constraints" } ], "data_models": "Entity definitions with relationships", "system_boundaries": { "in_scope": ["What the system handles"], "out_of_scope": ["What it delegates or ignores"], "assumptions": ["External dependencies assumed available"] }, "error_handling": "Strategies for failures", "testing_strategy": "Unit, integration, performance", "deployment": "Docker, environment, configuration" }

undefined

6. Generate Implementation Plan

6. 生成实施计划

Break down the project into executable tasks with clear scope boundaries:

python

undefined

将项目拆解为具有清晰范围边界的可执行任务：

python

undefined

Execute this to generate task structure with boundaries

tasks = { "project_boundaries": { "must_have": ["Core features for MVP"], "nice_to_have": ["Enhancement features"], "out_of_scope": ["Features explicitly excluded"], "technical_constraints": ["Framework/library limitations"] }, "phases": [ { "id": 1, "name": "Infrastructure Setup", "deliverables": ["What this phase produces"], "tasks": [ { "id": "1.1", "description": "Task description", "subtasks": ["Specific actions"], "requirements_fulfilled": ["REQ-1.1", "REQ-2.3"], "components_involved": ["COMP-1", "COMP-3"], "dependencies": [], "estimated_hours": 4, "success_criteria": "How to verify completion" } ] } ] }

undefined

tasks = { "project_boundaries": { "must_have": ["Core features for MVP"], "nice_to_have": ["Enhancement features"], "out_of_scope": ["Features explicitly excluded"], "technical_constraints": ["Framework/library limitations"] }, "phases": [ { "id": 1, "name": "Infrastructure Setup", "deliverables": ["What this phase produces"], "tasks": [ { "id": "1.1", "description": "Task description", "subtasks": ["Specific actions"], "requirements_fulfilled": ["REQ-1.1", "REQ-2.3"], "components_involved": ["COMP-1", "COMP-3"], "dependencies": [], "estimated_hours": 4, "success_criteria": "How to verify completion" } ] } ] }

undefined

Requirements Document Template

需求文档模板

markdown

undefined

markdown

undefined

Requirements Document

Introduction

[System description in 2-3 sentences. Target user and deployment model.]

Glossary

Term: Definition specific to this system
Component: Major system module or service [Add all domain-specific terms]

Term: Definition specific to this system
Component: Major system module or service [Add all domain-specific terms]

Requirements

Requirement [NUMBER]

User Story: As a [user type], I want [capability], so that [benefit]

Acceptance Criteria

WHEN [trigger/condition], THE [component] SHALL [action/behavior]
WHERE [mode/context], THE [component] SHALL [action/behavior]
IF [condition], THEN THE [component] SHALL [action/behavior]
THE [component] SHALL [capability with measurable target]

[Repeat for each requirement]

undefined

WHEN [trigger/condition], THE [component] SHALL [action/behavior]
WHERE [mode/context], THE [component] SHALL [action/behavior]
IF [condition], THEN THE [component] SHALL [action/behavior]
THE [component] SHALL [capability with measurable target]

[Repeat for each requirement]

undefined

Requirements Best Practices

需求文档最佳实践

One capability per requirement - Each requirement should address a single feature
Testable criteria - Every criterion must be verifiable
Use SHALL for mandatory - Consistent RFC 2119 keywords
Include performance targets - "within X milliseconds/seconds"
Specify all states - Success, failure, edge cases
Number systematically - REQ-1, REQ-2 for traceability

单一需求对应单一功能 - 每个需求应仅针对一项功能
可测试的验收标准 - 每条标准必须可验证
使用SHALL表示强制性 - 遵循RFC 2119标准关键词
包含性能指标 - 如“在X毫秒/秒内完成”
明确所有状态 - 包括成功、失败与边缘情况
系统编号便于追溯 - 使用REQ-1、REQ-2等格式

Acceptance Criteria Patterns

验收标准模式

Behavior criteria:
- WHEN [event occurs], THE system SHALL [respond]
- THE system SHALL [provide capability]
- THE system SHALL [enforce rule/limit]

Conditional criteria:
- IF [condition], THEN THE system SHALL [action]
- WHERE [mode is active], THE system SHALL [behavior]

Performance criteria:
- THE system SHALL [complete action] within [time]
- THE system SHALL support [number] concurrent [operations]
- THE system SHALL maintain [metric] above/below [threshold]

Data criteria:
- THE system SHALL persist [data type] with [attributes]
- THE system SHALL validate [input] against [rules]
- THE system SHALL return [data] in [format]

行为标准:
- WHEN [事件发生], THE system SHALL [响应]
- THE system SHALL [提供功能]
- THE system SHALL [执行规则/限制]

条件标准:
- IF [条件], THEN THE system SHALL [操作]
- WHERE [模式激活], THE system SHALL [行为]

性能标准:
- THE system SHALL [完成操作] within [时间]
- THE system SHALL support [数量] concurrent [操作]
- THE system SHALL maintain [指标] above/below [阈值]

数据标准:
- THE system SHALL persist [数据类型] with [属性]
- THE system SHALL validate [输入] against [规则]
- THE system SHALL return [数据] in [格式]

Design Document Template

设计文档模板

markdown

undefined

markdown

undefined

Design Document

Overview

[System architecture summary in 3-4 sentences. Key design decisions and priorities.]

System Architecture

Component Map

Component ID	Name	Type	Responsibility	Interfaces With
COMP-1	Web Frontend	UI	User interface	COMP-2
COMP-2	API Gateway	Service	Request routing	COMP-3, COMP-4
COMP-3	Business Logic	Service	Core processing	COMP-5
[Complete component inventory]

Component ID	Name	Type	Responsibility	Interfaces With
COMP-1	Web Frontend	UI	User interface	COMP-2
COMP-2	API Gateway	Service	Request routing	COMP-3, COMP-4
COMP-3	Business Logic	Service	Core processing	COMP-5
[Complete component inventory]

High-Level Architecture Diagram

[ASCII diagram showing all components and their relationships]

Data Flow Specifications

Primary Data Flows

1. [Flow Name] (e.g., User Authentication)

1. [Source] → [Component]: [Data description]
2. [Component] → [Component]: [Transformation applied]
3. [Component] → [Destination]: [Final data format]

Data Transformations:

Step 2: [How data changes]
Step 3: [Validation/Processing applied]

[Repeat for each major data flow]

1. [Source] → [Component]: [Data description]
2. [Component] → [Component]: [Transformation applied]
3. [Component] → [Destination]: [Final data format]

Data Transformations:

Step 2: [How data changes]
Step 3: [Validation/Processing applied]

[Repeat for each major data flow]

Integration Points

Internal Integration Points

Source	Target	Protocol	Data Format	Purpose
Frontend	API Gateway	HTTPS/REST	JSON	API calls
API Gateway	Auth Service	gRPC	Protobuf	Authentication
[All internal integrations]

Source	Target	Protocol	Data Format	Purpose
Frontend	API Gateway	HTTPS/REST	JSON	API calls
API Gateway	Auth Service	gRPC	Protobuf	Authentication
[All internal integrations]

External Integration Points

[External System Name]

Type: REST API / Database / Message Queue / etc. Purpose: [What this integration provides] Endpoint: [URL/Connection string pattern] Authentication: [Method - OAuth2, API Key, etc.] Rate Limits: [Any constraints]

Interface Contract:

language

// Request format
POST /api/endpoint
{
    "field": "type"
}

// Response format  
{
    "result": "type"
}

Error Handling:

Retry strategy: [Exponential backoff, circuit breaker]
Fallback: [What happens if unavailable]
Monitoring: [How to detect issues]

[Repeat for each external integration]

Type: REST API / Database / Message Queue / etc. Purpose: [What this integration provides] Endpoint: [URL/Connection string pattern] Authentication: [Method - OAuth2, API Key, etc.] Rate Limits: [Any constraints]

Interface Contract:

language

// Request format
POST /api/endpoint
{
    "field": "type"
}

// Response format  
{
    "result": "type"
}

Error Handling:

Retry strategy: [Exponential backoff, circuit breaker]
Fallback: [What happens if unavailable]
Monitoring: [How to detect issues]

[Repeat for each external integration]

Components and Interfaces

1. [Component Name]

Responsibility: [Single sentence description]

Key Classes:

```
ClassName
```
: [Purpose and main methods]
```
ServiceName
```
: [What it manages]

Interfaces:

language

class InterfaceName:
    def method_name(params) -> ReturnType
    # Core methods only

Data Flow:

Receives [input] from [source]
Processes by [algorithm/logic]
Outputs [result] to [destination]

Performance:

Target: [metric and value]
Constraints: [limitations]

[Repeat for each major component]

Responsibility: [Single sentence description]

Key Classes:

```
ClassName
```
: [Purpose and main methods]
```
ServiceName
```
: [What it manages]

Interfaces:

language

class InterfaceName:
    def method_name(params) -> ReturnType
    # Core methods only

Data Flow:

Receives [input] from [source]
Processes by [algorithm/logic]
Outputs [result] to [destination]

Performance:

Target: [metric and value]
Constraints: [limitations]

[Repeat for each major component]

Data Models

[Entity Name]

language

@dataclass
class EntityName:
    field: Type
    field: Optional[Type]
    # Core fields only

language

@dataclass
class EntityName:
    field: Type
    field: Optional[Type]
    # Core fields only

Error Handling

[Error Category]

Types: [List of error scenarios] Handling: [Strategy and recovery]

Testing Strategy

Unit Tests

[Component]: Test [aspects]
Coverage target: 80%

[Component]: Test [aspects]
Coverage target: 80%

Integration Tests

[Flow]: Test [end-to-end scenario]

[Flow]: Test [end-to-end scenario]

Performance Tests

[Operation]: Target [metric]

[Operation]: Target [metric]

Deployment

Docker Configuration

yaml

undefined

yaml

undefined

Essential service definitions only

undefined

undefined

Environment Variables

CATEGORY_VAR=description

CATEGORY_VAR=description

Performance Targets

[Operation]: <[time]
[Resource]: <[limit]

[Operation]: <[time]
[Resource]: <[limit]

Security Considerations

[Authentication method if applicable]
[Data protection approach]
[Access control model]

undefined

[Authentication method if applicable]
[Data protection approach]
[Access control model]

undefined

Design Best Practices

设计文档最佳实践

Component responsibilities - Single, clear purpose per component
Interface first - Define contracts before implementation
Data flow clarity - Show how data moves through system
Error categories - Group related failures with consistent handling
Performance targets - Specific, measurable goals
Deployment ready - Include Docker and configuration

组件职责单一 - 每个组件仅承担明确的单一职责
接口优先 - 先定义契约再进行实施
数据流清晰 - 展示数据在系统中的流动路径
错误分类处理 - 将相关故障分组并采用统一处理策略
明确性能指标 - 设定具体可衡量的目标
部署就绪 - 从一开始就包含Docker与部署配置

Implementation Plan Template

实施计划模板

markdown

undefined

markdown

undefined

Implementation Plan

1. [Phase Name]
- 1.1 [Task name]
  - [Subtask description]
  - [Subtask description]
  - Requirements: [REQ-X.Y, REQ-A.B]
- 1.2 [Task name]
  - [Subtask description]
  - Requirements: [REQ-X.Y]
  - Dependencies: Task 1.1
2. [Phase Name]
- 2.1 [Task name]
  - [Detailed steps or subtasks]
  - Requirements: [REQ-X.Y]
  - Dependencies: Phase 1

[Continue for all phases]

undefined

1. [Phase Name]
- 1.1 [Task name]
  - [Subtask description]
  - [Subtask description]
  - Requirements: [REQ-X.Y, REQ-A.B]
- 1.2 [Task name]
  - [Subtask description]
  - Requirements: [REQ-X.Y]
  - Dependencies: Task 1.1
2. [Phase Name]
- 2.1 [Task name]
  - [Detailed steps or subtasks]
  - Requirements: [REQ-X.Y]
  - Dependencies: Phase 1

[Continue for all phases]

undefined

Task Planning Best Practices

任务规划最佳实践

Hierarchical structure - Phases > Tasks > Subtasks
Requirement tracing - Link each task to requirements
Dependency marking - Identify blockers and prerequisites
Checkbox format - [x] for complete, [ ] for pending
Atomic tasks - Each task independently completable
Progressive implementation - Infrastructure → Core → Features → Polish

分层结构 - 阶段 > 任务 > 子任务
需求追溯 - 将每个任务与需求关联
标记依赖关系 - 识别阻塞点与前置条件
复选框格式 - 使用[x]表示完成，[ ]表示待办
原子化任务 - 每个任务可独立完成
渐进式实施 - 基础设施 → 核心功能 → 特色功能 → 优化完善

Common Implementation Phases

常见实施阶段

markdown

1. **Infrastructure Setup**
   - Project structure
   - Database schema
   - Docker configuration
   - Core dependencies

2. **Data Layer**
   - Models/entities
   - Database operations
   - Migrations

3. **Business Logic**
   - Core algorithms
   - Service classes
   - Validation rules

4. **API/Interface Layer**
   - REST/GraphQL endpoints
   - WebSocket handlers
   - Authentication

5. **Frontend/UI**
   - Component structure
   - State management
   - API integration
   - Responsive design

6. **Integration**
   - External services
   - Third-party APIs
   - Message queues

7. **Testing**
   - Unit tests
   - Integration tests
   - End-to-end tests

8. **DevOps**
   - CI/CD pipeline
   - Monitoring
   - Logging
   - Deployment scripts

9. **Documentation**
   - API documentation
   - User guides
   - Deployment guide
   - README

markdown

1. **基础设施搭建**
   - 项目结构
   - 数据库 schema
   - Docker 配置
   - 核心依赖

2. **数据层**
   - 模型/实体
   - 数据库操作
   - 迁移脚本

3. **业务逻辑层**
   - 核心算法
   - 服务类
   - 验证规则

4. **API/接口层**
   - REST/GraphQL 端点
   - WebSocket 处理器
   - 身份认证

5. **前端/UI层**
   - 组件结构
   - 状态管理
   - API 集成
   - 响应式设计

6. **集成阶段**
   - 外部服务
   - 第三方API
   - 消息队列

7. **测试阶段**
   - 单元测试
   - 集成测试
   - 端到端测试

8. **DevOps阶段**
   - CI/CD 流水线
   - 监控
   - 日志
   - 部署脚本

9. **文档阶段**
   - API 文档
   - 用户指南
   - 部署指南
   - README

Document Patterns by Project Type

按项目类型划分的文档模式

Web Application (Full-Stack)

Web应用（全栈）

Requirements focus:

User authentication and authorization
CRUD operations for entities
Real-time updates
Responsive UI
API design

Design focus:

3-tier architecture (Frontend, Backend, Database)
REST/GraphQL API design
State management strategy
Component hierarchy
Database schema

Tasks focus:

Database and backend setup
API implementation
Frontend components
Integration and testing

需求重点:

用户身份认证与授权
实体的CRUD操作
实时更新
响应式UI
API设计

设计重点:

三层架构（前端、后端、数据库）
REST/GraphQL API设计
状态管理策略
组件层级
数据库 schema

任务重点:

数据库与后端搭建
API 实现
前端组件开发
集成与测试

Microservices System

微服务系统

Requirements focus:

Service boundaries
Inter-service communication
Data consistency
Service discovery
Fault tolerance

Design focus:

Service decomposition
API contracts between services
Message queue/event bus
Distributed tracing
Container orchestration

Tasks focus:

Service scaffolding
Shared libraries/contracts
Individual service implementation
Integration layer
Orchestration setup

需求重点:

服务边界
服务间通信
数据一致性
服务发现
容错机制

设计重点:

服务拆分
服务间API契约
消息队列/事件总线
分布式追踪
容器编排

任务重点:

服务脚手架搭建
共享库/契约
单个服务实现
集成层
编排配置

Data Pipeline/ETL

数据管道/ETL

Requirements focus:

Data sources and formats
Transformation rules
Data quality checks
Schedule/triggers
Error handling and retry

Design focus:

Pipeline stages
Data flow diagram
Schema evolution
Monitoring and alerting
Storage strategy

Tasks focus:

Data source connectors
Transformation logic
Validation and quality checks
Scheduling setup
Monitoring implementation

需求重点:

数据源与格式
转换规则
数据质量检查
调度/触发机制
错误处理与重试

设计重点:

管道阶段
数据流图
Schema演进
监控与告警
存储策略

任务重点:

数据源连接器
转换逻辑
验证与质量检查
调度配置
监控实现

CLI Tool/Library

CLI工具/库

Requirements focus:

Command structure
Input/output formats
Configuration options
Error messages
Performance requirements

Design focus:

Command parser architecture
Plugin system (if applicable)
Configuration management
Output formatters
Testing strategy

Tasks focus:

Core command structure
Business logic implementation
Input/output handlers
Configuration system
Documentation and examples

需求重点:

命令结构
输入/输出格式
配置选项
错误信息
性能要求

设计重点:

命令解析器架构
插件系统（如适用）
配置管理
输出格式化
测试策略

任务重点:

核心命令结构
业务逻辑实现
输入/输出处理器
配置系统
文档与示例

Generating Documents for Specific Domains

特定领域的文档生成

Trading/Financial Systems

交易/金融系统

Additional requirements:

Risk management rules
Order execution logic
Market data handling
Compliance requirements
Audit trail

Additional design:

High-frequency data handling
Position tracking
Risk calculations
Order routing
Failover strategies

额外需求:

风险管理规则
订单执行逻辑
市场数据处理
合规要求
审计追踪

额外设计:

高频数据处理
头寸跟踪
风险计算
订单路由
故障转移策略

Real-time Systems (Chat, Gaming, IoT)

实时系统（聊天、游戏、IoT）

Additional requirements:

Latency targets
Connection handling
State synchronization
Offline support
Push notifications

Additional design:

WebSocket/SSE architecture
State management
Caching strategy
Message queuing
Horizontal scaling

额外需求:

延迟指标
连接处理
状态同步
离线支持
推送通知

额外设计:

WebSocket/SSE架构
状态管理
缓存策略
消息队列
水平扩展

Machine Learning Systems

机器学习系统

Additional requirements:

Model training pipeline
Feature engineering
Model versioning
Prediction API
Monitoring/drift detection

Additional design:

Training infrastructure
Feature store
Model registry
Serving architecture
A/B testing framework

额外需求:

模型训练管道
特征工程
模型版本控制
预测API
监控/漂移检测

额外设计:

训练基础设施
特征存储
模型注册表
服务架构
A/B测试框架

Quality Checklist

质量检查清单

Before finalizing documents, verify:

最终确定文档前，请验证：

Requirements Document

需求文档

Every requirement has a clear user story
All acceptance criteria are testable
Non-functional requirements specified (performance, security)
Glossary covers all domain terms
Requirements are numbered for tracing

每个需求都有清晰的User Story
所有验收标准均可测试
已指定非功能性需求（性能、安全）
术语表涵盖所有领域术语
需求已编号便于追溯

Design Document

设计文档

Architecture diagram included
All components have clear responsibilities
Interfaces defined for integration points
Error handling strategy documented
Performance targets specified
Deployment configuration included

Implementation Plan

实施计划

Tasks grouped into logical phases
Dependencies identified between tasks
Requirements traced to tasks
Tasks are atomic and completable
Checkbox format for progress tracking

任务按逻辑阶段分组
已识别任务间的依赖关系
需求已映射到任务
任务为原子化可完成状态
使用复选框跟踪进度

Example Usage Patterns

示例用法模式

Starting a New Project (With Explicit Architecture Focus)

启动新项目（聚焦明确架构）

User: "I want to build an order flow trading automation system"

Response: "I'll act as your Project Architect to create comprehensive planning documents. 

First, let me establish the architectural foundation:

**System Components I need to define:**
- Market data ingestion service
- Order flow analysis engine  
- Trading signal generator
- Risk management module
- Order execution service
- Monitoring dashboard

**Data Flows to map:**
- Market data → Analysis → Signals → Execution
- Position tracking → Risk calculation → Trading limits
- All events → Audit trail

**Integration Points to specify:**
- Exchange APIs (which ones?)
- Database system (time-series data needs?)
- Notification services (alerts/reporting?)

**Key Questions:**
1. Is this for personal use (single-user) or a platform (multi-user)?
2. Which specific exchanges/brokers will it connect to?
3. What are your latency requirements (milliseconds matter)?
4. What's your risk tolerance and position sizing approach?
5. Do you need backtesting capabilities?

**Deliverables I'll create:**
1. Requirements document with traceable user stories
2. System design with complete component map and data flows
3. Implementation plan with phased delivery milestones

This architectural blueprint will ensure nothing is overlooked during implementation."

用户: "我想要构建一个订单流交易自动化系统"

回复: "我将担任您的Project Architect，创建全面的规划文档。

首先，让我建立架构基础：

**需要定义的系统组件：**
- 市场数据摄入服务
- 订单流分析引擎  
- 交易信号生成器
- 风险管理模块
- 订单执行服务
- 监控仪表盘

**需要映射的数据流：**
- 市场数据 → 分析 → 信号 → 执行
- 头寸跟踪 → 风险计算 → 交易限制
- 所有事件 → 审计追踪

**需要明确的集成点：**
- 交易所API（具体是哪些？）
- 数据库系统（是否需要时间序列数据支持？）
- 通知服务（是否需要告警/报告？）

**关键问题：**
1. 这是个人使用（单用户）还是平台（多用户）？
2. 它将连接哪些具体的交易所/经纪商？
3. 您的延迟要求是什么（毫秒级很重要）？
4. 您的风险承受能力与头寸调整策略是什么？
5. 是否需要回测功能？

**我将生成的交付成果：**
1. 包含可追溯User Story的需求文档
2. 包含完整组件图与数据流的系统设计文档
3. 包含分阶段交付里程碑的实施计划

该架构蓝图将确保实施过程中不会遗漏任何内容。"

Starting a New Project (Simple Approach)

启动新项目（简化方式）

User: "I want to build an order flow trading automation system"

Response: "I'll help you create comprehensive planning documents for your trading system. Let me gather some key information:

1. Is this for personal use (single-user) or a multi-user platform?
2. Which markets/exchanges will it connect to?
3. What are the core trading strategies or patterns?
4. Any specific performance requirements (latency, throughput)?

Based on this, I'll generate:
- Requirements document with user stories
- System design with components and data flow
- Implementation plan with phases and tasks"

用户: "我想要构建一个订单流交易自动化系统"

回复: "我将帮助您为交易系统创建全面的规划文档。请提供一些关键信息：

1. 这是个人使用（单用户）还是多用户平台？
2. 它将连接哪些市场/交易所？
3. 核心交易策略或模式是什么？
4. 是否有特定的性能要求（延迟、吞吐量）？

基于这些信息，我将生成：
- 包含User Story的需求文档
- 包含组件与数据流的系统设计文档
- 包含阶段与任务的实施计划"

Expanding Existing Requirements

扩展现有需求

User: "Add real-time monitoring dashboard to the requirements"

Response: "I'll add dashboard requirements to your document:

用户: "在需求中添加实时监控仪表盘"

回复: "我将把仪表盘需求添加到您的文档中：

Requirement 15

需求15

User Story: As a trader, I want a real-time dashboard, so that I can monitor system performance and trading activity

User Story: 作为交易员，我想要一个实时仪表盘，以便监控系统性能与交易活动

Acceptance Criteria

验收标准

THE Dashboard SHALL display active positions with current P&L
THE Dashboard SHALL update market data within 1 second
THE Dashboard SHALL provide filtering by symbol, timeframe, and date range
WHEN a trade executes, THE Dashboard SHALL reflect it within 100ms"

undefined

THE Dashboard SHALL 显示带有当前盈亏的未平仓头寸
THE Dashboard SHALL 在1秒内更新市场数据
THE Dashboard SHALL 支持按标的、时间范围与日期筛选
WHEN 交易执行，THE Dashboard SHALL 在100ms内反映该交易"

undefined

Common Pitfalls to Avoid

需避免的常见陷阱

Planning Pitfalls

规划陷阱

Skipping architectural planning - Jumping to requirements without mapping components first
Vague role definition - Not establishing the architect role leads to unfocused documentation
Hidden integration points - Discovering external dependencies during implementation
Undefined boundaries - No clear scope leads to feature creep and timeline slippage
Missing data flow analysis - Not mapping how data moves reveals issues late

跳过架构规划 - 未先映射组件就直接进入需求定义
角色定义模糊 - 未明确架构师角色会导致文档缺乏焦点
隐藏的集成点 - 在实施过程中才发现外部依赖
边界定义不明确 - 范围不清晰会导致功能蔓延与时间线延误
缺失数据流分析 - 未映射数据流向会在后期暴露问题

Requirements Pitfalls

需求陷阱

Over-specifying implementation - Requirements should define "what" not "how"
Vague acceptance criteria - Avoid "user-friendly" or "fast" without metrics
Missing error cases - Include failure scenarios in requirements
Untraceable requirements - Every requirement should map to tasks

过度指定实现细节 - 需求应定义“做什么”而非“怎么做”
验收标准模糊 - 避免使用“用户友好”或“快速”等无指标描述
缺失错误场景 - 在需求中包含故障场景
需求不可追溯 - 每个需求都应映射到任务

Design Pitfalls

设计陷阱

Monolithic components - Break down large components into focused services
Circular dependencies - Ensure task dependencies form a DAG
Missing data models - Define core entities early
Ignoring deployment - Include Docker/deployment from the start
Unclear component boundaries - Each component needs explicit responsibilities

单体组件 - 将大型组件拆分为聚焦的服务
循环依赖 - 确保任务依赖形成有向无环图（DAG）
缺失数据模型 - 尽早定义核心实体
忽略部署 - 从一开始就包含Docker/部署配置
组件边界不清晰 - 每个组件都需要明确的职责

Output Format

输出格式

Generate documents in Markdown format for easy editing and version control. Use:

Clear hierarchical headings (##, ###, ####)
Code blocks with language hints
Bulleted and numbered lists
Tables for structured data
Checkboxes for task tracking
Bold for emphasis on key terms
Inline code for technical terms

Save documents as:

```
requirements.md
```
- Requirements document
```
design.md
```
- Design document
```
tasks.md
```
- Implementation plan

These documents serve as the foundation for AI-assisted implementation, providing clear specifications that can be referenced throughout development.

使用Markdown格式生成文档，便于编辑与版本控制。请使用：

清晰的层级标题（##、###、####）
带语言提示的代码块
项目符号与编号列表
表格展示结构化数据
复选框跟踪任务进度
粗体强调关键术语
行内代码标记技术术语

将文档保存为：

```
requirements.md
```
- 需求文档
```
design.md
```
- 设计文档
```
tasks.md
```
- 实施计划

这些文档将作为AI辅助实施的基础，提供可在整个开发过程中参考的明确规格说明。

project-planner

Original

Translation

Project Planner Skill

Project Planner Skill

Quick Start

快速开始

Why Explicit Architectural Planning Works

明确架构规划为何有效

Benefits of Upfront Definition

提前定义的优势

The Architect Mindset

架构师思维模式

Document Generation Workflow

文档生成工作流

1. Project Architect Role Definition

1. Project Architect角色定义

2. Initial Project Understanding

2. 初始项目理解

3. Deliverable Definition (Set Upfront)

3. 交付成果定义（提前设定）

4. Generate Requirements Document

4. 生成需求文档

Execute this to generate requirements structure

Execute this to generate requirements structure

5. Generate Design Document

5. 生成设计文档

Execute this to generate comprehensive design structure

Execute this to generate comprehensive design structure

6. Generate Implementation Plan

6. 生成实施计划

Execute this to generate task structure with boundaries

Execute this to generate task structure with boundaries

Requirements Document Template

需求文档模板

Requirements Document

Requirements Document

Introduction

Introduction

Glossary

Glossary

Requirements

Requirements

Requirement [NUMBER]

Requirement [NUMBER]

Acceptance Criteria

Acceptance Criteria

Requirements Best Practices

需求文档最佳实践

Acceptance Criteria Patterns

验收标准模式

Design Document Template

设计文档模板

Design Document

Design Document

Overview

Overview

System Architecture

System Architecture

Component Map

Component Map

High-Level Architecture Diagram

High-Level Architecture Diagram

Data Flow Specifications

Data Flow Specifications

Primary Data Flows

Primary Data Flows

1. [Flow Name] (e.g., User Authentication)

1. [Flow Name] (e.g., User Authentication)

Integration Points

Integration Points

Internal Integration Points

Internal Integration Points

External Integration Points

External Integration Points

[External System Name]

[External System Name]

Components and Interfaces

Components and Interfaces

1. [Component Name]