HARNESS ARCHITECTURE · ARCHITECTURE OPERATING SYSTEM

让架构从原则出发,在运行事实中闭环

Harness架构不是业务架构,也不是某个系统的设计。它是承载业务意图、约束系统实现、生产架构制品并执行治理规则的架构操作系统。

6
层控制系统
从原则到工程实体
13
个模板模块
可裁剪、可复用
2
个裁判
检测读代码 · 测试跑代码
HARNESS 版本— 大版本 —
最近一次—
版本住在.claude/harness-engineering.md 文首一行
全部版本在「版本」页签看 →
意图进入控制面,L0–L4 共同作用于 L5;运行事实沿证据链返回。
CONTROL控制面
  1. L0宪法定义使命、边界与不可违反的原则
  2. L1元治理管规范、规则、四件套与工作流自身的生命周期
  3. L2工作流定义从需求到落地的标准流程向导(教你写对)
  4. L3规范能力判据 · 条款 · 检测引擎 · 生成器
L5 · REALITY工程实体

代码、制品、环境与真实运行行为

L4 · MUST强制 · 守卫
传感器(写错就拦)

写前拦截 · 收尾逼修 · 部署门 · 按内容记账

两个裁判

检测 · 读代码判「写得合不合规」。
测试 · 跑代码判「行为对不对」。
FRAMEWORK OVERVIEW

框架全景

定义方向 · 组织生产 · 验证执行 · 反馈演进

  1. 01

    定义方向

    明确为什么做、做什么、建立原则、约束与边界。

    输入
    业务战略 · 外部环境
    机制
    宪法 · 价值主张
    输出
    架构方向 · 决策准则
  2. 02

    组织生产

    把方向转化为可落地、可复用的系统与架构制品。

    输入
    架构方向 · 业务需求
    机制
    工作流 · 模板 · 生成
    输出
    系统 ARCH · 规则资产
  3. 03

    验证执行

    通过自动化与门禁确保设计承诺进入真实工程。

    输入
    系统与制品 · 变更请求
    机制
    裁判 · Guard · 门禁
    输出
    合规证据 · 发布结论
  4. 04

    反馈演进

    基于事实持续改进,让架构在真实世界中成长。

    输入
    运行数据 · 质量反馈
    机制
    度量 · 复盘 · 演进规划
    输出
    改进建议 · 新版模板
UNIFIED MODEL · TETRAD + TWO JUDGES

统一模型:四件套定规矩,两个裁判判对错

每个规范域由设计、条款、判据、执法四件组成;判断对错的只有两个裁判 —— 检测读代码,测试跑代码。执法不是第三个裁判,它在四个关口把两个裁判一起叫来。本页后面各节,都是这个模型的展开。

01

设计

WHY

为什么这样定,哪里守不到。

架构页 · 框架自身写在架构详图
02

条款

MUST

必须什么、禁止什么、为什么;每一条都点名守护它的闸。

规则书(条款书)
03

判据

HOW TO JUDGE

怎么判:唯一标准写法加禁止项,检测器就写在判据里。

规范 · 内嵌检测器
04

执法

WHEN

在哪一刻把裁判叫来,裁判说不过时怎么办。

守卫 · 工作流 · 定版脚本 · 发布出口

条款与判据双向对齐派生部分按内容指纹锁步,判据一变,条款与设计必须跟上框架三件套同构:治理别人,也治理自己

裁判一x-spec-checker

检测 · 读代码

判「写得合不合规」。

  • 语言层:编译检查,引擎自带,不依赖任何判据
  • 规范层:各规范的判据与检测器
  • 结论记作「这份内容查过是干净的」;判据或检测引擎一变,结论作废
两个裁判同构
  1. 都按内容记结论
  2. 依据一变,旧结论作废
  3. 工具没跑、判定出错、跳过,都不算过
  4. 三层封版与发布,检测与测试两个都要过
裁判二x-harness-dev

测试 · 跑代码

判「行为对不对」。

  • 测试床由唯一运行器跑,按张记账
  • 云函数另有部署门入口,发布时当场真跑
  • 结论记作「这张床对这份内容跑过、过了」;被测对象、床、夹具或运行器一变,结论作废
  1. 01开发中向导

    一条命令同时叫两个裁判,没过就回去改。

    L2 · 工作流核对
  2. 02收尾反馈

    每轮一次,检测与测试两栏分开报;说不清就拦。

    L4 · 收尾逼修
  3. 03定版墙

    三层同一个封版命令:检测与测试都过才钉;本单元的代码没有测试覆盖,如实写 none。

    L1 · L2
  4. 04发布墙

    经本体系的发布出口当场真跑,不认旧记录;传上去的必须就是测过的那一份。小程序包由开发者工具上传,不经这里。

    L2 · L4 · L5

