Spec 必然腐烂?两阵营之争与知识光谱的第三条路

简介: 本文最后给出三条预测,每条附判定条件,期限一年。预测一:spec 工具会长出现状层。预测二:agent 平台会把知识和规范的分发做成一等能力。预测三:知识光谱的维护成本随规模亚线性增长。

闵锐,Inspire 英湃科技(原 Thoughtworks)资深全栈架构师与技术专家。深耕汽车及跨国企业数字化建设,精通规模化团队工程治理与复杂系统架构。持续探索 AI-native 交付体系与领域知识工程在研发提效中的场景落地。

2025 年,不少团队给 AI 编码工作流装上了 spec 框架:先写规格,再让 agent 照着实现。2026 年,其中一部分人发现 spec 开始说谎:页面早改了,spec 里还是旧交互;接口字段加了三个,需求列表纹丝不动。

对此市场上吵成两派。一派说,这只能说明你维护得不够:spec 就该是唯一权威,代码都可以从它重建。另一派说,手写的东西必然过时,唯一可信的真相是对代码库的机械重建,spec 只配当一次性草稿。

这场架吵了一年,谁也没说服谁。这篇文章的观点是:他们吵错了题。手写的技术现状必然腐烂,业务资产不必然,机制对了就不必然。

一、争的是什么:两派都对,也都只对一半

先把两派各自最强的版本摆出来,别打稻草人。

​一派说:spec 是权威,代码是构建产物。​工具厂商 Augment 把这条路线写进了官方指南,核心主张就摆在标题里:"spec as the source of truth, rebuildable codebase":人只维护规格,代码由 AI 从规格生成,不满意就推倒重来。代码像 target 目录一样可以随时清掉,规格才是资产。这派有真东西:AI 生成的代码量已经大到人逐行审不动,团队需要一个人能读、能评、能签的契约层;而且规格写清楚了,AI 的产出质量高一截,这一点试过的人很少有异议。

但它的死穴也正在"维护"两个字上。

一份过时的 spec 比没有 spec 更危险:没写下来,AI 知道自己不知道,它会去读代码、去问人;写错了,AI 会自信地错下去,而且每次引用都在强化同一个错误前提。

公司博客里有人把这叫 spec 的投毒效应:维护缺失比写错更毒。这个病也不新鲜,Pragmatic Engineer 引用 Birgitta Böckeler 的判断,spec 驱动开发一直没起飞,和当年模型驱动开发(MDD)是同一个死法:规格承诺了与代码同步,实践中没人付同步的成本。

​另一派说:手写的现状不可信,真相只能从代码机械重建。​代表声音是 kotrotsos 的《Spec.md Is Not the Problem》:问题从来不是用 Markdown 写规格,而是把规格当 source of truth 这件事本身;真正可信的 source of truth,是对当前仓库状态的机械重建,从代码现算出来的东西不会过时。这派同样有真东西:他们戳中了前一派的软肋。凡是手写的现状都逃不过腐烂,我没见过靠自觉维护活过三年的现状文档。

但它也有死穴:机械重建保得住结构,保不住语义。代码忠实记录了系统"是什么",却不记录"为什么这样设计",不记录"这个字段永远不能为空是业务红线",不记录"这层间接性是为了把谁的变更隔离开"。重建产物像一张精确到每条巷子的城市地图,但不告诉你哪条是单行道、哪座桥限重。

结构可达,意图不可达。

这场架在 Birgitta Böckeler 那里早有坐标,就是上文被 Pragmatic Engineer 引用的那位。她在 martinfowler.com 的系列文章里,把 spec 的严谨度分成三档:spec-first,写完即弃,适合原型;spec-anchored,规格与代码同步维护,适合长期系统;spec-as-source,人只编辑规格,代码完全机器生成,眼下只有少数新玩家在探索。两阵营就是这架梯子的两端在互相宣判死刑。这架梯子的用法本来是按需选档,但生态里没人选档,只有站队。

两派吵了一年,共享同一个前提:把"知识"当成一种均匀的东西。一个说"要维护",听起来是全部都要维护;一个说"会腐烂",听起来是全部都在腐烂。没有人问:哪种知识?腐烂的速率一样吗?烂掉之后,世界会糟糕多少?这个问题两派都答不了,因为他们的工具箱里没有这个维度。

二、镜头拉远:七个门派,共享同一个盲区

这场架不止关于 spec。把镜头拉远,"工程知识怎么到达 AI"这片地里门派比想象中多,而每个门派都在那两个极之间站队:手写权威,或者机器导出。逐个看过去,每派都有一手真功夫,也各有一处死穴。

最老的门派是团队 wiki。Confluence 上每个团队都有一个"知识库",人写、人审批、人不读。它比 AI 老得多,也烂得早:文档腐烂从来不是 AI 带来的新问题,AI 只是把代价放大了。以前文档烂了,新人多问两句就能绕过去;现在文档烂了,agent 会拿它当真理去生成代码。

