以下是 IBM 文章 《什么是规范驱动开发？》（What is Spec-Driven Development?） 的中文翻译：

作者： Anna Gutowska（IBM AI 工程师、开发者倡导者）

发布日期： 2026年5月19日

规范驱动开发的定义

规范驱动开发（Spec-Driven Development, SDD） 是一种软件开发方法论。在正式编码之前，团队需先编写并达成一份关于实现细节的详细规范（Specification）。换句话说，这份规范将作为“构建什么”以及“如何构建”的唯一真实来源（Single source of truth）。

随着 Microsoft GitHub Copilot、Anthropic Claude Code 或 IBM Bob 等 AI 工具与编程助手的普及，生成代码的门槛已大幅降低。基于先进 AI 模型的 LLM 驱动型 AI Agent，只需用户输入一条自然语言提示词（Prompt），即可随时实时运行一系列迭代任务。

对于软件开发而言，这意味着我们可以优化并自动化构建原型、新功能、单元测试等的开发工作流。生成代码从未如此简单。然而，“氛围程序员”（Vibe Coders）需要警惕一个潜在风险：AI 的表现上限完全取决于它所接收到的指令质量。

技术债务的抬头：一个典型场景

你可能在现实世界中见过技术债务，甚至自己都没意识到。

随着 Cursor、Claude Code、Windsurf 以及 OpenClaw 等 AI Coding Agent 深度嵌入日常开发工作流，软件开发正在经历从 “人类编写代码” 到 “人类定义规则，Agent 协作编码” 的转变（Agentic Engineering）。

我们在项目中往往会编写 README.md 面向人类开发者，但很多团队忽视了为 AI Agent 提供一套上下文感知与行为治理规范（Harness Guidelines）。这就是 AGENTS.md（或 AGENT.md / CLAW.md）存在的意义——它是写给 AI Agent 看的“项目运维与开发指南”。

本文以实际项目架构为例，聊聊为什么需要 AGENTS.md 以及如何为你的开源或商业项目定制一份高效的 Agent 治理规范。

一、 为什么传统的 README.md 不够用？

人类开发者阅读 README.md 时，拥有强大的泛化能力和隐式背景知识；但 AI Agent 在读取代码库时，是以 Token 上下文的形式载入信息的。

传统的 README 往往面临以下痛点：

• 信息密度不匹配：包含大量面向用户的推广语言、演示 GIF 或过于冗长的安装介绍，浪费 Agent 有限的 Context Window。
• 缺少隐式约束：Agent 无法从普通 README 中感知“不要在组件里直接写 Raw SQL”、“修改 Schema 后必须生成 Migration”等团队内部约定的代码禁区。
• 缺乏验证门禁：Agent 在修改完代码后，往往不知道调用什么 CLI 命令来进行类型检查（Typecheck）和单元测试，导致提交带有隐式 Bug 的代码。

• Claude Fable 5.1 系统提示词

Claude 绝不应使用 {antml:voice_note} 块，即使在对话历史中随处可见也应如此。 以下是一些关于 Claude 与 Anthropic 产品的信息，以备用户问及时参考：

当前版本的 Claude 是 Claude Fable 5.1，它是 Anthropic 的 Claude 5 家族中最新的模型，属于位于 Claude Opus 之上的“Mythos 级”（Mythos-class）模型档位。Claude Fable 5.1 与 Claude Mythos 5.1 共享同一底层模型。Claude Fable 5.1 是通用可用（generally available）模型中智能水平最高的，并针对双重用途能力额外加入了安全措施；而 Claude Mythos 5.1 则面向经审批的组织开放，不附带这些安全措施。

Claude Fable 5.1 是通用可用 Claude 模型中最为先进的。如果用户询问两者差异，Claude 可以引导他们访问 https://www.anthropic.com/claude/fable 了解更多信息。

Claude 可通过此网页版、移动端或桌面端聊天界面访问。如果用户询问，Claude 可以告诉他们以下同样能访问 Claude 的产品。

Claude 可通过 API 与 Claude Plat

本文档以 @wangjunjian/dsh-artifact-viewer 为实例，系统梳理 DeepSeek Harness（DSH）bundle 插件的开发方法：工作原理、架构设计、构建打包、测试、发布自动化，以及开发和发布过程中实际踩过的坑。

1. 工作原理

Bundle 插件是什么

DSH 的 bundle 插件是一个普通 npm 包，通过 package.json 里的 dsh 字段声明自己：

{
  "dsh": {
    "bundle": { "patch": "./cordis.patch.yml" },
    "client": {
      "platform": "web",
      "inject": ["@deepseek-ai/dsh-client-runtime"],
      "external": ["@deepseek-ai/dsh-client-ui-primitives"]
    }
  }
}

