我用的是开发驱动的规格说明，而不是规格驱动的开发

Ensemble 是依据 Bill Cox 的可执行教学书《The Art of Building AI Coding Agents》构建的编码智能体。当前版本是第 3 版：应用采用 C# 14 / .NET 10，在 Ensemble 内部借助 Cadence 开发。代码与规格说明一起构建。开发过程本身产出规格。目标不是预先写出一份详细计划交给 AI，也不是凭感觉写出一套系统、事后再补文档。目标是借助与 AI 结对编程成为专家，然后把这份专业知识以另一个智能体能够执行的形式保存下来。

最终产出的是可执行规格说明：一本代码手册，传递构建该系统所需的判断力，而不只是一份期望功能清单。Ensemble V2 执行这本书构建出了 V3；随后 Bill 和 Cadence 在 V3 内部工作，改进智能体和教学内容。各章仍保留其已记录的验证限制。

人的专业知识在开发过程中增长，而不是依赖最后检查自己不熟悉的生成代码。代码只是产出；可复用的资产是能够再次构建它的知识。不要只记录要构建什么。要教如何以及为什么那样构建。你无法一开始就学会这一切。

阅读这本书、章节指南，或汇编成册的手稿。

当前应用源码与人类伴侣文档。

保留的章节解答。

晋升与验证、实现证据。

冻结的历史：第 1 版和第 2 版，各自带有书、源码和评分器。

构建与运行

使用现有的 .NET 10 SDK（只有运行时无法构建应用）。这里不会安装 SDK、不会读取构建凭据、不会自动启动服务器，也不会替换已安装的应用。

首先检查你的 shell 能否找到 SDK：

dotnet --list-sdks # 应包含 10.x SDK

如果找不到 dotnet，或者 make 报告 dotnet: No such file or directory，说明构建还没到编译阶段：SDK 可执行文件不在你 shell 的 PATH 中。如果你已经安装了 SDK，可以把它的目录加入当前 shell 的 PATH（把示例路径替换为实际的 SDK 目录）：

export PATH="/absolute/path/to/dotnet-sdk:$PATH"

dotnet --list-sdks

或者不改 PATH，直接给 Make 可执行文件的完整路径：

make DOTNET=/absolute/path/to/dotnet

make cli DOTNET=/absolute/path/to/dotnet

其他目标也使用同样的覆盖方式，例如 make test。

例如，如果你把 SDK 安装在 $HOME/.local/share/ensemble-dotnet10，就用 make DOTNET="$HOME/.local/share/ensemble-dotnet10/dotnet"。这只是一个示例位置，不是必需的目录布局。如果没有安装 .NET 10 SDK，请从 Microsoft 的 .NET 10 下载页安装，然后打开新终端重新检查。

make # 构建 C# GUI 并生成 ./ensemble 启动器

make cli # 构建 C# 终端客户端

./ensemble --help # 显式启动；使用前先查看选项

make cli 之后的终端客户端：

dotnet agent/Cli/bin/Debug/net10.0/ch04.dll --help

如果你使用了显式 SDK 覆盖，启动终端客户端时也要用该完整可执行路径代替 dotnet。

真正启动时，请自选数据目录、工作区、资金配置和未占用的端口。不要为了刷新源码而替换正在运行的主机。GUI 在构建时嵌入其资源。应用行为和合格的测试证据见 crossover 章节和源码 README。

make test 运行 C# 回归可执行文件和根目录的 Go 工具测试；make test-go 只测试后者。Go 保留在根目录用于可复用的评分器、本地假提供者和发布工具——它不是活动运行时。

使用各章已记录的可执行命令和范围。C# 不能被发送给 Go 源码消费型评分器。例如，第 5 章记录了显式的 grade-edition3 -ch 5 -executable-only 路线及其 65 个限定点数。

make grade CH=5 DIR=/path/to/CLI-wrapper GRADEFLAGS='-executable-only ...'

需要显式目标，并转发到该第 3 版命令。

可执行评分器编号和保留的 chNN 快照保持其原始含义；章节映射解释了后续手稿的重新编号。历史第 2 版评分可从 edition-2/ 运行；第 1 版保留在 edition-1/。两个归档都不会为当前布局而重写。

make book 汇编当前手稿；make ebook 构建其 EPUB；make print 构建其印刷版和阅读版 PDF。这些使用现有的本地发布工具，绝不安装它们。前提条件和隔离输出见书籍构建说明。生成的出版物与源码修改不同；仅做源码晋升不会发布新书或上传它。

Puffin 书是 Gateway、Connections、Agenda、Puffin 及相关 Watchtower/安全工作的当前工作场所。其笔记遵循开发驱动规格；大纲是暂定的，不是已完成的功能。编码智能体书仍位于 book/ 下。