spec 框架派是这两年声量最大的一支。我考察过六个主流框架(OpenSpec、Spec Kit、BMAD、Superpowers、GSD,加上后面要出场的 Trellis),其中三个被同一份外部评测打过十三维的分:规格质量、到 PR 时间、迭代精炼、并行支持……全是怎么"生产"spec 的维度,没有一维问"变更结束之后知识去哪"。评测框架自己就暴露了行业的盲区:spec 被当产出物考核,没人当资产考核。

验尸一个真实的库更直观。OpenSpec 是这派评测得分最高的框架,它自己的仓库里,specs 目录下平铺着四十个 capability 文件,命令级粒度,没有层级也没有领域;每个文件是 Requirement 加 Scenario 的需求切片。架构、数据模型这类技术现状写在变更目录的 design.md 里,变更一归档,知识跟着沉没。这个仓库最近还在 specs 和 changes 之外长出了 explorations、initiatives 两个目录:纯增量模型不够用了,工具正在被真实使用推着长出设计时没有的知识分层。

仓内派把知识搬进代码仓,跟着 git 走。AGENTS.md 放仓库根上一页纸,CLAUDE.md、.cursor/rules 按目录生效,各有各的地盘。这派势头很猛:agents.md 这个开放约定截至发文已经挂在六万多个开源项目里,Codex、Gemini CLI、Cursor 都认它。卖点扎实:知识跟着代码进 code review、随分支隔离,而且离 AI 的注意力最近,agent 启动时默认读它。死穴也跟着仓来:代码仓是单库视角,跨服务的知识没地方放;文件没有结构约定,写着写着就长成几百行的无层级长文;同一知识忍不住写两处,漂移就开始了。

spec 框架派和仓内派的病,可以在同一个人身上发作。我看过一位前端同事的仓库,他用前面提到的 Trellis 跑了三个月:十次会话,十几个任务个个从设计文档走到归档,还留下三百多行使用日志。但框架里留给编码规范的六个文件,全部停留在 "To fill" 模板态;他真实的规范和业务知识,写进了他另行搭建的第二个系统,一个 wiki。

同一张项目路径映射表,AGENTS.md 里记了八个项目,框架 guide 里那份只记了五个,后来更新的那份没人去同步前一份。漂移就这么发生,而且没人发现。不是使用者不努力,是知识的构成里没给"现状"留位置。

工具管得了过程,管不了资产。

机械派干脆不写知识,现算。aider 的 repo map 是代表作:用 tree-sitter 从代码里抽符号,按图排序挑出最值得看的一屏,地图从代码里长出来,不写在纸上。我们团队后来也搭了一版,把全部后端服务的类、方法、端点、调用链抽成图谱,查"这个端点谁处理"先走图谱再回源码(前端和移动端还没接进来)。这派把"结构可达"做到了头,也永远碰不到语义:图谱知道一切结构、不知道任何意图。它答得了"在哪、谁调用谁",答不了"为什么这样设计、哪个枚举值是业务遗留的坑"。

memory 派让 AI 自己写知识自己召回。Claude Code 的 auto-memory、各类 agent 的 memory 文件,一条决策记下为什么、怎么用。零人力成本,贴着决策现场。但决策快照层和现状层是两回事:个人视角,换人即失忆;存在不等于被召回;更没法团队共享。

检索派把存量文档切块做向量索引,RAG 挂给 AI。卖点是不用重写,Confluence 里躺着的存量直接复用。死穴一句话:检索加速的是知识的获取,不是知识的保鲜。烂文档被更快地喂给 AI,投毒效应的自动化。

最外圈还有 llms.txt 这类轻量约定,本质是给 LLM 的一页导航,不承载知识本体。

这些门派放一张表上:

门派 知识放哪 谁写 最强卖点 死穴
团队 wiki wiki 平台 人 存量厚、人人都熟 人写人不读
spec 框架 specs/按能力切片 AI 起草、人审定 变更过程有契约 现状=需求切片,归档即沉没
仓内派 代码仓 rules/AGENTS.md 人机共写 跟 git 走,离注意力最近 单库视角,多载体漂移
机械派 不放,现算 机器 永不过期 语义盲区
memory 派 agent memory 目录 AI 零人力,贴决策现场 个人化,召回不可靠
检索派 存量 + 向量索引 人写存量、机器切块 存量直接复用 加速获取不保鲜
llms.txt 站点根一页 人或 AI 轻 只是入口,不承载知识

横看卖点一列,是各派的真功夫;竖看死穴一列,是同一个病的七种发作。

姿势各异,共享同一件事:一个位置、一种格式、全部知识。wiki 派把规范和业务现状塞同一个空间,spec 派把过程和资产混在变更目录里,仓内派把工程纪律和业务知识塞同一个文件,机械派假装结构就是全部,memory 派假装偏好能代替现状,检索派假装存量等于现状。没有一派先问:哪种知识?腐烂得多快?烂掉的代价多大?

三、什么知识值得写:三种盲区,三种命运

要回答"哪种知识",得先问一个更根本的问题:AI 到底缺什么?

用 AI 写码的人都见过它的两副面孔:设计原则讲得头头是道,却答不出"你们系统的服务边界为什么这么划"。别怪模型发挥不稳定,这是两种不同的缺失。模型的知识盲区分三类:

  • 通用知识盲区:设计模式的推荐用法、REST 的惯用约定。训练语料里有,模型进步会把它填平。
  • 业务特定盲区:你的字段语义、你的服务边界、哪个接口背着历史包袱。训练语料里没有你的业务,模型再强也填不上。
  • 可达性盲区:知道系统里有哪几十个服务、某类问题该在什么时候去查哪里。模型进步吃不掉"发现"这件事,系统越大这坑越深。

三类盲区对应知识的三种命运:

  • 通用知识会贬值。把它写进知识库,等于复述模型的默认答案,是噪音。薄投,甚至不投。
  • 业务特定知识是护城河。模型永远给不了,只随你的业务增值。重投。
  • 可达性知识会增值。它不绑业务,但它是机制不是内容:价值在"找得到",不在内容本身,库越大越值钱。模型进步抹平的是内容差距,抹不平发现成本。

“光谱”到这里先立起第一根轴:知识不是一个是非题(写或不写、信或不信),是一张连续的谱。一头是贬得最快的通用知识,另一头是不贬反增的可达性知识,中间是保值的业务知识。谱上的位置决定待遇:放哪、投多少维护。两阵营争"spec 该不该信",问法本身就错了,先问这段知识在谱的哪里。

除了"缺什么",还有第二问:这段知识要活多久?

第一章里那句"投毒效应",出自 2026 年 5 月智湃研究院发布的一篇文章《你的 SDD 还好吗?重新开始》。作者从 spec 驱动开发(SDD)的失败归因出发,得出一个干脆的二分:过程型 spec 绑定需求卡、单次执行、用完可以 gitignore;资产型 spec 描述系统现状、跨角色共享、长期演进。他的判词也狠:团队并没有在做 spec 驱动开发,而是在做“spec 版的需求卡开发”。

写这篇文章的时候两边并没有互相参考,但生命周期这根轴上的结论撞了个正着。本篇把它当作姊妹篇,接着往下写,重叠与差异留到第四章末逐笔结清。它立住了三件事:现状与过程分开记录,资产内部按全局地图、领域、流程分层,治理靠使用、更新、校验的闭环。也停在分层清单:层与层之间靠什么关联,各层变化周期是否一样,每层由谁投入维护,这三个问题没有展开。第四章接手回答,这也是本篇相对它的增量。

到这里,"哪种知识?"有了完整的答案,而且是两根轴:一根管内容和命运(贬值的、护城的、增值的),一根管生命周期(过程的、资产的)。第一章的三个设问也一并收账:哪种知识,轴上定位;腐烂速率,通用知识贬得最快、可达性知识不贬反增;烂掉的代价,护城河带最贵,它值得最重的维护。

回看第二章的门派死穴,可以统一诊断了:wiki 派有资产意识、没有分型;spec 框架派有过程、没有资产归宿;机械派有可达性、没有语义。每派都攥着光谱的一小段,把那一小段当成了全部。

剩下的问题只有一个:一座同时按两根轴组织的知识库,实际长什么样?

四、第三条路:知识光谱

我们团队维护着一座独立的知识仓库:十四个业务服务各占一个目录,全库六百八十多篇,维护者是一个人加 AI。到 2026 年 9 月,它已经走完二十六个变更的追踪与回写。它没有蓝图,是被三个约束压出来的形状:业务跨服务、维护力只有一个人、人要读 AI 也要读。压出来的结果就是光谱。

前两章诊断出的病,收拢成三个具体问题,各对应一个门派的现场:

  • 机械派的语义盲。它能现算出全部结构和调用关系,却答不出三件事:服务边界为什么这样划,某个字段的业务语义是什么,哪个接口背着历史包袱。这些业务知识只存在于人脑和过程对话里,代码里拿不到。
  • 仓内派的漂移。同一张项目映射表,AGENTS.md 记了八个项目,框架 guide 里那份只记了五个。根源是技术层随每次发布变动,手写维护当天就开始过期。
  • spec 框架派的沉没。OpenSpec 的 specs 目录全是需求切片,架构与数据模型写在变更目录的 design.md 里,归档即沉没。需求变了,架构、数据、接口都要跟着变,但没有人承担这个翻译。

原理:两个不对称