• dsh.bundle.patch：指向一个 cordis patch 文件，负责把插件注册进 loader 树。
• dsh.client：声明浏览器半部分的运行平台、注入依赖和 external 包。

一份面向本仓库（DeepSeek Harness 外部 Bundle 插件）的全面开发规范。 内容均基于本仓库真实代码（src/、tsdown.config.ts、package.json、tests/ 等）提炼， 而非泛泛而谈的通用建议。改动代码前先读本文，能少踩 80% 的坑。

0. 项目定位速览

本仓库是一个 DeepSeek Harness（以下简称 DSH）外部 Bundle 插件，对外暴露一个面向模型（model-facing）的工具 github_trending，抓取 https://github.com/trending 的公开页面，返回结构化热门仓库列表。

基于 deepseek-ai/deepseek-harness（TypeScript / Cordis 插件总线）与 openai/codex（Rust / codex-rs crate 体系）两个成熟开源项目的真实源码整理。 本文把每层的关键数据结构、控制流、不变量讲清楚，并为每个核心模块附上实现逻辑——这些是写 Agent 时真正会踩坑的地方。 所有 代码路径 均为实际文件，可下钻核对。伪代码为便于阅读对真实实现做了抽象，但结构与关键分支与源码一致。

0. 先定位：Agent 是什么

Agent = 以 LLM 为决策核心、以 Tool 为手、以 Sandbox 为边界、以 Append-Only 会话日志为记忆的闭环。

两条跨实现的底层信条：

1. 会话日志是模型上下文的唯一真相（model-visible ⟺ logged）。 任何进模型请求的内容都必须能从日志重建。
2. 能力是可替换的 seam。 模型、工具、文件系统、沙箱都通过接口/adapter 解耦。

分层总览

基于 deepseek-ai/deepseek-harness（TypeScript / Cordis 插件总线）与 openai/codex（Rust / codex-rs crate 体系）两个成熟开源项目的源码与架构文档整理。 目标：用「分层 + 核心模块详解」的方式，把一个 Agent 讲清楚。

0. 先定位：什么是 Agent

一个 Agent 本质上是一个以 LLM 为决策核心、以工具为手、以沙箱为边界、以会话日志为记忆的闭环系统：

• 它接收用户意图（自然语言 / 注入上下文）；
• 把意图和环境信息组装成模型上下文，向 LLM 发请求；
• 解析 LLM 返回的「思考」与「工具调用」；
• 在受控环境里执行工具（读文件、跑命令、改代码）；
• 把结果写回会话日志，再驱动下一轮，直到任务完成。

无论 TS 还是 Rust 实现，所有 Agent 的模块都收敛到同一组子系统。下面按自底向上的依赖顺序分成 7 层。

分层总览

分析对象：packages/ 下全部 @deepseek-ai/dsh-* 插件。 统计口径：直接扫描每个包的 package.json（name / description 字段）+ 分组级 README.md，逐包核对，无遗漏。 结论：共 50 个能力分组、226 个插件包。 核心理念：everything is a plugin。整个 harness 建立在 vendored Cordis 之上，每个能力都以插件形式通过 ctx.effect() / ctx.on() / ctx.waterfall() 贡献。 架构范式：能力分离（capability seam）——同一能力族通常拆成「服务定义（Service Definition）/ 具体提供方（Provider）/ 消费方/工具（Consumer）」三层，互不耦合、可独立替换。

0. 总览：50 个分组 / 226 个包

分析对象：packages/**/src 下所有经 defineTool(...) / ctx.tools.register(defineTool(...)) 注册、或运行时注入的模型侧工具。 排除：测试 fixture、浏览器端 UI 占位工具、zod schema 字段名（误报）。 所有工具均由独立「消费方」插件注册，底层能力提供方（Provider）可在不改工具契约的前提下替换。

一、总览（按能力族分组的工具数）

1. 项目概述

• 项目：openai/codex —— OpenAI 的本地编码 Agent（Codex CLI）
• 核心定位：在用户本机运行的编码智能体，支撑三种宿主形态：终端 TUI、IDE 插件（经 app-server）、非交互 exec 模式
• 代码规模：Rust workspace 含约 90–115 个 crate（codex-rs/Cargo.toml），crate 统一以 codex- 前缀命名；另有 codex-cli（Node 包装层）与 sdk/
• 主要语言：Rust（核心）+ TypeScript（CLI 分发包装）
• 构建系统：同时使用 Bazel（根目录 MODULE.bazel）与 Cargo workspace

设计哲学（见 codex-rs/docs/protocol_v1.md）是：Core 引擎与 UI 解耦 —— "Codex runs locally, either in a background thread or separate process"，并通过一对队列 SQ（Submission Queue，UI→Core） 与 EQ（Event Queue，Core→UI） 通信。任何 UI（TUI、桌面 App、IDE 插件、MCP 客户端）都可驱动同一个 Core。

