SuperAPI AI Directory

yy-frontend-refactor-scaffold

Coding & development

View repository

Updated 10-15 20:09

About this skill

yy-frontend-refactor-scaffold

Description

Generate a "plan + skeleton" pair for a frontend project (Vue2 / Vue3 / React) refactoring task:

  1. PLAN.md — A structured refactoring plan, recording the source layout analysis, component logic/interaction rule analysis, component dependency graph, route table, state flow diagram, and file mapping table.
  2. Placeholder skeleton files — According to the file mapping table, generate placeholder files of "empty skeleton + header comment" in the refactoring target folder, with each placeholder file marking the source file path it corresponds to and a TODO marker.

Throughout the skillRead-onlysource folder,Write-onlyrefactoring target folder and PLAN.md, never modify the source code.

Use cases

  • The user wants to refactor a frontend module into a new module and wants to plan before acting
  • The user wants to lay out an empty skeleton in another directory based on the layout of an existing directory
  • The user wants a "plan + placeholder files" pair for a refactoring task

Should not trigger:

  • Directly migrating/translating/copying source code (e.g., the actual code translation of upgrading Vue2 to Vue3) ← different operations on the same object
  • Modifying any code in the source folder ← different operations on the same object
  • Backend code refactoring (Java/Go/Python, etc.) ← the same verb on a different object
  • Adding inline comments / business explanations to existing code ← adjacent functionality
  • Code refinement, import cleanup, formatting ← adjacent functionality

Core principles

  1. Read-only on the source side, write-only on the target side: the source folder is read-only and not written to; PLAN.md and placeholder files are uniformly written to the refactoring target folder.
  2. PLAN is the sole basis for placeholders: the placeholder file list must come strictly from the confirmed "file mapping table" in PLAN.md; adding or removing files temporarily during the generation phase is prohibited.
  3. Minimal skeleton: placeholder files contain only the "minimal skeleton that the framework can recognize + header comment", without reserving any business logic, state, interfaces, or component imports.
  4. Keep the original structure: by default, the directory hierarchy and file names of placeholder files correspond one-to-one with the source folder; if the user requests adjustments during the confirmation step, adjust according to the user's intent.

Instructions

Step 1. Collect and validate paths

When the skill starts, collect two paths:

  • Source reference folder(source): the object to be analyzed, which must exist and be non-empty.
  • Refactoring target folder(target): the destination for writing PLAN.md and the placeholder files.

Decision branches:

  • The user has provided both paths: proceed directly to validation.
  • Only one is provided or none is provided: use the question tool to ask for the missing path in one go.
  • What is provided is a file rather than a folder: by default, switch to its containing directory and explain this to the user.

Path validation(In order, process upon match):

  1. Original folder does not exist → Use question tool to ask for re-specification; do not continue.
  2. Original folder is empty or contains no frontend files(no .vue / .jsx / .tsx / .js / .ts) → Use question tool to ask whether the wrong directory was selected.
  3. Target folder is the original folder itself or its subdirectory → Report an error and terminate directly, requiring the user to re-specify (to avoid scanning the target during analysis as well).
  4. Target folder already exists and is non-empty → Append by default (do not overwrite existing files), only note it in the generated summary; do not block the process.

Cross-project scenario: If the original and target belong to different projects (different codebases / different generations), mark "cross-project refactoring" in the PLAN.md metadata, and in the "Items to Confirm" list remind about differences in aliases, state management, UI libraries, etc.; do not block the process.

Step 2. Framework identification

According to resources/framework-detect.md , determine the frontend framework used by the original folder (Vue3 / Vue2 / React / JS-TS).

Decision branches:

  • Single framework identified successfully: Adopt it directly.
  • Mixed frameworks(e.g., Vue2 + Vue3 coexisting) → Use question tool to ask which framework should prevail, and list all identified candidates.
  • Cross-generation refactoring(e.g., source side Vue2 while target side Vue3) → Record both frameworks in the PLAN.md metadata, and explicitly remind about the differences in the "Items to Confirm" list.
  • Unable to identify(does not belong to any of the above frameworks, such as Svelte / Solid / Alpine, etc.) → Follow the fallback strategy and use question tool to ask the user to manually specify the framework.

Step 3. Analyze the original layout

Execute according to resources/layout-analysis.md , produce:

  1. Directory structure tree: Use text code block to present the directory tree of the original folder, annotating the brief responsibility of each file/folder.
  2. File inventory table: Path / Type (Vue/JS/TS/style/test) / Inferred responsibility (1 sentence) / Entry identifier.
  3. Entry file identification:main.js / main.ts / App.vue / index.html / index.js , etc.
  4. Route table(if a router configuration file is detected): Extract the path / name / component / meta list.
  5. Component dependency graph: Use Mermaid graph to express parent-child component relationships (generate only when the number of components ≥ 3; otherwise replace with a list).

Exception degradation:

  • Route file exists but parsing fails → Mark "route table automatic parsing failed, please supplement during the confirmation step" in PLAN.md; do not block the process.
  • Component dependencies are complex (> 30 nodes) → Draw only top-level components and first-level child components; present deeper components as a list.

Step 4. Analyze logic and interaction rules

Execute according to resources/logic-analysis.md ,differentiate by frameworkanalyze each component:

  • Vue2:Props、Events(this.$emit), key events,data state, Vuex calls, route navigation.
  • Vue3:Props(defineProps)、Emits(defineEmits), key events,ref / reactive state, Pinia / Vuex calls, route navigation.
  • React: Props (destructuring), callbacks (onXxx)、useState / useReducer state, Context, route navigation.

Output items(produced uniformly for each component; mark missing items as —):

  • Responsibility overview: 1 sentence.
  • Props list: name / type / required / default value.
  • Emits/Events list: event name / trigger condition / payload.
  • Key events: events bound in the template/JSX.
  • Data flow: APIs called (API function names), state management (store action / mutation / setState).
  • State transitions: if the component contains a notable state machine (approval flow, wizard steps, dialog toggle chain), express it with Mermaid stateDiagram ; skip for simple components.

Step 5. Generate PLAN.md

According to resources/plan-template.md 's standard template, generate PLAN.md, and write it tothe root directory of the refactoring target folder。

