系统四件套 · 条款

x-arch

条款回答「必须或禁止什么、为什么、怎么做」,每条末尾写明哪颗闸在守它 —— 写着「无机器闸」的,就是机器管不到、只能靠人的那一类。

规范版本
"V2.0.10"
判据指纹
"40bb20dc"
条款格式
"clauses-v1"
条款数
17

真相源:.claude/rules/x-arch-rule.md · 本页是它的构建产物,改内容改那份文件、重新构建即更新

设计:.claude/arch/system/x-arch/ARCH.html
判据:.claude/skills/x-spec-checker/references/x-arch-spec.md

条款

ARCH-A01业务域按四大中心登记,注册表与目录一一对得上

必须

.claude/arch/business/_index.md 是业务架构目录的唯一名册 —— 「四大中心」一节登记中心(第 2 列是反引号包住的小写英文代号,与后台菜单 localeKey 第一段同名,不重复);「已固化业务域」表每一行的门牌(第 1 列)是「中心/域」两层小写英文、中心已登记,第 2 列反引号里的文档路径就是「门牌/ARCH.md」且真实存在,不重复登记;反过来,arch/business/ 下每个域目录(含 ARCH.md 的目录)都在这张表里登记。

为什么

业务架构的第一层就是后台菜单的四个中心(营销 = 客户流、电商 = 订单流、服务 = 工单流、研发 = 系统),菜单、目录、站点导航同名同序,一个域只有一个名字(2026-09-23 用户拍板,ADR-59)。此前目录里三种口径混用 —— 客户与供给方放在根上、其余在 ecommerce/ 与 system/ 下,站点又另起一套 platform/… 名字,同一个域在目录与站点里叫法不同,而业务目录里的 system/ 还与系统架构 arch/system/ 撞名;站点只分「电商 / 平台」两类,导航平铺,订单、优惠券看上去挂在「平台」下面。登记即承诺有文档,登记了却没建文档读者照着注册表找过去就是死链;反过来有目录没登记,站点导航按注册表生成,那个域在导航里就不存在 —— 两个方向都要锁。门牌与文档路径必须同名,是为了让「这个域叫什么」只有一个答案。

怎么做

新建业务域先判它归哪条业务流 —— 围着客户转的进营销,从选购到下单的进电商,从派单到上门的进服务,系统本身、不对外开放的进研发 —— 再建 中心/域/ARCH.md 与 CHANGELOG.md,然后在注册表对应中心那一组里加一行(站点导航的顺序就取表的行序)。代码目录(x-data / x-server / x-admin / x-client)不跟着分类搬,域在 describes 里认领代码。确实要开一个新中心(客服、知识、运营、职能这类,后台菜单里已有位置),先在「四大中心」一节登记,名字与代号照后台菜单取。下线域时文档与注册表行同批删除。_index.md 与 _context-map.md 留在 business 根,它们是名册与跨域图,不是域文档。

ARCH-A02业务架构文档头按契约写

必须

ARCH.md 以 frontmatter 开头,含 title、layer、status、version、describes、specRefs、sourceOfTruth 七个键;layer 写 business;status 只取 active、superseded、deprecated;describes 下 data、server、admin、client 四端键齐全,不涉及的端写 null;describes 里每条路径的 base 目录必须真实存在(写了路径就得指到真东西,指不到就写 null),而且只能写成「目录/」这一种形态,路径是唯一的规范写法**(从仓库根写起、不带 ./ 或 ../、不重复斜杠、大小写与磁盘上的真实目录一致);specRefs 列的每个名字是 references 下真实存在的规范,并且在正文里出现。

为什么

