frontend-planning

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

frontend-planning

前端规划

6-step planning document pipeline for frontend projects, organized by domain.

面向前端项目的6步规划文档流水线，按领域进行组织。

When to Use

适用场景

User says "프론트엔드 기획", "frontend planning", "UI 설계", "화면 설계"
User says "프론트엔드 문서", "기획 문서 만들어줘", "plan frontend"
Starting a new frontend project that needs structured design documents
Adding a major frontend feature that requires multi-page planning

用户提及“프론트엔드 기획”（前端规划）、“frontend planning”、“UI 설계”（UI设计）、“화면 설계”（界面设计）
用户提及“프론트엔드 문서”（前端文档）、“기획 문서 만들어줘”（帮我做规划文档）、“plan frontend”
启动需要结构化设计文档的新前端项目
添加需要多页面规划的重大前端功能

When NOT to Use

不适用场景

Backend-only projects (use the backend planning pipeline instead)
Fixing a single component or small UI tweak
Editing or updating existing specification documents
Non-UI work such as CI/CD, infrastructure, or tooling

纯后端项目（请使用后端规划流水线）
修复单个组件或小的UI调整
编辑或更新现有规范文档
非UI相关工作，如CI/CD、基础设施或工具配置

Pipeline Overview

流水线概述

text

Step 0:   Tech stack detection
Step 0.5: Domain analysis & document discovery
Step 1:   Requirements
Step 2:   User Flows
Step 3:   Page Spec
Step 4:   Use Cases
Step 5:   Component Tree
Step 6:   State & API Integration
Step 7:   README (table of contents)

For multi-domain projects, Steps 1–6 are completed for each domain before moving to the next. Step 7 runs once at the end to generate the index.

text

步骤0:   技术栈检测
步骤0.5: 领域分析与文档发现
步骤1:   需求分析
步骤2:   用户流程
步骤3:   页面规范
步骤4:   用例设计
步骤5:   组件树
步骤6:   状态与API集成
步骤7:   README（目录）

对于多领域项目，需完成每个领域的步骤1–6后，再进入下一个领域。步骤7在最后执行一次，用于生成索引。

Output Structure

输出结构

text

docs/en/specifications/
├── architecture.md              # Project folder structure (created by init-docs)
├── config.md                    # Environment variables (created by init-docs)
├── infrastructure.md            # Infrastructure description (created by init-docs)
├── README.md                    # Index of all domains/documents (Step 7)
├── <domain-a>/
│   ├── requirements/
│   │   └── requirements.md      # Step 1
│   └── workflows/
│       ├── user-flows.md        # Step 2
│       ├── page-spec.md         # Step 3
│       ├── use-cases.md         # Step 4
│       ├── component-tree.md    # Step 5
│       └── state-api-integration.md  # Step 6
└── <domain-b>/
    ├── requirements/
    └── workflows/

text

docs/en/specifications/
├── architecture.md              # 项目文件夹结构（由init-docs创建）
├── config.md                    # 环境变量（由init-docs创建）
├── infrastructure.md            # 基础设施说明（由init-docs创建）
├── README.md                    # 所有领域/文档的索引（步骤7）
├── <domain-a>/
│   ├── requirements/
│   │   └── requirements.md      # 步骤1
│   └── workflows/
│       ├── user-flows.md        # 步骤2
│       ├── page-spec.md         # 步骤3
│       ├── use-cases.md         # 步骤4
│       ├── component-tree.md    # 步骤5
│       └── state-api-integration.md  # 步骤6
└── <domain-b>/
    ├── requirements/
    └── workflows/

Step-by-Step Instructions

分步说明

Step 0: Detect Tech Stack

步骤0：检测技术栈

Before generating any documents, detect the project's tech stack:

Read
```
package.json
```
— check for React, Vue, Next.js, Nuxt, Svelte, Angular, etc.
Read
```
tsconfig.json
```
— check if TypeScript is used
Scan directory structure —
```
src/
```
,
```
app/
```
,
```
pages/
```
,
```
components/
```
Check for styling solutions — Tailwind, styled-components, CSS Modules, etc.
Check for state management — Redux, Zustand, Recoil, Pinia, etc.

Summarize the detected stack and confirm with the user:

Detected tech stack:

Framework: Next.js 14 (App Router)

Language: TypeScript

Styling: Tailwind CSS

State: Zustand

I'll generate planning documents based on this stack. Does this look correct?

Wait for confirmation before proceeding.

在生成任何文档之前，先检测项目的技术栈：

