Superpowers 生成的文档很容易过期
superpowers skills 会在 docs/superpowers 目录下生成设计文档（specs）和执行计划（plans）。
刚开始使用时，我会把这些 specs 文档一起提交到 Git 仓库。后来逐渐发现，随着开发持续推进、产品不断迭代，这类文档很容易变得过时，最终与最新代码产生偏差。
问题在于，Agent 往往无法判断一份文档是否已经过期。
我就遇到过这样的情况：Agent 在调试 Bug 时读到了旧的设计文档，并把其中的内容当成当前标准。当它发现代码实现与文档不一致后，反而按照过期文档去修改代码，最终把原本正确的实现改错了。
这让我开始重新考虑：这类文档是否真的适合长期保存在 Git 仓库中。
如果这些文档已经没有持续维护的价值，最简单的做法就是直接从 Git 中删除。
如果仍然希望保留它们作为历史记录，又不希望它们干扰 Agent，可以在 docs/superpowers 目录下增加一个 AGENTS.md 文件，明确告诉 Agent：这里的内容只是归档资料，不能作为当前实现的依据。
mattpocock skills 对生成文档做了更合理的分类
相比之下，mattpocock skills 对不同类型文档的生命周期处理得更合理。
TIP
mattpocock skills 包括20多个互相配合的skills。 主要包括：grill-with-docs、to-spec、to-tickets、implement、code-review等。
详细使用教程见其作者的网站：https://www.aihero.dev/skills
它会生成 CONTEXT.md 和 ADR 等文档。
CONTEXT.md 主要用于记录领域词汇，本质上对应 领域驱动设计（DDD） 中的 Ubiquitous Language。
这类信息具有长期价值。它可以统一团队与 AI 对业务概念的理解，减少因为术语含义不一致而产生的沟通成本，因此非常适合长期保存在 Git 仓库中，并随着代码一起维护。
ADR（Architecture Decision Record） 则用于记录关键的架构决策。
每份 ADR 都会包含自己的状态（status）。当架构决策发生变化时，不需要直接修改或删除旧 ADR，而是创建一份新的 ADR，并把旧文档标记为已经被新的决策取代。
这样既能保留历史决策过程，又能让 Agent 明确知道哪一份文档才代表当前有效的架构决策。
另一方面，to-spec、to-tickets 生成的规格、任务和执行计划等短期文档，并不会长期存放在 Git 中，而是交给外部 Issue 跟踪系统管理。
从这个角度看，这套 Skills 实际上是按照文档的生命周期，把生成内容分成了两类：
- 长期持续有价值的知识，例如领域语言和架构决策，存放在 Git 中，并持续维护。
- 短期有效的工作过程信息，例如任务跟踪、规格说明和执行计划，存放在 Issue 跟踪系统中。
这种分类方式更符合实际的软件开发过程。
真正值得长期进入 Git 的，应该是那些能够随着代码持续演进、并且在未来仍然具有参考价值的知识。
而 specs、plans、tickets 这类文档，本质上更多是在描述“这一阶段准备做什么”以及“接下来怎么做”。一旦开发完成或需求发生变化，它们的价值就会迅速下降。
如果这些已经过期的工作过程文档仍然和代码放在一起，反而可能给 Agent 提供错误上下文。
因此，一个更合理的原则是：
长期知识进入 Git，短期工作过程留在 Issue 系统；如果历史文档必须保留，就明确标记其状态，避免 Agent 把过期内容当成当前事实。