Context Specs — the full story上下文规范 — 完整故事

This is the long-form documentation for Context Specs. The top-level README is the elevator pitch; this is the book.这是上下文规范的长篇文档。顶层的 README 是电梯演讲；这本书则是完整内容。

It's written to be read in order. Each chapter ends where the next one begins — by the last page you should see why a coding project, run well with agents, stops looking like a codebase you type into and starts looking like a harness you tune.它被写成按顺序阅读。每一章的结尾正是下一章的开头——读到最后一页，你会明白为什么一个运行良好的编码项目，不再像你敲进去的代码库，而更像一个你调校的工具箱。

The through-line主线

One idea runs under everything here: the right context at the right time. What enters an agent's context window is the biggest lever you have. Context Specs is that lever, pulled at three levels — each one building on the one before it:这里有一个贯穿所有内容的理念：在正确的时间提供正确的上下文。进入代理上下文窗口的内容是你拥有的最大杠杆。上下文规范就是这根杠杆，分为三个层级——每个层级都建立在前一个之上：

Context engineering          the idea: an agent choosing what enters its window
        │
        ▼
Spec-Driven Development       Layer 1 — the idea, applied to building one feature
        │
        ▼
The agent harness            Layer 2 — the project runs that loop for you, and
        │                              gets better every merge
        ▼
The human loop               Layer 3 — freed from typing, you improve the harness
        │
        ▼
A mindset shift              your project has become a harness; your job is context

Each layer is usable without the ones above it. Spec-Driven Development needs no harness. The harness needs no human-loop discipline to run. The value compounds as you climb — but you can stop on any rung.每一层都可以在没有上层的情况下使用。规范驱动开发不需要任何工具箱。工具箱本身也不需要人为循环的约束即可运行。价值会随着层层递进而复合——但你可以在任何层级停下来。

The chapters章节

1. Context engineering — what it actually is, and why the context window is the scarce resource everything else is fighting over.上下文工程 — 它到底是什么，以及为什么上下文窗口是所有其他资源争夺的稀缺资源。
2. Spec-Driven Development (Layer 1) — how Context Specs applies context engineering to a single feature: experts, specs, temporal slicing, signal, consensus validation. The foundation, usable on its own.规范驱动开发（第 1 层） — 如何将上下文规范应用于单一特性：专家、规范、时间切片、信号、共识验证。它是基础，可单独使用。
3. The agent harness (Layer 2) — file a PRD, walk away, come back to a finished PR. The autonomous loop, and why you can trust a machine to run it unattended.代理工具箱（第 2 层） — 提交 PRD，离开，回来时看到已完成的 PR。自主循环，以及为何你可以信任机器无人值守地运行它。
4. Continuous improvement (Layer 2) — how the harness gets better every merge: long-term memory, the four destinations for a learned fact, and lints the agent cannot ship past.持续改进（第 2 层） — 工具箱如何在每次合并时变得更好：长期记忆、已学习事实的四个去向，以及工具箱无法通过的 lint 检查。
5. The human loop (Layer 3) — once the machine does the typing, what's left is the part only you can do: Understanding → Intent → Evaluate.人为循环（第 3 层） — 当机器完成敲代码后，剩下的只有你能做的部分：理解 → 意图 → 评估。
6. The mindset shift — the payoff. Your project is a harness now. Here's how the way you work changes.思维方式的转变 — 收获。你的项目现在是一个工具箱。以下是工作方式的变化。

Reference参考

• Design invariants — the properties the harness holds no matter what crashes, races, or restarts. Read this when you want to understand why the machine is safe to leave running. (Optional; you can also hand it to an agent to give it a deeper model of the harness.)设计不变量 — 工具箱在任何崩溃、竞争或重启情况下都保持的属性。当你想了解为何机器可以安全地让它自行运行时，请阅读此文。（可选；你也可以交给代理，让它对工具箱形成更深的模型。）

Where the code lives代码所在位置

Everything described here ships as Agent Skills under skills/. The chapters point at the specific skill, script, or reference file that implements each idea, so you can read the story and then go read the source.这里描述的所有内容都以 Agent Skills 的形式放在 skills/ 下。各章节指向实现每个想法的具体 skill、脚本或参考文件，这样你既可以阅读故事，又可以去阅读源码。