feature-domain-expert

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

feature-domain-expert

Authoritative guide for authoring and consuming feature knowledge files in
ai-context/features/
.

Triggers: feature file, domain knowledge, ai-context/features, bounded context, business rules, feature-domain-expert, domain invariants, domain context, feature doc

这是编写和使用
ai-context/features/
目录下特性知识文件的权威指南。

触发词：feature file、领域知识、ai-context/features、bounded context、业务规则、feature-domain-expert、domain invariants、domain context、feature doc

Patterns

模式

Pattern 1: Feature file vs. SDD spec — the critical distinction

模式1：特性文件与SDD规范的关键区别

These two file types serve fundamentally different purposes and MUST NOT duplicate each other's content:

Aspect	`ai-context/features/<domain>.md`	SDD spec (engram artifact)
Purpose	Permanent business domain knowledge	Behavioral delta spec for a specific change
Lifetime	Lives forever — updated but never deleted	Created per change — eventually archived
Content	Business rules, invariants, data model, integration contracts, history	GIVEN/WHEN/THEN scenarios describing observable behavior for one change
When written	Once per bounded context; updated via `/memory-update`	Once per SDD change; archived with the change
Who reads it	`sdd-propose` Step 0, `sdd-spec` Step 0, human developers	`sdd-apply` (acceptance criteria), `sdd-verify`
Cross-change value	High — encodes knowledge that predates and outlasts any single change	Low — describes behavior introduced or modified by one specific change

Rule: if you are writing GIVEN/WHEN/THEN scenarios, it belongs in a SDD spec artifact. If you are writing a business rule that will still be true five SDD cycles from now, it belongs in

ai-context/features/

这两种文件类型的核心用途完全不同，绝对不能重复彼此的内容：

方面	`ai-context/features/<domain>.md`	SDD规范（engram工件）
用途	永久业务领域知识	针对特定变更的行为增量规范
生命周期	永久存在——仅更新不删除	随变更创建——最终归档
内容	业务规则、不变量、数据模型、集成契约、历史记录	描述单个变更可观测行为的GIVEN/WHEN/THEN场景
编写时机	每个限界上下文编写一次；通过 `/memory-update` 更新	每个SDD变更编写一次；随变更归档
阅读人群	`sdd-propose` 步骤0、 `sdd-spec` 步骤0、开发人员	`sdd-apply` （验收标准）、 `sdd-verify`
跨变更价值	高——编码了早于且存续于任何单个变更的知识	低——仅描述单个变更引入或修改的行为

规则：如果您在编写GIVEN/WHEN/THEN场景，它属于SDD规范工件。如果您在编写一个在五个SDD周期后仍然有效的业务规则，它属于

ai-context/features/

目录下的文件。

Pattern 2: When to create a feature file

模式2：何时创建特性文件

Create a new

ai-context/features/<domain>.md

when ALL of the following are true:

A bounded context (a coherent area of business logic with its own vocabulary) has been identified — either by working in it during an SDD cycle or during
```
memory-init
```
.
The domain has at least one business rule or invariant that is not captured in any spec file and that future SDD phases should know about.
The domain is likely to be touched again in future SDD cycles (i.e., it is not a one-off technical implementation detail).

Do NOT create a feature file for:

Pure infrastructure concerns with no business rules (e.g., CI pipeline configuration).
A domain whose knowledge is already fully expressed in a small, stable spec file that will never be archived.
Domains that have not yet been explored — create a stub via
```
memory-init
```
and leave sections empty until knowledge is acquired.

当以下所有条件均满足时，创建新的

ai-context/features/<domain>.md

文件：

已识别出一个限界上下文（具有专属术语的连贯业务逻辑领域）——无论是在SDD周期中工作时还是在
```
memory-init
```
过程中。
该领域至少有一个未在任何规范文件中记录且未来SDD阶段需要知晓的业务规则或不变量。
该领域在未来SDD周期中可能会被再次涉及（即它不是一次性技术实现细节）。

请勿为以下场景创建特性文件：

