> For the complete documentation index, see [llms.txt](https://zhouhao4221.gitbook.io/haiqing-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zhouhao4221.gitbook.io/haiqing-docs/02-design/domain-knowledge-layer.md).

# 领域知识层：让已有知识被 AI Skill 正确使用

## 1. 问题

工程团队已经积累了大量知识：产品需求文档、工程规约、领域规约。\
这些知识存在，但对 AI Skill 不可见。

结果是：Skill 输出在技术上正确，但违反了行业规则；修改了一个看似局部的变量，导致下游数据全部出错；不同开发者对同一业务概念的理解不一致。

> 没有显式建模的领域知识，会被 AI 用训练数据中的"通用假设"填充。

***

## 2. 三类领域知识

| 类型       | 回答的问题         | 变更频率  |
| -------- | ------------- | ----- |
| **产品需求** | 这个版本要做什么      | 随迭代变化 |
| **工程规约** | 怎么改才不会出问题     | 较稳定   |
| **领域规约** | 这个行业和项目的规则是什么 | 极少变更  |

三类知识的共同特征：

* **不可执行**：本身不是 Skill，不能被调用
* **边界性**：定义什么可以做、什么不能做
* **强制性**：不是建议，是所有开发人员（包括 AI）必须遵守的基线

> Skill 封装"怎么做"，领域知识定义"在什么边界内做"。

***

## 3. 在架构中的位置

```
原则（Principles）
  ↓
领域知识（Domain Knowledge）   ← 本层
  ↓
工作流（Workflow / 编排）
  ↓
Skill（执行单元）
  ↓
Prompt（实现细节）
```

领域知识不直接执行，而是在 Skill 运行时以上下文的形式注入。

***

## 4. 三类知识的作用与注入方式

### 4.1 产品需求

**存放位置**：`req:` 体系（需求文档、验收标准、业务规则）

**作用**：告诉 Skill 为什么执行、服务于谁、什么是正确的输出。

**缺失症状**：Skill 生成的方案在技术上可行，但解决的不是真实的业务问题；验收标准对 AI 不可见，导致输出需要反复修改。

**注入方式**：按任务动态传入，将相关需求片段（目标、约束、验收标准）作为上下文传入。需求变更时，同步检查依赖该需求的 Skill。

***

### 4.2 工程规约

**存放位置**：`03-build/`（逻辑边界说明、高危区域标注、架构约定、代码风格）

**作用**：定义什么可以改、什么不能乱改、改之前必须检查什么。工程规约不只是风格约定，更是防止危险修改的护栏。

这类规约包括：

* **逻辑边界**：哪些模块或变量具有全局影响，修改前必须评估波及范围
* **修改前置条件**：改动 A 之前必须验证 B，否则系统数据会出错
* **高危区域标注**：某段逻辑是多处依赖的核心，改动必须同步通知相关方
* **数据一致性约束**：某字段是系统单一数据源，不能绕过它建平行逻辑
* **代码风格约定**：命名、格式、架构模式等团队约定

**缺失症状**：AI 修改了一个看似局部的变量，导致下游数据全部出错；生成的代码绕过了核心校验逻辑，埋下数据一致性风险；已被明确否决的架构模式被重复引入。

**注入方式**：分两部分——逻辑边界和高危区域作为强制上下文始终注入；代码风格按场景按需注入。

***

### 4.3 领域规约

**存放位置**：规约文档（如团队 Wiki、`docs/specs/` 目录或专用规范文件）。存放位置不限形式，但必须是版本化、可共享的——不能只在个人记忆或口头约定中。

**作用**：定义正确性的边界。违反领域规约，输出本质上是错误的，而不只是质量问题。

这类规约包括：

* 行业规则（金融结算规则、医疗编码标准、合规要求）
* 项目固定约定（核心数据的业务含义、领域术语定义）
* 不随版本迭代改变的业务常识

**缺失症状**：Skill 产出在逻辑上自洽，但在业务上是错的；不同开发者对同一概念理解不同，导致系统行为不一致；问题出现时难以追查，因为错误不在代码层面，而在认知层面。

**注入方式**：强制静态注入，不可省略。

这里需要区分"存放"和"注入"：规约文档是存放位置，CLAUDE.md 或 Skill 的系统提示是注入机制。领域规约必须在 CLAUDE.md 中直接引用或内嵌关键内容，而不是在 Skill 执行时动态检索——动态检索依赖"恰好被查到"，无法保证始终生效。

***

## 5. 强制程度对比

| 类型   | 缺失后果          | 注入方式            |
| ---- | ------------- | --------------- |
| 产品需求 | 做了不该做的功能      | 按任务动态传入         |
| 工程规约 | 触碰高危区域，系统数据出错 | 逻辑边界强制注入；风格按需注入 |
| 领域规约 | **输出原则性错误**   | **强制静态注入，不可省略** |

> 产品需求缺失，顶多做错功能；领域规约缺失，会做出原则性错误。

新成员入职、新 Skill 上线，第一步都是对齐工程规约和领域规约。两者发生变更时，必须通知所有相关方，而不只是更新文档。

***

## 6. 何时应该建模

> 满足以下三个条件时，说明这部分知识已成为系统的隐性依赖，应该显式文档化：
>
> **被多个人或 Skill 共享** + **影响输出正确性** + **当前靠人工记忆维护**

反过来，如果某类知识只影响单个 Skill、变更极快、或已有其他系统管理，不必单独建模，直接在 Skill 的 Prompt 中处理即可。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://zhouhao4221.gitbook.io/haiqing-docs/02-design/domain-knowledge-layer.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.