domain-context

渐进式领域结晶（PDC）技能

此技能的作用

此技能使任何 AI 助手都能为任何业务应用构建并使用持续演进的领域知识库，通过人机协作协议在多个会话中逐步积累知识。

AI 默认并不“了解”该领域。但借助此技能，它可以：

• 在每次会话开始时读取结构化的 .tasks/domain.md 文件
• 严格按照业务定义使用内部术语和实体名称
• 在工作过程中内联标记领域理解中的空白
• 提出结构化的领域文件补充内容，供人工审核
• 绝不破坏知识库——所有更新都只作为提议，不会自动应用
• 通过渐进式披露管理领域知识的增长——只加载与当前会话相关的内容

---

核心协议

会话开始时

1. 在项目根目录中查找 .tasks/domain.md
2. 如果找到 → 检查文件结构：
   • 单个文件（约 200 行以内）：在开始任何工作之前完整读取。
   • 索引 + 详情文件（拆分结构）：读取根目录中的 .tasks/domain.md 索引（第 1 层 — 核心上下文）。然后确定哪些第 2 层详情文件与当前任务相关，并仅加载这些文件。参见§渐进式披露。
3. 如果未找到 → 提议使用 .tasks/domain.md 处的模板初始化一个文件
4. 向用户确认：“我已加载 [Project Name] 的领域上下文。我熟悉 [N] 个实体和 [N] 个流程。”如果采用拆分模式，还要说明：“我已加载核心上下文。我们开展工作时，我会按需加载详情文件。”

工作期间

• 严格按照 .tasks/domain.md 中的定义使用实体名称、术语和缩写
• 遇到未定义的术语或实体时，内联标记为：[UNKNOWN: <term>]
• 实体之间的关系不明确时，标记为：[RELATIONSHIP UNCLEAR: <entity-a> → <entity-b>]
• 发现似乎隐含但未记录的业务规则时，标记为：[RULE INFERRED: <description>]
• 不要编造领域事实——只使用文档中记载的内容或用户在会话中确认的信息
• 处理特定实体或流程时，如果存在尚未加载的第 2 层详情文件，则加载该文件

会话结束时

始终在最终回复底部生成一个 ## 📋 Proposed Domain Updates 部分。

格式如下：

## 📋 Proposed Domain Updates

> Review these and copy any confirmed items into your .tasks/domain.md

### New Entities Discovered
- **[EntityName]**: [Definition as understood from this session]
  - Attributes: [list]
  - Related to: [other entities]

### Terminology Clarified
- `[term]` → [plain definition]

### Relationships Identified
- [Entity A] → [verb] → [Entity B]: [description]

### Business Rules Observed
- [Rule description]

### Open Questions
- [ ] [Question about something ambiguous or unresolved]

### Suggested .tasks/domain.md Sections to Add/Update
- [ ] [specific section or entry to update]

人工审核此内容，并按需编辑，然后手动更新 .tasks/domain.md。这样可确保领域知识的权威始终掌握在人手中。

---

渐进式披露

领域知识文件会随着时间不断增长。一个在 80 行时运作良好的 .tasks/domain.md，到了 400 行就会变得难以使用。渐进式披露让 AI 能够专注于与当前会话相关的内容，同时仍可访问完整的知识库。

领域知识的三个层级

层级	包含内容	加载时机	典型大小
第 1 层 — 核心	项目概览、术语表、实体名称（仅单行说明）、业务规则表、用户角色表	始终在会话开始时加载	80–120 行
第 2 层 — 工作上下文	完整的实体描述（生命周期、备注、边缘情况）、完整的流程分步说明、关系图、集成点	按需加载；会话涉及该实体或流程时加载	每个文件 30–80 行
第 3 层 — 归档	变更日志、已解决的未决问题、数据迁移说明、供应商专属详情	收到明确请求时，或审查项目历史时加载	不定

每个层级包含的内容

第 1 层 — 核心（根目录下的 .tasks/domain.md，始终加载）：

• ## Project Overview — 项目是什么、谁会使用，以及业务目标（5 行）
• ## Domain Boundaries — 范围内的内容、辅助内容，以及明确排除的内容。防止过度构建。
• ## Terminology Glossary — 简写对照表
• ## Entity Registry — 仅包含名称和一句话描述（不包含完整属性列表、生命周期详情或备注）。可将其视为实体目录。
• ## State Models — 具有状态或生命周期阶段的实体所使用的命名枚举和有效状态转换。AI 必须将这些视为唯一有效值。
• ## Business Rules — 硬性规则表（BR-001、BR-002 等）。这些是 AI 必须始终了解的真实依据。
• ## User Roles — 角色表
• ## Stakeholder Map — 相关人员姓名、他们与系统的关系、主要关注事项，以及何时需要让他们参与。对采用和获得支持至关重要。
• ## Open Questions — 当前尚未解决的问题
• ## Detail Files — 第 2 层文件索引及其单行摘要（见下方文件布局）

