project-planner

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Planner

项目规划工具

When to Use

适用场景

Activate this skill when:

Breaking down a feature request or user story into an implementation plan
Sprint planning or backlog refinement for a Python/React project
Designing a new module, service, or feature area
Estimating the overall complexity of a proposed change
Identifying file-level impact before starting implementation
Mapping the impact of a change across backend and frontend layers

Do NOT use this skill for:

Architecture decisions or technology trade-offs (use
```
system-architecture
```
)

Writing implementation code (use

python-backend-expert

react-frontend-expert

)

API contract design (use
```
api-design-patterns
```
)
Decomposing into atomic implementation tasks (use
```
task-decomposition
```
)

激活该工具的场景：

将功能需求、用户故事拆解为实施计划
Python/React项目的迭代规划或待办事项梳理
设计新模块、服务或功能领域
估算拟议变更的整体复杂度
开始实施前识别文件级别的影响范围
梳理变更对前后端各层的影响范围

不适用场景：

架构决策或技术选型（请使用
```
system-architecture
```
工具）

编写实现代码（请使用

python-backend-expert

或

react-frontend-expert

工具）

API契约设计（请使用
```
api-design-patterns
```
工具）
拆解为原子级实施任务（请使用
```
task-decomposition
```
工具）

Instructions

使用指南

Planning Workflow

规划工作流

Follow this 4-step workflow for every planning request:

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

Step 1: Analyze the Requirement

步骤1：需求分析

Read the feature request, user story, or product requirement in full
Identify the core objective — what value does this deliver?
List explicit inputs (what triggers the feature) and outputs (what the user sees)
Note ambiguities or missing details — list them as open questions
Determine if this is a new feature, enhancement, bug fix, or refactoring

完整阅读功能需求、用户故事或产品需求
明确核心目标——该需求能带来什么价值？
列出明确的输入（触发该功能的条件）和输出（用户可见的结果）
记录模糊点或缺失的细节，将其列为待确认问题
判断需求类型：新功能、功能增强、Bug修复还是代码重构

Step 2: Map Affected Modules

步骤2：映射受影响模块

Scan the project and identify every file or module area affected by the change:

Backend (FastAPI):

```
routes/
```
— New or modified endpoint handlers
```
services/
```
— Business logic changes
```
repositories/
```
— Data access layer changes
```
models/
```
— SQLAlchemy model changes (triggers migration)
```
schemas/
```
— Pydantic request/response schema changes
```
core/
```
— Configuration, security, or middleware changes
```
migrations/
```
— Alembic migration files

Frontend (React/TypeScript):

```
pages/
```
— New or modified page components
```
components/
```
— Shared UI component changes
```
hooks/
```
— Custom hook changes or additions
```
services/
```
— API client changes (TanStack Query keys, mutations)
```
types/
```
— Shared TypeScript type definitions
```
utils/
```
— Utility function changes

Shared / Cross-cutting:

```
types/
```
or
```
shared/
```
— Types shared between backend and frontend
```
.env
```
/ config — Environment variable changes
```
tests/
```
— Test files for each changed module

Present the module map as a table:

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

梳理项目，识别所有受变更影响的文件或模块区域：

后端（FastAPI）：

```
routes/
```
— 新增或修改接口处理器
```
services/
```
— 业务逻辑变更
```
repositories/
```
— 数据访问层变更
```
models/
```
— SQLAlchemy模型变更（触发数据库迁移）
```
schemas/
```
— Pydantic请求/响应 schema 变更
```
core/
```
— 配置、安全或中间件变更
```
migrations/
```
— Alembic 迁移文件

前端（React/TypeScript）：

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

共享/跨领域：

```
types/
```
或
```
shared/
```
— 前后端共享类型
```
.env
```
/ 配置文件 — 环境变量变更
```
tests/
```
— 各变更模块对应的测试文件

请以表格形式呈现模块映射：

| 层级    | 模块           | 变更类型       | 影响范围    |
|----------|-----------------|-------------------|-----------|
| 后端  | models/user.py  | 新增字段         | 数据库迁移 |
| 后端  | schemas/user.py | 新增响应字段| API契约变更|
| 前端 | hooks/useUser.ts| 更新查询逻辑      | UI变更 |

Step 3: Define Verification Criteria

