create-requires-module

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create Requires Module

创建使用Requires的模块

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语法规则——但仅在尚未获取的情况下使用。

What Requires Does

Requires的作用

requires

establishes a build ordering between modules. The required module is built before the current one. This does not necessarily mean the current module extends or depends on the required module's code — it may be completely independent. The

requires

relationship simply ensures the build order is correct.

When this module is rendered:

The required module's generated code (
```
plain_modules/<required_module>
```
) is copied as the starting point.
The required module's
```
***functional specs***
```
become visible as previous functional specs.
Only
```
exported_concepts
```
from the required module are available (not its full definitions).

Use

requires

for:

Ensuring a module is built after another in the build chain
Building on top of an existing module's functionality
Extending a base module with additional features

If you only need shared definitions and reqs (no functional specs, no generated code), use

import

instead — see the

create-import-module

skill.

requires

用于在模块之间建立构建顺序。被依赖的模块会先于当前模块构建。这并不一定意味着当前模块会扩展或依赖被依赖模块的代码——两者可能完全独立。

requires

关系仅用于确保构建顺序正确。

当此模块被渲染时：

被依赖模块的生成代码（
```
plain_modules/<required_module>
```
）会被复制作为起点。
被依赖模块的功能规范会作为前置功能规范可见。
仅能使用被依赖模块的
```
exported_concepts
```
（而非其完整定义）。

requires

的适用场景：

确保一个模块在构建链中晚于另一个模块构建
基于现有模块的功能进行开发
扩展基础模块的功能，添加新特性

如果仅需要共享定义和依赖（不需要功能规范、不需要生成代码），请使用

import

替代——详见

create-import-module

技能。

Workflow

工作流程

Identify the dependency. Determine which module this new module builds on. That module must already exist and be renderable.
Create the
.plain
file at the repository root with YAML frontmatter containing the
```
requires
```
field. Modules with functional specs live at the root, not in
```
template/
```
.
Review the required module's functional specs — they will be treated as previous requirements. Your new functional specs must not conflict with them.
Review the required module's
exported_concepts
— only those concepts are available to reference from the required module.
Add module-specific content — definitions, implementation reqs, test reqs, and functional specs unique to this module.
Check for conflicts between your new functional specs and the required module's specs.

确定依赖项：明确新模块将基于哪个模块构建。该模块必须已存在且可被渲染。
在仓库根目录创建.plain文件，在YAML前置元数据中包含
```
requires
```
字段。带有功能规范的模块需放在根目录，而非
```
template/
```
目录下。
查看被依赖模块的功能规范——这些规范会被视为前置要求。新的功能规范不得与之冲突。
查看被依赖模块的
exported_concepts
——仅这些概念可被当前模块引用。
添加模块专属内容——包括定义、实现要求、测试要求以及该模块独有的功能规范。
检查冲突：确保新功能规范与被依赖模块的规范无冲突。

Format

格式

The

requires

field is a list of module paths in the YAML frontmatter:

plain

---
requires:
  - base_module
import:
  - shared_template
description: Extended module that builds on base_module
---

***definitions***
- :NewFeature: is a feature added by this module.

***functional specs***
- The system should support :NewFeature:.

A module can use both

requires

and

import

together.

requires

points to other root-level modules;

import

resolves from the default

template/

directory (no prefix needed).

requires

字段是YAML前置元数据中的模块路径列表：

plain

---
requires:
  - base_module
import:
  - shared_template
description: Extended module that builds on base_module
---

***definitions***
- :NewFeature: is a feature added by this module.

***functional specs***
- The system should support :NewFeature:.

一个模块可同时使用

requires

和

import

。

requires

指向其他根目录下的模块；

import

从默认的

template/

目录解析（无需前缀）。

Exported Concepts

导出概念

The required module controls what concepts are visible via

exported_concepts

plain

> In the required module's frontmatter:
---
exported_concepts: [":StorageClient:", ":BackupResult:"]
---

Only

:StorageClient:

and

:BackupResult:

would be available to modules that

require

this one. All other concepts from the required module are internal.

被依赖模块通过

exported_concepts

控制哪些概念可见：

plain

> In the required module's frontmatter:
---
exported_concepts: [":StorageClient:", ":BackupResult:"]
---

只有

:StorageClient:

和

:BackupResult:

可被

require

该模块的其他模块使用。被依赖模块的所有其他概念均为内部概念。

Chronological Ordering with Requires

使用Requires实现时序排序

Functional specs from

requires

modules are considered previous functional specs. This means:

They are already rendered and their code exists.
Your new specs are rendered after them, with full awareness of what they defined.
Your new specs must not conflict with the required module's specs.
The renderer sees the required module's functional specs as context when rendering yours.

The current module may or may not be functionally related to the required module. In some cases

requires

simply enforces build order — the two modules may be independent pieces of the same project that need to be built in sequence.

来自

requires

模块的功能规范会被视为前置功能规范，这意味着：

这些规范已被渲染，对应的代码已存在。
新规范会在之后被渲染，且完全知晓前置规范的定义。
新规范不得与被依赖模块的规范冲突。
渲染器在渲染新规范时，会将被依赖模块的功能规范作为上下文。

当前模块与被依赖模块可能存在功能关联，也可能没有。在某些情况下，

requires

仅用于强制构建顺序——两个模块可能是同一项目中需要按顺序构建的独立部分。

Import vs Requires

Import与Requires对比

Aspect	`import`	`requires`
Pulls in definitions	Yes	No (only `exported_concepts` )
Pulls in implementation reqs	Yes	No
Pulls in test reqs	Yes	No
Pulls in functional specs	No	Yes (as previous requirements)
Copies generated code	No	Yes
Typical use	Templates, shared definitions	Build dependency chain

方面	`import`	`requires`
引入定义	是	否（仅引入 `exported_concepts` ）
引入实现要求	是	否
引入测试要求	是	否
引入功能规范	否	是（作为前置要求）
复制生成的代码	否	是
典型用途	模板、共享定义	构建依赖链

Validation Checklist

验证检查清单

Module file is at the repository root (not in
```
template/
```
)
Required module exists and is renderable
Required module's
```
exported_concepts
```
provide the concepts you need
New functional specs do not conflict with the required module's specs
Module has at least one functional spec and one implementation req
Both
```
requires
```
and
```
import
```
are used correctly (not mixed up)
YAML frontmatter is correctly formatted between
```
---
```
markers

模块文件位于仓库根目录（而非
```
template/
```
目录）
被依赖模块已存在且可被渲染
被依赖模块的
```
exported_concepts
```
提供了所需的概念
新功能规范与被依赖模块的规范无冲突
模块至少包含一个功能规范和一个实现要求
```
requires
```
和
```
import
```
使用正确（未混淆）
YAML前置元数据在
```
---
```
标记之间格式正确