无业务规则的纯基础设施问题（如CI流水线配置）。
知识已完全体现在一个小型、稳定且永远不会归档的规范文件中的领域。
尚未探索的领域——通过
```
memory-init
```
创建占位文件，待获取知识后再补充内容。

Pattern 3: What belongs in each of the six sections

模式3：六个章节的内容规范

The canonical six sections in order — every feature file must contain all six:

1. Domain Overview Write 2–4 sentences describing what the bounded context does, who owns it, and what core responsibility it holds in the system. Focus on purpose and scope, not implementation details.

2. Business Rules and Invariants List the always-true constraints the domain enforces regardless of code path. Each item is a declarative statement that would still hold even if the implementation were rewritten from scratch. Examples: "A refund cannot exceed the original payment amount." "A user must have a verified email before making a purchase."

3. Data Model Summary Describe key entities, their relationships, and critical field constraints in plain prose or a small table. This is not a full schema — orient the reader to the most important entities and their constraints. Relationships between entities belong here.

4. Integration Points Document every external system, service, or domain this bounded context depends on or exposes an interface to. Use a table with columns: System/Service, Direction (inbound/outbound), Contract. Include async contracts (events, queues) and third-party dependencies.

5. Decision Log A chronological record of significant design or implementation decisions made for this domain. Each entry must state: what was decided, the rationale, and what it constrains going forward. Entries are NEVER deleted — they provide historical context for future developers.

6. Known Gotchas Unexpected behaviors, operational hazards, historical defects, or non-obvious constraints that a developer working in this domain must be aware of. Include things that caused bugs in the past, edge cases that are easy to miss, and anything that tripped up previous contributors.

标准的六个章节顺序——每个特性文件必须包含全部六个章节：

1. 领域概述 用2-4句话描述限界上下文的功能、所有者及其在系统中的核心职责。重点关注用途和范围，而非实现细节。

2. 业务规则与不变量 列出领域强制执行的始终有效的约束条件。每条内容均为声明式语句，即使实现被重写，这些约束依然成立。示例："退款金额不得超过原始付款金额。" "用户必须验证邮箱后才能进行购买。"

3. 数据模型摘要 用平实的文字或小型表格描述关键实体、它们的关系以及关键字段约束。这不是完整的架构——只需让读者了解最重要的实体及其约束。实体间的关系应放在此章节。

4. 集成点 记录此限界上下文依赖或对外暴露接口的所有外部系统、服务或领域。使用包含以下列的表格：系统/服务、方向（入站/出站）、契约。包括异步契约（事件、队列）和第三方依赖。

5. 决策日志 该领域重要设计或实现决策的 chronological（按时间顺序）记录。每条记录必须说明：决策内容、理由以及对未来的约束。记录永远不会被删除——它们为未来的开发人员提供历史背景。

6. 已知陷阱 开发人员在该领域工作时必须知晓的意外行为、操作风险、历史缺陷或非显而易见的约束。包括过去导致bug的问题、容易遗漏的边缘情况以及曾让之前的贡献者出错的任何事项。

Pattern 4: Domain slug matching heuristic (used by sdd-propose Step 0 and sdd-spec Step 0)

模式4：领域slug匹配启发式算法（sdd-propose步骤0和sdd-spec步骤0使用）

When an SDD phase runs for

<change-name>

, it determines which feature files to preload using this algorithm:

Input:  change-name (kebab-case string)
Output: list of matching ai-context/features/<domain>.md paths (may be empty)

Algorithm:
  1. If ai-context/features/ does not exist → return [] (skip silently)
  2. List all .md files in ai-context/features/
  3. Exclude any file whose name starts with underscore (e.g. _template.md)
  4. Extract stems: split change-name on "-", discard single-char stems
  5. For each remaining file f:
       domain = filename stem of f (without .md extension)
       if domain appears in change-name
         OR any stem from step 4 appears in domain:
         add f to matches
  6. Return all matches (may be multiple files)
  7. If matches is empty → skip preload silently (no error, no warning)

Examples:

