refactor-module

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Refactor Module

模块重构

Always use the skill

load-plain-reference

to retrieve the ***plain syntax rules — but only if you haven't done so yet.

请始终使用技能

load-plain-reference

获取***plain语法规则——但仅在尚未获取的情况下使用。

When to Use

使用场景

A module has many functional specs spanning multiple distinct domains or feature areas.
The module is hard to reason about because unrelated concerns are interleaved.
New features are difficult to add because the module's scope is too broad.
The user explicitly asks to split or reorganize a module.

模块包含许多功能规范，涉及多个不同领域或功能区域。
由于无关关注点相互交织，模块难以理解。
由于模块范围过广，新增功能变得困难。
用户明确要求拆分或重组模块。

Guiding Principle

指导原则

The refactoring is purely structural. The combined behavior of the resulting modules must be identical to the original module. No functional spec is added, removed, or weakened. The split is semantic — grouping related specs together — not behavioral.

本次重构纯粹是结构性的。生成模块的组合行为必须与原始模块完全一致。不得添加、删除或弱化任何功能规范。拆分是语义层面的——将相关规范分组在一起——而非行为层面的调整。

Input

输入

The

.plain

file to refactor, plus guidance from the user on the desired grouping (or ask the user to confirm your proposed grouping).

待重构的

.plain

文件，以及用户关于所需分组的指导（或请用户确认你提出的分组方案）。

Phase 1 — Analyze the Current Module

第一阶段——分析当前模块

Read the entire
.plain
file — frontmatter, definitions, implementation reqs, test reqs, and all functional specs. Also read any
```
import
```
and
```
requires
```
chains to understand the full context.
Inventory the functional specs. Number each spec and note which
```
:Concepts:
```
it references. Build a dependency map: which specs depend on earlier specs (by referencing behavior or state they introduced)?
Inventory the definitions. For each concept, note which functional specs reference it. Identify concepts that are used across multiple logical groups vs. concepts used only within one group.
Identify logical groups. Look for natural seams — clusters of functional specs that share concepts, represent a cohesive domain, or describe a single feature area. Common groupings:
- Data model setup and CRUD operations
- Business logic and processing rules
- UI screens and navigation
- Integrations and external interfaces
- Statistics, reporting, and analytics
Verify group independence. Each group's specs should form a contiguous or near-contiguous block in chronological order. If a group's specs are scattered and interleaved with other groups, the split boundary may need adjustment.

通读整个
.plain
文件——包括前置内容、定义、实现要求、测试要求以及所有功能规范。同时阅读所有
```
import
```
和
```
requires
```
链，以理解完整上下文。
梳理功能规范：为每个规范编号，并记录其引用的
```
:Concepts:
```
。构建依赖关系图：哪些规范依赖于更早的规范（通过引用它们引入的行为或状态）？
梳理定义：针对每个概念，记录哪些功能规范引用了它。识别跨多个逻辑组使用的概念，以及仅在一个组内使用的概念。
识别逻辑组：寻找自然的拆分点——共享概念、代表内聚领域或描述单一功能区域的功能规范集群。常见分组方式：
- 数据模型设置与CRUD操作
- 业务逻辑与处理规则
- UI界面与导航
- 集成与外部接口
- 统计、报告与分析
验证组独立性：每个组的规范应按时间顺序形成连续或接近连续的块。如果某个组的规范分散在其他组中，则可能需要调整拆分边界。

Phase 2 — Plan the Split

第二阶段——规划拆分

Present the proposed split to the user and get explicit confirmation before making any changes.

在进行任何更改之前，向用户展示拆分方案并获得明确确认。

2a. Define the module chain

2a. 定义模块链

The modules form a

requires

chain that preserves the original chronological ordering of functional specs. The first module in the chain contains the earliest specs; each subsequent module

requires

the previous one and adds the next logical group.

original-module
  ↓ splits into
module-group-a  (no requires — this is the new base)
module-group-b  (requires: module-group-a)
module-group-c  (requires: module-group-b)

If the original module already had

requires

import

dependencies, the first new module inherits them.

模块形成一个

requires

