ignatius-modeling

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ignatius modeling

Ignatius 建模

Guide the user through authoring an ignatius model — entities, data flow diagrams, a new-model bootstrap, or a Socratic discovery session that generates both — writing real files to disk and verifying them with the

ignatius

CLI.

通过引导式问答帮助用户创作 ignatius 模型，包括实体、数据流图、新模型骨架，或同时生成两者的苏格拉底式探索会话；将实际文件写入磁盘，并使用

ignatius

CLI 进行验证。

Quick Start

快速开始

Read

$ARGUMENTS

to choose the mode, read

references/interviewing.md

for how to conduct it, then follow the matching reference file step by step:

```
entity
```
— add one entity. Follow
```
references/entity-flow.md
```
.
```
model
```
— bootstrap a new model skeleton. Follow
```
references/model-flow.md
```
.
```
flow
```
— author a data flow diagram, for a user who already knows their processes. Follow
```
references/dfd-authoring.md
```
(templates in
```
references/flow-templates.md
```
).
```
discover
```
— Socratically extract a model, generating both entities and flows. Follow
```
references/discover-flow.md
```
. When a real database/codebase/schema exists to read, it routes to
```
references/reverse-engineering.md
```
.
empty or unrecognized — ask: "Which mode —
```
entity
```
(add one entity),
```
model
```
(bootstrap a new model),
```
flow
```
(author a data flow diagram), or
```
discover
```
(work out a model from how your business runs)?"

After writing any file, always run the verification loop in

references/verification.md

, then report or fix the findings.

读取

$ARGUMENTS

以选择模式，读取

references/interviewing.md

了解如何进行访谈，然后逐步遵循相应的参考文件：

```
entity
```
— 添加一个实体。遵循
```
references/entity-flow.md
```
。
```
model
```
— 搭建新模型骨架。遵循
```
references/model-flow.md
```
。
```
flow
```
— 为已经了解自身流程的用户创作数据流图。遵循
```
references/dfd-authoring.md
```
（模板位于
```
references/flow-templates.md
```
）。
```
discover
```
— 以苏格拉底式方式提取模型，同时生成实体和流。遵循
```
references/discover-flow.md
```
。当存在可供读取的真实数据库、代码库或 schema 时，转至
```
references/reverse-engineering.md
```
。
为空或无法识别 — 询问：“要选择哪种模式——
```
entity
```
（添加一个实体）、
```
model
```
（搭建新模型）、
```
flow
```
（创作数据流图），还是
```
discover
```
（根据业务实际运行方式推导模型）？”

写入任何文件后，始终运行

references/verification.md

中的验证循环，然后报告或修复发现的问题。

Core rules (apply to all four modes)

核心规则（适用于全部四种模式）