步骤3：定义验证标准

Define how the completed feature will be verified:

Integration verification:

End-to-end test scenario describing the complete user flow
Manual smoke test steps if automated E2E is not available

Regression check:

Existing tests still pass:
```
pytest -x && npm test
```
No type errors:
```
mypy src/ && npx tsc --noEmit
```
No lint issues:
```
ruff check src/ && npm run lint
```

定义已完成功能的验证方式：

集成验证：

描述完整用户流程的端到端测试场景
若没有自动化端到端测试，则提供手动冒烟测试步骤

回归检查：

现有测试全部通过：
```
pytest -x && npm test
```
无类型错误：
```
mypy src/ && npx tsc --noEmit
```
无代码规范问题：
```
ruff check src/ && npm run lint
```

Step 4: Identify Risks and Unknowns

步骤4：识别风险与未知项

Flag potential issues using the categories below. For each risk:

Risk: Description of what could go wrong
Likelihood: Low / Medium / High
Impact: Low / Medium / High
Mitigation: How to reduce or eliminate the risk

See

references/risk-assessment-checklist.md

for the complete risk category list.

按照以下类别标记潜在问题。针对每个风险，需包含：

风险： 可能出现的问题描述
可能性： 低/中/高
影响程度： 低/中/高
缓解方案： 降低或消除风险的方法

完整的风险类别列表请查看

references/risk-assessment-checklist.md

。

Output Format

输出格式

Write the plan to a file at the project root: plan.md
(or

plan-<feature-name>.md

if multiple plans exist). Use

references/plan-template.md

as the template.

The file must contain:

markdown

undefined

将规划写入项目根目录下的**

plan.md

**文件（若存在多个规划，可命名为

plan-<功能名称>.md

）。请使用

references/plan-template.md

作为模板。

文件必须包含以下内容：

markdown

undefined

Implementation Plan: [Feature Name]

实施计划：[功能名称]

Objective

目标

[1-2 sentence summary of what this delivers]

[1-2句话总结该功能的价值]

Context

背景

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

触发来源：[用户故事 / 功能需求 / Bug报告]
关联工作：[关联规划、架构决策记录或PR的链接]

Open Questions

待确认问题

[List ambiguities that need resolution before implementation]

[列出实施前需要解决的模糊点]

Affected Modules

受影响模块

[Module map table from Step 2]

[步骤2中的模块映射表格]

Verification

验证方式

[Integration verification from Step 3]

[步骤3中的集成验证内容]

Risks & Unknowns

风险与未知项

[Risk table from Step 4]

[步骤4中的风险表格]

Acceptance Criteria

验收标准

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

[可观测的结果列表，用于确认功能正常工作]

Estimation Summary

复杂度估算总结

[Overall complexity estimate — see table below]


**Always write the plan to a file.** This enables `/task-decomposition` to read it as input. After writing, tell the user: "Plan written to `plan.md`. Run `/task-decomposition` to break it into atomic tasks."

[以下表格]


**请务必将规划写入文件**。这样`/task-decomposition`工具才能读取该文件作为输入。写入完成后，请告知用户："规划已写入`plan.md`。运行`/task-decomposition`可将其拆解为原子任务。"

Estimation Summary

复杂度估算总结

Estimate overall feature complexity using this table:

Metric	Value
Total backend modules affected	[N]
Total frontend modules affected	[N]
Migration required	Yes / No
API changes	Yes / No (new endpoints / modified contracts)
Overall complexity	trivial / small / medium / large

Complexity guidelines:

Trivial: 1-2 modules, no migration, <50 lines
Small: 2-4 modules, no migration, <200 lines
Medium: 4-8 modules, migration possible, <500 lines
Large: 8+ modules, migration likely, 500+ lines

使用以下表格估算功能的整体复杂度：

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

复杂度判定标准：

微小： 1-2个模块，无需迁移，代码量<50行
小型： 2-4个模块，无需迁移，代码量<200行
中型： 4-8个模块，可能需要迁移，代码量<500行
大型： 8个以上模块，大概率需要迁移，代码量500+行

Examples

示例

Example: Plan "Add User Profile Picture Upload"

示例："添加用户头像上传"规划

Objective: Allow users to upload and display a profile picture.

Affected Modules:

