arc42-language

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

arc42 Language

arc42 语言

The arc42 cli helps you to create and maintain machine-friendly, human readable architecture documents The chapter templates and the CLI guide contain the authoring rules and chapter-specific guidance; consult them instead of relying on remembered conventions. Always keep interaction with the human developer high: Architecture is all about decisions and tradeoffs so be sure to always align.

arc42 CLI 有助于创建和维护便于机器处理、便于人类阅读的架构文档。章节模板和 CLI 指南包含编写规则及各章节的专项指导；请查阅这些资料，不要依赖记忆中的约定。始终保持与人类开发者的高频互动：架构的核心在于决策与权衡，因此务必始终达成一致。

Workflow

工作流

For an existing repository, start with
```
arc42 guide migration
```
and follow its review gates.
For a new workspace, create chapter files on demand as you reach each chapter — run
```
arc42 guide chapter <number>
```
first to get the brief and starter template.
Before authoring a chapter, run
```
arc42 guide chapter <number>
```
and read that chapter's template.
Inspect the current model with
```
arc42 get
```
and use
```
arc42 explain <type>
```
when a block is needed.
When authoring or debugging a diagram, run
```
arc42 explain diagram <type>
```
to see required fields, allowed notations, alias syntax, and authoring tips for that diagram type.
Finish with
```
arc42 --dir <workspace> validate
```
and resolve errors before continuing. Warnings and hints that are intentional can be suppressed with a single-line ignore directive placed inside the fenced block of the specific element you want to exempt:
arc42
```
:::ignore H020 Two interfaces, same entry point — intentional split contract :::
```
The rule code is case-insensitive. A reason is optional but recommended. One directive suppresses the next matching diagnostic for that rule at or after its position in the file — place it inside the fence of the element to exempt, not at the top of the file. For full placement rules and how to resolve stale-ignore warnings (WG06), run
```
arc42 explain ignore
```
.
Use
```
arc42 --dir <workspace> coverage --format tree
```
to see which source directories are claimed by building-block or interface elements, and which are not. Uncovered paths are not errors — they may be tooling, tests, or documentation that is intentionally out of model scope.

The guide is read-only. Do not invent facts, silently repair contradictions, or replace human review with validation output.

对于现有仓库，先运行
```
arc42 guide migration
```
，并遵循其中的评审检查点。
对于新的工作区，在进行到各个章节时按需创建章节文件——先运行
```
arc42 guide chapter <number>
```
，获取简要说明和初始模板。
编写章节前，运行
```
arc42 guide chapter <number>
```
，并阅读该章节的模板。
使用
```
arc42 get
```
检查当前模型；需要某个块时，使用
```
arc42 explain <type>
```
。
编写或排查图表时，运行
```
arc42 explain diagram <type>
```
，查看该图表类型所需的字段、支持的表示法、别名语法以及编写建议。
最后运行
```
arc42 --dir <workspace> validate
```
，解决所有错误后再继续。对于有意保留的警告和提示，可以使用单行 ignore 指令进行抑制，该指令应放在需要豁免的特定元素的围栏块内：
arc42
```
:::ignore H020 Two interfaces, same entry point — intentional split contract :::
```
规则代码不区分大小写。提供原因并非强制要求，但建议提供。一条指令会抑制该规则在文件中当前位置或之后出现的下一条匹配诊断信息——请将其放在需要豁免的元素的围栏内，而不是放在文件顶部。要了解完整的放置规则以及如何解决过期的 ignore 警告（WG06），请运行
```
arc42 explain ignore
```
。
使用
```
arc42 --dir <workspace> coverage --format tree
```
查看哪些源目录已被构建块或接口元素声明，以及哪些目录尚未被声明。未覆盖的路径不属于错误——它们可能是工具、测试或有意不纳入模型范围的文档。

该指南为只读内容。不要虚构事实、擅自修复矛盾，或用验证输出取代人工评审。

Commands

命令

bash

arc42 guide migration
arc42 guide chapter <number>
arc42 get --dir <workspace>
arc42 explain <type>
arc42 explain diagram
arc42 explain diagram <type>
arc42 --dir <workspace> validate
arc42 --dir <workspace> coverage --format tree
arc42 rules

arc42

is unavailable, use

npx @doctc/arc42 ...

bash

arc42 guide migration
arc42 guide chapter <number>
arc42 get --dir <workspace>
arc42 explain <type>
arc42 explain diagram
arc42 explain diagram <type>
arc42 --dir <workspace> validate
arc42 --dir <workspace> coverage --format tree
arc42 rules

如果

arc42

不可用，请使用

npx @doctc/arc42 ...

。