Change name	Stems (after filtering)	Matches
`add-payments-gateway`	`[add, payments, gateway]`	`features/payments.md` — "payments" stem appears in domain
`auth-token-refresh`	`[auth, token, refresh]`	`features/auth.md` — "auth" stem appears in domain
`feature-domain-knowledge-layer`	`[feature, domain, knowledge, layer]`	No match against `sdd-meta-system.md` — none of the stems appear in "sdd-meta-system" and "sdd-meta-system" does not appear in the change name
`improve-project-audit`	`[improve, project, audit]`	No match — stems do not appear in any domain slug

Key behaviors:

```
_template.md
```
is ALWAYS excluded — it is never a preload candidate.
The match is bidirectional: domain-in-change-name OR change-stem-in-domain.
Multiple files may match — all are loaded as enrichment context.
A non-match is NOT an error: the phase proceeds normally without domain context.

当为

<change-name>

运行SDD阶段时，它会使用以下算法确定要预加载的特性文件：

输入:  change-name（短横线分隔字符串）
输出: 匹配的ai-context/features/<domain>.md路径列表（可能为空）

算法:
  1. 如果ai-context/features/不存在 → 返回[]（静默跳过）
  2. 列出ai-context/features/中的所有.md文件
  3. 排除任何以下划线开头的文件（例如_template.md）
  4. 提取词干：将change-name按"-"拆分，丢弃单字符词干
  5. 对每个剩余文件f:
       domain = f的文件名词干（不含.md扩展名）
       如果domain出现在change-name中
         或者步骤4中的任何词干出现在domain中:
         将f添加到匹配列表
  6. 返回所有匹配项（可能有多个文件）
  7. 如果匹配项为空 → 静默跳过预加载（无错误、无警告）

示例:

变更名称	过滤后的词干	匹配结果
`add-payments-gateway`	`[add, payments, gateway]`	`features/payments.md` — "payments"词干出现在domain中
`auth-token-refresh`	`[auth, token, refresh]`	`features/auth.md` — "auth"词干出现在domain中
`feature-domain-knowledge-layer`	`[feature, domain, knowledge, layer]`	与 `sdd-meta-system.md` 无匹配 — 没有词干出现在"sdd-meta-system"中，且"sdd-meta-system"未出现在变更名称中
`improve-project-audit`	`[improve, project, audit]`	无匹配 — 词干未出现在任何domain slug中

关键行为:

```
_template.md
```
始终被排除——它永远不会成为预加载候选。
匹配是双向的：domain出现在变更名称中或变更词干出现在domain中。
可能匹配多个文件——所有匹配文件均会作为 enrichment context（增强上下文）加载。
无匹配不是错误：阶段会在没有领域上下文的情况下正常进行。

Pattern 5: Updating a feature file via /memory-update

模式5：通过/memory-update更新特性文件

Feature files follow an append-only update discipline. When

/memory-update

runs after a session that involved a domain with an existing feature file:

Business Rules and Invariants: append newly discovered rules as new list items. Never remove or reword existing rules unless they are factually wrong (in which case add a correction note below the original rule instead of deleting it).
Decision Log: append a new dated entry for any domain decision made during the session. Entries are never deleted or reordered.
Known Gotchas: append new gotchas discovered during the session. Never remove a gotcha — even if the underlying bug was fixed, a note about the former behavior is useful history.
Other sections: update Data Model Summary and Integration Points if new entities or integrations were introduced. Domain Overview may be updated if the scope of the domain changed significantly.

/memory-update

MUST NOT create new feature files — it only updates existing ones. New feature files are created manually or scaffolded by

memory-init

Respect

[auto-updated]

section boundaries if present (same convention as in other ai-context files).

特性文件遵循仅追加的更新原则。当涉及某个已有特性文件的领域的会话结束后运行

/memory-update

时：

