前言

agent-spec 是一个意图编译器（Intent Compiler）：人类的意图经它编译为结构化需求（IR），再降低为可机械验证的任务合同（Task Contract），最后由确定性管线证明 “代码仍然遵守着当初的意图”。它是给 AI 协作时代准备的工程底座——当实现代码越来越多地由 Agent 写出，人类的注意力应该花在定义正确上，而把验证正确交给机器。

本书基于 agent-spec 1.0.0（兼容性承诺生效版）写成，中文先行；英文版作为后续工作，将在本书结构稳定后启动。全书由浅入深，以用法为主线：第一、二部分让你从零跑通并精通合同工作流；第三、四部分进入意图编译与知识层；第五部分收束于设计哲学与架构全景。

本书自身就是 agent-spec 工作流的展品：它有自己的 KLL 需求（REQ-AGENT-SPEC-BOOK）与任务合同，每一章的定位锚、Mermaid 图、目录完整性都由绑定测试机械守卫——细节见附录 C。

阅读准备

前置知识

命令行基础：会在终端运行命令、读输出。
Git 常识：知道 commit / branch / staged 是什么。
不需要：Rust 编程能力（除非你读第 16 章 Atlas 的实现细节）、任何特定 AI 工具的经验——agent-spec 是 agent-agnostic 的。

全书知识地图

graph TD
    subgraph P1["第一部分 入门"]
        C1[ch01 意图编译器] --> C2[ch02 第一个合同] --> C3[ch03 七步工作流]
    end
    subgraph P2["第二部分 合同"]
        C4[ch04 四要素] --> C5[ch05 场景 DSL] --> C6[ch06 lint]
        C6 --> C7[ch07 lifecycle] --> C8[ch08 边界与守卫] --> C9[ch09 验收追溯]
    end
    subgraph P3["第三部分 意图编译"]
        C10[ch10 PRD→IR] --> C11[ch11 治理三轴] --> C12[ch12 计划]
        C12 --> C13[ch13 溯源重放] --> C14[ch14 编译束]
    end
    subgraph P4["第四部分 知识与生态"]
        C15[ch15 KLL] --> C16[ch16 Atlas] --> C17[ch17 Wiki与MCP]
    end
    subgraph P5["第五部分 理念与架构"]
        C18[ch18 哲学] --> C19[ch19 架构全景]
    end
    C3 --> C4
    C9 --> C10
    C14 --> C15
    C17 --> C18
    C8 -.符号验证.-> C16
    C13 -.证据链.-> C15

图例：实线为阅读顺序（部分之间的推荐先后），虚线为跨部分的主题关联；各章严格的前置依赖以每章定位锚为准。

标记约定

标注为真实运行的命令输出来自 agent-spec 1.0.0，未经虚构；教程性示例（如第 2 章的“用户注册API“演练）会注明“示例“。仓库快照数字（合同数、文档数等）以写作时为准，仓库会继续生长。
“详见第 N 章” 是交叉引用的规范格式（行文中也会自然使用“上一章/下一章“）。
每章开篇的 > **定位** 告诉你这一章讲什么、依赖哪一章（必要时含适用场景）。

agent-spec 1.0 — 意图编译器之书

前言

阅读准备

前置知识

推荐阅读路径

全书知识地图

标记约定

Keyboard shortcuts

agent-spec 1.0 — 意图编译器之书

前言

阅读准备

前置知识

推荐阅读路径

全书知识地图

标记约定