domainkit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

domainkit

Scribe of the project's domain model. domainkit keeps two living artifacts current as work happens: CONTEXT.md
, a glossary of the project's ubiquitous language, and docs/adr/
, the log of architectural decisions and why they were made. Its loop is narrow on purpose, detect the moment, offer to record it, write on consent, so the vocabulary and the reasoning behind hard choices stay pinned down without anyone remembering to do it.

It runs primarily as a byproduct of design work, though explicit invocation is supported. While a decision is being grilled, a plan drafted, or code written, a term crystallizes or a decision lands. That's when domainkit fires, proposes the entry, and writes it once you say yes.

项目领域模型的记录工具。domainkit会在工作开展过程中持续维护两个动态文档：CONTEXT.md
（项目通用语言的术语表）和**

docs/adr/

**（架构决策及其制定原因的日志）。它的工作流程刻意设计得简洁：检测时机、提议记录、经同意后写入，这样无需刻意提醒，就能确保核心词汇和关键决策背后的逻辑始终清晰明确。

它主要作为设计工作的副产品运行，但也支持显式调用。在决策研讨、方案起草或代码编写过程中，当某个术语明确下来或某项决策确定时，domainkit就会触发，提出记录方案，待您确认后完成写入。

When this fires

触发场景

A domain term needs pinning down, because it's vague, overloaded, or two words are being used for one concept. Or a decision gets settled that meets the ADR bar (below). Also on explicit asks: "record this decision", "write an ADR", "update the glossary", "add this term to the ubiquitous language", "/domainkit". And when another skill needs the domain model kept current, it defers here rather than carrying the format itself.

Two things it deliberately is not:

Not the interrogator. Challenging a term, inventing edge-case scenarios, stress-testing whether a decision holds: that's an interrogation step. domainkit records the settled understanding; if a term or decision is still genuinely unresolved, use grillkit when installed or ask the user to settle it directly rather than writing down a guess.
Not a status tracker. There is no
```
status.md
```
and no "current state" file. Project status is ambient: issues track what's planned, git and session history track what happened, a handoff compacts state on demand. domainkit persists only what those can't recover, meaning the vocabulary and the reasoning behind irreversible choices.

当领域术语需要明确（因含义模糊、过载或同一概念使用多个词汇），或某项决策达到ADR标准（见下文）时触发。此外，当用户明确提出“记录此决策”“编写ADR”“更新术语表”“将此术语添加到通用语言中”“/domainkit”，或其他技能需要保持领域模型最新时，也会触发domainkit，由它来处理格式相关的工作。

它刻意不承担以下两种角色：

不是质询工具：质疑术语、设想边缘场景、测试决策是否成立属于质询环节。domainkit仅记录已确定的共识；如果术语或决策仍未真正解决，若已安装grillkit则使用该工具，或直接请用户明确后再记录，而非猜测记录。
不是状态跟踪器：它不会生成
```
status.md
```
或“当前状态”文件。项目状态是实时可见的：议题跟踪计划内容，git和会话历史记录已完成工作，按需交接可汇总状态。domainkit仅保留上述方式无法恢复的内容，即核心词汇和不可逆决策背后的逻辑。

Procedure

操作流程

Every write is consent-gated, so detect, offer, then write only on a yes. A misfire costs one dismissible offer, never a spurious file.

所有写入操作都需要经同意，流程为：检测时机、提议记录、仅在同意后写入。误触发只会产生一个可忽略的提议，绝不会生成无效文件。

1. Detect the moment

1. 检测时机

A term is being used loosely or inconsistently, or a settled decision clears the three-part ADR bar. In flow, this surfaces mid-grill, mid-plan, or mid-implementation; you don't wait to be called.

当术语使用松散或不一致，或已确定的决策满足ADR的三项标准时触发。在实际工作中，这通常发生在研讨、方案起草或实现过程中，无需等待调用。

2. Locate the existing artifacts

2. 定位现有文档

Read the repo-root

CONTEXT.md

if it exists (or

CONTEXT-MAP.md

→ the right context file for a multi-context project). If neither exists, create

CONTEXT.md

at the repo root when the first glossary term is accepted. For an ADR, scan

docs/adr/adr-*.md

and take the highest existing decision number.

读取仓库根目录下的

CONTEXT.md

（若存在），或

CONTEXT-MAP.md

（适用于多上下文项目的正确上下文文件）。若两者都不存在，则在第一个术语表条目被接受时，在仓库根目录创建

CONTEXT.md

。对于ADR，扫描

docs/adr/adr-*.md

文件，获取现有最高决策编号。

3. Offer

3. 提议记录

Show the proposed glossary entry or ADR and ask before writing. Keep the proposal tight enough to accept or redirect at a glance.

展示拟添加的术语表条目或ADR内容，并在写入前征得同意。提议内容需简洁明了，便于快速接受或调整。

4. Write on consent

4. 经同意后写入

