从“会写代码”到“控制软件生长”：Pine Field 的 AI-Native SDLC 实践

过去一段时间，我们在 SpatialSmart、Agent、Omni、Spec Compilation、自动化测试和 Agent Eval 上做了不少看似分散的工作。它们分别解决插件安装、规格表达、回归测试、模型评测、发布门禁和运行观测的问题。

直到最近，我们才越来越明确地意识到：这些并不是几套独立的工程工具，而是在共同搭建一种新的软件开发认知模型。

它要解决的问题不是“怎样让 AI 多写一点代码”，而是：

人只有很短的上下文，不可能决定实现中的每个细节。我们如何只做那些真正重要的判断，再让 Agent 从这个稳定的中心向外展开，并且让展开后的每一层都可追踪、可验证、可回退？

这正是我们理解的 AI-Native SDLC。

代码已经不是最稀缺的部分

Anthropic 在 The AI-Native SDLC playbook 中提出：当 Agent 能快速完成实现，瓶颈会从 Build 向两侧移动——变成需求澄清、设计判断、评审、测试、发布和治理。传统 SDLC 的控制方式原本建立在“代码由人缓慢生产”这个前提上；当这个前提改变，逐行人工检查、阶段性交接和周期性审批就会越来越跟不上软件变化的速度。

Anthropic 强调让每个阶段提交下一阶段可读的制品；Pine Field 希望在此基础上再解决两个问题：如何把制品之间的语义映射机械化，以及如何让同一套组织能力跨 Agent Harness 复现。

这与我们的实际感受高度一致。

Agent 可以在几十分钟内改动几十个文件，但人无法在同样时间里重新理解整个系统。更危险的是，代码看起来可以运行，并不意味着它仍然忠于最初的业务意图、架构边界和风险约束。

所以我们真正需要控制的，不是 Agent 的每一步操作，而是软件如何从一个决定开始生长。

我们把它称为“认知着陆”

人的优势不是持有更多 token，也不是记住每个文件，而是判断意义：我们为什么做这件事，系统承诺什么，哪些边界不能跨越，哪些风险不可接受，哪些决定一旦做出就很难逆转。

Agent 的优势则是展开：读取仓库，探索依赖，分解任务，实现细节，运行测试，诊断失败，并把结果重新组织成可审阅的制品。

因此，人和 Agent 之间不应该是“人先写一份足够详细的任务单，Agent 照着执行”。更合理的分工是：

• 人决定稳定的中心：结果、领域含义、不可逆取舍、风险偏好和明确边界；
• Agent 展开可逆的外围：探索、分解、实现、测试、诊断和候选方案；
• 工程基础设施持续证明：外围的每一次扩张仍然与中心相连。

这里的“中心”不是一段更长的 Prompt，而是一组能在生命周期中保持身份、接受修订并留下证据的制品。所谓 Grounding SDLC，就是把人的有限认知着陆成 Agent 和自动化系统都能消费的工程对象。

四层控制面：从语义到运行证据

我们当前的 AI 工程基础设施可以理解为四层。它们不是四个串行阶段，而是四种同时存在的控制责任。

1. Spec Compilation：守住“我们到底决定了什么”

Anthropic 建议让每个阶段结束时提交一个下一阶段可读的制品，例如 intent.md、spec.md、plan.md、代码与测试、PR 评审结果和事故记录。commit chain 同时构成审计链。

在 Pine Field，我们正在把这个思路进一步形式化为一条规格编译链：

Grill 对话 → ADR → Contract → Full Tech Spec → Code Claim → Evidence

它不是把文档写得更长，而是把不同性质的信息分开：

• ADR 保存“为什么这样决定”，一旦接受便不再改写；
• Contract 保存“系统现在必须满足什么”，用稳定的意图、约束和验收项表达当前真相；
• Full Tech Spec 保存“这一次怎样实现并证明它”；
• Code Claim 把规格反向链接到代码入口与测试；
• Evidence 决定一份实现是否有资格进入 verified。

这里最重要的一点，是人的决定不会在 Agent 展开实现时被悄悄稀释。Contract 中的 I-*、C-*、A-* 必须进入 Trace Matrix；缺少来源、测试或反向 claim 时，状态不能被提升为已验证。

这条编译链之外还有一份不能忽略的 Grounding：Contract 表达系统必须满足什么，Architecture 表达系统现在如何组成。 前者拥有规范语义，后者为 Agent 展开实现提供当前状态视图；二者通过稳定规格 ID 关联，但不能相互替代。否则 Agent 可能忠实执行了一份决策，却把它落进了一个并不存在的系统结构。

