spec-tech

技术规范

你正在编写技术规范——也就是“如何实现”，承接产品规范 （/spec-product），并为各切片设计（/design）提供依据。实体引擎（TOML+MD 层级、关系、show 命令）记录在 [[mem.concept.doctrine.entity-engine]]。

结构。 Doctrine 将规范作为一等实体管理——技术规范与产品规范一样，都需要进行三次协调写入：使用 spec new 搭建框架（仅填写 subtype/title/slug），手动编辑主干和扁平字段，将其写入 spec-NNN.toml，然后通过 spec req add 添加需求。使用 show 查看重新组装后的完整内容，使用 validate 检查外键完整性，使用 list 查看语料库（标志见 --help；动词模型见 lib:reference/using-doctrine.md）。身份信息、关系主干和扁平字段（包括 c4_level、[[source]] 锚点）存放在 spec-NNN.toml 中，叙述内容存放在 spec-NNN.md 中；需求是同级实体（REQ-NNN），通过 members.toml 纳入；仅技术规范适用的规范→规范边，使用 doctrine spec interactions add/remove 写入（不得手动编写）。主干没有对应的 CLI 标志——它以 TOML 编写，而 spec validate 是完整性检查关卡。

记录持久的架构与机制：

• 解决方案的形态——组件、边界、数据流、不变量
• 关键技术决策及其依据（链接相关 ADR）
• 生命周期超出任何单次变更的接口与契约
• 实现必须遵守的约束

关系主干将语料库树中的每个规范关联起来（均为手动编辑的 TOML，并由 spec validate 检查）：

• descends_from——技术规范→PRD，单值，且必须是经过验证的外键，指向该能力所实现的产品意图。
• parent——单一父级，无环的包含关系（C4 分解）。
• 包含关系绝不是同级边。 parent 绝不能表示为 interactions 边；原则上，interactions 边也绝不表示包含关系——分解与同级的 uses/calls 是两个不同的维度。

C4 层级。 手动编写的规范通常止于容器/组件层级；代码级（C4 第 4 级）规范较为特殊，只有当某个机制单元确实需要这种细节层级时才编写。

定位有两种。 技术规范可以是回顾性的（已交付的“如何实现”），也可以是前瞻意图性的（描述尚未构建的引擎）——两者都可以，但必须明确区分计划中与已验证。需求是状态为 pending 的 REQ-NNN 实体；没有覆盖表，也不会推导状态——观测到的覆盖情况需要进行对照确认，绝不能从规范中推断。

三种规范形态。 context/container/component 类型各自只有一种固定形态——编写前，先使用 spec show 阅读一个相同类型的规范：

• context——整个系统的综合描述：无锚点、无 parent、无 descends_from；列出容器及其组成，但绝不复述任何一个容器的机制。
• container——仅有 parent，无继承关系：承载机制的容器，其子项负责记录各能力的继承关系。
• component——parent + descends_from：精简但不贫乏的能力形态——仅记录类型专属契约，通过父级引用共用机制，绝不重复描述。

保持内容长期适用。单次变更的具体设计——当前与目标行为、代码影响、验证方式——应放在该切片的 /design 中，而不是这里。如果某个决策在项目范围内通用且至关重要，可以将其记录为 ADR（doctrine adr new），而不是写入规范正文。