三个问题共享同一个变量:变化率,这是光谱的第一个不对称。光谱的语言轴同时是变化率轴。越往上越偏业务,也越稳定,业务规则、原语、术语都在这一头;越往下越偏技术,也越多变,接口、框架、部署都在那一头,两头之间隔着依赖隔离:依赖方向由外向内,外层怎么换,内层不动。上层的稳定由此是推论,不是巧合。整洁架构的同心圆是这个规律的著名先例:内环是稳定的业务实体,外环是多变的基础设施与接口。

whiteboard_exported_image.png

手写文档的维护成本随变化率线性上升,变化率过了阈值的层,手写必然滞后。对这些层,换生产方式是必然,不是偏好。落到三带的分配,依据各有不同:下带现算是结构必然,代码是唯一的权威源;上带人写也是结构必然,业务语义的源头只在人那里;中间带交给 AI,是当前工具条件下的最优分工。

各带的生产策略:

带 生产者 生产策略
上带·业务(变化率低) 人 选对输入时机:沉淀文档之外,主要靠变更过程记录。变更就是需求拆解,回流时业务层知识最完整,此刻回写。
中间带·对接(变化率中) AI 做双向映射。自底向上,AI 能把实施形态对应到业务类型,但到不了业务术语的源头;自顶向下,上带提供业务原语与术语。两向在中间对齐
下带·技术(变化率高) 机器 自动化。代码图谱现算 as-is,向上做自动总结与翻译

表中的生产者指内容的权威来源,不是执行动作:上带由人审定语义,拆散落位的动作交给 agent。

至此光谱有三根轴:类型谱承自第三章的三种命运,定投资强度;生命周期谱就是《你的 SDD 还好吗?重新开始》的过程/资产二分,定归宿;语言谱即变化率谱,定生产者与可翻译性。类型谱与生命周期谱决定目录的静态组织,语言谱驱动机制。

变化率之外还有一个不对称:展开量,即一条业务规则在每层展开成多少条事实。上层的一条业务规则,落到下层会成倍展开:跨几个服务的调用链,几组实体间的状态迁移,外部配置与部署环境,乃至可用性标准。越抽象越好记,越具体越难记;但下层难记的同时,它已经被代码和部署本身表征。

最底层的完整实况,等价于代码与部署本身:方法实现与配置值,用代码图谱加源码读取就能索引,不写进光谱;写进光谱的是这层之上的约束语义,即部署依赖、开关策略、协议兼容,落位在运行部署页。光谱的记录边界因此画在代码这条线上:线上各层都记,代码本身不记,它自己就是记录。线上的记录对代码做适度抽象,越过具体方法与实施细节,表征整段实施流程,特别是跨服务调用如何体现业务逻辑。这是光谱真正记录的内容。那篇姊妹篇把还原现状称为业务考古。展开量的不对称替考古划了边界:挖到代码之上为止。

静态形态:目录与账本

目录的静态结构按前两根轴组织。内容轴上,每个服务目录固定七个面,编号即阅读顺序,从业务语言一路下移到技术语言,结构见下方目录树。投资强度按第三章的三种命运分带:业务特定知识重投,通用知识薄投,可达性知识做成索引和触发器,例如规则中约定“修改该模块前先读其架构页”。它在光谱里不占一层:不描述某一层的内容,只负责层与层之间的指路。一座真实的服务目录(结构原样):

权益中心/
├── index.md          # 索引:这页是什么、往哪走
├── 01-概述.md        # 系统定位、核心能力、边界
├── 02-架构.md        # 上下文图、模块、事件流
├── 03-核心流程.md    # 状态机、用例、API
├── 04-数据模型.md    # 实体、字段、枚举
├── 05-集成.md        # 外部系统、集成矩阵
├── 06-风险.md        # 风险表、错误码、边界条件
└── 07-运行部署.md    # 依赖、配置、部署、监控

七个面与六层不是一一对应:03 一个面跨需求与接口两层,06 风险是横切各层的问题面,index 是导航,代码层没有面,源码仓就是它的载体。目录是光谱压成一维的阅读序列,合并与横切都是有意为之。

生命周期轴上,变更、技术债、发布、调研各有独立目录,不与现状层混放。债有总账,发布有档,调研有册:过程知识在各自的账本里走完,收尾时把值得长期保留的回写到资产层。

按这两根轴组织出来的形态并不新鲜。一个服务七个面,任何认真写过两年文档的团队都会沉淀出类似的目录。这座库的增量不在形态,在形态周围的机制。

机制:锚定与翻译

机制的实质一句话:探索、调研、变更都锚定在同一份分层现状上。这份现状沿"业务到基础设施"的语言轴连续展开,六层各有自己的原语,逐层对应到不同的现状页,见下方阶梯图。

