slopdocs

slopdocs

你的规划文档、Bug 调查记录和功能说明，是你产出的最有价值的成果。代码反而不值多少钱。没有这些文档，下一个 Agent 就得从零开始，每次都重新推导相同的约束，并重新争论相同的权衡。

这项技能定义文档存放的位置，以及何时应创建文档。它是一个归档系统，不是写作流程。使用其他技能（头脑风暴、编写计划、系统化调试等）生成内容，再使用 slopdocs 决定内容的存放位置。

受众：其他 Agent，而非人类

Slopdocs 是一个 Agent 留给下一个 Agent 的笔记。内容密集、不加修饰，但准确无误。它们保留原本会在每次会话中从头推导的上下文。

项目也可能有面向人类的文档，通常位于 docs/、README.md、wiki 或文档网站中。这类文档目标不同（引导入门、公开参考、营销），行文惯例也不同。Slopdocs 不能替代它们，也不应存放在那里。同样，不要把 slopdocs 写入 docs/ 或其他面向人类的位置。

如果用户只说“文档”，却没说明是哪种，请先询问。面向 Agent 的 slopdocs 和面向人类的文档存放在不同位置，阅读方式也大不相同——弄错了就白费功夫。快速确认一下，就能避免产出错误的文档。

约定

文档存放在项目根目录下的 slopdocs/ 中，包含三个子目录：

slopdocs/
├── features/
│   └── <feature>.md
├── bugs/
│   └── YYYYMMDD-<short-slug>.md
└── plans/
    └── YYYYMMDD-<feature>.md

slopdocs/features/<feature>.md

每个功能维护一份文档，描述该功能当前的工作方式：数据模型、关键逻辑和设计决策。功能发生变化时更新文档。

slopdocs/bugs/YYYYMMDD-<short-slug>.md

每次 Bug 调查对应一个文件，以日期为前缀。修复记录在提交历史中。文档保留相关上下文：走过的弯路、误导性线索和根因分析。这些上下文能避免下一个 Agent 重复同一项调查。

slopdocs/plans/YYYYMMDD-<feature>.md

每次规划会话对应一个文件，以日期为前缀。写代码前先写计划。功能发布后也保留计划。阅读原始计划，是日后理解功能最快的方式。

每个功能对应一份持续维护的文档。Bug 和计划则是特定时间点的快照。日期前缀便于按时间排序，也能避免命名冲突。

何时编写 slopdoc

• 你花了大量时间思考，或者遇到了真正的架构分岔。
• 某个 Bug 的根因不明显，其他人很可能还会遇到。
• 你正在构建新功能。保存已经生成的计划。
• 某项决策三个月后看起来会很奇怪，届时可能有人想把它“重构”掉。

何时跳过

• 差异本身就是文档。重命名、重新格式化、依赖升级。
• 改动微不足道，而且很容易撤销。
• 写文档比写代码花的时间还长。
• 你会重复其他 slopdoc 中已有的内容。改为链接到它。

如何编写

这些是一个工程师写给另一个工程师的笔记。内容要精炼。先说明决策，再说明理由。记录尝试过哪些替代方案，以及它们为何行不通。写成一份杂乱的要点列表也没问题。准确但不加修饰，胜过精美却过时。

不要写给人类快速浏览的状态更新或摘要。要写下文档，让下一个 Agent 能立即阅读并采取行动。

开始修改前

修改已有文档的功能前，先阅读相关 slopdocs。查看 slopdocs/features/ 中的持续维护文档，以及 slopdocs/plans/ 中该领域的历史背景。

与其他技能协作

Slopdocs 是归档系统，其他技能负责生成内容。两者同时启用时，使用其他技能的流程来编写文档，然后将文档保存到 slopdocs 对应路径，而不是保存到该技能通常使用的位置。

使用 superpowers（头脑风暴、编写计划、系统化调试）

头脑风暴／设计规范：

• 按照头脑风暴技能的流程编写设计规范。
• 将规范保存到 slopdocs/features/<feature>.md，而不是 docs/superpowers/specs/。这将成为持续更新的功能文档。随着功能演进，持续更新该文档。

实现计划：

• 按照编写计划技能的流程编写计划。
• 将计划保存到 slopdocs/plans/YYYYMMDD-<feature>.md，而不是 docs/superpowers/plans/。
• 功能发布后仍保留计划。这是之后了解该功能最快的方式。

Bug 调查：

• 按照系统化调试技能的流程进行调查。
• 如果调查结果值得留存（根因不明显、排查过程曲折，或以后还会有人遇到），请将调查记录保存到 slopdocs/bugs/YYYYMMDD-<short-slug>.md。

使用任何其他会生成文档的技能时

同样遵循这个原则：使用技能编写文档，将文件存放在 slopdocs 中。如果技能会将计划保存到 docs/plans/、.sisyphus/plans/ 或其他路径，请按照上述文件名约定，将其重定向到对应的 slopdocs/ 路径。

没有其他技能处于活动状态时

按照上文“如何编写文档”中的指南自行编写文档。无需遵循特殊流程，只需将文档放入正确的文件夹即可。