写入那一刻另有写前拦截(L4):挡越权写入与改坏规矩本身的写法;云端发布的部署门也挂在它上面,读检测结论、叫测试当场跑。写前拦截被摘下(开闸)时,这些一并不在岗,六层体检会把这一项报红。

JUDGES ARE JUDGED

裁判也被裁判

  1. 检测器由判据床守着;编译检查由它自己的反例床守着
  2. 测试床由空壳对照守着:新建或改过的床,把被测对象换成空壳再跑,床必须变红;已有的老床不追溯,个别确实做不了的逐张登记
  3. 空壳对照与判定模块由它们自己的床守着
  4. 最底层守卫、运行器、判定模块的床由收尾逼着跑,改它们的人亲眼看见红绿

证明不了的两个裁判都过,只证明「对当前内容查过、跑过、咬得住」,证明不了判据写得全、测试测得全 —— 测试守不到的地方,必须写进设计。

还没到的地方后台、端上的业务模块、官网和数据表文档目前没有测试,那里只有检测一个裁判,发布时也只有检测把关;宪法、元规则、架构详图这类文字同样只有检测看着。

六层控制系统,不是六层技术栈

L0–L4 不是具体的技术实现,而是从原则到强制的架构控制层,共同作用于 L5,确保架构能够被生产、执行、验证与持续演进。

  1. 01

    定向 / ORIENT

    定义为什么做,划定边界与治理主体

    L0WHY
    L0

    宪法

    回答
    我们为何存在,边界是什么
    真相源
    业务目标与技术原则
    机制
    约束、红线与例外机制
    产出
    架构宪法
    L1META
    L1

    元治理

    回答
    规矩本身怎么立、怎么改
    真相源
    元规范与元规则
    机制
    改判据先升版,派生部分锁步刷新,封版前两个裁判都过
    产出
    封了版的规范与条款书
  2. 02

    生产 / PRODUCE

    定义如何落地,从意图走向可交付

    L2HOW
    L2

    工作流

    回答
    如何从需求走向交付
    真相源
    架构需求识别
    机制
    设计、评审、验证与发布
    产出
    标准工作流
    L3WHAT
    L3

    规范能力

    回答
    用什么标准与能力构建
    真相源
    规范、条款与判据
    机制
    模板、生成器与检测引擎
    产出
    规范能力与制品模板
  3. 03

    兑现 / REALIZE

    通过强制确保验证,用事实驱动持续演进

    L4MUST
    L4

    强制

    回答
    如何确保必须执行
    真相源
    守卫、检测与阻断
    机制
    在收尾、发布等关口把检测与测试一起叫来
    产出
    两个裁判的结论与阻断
    L5REALITY
    L5

    工程实体

    回答
    最终交付什么
    真相源
    代码、制品、环境与运行事实
    机制
    产品、服务与基础设施
    产出
    可运行系统与业务结果

方向决定生产,生产接受强制,事实驱动演进。

TRUTH SOURCE MODEL

真相源分工:不让同一个事实拥有两个主人

框架负责定义“如何治理”,各层只拥有自己的事实;其他呈现必须引用或生成,不能复制成第二份可编辑真相。

01

原则真相

L0 · WHY

回答为什么存在、哪些边界不可突破。

宪法 · 价值主张 · 基本约束
02

治理真相

L1–L2 · META / HOW

回答规矩怎么立、怎么改,事情按什么路径做完。

元规范 · 元规则 · 工作流 · 决策记录
03

规范真相

L3 · WHAT

回答正确的结构、行为与质量标准是什么。

模板 · 条款 · 判据 · 能力清单
04

事实真相

L4–L5 · EVIDENCE

回答实际执行了什么、结果是否满足承诺。

检查结果 · 运行事实 · 版本证据

原创区由该层直接维护,是唯一可编辑入口。

派生区由工具从真相源生成,只读展示,不承载新事实。

锁步封版版本、指纹与验证结论一起推进,避免半更新状态。

GOVERNANCE TOPOLOGY

治理拓扑:工具独立于被治理材料

框架负责操作架构制品,但不能依赖任何一个被治理系统才能成立。

PART 1 · 框架三件套元规范 + 元规则 + 守卫;设计写在架构详图,自身闭环运转
条款元规则
判据元规范
执法守卫
自己也被两个裁判看着:脚本有床,文字只有检测
操作,
但不依赖
下发控制工具操作 返回证据不影响成立
PART 2 · 系统四件套每个系统规范域一套,接受框架的操作与约束
设计架构页
条款条款书
判据内嵌检测器
执法守卫等
四个关口
业务架构 · 以代码为锚 · 不设四件套按业务需要组织,与系统架构保持清晰分界。

开发闭环

