SPEC-AGENTS：反复修改之后，项目凭什么还是同一个项目

/research/spec-agents-project-continuity.md

来源：https://github.com/yibie/SPEC-AGENTS.md

从完成一次任务，到守住项目的连续性

让模型完成一次任务，如今已经不算难；难的是十次、一百次变更之后，一个项目是否还是原来那个项目。代码一直在改，文档有人读、有人不读，接手的人靠猜，规则散落在各处，时间一长谁也说不清“现在这样是否本该如此”。

SPEC-AGENTS 正是在这一层提出它的不同视角。它没有把重点放在更细的任务清单或文件规范上，而是把 Agent 开发中被治理的对象，从“这次要完成哪些任务、改哪些文件”上移到“项目此刻意味着什么、哪些变化合法、什么证据足以改写这条含义”。六个动作（plan → capture → arrange → do → check → learn）只是外壳：Kernel 记稳定语义，SPEC 界定单次允许的修改，State 只记执行进度，Evidence 保存会改变未来判断的稀疏事实。[1][3][4] 它关注多次变更之后，项目认知能否保持连续。

先交代证据边界。以下判断锁定在仓库 commit 9813159a3154b553a7ed4334171675641f81b818（tag v4.1.0，最后提交 2026-08-25 03:11:47Z）。抓取 GitHub 时，仓库有 125 stars、24 forks、1 位可见贡献者、0 open issues，API 报告 license 为 null，根目录也找不到 LICENSE 文件；这些只能当作成熟度与复用边界的信号，不能据此评价方法本身的好坏。[2] 主体证据以锁定 commit 的 README、WORKFLOW、六个 action skill、START、ADR、实验记录和本机复跑为准，README 的宣传句不作实测结论。

四类记录，各自只回答一个问题

这套文件体系容易让人误以为它只是“多一份需求文档”。理解它要看每一类记录回答什么问题，文件名反而次要。

Kernel 回答项目此刻意味着什么。长期概念、身份判据、关系、生命周期、动作契约、不变量和架构边界放进 KERNEL.md。SPEC 回答这一次允许改什么，跨上下文的工作契约放进 .specs/<feature>/；SPEC 之下再拆成单次可执行的 Slice。State 回答现在执行到哪里，当前活跃工作放进 STATUS.md。Evidence 回答哪些事实会影响以后的判断，放进 EVIDENCE.md。[4]

四者的边界也很重要：State 只能记录进展，不能重定义 Kernel；Evidence 可以支持或挑战 Kernel。[4] 一旦发现长期模型可能需要修订，就必须回到 plan 裁决。[7][10] 因而，动态修改可以围绕稳定语义展开，却不能在执行状态里顺手改掉它。

Context 在这个体系里不是档案总和。普通工作只读 AGENTS、WORKFLOW、STATUS（存在时）和项目 Kernel；Evidence、ADR、Protocol、Runbook、Lesson 按当前意图读取；Archive 只在明确的历史或回归问题上打开。[3][4]

这也解释了为什么 ontology graph pilot 只是“投影”而非权威。pilot 在内存里验证了 ActionType 与 RelationType 的区分、domain/range、生命周期 gate、从 Invariant 到 ActionContract/Code/Verification/Evidence 的影响遍历、relation provenance、rejected edge 可见但不进入 active query。[12] 本机在锁定 commit 上复跑通过。 但仓库明确不支持引入图数据库或 RDF/OWL：没有测试持久化、并发、推理或 Markdown 同步，图只是已批准语义模型的投影，不负责发明模型。[12]

名词和动词一起进入模型

Kernel 有八个轴：概念（Concepts）、身份（Identities）、关系（Relations）、生命周期（Lifecycles）、动作契约（Action Contracts）、不变量（Invariants）、架构边界（Architecture boundaries）和源证据（Source evidence）。[5] 概念、身份和关系描述系统中的对象，生命周期限定合法状态变化，不变量给出约束，动作契约规定可执行的改变，架构边界说明规则由哪个模块决定。模型里同时有名词和动词，这是它和普通项目说明的一个实质差别。