Layer	Module	Change Type	Impact
Backend	models/user.py	Add avatar_url	Migration
Backend	schemas/user.py	Add field	API contract
Backend	services/upload.py	New service	New file
Backend	routes/users.py	Add endpoint	API change
Frontend	components/AvatarUpload	New component	UI change
Frontend	hooks/useUploadAvatar.ts	New hook	Data fetch
Frontend	pages/ProfilePage.tsx	Integrate	UI change

Verification:

Upload an image via the profile page, verify it displays
Upload an oversized file, verify rejection with error message
Regression:
```
pytest -x && npm test
```

Risks:

File size limits need validation (server + client) — Medium likelihood — Add early validation
S3 permissions may need configuration — Low likelihood — Test with local storage first

Acceptance Criteria:

User can upload a profile picture from the profile page
Uploaded image displays as the user's avatar across the app
Files over 5MB are rejected with a clear error message
Non-image files are rejected
All existing tests pass

Estimation Summary:

Metric	Value
Backend modules affected	4
Frontend modules affected	3
Migration required	Yes
API changes	Yes (new upload endpoint)
Overall complexity	medium

Output: Written to

plan.md

. Run

/task-decomposition

to break it into atomic tasks.

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

受影响模块：

层级	模块路径	变更类型	影响范围
后端	models/user.py	新增avatar_url字段	数据库迁移
后端	schemas/user.py	新增字段	API契约变更
后端	services/upload.py	新增服务	新增文件
后端	routes/users.py	新增接口	API变更
前端	components/AvatarUpload	新增组件	UI变更
前端	hooks/useUploadAvatar.ts	新增Hook	数据获取变更
前端	pages/ProfilePage.tsx	集成组件	UI变更

验证方式：

通过个人资料页面上传图片，验证图片是否正常展示
上传超大文件，验证系统是否拒绝并返回错误提示
回归检查：
```
pytest -x && npm test
```

风险：

文件大小限制需要在服务端和客户端双重验证 — 可能性中等 — 提前添加验证逻辑
S3权限可能需要配置 — 可能性低 — 先使用本地存储测试

验收标准：

用户可从个人资料页面上传头像
上传的图片在全应用中作为用户头像展示
超过5MB的文件会被拒绝并显示清晰的错误提示
非图片文件会被拒绝
所有现有测试全部通过

复杂度估算总结：

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

输出： 已写入

plan.md

。运行

/task-decomposition

可将其拆解为原子任务。

Edge Cases

边缘场景

Cross-cutting changes (auth middleware, error handling, logging): These affect many modules. Flag for architecture review before planning. Consider whether the change should be its own plan.
Database migrations with data transformation: Flag as a risk. Note that migration testing (upgrade + rollback) is needed. Task-decomposition will create a dedicated migration task.
Frontend state cascades: When modifying shared state (React Context, TanStack Query cache), map the component tree to identify all consumers in the module map.
API breaking changes: If modifying an existing endpoint's contract, check for frontend consumers first. Consider API versioning if external consumers exist. Note in the plan that frontend updates must be coordinated.
Feature flags: For large features spanning multiple sprints, note in the plan that a feature flag is needed. Task-decomposition will handle the implementation ordering.
Third-party dependency updates: If the feature requires a new package, list it in the plan's affected modules. Note potential peer dependency conflicts as a risk.

跨领域变更（认证中间件、错误处理、日志）：这类变更会影响多个模块。规划前需标记为需要架构评审，考虑是否将该变更作为独立规划项。
涉及数据转换的数据库迁移：标记为风险项。需注明需要进行迁移测试（升级+回滚）。task-decomposition工具会创建专门的迁移任务。
前端状态连锁反应：修改共享状态（React Context、TanStack Query缓存）时，需梳理组件树，在模块映射图中标记所有依赖该状态的组件。
破坏性API变更：若修改现有接口的契约，需先检查前端依赖情况。若存在外部消费者，需考虑API版本化。请在规划中注明前端更新需要同步协调。
功能开关：对于跨多个迭代的大型功能，需在规划中注明需要使用功能开关。task-decomposition工具会处理实施顺序。
第三方依赖更新：若功能需要新增第三方包，需在规划的受影响模块中列出。需将潜在的 peer 依赖冲突标记为风险项。