从业务意图到架构同步,形成可验证的实现闭环。

  1. 业务意图
  2. 设计
  3. 实施
  4. 检测 + 测试
  5. 架构同步
共用两个裁判检测 x-spec-checker测试 x-harness-dev

治理闭环

从规范变化到封版,形成可持续的治理闭环。

  1. 规范变化
  2. 规则同步
  3. 派生生成
  4. 检测 + 测试
  5. 封版
架构结论

工具不能被材料反向绑架。

框架通过自身的控制面与裁判能力操作各类被治理架构制品;其成立不依赖任何一个具体业务系统,因此保持可迁移、可复用、可持续。

EXECUTION & VERIFICATION

执行与验证:把架构承诺变成机器事实

模板只解决“如何描述”,执行链解决“如何兑现”。HARNESS 用生成、裁判、门禁和证据四类能力,把设计约束带入每一次工程变更。

01PRODUCE

x-meta-dev

将模板、参数和规范能力编排为结构一致的架构制品。

  • 选择适用模板
  • 注入系统上下文
  • 生成原创区骨架与派生区
输出:可审查的初始制品
02JUDGE

两个裁判

检测(x-spec-checker)读代码判写法,测试(x-harness-dev)跑代码判行为;开发与治理两个闭环共用。

  • 检测:语言层 + 规范层
  • 测试:唯一运行器,按张记账
  • 空壳对照证明测试咬得住
输出:按内容记账的两份结论
03ENFORCE

执法 · 四个关口

开发中由工作流叫、收尾由守卫叫、定版由统一封版命令叫、发布由发布出口与部署门叫;写入那一刻另有守卫的写前拦截。

  • 写前拦截与云端写入的事后复判
  • 收尾两栏分开报、说不清就拦
  • 三层封版两个都卡,发布当场真跑
输出:可执行的允许或阻断
04PROVE

证据与封版

将版本、指纹、两个裁判的结论与处置记录归集为可追溯证据。

  • 版本锁步:三行指纹、锁清单与改动清单
  • 结果归档与问题清单
  • 复盘输入与演进触发
输出:可复核的发布事实
设计承诺生成制品两个裁判门禁执行证据封版任何阶段失败,都不能把“希望如此”冒充为“事实如此”。
VERSION DESIGN

版本设计:一个总版本,各域各管自己

整个 HARNESS 有一个总版本,就是框架设计的版本,在顶部「版本」页签按大版本、小版本展开。业务架构、系统架构里每个域各有自己的版本与变更历史。每个版本号只写在一个地方,页面和别的文件都从那里读;两处对不上,就是错。三层用同一份版本契约:同一种写法、同一份判定代码、同一个封版命令。

01

整个 HARNESS

= 框架设计
当前
—
版本住在
架构详图文首一行 .claude/harness-engineering.md
变更历史
.claude/harness/CHANGELOG.md,每版一节「v主.次.补 · 日期 · 一句标题」、新的在最上面,封版时写下设计、内容、测试三行指纹与改动清单;「版本」页签按大版本、小版本展开
什么时候升
框架的设计(架构详图、宪法、决策记录、没有系统架构目录的规则书、自研技能的说明与参考文档;执行体文件归 Agent 架构的单元,不在其内)或代码(守卫、各自研技能的脚本与模板资产、元规范与引擎文档、部署门入口与空壳对照)改了、新增或删掉任何文件就升:改写既有契约升第一位;新增一类东西(闸、视图、工作流、表、云函数)升第二位;订正、或设计内容没变只改写法升第三位;一次只升一步,升了哪一位后面的位归零
谁锁着
版本契约,框架自己判:改动当轮收尾在改的那个文件上报红;封版前检测与测试都要过;每条发布通道(部署门、云函数脚本出口、静态站点发布准备)同一套比对,整体核全部单元、逐版核封版记录。守卫另留一段不经契约代码的框架锁比对,契约代码被改松时,锁住的框架文件被改或删掉仍看得见;封版记录另记一份在守卫台账里
02

系统规范域

每个 x-* 一份
在哪看
系统架构 → 规范页头部与「变更历史」
版本住在
判据标题一处;条款书与架构页头部从它派生
变更历史
各域 CHANGELOG.md,与整个 HARNESS 同一种写法:每版三行指纹与改动清单
什么时候升
判据、同前缀注册表、条款或架构页原件一改就升
谁锁着
同一份版本契约:改动当轮收尾红;封版前检测、判据自测与规范验证、测试都要过;发布前整体比对
03

业务域

每个 中心/域 一份
在哪看
业务架构 → 域页「变更历史」
版本住在
域设计文档头 ARCH.md 的 version 一行
变更历史
各域 CHANGELOG.md,与另外两层同一种写法:每版三行指纹与改动清单
什么时候升
本域的设计文件,或它认领的数据表、云函数、前端代码一改,就回看设计、升版
谁锁着
同一份版本契约:改了代码或设计当轮收尾红;封版前检测与本域测试都要过;发布前整体比对。不归任何域的业务代码冻结在业务总览里,只减不增