链，以保留功能规范的原始时间顺序。链中的第一个模块包含最早的规范；每个后续模块

requires

前一个模块，并添加下一个逻辑组。

original-module
  ↓ 拆分为
module-group-a （无requires——这是新的基础模块）
module-group-b （requires: module-group-a）
module-group-c （requires: module-group-b）

如果原始模块已有

requires

或

import

依赖，第一个新模块将继承这些依赖。

2b. Assign functional specs to modules

2b. 为模块分配功能规范

Place each functional spec in exactly one module. The placement must respect chronological ordering:

Within each module, the specs appear in the same relative order as in the original.
Across the chain, the ordering is preserved: all specs in module A come before all specs in module B, which come before all specs in module C.
A spec cannot move to an earlier module than a spec it depends on.

每个功能规范必须恰好放入一个模块。分配必须遵循时间顺序：

在每个模块内，规范的相对顺序与原始模块一致。
在整个链中，顺序保持不变：模块A中的所有规范先于模块B中的所有规范，模块B中的所有规范先于模块C中的所有规范。
规范不能移至其依赖规范之前的模块。

2c. Assign definitions to modules

2c. 为模块分配定义

For each concept, determine where it belongs:

Concept usage	Placement
Used only within one module's specs	Define in that module
Used across multiple modules in the chain	Define in the first module that uses it, and add to that module's `exported_concepts`
Already defined in an import template	Leave in the import — no change needed

If many concepts are shared across all modules, consider creating a new import module (template) to hold them. This avoids long

exported_concepts

lists and keeps definitions centralized. Use the

create-import-module

skill for this.

针对每个概念，确定其归属：

概念使用场景	放置位置
仅在一个模块的规范中使用	在该模块中定义
在链中的多个模块中使用	在第一个使用它的模块中定义，并添加到该模块的 `exported_concepts` 中
已在导入模板中定义	保留在导入模板中——无需更改

如果许多概念在所有模块中共享，考虑创建一个新的导入模块（模板）来存放它们。这可以避免过长的

exported_concepts

列表，并保持定义集中化。使用

create-import-module

技能完成此操作。

2d. Assign implementation reqs and test reqs

2d. 分配实现要求与测试要求

Reqs that apply to all modules should live in a shared import template. If one already exists, keep them there.
Reqs specific to a single module's domain move to that module.
When in doubt, keep reqs in the shared template — duplication across modules is worse than a slightly broad template.

适用于所有模块的要求应放在共享导入模板中。如果已有共享模板，则保留在其中。
特定于单个模块领域的要求移至该模块。
如有疑问，将要求保留在共享模板中——模块间的重复比范围略宽的模板更糟糕。

2e. Present the plan

2e. 展示规划方案

Summarize for the user:

Number of resulting modules and their names
Which functional specs go in each module (listed by number or short description)
The
```
requires
```
chain order
Any new import module being created
Which concepts are exported from each module
Confirmation that all original specs are accounted for (none lost)

Get explicit user confirmation before proceeding.

向用户总结：

生成模块的数量及其名称
每个模块包含哪些功能规范（按编号或简短描述列出）
```
requires
```
链的顺序
将要创建的任何新导入模块
每个模块导出的概念
确认所有原始规范都已涵盖（无遗漏）

在继续之前获得用户的明确确认。

Phase 3 — Execute the Split

第三阶段——执行拆分

Create the new modules in order, from the base of the chain upward.

按链的基础到上层顺序创建新模块。

3a. Create or update the import template (if needed)

3a. 创建或更新导入模板（如有需要）

If shared definitions or reqs are being moved to a new import template, create it first using the

create-import-module

skill.

如果要将共享定义或要求移至新的导入模板，请先使用

create-import-module

技能创建它。

3b. Create the base module

3b. 创建基础模块

Create the first module in the chain:

Set the YAML frontmatter — inherit the original module's
```
import
```
references. Add
```
exported_concepts
```
for any concepts that downstream modules need.
Add the
```
***definitions***
```
section with concepts used by this module's specs and concepts that need to be exported.
Add
```
***implementation reqs***
```
and
```
***test reqs***
```
specific to this module (if not fully covered by the import template).
Add the
```
***functional specs***
```
assigned to this module, preserving their original order and exact wording.
Carry over any
```
***acceptance tests***
```
nested under the moved functional specs.