第 2 层 — 工作上下文（单独文件，按任务加载）：

• 完整实体规范 — 属性、生命周期、关系、备注、边缘情况（每个主要实体一个文件）
• 完整流程描述 — 分步骤的流程说明（每个流程一个文件）
• 关系图 — 完整的实体间关系表
• 集成点 — 外部系统详情

第 3 层 — 归档（单独文件，按需加载）：

• 变更日志 — 按会话记录所学内容
• 已解决问题 — 已关闭未决问题的历史记录
• 数据迁移备注 — 供应商目录详情、导入流程
• 供应商专属详情 — 价格表结构、门户访问备注

何时拆分：约 200 行规则

在项目早期，使用单个 .tasks/domain.md 效果很好。拆分的触发条件很简单：

当 .tasks/domain.md 超过约 200 行时，建议拆分。

对用户说：“领域文件内容越来越多了——目前有 [N] 行、[N] 个实体和 [N] 个流程。要我将它拆分为索引文件和详细文件吗？这样可以让会话专注于相关内容，同时不会遗漏任何信息。”

如果用户同意，则重组为分层文件布局（见下文）。如果用户更倾向于使用单个文件，请尊重这一选择——这是偏好，而非硬性要求。

AI 在会话开始时如何使用各层

1. Read root .tasks/domain.md (Tier 1 — always)
      ↓
2. Understand the current task
      ↓
3. Determine which entities/flows are relevant
      ↓
4. Load only those Tier 2 files
      ↓
5. Work — loading additional Tier 2 files if the task expands
      ↓
6. Propose updates — specifying which file each update belongs to

示例：用户说“我需要更新 PM 续约流程。”AI 会：

1. 读取根目录下的 .tasks/domain.md（核心上下文——了解所有实体名称和所有业务规则）
2. 加载 docs/domain/flows/pm-renewal.md（相关流程）
3. 加载 docs/domain/entities/pm-renewal.md（相关实体）
4. 不加载 docs/domain/flows/lead-distribution.md 或 docs/domain/entities/customer.md——与此任务无关。

拆分模式下提出更新

当领域内容拆分到多个文件时，“建议的领域更新”部分应指定每项更新应归属的文件：

## 📋 Proposed Domain Updates

### Update: `.tasks/domain.md` (Tier 1 — core)
- Add to Business Rules: BR-013 — [rule description]

### Update: `docs/domain/entities/pm-renewal.md` (Tier 2)
- Add attribute: `priceAdjustmentPercent` — annual price increase applied on renewal

### New File: `docs/domain/flows/engineering-review.md` (Tier 2)
- [Full flow description to create]

### Update: `docs/domain/archive/changelog.md` (Tier 3)
- [Session summary entry]

版本控制

.tasks/domain.md 的 frontmatter 中包含版本标头。这是面向人的版本信息，用于告知 AI 和团队领域知识当前处于什么状态。

版本格式： MAJOR.MINOR

• MAJOR：在基本范围发生变化时递增（新增业务流程、主要实体结构调整、领域边界变更）
• MINOR：每次获批更新时递增（新增实体、新规则、流程调整、新增利益相关者）

由谁递增： 每次获批更新时，系统会自动递增 MINOR。团队认为领域发生了根本性扩展时，由人工递增 MAJOR。

版本标头位于 .tasks/domain.md 的 frontmatter 中：

> **Version:** 1.5
> **Last updated:** 2026-04-06 (Session 30)
> **Changes:** +Commission Report entity, +BR-013–015, updated Quote-to-Close flow

每次获批更新时，AI 必须：

1. 递增版本号（MINOR +1）
2. 更新“Last updated”日期和会话引用
3. 更新“Changes”行，简要说明变更
4. 在 Changelog 部分追加一条记录

如果系统使用 git，提交消息应与 Changes 行保持一致。版本标头和 git 历史面向不同受众——标头面向 AI 和业务用户，git 面向工程团队。

---

.tasks/domain.md 文件结构

完整模板请参见 .tasks/domain.md。

单文件模式（约 200 行以内）

该文件包含以下顶级部分，全部位于同一个文件中：

部分	层级	用途
## Project Overview	1	应用的功能、使用者和主要目标
## Domain Boundaries	1	范围内的内容、辅助内容和排除内容
## Terminology Glossary	1	内部术语及其通俗释义
## Entity Registry	1（名称）/ 2（详情）	包含属性和描述的业务对象
## State Models	1	实体的有效状态、类型和状态转换
## Relationship Map	2	实体之间的关联方式
## Flow Catalog	2	命名的业务流程及其分步信息流
## Business Rules	1	约束、验证规则和边缘情况
## Integration Points	2	外部系统、API 和数据源
## User Roles	1	系统使用者及其可执行的操作
## Stakeholder Map	1	相关人员、他们与系统的关系、关注事项和参与时间
## Open Questions	1	尚未解决的歧义——随时间推移进行审查和澄清
## Changelog	3	所学内容及其时间