三者的关系各域的版本变,不带动整个 HARNESS 的版本;整个 HARNESS 只在框架本身变的时候升。否则每改一次业务,总版本就要升一次,真正改框架的那几版会被淹没。不是设计、但带版本号的东西(云函数内核、移动端母本包、微信基础库、后台组件库)各自只写一处,在「版本」页签里列着。

机器管不了的升第几位要看改动的性质,机器判不了;机器保证的是必须升、一次只升一步、两处一致、封过的一版与它下面的旧版一个字不能改。有人故意写脚本去改守卫保护的台账,拦不住,但会话记录与改动记录里都看得见。

TEMPLATE AS A FRAMEWORK CAPABILITY

架构模板属于框架的制品能力

模板不是另一类架构。它由框架拥有,被系统架构实例化,并由验证制品链持续校验。模板负责统一思考结构,而不替任何系统预写答案。

Harness架构拥有方法与模板定义模块、裁剪规则、生成能力与质量门槛
系统架构负责领域化实例基于真实边界、风险与运行条件完成 ARCH
验证制品链负责验证和证据让架构页、条款、判据、变更历史与测试床锁步闭环

架构制品生产线

从关注点进入,经过模板、生成、实例化和机器验证,最终形成可复核的演进证据。

  1. 01架构关注点
    • 业务目标
    • 质量属性
    • 约束与边界
    • 利益相关者
  2. 0213 模块模板
    01视角与范围
    02结构视图
    03运行时视图
    04决策与权衡
    05验证与证据
    06演进路线

    VIEWS → DECISIONS → EVIDENCE → EVOLUTION

  3. 03x-meta-dev 生成
    • 模板解析
    • 参数注入
    • 结构化生成
    • 一致性检查
  4. 04系统 ARCH.html
    • 领域化架构
    • 多视图文档
    • 可导航输出
    • 版本与追溯
  5. 05条款 · 判据 · 裁判 · 执法
    • 架构条款
    • 合规判据
    • 检测与测试
    • 执法与阻断
  6. 06证据与演进
    • 证据归集
    • 度量分析
    • 演进建议
    • 持续改进

十三个模块,一条证据链

模块覆盖从架构驱动力到验证演进的完整判断链;完整不等于全部展开。

  1. 01–02定位与边界定位 · 范围

    先回答为什么存在,以及系统内外的责任分界。

  2. 03–05驱动力与上下文质量 · 上下文 · 策略

    把干系人关注点、外部关系和总体解法连接起来。

  3. 06–09设计与运行视图结构 · 运行 · 数据 · 部署

    分别表达静态组成、动态协作、状态与真实运行环境。

  4. 10–11横切与决策横切 · 决策

    记录跨构件机制,以及昂贵、难逆和有争议的取舍。

  5. 12–13证据与演进验证 · 演进

    让承诺可验证,让风险、债务和下一步行动可追溯。

TAILORING RULE

按风险裁剪,不按目录填空

  1. 01识别本系统真正的架构驱动力与高风险场景。
  2. 02选择能回答这些关注点的视图和模块。
  3. 03合并或裁掉低风险模块,并记录裁剪理由。
  4. 04每项关键承诺必须追溯到判据、证据或明确的人工判断。

一个能力,三个角色

Harness架构系统架构验证与证据链
角色方法与模板的拥有者在领域中使用模板的设计者验证与持续改进的执行者
负责定义方法、维护 13 模块模板,提供生成能力与验证规则基于模板完成领域化实例,形成系统的设计承诺读取架构、条款、判据,在各关口叫检测与测试两个裁判并执法,生成证据与改进建议
产物方法、模板、生成工具、验证规则领域化的系统 ARCH.html验证结果、问题清单、证据与演进建议
不能做不复制其他来源的真相
不直接手工编辑派生区域
不修改模板方法本身
不绕过生成与验证流程
不更改架构内容
不作为其他真相来源的编辑入口
HONEST BOUNDARY

机器验证结构与一致性,
人类仍须判断架构是否正确。

框架能够证明
  • 结构、版本与真相源关系完整
  • 条款、判据和制品锁步一致
  • 对当前内容查过、跑过,并留下可复核证据
  • 改过的测试咬得住被测对象
  • 已知违规被识别、阻断或显式豁免
框架不能替代
  • 业务目标是否值得追求
  • 架构取舍是否最适合当前环境
  • 文档语义是否真实、完整且无误导
  • 未知风险与未来变化的专业判断

模板在框架内定义方法,在系统中形成实例,在验证制品链中留下证据。