Glossary. Add or adjust the term in place. Keep
```
CONTEXT.md
```
a pure glossary: what terms mean, nothing else. Be opinionated, so when several words compete, pick one canonical term and list the rest under
```
_Avoid_
```
.
ADR. Create
```
docs/adr/adr-NNNN-<slug>-YYYY-MM-DD.md
```
at the next number, using a short lowercase kebab-case slug and the decision's ISO creation date (for example,
```
adr-0007-use-postgres-2026-07-23.md
```
). Minimal by default; add optional sections only when they carry real value. ADR content is immutable once shipped; the
```
Status
```
field is the one mutable exception, so a later ADR may mark the old record
```
deprecated
```
or
```
superseded by ADR-NNNN
```
.

术语表：在合适位置添加或调整术语。保持
```
CONTEXT.md
```
为纯术语表：仅记录术语含义，不包含其他内容。要有明确立场，当多个词汇指代同一概念时，选择一个标准术语，其余词汇列在
```
_Avoid_
```
下。
ADR：使用下一个编号创建
```
docs/adr/adr-NNNN-<slug>-YYYY-MM-DD.md
```
文件，其中slug为简短的小写连字符格式，YYYY-MM-DD为决策创建的ISO日期（例如：
```
adr-0007-use-postgres-2026-07-23.md
```
）。默认内容极简；仅当确有价值时才添加可选章节。ADR内容一旦生成便不可修改；
```
Status
```
字段是唯一可修改的例外，后续ADR可将旧记录标记为
```
deprecated
```
（已弃用）或
```
superseded by ADR-NNNN
```
（被ADR-NNNN替代）。

5. Defer when unsettled

5. 未确定时暂缓

If the term or decision isn't actually resolved, don't manufacture certainty. Use grillkit to settle it first when installed, or ask the user to settle it directly, then record the result.

若术语或决策尚未真正解决，切勿强行确定。若已安装grillkit，先使用该工具解决，或直接请用户明确，之后再记录结果。

6. Hand off

6. 交接

Write this section in the procedural register: one instruction per sentence, active voice, present tense, no metaphor.

Keep this short. domainkit usually fires inside someone else's work, so a long report is an interruption on top of an interruption.

What changed. One line: the term added or adjusted, or the ADR written with its number and title.