文档头是代码锁步、放置闸与注册表读取的结构化入口,缺键就认不出这个域描述了哪些代码。业务架构对系统规范只点名引用、不复述技术契约;抄进来就是第二份真相,规范一改它就过时。路径必须指到真东西这一条是 2026-09-21 对抗审查实测逼出来的:保鲜闸的声明值与实算值取自同一行 frontmatter —— describes 指向不存在的目录时,实算文件集为空、签名算出 null,与声明的 null 恰好相等,于是整条静默通过。这让保鲜闸的唯一输入被它自己的被检对象握着:被拦下的人只要把那一端的路径改成一条死路(一行 Edit),该端从此永久绿且零告警。立闸当轮就抓到一处真错 —— 账号注销域三条路径全部不存在,而它的正文明写着「四端代码均未落地,srcHash 全 null 即是证据」,frontmatter 与正文自己的陈述互相矛盾。(V2.0.0 起保鲜闸改为代码锁步、srcHash 退役,但同一个病还在:describes 指向死路,锁清单里这一端就一个文件都没有,改了真代码也不会对不上 —— 这一臂照旧守着。)射程只到「路径存不存在」:把某端整个改成 null 仍然合法,那是 diff 里一眼可见的显式动作,归提交审查,不为它再开一本登记账。只许「目录/」一种写法是 2026-09-22 补的:路径存在但保鲜闸走不进去的写法 —— 单个文件、中段带通配、不带 /** 的目录 —— 实算同样是 null、与声明相等而静默,菜单方案的对抗检查用真判据实测打出来;值域那一臂只堵了「不存在」,没堵「存在但进不去」。路径必须是唯一规范写法是同日稍后补的**:同一个目录换个写法(./ 开头、重复斜杠、中段 ../、换大小写)保鲜闸照样走得进去,而放置闸按字面前缀判「谁认领了哪张表」—— 第二个域用别名认领同一张表,重叠检查就看不见,对抗检查实测五种写法全过。

怎么做

文档头照这个形状写(subdomain、endScope、lastReviewed 等附加键可以有):

  ---
  title: 订单业务架构
  layer: business
  status: active
  version: 1.0.0
  describes:
    data: ["x-data/ecommerce/order/**"]
    server: ["x-server/admin/ecommerce/order/**", "x-server/client/ecommerce/order/**"]
    admin: ["x-admin/src/xModules/order/**"]
    client: null
  specRefs: ["x-api", "x-order"]
  sourceOfTruth: true
  ---

正文讲到技术契约时写「以 x-order 规范为准」,不抄规则内容。

ARCH-A03改了描述域的代码或设计,必须在变更历史最上面加新的一版并封版

必须

describes 所指的四端代码、或域目录里的设计文件(ARCH.md 与视图页),在本域上一次封版之后改过、新增或删掉,就要回看本域设计、确认仍成立,在同级 CHANGELOG.md 最上面加新的一版(写标题与说明),把 ARCH.md 的 version 改成同一个,再用统一封版命令封版。一个文件被两个域认领,两个都要升。

为什么

业务架构最常见的坏法是随代码演化静默过时。封版时统一封版命令把本域描述的每个文件的指纹记进域的锁清单 version-lock.json(代码原文比,注释、空白、import 顺序改了也算改;数据表比完整结构,字段、必填、唯一、选项集、长度都算),此后改了哪个文件就在哪个文件上报红,报文写明是哪一份设计、该跑哪条命令 —— 「代码变了」是机器看得见的事实,「回看了设计」由封版这一步逼出来(检测零红、本域测试全过、写了这一版的标题与说明,缺一样不封)。V2.0.0 之前这件事靠文档头的 srcHash(四端各一个签名):只知道「这一端变了」,不知道是哪个文件,也没有地方记「这一版封的是哪份代码」;而且它是业务域独有的一套,与系统规范域、整个 HARNESS 各管各的,三层写法不一。报文不印指纹(2026-09-21 立,沿用):旧报文把正确答案直接递到手上,最小合规动作就成了复制粘贴,正是 ADR-16(2026-07-11)F3「橡皮图章均衡」的原形;现在指纹只由封版命令写,手写的记录行收尾复核认不出来。

怎么做

业务功能走 /x-feature-dev,收尾的 ARCH-SYNC 派 x-architect 回看、在变更历史最上面加新的一版(## v主.次.补 · YYYY-MM-DD · 一句标题,写明改了什么、回看结论)、改 ARCH.md 的 version,然后封版:node .claude/skills/x-feature-dev/scripts/arch/seal.js --unit=domain:<中心>/<域> --execute。它先核检测零红、本域测试面对当前内容全过(本域代码不在任何测试的被测范围里时如实写 none、不拦)、有标题有说明、日期是今天,都成立才按会话归属写下设计指纹、内容指纹、测试指纹、改动清单与锁清单;别的会话在途的改动保留旧指纹、继续对它的主人报红,无主的改动要 --adopt=路径 才认领。加了新的一版还没封叫「施工中」,收尾、开发流 VERIFY 与封版的检测前置只提示不拦,可以接着改;全量检测与发布不认施工中;施工中照样不许动已封的那一版与它下面的旧版。改动当轮在改的那个文件上报红(引擎内置的版本契约一段);本闸锚在 ARCH.md 上汇总成一条,全量检测看得见。报出的若不是本会话引入的改动(判据同宪法 §六.6;收尾环按写证据机器判归属,见 harness §八),按并行会话隔离铁律跳过。

ARCH-A04域目录必须成套

必须

有 ARCH.md 的域目录同时有同级 CHANGELOG.md。

为什么

日志载体缺了,下一次回看升版时版本记录无处可去,就会被写回文档头(ARCH-A05 防的就是这个)。

怎么做

含 ARCH.md 的目录就是域目录,固定落在「中心/域」两层(见 ARCH-A01),中心目录只做分组、不放文件。新建域目录时两份文件一起建;CHANGELOG.md 的文档头只放 title(以「变更历史」结尾)、unit(domain:中心/域)、kind(changelog),条目分节写成「## v主.次.补 · YYYY-MM-DD · 一句标题」(写法见 ARCH-A09);第一次封版之后同目录多一份锁清单 version-lock.json。

ARCH-A05设计正文与版本日志分居

禁止

ARCH.md 的 frontmatter 出现 version-log 键或已退役的 srcHash 键;CHANGELOG.md 的 frontmatter 出现 describes、srcHash、sourceOfTruth 键。

为什么

日志写回文档头,读设计的人就得先读完历史流水(order 域曾因此让文档头占到全文一半以上);真相源的身份键出现在日志上是两套账。srcHash 在 V2.0.0 退役(代码锁步改由锁清单逐文件记):文档头里再留一份签名,读者会以为它还在起作用。

怎么做

版本记录只追加到同级 CHANGELOG.md;ARCH.md 的文档头里只留当前 version。

ARCH-A06域目录里不放白名单外的东西

禁止

域目录里出现白名单外的任何条目。白名单恰好十一项 —— 文件 ARCH.md(LEVEL A 设计真相源)、CHANGELOG.md(变更历史)、version-lock.json(锁清单,只由统一封版命令写)、README.md(域内导读)、ARCH.html(LEVEL A 阅读视图)、CHANGELOG.html(日志阅读视图),子目录 parts/、adr/、assets/、modules/、tools/。

为什么

白名单外的文件不受任何 arch 闸保护,却坐在真相源旁边,读者分不清哪份算数。名单不是一次定死的:modules/ 曾是业务模块页十节那套写法的标准落点,收 ARCH.html 与 CHANGELOG.html 是承认客户域这个 MVP 当时长出来的形态。2026-09-22 起业务架构换成《架构设计模板》的六个视图(ARCH-B06):parts/ 成了五个视图页的住处;modules/、ARCH.html、CHANGELOG.html 成了旧模板形态 —— 本条仍允许它们存在(还有 14 个域没迁过来),它们的退场由 ARCH-B06 那颗闸管:一个域铺完六个视图,它们就必须删掉。其中 ARCH.html 是手写的第二份叙述、与 ARCH.md 之间一把锁都没有,这处「两套账」随迁到六视图一起消失。

怎么做

视图页放 parts/(只许名册里的那几页,见 ARCH-B06),架构决策记录放 adr/,图与可视化产物(含概念图素材)放 assets/,域内构建器放 tools/;modules/、ARCH.html、CHANGELOG.html 只在还没迁过来的域里留着,新建的域不许再建。确实需要第十二种形态,先走 /x-meta-dev 扩白名单,再落盘 —— 反过来做,就是在用「已经落盘了」逼判据让步。

ARCH-A07每张表恰好归一个域

必须

x-data 的每张表文档恰好被一个域的 describes.data 覆盖(「目录/**」的目录前缀,与代码锁步同一个口径)—— 没有域认领、或两个域同时认领,都不行。立闸当日的存量无主表登记在业务结构名册 x-arch-business-structure.json 的 pending.unowned 里,认领一张划掉一张。

为什么

表不属于任何域,就没有任何一份架构文档替它回答「它是什么、谁能改、改了影响谁」,改它也不会让任何一份设计升版 —— 立闸之前 61 张表里 23 张无主,检测全绿。一张表两个主,就是两本账对同一件事各说各话。ADR-53 否决过「认领闸 + 未认领名册」(担心名册成为第二本账、诱导一个域把所有表都认领),ADR-54 取代了它在数据表上的适用:无主永远从 describes 实时算,名册只是立闸当日存量的豁免清单,新表一出生就受管;「一个域全认领」会与其它域重叠而报红,把子表或关系认领错地方会被 ARCH-A08 的放置臂报红,剩下的只有「主业务编进哪个域」—— 那是业务判断,本闸只判「只有一个主」。

怎么做

新建一张表,同一轮把它所在目录写进该归的那个域的 describes.data;没有合适的域,就先建一个(ARCH.md + CHANGELOG.md)再认领。存量表认领之后,那张表自己的表文档当场报「已经有主了,却还登记」—— 同一轮从名册划掉、把 ceiling.unowned 降到登记数,再跑 /x-meta-dev sync(名册计入 x-arch 判据指纹)。名册只减不增是机器管着的:判据里冻结了立闸当日的存量清单,往名册里加一张不在清单里的表当场报红。一张表只能有一份文档:同名的第二份(哪怕写得是对的)两份都报红;表文档也不许放进检测引擎的忽略目录(那里的文件任何规范都不扫),名册锚一并报。射程只到这里:检测器跑在引擎沙箱里拿不到上一版,所以把某个域的 describes 改窄或删掉一个域的 ARCH.md、让一张表变成无主,要等全量检测扫到那张表时才报。

ARCH-A08子表与关系表写明上级,放在规则算出的那一层

必须

子表(_node / _leaf / _log)在表文档「上游/下游关系」段写一行「- 上级:」加反引号包住的上级表;关系表(_relation)写一行「- 两端:」加反引号包住的两张以上的表。声明的表必须存在且只有一份文档,而且必须是字段表里真实关联的那张 —— 「关联」只认字段设计段表格行里写成「关联 表.字段」的说明,那个字段必须真实存在于那张表(上级是关系表时,那张关系必须已写两端,且它的两端都要在字段里关联到,或直接关联它);关系表的两端必须恰好是字段里关联的全部表(自己跟自己的关系把同一张表写两遍);_relation 表写「上级」时,字段里只许关联这一张表;上级链往上追必须挂到主表或关系表上,不许成环;主表(_base / _dict)不写。放置:子表与上级同域;关系两端同域则与两端同域,两端跨域则归关系域 —— 它的域文档头写 kind: relation 与 relates:(恰好列出两端所在的那几个域),关系域不许拥有主表。

为什么

上级没法从外键推出来 —— 一张子表常常同时引用好几张别的表(用户券同时引用券模板与客户,SKU 维护的字段里一次都没引用供货表),推出来的上级只能是猜的,拿猜的东西立闸必然误报。写出来之后,放在哪一层就是确定的:这正是业务架构标准里的放置规则 —— 关系不挂在任何一个上级下面,挂在两端的最近共同上级下面,于是与两个上级同级。声明必须能在字段里找到对应的关联,是为了让它只是「在已有的事实里选一个」,而不是另写一份说法。跨域关系要有显式的关系域并写明 relates,否则任何一个恰好没有主表的域都能收留它。这些细则大半是立闸当日三路对抗检查逼出来的:关系表把「两端」改写成「上级」就能逃关系域;在字段段里写一句散文、一段注释或代码块就能伪造关联;脚手架把所有外键都记在上级名下,伪造的关联连看都不用看 —— 每一种都实测打穿过,现在钉在床里必红。上级或某一端还没有唯一的主时直接报红,而不是静默跳过:静默会让名册的豁免外溢到新表身上。

怎么做

写表文档时,把声明写在「上游/下游关系」段(写在别的段、注释或代码块里都不算数;冒号全角半角都认、标签可加粗、表名写在下一级缩进 bullet 里也认;表名必须用反引号包住,只认带六种后缀的表名,别的反引号注释不影响)。外键字段的说明写成「关联 表.字段」,「关联」二字紧挨着「表.字段」(中间只许空白、冒号与反引号);一个外键指向好几张表(多态,按前缀区分)时每个去向各写一次,如「关联 supplier_base.supplierId 或关联 brand_base.brandId」—— 只写一次「关联」、后面接「OR 表.字段」的那个去向不算。同一格里「同 / 取 / 快照自 / 引用 表.字段」只是提及,不算关联:快照来源、求和对账口径这类说明照写,不会被算成上级或关系的一端(V1.18.0 之前判据把任何提及都算关联,购物车、收藏、足迹三张关系表会因为快照来源被逼着把商品与供给单元写成第三、第四端)。用脚手架建表时,指向上级的外键只写字段名,指向别的表的写成「字段名:表名」,脚手架会各自写对。_relation 表只有一端是表的(另一端是代码里定义的东西),写「上级」按子业务算。存量没写的表登记在 pending.undeclared,审查到那一域时逐张补写、逐张划掉 —— 名册只豁免「没写」,写错了照样报;写好之后表文档当场报「同批从名册划掉」,划掉后跑 /x-meta-dev sync。挪动或改名一张上级表,让没动过的子表失配,增量检测看不见,要等全量检测。报错会指明是哪一臂,并写明改哪个文件。

ARCH-A09业务域的版本号、变更历史与锁清单三处锁步

必须

ARCH.md 的 version 等于同级 CHANGELOG.md 第一节的版本;变更历史的文档头只放 title(以「变更历史」结尾)、unit(domain:中心/域)、kind(changelog);每个二级标题都是一版,写成「## v主.次.补 · YYYY-MM-DD · 一句标题」(统一写法之前的旧条目可以没有标题),新的在最上面、版本严格变小、日期不倒挂、一次只升一步(升了哪一位,后面的位归零);统一之后的每一版都有标题、有说明;第一节已封版(由统一封版命令写下设计指纹、内容指纹、测试指纹与改动清单),锁清单 version-lock.json 与第一节一致,并钉住这一版到文件末尾的整段历史(封过的一版与它下面的旧版一个字都不能改,v4.2.0)。

为什么

版本号是「这份设计回看到哪一版」的唯一标记,变更历史是它的账,锁清单是它封下的那一份。V2.0.0 之前三层各有一套:系统规范域写「## V… · 日期」加判据指纹,业务域写「## v… — 日期」加代码指纹,整个 HARNESS 又是另一套封版清单 —— 同一件事三种写法、五套解析,页面也长得各不一样(用户 2026-09-28 发现后拍板统一)。现在三层同一种写法、同一份判定代码(检测引擎的版本契约)、同一个封版命令流程;本闸只是业务域那一层的薄壳,写法错、版本对不上、没封、锁清单被手改,都在这里报。V1.13.0 立闸时 15 个域里 11 个对不上、存量豁免在名册里;统一写法迁入后二十一个域全部锁步,名册同批退役。

怎么做

升版时在变更历史最上面加这一版(标题一句话、正文写清改了什么与回看结论),ARCH.md 的 version 改成同一个,再跑 ARCH-A03 那条封版命令 —— 三行指纹、改动清单与锁清单只由它写,手写或手改的记录行收尾复核认不出来(封版记录住守卫的台账);封过的一版一个字都不能改(日期、标题说明、测试行都记在锁清单里),封了版又改就再加一版;封版日期只能是今天。升哪一位:改写既有契约升第一位;新增一类东西(闸、视图、工作流、表、云函数)升第二位;订正、或设计内容没变只改写法升第三位。闸只判写法、相等与封版,判不了条目写得是否属实。

ARCH-A10业务总览同样锁步;不归任何域的业务代码只减不增

必须

业务总览(跨域关系图 _context-map.md 与业务架构注册表 _index.md)是一个单元,版本号写在关系图文档头,变更历史是 .claude/arch/business/CHANGELOG.md,写法、版本、封版与业务域完全相同(ARCH-A09),改了关系图或注册表就要加新的一版并封版。业务代码(四端与内核母本顶层目录下、按端取的文件:数据表的 datasource、云函数与移动端的 js 与 wxml、后台的 ts 与 tsx;依赖、构建与装配产物、自动生成的文件、测试根与部署门登记过的床不算)必须归某个业务域;业务总览的锁清单另记业务域名册,新增、删掉一个业务域都要它升版封版(HARNESS v4.2.0);业务总览、x-arch 与整个 HARNESS 自己不许消失(本机台账封过却从磁盘上找不到即红,v4.3.0);立闸当日不归任何域的冻结在业务总览的锁清单里,此后只减不增 —— 新出现一个不归任何域的业务代码文件即红。

为什么

关系图的日志此前写在它自己的文档头里(version-log),是唯一一份没有变更历史的业务文档,也不受任何锁步;搬出来之后它与二十一个域同一套规矩。无主的业务代码没有设计版本:它改了不会让任何一份设计升版,也没有任何一份文档替它回答「它是什么、改了影响谁」。立闸当日约一千个文件无主(后台公共组件、语言包、各端系统层、内核),一次全部归位等于一次全仓重新分域,而「新的必须有主」今天就能守住;所以冻结存量、只减不增,存量在逐域回归时一个个归位。基线住锁清单而不住一份人能改的名册,是因为「只减不增」要由机器保证:只有封版命令能写它,而封版命令拒绝把本会话新添的无主代码冻进去。

怎么做

新建业务代码之前先想清它归哪个域,同一轮写进那个域设计文档头的 describes(那个域随之升版并封版);没有合适的域就先建一个。改了关系图或注册表,在 .claude/arch/business/CHANGELOG.md 最上面加新的一版、关系图文档头的 version 改成同一个,封版:node .claude/skills/x-feature-dev/scripts/arch/seal.js --unit=business:overview --execute(已归位或已删掉的无主代码在这一步自动从基线划掉)。闸只判「有没有域认领」,判不了认领得对不对;改动当轮在新文件上报红(引擎内置的版本契约一段),全量检测锚在业务总览的变更历史上整仓看一遍。

ARCH-B01系统规范与系统架构目录一一对应

必须

references 下每份规范(元规范 x-standard 除外)要么已迁成系统四件套,即有 arch/system/规范名/ARCH.html 与 CHANGELOG.md、规则书是条款书;要么登记在系统组注册表 x-arch-system.json 的迁移名册里。arch/system/ 下每个目录名都有同名规范,目录里只放 ARCH.html、CHANGELOG.md、锁清单 version-lock.json(只由统一封版命令写)与 assets/,根下不放文件;名册按名称排序、不重复,登记数等于 ceiling。

为什么

设计件与判据一一对应,每份规范才都有地方写设计理由,每份设计也都有判据可锁。名册只减不增,迁移只会往前走,新规范不会悄悄绕开四件套。

怎么做

新建规范用 /x-meta-dev 的 tetrad 一次建整套,不进名册。迁一份旧规范:tetrad 建目录,按条款书格式改写规则书,写架构页原件与测试床点名,从名册划掉它并同批降 ceiling(名册计入 x-arch 判据,x-arch 同批升版),最后 sync 刷新派生区、用统一封版命令封版。

ARCH-B02架构页派生区只准引擎产出

禁止

直接改架构页的派生区,包括外壳样式与脚本(带 data-x-derived 的 style、script)、页头、条款总表、判据总表、面板与普查(x-derived 元素)。

为什么

派生区从条款书、判据与注册表机械算出,手改一处就与来源分叉。每个区带输出版本、产出指纹与来源指纹:直接改了指纹对不上,来源变了戳记过期,引擎改了输出而页面没刷新版本号也对不上。

怎么做

改原件(条款书、判据、注册表、assets/ 里的图)后跑 node .claude/skills/x-meta-dev/scripts/meta.js --action=sync --spec=规范名 --execute;普查快照要刷新时加 --census --date=YYYY-MM-DD。派生区以外的原件区照常直接写。

ARCH-B03版本号只写一处,变更历史与锁清单与它锁步

必须

版本号只写在规范简介一处;CHANGELOG.md 的文档头只放 title(以「变更历史」结尾)、unit(spec:规范名)、kind(changelog);每个二级标题写成「## v主.次.补 · YYYY-MM-DD · 一句标题」(统一写法之前的旧条目可以没有标题),新的在最上面、版本严格变小、一次只升一步、日期不倒挂,统一之后的每一版有标题、有说明;第一节等于规范简介版本,提交前已封版,锁清单 version-lock.json 与第一节一致并钉住这一版到文件末尾的整段历史(封过的一版与它下面的旧版一个字都不能改);x-arch 自己的锁清单另记系统规范域名册;封版之后判据(正文与同前缀注册表)、条款书的条款、架构页的原件改过而没升版即红(派生区与文档头不算)。

为什么

版本号写在多处必然漂。封版把「这一版的设计与判据长什么样」逐个文件钉进锁清单,此后改了哪个文件就在哪个文件上报红;封版命令同时写出改动清单,页面能直接回答「这一版改了什么」。V2.0.0 之前这里只锁判据(一个判据指纹),条款与架构页原件改了不留痕,而且封过的一版能被 sync --seal 重封、改写测试指纹;现在三层同一份版本契约、同一个封版命令,封了就钉死。

怎么做

改判据、条款或架构页原件时,规范简介升版本,变更历史最上面加新的一版(写标题与说明);施工中跑 sync 刷新派生区(sync 只刷新、从不封版);本版写完用统一封版命令封版:node .claude/skills/x-meta-dev/scripts/meta.js --action=seal --unit=spec:规范名 --execute —— 它先刷新派生区,核检测零红(增量检测、规范自测 -t、结构验证 -v)与测试全过,再按会话归属写三行指纹、改动清单与锁清单,封完再刷新一次派生区(页头「变更历史最新」一格变成已封版)。三行指纹与锁清单禁止手改;封过的一版不能重封。

ARCH-B04架构页原件写完,测试床点名属实

必须

架构页原件区不残留骨架占位符;每颗闸都出现在测试床点名里,有床写床的路径,没有床写「待补床」;点名引用的「规范名:规则号」真实存在,点名引用的「规范名:ARCH-条款号」在该规范的条款书里真实存在;点名的床位于测试根(x-test/、.claude/skills/x-<技能>/tests/、.claude/hooks/tests/;以引擎常量 constants/test-roots.js 为准,判据不另抄一份)、真实存在,内文写着它守的每个「规范名:规则号」与「规范名:ARCH-条款号」;被 HTML 注释包住的点名不算数,床里的「规范名:编号」要写完整编号(在四位编号后面多写一位数字的加长写法,不算写了原编号),点名的床不许住在唯一运行器不收床的目录里(夹具、依赖、以「.」或「zz」开头);床的种类要写实 —— 跑本规范判据的床不写 data-bed-kind,床文件剥掉注释后就必须按调用形态出现引擎令牌(调用 extractNsRuleDetector(、buildDetectorTools(、checkStandardFormat( 之一,或把 check.js 作为路径段写出,或在注释以外写出 X-RULE-BEGIN-SLOT),守不变量、不跑判据的床写 data-bed-kind="invariant";两者都不是的点名判红。

为什么

骨架没写完的架构页只是空壳。点名让每颗闸的验证追得到具体测试床,待补床在页面上标红,债务一眼可见;床里写明闸号,防止随手点一张不相干的床充数。床的种类必须写实,是因为 V1.3.0 之前这颗闸只证「床存在、写了闸号」,一行头注即满足 —— 于是守不变量却不跑判据的床(资损域回归床、装配对拍床)可以合法登记为「守这颗闸」,页面上的「已登记床」比它字面承诺的弱一档,读的人分不出哪些床真跑过判据(令牌因此按剥掉注释后的调用形态认,否则注释里一句 check.js、一个恰好含这段文字的文件名 access-check.js 都能充数);条款号进点名是因为无机器闸的条款里有一批实际由床承接(逐字等值断言、导出面锁),此前无处登记。V1.19.0 堵的三处都是「点名在、床却不算数」:注释掉的点名读者看不见却照样过闸;加长编号能冒充;住在夹具目录里的床永远不会被唯一运行器跑到,而封版前置要求点名的床对当前内容全过,登记一张跑不到的床会让那颗闸永远封不了版、或者让人以为它测过。

怎么做

在架构页「测试床」一节,每张床写一个带 data-bed 与 data-guards 属性的列表项,例如:

  <li data-bed=".claude/skills/x-spec-checker/tests/x-arch/tetrad-arch-gates.test.js" data-guards="x-arch:NS-COMMON-0007 x-arch:NS-COMMON-0008">这张床测什么</li>
  <li data-bed="x-test/functions/refund-order-update/refund-order-update.test.js" data-guards="x-api:NS-SERVER-0141 x-api:ARCH-F04" data-bed-kind="invariant">守锁配对与双分支逐字等值,不跑判据</li>

床文件头注释写「本床守护:x-arch:NS-COMMON-0007 x-arch:NS-COMMON-0008」(条款号同样写进去)。判据床用 require 引擎的 scanners 取 extractNsRuleDetector 喂样本,或调引擎真 STD 执行器 checkStandardFormat,或直接跑 check.js,或手抠判据的 X-RULE-BEGIN-SLOT 块再经 buildDetectorTools 喂 tools 跑(都算真跑判据);闸只认注释以外的调用形态,头注里提一句不算,调用经别名改名(const { extractNsRuleDetector: ext } = … 后只写 ext()它也认不出。只守不变量的床把 data-bed-kind="invariant" 写在点名上,不要为了显得「真跑了」去凑一次无意义的引擎调用。

ARCH-B05架构页按同一套标准长,机器看得见的那一面由名册强制

必须

系统架构页遵循《系统架构标准》可机判的那一面 —— 节只取自标准名册且顺序与名册一致、必填节齐全(s-census 与 s-ops 是条件节,不适用的域不建)、每节带 data-index 与 data-kicker 编号属性、页面挂共用表达层(body 带页面类、head 引共用样式表)。判定依据是名册 x-arch-standard.json,散文版住 .claude/arch/standards/system-architecture-standard.html,两者的关系与条款书和判据相同。

为什么

标准立起来之后,「按它长成一个样」这件事此前零机器强制 —— 实测过:一份还是旧骨架、没有任何编号属性、没挂表达层的架构页,四颗架构闸跑下来十项全过。于是三十多页可以各长各的而报表全绿,跨域对比失效,读者每翻一页都要重新学一遍这一页的结构。名册只收可判的形态(节、属性、引用),不碰「写得对不对」;标准里「不许发明第二套设计语言」「整页只有一种底色」这类要求判据够不着,仍由写页时读标准与人审兜底。名册里的 pending 是棘轮:立闸当轮把尚未改造的域全部登记进去整条静默,否则所有架构页同时爆红、一页也改不动。

怎么做

改造一页 → 从 pending 划掉它并把 ceiling 降到登记数 → x-arch 升版、跑 sync 刷新派生区、用统一封版命令封版(名册同前缀,计入 x-arch 判据)→ 对那一页跑本规范扫描验零。新建的规范直接按标准写,不进名册。节的顺序与必填态改动属于改标准:先改散文版说清为什么,再改名册,两者同一轮。

ARCH-B06业务域按架构设计模板写成七个视图,机器看得见的那一面由名册强制

必须

每个业务域按《架构设计模板》写成七个视图 —— 架构设计、流程设计、前端设计、服务设计、数据设计、测试设计六页住域目录的 parts/(文件名 architecture.html / flow.html / frontend.html / service.html / data.html / test.html),第七个「变更历史」就是域的 CHANGELOG.md。每一页的节只取自该视图的名册且顺序一致、必填节齐全;流程设计至少一个 scene-… 场景,每个场景先有流程图(带 SVG 的 bv-figure)、后有分步操作(bv-step);前端设计至少一屏 screen-…;测试设计写明谁在测本域的代码、每个服务有没有自己的测试、哪里测不到,并在底部登记本视图的异常;body 带页面类 bv-body,前两份样式表依次是共用底座 .claude/arch/assets/business-module.css 与视图画法 .claude/arch/assets/business-views.css。铺完全部视图的域,旧模板的形态(modules/、ARCH.html、CHANGELOG.html)同批删掉。判定依据是名册 x-arch-design-template.json,散文版住 .claude/arch/standards/architecture-design-template.html,两者的关系与条款书和判据相同。

为什么

业务架构要回答的是「这个域是什么、怎么用、怎么实现、数据长什么样、改过什么」,读者是不懂技术的决策者与要动手的开发者两种人。旧写法按模块切页、每页十节,一个域的内容散在几页里、每页又从头讲一遍契约与语境;2026-09-22 用户以菜单域为样板拍板改成六个视图 —— 组织单位从模块换成域,一个域点开就是六个页签。流程设计的形态是这套模板的核心:用户原话要的是「先画出流程图,再展示这个流程是如何操作的 —— 点 PC 端还是移动端哪个页面的什么东西、弹出一个框、然后做什么」,所以「每个场景先流程图、后分步操作」进了判据,顺序也判;没有它,流程设计会退化成一段散文加一张截图。旧名册(业务模块页十节)同批退役,因为两种写法并存就是两套账 —— 十节的内容全部有去处,映射写在模板散文里。测试设计是 2026-09-24 用户拍板加的第七个视图:宪法测试闭环要求「测试守不到的地方必须在设计里写明」,此前业务域没有地方写这件事 —— 测试事实散在服务设计的备注与变更历史的测试指纹里,读者回答不了「这个域谁在测、哪里测不到」。每个视图自己的问题登在自己那一页的底部,不另建全局问题清单:问题跟着它所在的设计走,复盘哪个域就看哪个域。样式表按落点判,不按字面:各域深浅不同,同一个共用文件写出来的相对路径不一样;文件名对了而落点在自己域里(复制了一份)也不算。底座在前、画法在后、域内私有样式只能接在两者之后,是为了让私有样式覆盖得了共用层,而共用层之间的覆盖顺序固定。棘轮:立闸当日另外 14 个域还没铺成六个视图,登记在名册 pending 里,「缺视图」「旧形态还在」两臂对它们静默 —— 但视图页本身不豁免,哪个域开始写视图页,那一页一出生就按模板判。

怎么做

新建或改写一个域的视图,照模板散文的骨架写六页(节的 id 以名册为准,不以记忆为准;测试设计的事实从本域文档头的 describes、测试面判定与部署门注册表派生,不凭印象写),画图用共用画法里的节点、连线与泳道样式,界面高保真照抄真实代码与语言包的文案;<head> 前两行样式表引共用底座与画法(按本页到 .claude/arch/assets/ 的真实相对路径写)。内容搬完后删掉本域的 modules/、ARCH.html、CHANGELOG.html,ARCH.md 里的模块索引换成全部视图的索引;这个域的 ARCH.md 当场报「同批划掉」时,从 pending 划掉它、把 ceiling 降到登记数,跑 /x-meta-dev sync(名册同前缀,计入 x-arch 判据指纹)。本域的版本照 ARCH-A09 升一版并记账,用 ARCH-A03 那条封版命令封版 —— 代码没变的一版,封版命令写出的改动清单里代码一栏就是 0 个,读变更历史的人一眼看得出这一版只改了设计。

ARCH-C01两个目录各归一个执行者写

必须

arch/business/** 由 x-architect 在开发流收尾的 ARCH-SYNC 里撰写;arch/system/**、规则书与规范由 x-meta-governor 经 /x-meta-dev 撰写;开发流不写 arch/system/。

为什么

业务架构跟着代码走,在开发流收尾回看;系统架构跟着判据走,改它就是改治理,要过升版与封版。混着写,一个改动就能同时躲开两个环的把关。

怎么做

开发中发现系统规范或它的设计要改,回头触发 /x-meta-dev;改了业务域代码,在收尾派 x-architect 回看对应域文档。

守护

无机器闸:分工类(检测器只看文件内容,判不了是哪个执行者、经哪条流程写的,由工作流派发与提交审查把关)

速查

<!-- X-DERIVED-BEGIN 速查 from="x-arch-system.json" view="kv" -->

键值
说明x-arch 系统组注册表(判据的一部分:同前缀注册表计入 x-arch 判据指纹,改它走 /x-meta-dev sync 升版)。pending = 迁移名册:还没迁成系统四件套的规范(元规范 x-standard 除外,其设计留在 harness)。名册只减不增 —— 迁完一份就划掉一份,同批把 ceiling 降到登记数;新建的规范直接走 /x-meta-dev tetrad 建整套,不进名册。本文件同时是成套闸 NS-COMMON-0007 与版本锁步闸 NS-COMMON-0009 的全局锚点,名册清空后也保留。
ceiling0
pending

<!-- X-DERIVED-END 速查 -->

验证

node .claude/skills/x-spec-checker/scripts/check-spec/check.js -v x-arch
node .claude/skills/x-spec-checker/scripts/check-spec/check.js -m x-arch .claude
node .claude/skills/x-meta-dev/scripts/meta.js --action=validate --spec=x-arch