创建链中的第一个模块：

设置YAML前置内容——继承原始模块的
```
import
```
引用。为下游模块需要的任何概念添加
```
exported_concepts
```
。
添加
```
***definitions***
```
部分，包含此模块规范使用的概念以及需要导出的概念。
添加特定于此模块的
```
***implementation reqs***
```
和
```
***test reqs***
```
（如果未完全由导入模板覆盖）。
添加分配给此模块的
```
***functional specs***
```
，保留其原始顺序和确切措辞。
移交所嵌套在已移动功能规范下的任何
```
***acceptance tests***
```
。

3c. Create subsequent modules

3c. 创建后续模块

For each subsequent module in the chain:

Set
```
requires
```
to point to the previous module in the chain. Set
```
import
```
if it uses shared templates.
Add
```
exported_concepts
```
for any concepts that later modules in the chain need.
Add
```
***definitions***
```
for concepts local to this module. Do not redefine concepts already available via
```
requires
```
(exported) or
```
import
```
.

Add

***implementation reqs***

and

***test reqs***

specific to this module.

Add the
```
***functional specs***
```
assigned to this module, preserving their original order and exact wording.
Carry over any
```
***acceptance tests***
```
.

针对链中的每个后续模块：

设置
```
requires
```
指向链中的前一个模块。如果使用共享模板，设置
```
import
```
。
为链中后续模块需要的任何概念添加
```
exported_concepts
```
。
添加
```
***definitions***
```
用于此模块本地的概念。不要重新定义已通过
```
requires
```
（导出）或
```
import
```
可用的概念。

添加特定于此模块的

***implementation reqs***

和

***test reqs***

。

添加分配给此模块的
```
***functional specs***
```
，保留其原始顺序和确切措辞。
移交所嵌套的
```
***acceptance tests***
```
。

3d. Handle the original module file

3d. 处理原始模块文件

After all new modules are created:

If the original module is being fully replaced (all specs moved out), delete it or rename it to avoid confusion.
If the original module was required by other modules, update those modules to
```
require
```
the last module in the new chain instead (since it transitively includes all prior modules' specs and generated code).

创建所有新模块后：

如果原始模块被完全替换（所有规范已移出），删除它或重命名以避免混淆。
如果原始模块被其他模块引用，更新这些模块以
```
require
```
新链中的最后一个模块（因为它会传递包含所有先前模块的规范和生成代码）。

Phase 4 — Verify

第四阶段——验证

4a. Completeness check

4a. 完整性检查

This is the most critical verification. Walk through every functional spec from the original module and confirm it appears in exactly one of the new modules. Nothing may be lost, weakened, modified, or left implicit.

Checklist:

Total spec count across all new modules equals the original spec count
Each spec's text is identical to the original (no rewording)
Each spec's acceptance tests (if any) are carried over intact

这是最关键的验证步骤。逐一检查原始模块的每个功能规范，确认它恰好出现在一个新模块中。不得遗漏、弱化、修改或隐含任何内容。

检查清单：

所有新模块的规范总数等于原始模块的规范数
每个规范的文本与原始文本完全相同（无改写）
每个规范的验收测试（如有）完整移交

4b. Chronological ordering check

4b. 时间顺序检查

Verify that the chronological order of all functional specs — when read across the requires chain from base to leaf — matches the original ordering exactly. A spec must not appear before a spec it depends on.

验证所有功能规范的时间顺序——从链的基础到叶子模块读取时——与原始顺序完全一致。规范不得出现在其依赖规范之前。

4c. Concept availability check

4c. 概念可用性检查

For each module, verify:

Every
```
:Concept:
```
referenced in its specs is either defined locally, available via
```
import
```
, or available via
```
exported_concepts
```
from the
```
requires
```
chain
```
exported_concepts
```
includes every concept that downstream modules need
No concept name collisions between modules

针对每个模块，验证：

其规范中引用的每个
```
:Concept:
```
要么在本地定义，要么通过
```
import
```
可用，要么通过
```
requires
```
链的
```
exported_concepts
```
可用
```
exported_concepts
```
包含下游模块需要的所有概念
模块之间没有概念名称冲突

4d. Structural validation per module

4d. 每个模块的结构验证

For each new module:

Has at least one functional spec and one implementation req
YAML frontmatter is correctly formatted
```
requires
```
and
```
import
```
paths are correct
Module file is at the repository root (not in
```
template/
```
)
Specs are language-agnostic
All external interfaces remain explicit

针对每个新模块：

至少包含一个功能规范和一个实现要求
YAML前置内容格式正确
```
requires
```
和
```
import
```
路径正确
模块文件位于仓库根目录（不在
```
template/
```
中）
规范与语言无关
所有外部接口保持明确

4e. Read all new modules

4e. 通读所有新模块

Read each new

.plain

file in full and present the final structure to the user for approval. If the user requests changes, apply them and re-verify.

完整阅读每个新的

.plain

文件，并向用户展示最终结构以获得批准。如果用户要求更改，应用更改并重新验证。

Common Pitfalls

常见陷阱

Splitting too aggressively

拆分过于激进

Creating many tiny modules with 1–2 specs each adds overhead without clarity. Aim for modules with 3–10 functional specs each, grouped around a cohesive theme.

创建许多仅包含1-2个规范的微小模块会增加开销而不会提升清晰度。目标是围绕内聚主题创建包含3-10个功能规范的模块。

Breaking chronological order

打破时间顺序

Specs that set up foundational behavior (entry point, database init, core CRUD) must stay in the base module even if they touch concepts from multiple domains. Only split when specs are cleanly separable.

设置基础行为的规范（入口点、数据库初始化、核心CRUD）即使涉及多个领域的概念，也必须保留在基础模块中。仅当规范可以清晰分离时才进行拆分。

Forgetting exported_concepts

忘记exported_concepts

If a concept defined in module A is referenced by a spec in module B (which requires A), the concept must be in A's

exported_concepts

. Missing exports cause rendering failures.

如果模块A中定义的概念被模块B（依赖A）的规范引用，则该概念必须在A的

exported_concepts

中。缺少导出会导致渲染失败。

Modifying spec text during the split

拆分期间修改规范文本

This is a refactoring, not a rewrite. Spec text must be copied verbatim. If a spec needs rewording to work in its new module context, that is a sign the split boundary is wrong — adjust the grouping instead.

这是重构，而非重写。规范文本必须逐字复制。如果规范需要改写才能在新模块上下文中生效，这表明拆分边界有误——应调整分组。

Losing acceptance tests

丢失验收测试

Acceptance tests are nested under their parent functional spec. When moving a spec to a new module, its acceptance tests must move with it.

验收测试嵌套在其父功能规范下。将规范移至新模块时，其验收测试必须一并移动。

Validation Checklist

验证清单

User confirmed the split plan before execution
All original functional specs are present in exactly one new module — none lost
Spec text is identical to the original — no rewording
Acceptance tests moved with their parent specs
Chronological order preserved across the requires chain
Every referenced
```
:Concept:
```
is available in each module (local, import, or exported)
```
exported_concepts
```
are correctly set on each module
No concept name collisions
Each module has at least one functional spec and one implementation req
```
requires
```
chain is correctly ordered (base → leaf)
Original module removed or updated
Downstream modules (if any) updated to require the correct module
User approved the final result

执行拆分前已获得用户确认
所有原始功能规范都存在于恰好一个新模块中——无遗漏
规范文本与原始文本完全相同——无改写
验收测试随其父规范一并移动
时间顺序在requires链中得以保留
每个模块中引用的所有
```
:Concept:
```
均可用（本地、导入或导出）
每个模块的
```
exported_concepts
```
设置正确
无概念名称冲突
每个模块至少包含一个功能规范和一个实现要求
requires链顺序正确（基础→叶子）
原始模块已删除或更新
下游模块（如有）已更新为引用正确的模块
用户已批准最终结果