动作契约（Action Contract）必须同时写清 precondition、input、permitted effect、invariant、verification 五样东西，仓库把它当作连接静态语义与代码的最小接口。[4][5] 这意味着，动作被写成一组受约束、可验证的效果。

这个框架与 Palantir 对 Ontology 的描述相通。Palantir 官方资料把 Ontology 描述为组织的 operational layer，同时包含 objects/properties/links 这类语义元素，以及 actions/functions/dynamic security 这类动能元素；[16] 另一页则用 data、logic、action、security 四个维度描述决策系统。[17] 它的需求提炼句式是 [User Type] [Interface] [Decision] [Decision Inputs] [Action]，先澄清谁依据什么作出什么决定、产生什么动作，再选择实现形式。[18]

SPEC-AGENTS 吸收了这个“名词 + 动词 + 约束 + 反馈”的框架，但两点要讲清：一是当前生产版没有把 Security/Policy 做成完整运行时授权系统；二是 README 明确拒绝把它说成正式 ontology runtime。[3] 它只借用了本体论的一部分建模习惯，距离可运行的本体引擎还很远。

小改动也可能改变项目含义

进入正式流程的门槛，不看任务大小，而看请求是否新增、重命名、拆分、合并、废弃或重定义概念、身份、关系、生命周期、不变量、动作契约或架构边界。[6] 很小的 diff 也可能是一次语义变化。

plan 据此区分 no-change、plan-only、approve、compatible revise、breaking、reject/unresolved 几类结果。语义不变且当前上下文能完成时，approve 走短路径；跨上下文即使语义不变也要 capture，以保留可交接的契约。[6] 这样一来，“是否需要正式流程”的判断就从代码行数转成了语义影响与交接风险。

这个转换的意义在于，它把 Agent 协作里最容易被忽略的“边界是否被悄悄移动”摆到了台面上。一次重命名、一次把某个字段从 A 服务搬到 B 服务，行数可能很少，但它改变了“项目里到底有什么”的答案。

稳定模型也要允许被证明过时

Kernel 记的是稳定语义，但不等于永恒真理。check 新增了一类 semantic finding：发现代码与 Kernel 冲突时，只指出冲突、路由回 plan，不裁决究竟是代码错还是 Kernel 过期。[7][10] 这样做的目的是避免在验证阶段偷偷改掉长期模型。

每次 check 都必须回答：本次改动是否新增、改变或废止概念、身份、关系、生命周期、不变量或动作契约。原因很实在——新增一个 Kernel 从未记录的概念并不违反任何已有不变量，常规一致性检查根本不会响。[7][10]

start 可以当作一次只读 re-scan：已有 Kernel 时不去改它，只输出 present / stale / contradicted 和差异报告，再由用户决定什么进入 plan。[5][10] 但 ADR 0005 说得很明白：没有任何东西会自动安排 re-scan，项目不重跑就仍可能漂移。[10] 这条限制到讲仓库缝隙时还会回来。

规则落在哪一层，本身也是语义

权威落点是这套方案里很有启发的一处。ADR 0006 记录了一次现场：一个被管理项目连续四批走完六个动作，单测和 live replay 都通过，独立 reviewer 仍然发现 15 个多权威实现——包括 Python 与 JavaScript 对同一条规则给出不同结果、服务与 store 两份投影漂移、derived state 被重复持久化。[11]

测试能证明实现按自己的局部规则工作，却不能证明规则落在了正确的层；实现和同层测试可能来自同一个错误的架构决定。[7][11]

于是，架构边界被具体化为权威地图（authority map）：每条可能散落的业务规则必须指定一个权威模块，第二落点必须说明理由并通过同输入等价验证。[11] arrange 强制 Slice 写 authority: 或 n/a: reason，do 写代码前对照，check 从 diff 核验是否出现第二实现、客户端复制服务端规则或派生状态被重复持久化。[7][11]

结论不宜夸大：那 15 个问题只能说明旧检查漏掉了规则落点，不能说明新的权威地图方案已经被证明有效；外部 single-authority trial 还没回报。[11][22]

