working-docs

工作文档

核心原则

_working/<topic>/ 是外部任务记忆：只保留后续工作确实会用到的笔记、证据和中间产物。

只有在删除某个文件会改变后续操作、决策、交接或审计时，该文件才值得保留。如果没有这个文件夹，任务也能以完全相同的方式完成，就不要创建它。

工作文档服务于用户请求的任务。它们不会扩大任务范围、增加额外的审查或测试义务，也不会把简单任务变成需要记录的项目。

启用条件

如果用户明确要求使用工作文件夹，就使用工作文档。否则，以下条件中至少有两项成立时再使用：

• 任务涉及多个阶段、来源、文件或系统；
• 发现可能会改变后续计划；
• 任务可能会中断、压缩上下文或需要交接；
• 其他 Agent 或流程需要明确命名的中间产物；
• 结论必须在会话结束后仍可审计。

不要将其用于一次性答复、微小修改，或下一次工具调用之后就不再需要中间状态的工作。即使技能已预加载，也要重新评估这些条件。

位置

在工作目录附近创建一个稳定的文件夹，通常放在仓库根目录，除非用户指定了其他路径：

<repo-root>/_working/<topic-slug>/
  README.md         # current state and entry point
  <other files>     # only evidence, drafts, prompts, or outputs later work needs

README.md 应让新的 Agent 能够接手工作：说明根本需求、重要约束、当前状态、决策、阻碍、下一步，以及需要读取的文件。

除非用户希望将 _working/ 纳入版本控制，否则不要将其提交。请从仓库根目录检查实际生效的忽略规则：

git check-ignore -q _working/

如果该目录未被忽略，请将 _working/ 添加到 .git/info/exclude。只有用户明确要求制定适用于整个仓库的规则时，才修改受版本控制的 .gitignore。如果当前目录不在仓库内，就使用工作目录，不要创建 Git 配置。

保留内容

只记录对后续工作有价值的信息：

• 决策，以及决策所依据的证据或约束；
• 不应重蹈覆辙的失败方案；
• 会影响结论的路径、ID、版本、确切输入和来源引用；
• 用户的更正及其对计划造成的变化；
• 未解决的问题、阻碍、恢复信息和下一步；
• 其他阶段、流程或人员会使用的计划、提示词、草稿或报告。

不要倾倒本身并非证据的原始输出，不要重复最终答复，不要维护含糊的活动日志，也不要仅仅因为模板建议创建文件就写文件。

工作记忆循环

1. 深入工作前先建立基础。 创建 README.md，写明需求、重要约束、当前状态和下一步。
2. 发生重要变化时更新。 出现决策、可复用的发现、方向变化、持久性阻碍或产物时，及时记录，而不是每次工具调用后都记录。
3. 记录具有权威性时再读取。 中断或上下文压缩后、交接前、其他 Agent 返回后，或在依据已记录证据作出决策前，读取 README.md。不要为了形式反复重读未更改的文件。
4. 保持入口信息最新。 计划或状态发生重大变化时，更新 README.md，使其指向权威产物。
5. 材料充分后停止。 一旦后续工作可以继续，且所有声称存在的产物都有据可查，就不要添加回顾文件或进行后续操作不需要的润色。

委派与交接

当其他 Agent 或流程需要使用工作文件夹时：

• 提供准确的 _working/<topic>/ 路径；
• 指明必须读取的输入文件和必须生成的输出文件；
• 要求重要主张附上来源路径或证据；
• 依赖指定输出前，先读取该输出。

声称已写入文件的摘要，并不能证明文件确实存在。如果预期文件缺失或无法读取，应报告缺少该产物，而不是将委派任务视为已完成。

有界验证

使用最小的直接检查来验证有关工作文档的声明：

1. 列出相关文件夹；
2. 回读 README.md 以及你将声称其存在或内容如何的每个产物；
3. 确认阻碍事项和后续步骤对于交接或最终回复仍然足够新。

这仅验证工作基础。关于产品行为、代码、部署或硬件的声明，需要来自所属任务的证据；工作文档不会触发无关的测试、完整测试套件、审查或现场操作。