mcpField
D
define-system-doc

define-system-doc

github.com/jayden-dang开发147 次安装4 天前更新
代码仓库

关于 define-system-doc

用于按需编写 Hybrid 1A 目录条目的技能，面向维护系统文档的开发者。它以证据、结构校验和明确审批为门槛，避免将草稿或推断写成权威内容。

主要功能

  1. 01每次仅处理一个目录条目
  2. 02按目录解析条目及模板
  3. 03记录证据等级与来源
  4. 04结构校验后等待人工审批
  5. 05仅写入获批的规范文件

适用场景

  1. 01为目录中的条目起草系统文档
  2. 02在续作时恢复未完成的文档提案
  3. 03审查条目证据并标记阻塞项

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jayden-dang/skills --skill define-system-doc

安装后在 Claude Code 中输入/define-system-doc确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

catalog/
CATALOG.md
catalog/entries/
adr.md
glossary.md
out-of-scope.md
catalog/entries/agents/
config.md
catalog/entries/architecture/
data.md
INDEX.md
integrations.md
runtime.md
system.md
catalog/entries/codebase/
dependencies.md
map.md
modules.md
ownership.md
catalog/entries/ops/
deployment.md
disaster-recovery.md
observability.md
reliability.md
runbooks.md
catalog/entries/product/
guidelines.md
metrics.md
personas.md
principles.md
vision.md
catalog/entries/roadmap/
INDEX.md
catalog/entries/security/
compliance.md
posture.md
threat-model.md
catalog/entries/specs/
INDEX.md
catalog/entries/standards/
accessibility.md

详细介绍

定义系统文档

每次调用恰好编写一条 Hybrid 1A 目录条目。未完成的工作保留在 .skills/system-docs/<entry-key>/ 下。只有在获得明确的人工批准，且提案通过结构验证后，才写入规范使用方文件。

工具包目录 SSOT（不会安装到使用方）： 此技能目录中的 catalog/CATALOG.md 和 catalog/entries/。

查阅其他技能中的钩子： 共享规则位于此文件旁的 consult-recipe.md 中。使用方指向该文件；不会重复陈述这些规则。

解析条目（有界）

  1. SKILL_DIR = 包含此 SKILL.md 的目录。
  2. 仅读取 SKILL_DIR/catalog/CATALOG.md；查找 <entry-key> 对应的行。
  3. 仅加载该行中的条目包路径（位于 SKILL_DIR/ 下）。
  4. 仅加载条目包指定的模板/验证器路径（位于 SKILL_DIR/ 下）。
  5. 默认情况下，不要加载完整目录正文、所有模板或整个文档树。

如果该条目不是 First-class，或者没有可编写的模板，则停止并说明原因——不要编造内容。

临时文件

.skills/system-docs/<entry-key>/
  state.md
  evidence.md
  proposal.md

条目键路径镜像：codebase/map → .skills/system-docs/codebase/map/。

文件内容
state.md条目、规范目标、阶段、已确认的决策、None 槽位、待处理槽位/阻塞项、已否定的假设、延期条件、最后验证的修订版本
evidence.md带有等级 Verified | Inference | Open 的声明；来源；修订版本/环境；槽位
proposal.md仅供预览——绝非 SSOT

恢复工作： 条目包 + state.md + 规范文件（若存在）+ 未解决槽位的证据 + 模板/验证器。默认不要重放对话、读取完整目录或重新扫描整个仓库。

流程

  1. 单个产物——绝不配置整个 Hybrid 1A 树；也绝不为了启动而创建空的使用方目录/文件。
  2. 恢复或初始化临时文件。
  3. 先有证据，再有事实——Verified / Inference / Open。Verified 声明需引用文件:行号。未经明确人工确认，不得将关于合规性、SLO 目标、信任边界、所有权、运行时拓扑或运维流程的 Inference 提升为事实。
  4. 必填槽位——每个槽位最终必须是已确认内容、None — <reason> 或注明名称的 Blocker:。
  5. 提议完整文件或定向补丁（添加/修改/删除选定内容；保留无关内容）。只有在完整审阅新正文后，才能整体替换。
  6. 结构验证——失败 ⇒ 不得提请批准。
  7. 获得明确的人工批准后，才能写入任何规范文件。
  8. 仅写入此条目的规范路径。对于单文件条目，设置 Status: Approved。不得在规范路径写入经中介的 Status: Draft。同一次写入中不得创建同级产物。未经审阅完整替换内容，不得覆盖整个文件。
  9. 新补丁应用前，先前已批准的内容仍具权威性。
  10. 写入后，在 state.md 中将摘要标记为完成。只有 Approved 且验证器通过，才是该主题的唯一 SSOT。

完成条件： 用户拥有已批准的规范文件（或明确停止并列出阻塞项），临时文件已完成或已延期，且未创建任何同级 Hybrid 1A 文件。

权威性

默认的单文件判定规则（条目包可以细化）：

状态规则
Absent规范路径不存在
Non-authoritative文件存在，但 Status ≠ Approved，或结构验证器未通过（包括外部 Draft）
ApprovedStatus: Approved 且结构验证器通过

目录条目使用条目包中的判定规则（不要求有单独的 Status 标头）。

铁律

NEVER SEED AN EMPTY HYBRID 1A TREE
NEVER WRITE CANONICAL DRAFT VIA THIS SKILL
NEVER TREAT proposal.md OR EPHEMERA AS STANDING PROJECT TRUTH
NEVER PROMOTE HIGH-RISK INFERENCE WITHOUT HUMAN CONFIRMATION

合理化借口

想法现实
“我顺手把所有标准文件夹都建好”空林。只创建一个条目
“在该路径下起草没问题；状态标明了 Draft”经协调的工作流绝不会将 Draft 写入规范位置；读者会将外部 Draft 视为非权威内容
“proposal.md 就是最新真相”它只是预览；已批准的规范版本才是 SSOT
“从代码就能看出威胁边界”这是高风险类别——写入持久文本前必须由人工确认
“跳过验证器吧；看起来各项都填满了”结构验证失败会阻止批准——不能含糊其辞
“用我的改写覆盖整张映射表”只能进行针对性补丁，或完全审查后的完整替换

危险信号 — 立即停止

  • 创建空的 docs/security/ 或同级 Hybrid 1A 文件，说是“以后再用”
  • 在模型技能中使用自动调用措辞，将此技能指为 REQUIRED SUB-SKILL
  • 从此技能在规范路径下写入 Status: Draft
  • 为一个条目将整个目录或每个模板都载入上下文
  • 尚有高影响的 Blocker: 未解决时就批准

评论

支持 Markdown