读取
```
package.json
```
——检查是否使用React、Vue、Next.js、Nuxt、Svelte、Angular等
读取
```
tsconfig.json
```
——检查是否使用TypeScript
扫描目录结构——
```
src/
```
、
```
app/
```
、
```
pages/
```
、
```
components/
```
检查样式方案——Tailwind、styled-components、CSS Modules等
检查状态管理工具——Redux、Zustand、Recoil、Pinia等

总结检测到的技术栈并与用户确认：

检测到的技术栈：

框架：Next.js 14（App Router）

语言：TypeScript

样式：Tailwind CSS

状态管理：Zustand

我将基于此技术栈生成规划文档。是否正确？

等待用户确认后再继续。

Step 0.5: Domain Analysis & Document Discovery

步骤0.5：领域分析与文档发现

After confirming the tech stack, identify the project's domain structure and discover existing documents:

Domain Analysis

Ask the user to describe the project's major feature areas
Propose domain groupings based on their description (e.g.,
```
auth
```
,
```
payment
```
,
```
dashboard
```
)
Always create at least one domain directory — even single-domain projects use
```
specifications/<domain>/
```
Present the proposed directory structure for confirmation:

Proposed domain structure:
docs/en/specifications/
├── auth/
│   ├── requirements/
│   └── workflows/
└── dashboard/
    ├── requirements/
    └── workflows/
I'll generate the 6 planning documents for each domain in sequence. Shall I proceed with this structure?

Store the confirmed domain list for subsequent steps

Wait for confirmation before proceeding. If the user requests changes to the domain groupings, adjust and re-confirm.

Document Discovery

Entry point scan — read

README.md

CLAUDE.md

docs/en/specifications/README.md

if they exist

Recursive directory scan — list all
```
.md
```
files under
```
docs/en/specifications/
```
(including subdirectories) and
```
docs/en/policy/
```

Document classification — read the first 30 lines of each discovered file and classify by type:

requirements

user-stories

use-cases

api-spec

sequence-diagram

architecture

config

infrastructure

deployment

policy

other

User confirmation — present discovered documents grouped by category using
```
@
```
-reference format:

Discovered project documents:

requirements

@docs/en/specifications/auth/requirements/requirements.md

api-spec

@docs/en/specifications/auth/workflows/state-api-integration.md

policy

@docs/en/policy/naming-conventions.md

Should I use these documents as reference material for the planning pipeline?

Carry the confirmed document list as context for all subsequent steps

If no documents are found, record "No project documents found" and proceed.

确认技术栈后，识别项目的领域结构并发现现有文档：

领域分析

请用户描述项目的主要功能领域
根据用户描述提出领域分组建议（如
```
auth
```
、
```
payment
```
、
```
dashboard
```
）
至少创建一个领域目录——即使是单领域项目也使用
```
specifications/<domain>/
```
展示建议的目录结构供用户确认：

建议的领域结构：
docs/en/specifications/
├── auth/
│   ├── requirements/
│   └── workflows/
└── dashboard/
    ├── requirements/
    └── workflows/
我将为每个领域依次生成6份规划文档。是否按此结构继续？

存储确认后的领域列表，供后续步骤使用

等待用户确认后再继续。如果用户要求修改领域分组，调整后重新确认。

文档发现

入口点扫描——读取
```
README.md
```
、
```
CLAUDE.md
```
、
```
docs/en/specifications/README.md
```
（如果存在）
递归目录扫描——列出
```
docs/en/specifications/
```
（包括子目录）和
```
docs/en/policy/
```
下的所有
```
.md
```
文件
文档分类——读取每个发现文件的前30行，按类型分类：
```
requirements
```
（需求）/
```
user-stories
```
（用户故事）/
```
use-cases
```
（用例）/
```
api-spec
```
（API规范）/
```
sequence-diagram
```
（时序图）/
```
architecture
```
（架构）/
```
config
```
（配置）/
```
infrastructure
```
（基础设施）/
```
deployment
```
（部署）/
```
policy
```
（规范）/
```
other
```
（其他）
用户确认——使用
```
@
```
引用格式按类别展示发现的文档：

发现的项目文档：

需求

@docs/en/specifications/auth/requirements/requirements.md

API规范

@docs/en/specifications/auth/workflows/state-api-integration.md

规范

@docs/en/policy/naming-conventions.md

是否将这些文档作为规划流水线的参考资料？

将确认后的文档列表作为上下文，传递给所有后续步骤

如果未发现任何文档，记录“未找到项目文档”并继续。

Step 1: Requirements