Derive, never ask: the parser infers
```
classification
```
and per-edge
```
identifying
```
from key shape. Ask
```
reference: true?
```
only for lookup or code tables.
Convention is derived, not declared: an entity's PK shape is its style —
```
key-inherited
```
(parent PK migrates into the child PK) or
```
orm-oriented
```
(surrogate
```
id
```
, FKs outside the PK). Detect the prevailing style from existing entities and use it only as the default suggestion; if one entity deviates, nudge once and allow it.
Adapt to the user's conventions, never invent your own: this extends beyond key style to every naming choice — entity ids, column names, group slugs, flow file names. Read the existing files first and match what is there. The skill's built-in defaults (PascalCase ids, snake_case slugs, Title-Case flow files) apply only when nothing exists yet, and even then as suggestions. Names extracted from a real system stay verbatim.
Existence rules survive the key style: a mandatory parent is asserted by key placement (key-inherited) or by FK
```
nullable: false
```
plus a documented rule in the body (orm-oriented). Surface it either way — the dependency is never lost, only expressed in a different channel.
Subtype clusters are an independent authoring choice; classification as Subtype is derived from the cluster declaration, never asked.
Predicates carry business meaning, not cardinality: push for the domain verb a stakeholder would say ("makes payments using", "settles") over "has many" / "belongs to". The crow's-foot already shows cardinality; the predicate makes the line read as a true sentence.
Examples always, in every mode: every entity carries 2–3
```
examples:
```
rows and every process carries in/out
```
examples:
```
— never skipped, never offered as optional. Generate them yourself from the business context (realistic domain values, not
```
foo
```
/
```
1
```
/
```
test
```
), show them, and let the user adjust. Concrete instances expose wrong rules that pass every structural check; a model without examples is unverified.
```
description:
```
always, in every mode: every entity, group, process, external, and store carries a one-line
```
description:
```
in frontmatter, and so does every top-level flow folder, in the frontmatter of
```
flows/<flow>/index.md
```
— never skipped, never offered as optional. It is not documentation; it is the payload of the generated router tables and of the app's flow index and breadcrumb menus, the line a reader uses to decide whether to open the file or the diagram. Generate it yourself from real business context, show it, and let the user adjust. Never name a file
```
index.md
```
(or whatever
```
index_file
```
resolves to in
```
ignatius.yml
```
) for an entity — that name is reserved for the generated router, whose frontmatter is the one place a flow folder describes itself.
Capture the business story, not just the schema: business rules, constraints, lifecycle, and the why behind structural complexity go in the body with their source and justification. Treat an offhand "billing won't allow payments under $5" as a documentable rule, not chatter.
Labels and clusters always, in every mode that writes flows: every
```
inputs:
```
/
```
outputs:
```
entry carries a short prose
```
label:
```
beside its
```
data:
```
(the diagram shows the label; the column list stays the validated contract), and two or more stores a process reads or writes as one thing are declared once in
```
clusters/<slug>.md
```
and referenced with one
```
cluster:
```
entry. This is what keeps a diagram readable at the size real models reach; neither is optional or an afterthought. Steps F4a and F5 in
```
references/dfd-authoring.md
```
.
Every edit session ends with one change note: in any mode that writes or changes model files, finish by writing one
```
.ignatius/changes/<slug>.md
```
next to
```
ignatius.yml
```
. Its frontmatter names each changed entity with its changed columns (
```
entities:
```
) and each changed diagram with its changed nodes (
```
flows:
```
); its body tells the reviewer why. The user reviews it in
```
ignatius serve
```
and accepts it with
```
ignatius approve
```
. Before the first write to an existing model with no valid
```
<model>/.ignatius/baseline.json
```
, run
```
ignatius approve <model-root>
```
to record the untouched starting point, but only when
```
.ignatius/changes/
```
holds no files; if it holds notes, stop and ask the user to approve after reading them or to restore the baseline. Never run it after editing. Every model the skill creates gets a
```
<model>/.gitignore
```
containing
```
.ignatius/
```
. Format, coverage, and the bootstrap exception:
```
references/change-notes.md
```
.

只推导，绝不询问：解析器根据键的结构推断
```
classification
```
和每条边的
```
identifying
```
。仅在查找表或代码表时询问
```
reference: true?
```
。
约定应推导，而非预先声明：实体的 PK 结构就是其风格——
```
key-inherited
```
（父级 PK 迁移到子级 PK）或
```
orm-oriented
```
（使用代理
```
id
```
，且 FK 位于 PK 之外）。从现有实体中检测主流风格，并仅将其作为默认建议；如果某个实体有所偏离，提示一次并允许其保留。
适应用户的约定，绝不自创约定：这不仅适用于键风格，还适用于每一种命名选择——实体 id、列名、group slug 和 flow 文件名。先读取现有文件并与其保持一致。skill 的内置默认值（PascalCase id、snake_case slug、Title-Case flow 文件名）仅在尚不存在任何内容时适用，即使如此也只应作为建议。从真实系统提取的名称保持原样。
存在性规则不会因键风格而失效：必需父实体的存在通过键的位置（key-inherited）来断言，或通过 FK
```
nullable: false
```
加上正文中记录的一条规则来断言（orm-oriented）。无论采用哪种方式都要明确呈现——依赖关系绝不能丢失，只会通过不同渠道表达。
Subtype 聚类是独立的创作选择；将分类判定为 Subtype 是根据聚类声明推导出来的，绝不询问。
谓词表达业务含义，而非基数：应推动利益相关者说出其会使用的领域动词（“makes payments using”“settles”），而不是“has many”或“belongs to”。乌鸦脚表示法已经展示基数；谓词则让关系线读起来像一句真实的话。
示例始终必需，适用每种模式：每个实体都要包含 2–3 行
```
examples:
```
，每个流程都要包含输入/输出
```
examples:
```
——绝不跳过，也绝不作为可选项。根据业务上下文自行生成（使用真实的领域值，而不是
```
foo
```
/
```
1
```
/
```
test
```
），展示给用户并允许其调整。具体实例能暴露那些通过所有结构检查的错误规则；没有示例的模型不能视为已验证。
```
description:
```
始终必需，适用每种模式：每个实体、group、流程、外部实体和存储都要在 frontmatter 中包含一行
```
description:
```
，每个顶层 flow 文件夹也要在
```
flows/<flow>/index.md
```
的 frontmatter 中包含该字段——绝不跳过，也绝不作为可选项。它不是文档；而是生成的 router 表格、应用 flow 索引和面包屑菜单所使用的 payload，也是读者决定是否打开文件或图示的依据。根据真实业务上下文自行生成，展示给用户并允许其调整。绝不能将实体文件命名为
```
index.md
```
（或
```
ignatius.yml
```
中
```
index_file
```
所解析出的名称）——该名称专用于生成的 router，而其 frontmatter 是 flow 文件夹进行自我描述的唯一位置。
捕捉业务故事，而不只是 schema：业务规则、约束、生命周期，以及结构性复杂性背后的原因，都应在正文中写明其来源和理由。将随口提到的“billing 不会允许金额低于 $5 的付款”视为可形成文档的规则，而不是闲聊。
标签和聚类始终必需，适用所有会写入 flow 的模式：每个
```
inputs:
```
/
```
outputs:
```
条目都要在
```
data:
```
旁附上一段简短说明文字
```
label:
```
（图示显示标签；列清单仍是经过验证的契约），而一个流程读写的两个或更多 store 若被视为同一事物，则应在
```
clusters/<slug>.md
```
中声明一次，并通过一个
```
cluster:
```
条目引用。当真实模型达到实际规模时，这正是保持图示可读性的方法；两者都不是可选项，也不是事后补充。参见
```
references/dfd-authoring.md
```
中的步骤 F4a 和 F5。
每次编辑会话都以一条变更说明结束：在任何会写入或更改模型文件的模式中，最后都要在
```
ignatius.yml
```
旁写入一个
```
.ignatius/changes/<slug>.md
```
。其 frontmatter 通过
```
entities:
```
列出每个发生变更的实体及其变更列，并通过
```
flows:
```
列出每个发生变更的图及其变更节点；正文则向审阅者说明原因。用户可在
```
ignatius serve
```
中审阅，并通过
```
ignatius approve
```
接受。首次写入现有模型之前，如果不存在有效的
```
<model>/.ignatius/baseline.json
```
，则运行
```
ignatius approve <model-root>
```
，记录未经改动的初始状态，但仅当
```
.ignatius/changes/
```
中没有任何文件时；如果其中已有说明，则停止操作，并请用户阅读后批准或恢复基线。编辑后绝不能运行该命令。skill 创建的每个模型都会获得一个
```
<model>/.gitignore
```
，其中包含
```
.ignatius/
```
。格式、覆盖范围和 bootstrap 例外情况参见
```
references/change-notes.md
```
。

