project-planner

Project Planner Skill

此技能提供用于生成全面项目规划文档的模板和指导，这些文档将作为 AI 辅助实施的蓝图。

快速开始

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

1. 需求文档 - 包含验收标准的用户故事
2. 设计文档 - 技术架构和组件规范
3. 实施计划 - 带有需求追踪的分层任务拆解

为什么明确的架构规划行之有效

预先明确角色、职责和交付成果，可显著改善项目结果：

提前定义的优势

1. 组件清晰 - 首先定义所有系统组件，可防止范围蔓延并确保覆盖完整
2. 数据流可见 - 尽早绘制数据流动路径，可揭示集成复杂性和性能瓶颈
3. 集成规划 - 提前识别所有接触点，可避免实施期间出现意外依赖
4. 边界明确 - 明确说明范围内和范围外的内容，有助于集中精力并防止功能偏离
5. 成功可衡量 - 明确的目标和约束有助于客观跟踪进度

架构师思维

担任 项目架构师 时，请按以下方式开展规划：

• 系统思维 - 先了解整体，再深入各个部分
• 接口优先设计 - 先定义组件间的契约，再设计内部实现
• 关注可追踪性 - 每项需求都映射到设计元素和任务
• 了解约束 - 提前承认限制，以指导决策
• 以交付成果为导向 - 明确知道要产出哪些工件

文档生成工作流

1. 项目架构师角色定义

启动项目时，明确将 Claude 设定为 项目架构师，并明确其职责：

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

• 定义包含所有组件的完整系统架构
• 绘制系统各元素之间的数据流
• 识别所有集成点和接口
• 明确项目边界和约束
• 创建可追踪至实施任务的需求

2. 初步了解项目

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

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. 定义交付成果（提前设定）

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

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. 生成需求文档

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

# 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]"
            ]
        }
    ]
}

5. 生成设计文档

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

# 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"
}

6. 生成实施计划

将项目拆解为可执行任务，并明确范围边界：

# 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"
                }
            ]
        }
    ]
}

需求文档模板

# 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]

## Requirements

### Requirement [NUMBER]

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

#### Acceptance Criteria

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

[Repeat for each requirement]

需求最佳实践

1. 每项需求对应一项能力 - 每项需求应针对单一功能
2. 标准可测试 - 每条标准都必须可验证
3. 强制要求使用 SHALL - 保持 RFC 2119 关键词一致
4. 包含性能目标 - “在 X 毫秒/秒内”
5. 明确所有状态 - 成功、失败和边缘情况
6. 系统化编号 - 使用 REQ-1、REQ-2 等编号以便追踪

验收标准模式

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]

设计文档模板

# 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]

### 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. [源] → [组件]：[数据描述]
2. [组件] → [组件]：[应用的转换]
3. [组件] → [目标]：[最终数据格式]

**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]

### 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"
}

错误处理：

• 重试策略：[指数退避、熔断器]
• 回退方案：[不可用时的处理方式]
• 监控：[问题检测方式]

[对每项外部集成重复上述内容]

组件和接口

1. [组件名称]

职责： [一句话描述]

关键类：

• ClassName：[用途和主要方法]
• ServiceName：[管理的内容]

接口：

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

数据流：

• 从 [来源] 接收 [输入]
• 通过 [算法/逻辑] 进行处理
• 将 [结果] 输出到 [目标]

性能：

• 目标：[指标和值]
• 限制：[限制条件]

[对每个主要组件重复此部分]

数据模型

[实体名称]

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

错误处理

[错误类别]

类型： [错误场景列表] 处理方式： [策略和恢复方式]

测试策略

单元测试

• [组件]：测试 [方面]
• 覆盖率目标：80%

集成测试

• [流程]：测试 [端到端场景]

性能测试

• [操作]：目标 [指标]

部署

Docker 配置

# Essential service definitions only

环境变量

CATEGORY_VAR=description

性能目标

• [操作]：<[时间]
• [吞吐量]：>[速率]
• [资源]：<[限制]

安全注意事项

• [适用时填写身份验证方法]
• [数据保护方案]
• [访问控制模型]

### Design Best Practices

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

## Implementation Plan Template