步骤1：需求分析

Output:

docs/en/specifications/<domain>/requirements/requirements.md

Load the reference template:
```
references/requirements-template.md
```
From document discovery results, load all documents classified as
```
requirements
```
,
```
user-stories
```
, or
```
architecture
```
— use them as reference context
Ask the user to describe:
- Project purpose and target users
- Core features and functionality
- Non-functional requirements (performance, accessibility, etc.)
Generate the document following the template structure
Present the document to the user and wait for review

Step 1/6 complete: Requirements document generated. Please review and let me know if any changes are needed. Ready to proceed to the next step?

输出：

docs/en/specifications/<domain>/requirements/requirements.md

加载参考模板：
```
references/requirements-template.md
```
从文档发现结果中，加载所有分类为
```
requirements
```
、
```
user-stories
```
或
```
architecture
```
的文档——将其作为参考上下文
请用户描述：
- 项目目标和目标用户
- 核心功能
- 非功能性需求（性能、可访问性等）
按照模板结构生成文档
将文档展示给用户并等待评审

步骤1/6完成：需求文档已生成。请评审并告知是否需要修改。是否准备进入下一步？

Step 2: User Flows

步骤2：用户流程

Output:

docs/en/specifications/<domain>/workflows/user-flows.md

Load the reference template:
```
references/user-flows-template.md
```
Load Step 1 output:
```
<domain>/requirements/requirements.md
```
From document discovery results, load all documents classified as
```
use-cases
```
or
```
sequence-diagram
```
— reference existing flows if present
For each major feature, create:
- Mermaid flowchart diagram showing the happy path
- Alternative paths and error/exception flows
- Entry and exit conditions
Generate the document and wait for review

Step 2/6 complete: User flows document generated. Please review and let me know if any changes are needed. Ready to proceed?

输出：

docs/en/specifications/<domain>/workflows/user-flows.md

加载参考模板：
```
references/user-flows-template.md
```
加载步骤1的输出：
```
<domain>/requirements/requirements.md
```
从文档发现结果中，加载所有分类为
```
use-cases
```
或
```
sequence-diagram
```
的文档——如果存在现有流程则参考
为每个主要功能创建：
- Mermaid流程图，展示主路径
- 备选路径和错误/异常流程
- 进入和退出条件
生成文档并等待评审

步骤2/6完成：用户流程文档已生成。请评审并告知是否需要修改。是否准备继续？

Step 3: Page Spec

步骤3：页面规范

Output:

docs/en/specifications/<domain>/workflows/page-spec.md

Load the reference template:
```
references/page-spec-template.md
```
Load previous outputs: Steps 1–2
From document discovery results, skim documents classified as
```
api-spec
```
or
```
architecture
```
— reference any relevant layout or routing information
For each page/screen, define:
- URL / route path
- Layout structure and sections
- Key components on the page
- Responsive behavior (mobile / tablet / desktop)
- SEO considerations (title, meta, OG tags)
Generate the document and wait for review

Step 3/6 complete: Page specification generated. Please review and let me know if any changes are needed. Ready to proceed?

输出：

docs/en/specifications/<domain>/workflows/page-spec.md

加载参考模板：
```
references/page-spec-template.md
```
加载之前的输出：步骤1–2
从文档发现结果中，浏览分类为
```
api-spec
```
或
```
architecture
```
的文档——参考任何相关的布局或路由信息
为每个页面/界面定义：
- URL/路由路径
- 布局结构和区域
- 页面上的关键组件
- 响应式表现（移动端/平板/桌面端）
- SEO考虑（标题、元标签、OG标签）
生成文档并等待评审

步骤3/6完成：页面规范已生成。请评审并告知是否需要修改。是否准备继续？

Step 4: Use Cases

步骤4：用例设计

Output:

docs/en/specifications/<domain>/workflows/use-cases.md

Load the reference template:
```
references/use-cases-template.md
```
Load previous outputs: Steps 1–3
From document discovery results, load all documents classified as
```
use-cases
```
— reference existing actor definitions and flows; also load
```
architecture
```
documents for backend interaction mapping
For each use case, define:
- Actor (user role)
- Preconditions and postconditions
- Main flow (step-by-step actor-system interaction)
- Alternative flows
- Exception flows
Generate the document and wait for review

Step 4/6 complete: Use cases document generated. Please review and let me know if any changes are needed. Ready to proceed?

输出：

docs/en/specifications/<domain>/workflows/use-cases.md