知识需要晋升，被拒绝的路径也有保留价值

learn 阶段区分了几类去向：只影响当前任务的事实不提升；会改变以后判断的事实进 Evidence；稳定语义进 Kernel；重复开发约定进 Protocol；操作步骤进 Runbook；有适用范围的失败模式进 Lesson；难逆转的取舍进 ADR。[8]

每条晋升记录必须带 status、scope、applies_when、source Evidence ID、verification，冲突时写 supersedes / contradicts，不能静默覆盖。[8] 被拒绝的路径可以留在 Evidence，免得以后被当成新想法无证据重试一遍。[3][8]

这里要区分 Evidence 和 Event Sourcing。Fowler 对 Event Sourcing 的定义，是把应用状态的每次变化作为事件序列保存，可以重建历史状态和 replay；SPEC-AGENTS 只保留会影响未来判断的稀疏证据，不能据此重建应用状态。[20] 所以 Evidence 是决策证据，不是完整日志。

它和几套相近的方法不在同一层

把 SPEC-AGENTS 放进更大的地图里，能看清它占了哪个位置。

普通 AGENTS.md 是“README for agents”，提供项目上下文、开发/测试/PR 指令，面向的问题是 Agent 应该怎样工作。[15] SPEC-AGENTS 在这个入口之上增加项目本体与演化机制，面向的问题扩展为“项目中什么存在、哪些变化合法、哪些证据足以改长期语义”。普通 AGENTS.md 是操作说明，SPEC-AGENTS 更像项目认知治理协议。

GitHub Spec Kit 现在把流程写成 constitution → specify → plan → tasks → implement → converge，规格被提升为可生成实现、并反复与实现收敛的主工件。[14] SPEC-AGENTS 的切入点不同：长期 Kernel 高于 feature SPEC，小改可以跳过 SPEC，验证后的知识还要分类晋升或拒绝，语义冲突回 plan。Spec Kit 主要治理“一次功能如何从意图走到实现”，SPEC-AGENTS 主要治理“多次功能变更如何不悄悄改掉项目的长期含义”。两者有重叠，不宜写成互斥或绝对优劣。

DDD 这边，Fowler 把它概括为围绕对领域过程和规则有丰富理解的 domain model 开发，强调 Ubiquitous Language 在软件中演化，以及用 Bounded Contexts 组织大型领域。[19] SPEC-AGENTS 借用了“领域语言必须进入实现”的方向，但给 Agent 工作加了动作契约、证据晋升、写权限和状态路由。它不等于完整 DDD——当前没有 Aggregate、Value Object、Context Map 那套完整建模体系，也不该声称替代 DDD。它实际只把一小部分领域语义变成了 Agent 可执行的开发护栏。

Event Sourcing 和知识图谱的边界前面已提过：前者保存所有状态变化并可 replay，后者关注类型化节点/边、查询和可能的推理。SPEC-AGENTS 当前权威仍是 Markdown，graph pilot 只证明临时 impact traversal 有用。[12][20]

仓库自身暴露出的缝隙

以上是这套方案的“应然”。下面是本机复核出来的“实然”——这些和 README 的成功叙事对不上，但恰恰最值得写下来。

先看通过项：bash -n bin/spec-agents 通过；./bin/spec-agents --help 通过并报告 CLI v4.1.0；临时目录连续安装两次均 exit 0、已有文件保留，产物只有 Doctrine（AGENTS/START/UPGRADE/CONTEXT/docs/spec-agents/六个 skills），没有 STATUS/EVIDENCE/ROADMAP，布局断言通过；tests/protocol-cost-comparison.sh 通过，但它只比较历史 v2 与 v3 fixture，报告 estimated tokens 601 vs 290，脚本自己声明不测模型智能或代码质量；[24] ontology graph pilot 与 JSONL evidence pilot 在本机复跑均通过（JSONL 在该 fixture 中字节/粗略 token 反而更高，所以仓库保留 Markdown）；git diff --check 通过，工作树干净。

不一致处如实列出：