变更沿层向下翻译:需求改了,译成架构调整,再译成数据与接口的改动,最后落到代码与部署;基础设施触发的变更沿同一条路反向走。归档时知识沿层向上回写,一上一下两条流共用同一组现状页作锚点。相邻层因此互为校验:下层变了、上层没跟上,就是漂移。目前只有代码边界上的互校是自动化的,即代码图谱对账;其余相邻层靠变更管线的纪律承载,尚未自动化。

whiteboard_exported_image-2.png

阶梯是同心圆的侧视画法:由内向外,就是自下而上。两图分工不同,同心圆解释为什么内稳外变,阶梯补上每层的原语、现状页与双向流向。

拿一条虚构的需求走一遍:会员的权益要能跨服务共享。需求层先确认能力与场景;架构层回答边界,权益归谁、事件怎么流;数据层回答实体,共享关系落在哪张表、哪些字段;接口层回答契约,谁暴露端点、字段叫什么;最后落成代码层的提交与基础设施层的开关。每层用自己的原语承接同一次变更,这就是向下翻译。

这条链有固定的操作规程。阶梯图给流向,走例给动作,这张表给的是一次变更在每层的确切落点:

层 本层原语 变更期间落在哪里
需求 能力与场景 探索与提案两步的产出:原子变更清单;每个故事一份场景式 spec,作为验收标准
架构 服务边界与事件流 设计文档写边界调整与事件流变化,含被否方案与理由
数据 实体与字段 设计文档的数据章节:实体、字段、枚举的变更,配 migration
接口 端点与契约 契约调整进故事 spec 与设计文档,字段语义同步进缩写表
代码 提交与 MR 任务拆解到提交粒度,MR 描述回链故事 spec
基础设施 配置与部署 发布清单:toggle 策略、协议兼容、升级论据

归档时逐层回写:行为变化进 03-核心流程,边界调整进 02-架构,实体与字段进 04-数据模型,契约进 05-集成,部署事项进 07-运行部署,变更目录整体冷藏。

三带的生产:时机与载体

三带落在阶梯上:上带是需求层,中间带是架构、数据、接口三层,下带是代码与基础设施两层。中间带能交给 AI,靠的是载体同构。状态机、集成矩阵、业务规则表、库表总览,这些页面的知识有结构化载体。变更产物按同样的形态写差量:状态迁移写成状态机片段,契约增改写成矩阵行,规则写成带编号的条目。归档时 agent 只负责语义路由,判断每块知识回哪页哪段。路由之后是同构搬运,新表加行、语义变更改行、片段并入现状页,不重新推导。

输入时机上,上带只有变更回流一处,中间带有两处:归档时的差量回写,图谱重扫后的漂移裁决。重扫只产出过时候选清单,逐条裁决后回流,机器不改写语义层。

日常生产按三带分工;从零建库则分三步走。自下而上:基于全部代码与代码图谱梳理出代码之上的抽象层(图谱脚本出结构面初稿,矩阵行、状态集候选、规则锚点;人补语义列,三方对照后定版),把它理解为代码所表述的业务逻辑。自顶向下:把业务愿景、业务目标、业务规则向下对应到各层。中间对齐:两条线在对接层会合,上层术语与下层实现在此互相锁定。

上边界:沟通这条供给线

光谱还有一条上边界。BA 和 PO 是团队对外的边界口径,以这条口径为界,上边界分两段。界内是需求输入与传递:业务层的决策到了 BA 和 PO 手里,整理成产品输入,再沿 backlog 梳理、迭代计划、故事开卡这几个固定环节传给团队。界外是业务层决策:按优先级、市场反馈、资源与指标做权衡,排定想做的事和期望的产品进化形态。姊妹篇说核心约束藏在白板、聊天记录和脑海里,说的就是这两段里的沟通。

两段的待遇不同。界外的高变化率权衡,过程不收,收的是它沉淀的产出:期望的产品进化形态进 01-概述,逐期的优先级排序随变更本身留痕。界内这一段可以收割:环节固定、时间可预期,这条线今天就靠人工运转,BA 在会议里把散落的讨论拼成确认过的输入。机械化只缺一个条件:沟通聚合到机器可读的集中渠道,工作台就能自动归纳、总结、提取。

收割点选在环节收敛处,不收过程草稿:确认结果进库,反复与噪声不进,与图谱锚定生产基线、不读 feature 分支是同一条纪律。审定权不变:收割改变的是采集,进需求层前仍由 BA 和 PO 确认,上带生产者仍是人。

这条供给线今天没有走通:渠道聚合不在团队手里。走通之日,上带的增量输入从变更回流一处变成回流与沟通收敛两处,光谱的上边界上移一层;界外那段维持只接产出的姿态,它的稳定产出在构建三步的自顶向下里已经有了落点。

打回:三个现场的对答

