project-planner

项目规划器

适用场景

在以下情况下启用此技能：

• 将功能需求或用户故事拆分为实施计划
• 为 Python/React 项目进行冲刺规划或待办事项细化
• 设计新模块、服务或功能领域
• 评估拟议变更的整体复杂度
• 在开始实施前识别文件级影响
• 梳理变更对后端和前端各层的影响

以下情况请勿使用此技能：

• 架构决策或技术权衡（使用 system-architecture）
• 编写实施代码（使用 python-backend-expert 或 react-frontend-expert）
• API 契约设计（使用 api-design-patterns）
• 拆解为原子实施任务（使用 task-decomposition）

说明

规划工作流

对每个规划请求，遵循以下 4 步工作流：

第 1 步：分析需求

1. 完整阅读功能需求、用户故事或产品需求
2. 确定核心目标——这能带来什么价值？
3. 列出明确的输入（触发功能的条件）和输出（用户会看到什么）
4. 记录模糊之处或缺失细节——将其列为待解决问题
5. 判断这是新功能、功能增强、错误修复还是重构

第 2 步：梳理受影响模块

扫描项目，识别变更影响的每个文件或模块区域：

后端（FastAPI）：

• routes/ — 新增或修改的端点处理程序
• services/ — 业务逻辑变更
• repositories/ — 数据访问层变更
• models/ — SQLAlchemy 模型变更（会触发迁移）
• schemas/ — Pydantic 请求/响应模式变更
• core/ — 配置、安全或中间件变更
• migrations/ — Alembic 迁移文件

前端（React/TypeScript）：

• pages/ — 新增或修改的页面组件
• components/ — 共享 UI 组件变更
• hooks/ — 自定义 Hook 的变更或新增
• services/ — API 客户端变更（TanStack Query 键、变更操作）
• types/ — 共享 TypeScript 类型定义
• utils/ — 工具函数变更

共享 / 跨领域：

• types/ 或 shared/ — 后端与前端共享的类型
• .env / config — 环境变量变更
• tests/ — 每个变更模块对应的测试文件

将模块映射整理为表格：

| Layer    | Module           | Change Type       | Impact    |
|----------|-----------------|-------------------|-----------|
| Backend  | models/user.py  | Add field         | Migration |
| Backend  | schemas/user.py | Add response field| API change|
| Frontend | hooks/useUser.ts| Update query      | UI change |

第 3 步：定义验证标准

定义如何验证已完成的功能：

集成验证：

• 描述完整用户流程的端到端测试场景
• 如果没有自动化 E2E 测试，则列出手动冒烟测试步骤

回归检查：

• 现有测试仍能通过：pytest -x && npm test
• 无类型错误：mypy src/ && npx tsc --noEmit
• 无 lint 问题：ruff check src/ && npm run lint

第 4 步：识别风险和未知事项

使用以下类别标记潜在问题。每项风险都应包含：

• 风险： 可能出现的问题描述
• 可能性： 低 / 中 / 高
• 影响： 低 / 中 / 高
• 缓解措施： 如何降低或消除风险

完整的风险类别列表请参阅 references/risk-assessment-checklist.md。

输出格式

将计划写入项目根目录下的文件：plan.md（如果存在多个计划，则使用 plan-<feature-name>.md）。使用 references/plan-template.md 作为模板。

文件必须包含：

# Implementation Plan: [Feature Name]

## Objective
[1-2 sentence summary of what this delivers]

## Context
- Triggered by: [user story / feature request / bug report]
- Related work: [links to related plans, ADRs, or PRs]

## Open Questions
[List ambiguities that need resolution before implementation]

## Affected Modules
[Module map table from Step 2]

## Verification
[Integration verification from Step 3]

## Risks & Unknowns
[Risk table from Step 4]

## Acceptance Criteria
[Bullet list of observable outcomes that confirm the feature works]

## Estimation Summary
[Overall complexity estimate — see table below]

务必将计划写入文件。 这样 /task-decomposition 就能读取该文件作为输入。写入后，告知用户：“计划已写入 plan.md。运行 /task-decomposition 将其拆分为原子任务。”

复杂度估算摘要

使用此表估算功能的整体复杂度：

指标	值
受影响的后端模块总数	[N]
受影响的前端模块总数	[N]
是否需要迁移	是 / 否
API 变更	是 / 否（新增端点 / 修改契约）
整体复杂度	极小 / 小 / 中 / 大

复杂度指南：

• 极小： 1-2 个模块，无需迁移，少于 50 行
• 小： 2-4 个模块，无需迁移，少于 200 行
• 中： 4-8 个模块，可能需要迁移，少于 500 行
• 大： 8 个以上模块，很可能需要迁移，500 行以上

示例

示例：计划“添加用户头像上传”

目标： 允许用户上传并显示头像。

受影响的模块：

层	模块	变更类型	影响
后端	models/user.py	添加 avatar_url	迁移
后端	schemas/user.py	添加字段	API 契约
后端	services/upload.py	新服务	新文件
后端	routes/users.py	添加端点	API 变更
前端	components/AvatarUpload	新组件	UI 变更
前端	hooks/useUploadAvatar.ts	新钩子	数据获取
前端	pages/ProfilePage.tsx	集成	UI 变更

验证：

• 通过个人资料页上传图片，并确认图片显示正常
• 上传超大文件，并确认系统拒绝上传且显示错误消息
• 回归测试：pytest -x && npm test

风险：

• 需要验证文件大小限制（服务端 + 客户端）——可能性中等——尽早进行验证
• 可能需要配置 S3 权限——可能性低——先使用本地存储进行测试

验收标准：

• 用户可以从个人资料页上传头像
• 上传的图片会作为用户头像显示在应用的各处
• 超过 5MB 的文件会被拒绝，并显示清晰的错误消息
• 非图片文件会被拒绝
• 所有现有测试均通过

复杂度估算摘要：

指标	值
受影响的后端模块	4
受影响的前端模块	3
是否需要迁移	是
API 变更	是（新增上传端点）
整体复杂度	中

输出： 写入 plan.md。运行 /task-decomposition，将其拆分为原子任务。

边缘情况

• 跨领域变更（身份验证中间件、错误处理、日志记录）：这些变更会影响许多模块。规划前应标记并进行架构审查。考虑是否应将此变更单独制定计划。

• 包含数据转换的数据库迁移：将其标记为风险。注明需要测试迁移（升级 + 回滚）。Task-decomposition 会创建专门的迁移任务。

• 前端状态级联：修改共享状态（React Context、TanStack Query 缓存）时，在模块映射中梳理组件树，找出所有使用方。

• API 破坏性变更：如果修改现有端点的契约，请先检查前端使用方。如果存在外部使用方，可考虑 API 版本控制。在计划中注明必须协调前端更新。

• 功能标志：对于跨多个冲刺的大型功能，在计划中注明需要功能标志。Task-decomposition 会处理实现顺序。

• 第三方依赖更新：如果功能需要新增软件包，请在计划的受影响模块中列出。将潜在的对等依赖冲突注明为风险。