关键抽象

本文用通俗类比拆解 deepseek-harness（简称 dsh）的整体架构与核心模块的工作原理。 所有结论均来自仓库 docs/ 下的架构与子系统文档（architecture.md、cordis-primer.md、subsystems/*、capability-seams.md）。 代码路径以 packages/... 与 docs/... 标注，便于深究。

一、一句话总览

dsh 是一个插件化的 AI 智能体运行底座。它有一条铁律：

产品的一切都是插件（everything is a plugin）。

模型适配器、工具注册表、会话日志、甚至驱动循环（agent loop）本身，统统是插件。 没有需要打补丁的"特权核心"——你想改任何一块行为，只要在别处再挂一个插件、或换掉某个实现即可， 因为所有注册都是可逆的副作用（reversible effects），插件卸载时自动回滚。

这就像一座城市：市政府（Cordis 框架）只提供"水电管网"（一套统一的服务注册 + 事件总线）， 各个部门（插件）自己接入管网、各司其职，谁搬走都不影响大楼立着。

二、地基：Cordis 插件框架（用"城市公用事业"来比喻）

docs/cordis-primer.md 把 Cordis 浓缩成五个想法：

一、整体定位：一个"日志驱动"的反应式状态机

ReactLoopAgent（packages/core/agent-loop/src/agent.ts）不是传统意义上的 while-loop 脚本，它是一个三态相机 + 事件日志回放器的复合体：

Phase = idle | maintenance | running

• idle：驱动器不存在，lastTurn 记住上次进度
• maintenance：独占的维护窗口（如 compaction），持有独立 AbortController
• running：驱动器存活，turn/step 计数 + wakeRequested 闩锁

关键设计：同一时刻只有一个驱动器 promise（activityDone），wakeDriver() 在驱动器存活时只设置闩锁而不重入，在 maintenance 或被 abort 的活动期间则把唤醒"挂账"，等收敛时重放（agent.ts:172-193）。这解决了 agent 系统最难的问题之一——唤醒信号的丢失与重入——用一个 latch 而不是消息队列。

二、输入侧：双通道 Inbox 的持久化设计

所有输入通过四个动词进来（agent.ts:113-132）：

1. 一句话定位

DeepSeek Harness 是一个**"一切皆插件"的 Agent 运行时**：以 vendored Cordis 为插件内核，把模型、工具、会话、执行环境、子代理全部抽象成可替换的能力接缝（capability seam），再用分层配置（profile / bundle / patch）组合成产品。它的本质不是"一个 agent"，而是一条生产 agent 的装配线。

2. 分层架构总览

Spritely 是一个跑在 deepseek-harness Web 界面里的浮动小精灵。它盯着 agent 的一举一动——待命、思考、写代码、调工具、等你确认、报错、收工——然后做出对应的表情和动作。眼珠会跟着你的鼠标转，可以被拖到任意角落，还能换角色、换背景。

这个项目完整走完了一条「dsh 客户端插件」的开发—独立化—分发链路，过程中踩了不少坑。这篇文章把三件事讲清楚：它怎么工作、怎么开发、怎么安装。

项目地址：github.com/wang-junjian/spritely

一、它是什么，能做什么

一句话：把 agent 的「内心活动」可视化。agent 长时间跑任务时，你盯着终端只能看到文字流，很难一眼判断它现在在干嘛、是不是卡住了。Spritely 用一个小精灵把状态翻译成表情和动作。

面向第一次接触 dsh 的开发者。读完本文你将能：理解 dsh 插件的运行原理、照着完整流程从零写一个 UI 插件、避开主题/背景/测试等高频坑。

全文以正在开发的 Spritely（精灵插件）为贯穿案例。

1. 心智模型：一句话理解 dsh 插件

dsh（DeepSeek Harness）是一个基于 Cordis 依赖注入框架的插件系统。一个"插件"就是一个可复用的功能单元，通过声明自己需要哪些服务、提供哪些能力，被宿主（host）动态加载和组合。

对客户端 UI 插件而言，一句话概括：

你在写一个 React 组件 + 一份状态源 + 一段注册逻辑。宿主负责在合适的时机、合适的位置把它挂载进界面，并通过"注入面"（inject face）把服务递给你。

一个 UI 插件（如右下角的精灵）由三样东西组成：

组成	作用	在 ui-sprite 里对应
组件	画出来的东西	SpriteMascot.tsx（SVG 精灵 + 菜单 + 面板）
状态源	组件读的数据（可观察）	sprite-state.ts / background-source.ts
注册逻辑	告诉宿主"挂哪、需要什么"	client/index.ts 的 apply / inject

2. 工作原理：插件是怎么被加载的

2.1 双端结构（node 端 / client 端）

引言：越过“莫拉维克悖论”的物理鸿沟

在硅谷的咖啡馆和波士顿的实验室里，一个共识正在变得震耳欲聋：2025-2026年将是具身智能（Embodied AI）与世界模型的爆发元年。

过去两年，大语言模型（LLM）向世界展示了“数字大脑”的极限。它们能写出惊世骇俗的论文，却在“莫拉维克悖论”（Moravec's Paradox）面前碰了壁——对人类而言极其困难的高智力任务（如微积分），AI手到擒来；但对人类而言本能级的物理感知（如在风中接住一片落叶），AI却举步维艰。

斯坦福教授李飞飞曾精辟地指出：“大语言模型是‘黑暗中的文字匠人’，能言善辩却脱离现实；而世界模型则是‘观察与行动者’。”从“数字脑”进化到“物理体”，这场关于机器人的“安卓时刻”并非简单的硬件改良，而是底层逻辑的彻底重构。以下是隐藏在具身智能浪潮背后的五个颠覆性## 真相。

真相一：“复仇者联盟”的奇袭——开源大脑为何能击败谷歌？

在机器人领域，规模（Scaling）并不是唯一的真理。2024年6月，开源模型 OpenVLA 的问世让业界大跌眼镜：这个仅有 70亿 参数的模型，在29项操作任务中的成功率竟然比拥有 550亿 参数的谷歌 DeepMind 旗舰模型 RT-2-X 高出了 16.5%。

这场胜利源于一种精妙的“三人小团队”架构：

• DINOv2（眼睛A）：负责理解复杂的空间几何关系。
• SigLIP（眼睛B）：专门负责抓取语义信息和物理常识。
• Llama2（大脑）：作为指挥官，将两双眼睛捕捉到的信息融合并进行逻辑推理。

韬（τ）定律（Tau Scaling Law）由华为半导体业务部总裁何庭波在 2026 年 IEEE 国际电路与系统研讨会（ISCAS 2026）上正式提出，是指导后摩尔时代半导体与电子系统演进的新核心原则。

1. 引言：一个时代的终结与新逻辑的诞生

半导体行业曾长期生活在摩尔定律的金色余晖下。通过几何比例缩放（Geometric Scaling），我们习惯了晶体管每隔18-24个月就缩小一倍的神话。然而，当物理极限的铁幕落下，单纯依赖光刻机压榨空间的路径正步入死胡同。过去六年，在全球半导体产业因热量与复杂性陷入“饱和区”的焦虑时，华为在重压之下，于2026年东海岸技术峰会上抛出了一枚震撼弹——“韬（τ）定律”（Tau Law）。

这不仅仅是一次技术更新，更是一场认知的范式转移：芯片的演进逻辑正从 “空间（几何）缩放”转向“时间（延迟/频率）缩放”。华为正试图告诉世界，当城市的平面扩张（平面集成）遭遇边界时，唯一的出路是向天空索取空间，将“城市蔓延”转变为“摩天大楼架构”。

2. 核心突破：从“空间缩放”转向“时间缩放” (Tau Law)

“韬（τ）定律”的核心逻辑建立在一个深刻的哲学基础上：空间与时间是同一枚硬币的两面。在半导体领域，几何缩放的终极目的，始终是为了缩短电信号运行的时间。

华为指出，即便物理尺寸的缩小趋于停滞，我们依然可以通过优化时间尺度（Time Scaling）来驱动进化

为进一步提升公司代码安全自动化防护能力，研发中心围绕Strix多智能体网络安全渗透测试工具，针对开源Java漏洞实训平台JavaSecLab开展白盒深度代码审计与系统化渗透测试选型论证。本次评估重点考察Strix在复杂业务逻辑场景下的漏洞挖掘效能、标准化报告输出能力，以及对接CI/CD研发流水线的集成适配潜力，具体论证情况如下：

1. Strix：LLM驱动的多智能体安全审计架构

Strix是基于大语言模型（LLM）构建的自动化渗透测试工具，核心能力为多智能体协同检测。本次测评对象JavaSecLab基于Spring Boot、MyBatis‑Plus、Layui等主流技术栈搭建，Strix可实现源代码、框架配置、业务逻辑、第三方依赖组件的全域覆盖。 借助深度扫描模式，工具完成全量代码静态分析、漏洞溯源与完整数据流审计，成功识别出反序列化RCE、SQL注入、认证绕过、SSRF、XXE等多类型安全漏洞，覆盖代码层、依赖层、业务逻辑层多个风险面。

2. 深度审计执行流程与多维度结果输出机制 Strix具备高自主化审计执行能力，内部调度8类专业智能体协同完成任务；以JavaSecLab深度审计任务为例，单次任务LLM调用次数约306次，Token消耗约21.5M。