sdd-kb

SDD KB

首次回应此技能时，只在开头写一次这一行： sdd-kb v2.1.0 · out/2026 · versão atual: https://github.com/robertodiasduarte/sdd-starter/releases/latest

快速开始

将你对某个领域的了解转化为任何 AI 都能按需查阅的材料，而不是每次对话都要重新解释一遍。

1. 界定领域：哪些内容纳入、哪些内容排除——并询问该领域是否有按时期生效的规则（规范性配置），以及基准日期是什么。
2. 梳理你掌握的知识，区分哪些是理解，哪些是执行。
3. 检查项目索引是否存在；如果不存在，就创建。
4. 编写最小可行内容：index.md + quick-reference.md + 1 个概念 + 1 个操作指南。对于规范性配置，还需包含 fontes/CATALOGO.md、rules/ 中至少 1 条规则，以及生成的 RULE_MAP.md。
5. 遵守各类型的篇幅限制。
6. 声明每个文件的来源，并标记未经核实的内容。
7. 将领域登记到索引中——这是必做步骤。
8. 请专业人员审核——内容由专业人员负责，而不是 AI。

有关分类法和规则，请查阅 references/kb-protocol.md；有关来源信息，请查阅 references/sourcing.md。模板位于 assets/，而 assets/example-kb/ 是完整的示例 KB。对于规范性配置，请阅读 references/normativo.md，并使用 assets/example-kb-normativo/ 作为范例。

适用场景 / 不适用场景

当用户需要 AI 了解其原本并不了解的背景时使用：法律、标准、手册、规范性指引、内部政策、办公室流程、客户规则，以及用户熟悉的工具。当用户发现自己在每次新对话中都要重复同样的解释时，也可以使用。

建议在启动 SDD 工作流之前使用——准备好知识库后，后续阶段便能基于已梳理的内容开展，而不必每次对话都从头重建。这不是前置条件：没有知识库也能使用该方法。

不要将其用于记录正在开发的软件项目——这类内容应使用 SDD 工作流的产物。不要用它来复制公开文档：KB 保存的是你对该内容的理解，尤其是文档中没有说明的内容。

所需数据

最低输入：

• 要记录的领域，以及用户已掌握的相关知识。

可选输入：

• 参考文档、手册或标准；
• 流程当前实际运行方式的示例；
• 要扩充的既有 KB；
• 写入文件所需的项目访问权限。

不要求访问文件系统或互联网。如果无法访问项目，则在聊天中提供文件内容。

必需的输出资源

assets/ 中的模板是输出资源：生成最终文件时必须使用这些模板，而不是凭记忆重建结构。