• 当前 project-knowledge-routing-pilot 直接失败，报 FileNotFoundError: ... /CONTEXT.md。runner 的 DEFAULT_DOCS 仍硬编码 AGENTS.md, CONTEXT.md, STATUS.md, ROADMAP.md，installer smoke 仍期待安装 ROADMAP.md/STATUS.md/EVIDENCE.md/docs/protocols/...，与 v4.1 的 Doctrine/Instance 分离及 ROADMAP 退役冲突。[13] RESULTS 仍写着 pilot passed，因此它是历史实验记录，不能当作当前 commit 的可重复验证。[23]
• installer 的实际布局正确，帮助输出却仍写 ROADMAP.md by learn, when a phase direction is agreed；v4.1 CHANGELOG 已明确 Phase 和 ROADMAP 退役。[9][21]
• STATUS.md 写 mandatory read “exactly 400 lines”，本机实测合计 374 行（AGENTS.md 144 行、WORKFLOW.md 230 行），与 CHANGELOG 一致；STATUS 同时承认没有检查阻止它再次膨胀。[9][22]
• STATUS 自己承认：plan-only/reject/unresolved 路由没有按契约走过；capture 不保证覆盖 plan 的每个决定，已有一次决定在 handoff 中丢失；reference-integrity 仍无自动 enforcement；外部 single-authority trial 尚未回报。[22]
• writer 分工称 .specs/<feature>/ 只由 capture/arrange 写，STATUS/EVIDENCE/Kernel 只由 learn 写。[25]

  实际上，do 会更新 Slice 状态和验证摘要，learn 会回写 Slice 的 evidence_ref，plan 在部分情况下还会直接登记 STATUS。[6][8][26] 这更像未显式建模的字段级共享所有权，而不是表面上的单写者模型。

• 文档权威顺序没有列入 skills，但同一份 AGENTS 又说每个动作的真实契约在对应 skill 中。[25]

  高层 Single Authority Protocol 规定规则不在 authority map 时停止并回 plan；[27] do skill 却规定缺图或缺项时不要停止，记录 semantic finding 后继续执行。[26] 因而，这套强调单一权威的协议，自己的 doctrine 与 action contract 还没有明确谁覆盖谁。

• ADR 0005 承认 re-scan 没有调度机制，ADR 0006 承认权威地图方案尚未收到 field trial 结果。[10][11]
• 仓库没有显式许可证。可以研究、借鉴思想，但整套文件的复用与再分发授权并不明确。[2]

这些缝隙不否定本体论视角，反而说明一件事：“写了语义规则”和“每条路线真的可执行、每项证据仍可复跑”是两回事。仓库最近一次 release，本身就是在独立审查后修复了五条没有可满足下一步的 route。[9] 当一个项目把规则与证据的可执行性作为主要机制时，它自己也可能在文档规则与可执行协议之间留下差距——这个观察比“它是否可用”的简单结论更有用。这套以规则与证据为主要机制的方案，最终也要由可跑、可复核的检查来兑现，不能只停留在 Markdown 里。

吸收机制，不整套照搬

当前工作流由 Hermes 负责统筹、审 diff、实测、提交和汇报，项目开发由 Codex worker 执行，同时已有 AGENTS、skills、BuJo、证据验证和跨 session 记录。在这个前提下，值得吸收的有四项：

• Action Contract 进入 worker brief：中高风险任务先写 unchanged baseline、scope/out of scope、authority、precondition、permitted effect、invariants 和 verification；只有这些任务反复暴露稳定语义时，才再整理项目 Kernel。
• 语义影响必答：每次 review 除了看“测试过了吗”，还要问改动是否改变那六类语义，以及规则是否落在权威模块。
• semantic finding 回 plan：Hermes 在 review 里发现代码与模型冲突时，不替 Codex 当场改模型，也不强迫代码迁就旧文档，先把冲突显式交回规划判断。
• 知识晋升门槛：一次失败先进入 Evidence 或 Lesson；重复、可复核、会影响未来判断时才进入 Protocol 或 Kernel，防止 skills、memory、AGENTS 越积越重。