Anthropic 的 plan.md 在我们当前模型里主要由 Full Tech Spec 的实施设计、代码索引和验证计划承担。Coding Agent 仍会在会话中产生执行计划，但是否把它独立提交、以及偏离时如何与 Full Tech Spec 同步，尚未标准化，属于 [WIP]。

当前状态：机制已实现，项目级试跑中。 Spec 制品模型、状态机、Architecture 文档树、模板、specctl compile / claim / validate 和 Spec Compilation Plugin 已经存在，并已开始在真实规格中试跑；它还不是所有项目不可绕过的组织级默认入口。

[WIP] 从业务意图到 ADR/Contract 的入口还没有成为所有项目统一的默认入口；规格 ID 与代码、测试、CI 门禁之间的自动关联仍在扩展。

[TBD] 对跨多个仓库的意图，最终以需求系统还是 Git 仓库作为唯一事实源，团队尚未形成统一约定。最低要求应是双方保存稳定 ID 与 commit SHA 的双向链接。

2. Omni Plugin：让组织能力跟着任务到达 Agent

仅有 Spec 还不够。Agent 能否正确行动，还取决于它在当次执行中实际获得了哪些 Skill、Agent、MCP、Hook 和项目规则。

Omni 的作用不是创造另一个统一 Agent Runtime，而是提供跨 Harness 的插件依赖、解析与投影层。同一套 Plugin Package 可以被声明在 omni.toml 中，经由 lockfile 固定解析结果，再投影到 Claude Code、Codex 等不同 Harness 能识别的位置。

这使“组织知识”不再只是 Wiki 中的一段说明，而成为可安装、可版本化、可复现的执行能力：

• Skill 承载重复工作的方法和约束；
• Agent 定义可委派的角色；
• MCP 连接外部系统与证据源；
• Hook 把规则放在行为发生的边界执行；
• lockfile 记录项目解析并安装了哪些 Plugin 及其来源，使能力环境可以复现。

需要特别区分：安装了什么，不等于一次 Agent 执行实际使用了什么。 后者仍需要 transcript、Hook trace 和 Eval trial 来证明，这是当前证据链的 [WIP]。

我们内部讨论的 Spec Completion，目前主要落在 Spec Compilation Skill 的“语义补全”阶段。它并非简单补全文档，而是根据已有事实、仓库状态和规格类型，识别缺失的边界、失败处理、迁移、观测与验证设计；对于不可逆、跨边界或高成本问题，回到人；对于可逆实现细节，允许 Agent 做出假设并显式记录。这样可以避免把一个仍在形成中的机制误写成已经独立发布的 Plugin。

Agent 项目中的 main-dev Plugin 则展示了另一种 Grounding：Delivery Orchestrator 用 .claude/project-state.json 保存七个交付阶段、跨域 ID、产物和 pendingHumanActions，明确规定“持久化状态优先于 LLM 记忆”；Hook 在用户提交任务、工具调用前和 Agent 停止时分别检查入口、阶段前置条件与最终状态。它把原本只存在于长对话里的进度和依赖，转换为 context compaction 之后仍可恢复、也可被程序检查的状态。

我们曾遇到过一个很具体的问题：在某些高版本模型组合下，预期的 Skill 没有被调用。Plugin 已经安装、能力也能被 Harness 发现，但 Agent 的行为仍然偏离了设计。修复后，评测中的 correctness 从 87 提升到 95，process 从 81 提升到 92，工具错误率从 13% 降到 3%。这个案例把三层责任分得很清楚：Omni 证明能力可到达，Eval 证明能力被正确使用，CI 才决定这种变化能否被接受。

当前状态：安装机制已实现，行为控制在项目级试跑。 Omni 已具备 manifest、依赖图、override、lockfile、Claude/Codex adapter，以及 direct/native 安装模式；核心解析、适配器、CLI 和 E2E 均有分层测试。Spec Compilation 已经能够作为 Plugin 分发给 Coding Agent；main-dev 也已经用持久化 project state 和阶段 Hook 约束空间应用交付流程。

[WIP] Plugin 的“安装正确”已经能被测试，但“安装后是否在真实任务中稳定地产生正确行为”还没有全面接入持续 Agent Eval。