业务规则与不变量：将新发现的规则作为新列表项追加。除非原有规则存在事实错误（此时应在原有规则下方添加更正说明而非删除），否则永远不要删除或改写现有规则。
决策日志：将会话期间做出的任何领域决策添加为新的带日期记录。记录永远不会被删除或重新排序。
已知陷阱：追加会话期间发现的新陷阱。永远不要删除陷阱——即使底层bug已修复，关于过往行为的记录仍是有用的历史信息。
其他章节：如果引入了新实体或集成，更新数据模型摘要和集成点章节。如果领域范围发生重大变化，可更新领域概述章节。

/memory-update

绝对不能创建新的特性文件——它仅更新现有文件。新特性文件需手动创建或通过

memory-init

生成框架。

如果存在

[auto-updated]

章节边界，请遵循该约定（与其他ai-context文件相同）。

Pattern 6: Worked example — the sdd-meta-system domain

模式6：示例——sdd-meta-system领域

The canonical worked example for this skill is

ai-context/features/sdd-meta-system.md

in the

agent-config

repository. It demonstrates all six sections with realistic content for the SDD meta-system bounded context.

Below is an abbreviated illustration of the pattern each section should follow:

Domain Overview (2–4 sentences of purpose and scope):

"The SDD meta-system is the Claude Code configuration and skill orchestration framework... It provides two primary capabilities: a library of reusable skills and an SDD phase pipeline... The system is self-hosting: changes to its own skills must follow the same SDD cycle."

Business Rules and Invariants (declarative always-true statements):

- Every skill modification MUST go through the SDD planning cycle (at minimum /sdd-propose) before /sdd-apply.
- sync.sh MUST only move memory/ from ~/.claude/ to the repo.
- Developers MUST NOT edit files under ~/.claude/ directly.

Data Model Summary (table of key entities with constraints):

