reflect

核心用法

Reflect 是 SpecWeave 生态中的自我学习记忆系统，核心机制是在会话结束时自动分析对话内容，提取用户纠正、规则确立和模式认可等信号，将其转化为结构化学习记录并持久化到本地文件。系统采用三级存储架构：技能专属 MEMORY.md（如 frontend、backend）、项目级分类记忆（.specweave/memory/）和全局记忆（~/.specweave/memory/）。用户可通过 /sw:reflect 手动触发反思，或启用 /sw:reflect-on 实现会话结束自动学习。

显著优点

零重复纠正：用户无需在每次新会话中重复说明项目规范，AI 自动加载已学习的模式。例如首次纠正"使用设计系统的 Button 组件"后，后续会话自动应用该规则。

技能精准路由：基于优先级检测系统（显式技能名 > 关键词匹配 > 分类回退），学习记录自动归类到对应技能文件，避免信息混杂。

智能合并机制：市场更新时用户学习记录永不覆盖，新默认规则智能去重合并，并自动创建备份，确保知识资产安全。

质量管控严格：内置七项检查清单（完整性、可执行性、特异性、独立性、非问题性、非抱怨性、上下文充分性），拒绝存储低质量片段。

跨平台兼容：支持 Claude Code 原生环境（~/.claude/plugins/...）和普通项目环境（.specweave/...），Windows/macOS/Linux 全平台覆盖。

潜在缺点与局限性

学习提取依赖对话质量：模糊表达如"这样不太好"难以转化为有效学习，需要用户明确使用"总是/从不/使用/避免"等指令性语言。

无向量语义检索：采用纯 Markdown 文件存储，依赖关键词触发匹配，复杂语义关联场景下召回率有限。

技能检测存在误判：关键词匹配可能将数据库查询讨论路由到 database 技能而非 backend 技能，需手动 --skill 参数修正。

学习记录膨胀风险：单技能默认上限 50 条学习记录，长期高频使用下可能需要手动清理或归档。

隐私边界需用户把控：虽然系统承诺不存储原始对话，但学习记录中的上下文字段可能包含项目敏感信息，需用户自行审查。

适合的目标群体

• 长期项目开发者：需要维护数月甚至数年的代码库，保持跨会话一致性
• 团队技术负责人：沉淀团队编码规范、架构决策，实现知识传承
• 多技能切换用户：同时在前后端、DevOps、架构设计等角色间切换，需要上下文隔离
• AI 协作高频用户：每日与 Claude 进行多轮深度协作，追求效率最大化

使用风险

存储位置风险：记忆文件默认存储在用户主目录，多设备同步时需手动处理 ~/.specweave/ 或 ~/.claude/ 目录，否则出现学习记录不一致。

版本兼容风险：v4.0 与旧版 v3.0 存储格式并存，虽然官方声明无需迁移，但长期可能产生碎片化文件。

过度学习风险：AI 可能将临时性妥协（"这次先这样"）误判为持久规则，需定期 /sw:reflect-status 审查并清理。

备份依赖风险：虽然合并时自动备份，但用户主动删除或磁盘损坏无云端恢复机制，重要项目建议 git 跟踪 MEMORY.md 文件。

性能影响：技能激活时需加载 MEMORY.md 内容，极端情况下（单技能 50+ 条学习记录）可能增加 token 消耗和响应延迟。