模板	生成内容
assets/INDEX_TEMPLATE.md	index.md
assets/QUICK_REFERENCE_TEMPLATE.md	quick-reference.md
assets/CONCEPT_TEMPLATE.md	concepts/*.md
assets/PATTERN_TEMPLATE.md	patterns/*.md
assets/KB_INDEX_TEMPLATE.yaml	首次运行时生成项目的 _index.yaml

对于规范性配置，还需使用：

模板	生成内容
assets/INDEX_NORMATIVO_TEMPLATE.md	index.md（替代 INDEX_TEMPLATE.md）
assets/RULE_TEMPLATE.md	rules/*.md
assets/CATALOGO_FONTES_TEMPLATE.md	fontes/CATALOGO.md
assets/TABELA_TEMPLATE.json	tabelas/AAAA-MM-DD/*.json
assets/CASO_TEMPLATE.json	casos/*.json

如何与学员沟通

首次回复前，请阅读 references/como-falar.md：本技能的术语表和一个完整示例。 使用本技能的人通常从未使用过 git 或终端。

阶段	学员看到的名称	本技能中的步骤
1	领域	1
2	理解 × 执行	2
3	编写	3（先编写索引），4 和 5
4	来源和索引	6 和 7
5	专业人员审核	8 到 10（审核提示是必需的，不是问题）

每次回复都按以下顺序组织（没有内容的部分可跳过）：状态（KB: ✅ 1 … · ▶️ 2 … · ⬜ 3 …； ✅ 已完成，不只是已访问；⏸️ 暂停；➖ 跳过；返回某个阶段时，在“现在”中说明原因）· 已完成的工作（短句，不展示命令输出；记录学员的选择）· 现在：阶段 N — 名称（2 到 4 句；进行耗时操作前，说明将运行什么，并告知无需回复）· 你的决定（授权：加粗问题 + 说明每个选项效果的选项； 开放式问题：加粗问题 + 回答方式，并提供“我不知道”选项；分组编号）· 下一步（一行）。

• 每次回复只处理一个阶段；以决策部分结束并停止。
• 技术术语首次出现时必须附上解释——状态中的术语也不例外（术语表见参考文档）。
• 命令输出不能原样呈现：说明数量、内容和需要关注之处；名称最多列出 10 个，之后写“以及另外 N 个”。只有学员需要运行命令时才提供命令，每个编号步骤只提供一个命令，并说明屏幕上会显示什么。
• 不要引用或概括本技能的说明（例如“按照步骤 N”）：说明这样做对学员有什么帮助。
• 回复与选项不符 ⇒ 解答疑问并重复选项。
• 暂停：状态标记为 ⏸️，用一句话说明原因和操作发生的位置，列出带预期结果的编号步骤，说明尚未完成的工作；如果学员需要执行某项操作，则写“完成后，请再来找我——我会从这里继续。”

逐步操作流程

1. 界定领域

与用户确定范围：主题是什么，尤其是哪些内容不属于范围。好的领域应该让人能毫不犹豫地说出“这不属于这里”。

领域太大，写出来的材料就没人能完成。拿不准时，先从小范围开始——之后拆分很容易；未完成的领域对任何人都没有帮助。

接着，用以下措辞或等效说法询问：

这个领域有没有按时期生效的规则——法律、税率、期限、税务文件格式？如果有，本次审核的基准日期是什么（即对照来源核查内容的日期）？

• 是 → normativo 配置：所有带日期的陈述都要注明生效时间，所有来源都要以层级和 SHA-256 记录在目录中，并记录来源之间的冲突。编写前阅读 references/normativo.md。
• 否 → geral 配置（默认）：按以下流程进行，不包含规范性要求。

税务规则并非绝对正确：它只在某个时期内正确。如果不注明生效时间，今天正确的文件明年就会过时，即使一行都没改。

2. 区分理解与执行

与用户梳理其已知内容，并用一个能解决所有问题的问题对每一部分进行分类：

读完之后，这个人会理解某件事，还是会执行某项操作？

• 理解 → concept
• 执行 → pattern

留意常见错误及其明确方向：把实际上的操作步骤写成概念。其表现是文章解释得很好，却无法据此执行任何操作。用户描述一系列操作时，这就是 pattern——请写出步骤。

3. 检查（或创建）项目索引

查找项目的知识库索引——通常位于知识库文件夹根目录的 _index.yaml。

如果不存在，就根据 assets/KB_INDEX_TEMPLATE.yaml **创建。**切勿假定它已经存在，也绝不要因此中断：首次操作时没有索引是正常情况。

4. 编写最小可行内容

严格按以下结构生成：

{dominio}/
├── index.md
├── quick-reference.md
├── concepts/
│   └── {um-conceito}.md
└── patterns/
    └── {uma-receita}.md

四个文件。每个文件都遵循对应模板。

在规范型配置中，最小要求会增加：

{dominio}/
├── index.md              ← INDEX_NORMATIVO_TEMPLATE: Data-base, Conflitos entre fontes, aviso
├── quick-reference.md
├── concepts/{um}.md      ← com `> **Vale para:** <período>` no cabeçalho (até a linha 15)
├── patterns/{uma}.md     ← com "Vale para:" no cabeçalho
├── rules/{ID}.md         ← ≥ 1 regra, uma por arquivo, com vigência e fonte
├── fontes/CATALOGO.md    ← cada documento citado: degrau, versão, captura, SHA-256
└── RULE_MAP.md           ← gerado: python3 scripts/kb_normativo.py rule-map {dominio}

当领域存在相关材料时，tabelas/AAAA-MM-DD/（按生效日期记录的值）和 casos/（输入 → 预期结果）也必须包含在内。某条规则在某个日期发生变更？用 ate: 关闭旧规则，并新增一条——不要编辑过去。只有概念的领域无法帮助执行；只有操作方法的领域无法帮助判断何时应用这些方法——因此，从一开始就必须同时包含两者。

如果有相关材料，欢迎编写多个概念或操作方法。最低要求是底线，不是上限。

5. 遵守长度限制

类型	限制
quick-reference.md	100 行
concepts/*.md	150 行
patterns/*.md	200 行

用户询问时，或文件超出限制时，向用户解释原因：AI 会将该文件与上下文中的所有其他内容一同加载；材料过多不会产生明显错误，而是会让 AI 默默地忽略部分内容。400 行的文件并不更完整，反而更不可靠。

超出限制了？通常是因为文件中有两个主题。拆分比概括更好。

6. 声明来源

每个文件都要说明内容来源：文档、规范或自身实践——这些都可以作为来源。未核实的内容必须用一句话标记为未核实。

把假设写成事实，是知识库中代价最高的错误：它无法与其他内容区分，并会以肯定的语气传播。参见 references/sourcing.md。

在规范型配置中，来源有等级（宪法 > 补充法律 > 法律 > 法令 > 规范性文件 > 技术文件 > 咨询意见 > 学说 > 自身实践）。仅由学说或自身实践支持的规则应标记为 nao-confirmado。而且，文件日期和名称不能证明规则仍然有效：目录会记录版本、采集日期和 SHA-256（python3 scripts/kb_normativo.py sha fontes/<arquivo>）。

切勿包含真实人物的数据、密码或密钥。使用虚构示例同样有效。

7. 在索引中登记领域

这是必做步骤，也是最容易被遗漏的一步。 在 _index.yaml 中添加该领域的区块，包含名称、描述、路径和日期。

如果某个领域的文件夹存在，但没有登记在索引中，它就是不可见的：人和 AI 都无法发现它。在一个包含 43 个领域的实际资料库中，有 4 个领域处于这种情况——整套知识库都无人发现。

8. 交付

如果项目文件系统可写入，则将文件写入领域文件夹，且不得在不提示的情况下覆盖现有材料。

如果无法访问文件系统，则在聊天中交付所有文件，分别放在代码块中，并标明路径；最后按以下顺序提供这三项信息：

1. 说明文件未写入；
2. 提供建议的文件夹结构（包含文件名）；
3. 说明如何使用这些文件——按指定结构保存，并在之后的对话中让 AI 使用该文件夹。

绝不能默默失败，也不能暗示文件已写入。

9. 由专业人士完成最终审核（必需）

在宣布知识库已准备就绪之前，必须明确说明：内容由用户审核，而不是由你审核：

正式使用这个知识库之前，请逐个审核文件。文件由我整理和撰写，但内容由你负责——尤其是涉及法律、法规、政策或期限的部分。请核对记录的内容，并更正与来源不符之处。

这不是走形式。人们正是在自己不知道答案时才会查阅知识库——也就是说，他们无法察觉信息有误。错误一旦进入知识库，就不会只停留在原处：你和 AI 都会信心十足地重复它，并据此指导决策。如果涉及法规或义务，专业人士要承担错误的代价。

明确指出最需要核查的内容：数字、期限、金额、规则的适用条件，以及所有标记为未经核实的内容（步骤 6）。

如果用户表示暂时不会审核，请在 index.md 中注明知识库待审核——标明未经核查的知识库，也好过一个看似权威、实际却未经核查的知识库。

对于规范类配置文件，还要在 index.md 中明确写出以下声明：此知识库不构成税务、会计或法律建议。待审核的知识库不得供软件使用：validate_kb.py --strict 会拒绝标记为 PENDENTE DE REVISÃO 的规范类领域——在任何技能、Agent 或系统使用该知识库之前，都要先运行此命令。

10. 说明今后如何使用

最后用两三行说明用户今后如何查询：在对话开始时，让 AI 读取对应领域的文件夹，或在就相关主题回答之前，让 AI 先读取 index.md。

用户不知道如何调用的知识库，无法改变他们的日常工作。

验证与质量检查清单

在宣布完成之前，请确认：

• 已明确划定领域范围，并在 index.md 中说明哪些内容不包含在内。
• 每个文件都通过了“理解或执行”测试。
• 没有将操作步骤写成概念。
• 最小可行版本所需的四个文件都已存在。
• 没有文件超出其类型的长度限制。
• 每个文件都注明了来源。
• 未经核实的内容均已标记。
• 不包含任何真实个人数据、密码或密钥。
• 已在索引中登记该领域。
• 没有遗留任何 {placeholder}。
• 已告知用户由其负责审核内容，并指出了关键部分。
• 未经审核的知识库已在 index.md 中标记为待审核。
• 用户知道今后如何查询 KB。

对于规范类配置文件，还要确认：

• index.md 中包含基准日期、“来源冲突”章节，以及“此知识库不构成税务建议”的声明。
• 每个概念和操作步骤的标题中都包含“适用范围：”。
• 每条规则都注明生效期（de，若已结束还要注明 ate），来源已编入目录，状态如实标注。
• 目录中的每个来源都注明层级、版本、捕获日期；如果文件位于 fontes/ 中，还要注明 SHA-256。
• 在最后一次修改 rules/ 之后，已重新生成 RULE_MAP.md。

如果可以访问文件系统，脚本 scripts/validate_kb.py 会对其中部分内容进行机械检查：

python3 scripts/validate_kb.py {caminho-do-dominio}            # escrever
python3 scripts/validate_kb.py {caminho-do-dominio} --strict   # antes de software consumir

通过时会输出 PASS，退出代码为 0；发现问题时会列出问题，退出代码为 2。WARN: 行（知识库待审核、基准日期过旧、通用领域看似属于规范类）不会改变退出代码。配置文件类型取自 _index.yaml 中的领域登记信息。

异常处理

• 领域范围过大： 提议缩小范围，并列出留待以后处理的相邻领域。在 index.md 中记录未涵盖的内容。
• 用户只有概念，没有操作方法： 询问用户如何运用这些知识。操作方法几乎总是存在，只是尚未明确表达。
• 用户只有操作方法： 询问为什么要按这些步骤来做。答案中通常会包含相关概念。
• 项目索引不存在： 根据模板创建。这是首次使用时的正常状态，不是错误。
• 该领域已有 KB： 在现有 KB 中扩展——在相同目录中添加概念和操作方法——而不是另建一个平行领域。
• 文件超出限制： 找出其中的两个主题并拆分。只有确实属于同一主题时才进行概述。
• 没有文件系统： 在聊天中提供全部内容，并附上步骤 8 中的三项信息。
• 材料包含真实数据： 写入前替换为等效的虚构示例。
• 两个来源说法不同： 在规则中记录冲突（conflito_com），并在 index.md 中说明知识库采用哪种说法及其原因。绝不默默做出选择。
• 规则发生变化： 为旧规则填写结束时间 ate:，并从新日期起创建新规则；重新生成 RULE_MAP.md。
• 软件将使用该知识库： 先运行 --strict；软件通过规则 ID 引用规则，通过 SHA-256 引用来源，不复制概念（参见 references/normativo.md 中的“KB consumido por software”）。

示例

办公室流程 Quero que a IA saiba como funciona o fechamento mensal aqui.

划定范围（会计结账，不包括税款计算），将解释决策的概念与执行核查的操作方法分开，编写四个文件并登记。

用户熟悉的工具 Uso essa ferramenta há anos e toda vez preciso reexplicar pra IA.

梳理用户知道、但文档未提及的内容——陷阱、容易出错的地方以及不适用的情况。这正是 AI 所缺少的材料。

有生效期限的法规 Quero uma base da Reforma Tributária para alimentar meu validador de NF-e.

采用规范性配置，并在步骤 1 询问基准日期。技术说明中的每条规则都在 rules/ 中创建一个文件，标明生效期限和页码；技术说明、补充法律和查阅的报道按层级加入目录；将“划掉 2026，覆盖写上 2027”作为冲突记录。kb_normativo.py rule-map 会生成 RULE_MAP.md（validate_kb.py 只检查它是否为衍生生成），而 NF-e 验证器会复制此映射并通过 ID 引用每条规则。

分散的知识 Tenho anotações espalhadas sobre isso.

阅读材料，将每部分归类为理解或操作，并在写入前向用户说明哪些内容未纳入范围。

没有文件系统 (no chat da web) Monta uma base de conhecimento disso aqui.

在聊天中提供四个文件，注明各自路径，并附上目录结构以及之后如何将 AI 指向这些文件的说明。

下一步

知识库已创建。之后每次就该主题开始对话时，请将 AI 指向该领域的文件夹。

---

SDD Open by RDD 的一部分 — https://github.com/robertodiasduarte/sdd-open