对照开头的三个现场。机械派语义盲的答案是输入时机:业务知识在变更回流时最完整,回写成为变更收尾的必经步骤,"随时补文档"变成"此刻必须写"。仓内派漂移的答案是生产方式:下带代码即记录、图谱即索引,手写只保留 should-be,过期即漂移,漂移即可见。spec 框架派沉没的答案是翻译者:语言轴连续、每层有原语、相邻层互校,翻译从无人承担变成结构内置。三个答案合起来,治的是第二章那个统一的病:知识不再挤在一个位置、一种格式里,而是按带生产、按层回写。

运行:五站一循环

机制落在时间轴上是一条循环。跟着一段知识的生命周期走一遍,共五站:

​第一站,开工。​新变更启动时,对应服务的现状页作为上下文进入会话,AI 拿到的是该服务完整的当前状态。变更自身有管线:探索、提案、设计、验证、归档,五步走完。

​第二站,过程。​变更期间产生的知识(设计文档、spec、测试记录)全部落在变更目录这个临时层,不直接写现状页。过程知识与资产知识分开存放。

​第三站,回归。​变更收尾时,AI 读取变更目录的全部工件,判断每块知识回写到哪一页哪一段,拆散、落位,随后归档变更目录。这个动作称为 agentic delta-merge。

这一步无法机械化。OpenSpec 的合并单位是需求条目:Requirement 和 Scenario 结构规整,能带 ADDED、MODIFIED、REMOVED 标记,归档时机械地合回 specs/。同一套标记到架构叙述就失灵。一次迁移的设计文档里,有跨服务链路的重新划分,有某个字段语义的修正,有一条"以后不要再这样"的教训,它们该去五个不同页面的不同段落,没有机械标记能描述这种散布。合并是语义动作,只能交给 agent。卡的只是路由这一步;路由之后的搬运,载体同构已经解掉。

git 管 code diff,agent 管 knowledge diff。

​第四站,防腐。​资产层有三级防御。Lint 防走形,查元信息、链接与编号,每次变更后必跑。全库健康扫描防遗漏,周期性体检,查收尾完整性和漂移。第三级防说谎,是图谱对账:光谱每页写"应该是什么"(should-be),代码图谱从代码现算"实际是什么"(as-is),两个源各自独立、互不喂养。图谱列出该服务全部对外端点,核心流程页写明的行为清单对不上,差值即漂移清单。岗位分工是结构性的:作者必须懂语义,由人加 AI 担任;审计员必须只认代码,由机器担任。审计员一旦承担写作,双源退化为单源,机械派警告过的腐烂就会回来。

对账已在实际运转。近期接入四个新仓库,每个仓各自抽取、汇总成一张总图。重建总图时自动检出五个存量服务的漂移:上游代码已变,图谱产物还停在旧版。图谱采集锚定在生产基线分支上,漂移因此有了精确含义。

每一条 drift,都对应一次进了生产而图谱没跟上的发布。

三级防御的递进关系:

结构坏了看得见,漏了查得出,说谎了对得上。

​第五站,分发。​知识的物理位置由受众决定:团队要读的发布到团队 wiki;AI 执行的规则与技能在知识仓单一维护,通过软链接分发到各项目仓。wiki 降为渲染目标:内容单向发布、不回写、不当权威。内容生产移到知识仓、wiki 只负责渲染后,"人写人不读"失去落脚点。

五站连成一条循环,是这座库全部的机制:

whiteboard_exported_image-3.png

实线是知识的两条主路:变更经 delta-merge 归档回写,新变更再把现状页取作上下文;虚线是防腐,should-be(现状页)与 as-is(代码现算)各自独立、互不喂养,差值即漂移。

定位:零件对位、姊妹篇与先例

逐件对位:SDD 工具箱的五件零件在光谱里各有去向;光谱还多出两件,工具箱里找不到对位。

  • changes/ 变更提案:对应变更管线(探索、提案、设计、验证、归档),​同构且更细​。
  • specs/ 想要的资产层:对应服务目录的全息现状,即 ​SDD 缺失的半边​。
  • AGENTS.md 仓内规则:对应规则层,差别是单一源头、软链接分发,同一知识只有一份,第二章那类映射表漂移没有生存空间。
  • repo map:对应代码图谱,角色从查询入口升级为对账的审计员。
  • memory:对应决策快照,值得共享的由人工提升进资产层,该管道目前是人工的。
  • 检索派与 llms.txt:无对位零件。前者作为建设期供给线消化存量,后者仅作入口导航。
  • 第四站防腐与第五站分发:SDD 工具箱没有对位零件,​是光谱的增量​。

坐标再对一次,而且对得更齐。那篇姊妹篇的作者不知道这座库,我们也不是照它搭的:资产三层对得上全库入口、服务目录、核心流程页,“使用、更新、校验”的闭环对得上五站的开工、回归、防腐,“资产型天然适合跨角色共享”对得上第五站的受众分层。重叠止步于此。