这四点恰好能借这套编排已有的优势，补上该流程的弱点：Codex worker 执行、Hermes 独立 review，比“同一上下文 do + check”更接近彼此独立的审查；Hermes 已经要求真实命令输出、不静默失败，可以把 Markdown 里的 procedure 变成脚本检查，而不是只靠 Agent 自觉。

同时保留五条边界：

• 不直接全局安装并替换现有 AGENTS/skills，以免和 Hermes/Codex 编排及现有项目规范重叠。
• 不一上来复制六动作、八类文档和全部词汇，先测 Action Contract 加两个 review 问题；需要长期语义时再建最小 Kernel。
• 不把所有代码类型、文件和类都本体化，也不加 graph DB、RDF、OWL。
• 不移除 BuJo roadmap；仓库“不记录未来意图”的选择只适合执行层，不适合产品与研究管理这一层。
• 没有许可证确认时，不整套复制仓库内容。

BuJo 在这里的分工是清晰的：BuJo 管方向、管产品判断和跨项目研究，repo 里的 Kernel/SPEC 管已确认、正在执行的契约。这个边界正好补上 SPEC-AGENTS 刻意不碰“未来 roadmap”留下的空白。

试点建议

先不做整套迁移，选一个边界清楚、会持续维护、但出问题代价不大的项目或独立 feature，试 5–10 次真实变更，然后复盘。

第一阶段不新增第二套状态系统，只给中高风险 worker brief 增加 unchanged baseline、scope/out of scope、authority、precondition、permitted effect、invariants 和 verification。试点中若反复出现身份、生命周期、不变量或权威落点的分歧，再把已确认事实收敛成约 100–150 行的 KERNEL.md；只保留 Concepts/Identities、Relations/Lifecycles、Action Contracts（只写用户可观察的高影响动作）、Invariants、权威地图（规则由哪个模块决定；合法副本需同输入等价验证）和 Source evidence。

流程压到四步：Hermes（或用户自己）做 plan，确认 unchanged baseline、语义影响、权威模块和验收；Codex worker 做 do，完成最小实现与测试；Hermes 独立做 check，执行行为验证、语义影响六问和规则落点审查；只有会改变以后判断的结果才 learn，进入 Evidence、Lesson、Protocol 或 Kernel。跨 session 或多 Agent 才持久化 SPEC/Slice，小改走短路径。

复盘时看几类指标：是否捕获了原本会漏掉的语义变化或错误落点；Kernel 是否出现 stale 或 contradicted；handoff 后新 Agent 是否无需重读历史就能说清边界；文档维护耗时与误阻塞次数；默认上下文大小是否持续增长；同一业务规则是否出现第二落点、合法副本是否有同输入等价验证；Evidence 里多少条最终值得晋升、多少只是一次性噪声。

停止条件也要提前想好：如果只是多填了表单而没有捕获新风险；如果 Kernel 很快变成第二份需求书；如果 Agent 开始为了适配术语而绕规则；如果语义文件与代码频繁漂移且没人 re-scan；如果小改被迫走完整六步——出现这些，就说明试点没有带来净收益，该收手而不是继续加规则。

Sources

