做 AI 协作工具时，我越来越确信一件事：真正麻烦的不是模型偶尔答错，而是它会在相似场景里反复答错。
一次纠正当然不难。难的是，纠正之后，这条经验到底沉淀到了哪里。很多时候，修正只存在于一段聊天记录里，或者存在于操作者脑子里。下一次换个上下文、换个仓库、换个提问方式，AI 还是会把同样的问题再来一遍。
team-pitfalls 就是在这个背景下长出来的。
它最初只是一个“团队踩坑收集器”，目标很朴素：把那些容易重复犯错的规则记下来，避免下一次再踩。但随着使用场景变多，我发现“记下来”远远不够。一个真正有用的 Skill，不应该只是个归档器，它还得在下一轮任务开始前主动参与判断，提醒系统哪些地方已经有过代价不低的错误。
这篇文章不打算讲一个功能清单，而是想拆开 team-pitfalls 的几个关键设计：为什么它后来会变成双层知识库，为什么我把它固定成“前置检查 + 后置复盘”的流程，以及为什么最终选择了最小设计，而不是继续往里堆迁移、同步、自动归档之类的能力。
问题不是“记不住”，而是“知识不会参与决策”
一开始，team-pitfalls 只服务于通用规则沉淀。比如：
- 内部文档和平台内容优先通过 MCP 获取，而不是直接抓网页
- README 里不要写个人机器上的绝对路径
- 提交信息优先给一条主线，而不是一堆并列候选
这类规则本身没问题，而且确实能复用。但写着写着，另一个问题就冒出来了：很多错误并不是“通用规范”意义上的错，而是业务语义理解错了。
例如，同一个缩写，在不同仓库里的含义可能完全不同；某些流程词在通用语境里很好理解，但落到具体业务里就会变成误判。用户会在对话里把这些问题纠正回来，但如果 Skill 没有一个合适的结构承接它们，下次还是会错。
这时候我意识到，原先的思路有一个明显缺口：它只能沉淀“跨仓库通用规则”，却装不下“某个仓库里反复出现的业务知识”。
问题到这里就从“经验收集”变成了“知识分层”。
从单层踩坑库，到双层知识结构
team-pitfalls 后来的核心变化，是把原本单层的通用踩坑库，拆成了两层：
- 通用层：继续记录跨仓库、跨项目都成立的规则
- 仓库层：按仓库名维护业务黑话和 AI 被纠正过的理解
通用层继续放在 references/*.md 里，承载的是所有项目都可能复用的共性约束。仓库层则单独落到 references/repos/<repo-name>/，每个仓库维护三份文件：
INDEX.md：局部索引glossary.md：业务黑话、术语映射、缩写解释corrections.md：AI 理解错后，被用户纠正过的记录
这个设计有两个直接收益。
第一，通用规则和业务知识终于分开了。以前最危险的地方在于，所有“值得记住的事”都挤在一个篮子里，最后会让规则越来越糊。通用层一旦混入仓库私有语义，就不再通用；仓库层如果混入全局规则，也会让索引越来越难用。拆层之后，边界一下清楚很多。
第二，Skill 终于有了更合理的加载顺序。team-pitfalls 明确把优先级收敛成一句话：
仓库级校验 > 通用校验
这不是形式问题，而是判断顺序本来就应该如此。业务语义错了的时候，先谈通用规范并没有意义。必须先把“这个词在这个仓库里到底是什么意思”校准，再谈路径、文档、提交信息这些横向规则。
只会存档的 Skill，还是不够好用
如果 team-pitfalls 只是多了一层仓库目录，它仍然只是一个更复杂的知识库，不算“自迭代”。
真正让它发生质变的，是流程上的第二次收敛：我把它从“用户需要时再调用的收集器”，改成了一个固定两段式流程。
第一段：对话前检查
只要本轮任务命中了高频易错场景，比如整理规范、改 README、沉淀业务黑话、用户正在纠正上一轮输出，那么在正式回答前，必须先读索引和相关条目，做一次“这类坑之前记过没有”的检查。
这一步的意义，在于让历史知识前置参与当前决策，而不是等答错以后再回头补档。
第二段：对话后复盘
本轮任务准备结束时，再回看一次本轮对话和产出，判断有没有新的通用坑、仓库黑话、纠错记录值得沉淀。
有价值就写入，没有价值也要明确说明“本轮检查过，但不记录”。
这条要求看起来很啰嗦，但它其实是在解决一个很现实的问题：很多系统都强调“支持沉淀”，真正落地时却没有人负责判断“这次该不该记”。结果就是规则越来越依赖操作者自觉，最后又退化回人工记忆。
我后来越来越倾向于把这类动作做成强制流程，因为只有流程固定了，知识循环才会稳定。
为什么最后放弃了“迁移机制”
在 team-pitfalls 的演进里，还有一个挺典型的分叉点：一度考虑过做“坑位迁移机制”。
思路并不复杂。既然 Skill 在不断迭代，那是不是应该支持把旧版本目录里的案例、其他仓库里的 references/ 内容批量迁进来，避免重复录入？
这个想法一开始看起来很合理，甚至挺完整。但认真往下拆，会发现它很快就把系统带向了另一个方向：
- 你要处理来源差异
- 要定义迁移规则
- 要考虑去重和冲突合并
- 要解释迁移后索引怎么维护
- 还要说明哪些内容能迁，哪些内容不能迁
到这里，系统的重心就变了。原本要解决的是“如何让错误经验参与下一轮决策”，最后却容易变成“如何维护一个越来越复杂的知识搬运系统”。
这也是 team-pitfalls 最重要的一次设计收缩：放弃迁移机制，回到最小设计。
所谓最小设计，不是功能少，而是只保留真正影响闭环的环节：
- 任务开始前检查已有坑
- 任务结束后判断是否值得沉淀
- 通用规则和仓库知识明确分层
- 写入统一走脚本，避免手工维护格式和索引
从结果看，这个取舍是对的。它没有把系统做成一个“知识平台”，而是保住了它最核心的身份：一个在 AI 协作流程里真实生效的约束器。
让 Markdown 持续可用，比引入新存储更重要
另一个我刻意克制的点，是没有把这套系统做成数据库或服务化索引。
team-pitfalls 现在依然以 Markdown 为主，索引和条目都直接落在仓库里，配合脚本统一写入。表面看这有点“土”，但它非常符合这个场景的实际需求。
首先，知识本身就是给人看的。工程规范、术语映射、纠错记录，天然适合直接阅读和版本管理。Markdown 的可审阅性、可追踪性、可比对性，在这里比“结构更强”更重要。
其次，这套知识不需要复杂查询能力。它需要的是稳定的目录、清晰的边界、确定的写入格式，以及在任务开始前能被按需加载。对于这种规模的系统，引入数据库并不能显著提高效果，反而会增加额外的同步和维护成本。
所以最后的策略是：存储保持朴素，把复杂度放在流程和边界上，而不是放在基础设施上。
一个 Skill 真正变“聪明”，靠的不是提示词，而是约束结构
回头看 team-pitfalls 的开发历程，我觉得最有意思的地方并不是它最终支持了多少文件格式、多少命令参数，而是它让我更明确了一件事：AI 工程协作里，真正稳定的不是一次写得更好的 prompt，而是让纠错信息进入后续流程的结构。
team-pitfalls 现在的状态，仍然很朴素。它没有炫技式的自动化，也没有把知识管理包装成一个庞大的系统。但正因为它把边界收得足够紧，反而更接近一个能长期工作的方案：
- 该通用的，放通用层
- 该仓库私有的，放仓库层
- 该在回答前检查的，不留到回答后补救
- 该复盘的，不靠“这次刚好想起来”
如果要用一句话概括这次迭代，我会说：
team-pitfalls 不是把“过去错过什么”记下来，而是把“这些错误以后怎样影响当前决策”真正做进了 Skill 的工作流里。
这也是我现在理解的“自迭代 Skill”。
它不是自己长功能，而是每次被纠正之后，都会更具体地约束下一次自己该怎么做。
代码仓库
team-pitfalls 收录在 xiy-skills 仓库中：
