在偶尔答错并不是真正的问题，真正麻烦的是它在相似场景里反复答错。一次纠正往往很容易，但如果这些经验没有被程序化存储。下一次换个上下文、换个仓库、换个提问方式，AI 仍会重复一样的错误。

从痛点一来看。经验未能沉淀

很多时候，修正只存在于单条聊天记录或操作者的记忆里。相同错误频繁出现由缺乏统一的知识库导致。

team-pitfalls 的诞生

team-pitfalls 最初是一个“团队踩坑收集器”，目标是把易犯错的规则记录下来避免下一次再踩。老实说，但因为使用场景 “记下来”远远不够。真正有用的 Skill 必须主动参与判断，在下一轮任务开始前提醒程序哪些地方已有代价不低的错误。

主要设计拆解

• 双层知识库：
  • 通用层: 跨仓库、跨项目适用的规则。老实说，
  • 仓库层: 按仓库维护业务和已被纠正过的理解。
• 前置检查 + 后置复盘流程：
  • 前置检查: 在任务开始前读取索引和相关条目，做一次“这类坑之前记过没有”的检查。
  • 后置复盘: 任务结束后回顾对话和产出，判断是否值得沉淀新规则。
• 最小化设计原则：
  • - 只保留对闭环影响最大的环节；按理说，- 避免复杂迁移、同步、自动归档等功能带来的维护成本。

痛点二的观点是。知识无法参与决策

原先的思路只能沉淀“跨仓库通用规则”，但无法容纳“某个仓库里反复出现的业务知识”。这导致 AI 在面对具体业务语义时仍会误判，因为缺少针对性的校准。

双层结构带来的收益

• 清晰分层：“通用规则”与“业务知识”分离。 避免混淆，使索引更易用，
• 优先级顺序：“仓库级校验> 通用校验”——先校准业务语义，再考虑横向规则。

从痛点三来看。手工维护成本高且易失效

AIs 的错误经验往往需要手动写入或更新文件，而程序没有强制流程来保证这一操作。结果是很多规则依赖操作者自觉，最终退化为人工记忆，没有真正实现闭环。

强制流程的关键性

• “对话前检查”确保历史知识参与当前决策；“对话后复盘”让新发现的坑及时写入或明确不记录，从而保持知识质量。怎么说呢，“统一脚本写入”避免格式差异和手工维护问题。

Pain Point 4：复杂迁移机制带来的副作用

`team-pitfalls` 曾考虑过实现坑位迁移机制，以批量导入旧版本目录里的案例。但拆解后发现，这一功能会导致程序转向知识搬运网站方向：需要处理来源差异、迁移规则、去重冲突、索引维护等多重复杂度。从而偏离了最初解决“如何让错误经验参与下一轮决策”的主要目标。按理说，最终决定放弃迁移机制，回归最小设计。

A Skill 真正变聪明的方法：约束结构而非提示词

`team-pitfalls` 并未采用炫技式自动化，也未将知识管理包装成庞大程序；它通过紧凑边界 + 明确分层 + 强制流程 + 简单目录存储,成为在 AI 协作流程中真实生效的约束器。

`

# 通用层
references/*.md
# 仓库层
references/repos//INDEX.md
references/repos//glossary.md
references/repos//corrections.md
# 流程
1️⃣ 对话前检查 - 加载索引 &amp，amp;amp，amp;amp，# 确认是否已知此类坑 
├─ 仓库级校验> 通用级校验
└─ 提前调整提问或回答策略
2️⃣ 对话后复盘 - 判断是否出现新坑 / 新术语
├─ 写入对应文件
└─ 若无新内容，则标注“不记录”
3️⃣ 单一脚本写入 - 保持格式一致性与索引完整性
4️⃣ 无数据库。无服务化索引 - 仅依靠目录结构与静态文件即可满足需求
`
`
*以上为可直接粘贴到 Markdown 文件中的代码块示例*

代码仓库位置 &

`team-pitfalls` 已收录于 xiy-skills 仓库中：