差异正是姊妹篇留下的三个问题。层间关联:他给到分层清单为止,光谱给的是翻译链与相邻层互校。变化周期:他注意到资产型内容“变化频率相对更低”,光谱把整条语言轴按变化率排了序。投入力度:他主张先由人建立认知、再逐步引入 AI;光谱按带分工,下带机器现算,上带人在回流时回写,中间带 AI 做双向映射。

连他的保留意见也有回应。LLM Wiki 一类的自动构建,他的判断是“稳定性与可控性仍有待验证”。光谱的回应是双源纪律:审计员只认代码、不承担写作,双源不退化,对账已在生产运转。

最后说明先例。这套东西的每个成分都有先例:整洁架构的变化率分层、活文档、ADR(架构决策记录)、doc-as-code、资产型 spec、机械派的对账意识。第三条路的贡献在组合:按知识类型分开命运、分开归宿、分开投资强度,再给每个既有门派派了岗位。独立收敛背书的是问题真实,不是独创性。

边界也划出来。这套机制有三处边界。

规模之下不成立。服务少、变更稀的团队,过程型 spec 够用;建光谱要养回写管线和现状层两套结构,边际成本靠复用摊薄,第一个服务的账一定亏。

人手一环未验证。维护者是“一个人加 AI”,这是被约束压出来的,不是主张。结构本身不依赖个人记忆,但 should-be 的续写判断仍系于人;人换之后能否续上,取决于结构而非继任者的记性。

时间之内会被部分收编。平台若原生长出现状层、把团队知识分发做成一等能力,本文哪些部分会留下?判断是:分级与归宿是原理,留下;回写管线与图谱审计员是自建实现,可能被平台收编;软链接分发是过渡期脚手架。

五、三个预测:把结论交给一年后的事实

本文最后给出三条预测,每条附判定条件,期限一年。

​预测一:spec 工具会长出现状层。​主流 spec 框架的"现状"目前仍是需求切片,变更产物随归档沉没。预计一年内有框架把架构、数据模型、集成做成现状层的一等公民,并把归档回流做成机制。旁证已经出现:OpenSpec 在 specs 和 changes 之外长出了 explorations 和 initiatives,工具在真实使用中被逼出知识分层;但那是过程侧,本条标的现状侧(架构、数据模型进 specs)仍空缺。判定条件:一年后主流框架仍是需求切片加归档沉没,该预测不成立。

​预测二:agent 平台会把知识和规范的分发做成一等能力。​目前各平台只认仓库根文件(agents.md 已覆盖六万多个项目),团队级知识库与技能依赖软链接、复制粘贴、MCP 外挂。下一步是团队级分发,像 npm 分发代码一样分发知识。发文时无主流平台完整实现该能力,此条为未验证预测。判定条件:一年后平台仍只认仓内根文件、团队知识仍靠手工同步,本条即被证伪。

​预测三:知识光谱的维护成本随规模亚线性增长。​直觉的账是线性增长,本文判断为亚线性:回写管线与分类归宿摊薄边际成本,第二个服务复用第一个的模板,回写是流程,防御是工具。第四章的变化率判据在此收口,手写成本随变化率线性上升,压平它靠的正是把最易变的两层交给机器现算。这座库 2026 年前九个月二十六个变更、六百八十多篇,尚无反例。曲线级的验证按判定条件交账。判定条件:按 git 历史统计仅修改既有页面(不含新增目录)的维护类提交,相对页面总数画出趋势为线性或超线性,该预测不成立,且全文核心主张需随之重估。

三条预测期限均为一年,到期按判定条件检验。

只带走三件事

以下三条均可直接迁移到读者自己的知识库:

  1. 翻开你现在的 spec 或 wiki,把内容按"通用、业务、可达性"分三堆。通用堆停投,业务堆重投,可达性堆做成索引。
  2. 过程文档和现状文档分目录放。变更归档时,把值得长期留下的回写进现状页,不让它随归档沉没。
  3. 挑一个能从代码现算的东西(对外端点、调用链),做第一个审计员,先让一处 should-be 和 as-is 对上账。

参考资料

  1. Augment 官方指南:Spec as the source of truth, rebuildable codebase——spec 维护派(spec-as-source 路线)的代表主张。
  2. Pragmatic Engineer 转引 Birgitta Böckeler:spec 驱动为何一直没有起飞——两派争论的历史坐标,与模型驱动开发(MDD)同构的死法。
  3. kotrotsos:Spec.md Is Not the Problem——机械重建派的代表文章。
  4. Birgitta Böckeler(martinfowler.com):SDD 工具系列——spec 严谨度三档梯子(spec-first / spec-anchored / spec-as-source)。
  5. ranthebuilder:三个 spec 驱动 AI 工具的十三维评测——评测维度只覆盖生产、不覆盖资产归宿的行业盲区样本。
  6. OpenSpec GitHub 仓库——spec 框架派的解剖样本,归档沉没与 explorations/initiatives 旁证均出自它。
  7. agents.md 开放约定——仓内派代表,覆盖项目数用于判断分发趋势。
  8. aider:Repository map——机械重建派 repo map 的代表作。
  9. 《你的 SDD 还好吗?重新开始》——本文姊妹篇,生命周期谱承自它的过程/资产二分,层间关联、变化周期、投入力度三问由本文接手。