加载参考模板：
```
references/use-cases-template.md
```
加载之前的输出：步骤1–3
从文档发现结果中，加载所有分类为
```
use-cases
```
的文档——参考现有的角色定义和流程；同时加载
```
architecture
```
文档，用于映射后端交互
为每个用例定义：
- 角色（用户角色）
- 前置条件和后置条件
- 主流程（角色与系统的分步交互）
- 备选流程
- 异常流程
生成文档并等待评审

步骤4/6完成：用例文档已生成。请评审并告知是否需要修改。是否准备继续？

Step 5: Component Tree

步骤5：组件树

Output:

docs/en/specifications/<domain>/workflows/component-tree.md

Load the reference template:
```
references/component-tree-template.md
```
Load previous outputs: Steps 1–4
Define the component hierarchy:
- Mermaid graph TD diagram showing parent-child relationships
- Separate sections for shared/common components and page-specific components
- TypeScript interface for each component's props
Generate the document and wait for review

Step 5/6 complete: Component tree document generated. Please review and let me know if any changes are needed. Ready to proceed?

输出：

docs/en/specifications/<domain>/workflows/component-tree.md

加载参考模板：
```
references/component-tree-template.md
```
加载之前的输出：步骤1–4
定义组件层级：
- Mermaid graph TD图，展示父子关系
- 分为共享/通用组件和页面专属组件两个部分
- 每个组件属性的TypeScript接口
生成文档并等待评审

步骤5/6完成：组件树文档已生成。请评审并告知是否需要修改。是否准备继续？

Step 6: State & API Integration

步骤6：状态与API集成

Output:

docs/en/specifications/<domain>/workflows/state-api-integration.md

Load the reference template:

references/state-api-integration-template.md

Load previous outputs: Steps 1–5
From document discovery results, load all documents classified as
```
api-spec
```
— extract endpoint definitions and use them as the authoritative source for the API table; add a Source column to track which discovered document each endpoint originates from
Define:
- State management strategy and rationale
- TypeScript interface for each store/slice
- API endpoints table with method, path, description
- TypeScript interface for request/response DTOs
- Caching strategy and error handling patterns
Generate the document and wait for review

Step 6/6 complete: State & API integration document generated. Please review and let me know if any changes are needed.

输出：

docs/en/specifications/<domain>/workflows/state-api-integration.md

加载参考模板：

references/state-api-integration-template.md

加载之前的输出：步骤1–5
从文档发现结果中，加载所有分类为
```
api-spec
```
的文档——提取端点定义并作为API表格的权威来源；添加来源列，跟踪每个端点来自哪个发现的文档
定义：
- 状态管理策略及理由
- 每个store/slice的TypeScript接口
- API端点表格，包含方法、路径、描述
- 请求/响应DTO的TypeScript接口
- 缓存策略和错误处理模式
生成文档并等待评审

步骤6/6完成：状态与API集成文档已生成。请评审并告知是否需要修改。

Step 7: Generate README

步骤7：生成README

Output:

docs/en/specifications/README.md

After all domains have completed Steps 1–6, generate a table of contents.

For single-domain projects:

markdown

undefined

输出：

docs/en/specifications/README.md

所有领域完成步骤1–6后，生成目录。

单领域项目的README格式：

markdown

undefined

Specifications

规范文档

Domains

领域

<domain>

Document	Path	Description
Requirements	[requirements.md](<domain>/requirements/requirements.md)	Feature requirements and constraints
User Flows	[user-flows.md](<domain>/workflows/user-flows.md)	User interaction flows with Mermaid diagrams
Page Spec	[page-spec.md](<domain>/workflows/page-spec.md)	Page layouts, routes, and responsive behavior
Use Cases	[use-cases.md](<domain>/workflows/use-cases.md)	Actor-system interactions
Component Tree	[component-tree.md](<domain>/workflows/component-tree.md)	Component hierarchy and props
State & API	[state-api-integration.md](<domain>/workflows/state-api-integration.md)	State management and API integration


For multi-domain projects, list each domain in a separate section. Also generate
a per-domain `README.md` at `<domain>/README.md` if there are 2+ domains.

If `docs/en/specifications/README.md` already exists, merge the frontend
planning section rather than overwriting.

If document discovery found any project documents, add a **Related Project Documents**
section at the end of the README listing all discovered documents using `@`-reference format,
grouped by category.

Report completion:

