domainkit

domainkit

项目领域模型的记录者。domainkit 持续维护两份文档：CONTEXT.md，简要介绍产品是什么、面向谁，后接项目通用语言术语表；以及 docs/adr/，记录架构决策及其缘由。它的核心循环刻意保持精简：捕捉时机、提议记录、征得同意后写入，让词汇以及艰难抉择背后的考量得以明确记录，不必依赖任何人记得去做。

它主要作为设计工作的副产品运行。在讨论决策、起草计划或编写代码时，某个术语逐渐明晰，或某项决策尘埃落定。这时 domainkit 就会触发，提议添加条目，并在你同意后写入。除此之外，还有两种显式模式：一种在单次操作中为项目创建 CONTEXT.md，另一种在之后检查它是否仍与代码相符。

触发时机

路由到以下三种模式之一：

• record，默认模式。需要明确记录某个领域术语，因为它含义模糊、存在多种含义，或两个词被用于指代同一个概念。或者某项决策已敲定，并达到 ADR 标准。也适用于明确请求：“记录这项决策”、“编写 ADR”、“更新术语表”、“将此术语加入通用语言”、“/domainkit”。如果其他技能需要保持领域模型最新，也会将任务交给此模式，而不是自行维护记录格式。
• init。 用户要求创建领域模型：“设置 CONTEXT.md”、“编写项目概述”、“domainkit init”。它会读取代码仓库，只采访负责人一次，然后提议完整的 CONTEXT.md。
• audit。 用户询问模型是否仍然准确：“CONTEXT.md 仍然准确吗”、“审核术语表”、“domainkit audit”。当 CONTEXT.md 已落后于代码时，statuskit 会将任务交给此模式。

由模型触发的运行始终路由到 record。 init 和 audit 仅在用户提出要求时运行，因为它们都会读取整个代码仓库并提议大量差异；是否承担这项开销由用户决定。

domainkit 刻意不承担两种职责：

• 不是盘问者。 质疑某个术语、构造边界情况、压力测试某项决策是否站得住脚，都属于盘问环节。domainkit 记录的是已经敲定的理解；如果某个术语或决策确实尚未解决，请在已安装时使用 grillkit，或直接请用户作出决定，而不是把猜测写下来。init 确实会向负责人提问，但只询问代码无法回答的事实，并为每个问题提供推荐答案。
• 不是状态跟踪器。 项目没有 status.md，也没有记录“当前状态”的文件。项目状态是分散体现的：议题跟踪计划，git 和会话历史记录已发生的事情，交接内容则按需压缩状态。domainkit 只持久记录这些渠道无法还原的内容，也就是产品的用途、术语，以及不可逆选择背后的考量。

同意（适用于所有模式）

每次写入都必须征得同意：只有在用户明确同意后，domainkit 才会写入。record 会逐条提出记录建议。init 和 audit 会展示完整的拟议变更（整个文件或完整差异），并在用户一次明确同意后写入。即使误触发，代价也只是一次可忽略的提议，绝不会写入多余文件。

模式

各模式的正文分别位于 modes/ 下的一个文件中。根据触发时机选择模式，读取对应文件并按其说明操作。本文件中的所有内容均适用于所有模式，因此不会在各模式文件中重复说明。

• 模式 record → 阅读 modes/record.md，然后按其说明操作。
• 模式 init → 阅读 modes/init.md，然后按其说明操作。
• 模式 audit → 阅读 modes/audit.md，然后按其说明操作。

CONTEXT.md 格式

CONTEXT.md 是关于产品是什么，以及其中的词语是什么意思的唯一事实来源：一段简短概述，后接领域驱动设计的通用语言。它不是规范、状态文件，也不是 README。

# <Context name>

<1–2 sentence description of this context.>

## Overview

### What it is
<3 lines or fewer.>

### Who it is for
<3 lines or fewer.>

### The problem it solves
<3 lines or fewer.>

### Core capabilities
- <7 bullets or fewer, one capability each>

### Non-goals
- <3 lines or fewer: what the product deliberately does not do>

## <Optional grouping subheading>

### <Term>
<Tight definition. What it *is*, in 1–2 sentences.>
_Avoid: <synonym to reject>, <another>_

概述。 概述为术语表提供背景，并且能在一屏内显示。