Reference files

参考文件

Load only the file for the step you are on:

```
references/interviewing.md
```
— how to conduct the Q&A (read first; applies to every mode).
```
references/entity-flow.md
```
— entity Q&A steps, the convention nudge, the subtype step.
```
references/model-flow.md
```
— new-model bootstrap Q&A steps.
```
references/dfd-authoring.md
```
— DFD Q&A steps: the
```
db:
```
/
```
kind:
```
store fork, the cluster step, the label step, the stack legibility count, examples-always, business-context bodies.
```
references/flow-templates.md
```
— process, external, non-
```
db
```
store, and cluster templates.
```
references/discover-flow.md
```
— the Socratic five-gate method (generates entities + flows).
```
references/reverse-engineering.md
```
— extract entities + flows from an existing system (IDEF1X spirit).

references/verification.md

— the

ignatius validate

loop and the rule reference tables.

```
references/change-notes.md
```
— the baseline step before the first write, the change note every edit session ends with, and the model
```
.gitignore
```
.
```
references/templates.md
```
— entity, group, and
```
ignatius.yml
```
templates.
```
references/conventions.md
```
— column types and the classification/cardinality derivation tables.

仅加载当前步骤对应的文件：

```
references/interviewing.md
```
— 如何进行问答（先读；适用于每种模式）。
```
references/entity-flow.md
```
— 实体问答步骤、约定提醒和 Subtype 步骤。
```
references/model-flow.md
```
— 新模型 bootstrap 问答步骤。
```
references/dfd-authoring.md
```
— DFD 问答步骤：store 的
```
db:
```
/
```
kind:
```
分支判定、聚类步骤、标签步骤、stack 可读性计数、示例必填机制和业务上下文正文。
```
references/flow-templates.md
```
— 流程、外部实体、非
```
db
```
存储和聚类模板。
```
references/discover-flow.md
```
— 苏格拉底式五关方法（生成实体和流）。
```
references/reverse-engineering.md
```
— 从现有系统中提取实体和流（IDEF1X 理念）。

references/verification.md

—

ignatius validate

循环和规则参考表。

```
references/change-notes.md
```
— 首次写入前的基线步骤、每次编辑会话结束时的变更说明，以及模型
```
.gitignore
```
。
```
references/templates.md
```
— 实体、group 和
```
ignatius.yml
```
模板。
```
references/conventions.md
```
— 列类型以及分类/基数推导表。