Cursor对话历史不可复用，必须转译为PROGRESS.md、ARCHITECTURE.md等项目文件及docs/ai-guide/下的短文档，否则每次新会话均需重复解释设计决策。
直接说结论：Cursor 的对话历史本身不构成可复用的维护资产，必须主动把它“转译”成项目文件，否则每次打开新 session 都得重新解释一遍 pkg/auth 为什么用 Claims 而不是 map[string]interface{}。
为什么不能依赖默认对话历史做维护
Cursor 默认对话历史是会话级、无结构、不可搜索的。你在上周五调试 payment_service 时让 AI 分析过 RetryPolicy 的 fallback 逻辑，但这段对话不会自动关联到 internal/retry/config.go，也不会被下次问“怎么改重试次数上限”时召回。
常见错误现象包括：
- 反复解释同一个模块的职责（比如第 3 次告诉 AI “
pkg/metrics只上报 P99 和 error count，不存原始日志”） - AI 在重构时误删
legacy/下的兼容函数，因为没读过你上次写的迁移 checklist - 跨分支协作时，同事新开 session 完全不知道你三天前已确认
DB transaction isolation level必须设为RepeatableRead
把对话历史变成可维护资产的三步操作
核心思路：不保存“聊了什么”，而保存“聊出了什么结论”，并让这些结论落地为代码库的一部分。
- 每次对话结束前，强制执行：
请总结本次 session 达成的共识、修改点、待验证假设，并更新 PROGRESS.md 和 ARCHITECTURE.md - 对关键设计决策，单独生成 Markdown 文件并提交 Git，例如：
PLAN_idempotency_v2.md或DECISION_api_versioning_strategy.md - 把高频问答沉淀为
docs/ai-guide/下的短文档，命名直白，如：how-to-add-new-middleware.md、when-to-use-context-with-value.md
这样下次有人问“怎么加一个 auth middleware”，AI 就会先读 docs/ai-guide/how-to-add-new-middleware.md，而不是靠模糊回忆你上个月某次对话里提过的 echo.MiddlewareFunc 写法。
用 @Past 引用旧对话时的真实限制
@Past 看起来方便，但实际在大型 Go 项目中容易失效，原因很实在：
- 它只引用对话摘要，不带类型定义或测试用例 —— 而 Go 项目最依赖这两样来保证行为一致
- 如果旧对话里讨论的是
user_service，新对话聚焦notification_service，@Past带来的上下文噪声反而干扰 AI 判断依赖边界 - 当项目有多个 Git 分支时，
@Past "v1.2 auth refactor"可能指向一个已被 rebase 掉的 commit，导致 AI 基于过期代码推理
真正稳定的做法是：用 go test ./pkg/auth/... 的输出 + pkg/auth/types.go 的当前内容作为上下文，而不是依赖某次对话里 AI 曾经写过的伪代码。
哪些对话历史值得手动导出并归档
不是所有对话都值得留。只导出三类：
- 架构评审结论：比如导出为
ARCHITECTURE_review_20260510_websocket_scaling.md，含性能压测数据和分片策略 - 安全加固过程：比如导出为
SECURITY_audit_20260508_jwt_validation.md，含漏洞复现步骤和修复 diff - 线上故障复盘：比如导出为
INCIDENT_postmortem_20260505_db_lock.md，含 pprof 图、SQL trace 和 rollback checklists
这些文件要放进 docs/ 目录，且每份开头加一行 <!-- GENERATED_FROM_CURSOR_SESSION: 20260510-1422 --> ，方便未来用脚本批量索引。别图省事扔进 .specstory/ 就完事 —— 那个目录没人会去 grep。
最常被忽略的一点：Go 的 go mod graph 输出和 go list -f '{{.Deps}}' ./... 结果，比任何对话历史都更能说明模块真实依赖。维护大型系统时，宁可花 2 分钟让 AI 解析这些命令结果，也不要指望它从 3 天前的聊天记录里猜出 pkg/cache 实际被多少 service import 了。