在单文件模式下，所有层级的内容都放在一个文件中。这没有问题——层级标签只是注释，用于指导将来的文件拆分。

拆分文件模式（约 200 行以上）

your-project/
├── .tasks/domain.md                   ← Tier 1: Core index (always loaded)
├── docs/
│   └── domain/
│       ├── entities/                  ← Tier 2: One file per major entity
│       │   ├── quote.md
│       │   ├── customer.md
│       │   ├── product.md
│       │   └── ...
│       ├── flows/                     ← Tier 2: One file per business process
│       │   ├── quote-to-close.md
│       │   ├── pm-renewal.md
│       │   └── ...
│       ├── relationships.md           ← Tier 2: Full relationship map
│       ├── integrations.md            ← Tier 2: External system details
│       └── archive/                   ← Tier 3: Historical records
│           ├── changelog.md
│           └── resolved-questions.md
└── ... (rest of your project)

拆分模式下，根目录中的 .tasks/domain.md 包含：

• 完整的第 1 层部分（Project Overview、Domain Boundaries、Glossary、实体名称表、State Models、Business Rules、User Roles、Stakeholder Map、Open Questions）
• 一个 ## Detail Files 索引，指向每个第 2 层文件，并附有一行摘要：

## Detail Files

| File | Contents |
|------|----------|
| `docs/domain/entities/quote.md` | Quote entity — lifecycle, attributes, status workflow |
| `docs/domain/entities/customer.md` | Customer/Account entity — parent-child, territory assignment |
| `docs/domain/flows/quote-to-close.md` | Full quote lifecycle from opportunity to installation |
| `docs/domain/flows/pm-renewal.md` | PM contract renewal process |
| `docs/domain/relationships.md` | Complete entity relationship map |
| `docs/domain/integrations.md` | Salesforce, Watertight, Procore, vendor portals |
| `docs/domain/archive/changelog.md` | Session-by-session learning history |

---

初始化工作流

如果不存在 .tasks/domain.md，AI 应当：

1. 向用户提出 5 个初始问题（参见 references/seed-questions.md）
2. 根据回答填充模板
3. 编写 .tasks/domain.md 草稿
4. 保存前提交审核

初始文件会远少于 200 行。先使用单文件模式，之后再随内容增长进行拆分。

---

随时间扩展领域知识

每次会话都遵循以下循环：

READ .tasks/domain.md (+ relevant Tier 2 files if split)
      ↓
DO WORK (flag unknowns inline)
      ↓
PROPOSE UPDATES (specify target file if split)
      ↓
HUMAN REVIEWS & APPROVES
      ↓
HUMAN UPDATES .tasks/domain.md (or detail files)
      ↓
(next session reads updated files)

成长生命周期

Sessions 1–3:     Single .tasks/domain.md, ~60–80 lines      (Tier 1 only)
Sessions 4–10:    Single .tasks/domain.md, ~100–200 lines     (Tier 1 + 2 mixed)
Sessions 10+:     Split into index + detail files       (Tier 1 / 2 / 3 separated)
Mature project:   Full three-tier structure with archive

当文件超过约 200 行时，AI 应主动提出拆分：

“领域文件现在有 [N] 行了，详细描述了 [N] 个实体和 [N] 个流程。要不要把它拆分成一个核心索引文件和若干独立的详细文件？每次会话只需加载与当前工作相关的部分，而且不会遗漏任何内容。”

如果用户同意：

1. 将 Tier 1 内容提取到精简的根目录文件 .tasks/domain.md（约 80–120 行）
2. 将每个实体的完整描述移至 docs/domain/entities/[name].md
3. 将每个流程的完整描述移至 docs/domain/flows/[name].md
4. 将关系图和集成要点分别移至各自的 Tier 2 文件
5. 将变更日志移至 docs/domain/archive/changelog.md
6. 将 ## Detail Files 索引添加到根目录文件 .tasks/domain.md
7. 保存前展示新的结构供用户审核

随着时间推移，.tasks/domain.md 会成为以下内容的唯一可信来源：

• 新开发者入门
• 未来的 AI 会话（任何模型、任何工具）
• 文档和规格说明
• 测试用例依据

---

参考文件

• .tasks/domain.md — 用于初始化新领域文件的空白模板
• references/seed-questions.md — 启动新领域时要提出的问题
• references/entity-template.md — 用于单个实体文件的模板（大型项目）
• references/anti-patterns.md — 构建领域上下文时应避免的常见错误