[WIP] main-dev 的阶段门禁目前服务于特定的空间应用交付流程，其中 Stop Hook 对自身异常采用 fail-open；它还不是可以替代 CI 门禁的组织级强保证。真正不可绕过的控制仍应在仓库和流水线侧重复执行。

[TBD] 我们还没有确定组织级 Plugin 的兼容性承诺、废弃策略和强制升级窗口。未来 lockfile 不只要回答“装了什么”，还应能关联“在哪组 Eval 上证明过”。

3. 分层自动化测试与 Agent Eval：证明展开没有漂移

传统测试主要回答“这段确定性代码是否符合断言”。Agent 系统还需要回答另外两类问题：

1. 最终结果是否正确；
2. Agent 是否以可接受的过程得到这个结果。

这也是为什么我们同时推进分层自动化测试与 Agent Eval。

在 SpatialSmart Electron 重构中，测试不能只停留在组件单测。不同层级承担不同的故障定位责任：纯逻辑和协议由单元测试覆盖；进程边界、IPC、状态同步由集成测试覆盖；浏览器和 Electron 关键路径由端到端测试覆盖；界面变化由视觉回归给出证据；打包、安装与真实运行环境则需要发布级 smoke test。

Agent Eval 则把 task、trial、transcript、outcome 和 grader 组织成可重复实验。确定性检查适合验证 schema、工具调用、状态与最终文件；对于过程质量、任务完成度和开放式结果，再使用 rubric grader。Anthropic 在 Demystifying evals for AI agents 中也强调，能力评测与回归评测目的不同，Coding Agent 的评测尤其依赖稳定环境、清晰任务和可靠 grader。

上面的结果说明 evaluator 已经能够暴露能力变化，但它还不能自动成为可靠的回归基线。要比较一次 Plugin、Prompt、模型或工具链改动，我们仍需要冻结任务集、环境、grader 版本和 trial 记录，这是 [WIP]。

当前状态：基础机制已实现，覆盖范围持续扩展。 团队已经具备 Agent evaluator、重试机制、execution-readiness 测试，并持续增加浏览器集成、视觉回归、结果汇总与问题分诊；Omni 自身也有 unit、adapter、CLI 和 E2E 测试分层。

[WIP] SpatialSmart Electron 重构中的完整测试金字塔仍在建设，特别是跨主进程、渲染进程、Agent 会话、预览运行时和打包产物的端到端追踪。

[WIP] 真实事故和重复人工纠错还没有自动沉淀成回归 Eval；Spec 的每个 A-* 也还不能稳定生成或绑定对应测试。

[TBD] 对 Agent 的过程质量，我们还没有一套跨项目统一、足够抗 grader 漂移的评分标准。近期更适合坚持“少量稳定硬指标 + 项目特定 rubric”，而不是追求一个万能总分。

4. CI/CD 与 Runtime：把证据变成门禁和反馈

如果测试和 Eval 只在本地偶尔运行，它们还不是 SDLC 控制面。只有当证据能够阻止不合格变更进入下一个环境，并且生产信号能返回规格层，生命周期才真正闭合。

Pine Field 已完成 Alpha/Beta 发版流程和 Matrix 核心库门禁初版，也已上线 SpatialSmart 可观测性和日志查询能力；Alloy、Loki、Tempo 链路及端到端追踪仍在推进。我们希望形成的不是一条只会“构建—部署”的流水线，而是一条证据流水线。

目标证据流水线 [WIP]：

Spec / Plugin 变化
  → 确定性检查与分层测试
  → Agent Eval
  → 风险分级评审
  → Alpha / Beta / Production
  → Logs / Traces / Control Bands
  → Incident / New Intent / Contract Revision

Anthropic 的安全实践提供了一个重要边界：Agent 可以承担确定性扫描和窄职责评审，但关键和高风险代码仍需人负责；自动化身份应最小权限、没有生产凭证，写入通过 PR 完成，部署与回滚必须可演练。详见 How Anthropic secures its AI-native SDLC。

当前状态：部分实现。 Alpha/Beta 发布、核心库门禁、自动化测试和可观测性基础已经存在。

[WIP] Spec、Plugin、Eval、CI 和运行 trace 还没有被统一的变更 ID 串成完整证据链；风险等级也尚未系统映射为不同的审批和 Agent 自治级别。

[WIP] 从监控异常自动形成结构化 Incident，再触发新的 Intent/ADR/Contract 修订，目前仍是目标闭环，而不是默认行为。