Sections that PLAN.md must contain:

  1. Meta information (original path / target path / framework identification result / generation timestamp)
  2. Original layout analysis (output of step 3)
  3. Logic and interaction rule analysis (output of step 4, grouped by file)
  4. Component dependency graph (Mermaid graph, if applicable)
  5. Route table (if applicable)
  6. State transition diagram (Mermaid stateDiagram, if applicable)
  7. File mapping table(core section): original path → refactored path / file type / inferred responsibility / remarks
  8. List of items to confirm (explicitly list the open questions that require the user's decision)

Generation timestamp(must be executed before writing to the "Generation Time" field of the "Meta Information" table):

date "+%Y-%m-%d %H:%M:%S"

AI is prohibited from estimating the time — AI does not have the ability to perceive the system clock.

Step 6. Confirm with the user

After PLAN.md is generated,immediately stop subsequent actions, and use the question tool to initiate a one-time confirmation with the user.

Required questions(merged into a single inquiry):

  1. Whether the file mapping table is accurate: whether there are omissions / extras / path errors.
  2. Whether the directory structure is adjusted: by default, keep the original structure; if flattening / merging directories / renaming is needed, the user should point it out.

The user's response paths:

  • "Confirm all" → proceed to step 7.
  • "Needs adjustment" → after modifying PLAN.md according to the user's instructions, confirm again.
  • "Terminate" → do not generate placeholder files; keep PLAN.md for the user's reference.

This step is a key checkpoint of the skill. It is prohibited to skip confirmation and directly generate placeholder files — once placeholder files are spread out, the rollback cost rises linearly with the number of files.

Step 7. Generate placeholder files

After the user confirms, according to theconfirmed file mapping tablein PLAN.md, generate placeholder files one by one under the refactoring target folder.

Placeholder file form(see resources/scaffold-templates.md):

  • Empty skeleton + header comment: contains only the minimal structure that allows the framework to recognize it (such as Vue3's <template>/<script setup>/<style lang="scss"> empty shell), with a header comment pointing to the original file + a TODO marker.
  • No pre-filled business logic: Do not pre-fill props default values, initial state values, API calls, component imports, style class names, etc.
  • Keep file naming consistent: By default, use the same name as the original file (including case). If the user requests a rename during the confirmation step, follow the user's instructions.
  • Directory structure follows PLAN.md: Strictly create directories and files according to the "Refactoring Path" column in the file mapping table.

Generation order:

  1. Generate top to bottom according to the PLAN.md file mapping table (create directories first, then create files).
  2. Print one line for each generated file ✅ <相对路径>。
  3. On failure, print ❌ <相对路径> - <失败原因>,continue with subsequent files, without interruption.
  4. After everything is complete, count the number of successful / skipped / failed items and return them to step 8 for output.

Handling of existing files(default: skip, non-blocking):

  • Defaultskip and warn(do not overwrite), and list them in the generation summary.
  • When the path does not exist, automatically create the required directories (mkdir -p semantics).
  • Placeholder filesDo not pre-fill any import paths(the skeleton is empty to begin with); only remind the user in PLAN.md about cross-project alias differences.

Step 8. Output results

Output in the following format (do not omit failed items):

## 重构脚手架生成汇总

- 📁 原始文件夹:<source>
- 📁 重构文件夹:<target>
- 🧩 框架识别:<Vue3 / Vue2 / React / JS-TS>
- 📄 PLAN.md:<target>/PLAN.md

### 文件生成统计

- ✅ 成功:X 个
- ⏭️ 跳过:Y 个(已存在 / 用户选择跳过)
- ❌ 失败:Z 个

### 文件清单

#### ✅ 成功生成

- <target>/src/views/user-center/index.vue
- <target>/src/views/user-center/components/UserCard.vue
- ...

#### ⏭️ 跳过

- <target>/src/router/index.js(已存在)

#### ❌ 失败

- <target>/xxx - <失败原因>

### 后续建议

- 用户需手动在重构文件夹内补充业务逻辑(占位文件已标注 TODO)
- 跨项目场景需检查别名、状态管理、路由配置差异

Security boundaries

Prohibited:

  • Modify any file in the original folder (even formatting or adding comments is not allowed)
  • Perform git operations in the original folder (commit / push / checkout)
  • Overwrite an existing file with the same name in the target folder without confirmation
  • Pre-fill business logic, state, API calls, component imports, or styles in placeholder files

Allowed:

  • Create directories in the target folder, write placeholder files, and write PLAN.md
  • Read the configuration of the original folder and target project (package.json / tsconfig.json / vite.config._ / vue.config._) for framework identification and alias detection
  • When the target folder already exists, skip files with the same name (do not overwrite by default)

Boundary conditions

  • Original folder is too large(> 200 files): prompt the user "There are many files; analysis will take a long time," and suggest narrowing the scope or processing in batches.
  • Original folder is the project root directory: warn "It is recommended to narrow it down to a specific module directory to avoid scanning the entire project."
  • Target folder is the same as the original folder or is a subdirectory of it: report an error and terminate directly (already intercepted in step 1).
  • No route configuration: in the route table section of PLAN.md, mark "No route configuration detected" and skip.
  • No significant state transitions: in the state transition diagram in PLAN.md, mark "No significant state machine" and skip.

Related resources

Read the corresponding file according to the current task; do not load all of them at once:

  • resources/framework-detect.md: read during framework identification in step 2 to understand the identification features and failure fallback for Vue2/Vue3/React
  • resources/layout-analysis.md: read during original layout analysis in step 3 to understand the specific rules for directory trees, file lists, entry identification, route extraction, and dependency graphs
  • resources/logic-analysis.md: Read during step 4 logic/interaction analysis; read the corresponding chapter based on the current framework (Vue2 / Vue3 / React)
  • resources/plan-template.md: Read during step 5 when generating PLAN.md to understand the chapter structure and how to write Mermaid diagrams
  • resources/scaffold-templates.md: Read during step 7 when generating placeholder files; read the corresponding skeleton template based on the current framework