Where it landed. Give the exact path (

CONTEXT.md

, or

docs/adr/adr-NNNN-<slug>-YYYY-MM-DD.md

Next. Normally, return to what was interrupted: name the grill, plan, or implementation this fired inside and pick it straight back up. Only when something genuinely follows from the write does it outrank that: a new ADR that supersedes an older one leaves the old record's

Status

stale, so offer that flip; a term that turned out to be contested isn't settled at all, so route to grillkit (when installed) or ask the user to settle it rather than leaving a guess on disk. Invoked directly with nothing to return to? Say what was written and stop, because there is no next step to invent.

Write this section in the procedural register: one instruction per sentence, active voice, present tense, no metaphor.

保持内容简短。domainkit通常在其他工作过程中触发，过长的报告会额外打断工作。

变更内容：一句话说明：添加或调整的术语，或已写入的ADR编号及标题。

存放位置：给出精确路径（

CONTEXT.md

或

docs/adr/adr-NNNN-<slug>-YYYY-MM-DD.md

）。

下一步：通常，回到被打断的工作：指明触发domainkit时正在进行的研讨、方案或实现工作，并直接继续。仅当写入操作确实带来后续工作时，才优先处理该后续工作：例如，新ADR替代旧ADR会导致旧记录的

Status

过时，此时需提议更新状态；若术语存在争议则并未真正解决，需转至grillkit（若已安装）或请用户明确，而非在磁盘上留下猜测性记录。若直接调用且无后续工作可返回？说明已写入内容即可停止，无需凭空创造下一步。

The CONTEXT.md glossary format

CONTEXT.md术语表格式

CONTEXT.md

is the single source of truth for what words mean in this project, a Domain-Driven-Design ubiquitous language, not a spec and not a status file.

markdown

undefined

CONTEXT.md

是项目中词汇含义的唯一权威来源，是领域驱动设计（Domain-Driven-Design）的通用语言，而非规范文件或状态文件。

markdown

undefined

<Context name>

<上下文名称>

<1–2 sentence description of this context.>

<1–2句话描述此上下文。>

<Optional grouping subheading>

<可选分组子标题>

<Term>

<术语>

<Tight definition. What it is, in 1–2 sentences.> Avoid: <synonym to reject>, <another>


- **Content allowed.** Terms specific to *this* project's domain; concepts unique to the work.
- **Content forbidden.** General programming concepts (timeouts, error types, utility patterns), however heavily used. If it isn't domain-specific, it doesn't belong here.
- **Definition style.** Define *what a term is*, not what it does; one or two sentences.
- **Be opinionated.** When multiple words exist for one concept, choose the best and push the others to `_Avoid_`.
- **No size cap.** A glossary grows with the domain; never evict a real term to hit a length target.
- **Multiple contexts.** When bounded contexts clearly diverge, keep a `CONTEXT-MAP.md` at the repo root listing each context, where its file lives, and the relationships between them; split lazily, only once one file stops making sense.

<简洁定义。1–2句话说明术语是什么。> Avoid: <需弃用的同义词>, <另一个同义词>


- **允许的内容**：特定于*本项目*领域的术语；工作特有的概念。
- **禁止的内容**：通用编程概念（超时、错误类型、工具模式），无论使用频率多高。若不属于领域特定内容，则不应放入此处。
- **定义风格**：定义术语**是什么**，而非**做什么**；1–2句话。
- **明确立场**：当同一概念有多个词汇时，选择最优词汇，其余词汇放入`_Avoid_`。
- **无大小限制**：术语表随领域发展而增长；切勿为了达到长度限制而删除真实术语。
- **多上下文场景**：当限界上下文明显分化时，在仓库根目录保留`CONTEXT-MAP.md`，列出每个上下文、其文件位置及上下文间的关系；仅当单个文件不再合理时，才逐步拆分。

The ADR decision record format

ADR决策记录格式

ADRs live in

docs/adr/

and use

adr-NNNN-<slug>-YYYY-MM-DD.md

, numbered sequentially with zero-padding:

adr-0001-use-postgres-2026-07-23.md

adr-0002-adopt-event-log-2026-07-24.md

, … The number is the authoritative decision order and the ISO suffix is the creation date; never rename an ADR merely because its status changes later. To number a new one, scan

docs/adr/

for the highest existing decision number and increment. Create the directory only when the first ADR is needed. Parallel branches may claim the same number; when that happens, renumber the later ADR during merge and update any references to it.

markdown

undefined

ADR存放在

docs/adr/

目录下，命名格式为

adr-NNNN-<slug>-YYYY-MM-DD.md

，编号按顺序零填充：

adr-0001-use-postgres-2026-07-23.md

、

adr-0002-adopt-event-log-2026-07-24.md

……编号是决策的权威顺序，ISO后缀是创建日期；切勿仅因状态变更而重命名ADR。为新ADR编号时，扫描

docs/adr/

获取现有最高决策编号并递增。仅在需要创建第一个ADR时才创建该目录。并行分支可能使用相同编号；出现这种情况时，在合并期间重命名较晚的ADR，并更新所有对它的引用。

markdown

undefined

NNNN: <Title>

NNNN: <标题>

<1–3 sentences: what the context was, what was decided, and why.>

<1–3句话：决策背景、决策内容及原因。>

Status

proposed | accepted | deprecated | superseded by ADR-NNNN

Considered Options

<rejected alternative worth remembering, and why it lost>

<值得记录的被否决方案及其落选原因>

Consequences

<non-obvious downstream effect>


A single paragraph, title plus the context/decision/why, is already a valid ADR. `Status`, `Considered Options`, and `Consequences` are **optional**; include one only when it adds value.

**Write an ADR only when all three hold:**

1. **Hard to reverse.** Changing course later carries real cost.
2. **Surprising without context.** A future reader will question the approach from the code alone.
3. **A genuine trade-off.** Real alternatives existed and were weighed.

Typical qualifiers: architectural structure (monorepo layout, event sourcing), integration approaches between contexts, technology choices with high switching cost (database, auth provider), boundary and scope definitions, deliberate deviations from convention, constraints invisible in code (compliance, performance), and non-obvious rejections of an alternative.

<非显而易见的后续影响>


仅包含标题和背景/决策/原因段落的ADR即为有效。`Status`、`Considered Options`和`Consequences`为**可选**；仅当能增加价值时才包含。

**仅当满足以下全部三项条件时才编写ADR**：

1. **难以撤销**：后续改变方向会产生实际成本。
2. **无上下文时易引发疑问**：未来读者仅通过代码会对该方法产生疑问。
3. **存在真实权衡**：曾考虑过真实替代方案并进行了权衡。

典型适用场景：架构结构（单仓库布局、事件溯源）、上下文间的集成方式、切换成本高的技术选择（数据库、认证提供商）、边界和范围定义、刻意偏离常规的做法、代码中不可见的约束（合规性、性能）、非显而易见的方案否决。

Notes

注意事项

Consent holds even when auto-fired. Being model-invoked never means writing unprompted, because the offer always comes first.
Bias toward the high bar. Better to fire on a genuinely conflicting term or a genuinely irreversible decision than to nag on every noun; when in doubt, stay quiet.
No filesystem or shell (e.g. a browser-based agent)? Print the proposed glossary entry or ADR as a codeblock for the user to save, and skip the file write. Everything else is unchanged.

即使自动触发也需经同意：即使由模型调用，也绝不擅自写入，必须先提出提议。
倾向于高标准触发：宁可在术语确实冲突或决策确实不可逆时触发，也不要对每个名词都进行提示；存疑时保持静默。
无文件系统或Shell环境（例如基于浏览器的Agent）？将拟添加的术语表条目或ADR以代码块形式打印给用户保存，跳过文件写入步骤。其余流程保持不变。