| Entity        | Key Fields                         | Constraints                               |
|---------------|------------------------------------|--------------------------------------------|
| Skill         | directory name, SKILL.md, format   | format must be procedural|reference|anti-pattern |
| SDD Change    | proposal, design, tasks             | stored in engram as sdd/<name>/* artifacts |

Integration Points (table of systems with direction and contract):

| System      | Direction | Contract                                              |
|-------------|-----------|-------------------------------------------------------|
| install.sh  | outbound  | Deploys repo to ~/.claude/ — run after any config change |
| sync.sh     | inbound   | Copies ~/.claude/memory/ to repo — memory only         |

Decision Log (chronological, with rationale and impact):

undefined

该技能的标准示例是

agent-config

仓库中的

ai-context/features/sdd-meta-system.md

。它展示了SDD元系统限界上下文的所有六个章节的真实内容。

以下是各章节应遵循模式的简化示例：

领域概述（2-4句关于用途和范围的描述）：

"SDD元系统是Claude Code配置和技能编排框架... 它提供两个核心功能：可复用技能库和SDD阶段流水线... 系统是自托管的：其自身技能的变更必须遵循相同的SDD周期。"

业务规则与不变量（声明式的始终有效语句）：

- 任何技能修改在执行/sdd-apply之前必须经过SDD规划周期（至少执行/sdd-propose）。
- sync.sh必须仅将memory/从~/.claude/移动到仓库。
- 开发人员不得直接编辑~/.claude/下的文件。

数据模型摘要（含约束的关键实体表格）：

| 实体        | 关键字段                         | 约束条件                               |
|---------------|------------------------------------|--------------------------------------------|
| Skill         | 目录名、SKILL.md、格式   | 格式必须为procedural|reference|anti-pattern |
| SDD Change    | proposal、design、tasks             | 作为sdd/<name>/*工件存储在engram中 |

集成点（含方向和契约的系统表格）：

| 系统      | 方向 | 契约                                              |
|-------------|-----------|-------------------------------------------------------|
| install.sh  | 出站  | 将仓库部署到~/.claude/ — 任何配置变更后运行 |
| sync.sh     | 入站   | 将~/.claude/memory/复制到仓库 — 仅处理memory |

决策日志（按时间顺序，含理由和影响）：

undefined

2026-03-03 — Add ai-context/features/ as Tier 1 domain knowledge layer

2026-03-03 — 将ai-context/features/添加为一级领域知识层

Decision: Introduce ai-context/features/<domain>.md as a permanent sub-layer... Rationale: SDD phase skills lack access to stable business context between cycles... Impact: sdd-propose and sdd-spec gain a non-blocking Step 0 that preloads matching feature files.


**Known Gotchas** (operational hazards and non-obvious behaviors):

sync.sh does NOT deploy skills. Running it after a skill edit does nothing — run install.sh.
Direct edits to ~/.claude/ are silently lost on the next install.sh run.


For the full worked example, read `ai-context/features/sdd-meta-system.md`.

---

决策：引入ai-context/features/<domain>.md作为永久子层... 理由：SDD阶段技能在周期之间无法获取稳定的业务上下文... 影响：sdd-propose和sdd-spec新增了一个非阻塞的步骤0，用于预加载匹配的特性文件。


**已知陷阱**（操作风险和非显而易见的行为）：

sync.sh不部署技能。编辑技能后运行它不会产生任何效果——请运行install.sh。
直接编辑~/.claude/下的文件会在下次运行install.sh时被静默覆盖。


完整示例请查看`ai-context/features/sdd-meta-system.md`。

---

Rules

规则

A feature file MUST follow the canonical six-section structure defined in
```
ai-context/features/_template.md
```
. Sections must appear in this exact order: Domain Overview, Business Rules and Invariants, Data Model Summary, Integration Points, Decision Log, Known Gotchas.
Feature files MUST be named
```
<domain-slug>.md
```
where the slug is lowercase and hyphen-separated. No subdirectories are allowed inside
```
ai-context/features/
```
.
```
_template.md
```
and any file with a leading underscore are excluded from the domain preload heuristic. They MUST NOT be loaded by SDD phases.
Feature files encode permanent domain knowledge — they are updated but NEVER deleted or archived. Do not confuse them with SDD spec artifacts (stored in engram as
```
sdd/<change>/spec
```
), which are created per change and eventually archived.
The domain preload step in
```
sdd-propose
```
and
```
sdd-spec
```
is non-blocking. A missing
```
ai-context/features/
```
directory or a non-matching slug MUST NOT produce a warning or failure. The phase always proceeds normally.
```
/memory-update
```
appends to feature files — it MUST NOT overwrite or delete existing content.
```
/memory-update
```
MUST NOT create new feature files; only scaffold them via
```
memory-init
```
or manual authoring.
```
project-analyze
```
does NOT write to
```
ai-context/features/
```
. Feature files require domain expert judgment; they must not be auto-overwritten by a structural scan.
The
```
feature_docs:
```
block in project config is reserved for V2 audit integration. Do not activate it in V1.

特性文件必须遵循
```
ai-context/features/_template.md
```
中定义的标准六章节结构。章节必须严格按照以下顺序排列：领域概述、业务规则与不变量、数据模型摘要、集成点、决策日志、已知陷阱。
特性文件必须命名为
```
<domain-slug>.md
```
，其中slug为小写且用短横线分隔。
```
ai-context/features/
```
目录下不允许有子目录。
```
_template.md
```
和任何以下划线开头的文件均被排除在领域预加载启发式算法之外。它们绝对不能被SDD阶段加载。
特性文件编码永久领域知识——仅更新绝不删除或归档。请勿将其与SDD规范工件（存储在engram的
```
sdd/<change>/spec
```
中）混淆，后者随变更创建并最终归档。
```
sdd-propose
```
和
```
sdd-spec
```
中的领域预加载步骤是非阻塞的。
```
ai-context/features/
```
目录缺失或slug不匹配绝对不能产生警告或失败。阶段始终正常进行。
```
/memory-update
```
仅向特性文件追加内容——绝对不能覆盖或删除现有内容。
```
/memory-update
```
绝对不能创建新特性文件；只能通过
```
memory-init
```
生成框架或手动创建。
```
project-analyze
```
不会写入
```
ai-context/features/
```
目录。特性文件需要领域专家判断；不能通过结构扫描自动覆盖。
项目配置中的
```
feature_docs:
```
块是为V2审计集成预留的。请勿在V1中激活它。