project-planner

项目规划技能

执行环境

路径类型	说明
使用方式	此技能提供模板和指导，无需本地脚本执行
调用场景	当用户需要项目规划、需求文档、系统设计时自动激活
输出格式	Markdown 文档（requirements.md、design.md、tasks.md）

路径说明

• 无本地路径依赖：此技能生成文档模板，不涉及本地脚本执行
• 生成的文档：保存在执行命令时的当前目录（process.cwd()）
• 项目上下文：基于当前工作目录确定项目根目录

此技能提供模板和指导，用于生成全面的项目规划文档，为 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. 监控实现

命令行工具/库

需求重点：

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

设计重点：

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

任务重点：

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

为特定领域生成文档

交易/金融系统

附加要求：

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

附加设计：

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

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

附加要求：

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

附加设计：

• 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. 循环依赖 - 确保任务依赖关系构成有向无环图
3. 缺少数据模型 - 尽早定义核心实体
4. 忽略部署 - 从一开始就纳入 Docker/部署
5. 组件边界不清 - 为每个组件明确定义职责

输出格式

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

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

将文档保存为：

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

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