• 按以下顺序分为五部分。 产品是什么、面向谁、解决什么问题、核心能力、非目标。每部分不超过 3 行，核心能力不超过 7 个要点。
• 必须说明产品是什么。 其他部分在所有者表示无关紧要时均可省略。
• 说明目的和受众，而非用法。 概述说明产品为何存在，以及面向谁。不要重复 README 中的安装或使用说明；改为链接到 README。
• 现有文件可选。 没有概述的 CONTEXT.md 仍然有效。init 会提供添加概述的选项，而且不会仅仅因为文件缺少概述就发出标记。

术语表。 除 ## Overview 外，每个 ## 小节都包含术语。

• 允许的内容。 属于本项目领域的专有术语；工作中独有的概念。
• 禁止的内容。 通用编程概念（超时、错误类型、实用模式），无论使用得多么频繁。如果不是领域专属内容，就不应收录在这里。
• 定义风格。 定义术语是什么，而不是它做什么；用一到两句话说明。
• 明确取舍。 一个概念有多个称呼时，选出最佳称呼，并将其他称呼列入_避免_。
• 不设篇幅上限。 术语表随领域发展而扩充；不要为了达到篇幅目标而删去真实术语。

内容规则：仅包含概述和术语表。 不要写状态、阶段、路线图或指标，因为这些内容会过时，应记录在跟踪工具中。不要写决策，因为决策属于 ADR；术语可以链接到影响其定义的 ADR。不要写安装或使用步骤，因为这些属于 README。

多个上下文。 当有界上下文明显不同时，在仓库根目录维护 CONTEXT-MAP.md，列出各个上下文、对应文件的位置，以及上下文之间的关系；仅在单个文件不再适用时才拆分，避免过早拆分。在多上下文项目中，## Overview 块应放在上下文列表上方的 CONTEXT-MAP.md 中，因为它描述的是整个产品。每个上下文对应的 CONTEXT.md 保留其 1–2 句描述和术语表，不包含自身的概述。

ADR 决策记录格式

ADR 存放在 docs/adr/ 中，文件名格式为 NNNN-adr-<slug>-YYYY-MM-DD.md，按顺序编号并补零：0001-adr-use-postgres-2026-07-23.md、0002-adr-adopt-event-log-2026-07-24.md，……编号放在最前面，这样列表就会按决策顺序排列，与其他 docs/ 文件所带的序号一致。编号是权威的决策顺序，ISO 日期后缀是创建日期；不要仅仅因为状态后来发生变化就重命名 ADR。要为新 ADR 编号，请扫描 docs/adr/，找到现有的最大决策编号并加一。仍采用旧格式 adr-NNNN-<slug>-YYYY-MM-DD.md 存放 ADR 的仓库应保留原有编号；新 ADR 使用新格式，并在安装了 repokit 的情况下，指引用户使用其 docs 模式重命名旧文件。只有在需要创建第一个 ADR 时才创建该目录。并行分支可能会使用相同编号；如果发生这种情况，请在合并时重新编号较晚的 ADR，并更新所有引用，包括提及该 ADR 的 Status 行。

# NNNN: <Title>

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

## Status
proposed | accepted | accepted, supersedes ADR-NNNN | deprecated | superseded by ADR-NNNN

## Considered Options
- <rejected alternative worth remembering, and why it lost>

## Consequences
- <non-obvious downstream effect>

标题、背景／决策／原因段落和 Status 构成一份完整的 ADR。每条新记录都必须包含 Status，因为被取代时必须更新其状态。Considered Options 和 Consequences 可选；仅在确有价值时才添加。取代其他 ADR 的记录应在自己的 Status 行中说明：accepted, supersedes ADR-NNNN。

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

1. 难以撤销。 之后改变方向会付出实际代价。
2. 没有背景就会令人意外。 未来的读者仅凭代码会对这种做法感到疑惑。
3. 确实存在权衡。 有实际的替代方案，且经过了权衡。

典型适用情形：架构结构（单体仓库布局、事件溯源）、上下文之间的集成方式、切换成本较高的技术选择（数据库、身份验证提供商）、边界与范围定义、有意偏离惯例、代码中看不出来的约束（合规性、性能），以及对某个替代方案不显而易见的否决理由。

备注

• 即使自动触发，也必须先征得同意。 由模型调用绝不意味着可以在未获提示时写入，因为总会先提出建议。
• 倾向于采用较高门槛。 只有在术语确实冲突或决策确实不可逆时才触发，胜过对每个名词都发出提醒；拿不准时，就保持安静。
• 没有文件系统或 Shell（例如基于浏览器的 Agent）？请将拟议的词汇表条目、ADR 或完整的 CONTEXT.md 以代码块形式打印出来，供用户保存，并跳过文件写入。没有 git log 时，audit 仅与当前工作树进行比较。其他一切保持不变。