This is the seventh article in a series on agentic engineering and AI-driven development. Read part one here, part two here, part three here, part four here, part five here, and part six here.这是关于代理工程和 AI 驱动开发系列的第七篇文章。阅读第一部分 here，第二部分 here，第三部分 here，第四部分 here，第五部分 here，第六部分 here。
This is the latest article in my Radar series on AI-driven development and agentic engineering, and I have to admit that this one took a bit of a turn I wasn’t expecting.这是我关于 AI 驱动开发和代理工程的 Radar 系列的最新文章，我必须承认，这篇文章出现了我没预料到的转折。
In my last article I talked about context and context management and I promised to give you some real practical tips for using it. It was originally meant to be about specific, practical context management techniques that were really helpful to me building Octobatch and the Quality Playbook, two open source projects where I work with AIs to plan and orchestrate all of the work and every line of code is written by AI tools like Claude Code and Cursor.在上一篇文章中，我谈到了上下文和上下文管理，并承诺给你一些实际的技巧来使用它。最初的目的是介绍一些对我构建 Octobatch 和 Quality Playbook（两个开源项目）非常有帮助的具体、实用的上下文管理技术，这两个项目中我使用 AI 来规划和编排所有工作，所有代码行都是由 Claude Code、Cursor 等 AI 工具编写的。
But as I was writing this, I found that I’d adapted those same techniques to my work writing articles like this one. Which is surprising! I’ve been doing all this work finding ways to help people developing AI skills improve context management, so their skills run more efficiently. It turns out that those same exact techniques apply to anyone using AI tools, even when you’re using chatbots like Claude.ai or ChatGPT.但在写这篇文章时，我发现我已经把这些技术同样应用到了写作上。真是令人惊讶！我一直在寻找帮助人们提升 AI 技能、改进上下文管理的方法，以便他们的技能运行得更高效。结果发现，这些完全相同的技术同样适用于任何使用 AI 工具的人，即使你使用的是 Claude.ai 或 ChatGPT 之类的聊天机器人。
Full disclosure: I use multiple AI tools to manage this article series. My primary tools are Claude Cowork for brainstorming and managing my article research, notes, and backlog and Gemini’s mobile app for reading drafts aloud and taking my notes while I’m away from my desk. And I want to tell you about something that happened while I was using those tools, because I think it really helps show why context management isn’t just a problem for developers.完整披露：我使用多种 AI 工具来管理这系列文章。我的主要工具是 Claude Cowork，用于头脑风暴以及管理文章研究、笔记和待办事项；还有 Gemini 的移动应用，用于朗读草稿并在我离开桌面时记录笔记。我想告诉你在使用这些工具时发生的一件事，因为它真的帮助说明了上下文管理不仅是开发者的问题。
While I was writing this article, I was using Gemini’s mobile app to read the draft aloud and take my notes. Partway through the session I asked it to go back and check whether there were earlier notes it hadn’t incorporated yet. It told me it didn’t have access to the previous notes, which seemed weird and insane, since we had just taken those notes a few prompts earlier in the session. I could scroll back up and see them earlier in the conversation, but somehow it didn’t “know” about them.在写这篇文章时，我使用 Gemini 的移动应用朗读草稿并记录笔记。会话进行到一半时，我让它回去检查是否有之前的笔记还没有被整合。它告诉我它没有访问之前笔记的权限，这听起来既奇怪又荒唐，因为我们几条提示前才刚刚记录了那些笔记。我可以向上滚动看到它们，但它似乎并“不知道”这些笔记。
Here’s what happened. Gemini had compacted our conversation without telling me, and the notes from the first half of the session were just… gone.事情是这样的：Gemini 在没有告诉我的情况下压缩了我们的对话，导致会话前半段的笔记就这样……消失了。
If you’ve ever had a web chat AI just seem to forget things you talked about earlier, you’ve experienced context compaction, just like I did. Understanding even the basics of context and context windows can make a big difference in preventing that kind of frustration.如果你曾经遇到网页聊天 AI 好像忘记了之前谈过的内容，那你就经历了上下文压缩，就像我一样。了解上下文及其窗口的基本概念可以在防止这种挫败感方面产生巨大差异。
This all reminded me of something I wrote more than two decades ago in Applied Software Project Management (back in 2005!): “Important information is discovered during the discussion that the team will need to refer back to during the development process, and if that information is not written down, the team will have to have the discussion all over again.”这让我想起二十多年前我在《应用软件项目管理》（2005 年）中写的句子：“在讨论过程中会发现重要信息，团队在开发过程中需要回顾这些信息，如果这些信息没有被记录下来，团队就必须重新进行讨论。”
Jenny Greene and I wrote that about human teams and project meetings, but it applies to AI sessions just as well.Jenny Greene 和我写的这句话本是针对人类团队和项目会议的，但同样适用于 AI 会话。
Which brings me back to context, which I wrote about in my last article, and which I’ll write more about in the next one, because it’s one of the most important concepts to keep top of mind when working with AI.这把我拉回到上下文，我在上一篇文章中写过，也将在下一篇中进一步阐述，因为它是与 AI 合作时必须时刻牢记的最重要概念之一。
Context loss may be invisible, but that doesn’t make it any less frustrating上下文丢失可能是无形的，但这并不意味着它不让人沮丧
Context is everything the AI is holding in its working memory during a conversation: what you’ve told it, what it’s told you, any files or instructions it’s read, and whatever internal notes the system has made along the way. All of that lives in a fixed-size context window—think of that as your AI’s short-term memory, the stuff it’s thinking about right now—and when the window fills up, the AI has to start letting things go. Different tools handle this differently: Some truncate older messages, some compress the conversation into a summary (which means details get lost even though the summary looks complete), and some just start behaving inconsistently so you can’t tell whether the AI forgot something or never understood it in the first place. The result is the same: The AI loses track of things you told it, decisions you made together, or details it noticed earlier in the session. And it won’t tell you it forgot. It’ll just keep generating confident-sounding output based on whatever it still has.上下文是 AI 在对话期间保存在工作记忆中的所有内容：你告诉它的、它告诉你的、它读取的任何文件或指令，以及系统在此过程中做的内部笔记。所有这些都存在于固定大小的上下文窗口中——可以把它想象成 AI 的短期记忆，即它此时正在思考的内容——当窗口被填满时，AI 必须开始丢弃信息。不同工具的处理方式各不相同：有的会截断旧消息，有的会将对话压缩成摘要（这会导致细节丢失，即使摘要看起来完整），还有的会表现出不一致的行为，让你无法判断是 AI 忘记了还是根本没理解。结果都是一样的：AI 丢失了你告诉它的内容、你们共同做出的决定或它在会话早期注意到的细节。而且它不会告诉你它忘记了，只会继续生成自信的输出，基于它仍然拥有的内容。
Before we dive in a little deeper, I want to do a quick jargon check. If you’ve seen the terms “skills” and “agents” floating around but aren’t sure what they are, think of skills as libraries for AIs and agents as interactive executables. Those aren’t perfectly precise definitions, but if you’re a developer they’re close enough for this discussion.在深入探讨之前，我想先做一个术语检查。如果你看到“skills”和“agents”这两个词却不确定它们指的是什么，可以把 skills 当作 AI 的库，把 agents 当作交互式可执行文件。虽然这些定义并不完全精确，但对开发者来说已经足够用于本讨论。
When you’re coding skills and agents, you run into context problems quickly. The work you’re asking the AI to do is often complex enough that the context window fills up, and the AI has to start compacting: compressing or dropping older parts of the conversation to make room for new ones. Compaction always seems to happen at the most frustrating and inconvenient time, which makes sense when you think about it. You hit context limits precisely when you’ve put the most information into the conversation, which is exactly when losing that information costs you the most.当你在编写 skills 和 agents 时，往往会快速遇到上下文问题。你让 AI 执行的任务往往足够复杂，以至于上下文窗口被填满，AI 必须开始压缩：压缩或丢弃旧的对话部分以腾出空间。压缩总是在最让人沮丧、最不方便的时候发生，这很合情合理。你正好在把最多信息放进对话时触及上下文限制，而这正是失去这些信息代价最大的时刻。
That’s why I think it can often help to think of AIs as having the same shortcomings that human teams do, except those shortcomings are exaggerated by their AI nature. A person who forgets something from a meeting last week might remember it when you remind them. An AI that lost something to context compaction won’t, because the information is gone. But there’s something you can do about it, and it turns out the techniques that help are the same whether you’re building autonomous AI skills or just trying to get a chatbot to remember what you told it 20 minutes ago.这就是为什么我认为把 AI 看作拥有与人类团队相同的缺点是有帮助的，只是这些缺点因其 AI 本质被放大了。一个人如果忘记了上周会议的内容，提醒一下他他可能会记起来。而因为上下文压缩而丢失信息的 AI 则不可能，因为信息已经消失。但你可以采取措施，事实证明，无论是构建自主 AI skills 还是让聊天机器人记住你 20 分钟前说的话，帮助的技术都是相同的。
I’ve landed on four techniques that I come back to over and over again. Each one exists because at some point the AI forgot something important and I responded by putting that thing in a file where it couldn’t be forgotten. None of them require special tooling. And to my surprise, all of these techniques have turned out to be useful for both building software and managing a writing project like this one, whether I’m chatting with Claude, ChatGPT, or Gemini, or using a desktop tool like Claude Cowork or Codex. These are the techniques I find most valuable:我总结出四种技术，我会一遍遍地回到它们。每一种都是因为某次 AI 忘记了重要信息，我于是把这件事写进了一个文件，防止它再被忘记。它们都不需要特殊工具。令我惊讶的是，这些技术对软件开发和管理像本文这样的写作项目同样有用，无论我是在和 Claude、ChatGPT、Gemini 对话，还是使用 Claude Cowork、Codex 等桌面工具。以下是我认为最有价值的技术：
- Split discovery from documentation: Don’t ask the AI to figure something out and produce polished output in the same pass.将发现过程与文档编写分离：不要在同一次请求中让 AI 既要发现问题又要生成精炼的输出。
- Use handoff documents, not continuation prompts: Before closing a stale session, have the AI write down everything the next session needs to know.使用交接文档，而不是继续提示：在结束一个会话之前，让 AI 把下一次会话需要了解的所有信息写下来。
- Give the AI an acceptance criterion, not a procedure: Tell it what “done” looks like instead of spelling out the steps.给 AI 一个验收标准，而不是一个步骤流程：告诉它“完成”应该是什么样子，而不是逐步列出该怎么做。
- Use spec documents as the bridge between AI tools: Make a shared document the single source of truth that all your tools read from.使用规范文档作为 AI 工具之间的桥梁：创建一个共享文档作为所有工具读取的唯一真相来源。
Split discovery from documentation将发现过程与文档编写分离
When you ask an AI to do something complex, you’re often asking it to do two things at once without realizing it. You’re asking it to figure something out and produce polished output at the same time. The problem is that figuring things out takes attention, and producing output takes attention, and the model only has so much of it. When you combine both tasks in the same prompt, the model starts cutting corners on one of them, and you can’t tell which one it shortchanged.当你让 AI 做复杂任务时，往往不自觉地让它一次完成两件事：既要发现问题，又要生成精炼的输出。问题在于，发现需要注意力，生成输出也需要注意力，而模型的注意力是有限的。当你把这两个任务合在同一个提示里时，模型会在其中一个上偷工减料，而你根本不知道它偷了哪一个。
I ran into this with the Quality Playbook, an open source AI coding skill I built that runs structured code reviews against any codebase. One of the things it does is derive requirements from source code: It reads through the code, identifies what the code promises to do (I call these behavioral contracts), and then produces a requirements document. Originally this all happened in a single pass. The problem was that single-pass requirement generation ran out of attention after about 70 requirements. The model forgot behavioral contracts it had noticed earlier in the code, and the forgetting was completely invisible. There was no stack trace or error message, just incomplete output and no way to know what was missing. I fixed it by splitting the work into two separate prompts:我在 Quality Playbook 中遇到了这个问题——这是我构建的一个开源 AI 编码 skill，用于对任意代码库进行结构化代码审查。它的一个功能是从源代码中推导需求：它阅读代码，识别代码承诺要做的事情（我称之为行为契约），然后生成需求文档。最初，这一切都是在一次请求中完成的。问题是，单次需求生成在大约 70 条需求后就耗尽了注意力。模型忘记了之前在代码中注意到的行为契约，而这种遗忘是完全不可见的。没有堆栈跟踪或错误信息，只有不完整的输出，且无法知道缺少了什么。我通过把工作拆分为两个独立的提示来解决：
Read each source file and write down every behavioral contract you observe as a simple list in CONTRACTS.md.读取每个源文件，将观察到的每个行为契约写入 CONTRACTS.md 的简单列表中。
Read CONTRACTS.md and the documentation, then derive requirements from them and write REQUIREMENTS.md.读取 CONTRACTS.md 和文档，然后从中推导需求并写入 REQUIREMENTS.md。
Then a third pass checks whether every contract has a corresponding requirement, and if there are gaps, goes back to step one for the files with gaps.随后第三次检查每个契约是否都有对应的需求，如果有缺口，则返回第一步处理有缺口的文件。
The key idea is that CONTRACTS.md 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. You can see what was forgotten and fix it.关键在于 CONTRACTS.md 充当了外部记忆。当模型“忘记”了之前注意到的行为契约时，这种遗忘通常是不可见的。有了契约文件，所有观察都会在开始需求工作前被记录下来，因此未覆盖的契约会成为可见、可搜索的缺口。你可以看到被忘记的内容并进行修正。
The principle: Don’t ask the AI to figure out what exists and write formatted output in the same pass. The model runs out of attention trying to do both at once. Whenever you’re asking an AI to do something complex, consider whether you’re actually asking it to do two things at once. “Analyze this codebase and write a report” is two tasks. “Read this document and suggest improvements” is two tasks. Split them, and let the first pass write its observations to a file before the second pass starts working with them.原则：不要让 AI 在同一次请求中既要发现存在的内容又要写出格式化的输出。模型在同时做两件事时会耗尽注意力。每当你让 AI 做复杂任务时，考虑它是否实际上被要求一次完成两件事。“分析这个代码库并写报告”是两个任务。“阅读此文档并提出改进建议”也是两个任务。把它们拆开，让第一次请求把观察写入文件，再让第二次请求基于这些文件工作。
Use handoff documents, not continuation prompts使用交接文档，而不是继续提示
Anyone who’s spent a long session with an AI coding tool has felt the moment when the context starts to go stale. The AI stops tracking details it was handling fine an hour ago, or it contradicts something it said earlier. The session gets slow, and you’re often restarting because the AI seems to have gotten bogged down and filled up on what you told it. You get the sense that if you keep going, you’re going to spend more time correcting it than making progress.任何长时间使用 AI 编码工具的人都经历过上下文开始变陈旧的时刻。AI 停止跟踪一小时前还能正常处理的细节，或者与之前的说法相矛盾。会话变慢，你常常需要重新启动，因为 AI 似乎被你提供的信息塞满了。你会感觉如果继续下去，你将花更多时间纠正它而不是取得进展。
Most developers respond to their session getting too long in one of two ways: They push through the problem, or they start a fresh one and try to reexplain everything from scratch. Both of those approaches can cause the AI to lose context. The first loses it to compaction; the second loses it to incomplete reexplanation. And both are frustrating! Specifically because you just spent so much time building up all that context with the AI.大多数开发者会以两种方式应对会话过长：要么硬着头皮继续，要么重新开始并从头解释所有内容。这两种方式都会导致 AI 丢失上下文。第一种会因压缩而丢失，第二种会因不完整的重新解释而丢失。而且两者都让人沮丧！尤其是因为你已经花了大量时间与 AI 构建了这些上下文。
There’s a third option. Before you close the session, ask the AI to write a handoff document: a file that captures everything the next session needs to know, written while the current session still has full context. The key is that you’re asking the AI to write this while the relevant details are still fresh in the working context, and in a way that it or another AI can read.还有第三种选择。在关闭会话之前，让 AI 编写交接文档：一个捕获下一次会话需要了解的所有信息的文件，在当前会话仍拥有完整上下文时编写。关键是让 AI 在相关细节仍然新鲜且可被读取时写下这些内容，以便后续的 AI 或其他 AI 能读取。
I built this into the Quality Playbook as a core part of how phases communicate. When I split the playbook from a single prompt to independent phases, I needed each phase to run as a completely independent session with no context carryover. So each phase got its own kickoff prompt as a standalone file. Here’s the structure each one follows:我把这套方法嵌入到 Quality Playbook 中，作为各阶段之间通信的核心。当我把 Playbook 从单一提示拆分为独立阶段时，需要每个阶段都作为完全独立的会话运行，不能携带上下文。因此每个阶段都有自己的启动提示，作为独立文件。每个阶段的结构如下：
Write a handoff document that a fresh session could use to pick up this work cold. Include everything it would need to know.编写一个交接文档，使全新会话能够从头接手此工作。包括它需要了解的所有内容。
Every kickoff opens with what prior phases accomplished, includes explicit boundaries about what’s frozen, and names which future phase owns each piece of remaining work, because without it the AI will helpfully start doing Phase 3 work while you’re still in Phase 2. Each phase also ends with a required forward-looking handoff where the completing agent writes down what the next session needs to know.每个启动提示都说明了前置阶段完成了什么，明确哪些内容已冻结，并指明未来哪个阶段负责剩余工作，因为如果不这么做，AI 会在你仍在第二阶段时就开始执行第三阶段的工作。每个阶段还以必需的前瞻性交接结束，完成的代理会写下下一次会话需要了解的内容。
The principle: Each handoff is a complete state snapshot. The incoming AI agent never needs to read prior kickoff prompts or chat history. Everything it needs is in the current handoff file: current state, uncommitted changes, immediate next task, pending tasks, file locations, and anything that was discovered during the prior session. A fresh AI session can pick it up cold.原则：每个交接都是完整的状态快照。进入的 AI 代理永远不需要读取之前的启动提示或聊天记录。它所需的一切都在当前的交接文件中：当前状态、未提交的更改、立即的下一个任务、待办任务、文件位置以及前一次会话中发现的任何内容。全新的 AI 会话可以直接冷启动。
If you’re deep into a Claude Code or Copilot session and you can feel the context getting stale, ask the AI to write a handoff document before you close the session. Tell it to include everything a fresh session would need to continue the work. Then start a new session and point it at that file. A fresh session with a good handoff document will usually outperform a stale session, because it’s starting with clean context instead of compacted, fragmented context.如果你在 Claude Code 或 Copilot 会话中感到上下文变陈旧，在关闭会话前让 AI 编写交接文档。告诉它包括全新会话继续工作所需的所有信息。然后启动新会话并指向该文件。带有良好交接文档的全新会话通常会优于陈旧会话，因为它使用的是干净的上下文，而不是被压缩、碎片化的上下文。
Give the AI an acceptance criterion, not a procedure给 AI 一个验收标准，而不是一个步骤流程
When you give an AI a multistep task, the natural instinct is to spell out the steps. First do this, then do that, then combine the results. The problem is that step-by-step procedures are the first thing the AI forgets when the context window fills up. It’ll skip steps, merge phases, or quietly drop tasks, and there’s nothing in the procedure itself that would help the AI notice what it missed. The procedure tells the AI what to do, but it doesn’t tell the AI what “done” looks like.当你给 AI 一个多步骤任务时，自然的冲动是把步骤全部写出来。先做这个，再做那个，然后合并结果。问题是，当上下文窗口被填满时，步骤流程是 AI 最先忘记的内容。它会跳过步骤、合并阶段或悄悄丢弃任务，而流程本身并不能帮助 AI 发现它遗漏了什么。流程告诉 AI 要做什么，但并没有告诉 AI “完成” 应该是什么样子。
I learned this the hard way with the Quality Playbook. The playbook runs multiple iteration passes over a codebase, and the results need to be cumulative. It keeps a list of all the bugs it finds in the code being tested in a file called BUGS.md. Early on, I gave the AI a procedure to run four times and then update that file:我在 Quality Playbook 中深有体会。该 Playbook 对代码库进行多次迭代，每次结果都需要累积。它在一个名为 BUGS.md 的文件中记录所有发现的 bug。起初，我给 AI 一个指令，让它运行四次迭代并更新该文件：
First run the main pass, then run four iteration passes, then merge the findings into BUGS.md.先运行主遍，然后运行四次迭代遍，最后将发现合并到 BUGS.md。
The AI did not respond well to that instruction.AI 对此指令的响应并不好。
It turns out that when you ask an AI to do a very complex task a specific number of times, it can lose count. In fact, from my experimentation, it seems that count is one of the first casualties of context compaction. Most of the time the AI decided three iterations was enough, or merged findings from only two passes, and no matter how many different ways I tried to rephrase that instruction, there was nothing I could come up with that prevented the problem.事实证明，当你让 AI 完成一个非常复杂的任务并要求执行特定次数时，它会失去计数。根据我的实验，计数是上下文压缩的首批受害者之一。大多数情况下，AI 认为三次迭代就足够，或者只合并了两次的发现，无论我怎样改写指令，都无法根除这个问题。
However, everything changed when I replaced the “run four times” instruction with an acceptance criterion, or a specific condition that tells the AI when to stop looping:然而，当我把 “运行四次” 的指令换成验收标准，或一个告诉 AI 何时停止循环的具体条件时，一切都改变了：
You are done only when BUGS.md contains the cumulative findings from the main run plus all four itration passes.只有当 BUGS.md 包含主运行加上所有四次迭代的累计发现时，你才算完成。
Even when the AI lost track of intermediate steps, it could check the output against the criterion and know whether it was finished. And I could verify the output against the same criterion, which gave me a way to audit the agent’s work without watching every step.即使 AI 失去了对中间步骤的追踪，它仍然可以根据该标准检查输出是否完成。而我也可以根据同一标准验证输出，这为我提供了一种在不监视每一步的情况下审计代理工作的方法。
In developer terms, the AI is really bad at loops like for (i = 0; i < 4; i++) because it loses track of the value of the iterator i when it compacts its context. But it’s really good at loops like while (!done) because it can check done based on the current state without relying on history.用开发者的语言来说，AI 对类似 for (i = 0; i < 4; i++) 的循环非常糟糕，因为在压缩上下文时它会失去对迭代器 i 的追踪。但它对 while (!done) 之类的循环却相当擅长，因为它可以基于当前状态检查是否完成，而不依赖历史。
The principle behind all this is that an acceptance criterion survives context pressure because the AI can always check “Am I done?” against a concrete test. This is actually the same principle behind test-driven development: write the test before the code so you know when you’re done. The acceptance criterion is the test for your AI session. When you’re giving an AI a task that has multiple steps, don’t describe the steps. Describe what “done” looks like, and let the AI figure out how to get there.背后的原则是：验收标准能够在上下文压力下存活，因为 AI 总能根据具体测试检查 “我完成了吗？” 这实际上与测试驱动开发的原理相同：先写测试再写代码，这样你就知道何时完成。验收标准就是你 AI 会话的测试。当你给 AI 一个多步骤任务时，不要描述步骤，而是描述 “完成” 的样子，让 AI 自行决定如何达成。
Use spec documents as the bridge between AI tools使用规范文档作为 AI 工具之间的桥梁
Most developers working with AI don’t use just one tool. You might use Claude for design, Cursor for coding, and Copilot for quick edits. You might even use multiple models inside the same tool, like GPT-5.5 and Opus 4.7 in separate Copilot chats inside VS Code. It’s common to have one model for coding, another for review, and a third for orchestration and project management. The problem is that none of these tools or chats know what you told the others. Claude doesn’t know what you decided with Cursor. Two separate Copilot chats in the same editor don’t share context. You’re the one carrying context between them, and that’s exactly the kind of lossy handoff that causes drift. A design decision you made in one conversation gets lost or distorted by the time it reaches the tool that needs to implement it.大多数使用 AI 的开发者并不只用一种工具。你可能用 Claude 做设计，用 Cursor 编码，用 Copilot 做快速编辑。甚至在同一个工具里使用多个模型，例如在 VS Code 的 Copilot 聊天中同时使用 GPT-5.5 和 Opus 4.7。常见的做法是让一个模型负责编码，另一个负责审查，第三个负责编排和项目管理。问题是这些工具或聊天之间并不知道彼此的上下文。Claude 不知道你在 Cursor 中做了什么决定。两个在同一编辑器中的 Copilot 聊天也不共享上下文。你必须在它们之间携带上下文，这正是导致漂移的有损交接。你在一次对话中做的设计决定，到达需要实现的工具时可能已经丢失或被扭曲。
The fix is to make the spec document the single source of truth that all your AI tools read from. I used this when building a game prototype, where I had Claude handling design and planning and Cursor doing the coding. They never talked to each other directly, so the spec documents served as the shared contract: Claude wrote the specs, and Cursor read them. The rule I followed was simple:解决办法是把规范文档设为所有 AI 工具读取的唯一真相来源。我在构建一个游戏原型时使用了这种方式，当时 Claude 负责设计和规划，Cursor 负责编码。它们从未直接交流，规范文档充当了共享契约：Claude 编写规范，Cursor 读取。我的规则很简单：
Never tell the AI coder something that isn’t already in the specs. If you make a design decision in conversation, write it into the spec first, then point the coder at the spec.永远不要把未写入规范的内容告诉 AI 编码者。如果在对话中做了设计决定，先把它写进规范，再指向编码者。
If I made a design decision in a conversation with Claude, that decision had to be written into the spec before I told Cursor about it. If I discovered something during implementation, I wrote it into the appropriate doc first, then pointed the coder at it. The spec was always the single source of truth. When Claude and I changed the wound topology (removing one wound type, promoting another), we updated the docs first, then told Cursor to reread them. When we decided to add a new UI element, we wrote it into the UI spec first, then told Cursor to reread the doc.如果我在与 Claude 的对话中做了设计决定，必须先把决定写进规范，然后再告诉 Cursor。如果在实现过程中发现了新东西，也先写进相应文档，再指向编码者。规范始终是唯一的真相来源。当 Claude 和我更改伤口拓扑（移除一种伤口类型，提升另一种）时，我们先更新文档，再让 Cursor 重新读取。当我们决定添加新的 UI 元素时，先把它写进 UI 规范，再让 Cursor 重新读取。
The key was including rationale in the specs. Not just “show 5 progressive labels” but why: “The player shouldn’t be told what they’re fighting. They should discover it.” This helps the AI coder make better decisions when the spec doesn’t cover an edge case because it knows the intent behind the requirement.关键是把背后的理由写进规范。不只是 “显示 5 个递进标签”，而是解释为什么：“玩家不应该被告知他们在对抗什么，他们应该自行发现。”这帮助 AI 编码者在规范未覆盖的边缘情况时做出更好的决定，因为它了解需求背后的意图。
The principle: The spec document is the shared context that all your tools can read. It prevents the drift that happens when design intent lives only in chat history that the other tool can’t see. This technique works any time you’re using more than one AI tool on the same project, which at this point is most projects.原则：规范文档是所有工具可以读取的共享上下文。它防止了设计意图仅存在于聊天记录而其他工具看不到时产生的漂移。这种技术在同一项目中使用多个 AI 工具时都适用，而这在如今已经是大多数项目的常态。
How these techniques combine: Managing this article series这些技术如何组合：管理本文系列
Those four practices came out of AI-driven development work, but they apply to almost any AI work. And while these techniques emerged for me while working on agents and skills, I think it’s valuable to demonstrate them in a nondevelopment context, so I’ll share an example from my work on the article series you’re reading now.这四个实践源自 AI 驱动开发工作，但它们几乎适用于所有 AI 工作。虽然这些技术最初是为我在代理和技能上工作时总结的，我认为在非开发场景中展示它们也很有价值，所以我将在这里分享一个我在撰写本文系列时的实际例子。
Over time, the process for how my AI assistant and I manage this article backlog evolved organically in conversation, but it was never written down anywhere except in the AI’s context window. Which means every time the session compacted or I started a fresh chat, the process was gone and I had to reexplain it. I caught this when the AI did something slightly wrong and I wanted to confirm we were on the same page. So I asked:随着时间的推移，我的 AI 助手和我管理文章待办事项的流程在对话中自然演化，但从未以任何形式记录下来，只有在 AI 的上下文窗口中。这意味着每次会话被压缩或我开启新聊天时，流程就会消失，我必须重新解释。我在 AI 出现轻微错误并想确认我们是否在同一页面时注意到了这一点。于是我问：
Every time I suggest a new article idea, you add an entry to the backlog, and then create a new markdown file with the source material, right?每当我提出一个新文章想法时，你会在待办列表中添加一条记录，然后创建一个包含源材料的新 markdown 文件，对吗？
That’s split discovery from documentation. I didn’t say “document our process.” I said “confirm what we do.” Discovery first, then documentation as a separate step. If I’d said “write up our process” without confirming first, the AI might have written something plausible but wrong, and I wouldn’t have caught the discrepancy.这就是将发现过程与文档编写分离。我没有说 “记录我们的流程”。我说的是 “确认我们在做什么”。先发现，再单独记录。如果我直接说 “写下我们的流程”，AI 可能会生成看似合理但错误的内容，我也就无法发现差异。
Once we’d confirmed the process, I asked the AI to create two files. AGENTS.md is an emerging standard for AI-readable project context—a single file that tells any AI session what it needs to know about a project. You can learn more about the convention at agents.md. CONTEXT.md serves a similar role as a bootstrapping document—it’s less established as a standard, but the practice of asking the AI to dump everything it knows into a context file so the next session can pick it up cold has been one of the most valuable habits I’ve developed. Here’s the prompt I used:确认流程后，我让 AI 创建两个文件。AGENTS.md 是一种新兴的 AI 可读项目上下文标准——一个文件告诉任何 AI 会话它需要了解的项目内容。你可以在 agents.md 上了解更多。CONTEXT.md 扮演类似的引导文档角色——虽然它还不是标准，但让 AI 将它所知道的一切导出到一个上下文文件，以便下次会话可以直接冷启动，这已经成为我最有价值的习惯之一。以下是我使用的提示：
Update the backlog file to explain what it is and how we maintain it. Create a CONTEXT.md with everything you’d need to bootstrap a new chat. Create an AGENTS.md to make it easy to bootstrap with a single-line prompt.更新待办文件，解释它是什么以及我们如何维护它。创建一个 CONTEXT.md，包含你需要的所有信息以启动新聊天。创建一个 AGENTS.md，以便通过单行提示轻松启动。
That prompt is a handoff document. I was explicitly asking the AI to write down everything it knew while it still had full context, specifically because I knew that context would be lost to compaction. The CONTEXT.md file is a handoff from this session to whatever fresh session picks up the work next week.这个提示本身就是交接文档。我明确要求 AI 在仍拥有完整上下文时把它知道的所有信息写下来，因为我知道这些信息会因压缩而丢失。CONTEXT.md 文件就是从本次会话到下周任何新会话的交接。
Notice what I didn’t say. I didn’t give step-by-step instructions for what should go in those files. I said “everything you would need to bootstrap this process again in case we lost it” and “a complete dump of all of the context you would need to bootstrap a new chat and get it to the point where this current chat is.” Those are acceptance criteria, not procedures. The AI had to figure out what belonged in those files. If I’d given it a procedure (“first write the publication history, then the voice rules, then the file locations”), it would have followed the list and missed anything I forgot to include. The acceptance criterion is harder to satisfy but more robust: the test is “Could a fresh session bootstrap from these files alone?”注意我没有说什么。我没有给出文件内容的逐步指令。我说的是 “把你在本次会话中需要的所有信息写下来，以防我们丢失”，以及 “完整导出所有上下文，以便新聊天能够达到当前会话的状态”。这些是验收标准，而不是流程。如果我给出流程（先写出版历史，再写语音规则，最后写文件位置），AI 会按顺序执行，可能会遗漏我忘记的内容。验收标准更难满足，但更稳健：测试是 “全新会话能否仅凭这些文件启动？”
And the AGENTS.md file itself is a spec document as a bridge between tools. It’s the shared contract that any AI session, whether it’s Claude, Gemini, Cowork, or a fresh chat, can read to get aligned with the project. This session wrote it; the next session reads it. The two sessions never communicate directly, so the spec file bridges the gap between them.而 AGENTS.md 本身就是在工具之间充当桥梁的规范文档。它是任何 AI 会话（无论是 Claude、Gemini、Cowork 还是全新聊天）都可以读取的共享契约，以便与项目保持一致。本会话写入它，下一会话读取它。两次会话之间没有直接通信，规范文件弥合了它们之间的鸿沟。
That’s all four practices in two prompts, applied to something as ordinary as managing a writing project. It didn’t require pipelines or codebases or batch orchestration. The practices work because they solve the same underlying problem regardless of the domain: important information living in the AI’s context window instead of on disk.这就是四个实践在两个提示中的全部应用，甚至用于管理写作项目这种普通任务。它不需要流水线、代码库或批处理编排。之所以有效，是因为它们解决了相同的底层问题：重要信息存在于 AI 的上下文窗口而不是磁盘上。
Context management is a development skill上下文管理是一项开发技能
Every practice I’ve described in this article and the last one is something developers have always been told to do: write things down, record your rationale, be deliberate about what you save and what you let go, write ADRs and design docs and inline comments explaining nonobvious choices. We’ve always known we should do more of it. When you’re working with AI, the cost of not doing it becomes immediate and visible.本文以及上一篇文章中描述的所有实践，都归结为同一点：把重要信息写入文件，使压缩无法触及，这样你就能看到 AI 知道什么，并验证它是否与现实相符。下一篇文章我将更深入探讨调试角度：如何使用外部化文件了解 AI 实际在做什么，并提供即使不构建代理、仅使用聊天机器人的实用技术。
The practices in this article all come down to the same thing: putting the important information in files where compaction can’t touch it, so you can see what the AI knows and verify that it matches reality. In the next article, I’ll go deeper on the debugging angle: how to use externalized files to understand what your AI is actually doing, with practical techniques that work even if you’re not building agents but are just using a chatbot.Quality Playbook 是开源的，可与 GitHub Copilot、Cursor 和 Claude Code 配合使用。它也作为 awesome-copilot 的一部分提供。
The Quality Playbook is open source and works with GitHub Copilot, Cursor, and Claude Code. It’s also available as part of awesome-copilot.披露：本文所述方法的部分内容已于 2026 年 4 月 20 日由作者提交美国临时专利申请号 64/044,178。开源的 Quality Playbook 项目（Apache 2.0）在 Apache 2.0 许可证条款下向该项目的用户授予专利许可。
Disclosure: Aspects of the approach 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.探索相关文章