[1] https://github.com/yibie/SPEC-AGENTS.md — yibie/SPEC-AGENTS.md [2] https://api.github.com/repos/yibie/SPEC-AGENTS.md — GitHub repository metadata [3] https://github.com/yibie/SPEC-AGENTS.md/blob/9813159a3154b553a7ed4334171675641f81b818/README.md — SPEC-AGENTS README at 9813159 [4] https://github.com/yibie/SPEC-AGENTS.md/blob/9813159a3154b553a7ed4334171675641f81b818/docs/spec-agents/WORKFLOW.md — SPEC-AGENTS workflow model at 9813159 [5] https://github.com/yibie/SPEC-AGENTS.md/blob/9813159a3154b553a7ed4334171675641f81b818/START.md — SPEC-AGENTS Start review at 9813159 [6] https://github.com/yibie/SPEC-AGENTS.md/blob/9813159a3154b553a7ed4334171675641f81b818/skills/plan/SKILL.md — SPEC-AGENTS plan action at 9813159 [7] https://github.com/yibie/SPEC-AGENTS.md/blob/9813159a3154b553a7ed4334171675641f81b818/skills/check/SKILL.md — SPEC-AGENTS check action at 9813159 [8] https://github.com/yibie/SPEC-AGENTS.md/blob/9813159a3154b553a7ed4334171675641f81b818/skills/learn/SKILL.md — SPEC-AGENTS learn action at 9813159 [9] https://github.com/yibie/SPEC-AGENTS.md/blob/9813159a3154b553a7ed4334171675641f81b818/CHANGELOG.md — SPEC-AGENTS changelog at 9813159 [10] https://github.com/yibie/SPEC-AGENTS.md/blob/9813159a3154b553a7ed4334171675641f81b818/docs/adr/0005-kernel-drift-detection.md — ADR 0005 Kernel drift detection [11] https://github.com/yibie/SPEC-AGENTS.md/blob/9813159a3154b553a7ed4334171675641f81b818/docs/adr/0006-single-authority.md — ADR 0006 Single authority [12] https://github.com/yibie/SPEC-AGENTS.md/blob/9813159a3154b553a7ed4334171675641f81b818/research/experiments/ontology-graph-pilot/RESULTS.md — Ontology graph projection pilot results [13] https://github.com/yibie/SPEC-AGENTS.md/blob/9813159a3154b553a7ed4334171675641f81b818/research/experiments/project-knowledge-routing-pilot/run_pilot.py — Project knowledge routing pilot runner [14] https://github.com/github/spec-kit/blob/5aa8bea7823dcd056f111f847bf2d576bad3f0a5/README.md — GitHub Spec Kit README at 5aa8bea [15] https://github.com/agentsmd/agents.md/blob/6ae22720966e9cca6b2c2dd0780fb7265a87a46c/README.md — AGENTS.md format README at 6ae2272 [16] https://www.palantir.com/docs/foundry/ontology/overview — Palantir Ontology overview [17] https://www.palantir.com/docs/foundry/architecture-center/ontology-system — Palantir Ontology system [18] https://www.palantir.com/docs/foundry/use-case-life-cycle/distilling-functional-requirements — Palantir functional requirements [19] https://martinfowler.com/bliki/DomainDrivenDesign.html — Martin Fowler on Domain-Driven Design [20] https://martinfowler.com/eaaDev/EventSourcing.html — Martin Fowler on Event Sourcing [21] https://github.com/yibie/SPEC-AGENTS.md/blob/9813159a3154b553a7ed4334171675641f81b818/bin/spec-agents — SPEC-AGENTS installer at 9813159 [22] https://github.com/yibie/SPEC-AGENTS.md/blob/9813159a3154b553a7ed4334171675641f81b818/STATUS.md — SPEC-AGENTS repository status at 9813159 [23] https://github.com/yibie/SPEC-AGENTS.md/blob/9813159a3154b553a7ed4334171675641f81b818/research/experiments/project-knowledge-routing-pilot/RESULTS.md — Project knowledge routing pilot results [24] https://github.com/yibie/SPEC-AGENTS.md/blob/9813159a3154b553a7ed4334171675641f81b818/tests/protocol-cost-comparison.sh — SPEC-AGENTS protocol cost comparison script at 9813159 [25] https://github.com/yibie/SPEC-AGENTS.md/blob/9813159a3154b553a7ed4334171675641f81b818/AGENTS.md — SPEC-AGENTS AGENTS.md at 9813159 [26] https://github.com/yibie/SPEC-AGENTS.md/blob/9813159a3154b553a7ed4334171675641f81b818/skills/do/SKILL.md — SPEC-AGENTS do skill at 9813159 [27] https://github.com/yibie/SPEC-AGENTS.md/blob/9813159a3154b553a7ed4334171675641f81b818/docs/spec-agents/single-authority.md — SPEC-AGENTS Single Authority Protocol at 9813159