相关文章
|
4天前
|
Linux Go 开发工具
手机上跑 DeepSeek 智能体:开源安卓客户端 DSH Go 安装与使用指南
DSH Go 是一款开源安卓客户端,将 DeepSeek Harness 智能体引擎装进手机:免 Root、免 Termux,一键安装即用;支持本机运行(内置 Ubuntu+Node.js)或远程接管电脑会话;具备插话打断、过程折叠、屏幕操控、端到端加密分享等特色功能,真正实现智能体“口袋化”。
5004 8
|
4天前
|
弹性计算 人工智能 API
Codex超详细入门指南(下载·安装·登录·上手,全版本覆盖,2026最新版)
建议收藏本教程,2026 全年各版本更新随时回来查阅。如果你在搭建过程中遇到任何问题,欢迎结合 阿里云工单系统 提交技术支持请求,或在 阿里云开发者社区 搜索 Codex 相关话题交流。 祝你编码愉快,效率翻倍!
2017 5
|
7天前
|
JSON 前端开发 API
阿里云最新Qwen4-Max大模型介绍:模型定位、特征、能力、适用场景解析
2026 年 11 月 11 日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问 AI 平台 Token Plan,并同步接入千问办公、Qoder 等入口。该版本聚焦知识理解、世界感知、编程与 Agentic 四项升级,主打复杂编程、专业办公、前端设计与专业软件操作。预览期至 11 月 25 日 24:00,到期后模型标识下线;限时 2 折、新用户再享 5 折,最低 1 折可体验。
|
7天前
|
人工智能 前端开发 API
阿里云Qwen4-Max 大模型详解:定位、特征、能力、适用场景与相对Qwen3-Max差异解析
2026年11月11日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问AI平台Token Plan并接入千问办公、Qoder等入口。该版本聚焦知识理解、世界感知、编程与Agentic四项升级,主打复杂编程、专业办公、前端设计与专业软件操作等真实任务。预览期为11月11日10:00至11月25日24:00,仅支持Token Plan调用,到期后模型标识下线;限时2折、新用户再享5折,最低1折可体验。
|
20天前
|
Linux 开发工具 iOS开发
Codex保姆级教程(下载+安装+登录+使用,含所有版本,2026最新)
Codex是OpenAI推出的开源AI编程智能体,本地运行,可理解整个代码库,支持自然语言指令改代码、执行命令、跑测试、修Bug,兼容Win/macOS/Linux。(239字)
9618 58
|
2天前
|
传感器 安全 区块链
Windows 电脑运行安卓应用教程:开源工具 ApkStart 双击 APK 即装、独立窗口运行
ApkStart 是一款开源Windows工具,让安卓APP像原生软件一样运行:双击APK即安装、生成真实图标、独立窗口启动、开始菜单可搜索。无需传统模拟器,内置QEMU运行时,支持数据互通、ARM兼容与命令行操作。(239字)
|
14天前
|
Linux 开发工具 iOS开发
2026最新codex下载安装保姆级使用教程(下载+安装+登录+使用,含所有历史版本)
本文详解OpenAI Codex国内快速上手指南:提供Win/macOS/Linux全平台免安装包、npm/Homebrew等多方式安装、账号/API Key双登录、简体中文切换,覆盖下载、安装、汉化、使用及高频避坑(如微软商店失败、npm超时等),10分钟即可跑通。
3280 9
|
20天前
|
JavaScript API iOS开发
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(DSH)是DeepSeek于2026年开源的MIT协议AI Agent框架,支持插件化组装模型、工具、沙箱与UI,兼容主流大模型。本文提供免Node.js的桌面端安装包(Win/macOS),含详细图文教程及热门插件推荐。
5973 69
|
3天前
|
人工智能 弹性计算 开发工具
零成本玩各大模型!DeepSeek Harness dsh-our-free-model 插件,13 个厂商模型直接用
总结一下:装这个插件,你不用注册、不用绑卡、不用填一个 Key,就能在 DeepSeek Harness 里用上 DeepSeek V4.1 Flash、Kimi K3 这一批前沿模型,而且是白嫖的、还不限量。三步搞定:下载插件,复制包含 `package.json` 的插件目录路径,在「添加插件」里粘贴路径安装并重启。无论是在阿里云 ECS 上通过命令行部署的 Web 版,还是本地的 Electron 桌面端,都能顺利跑通,快速搭建一套零成本的免费模型使用环境。
920 0