BLOG

五层World文档治理模型

2026/05/15 3 min read BLOG 编程规范 结构化 五层WORLD文档治理模型

Worked for 1m 3s

可以,按你这个仓库语境,我会这样定义:

World 含义 现有主文件
Truth World 真值层,记录“事实本体”在哪里。比如 MySQL、文件真源、project.json 里的 sourceOfTruth。 project.json, storage-contract.md, STORAGE_TOPOLOGY.md
Contract World 规则层,定义“怎么说、怎么读、怎么写”。包括 schema、OpenAPI、边界约定、版本兼容。 openapi.yaml, api-surface-governance.md, docs/contracts/*
Runtime World 执行层,真正跑起来的服务、脚本、路由、守护进程。 gateway/services/docs/runtime/*
Evidence World 证据层,证明“做过、跑过、验过”。包括 smoke、日志、inventory、timeline、benchmark。 smoke.mjs, events.jsonl, docs/operations/*
Projection World 投影层,真值的派生视图,不是本体。比如 generated client、catalog、索引、外部展示面。 generated/clients/database-gateway, catalog-info.yaml

我的规范建议是:

  1. 每份文档先声明自己属于哪个 World。
  2. 每个 World 只保留一个 canonical owner。
  3. Truth 不写接口细节,Contract 不写运行细节,Runtime 不写事实定义,Evidence 不写业务规则,Projection 不反向当真源。
  4. README 只做总索引,不堆规则正文。
  5. 一份文档如果跨两个 World,拆开,不要混写。

最稳的文档模板我建议统一成这几个字段: