This is the fifth article in a series on agentic engineering and AI-driven development. Read part one here, part two here, part three here, and part four here.这是关于代理工程和 AI 驱动开发系列的第五篇文章。请在此阅读第一部分，在此阅读第二部分，在此阅读第三部分，在此阅读第四部分。
I recently had a taste of humility with my AI-generated code. I live in Park Slope, Brooklyn, and recently I needed to get to the other side of the neighborhood. I thought I’d be clever: I like taking the bus, so I decided to hop on the one that goes right down 7th Avenue. I know I could check the schedule using the MTA’s really useful Bus Time app or website, but it doesn’t take into account walking time from my house or give me a good idea of when to leave. This seemed like a great opportunity to vibe code an app and do some quick AI-driven development.我最近在我的 AI 生成代码上尝到了谦卑的滋味。我住在布鲁克林的公园坡，最近需要去邻里另一侧。我想要聪明一点：我喜欢坐公交，于是决定搭乘那条直走第七大道的线路。我知道可以用 MTA 的 Bus Time 应用或网站查看时刻表，但它不考虑从我家步行的时间，也没有给出何时出发的好建议。这似乎是一个很好的机会来用代码快速开发一个应用并进行 AI 驱动的开发。
It took about two minutes for Claude Code to get my new app working. It made a lovely little web UI, I configured my stop and how long it takes me to walk there, and it gave me the perfect departure time.Claude Code 用了大约两分钟就让我的新应用跑起来了。它做了一个可爱的网页 UI，我配置了我的站点和步行所需时间，它给出了完美的出发时间。
When I actually walked out the door, the app perfectly predicted my wait. There was just one problem: my bus was nowhere to be seen. What I did see was a bus driving the exact opposite direction down 7th Avenue.当我真的走出门时，应用准确预测了我的等待时间。唯一的问题是：我的公交车根本不见踪影。我看到的是一辆正朝相反方向行驶的公交车。
It was pretty obvious what had happened. I needed to go deeper into Brooklyn, not towards Manhattan, and the AI had picked the wrong direction. (Actually, as Cowork pointed out, each stop has its own ID, and it had selected the ID for the wrong stop.) I’d been using Cowork to orchestrate everything, and I could easily have just asked it to go out and check the MTA’s BusTime site for me to make sure the app was working. But I just trusted the AI. As a result, I had to walk. Which is fine—I love walking—but the irony was painful. I had literally just published an article about AI code quality and why you shouldn’t blindly trust it, and here I was doing exactly that.情况显而易见：我需要往布鲁克林更深处去，而不是朝曼哈顿方向，AI 选错了方向。（实际上，正如 Cowork 所指出的，每个站点都有自己的 ID，AI 选中了错误站点的 ID。）我一直在用 Cowork 编排所有工作，本可以让它去 MTA 的 BusTime 网站检查一下，以确保应用正常。但我只信任了 AI。结果我只能步行。没关系——我喜欢走路——但讽刺的是，我刚发表了一篇关于 AI 代码质量以及为何不盲目信任它的文章，而我正做着完全相反的事。
The app had a bug. But it wasn’t the kind of bug you’d necessarily catch using a typical AI code review prompt. It built, ran, and did a perfectly fine job parsing the JSON from the MTA API. But if I’d started with a simple requirement—even just a user story like “as a Park Slope resident, I want to catch the B69 headed towards Kensington so I can get deeper into Brooklyn”—the AI would have built it differently. The problem is that AI can only build the thing you tell it to build, which isn’t necessarily the thing you wanted it to build. AI is really good at writing “correct” code that does the wrong thing.这个应用有 bug。但这并不是那种你用典型的 AI 代码审查提示一定能捕获的 bug。它能够构建、运行，并且能够很好地解析 MTA API 返回的 JSON。但如果我从一个简单的需求开始——甚至只是一条用户故事，例如“作为公园坡的居民，我想捕获前往肯辛顿的 B69 公交，这样我才能更深入地进入布鲁克林”——AI 会以不同的方式构建它。问题在于，AI 只能构建你告诉它构建的东西，而这不一定是你真正想要的。AI 很擅长写出“正确”的代码，却做错事。
My Brooklyn bus detour was a minor inconvenience. But it was a really useful, small-scale example of what I kept running into in my larger projects, too. There’s an entire class of bugs that you simply can’t find with structural analysis—no linter, no static analyzer, no AI code reviewer will catch them—because the code isn’t wrong in any way that’s visible from the code alone. You need to know what the code was supposed to do. You need to know the intent.我的布鲁克林公交绕行只是个小小的不便。但它是一个非常有用的小规模示例，说明了我在更大项目中不断遇到的同样问题。有一类 bug 是结构化分析根本找不到的——没有任何 linter、静态分析器、甚至 AI 代码审查工具能捕获它们，因为代码本身并没有明显错误。你必须知道代码本应做什么。你必须了解意图。
The data on why requirements matter goes back decades. Back in the 1990s, for example, the Standish CHAOS reports were a big eye-opener for me and a lot of other people in the industry, large-scale data confirming what we’d been seeing on our own projects: that the most expensive defects trace back to misunderstood or missing requirements. Those reports really underscored the idea that poor requirements management, and specifically incomplete or frequently changing specifications, were one of the most primary drivers behind IT project failures. (And, as far as I can tell, they still are, and AI isn’t helping things—see my O’Reilly Radar article, “Prompt Engineering Is Requirements Engineering”).关于需求为何重要的数据可以追溯到几十年前。例如，1990 年代的 Standish CHAOS 报告对我和业界许多人都是一次大开眼界的经历——大量数据证实了我们在自己的项目中看到的情况：最昂贵的缺陷追溯到误解或缺失的需求。这些报告强烈表明，糟糕的需求管理，尤其是不完整或频繁变更的规格，是 IT 项目失败的主要驱动因素之一。（据我所知，这一点至今仍然成立，AI 并没有改善这种情况——参见我的 O’Reilly Radar 文章《Prompt Engineering Is Requirements Engineering》）。
The idea that requirements problems really are the source of the most expensive kind of defects should make intuitive sense: If you build the wrong thing, you have to tear it apart and rebuild it. That’s why I made requirements the foundation of the Quality Playbook, an open-source skill for AI tools like Claude Code, Cursor, and Copilot that I introduced in the previous article. I’ve spent decades doing test-driven development, partnering with QA teams, welcoming the harshest code reviews from teammates who don’t pull punches—and that experience led me to build a tool that uses AI to bring back quality engineering practices the industry abandoned decades ago. I’ve tested it against a wide range of open-source projects in Go, Java, Rust, Python, and C#, from small utilities to widely-used libraries with tens of thousands of stars, and it’s found real bugs in almost every project it’s come across, including ones that have been confirmed and merged upstream.需求问题是最昂贵缺陷来源的想法应该是直观的：如果你构建了错误的东西，就必须把它拆掉重新做。这也是我把需求作为质量手册（Quality Playbook）基础的原因——这是一个面向 Claude Code、Cursor 和 Copilot 等 AI 工具的开源技能，我在前一篇文章中介绍过。我几十年一直在做测试驱动开发，和 QA 团队合作，接受来自不留情面的同事的严苛代码审查——这些经验促使我构建了一个使用 AI 恢复行业几十年前已被抛弃的质量工程实践的工具。我已经在 Go、Java、Rust、Python 和 C# 等开源项目中广泛测试过它，从小工具到拥有数万星的流行库，它几乎在每个项目中都发现了真实的 bug，包括已经被确认并合并到上游的 bug。
I think there are a lot of wider lessons we can learn from my experience using requirements to help AI find bugs—especially security bugs. So in this article, I want to focus on the single most important thing I’ve learned from building it: everything depends on requirements. Not just any requirements, but a specific kind of requirement that most projects don’t have, that most AI tools don’t ask for, and that turns out to be the key to making AI actually useful for verifying code quality.我认为我们可以从我使用需求帮助 AI 找 bug 的经验中学到很多更广泛的教训——尤其是安全 bug。因此在本文中，我想重点分享我从构建过程中学到的最重要的一点：一切都取决于需求。不是随便的需求，而是大多数项目没有、绝大多数 AI 工具也不会询问的特定类型需求，而这正是让 AI 真正有用以验证代码质量的关键。
Spec-driven development and what it misses规范驱动开发及其缺失之处
Developers using AI tools have been rediscovering the value of writing things down before asking the AI to build them. Spec-driven development (SDD) has become very popular, and for good reason. Addy Osmani wrote an excellent piece on this, “How to Write a Good Spec for AI Agents,” and the core idea is sound: If you write a clear specification of what you want built, the AI produces dramatically better results than if you just describe it in a chat prompt and hope for the best.使用 AI 工具的开发者正在重新发现，在让 AI 构建之前先把需求写下来的价值。规范驱动开发（Spec‑driven development，SDD）已变得非常流行，这并非没有原因。Addy Osmani 写了一篇优秀的文章《How to Write a Good Spec for AI Agents》，核心思想很合理：如果你写下清晰的规格，AI 的产出会远好于仅在聊天提示中描述并期望得到最佳结果的情况。
I think SDD is important, and I’d encourage any developer working with AI to adopt it. But as I was building the Quality Playbook, I discovered that SDD has a blind spot that matters a lot for code quality. An SDD spec describes the how—what the implementation should look like. It tells the AI “implement a duplicate key check” or “add a retry mechanism with exponential backoff” or “create a REST endpoint that returns paginated results.” That’s useful for building things. But it’s not enough for verifying them.我认为 SDD 很重要，我也鼓励所有使用 AI 的开发者采用它。但在我构建质量手册的过程中，我发现 SDD 有一个盲点，对代码质量影响很大。SDD 规范描述的是“如何”——实现应该是什么样子。它告诉 AI “实现重复键检查”或“添加指数退避的重试机制”或“创建返回分页结果的 REST 端点”。这对构建东西很有用，但不足以验证它们。
But a requirement doesn’t say “implement a duplicate key check.” It says “users depend on Gson to reject ambiguous input so they don’t silently accept corrupted data.” The AI can reason about the second one in ways it can’t reason about the first, because the second one has the purpose attached. When the AI knows the purpose, it can evaluate whether the code actually fulfills that purpose across all the edge cases, not just the ones the spec explicitly listed. That’s how the Quality Playbook caught a bug in Google’s Gson library, one of the most widely used JSON libraries in Java.而需求并不是说“实现重复键检查”。它说的是“用户依赖 Gson 拒绝模糊输入，以免悄悄接受损坏的数据”。AI 能够对第二种情况进行推理，而对第一种则无法，因为第二种附带了目的。当 AI 知道了目的后，它可以评估代码是否在所有边缘情况都实现了该目的，而不仅仅是规格明确列出的那些。这就是质量手册在 Google 的 Gson 库中捕获 bug 的方式——这是 Java 中最广泛使用的 JSON 库之一。
I think it’s worth digging into that particular bug, because it’s a great example of just how powerful requirements analysis can be for finding defects. The playbook derived null-handling requirements from Gson’s own community—GitHub issues #676, #913, #948, and #1558, some dating back to 2016—then used those requirements to find that duplicate keys were silently accepted when the first value was null. It confirmed the bug by generating a failing test, then patched the code and verified the test passed. I’ve used Gson for years and done a lot of work with Java serialization, so I read the code and the fix myself before submitting anything—trust but verify. The fix was merged as https://github.com/google/gson/pull/3006, confirmed by Google’s own test suite.我认为值得深入探讨那个特定的 bug，因为它很好地展示了需求分析在发现缺陷方面的强大力量。手册从 Gson 社区的 GitHub issue（#676、#913、#948、#1558，部分可追溯到 2016 年）中提取了空值处理需求，然后利用这些需求发现当第一个值为 null 时，重复键会被悄悄接受。它通过生成一个失败的测试确认了 bug，随后修复代码并验证测试通过。我多年使用 Gson 并且做了大量 Java 序列化工作，所以在提交之前我自己阅读了代码和修复——信任但要验证。修复已合并至 https://github.com/google/gson/pull/3006，得到 Google 自己的测试套件确认。
That bug had been hiding in plain sight for years, through thousands of tests and countless code reviews. But it’s possible that no structural analysis might have ever found it because you needed the requirement to know it was wrong.这个 bug 多年来一直隐藏在显眼之处，经过成千上万的测试和无数代码审查。但可能没有任何结构化分析能够发现它，因为你需要需求来判断它是错误的。
This distinction might sound academic, but it has very concrete consequences for whether your AI can actually find bugs in your code.这种区别听起来像学术讨论，但它对你的 AI 能否真正发现代码中的 bug 有非常具体的影响。
About half of all security bugs are invisible to structural analysis大约一半的安全 bug 对结构化分析是不可见的
The security world has known about the limits of structural analysis for a long time. The NIST SATE evaluations found that the best static analysis tools plateaued at around 50-60% detection rates for security vulnerabilities. Gary McGraw’s Software Security: Building Security In (Addison-Wesley, 2006) explains why: Roughly 50% of security defects are implementation bugs, and the other 50% are design flaws. Static analysis tools target the implementation bugs—buffer overflows, SQL injection, format string vulnerabilities—because those are pattern-matchable. But design flaws are about intent: The system’s architecture doesn’t enforce the security properties it’s supposed to enforce, and no amount of scanning the code will reveal that. A 2024 study by Charoenwet et al. (ISSTA 2024) confirmed this is still the case: They tested five static analysis tools against 815 real vulnerability-contributing commits and found that 22% of vulnerable commits went entirely undetected, and 76% of warnings in vulnerable functions were irrelevant to the actual vulnerability. The pattern is consistent across two decades of research: There’s a ceiling on what you can find by analyzing code, and it’s around half.安全领域早已认识到结构化分析的局限性。NIST SATE 评估发现，最好的静态分析工具在安全漏洞检测率上停留在约 50‑60%。Gary McGraw 在《Software Security: Building Security In》（Addison‑Wesley，2006）中解释了原因：大约 50% 的安全缺陷是实现层面的 bug，另外 50% 是设计缺陷。静态分析工具针对实现层面的 bug——缓冲区溢出、SQL 注入、格式化字符串漏洞——因为这些可以模式匹配。但设计缺陷涉及意图：系统架构未能强制执行应有的安全属性，任何代码扫描都无法揭示。Charoenwet 等人在 2024 年的 ISSTA 研究（Charoenwet et al., 2024）证实了这一点：他们对 815 条真实的漏洞提交测试了五种静态分析工具，发现 22% 的漏洞提交完全未被检测到，且在易受攻击的函数中 76% 的警告与实际漏洞无关。二十年的研究表明：通过分析代码能发现的东西有上限，大约是“一半”。
There’s a good reason for that limitation: the intent ceiling. A structural analysis tool is limited to reading the code and looking at what it does; it has no way to take into account what the developer intended it to do.这种限制的根本原因是意图上限。结构化分析工具只能读取代码并观察它的行为；它们无法考虑开发者的意图。
When an AI does a code review without requirements, it’s limited to structural analysis: pattern matching, code smell detection, race condition analysis. It can ask “does this look right?” but it can’t ask “does this do what it’s supposed to do?” because it doesn’t know what the code is supposed to do. Structural review catches genuinely important stuff—race conditions, null pointer issues, resource leaks, concurrency bugs. A structural reviewer looking at a shell script will catch a missing fi, a bad variable expansion, a race condition. Structural review is useful, and structural review is what most AI code review tools do today.当 AI 在没有需求的情况下进行代码审查时，它只能进行结构化分析：模式匹配、代码味道检测、竞争条件分析。它可以问“这看起来对吗？”，但不能问“它是否实现了预期的功能？”，因为它不知道代码应该做什么。结构化审查能够捕获真正重要的东西——竞争条件、空指针、资源泄漏、并发 bug。结构化审查者在审查 shell 脚本时会发现缺少 fi、变量展开错误、竞争条件等。结构化审查是有用的，也是大多数 AI 代码审查工具今天所做的。
But about half of all security defects are intent violations: things the code doesn’t do that it was supposed to do, or things it does that it wasn’t supposed to do. They’re invisible without a specification to check against, and no tool will find them by looking at code that is, structurally, perfectly sound. A structural reviewer looking at a script that’s, say, used to check router configuration files, might find well-formed bash, correct syntax, proper quoting, and code that looks like it works and doesn’t match known antipatterns. It wouldn’t know the script is only validating three of the five access control rules it’s supposed to enforce because that’s a requirements question, not a syntax question.但大约一半的安全缺陷是意图违规：代码没有做它应该做的事，或做了它不该做的事。没有规格进行对照，它们是不可见的，任何仅看代码的工具都找不到它们，因为代码在结构上是完好的。结构化审查者在审查一个用于检查路由器配置文件的脚本时，可能会发现 Bash 语法正确、引号使用得当、代码看起来可以工作，并且没有匹配已知的反模式。但它不会知道该脚本只验证了五条访问控制规则中的三条，因为那是需求层面的问题，而不是语法层面的问题。
Or, more personally for me, this is what happened with my bus tracker app: The JSON parsing was flawless, the UI was correct, the timing logic worked perfectly. The only problem was that it showed buses headed towards Manhattan when I needed to go deeper into Brooklyn—and no structural analysis would ever catch that, because you need to know which direction I intended to go. That’s me and my very clever AI hitting the intent ceiling.或者，对我个人而言，这正是我的公交追踪应用发生的情况：JSON 解析完美，UI 正确，计时逻辑运行良好。唯一的问题是它显示的是前往曼哈顿的公交，而我需要的是前往布鲁克林更深处的公交——没有任何结构化分析能够捕获这个问题，因为你必须知道我打算去哪个方向。这就是我和我那非常聪明的 AI 碰到的意图上限。
The intent ceiling is a security problem意图上限是一个安全问题
This is where it gets really serious, because security vulnerabilities are some of the most dangerous members of this class of invisible bugs.这就变得非常严肃，因为安全漏洞是这类不可见 bug 中最危险的成员。
Think about what a missing authorization check looks like to an AI code reviewer. Let’s say you’ve got a web endpoint with a well-formed HTTP handler, properly sanitized inputs, and a safe database query. The code is clean, and passes every structural check and static analysis tool you’ve thrown at it. Now you’re testing it and, much to your dismay, you discover that the endpoint lets any authenticated user delete any other user’s data because nobody ever wrote down the requirement that says “only administrators can perform deletions.” That’s CWE-862: Missing Authorization, and it rose to #9 on the 2024 CWE Top 25 most dangerous software weaknesses.想象一下，缺失授权检查在 AI 代码审查器眼中是什么样子。假设你有一个网络端点，拥有良好构建的 HTTP 处理器、正确消毒的输入和安全的数据库查询。代码干净，能够通过所有结构化检查和你使用的静态分析工具。现在你进行测试，却发现该端点允许任何已认证用户删除其他用户的数据，因为从未写下“只有管理员才能执行删除”的需求。这就是 CWE‑862：缺失授权，它在 2024 年 CWE Top 25 最危险软件弱点中排名第 9。
That’s not a coding error! It’s a missing requirement.这不是代码错误！而是缺失的需求。
That’s McGraw’s point: About half of all security defects aren’t implementation bugs at all. They’re design flaws, places where the system’s architecture doesn’t enforce the security properties it was supposed to enforce. A cross-site scripting vulnerability isn’t always a failure to sanitize input. Sometimes it’s a failure to define which inputs are trusted and which aren’t. A privilege escalation isn’t always a broken access check. Sometimes there was never an access check to begin with because nobody specified that one was needed. These are intent violations and they’re invisible to any tool that doesn’t know what the software is supposed to prevent.这正是 McGraw 的观点：大约一半的安全缺陷根本不是实现层面的 bug。它们是设计缺陷，系统架构未能强制执行应有的安全属性。跨站脚本漏洞并不总是因为未对输入消毒。有时是因为未定义哪些输入是可信的。特权提升并不总是因为访问检查失效。有时根本没有访问检查，因为从未有人规定需要。它们是意图违规，对任何不了解软件应防止什么的工具来说都是不可见的。
AI code review tools today are very good at catching the implementation half of McGraw’s split. They can spot a SQL injection pattern, flag an unsafe deserialization, identify a buffer overflow. But they’re working on the same side of the 50/50 line that static analysis has always worked on. The design half—the missing authorization checks, the unspecified trust boundaries, the security properties that were never written down—requires the same thing that catching my bus tracker bug required: knowing what the software was supposed to do in the first place.如今的 AI 代码审查工具在捕获 McGraw 所说的实现层面方面做得非常好。它们可以发现 SQL 注入模式、标记不安全的反序列化、识别缓冲区溢出。但它们仍然停留在 50/50 线的同一侧——即静态分析一直关注的那一侧。设计层面的缺失——缺失的授权检查、未定义的信任边界、从未写下的安全属性——需要的正是捕获我的公交追踪 bug 时所需的东西：首先要知道软件原本应该做什么。
How the Quality Playbook derives requirements (and how you can too!)质量手册如何推导需求（以及你如何做到）
The problem most projects face is that they don’t have formal requirements. What they have is code, documentation, commit messages, chat history, README files, and maybe some design docs. The question is how to get from that mess to a specification that an AI can actually use for verification.大多数项目面临的问题是没有正式的需求。它们拥有的是代码、文档、提交信息、聊天记录、README 文件，或许还有一些设计文档。关键是如何从这些混乱中提炼出 AI 能真正用于验证的规格。
The key insight I had while building the playbook was that every previous approach I tried asked the model to do two things at once: figure out what contracts exist AND write requirements for them. That doesn’t work—the model runs out of attention trying to hold the entire behavioral surface in its head while also producing formatted requirements. So I split them apart into four steps: First, have the AI read each source file and write down every behavioral contract it observes as a simple list. Second, derive requirements from those contracts plus the documentation. Third, check whether every contract is covered by a requirement. Fourth, assert completeness—and if there are gaps, go back to step one for the files with gaps.我在构建手册时的关键洞见是：之前的每一种方法都让模型一次性完成两件事：找出存在哪些契约并为它们编写需求。这行不通——模型在试图记住整个行为表面的同时又要生成格式化的需求，注意力会耗尽。所以我把它们拆分为四步：第一，让 AI 阅读每个源文件并把它观察到的每个行为契约写成一个简单列表。第二，从这些契约加上文档中提炼需求。第三，检查每个契约是否都有对应的需求。第四，断言完整性——如果有缺口，回到第一步，对有缺口的文件重新执行。
The key idea is that the contracts file is external memory. When the model “forgets” about a behavioral contract it noticed earlier, that forgetting is normally invisible. With a contracts file, every observation is written down before any requirements work begins, so an uncovered contract is a visible, greppable gap.关键思想是把契约文件当作外部记忆。当模型“忘记”之前注意到的某个行为契约时，这种遗忘通常是不可见的。有了契约文件，所有观察都会在开始编写需求之前记录下来，这样未覆盖的契约就会成为一个可见、可 grep 的缺口。
You don’t need the Quality Playbook to do this—you can apply the same technique with any AI coding tool that you’re already using. Here’s what I’d recommend:你不一定需要质量手册来做到这一点——可以在你已经使用的任何 AI 编码工具上应用相同的技术。以下是我的建议：
- Write down what your software is supposed to guarantee. Not just what it does—what it’s supposed to do, for whom, under what conditions. If you’re practicing spec-driven development, you’re already partway there. The next step is adding the why: Why does this behavior matter, who depends on it, what goes wrong if it fails? That’s the difference between a spec and a requirement, and it’s the difference between an AI that can build your code and an AI that can verify it.
写下你的软件应该保证什么。不仅是它做了什么，而是它应该做什么，针对谁，在什么条件下。如果你在实践规范驱动开发，你已经走在了一半路上。下一步是加入“为什么”：为什么这个行为重要，谁依赖它，如果失败会怎样？这就是规范和需求的区别，也是能够构建代码的 AI 与能够验证代码的 AI 之间的区别。 - Feed the AI your intent, not just your code. The intent is already sitting in your chat history, your design discussions, your Slack threads, your support tickets. Every Claude export, every Gemini conversation, every Cowork transcript contains design intent that never made it into specifications: why a function was written a certain way, what failure prompted an architectural decision, what tradeoffs were discussed before choosing an approach. The design intent that used to require a human to extract and document is now sitting in your chat logs. Your AI can read the transcripts and extract the why.
把你的意图喂给 AI，而不仅仅是代码。意图已经存在于你的聊天记录、设计讨论、Slack 线程、支持工单中。每一次 Claude 导出、每一次 Gemini 对话、每一次 Cowork 转录都包含了从未写进规格的设计意图：为什么某个函数以特定方式编写，是什么失败促使了架构决策，选择某种方案前讨论了哪些权衡。过去需要人工提取并记录的设计意图，现在已经在你的聊天日志里。你的 AI 可以读取这些记录并提取“为什么”。 - Look for the negative requirements. What should your software not do? What states should be impossible? What data should never be exposed? These negative requirements are often the most valuable because they define boundaries that structural review can’t see. The missing authorization bug was a negative requirement: Unauthenticated users must not be able to delete other users’ data. The Gson bug was a negative requirement: Duplicate keys must not be silently accepted when the first value is null. If you can articulate what your software must never do, you’ve given the AI something powerful to check against.
寻找负向需求。你的软件不应该做什么？哪些状态应该是不可能的？哪些数据绝不应被暴露？这些负向需求往往最有价值，因为它们定义了结构化审查看不到的边界。缺失授权的 bug 就是一个负向需求：未认证用户不得删除其他用户的数据。Gson 的 bug 也是负向需求：当第一个值为 null 时，重复键不得被悄悄接受。如果你能清晰表述软件绝不能做的事情，就为 AI 提供了强有力的检查依据。
In the next article, I’ll talk about context management—the skill that actually determines whether your AI sessions produce good work or mediocre work. Everything I’ve described here depends on the AI having the right information at the right time, and it turns out that managing what the AI knows (and what it forgets) is an engineering discipline in its own right. I’ll cover how I went from running 15 million tokens in a single prompt to splitting the playbook into independent phases with zero context carryover, and why that transition worked on the first try.在下一篇文章中，我将讨论上下文管理——这项技能实际上决定了你的 AI 会话是产出好工作还是平庸工作。一切都依赖于 AI 在正确的时间拥有正确的信息，而管理 AI 知道什么（以及忘记什么）本身就是一门工程学科。我会介绍如何从一次性使用 1500 万 token 的单一提示，转变为将手册拆分为独立阶段且没有上下文迁移的做法，以及为什么这种转变在第一次尝试时就成功了。
The Quality Playbook is open source and works with GitHub Copilot, Cursor, and Claude Code. It’s also available as part of awesome-copilot.质量手册是开源的，可与 GitHub Copilot、Cursor 和 Claude Code 配合使用。它也作为 awesome‑copilot 的一部分提供。
Disclosure: Aspects of the methodology described in this article are the subject of US Provisional Patent Application No. 64/044,178, filed April 20, 2026 by the author. The open-source Quality Playbook project (Apache 2.0) includes a patent grant to users of that project under the terms of the Apache 2.0 license.披露：本文所述方法的部分内容已于 2026 年 4 月 20 日以美国临时专利申请号 64/044,178 提交。开源的质量手册项目（Apache 2.0）在 Apache 2.0 许可证条款下向该项目的用户授予专利许可。