```markdown
# Implementation Plan

- [x] 1. [Phase Name]
  
  - [x] 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]

任务规划最佳实践

1. 层级结构 - 阶段 > 任务 > 子任务
2. 需求追踪 - 将每项任务关联到需求
3. 依赖标记 - 确定阻塞项和前置条件
4. 复选框格式 - 已完成用 [x]，待处理用 [ ]
5. 原子任务 - 每项任务均可独立完成
6. 渐进式实施 - 基础设施 → 核心 → 功能 → 润色

常见实施阶段

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

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

Web 应用（全栈）

需求重点：

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

设计重点：

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

任务重点：

1. 数据库和后端设置
2. API 实现
3. 前端组件
4. 集成和测试

微服务系统

需求重点：

• 服务边界
• 服务间通信
• 数据一致性
• 服务发现
• 容错能力

设计重点：

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

任务重点：

1. 服务脚手架搭建
2. 共享库/契约
3. 各个服务的实现
4. 集成层
5. 编排设置

数据管道/ETL

需求重点：

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

设计重点：

• 管道阶段
• 数据流图
• 模式演进
• 监控和告警
• 存储策略

任务重点：

1. 数据源连接器
2. 转换逻辑
3. 验证和质量检查
4. 调度设置
5. 监控实现

CLI 工具/库

需求重点：

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

设计重点：

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

任务重点：

1. 核心命令结构
2. 业务逻辑实现
3. 输入/输出处理器
4. 配置系统
5. 文档和示例

为特定领域生成文档

交易/金融系统

额外需求：

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

额外设计：

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

实时系统（聊天、游戏、物联网）

其他要求：

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

其他设计：

• WebSocket/SSE 架构
• 状态管理
• 缓存策略
• 消息队列
• 横向扩展

机器学习系统

其他要求：

• 模型训练流水线
• 特征工程
• 模型版本管理
• 预测 API
• 监控／漂移检测

其他设计：

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

质量检查清单

定稿文档前，请确认：

需求文档

• 每项需求都有明确的用户故事
• 所有验收标准均可测试
• 已指定非功能性需求（性能、安全性）
• 术语表涵盖所有领域术语
• 需求已编号，便于追踪

设计文档

• 已包含架构图
• 所有组件都有明确的职责
• 已定义集成点的接口
• 已记录错误处理策略
• 已指定性能目标
• 已包含部署配置

实施计划

• 任务已分组为逻辑阶段
• 已明确任务之间的依赖关系
• 需求已追踪到任务
• 任务粒度适当且可完成
• 使用复选框格式跟踪进度

使用示例

启动新项目（明确关注架构）

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."

启动新项目（简单方式）

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"

扩展现有需求

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

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

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

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

应避免的常见陷阱

规划陷阱

1. 跳过架构规划 - 未先梳理组件就直接开始编写需求
2. 角色定义模糊 - 未确立架构师角色会导致文档缺乏重点
3. 隐藏集成点 - 在实施期间才发现外部依赖
4. 边界未定义 - 缺少明确范围会导致功能蔓延和进度延误
5. 缺少数据流分析 - 未梳理数据流向会导致问题迟迟未被发现

需求陷阱

1. 过度规定实现方式 - 需求应定义“做什么”，而非“怎么做”
2. 验收标准模糊 - 避免使用“易于使用”或“快速”等缺少衡量指标的表述
3. 遗漏错误情况 - 在需求中纳入失败场景
4. 需求无法追踪 - 每项需求都应关联到任务

设计陷阱

1. 单体组件 - 将大型组件拆分为职责专一的服务
2. 循环依赖 - 确保任务依赖关系构成有向无环图（DAG）
3. 缺少数据模型 - 尽早定义核心实体
4. 忽略部署 - 从一开始就纳入 Docker／部署规划
5. 组件边界不清晰 - 每个组件都需要明确的职责

输出格式

以 Markdown 格式生成文档，便于编辑和进行版本控制。使用：

• 清晰的层级标题（##、###、####）
• 带语言标注的代码块
• 无序列表和有序列表
• 用于结构化数据的表格
• 用于任务跟踪的复选框
• 用于强调关键术语的粗体
• 用于技术术语的行内代码

将文档保存为：

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

这些文档是 AI 辅助实施的基础，可提供清晰的规范，供整个开发过程中参考。