[TBD] 哪些低风险变更可以由 Agent 自动合并或自动进入 Beta，哪些必须由架构、安全或发布责任人批准，需要形成团队级策略。

一次变更应该怎样穿过这四层

把四层合起来，一次理想的变更不会从“让 Agent 改一下”开始，而会经历以下过程：

1. 发起人用自己的语言描述问题、期望结果、范围和风险。
2. Agent 通过 Grill 识别 Known、Assumed、Unknown、Decided，只把会改变边界或产生不可逆后果的问题交还给人。
3. 决策被保存为 ADR 与 Contract；稳定 ID 进入 Full Tech Spec 的 Trace Matrix。
4. Omni 根据 manifest 安装并投影指定版本的 Spec Compilation 与领域 Plugin；Coding Agent 在 Spec Compilation 流程中执行确定性编译和语义补全。
5. Coding Agent 读取规格和仓库，形成可审阅的实施计划，再展开代码与测试。
6. Code Claim 把实现入口反向链接到 Tech Spec；分层测试与 Agent Eval 产生证据。
7. CI 根据确定性测试、Eval 基线、风险等级和人工审批决定能否进入下一环境。
8. 运行日志、trace、控制带异常和人工反馈形成 Incident；如果它暴露的是需求或边界错误，就返回新的 Intent/ADR/Contract，而不是只在代码层打补丁。

其中 1–3 稳定心智中心，4–6 扩展实现，7–8 检验并校正扩散。人不需要决定每个细节；在目标模型中，每个具有行为影响的细节，都应该能够追溯到某个明确决定、显式假设或验证证据。

人的责任没有减少，而是变得更集中

AI-Native SDLC 容易被误解成“让 Agent 接管整个研发流程”。我们的理解恰好相反：它要求更清楚地声明哪些判断只能由人承担。

人需要负责：

• 结果是否值得追求；
• 领域语义是否正确；
• 系统边界和非目标；
• 不可逆或高成本的架构取舍；
• 安全、合规和发布风险是否可接受；
• 证据是否足以支持进入下一阶段。

Agent 可以提出方案、补全遗漏、模拟反例、执行验证，却不能替人承担责任。最成熟的自动化不是消除人，而是让人的注意力集中在真正需要判断的门上。

接下来最值得做的，不是再增加一个 Agent

我们下一阶段的工作重点应当是连接，而不是堆叠：

1. 建立统一 Change ID。 让 Intent、ADR、Contract、Tech Spec、代码 claim、测试、Eval、PR、部署和 trace 可以被同一条查询串联。
2. 让验收项变成可执行对象。 逐步把 Contract 的 A-* 编译为测试、Eval case 或人工检查项，并在 CI 中报告覆盖缺口。
3. 为 Plugin 建立行为级回归。 Omni 验证安装结构；Agent Eval 验证装载后的能力行为。两者需要共享 Plugin 版本和 Eval 基线。
4. 定义风险分级自治。 把变更按 blast radius、数据敏感度、可回滚性和证据充分度分级，决定 Agent 可以执行、提 PR、进 Beta 或必须停在人审的边界。
5. 把运行事故写回认知中心。 Incident 不应只产生修复 ticket；它还要判断究竟是实现偏差、规格缺口还是原始决策错误，并进入对应层级修订。
6. 衡量 SDLC 本身。 除了代码质量，还应观察 intent-to-spec 时间、首次实现通过率、规格后置返工、Eval 回归率、变更前置时间和回滚恢复时间。

Change ID、可执行验收和 Plugin 行为回归已有可以继续扩展的技术基础；风险自治、事故回写和 SDLC 度量仍需要团队在真实项目中形成策略，而不能只靠工具设计完成。

结语：稳定中心，允许扩散

我们最终要控制的不是 Agent，而是软件变化的认知边界。

人的上下文永远有限。好的工程系统不要求人把所有实现细节提前想完，而是帮助人做少量、关键、可负责的决定；再让 Agent 和自动化基础设施把这些决定扩散到代码、测试、发布与运行现场，并用连续证据证明它们没有在途中失真。

Spec Compilation 让意图拥有稳定结构，Omni 让组织能力可分发和复现，分层测试与 Agent Eval 让实现可证明，CI/CD 与 Runtime 让证据成为门禁并返回反馈。

当这四层真正连成闭环，AI-Native SDLC 才不只是“开发更快”，而是一种新的软件控制方式：

心智中心保持稳定，软件细节可以快速扩散；人的判断保持稀缺而明确，Agent 的执行可以广泛而可证。