> **Frontend planning complete.** Generated documents for all domains:
> - `docs/en/specifications/<domain>/requirements/requirements.md`
> - `docs/en/specifications/<domain>/workflows/user-flows.md`
> - `docs/en/specifications/<domain>/workflows/page-spec.md`
> - `docs/en/specifications/<domain>/workflows/use-cases.md`
> - `docs/en/specifications/<domain>/workflows/component-tree.md`
> - `docs/en/specifications/<domain>/workflows/state-api-integration.md`
> - `docs/en/specifications/README.md`

文档	路径	描述
需求	[requirements.md](<domain>/requirements/requirements.md)	功能需求与约束
用户流程	[user-flows.md](<domain>/workflows/user-flows.md)	包含Mermaid图的用户交互流程
页面规范	[page-spec.md](<domain>/workflows/page-spec.md)	页面布局、路由和响应式表现
用例	[use-cases.md](<domain>/workflows/use-cases.md)	角色与系统的交互
组件树	[component-tree.md](<domain>/workflows/component-tree.md)	组件层级与属性
状态与API	[state-api-integration.md](<domain>/workflows/state-api-integration.md)	状态管理与API集成


多领域项目需为每个领域单独列出一个章节。如果领域数量≥2，还需在`<domain>/README.md`生成每个领域的README。

如果`docs/en/specifications/README.md`已存在，合并前端规划部分而非覆盖。

如果文档发现环节找到任何项目文档，在README末尾添加**相关项目文档**章节，使用`@`引用格式按类别列出所有发现的文档。

完成后告知用户：

> **前端规划完成**。已为所有领域生成以下文档：
> - `docs/en/specifications/<domain>/requirements/requirements.md`
> - `docs/en/specifications/<domain>/workflows/user-flows.md`
> - `docs/en/specifications/<domain>/workflows/page-spec.md`
> - `docs/en/specifications/<domain>/workflows/use-cases.md`
> - `docs/en/specifications/<domain>/workflows/component-tree.md`
> - `docs/en/specifications/<domain>/workflows/state-api-integration.md`
> - `docs/en/specifications/README.md`

Document Rules

文档规则

Language: English
Meta block: Every document includes Created date, Last Modified date, Status (Draft/Review/Final), Tech Stack, and Prerequisites
Mermaid: Use
```
flowchart TD
```
for user flows,
```
graph TD
```
for component trees
TypeScript: Use
```
interface
```
declarations for props, store shapes, and API DTOs
References: Each step must load all previous step outputs before generating
Review gate: Never proceed to the next step without user approval

语言：英文
元信息块：每个文档都包含创建日期、最后修改日期、状态（草稿/评审/最终版）、技术栈和前置条件
Mermaid：用户流程使用
```
flowchart TD
```
，组件树使用
```
graph TD
```
TypeScript：使用
```
interface
```
声明组件属性、store结构和API DTO
参考：每个步骤生成前必须加载所有之前步骤的输出
评审环节：未获得用户批准，不得进入下一步

Document Discovery Rules

文档发现规则

Scan targets:

README.md

CLAUDE.md

, all

.md

files under

docs/en/specifications/

(recursive) and

docs/en/policy/

Classification types:

requirements

user-stories

use-cases

api-spec

sequence-diagram

architecture

config

infrastructure

deployment

policy

other

Classification method: Read the first 30 lines of each file and classify based on content, headings, and filename
Reference format: Use
```
@
```
-reference links for all discovered documents per @docs/en/policy/reference-convention.md
docs/reference/ exclusion: Never apply
```
@
```
-prefix to files in
```
docs/reference/
```
— cite them with standard backtick paths only
No-documents fallback: If no project documents are found, record "No project documents found" and proceed without references
Carry forward: The confirmed document list from Step 0.5 must be available as context to every subsequent step

扫描目标：
```
README.md
```
、
```
CLAUDE.md
```
、
```
docs/en/specifications/
```
（递归）下的所有
```
.md
```
文件，以及
```
docs/en/policy/
```
下的所有
```
.md
```
文件

分类类型：

requirements

、

user-stories

、

use-cases

、

api-spec

、

sequence-diagram

、

architecture

、

config

、

infrastructure

、

deployment

、

policy

、

other

分类方法：读取每个文件的前30行，根据内容、标题和文件名分类
引用格式：所有发现的文档使用
```
@
```
引用链接，遵循@docs/en/policy/reference-convention.md
排除docs/reference/：
```
docs/reference/
```
下的文件不得使用
```
@
```
前缀——仅使用标准反引号路径引用
无文档回退：如果未找到项目文档，记录“未找到项目文档”，不参考任何文档直接继续
上下文传递：步骤0.5中确认的文档列表必须作为所有后续步骤的上下文