长周期项目最容易积累的是信息，不是知识。聊天记录越来越长，代码提交越来越多，截图、架构图、测试报告和文档散落在不同目录。几个月后还能搜索到“做过什么”，却很难回答“为什么这样做、现在还成立吗、哪条证据支持它”。
TeachFlow 最后形成 26 篇文章地图，真正有价值的并不是文章数量，而是它迫使我把项目记录重新组织成一套可以审阅的知识结构。
聊天记录为什么不是知识库
聊天保留了探索过程，也混合了：
- 尚未执行的建议；
- 后来被推翻的假设；
- 对旧版本成立的结论；
- 临时排障命令；
- 用户明确冻结的范围；
- 已经完成但没有证据指针的总结。
如果直接把聊天摘要当作项目事实，最危险的问题不是漏掉内容，而是把不同证据状态压成同一种“记忆”。
五层项目知识结构
第一层：源码与可执行事实。
当前提交、类型、合同、迁移、测试脚本和真实运行产物，是可复核的基础。
第二层：决策记录。
记录 context、alternatives、decision、consequence、status 与 revisit trigger。它解释为什么系统长成现在这样，但不能替代运行证据。
第三层：证据索引。
把 claim 对应到源码、回归、浏览器截图、数据库状态或外部资料，并标注 verified、code-confirmed、partial、blocked、superseded。
第四层：专题地图。
架构图、工作流、生命周期和文章地图回答“这些事实之间是什么关系”，避免读者只能沿时间线翻几千行日志。
第五层：公开叙事。
面向读者选择一个问题，使用必要证据和图解释机制，同时移除本地路径、私密数据和无法支持的生产声明。
为什么决策要和事实分开
英国 Government Digital Service 建议把影响服务架构的决定保存在版本控制中，使用 title、status、context、decision 和 consequences 等字段；当已实现的决定被推翻时，应创建新的记录并把旧记录标为 superseded。Martin Fowler 也强调 ADR 的价值不仅是多年后解释系统，也在于写作过程本身迫使人澄清分歧。
TeachFlow 的实践与这个原则接近：DESIGN_DECISIONS.md 保存当前重要决策，项目亮点与演进.md 保存更完整的演进时间线，文章包里的 claims.md 则逐条声明公开说法和缺失证明。三者不能合并成一个万能文档：
- 时间线适合回答“何时发生”；
- ADR 适合回答“为什么决定”；
- claim ledger 适合回答“凭什么公开说”。
AI 在这里负责什么
AI 可以帮助搜索长记录、聚类主题、发现冲突、生成初稿、检查链接和把证据映射为结构化清单。它尤其适合从大量散乱信息中提出“可能值得写的文章”。
但作者仍必须负责四件事：
- 选择当前权威源码，而不是最容易找到的旧总结；
- 判断两段相似表述是重复、演进还是冲突；
- 决定哪些公开说法会越过证据；
- 对最终叙事和遗漏承担责任。
因此，每个 TeachFlow 文章包都保留 sourceCommit、claims.md、media-manifest.yaml 和 draft: true。AI 可以产出提案，个人博客工作区才拥有最终导入与发布权。
5W2H 仍然有用，但必须加上证据
Why、What、Where、When、Who、How、How much 能帮助一篇文章避免只讲实现。例如：
- Why：为什么要改变；
- Who：谁使用、谁决定、谁受影响；
- How much：成本、覆盖与收益如何衡量。
但项目写作还需要两个问题：
- Evidence：哪条源码、运行或外部资料支持这句话？
- Limits：什么还没有证明，什么条件会推翻它？
所以我实际采用的是“5W2H + Evidence + Limits”。这不是新方法论命名，而是一条写作自检：问题结构不能替代证据边界。
一篇文章如何从记录中产生
以“转班之后，历史学情属于哪个班”为例：
- 从演进记录发现“班级历史不能由 Current 倒推”的决定；
- 回到
classroom-trajectory.ts和专项脚本确认当前机制； - 用最小时间线反例解释错误；
- 查阅 OneRoster 的 Enrollment beginDate/endDate 作为外部领域参照；
- 在 claims 中把本地机制标为 code-confirmed，把跨校与真实制度留存标为 blocked；
- 生成解释图，但把真实浏览器截图保持 blocked，直到当前提交重跑。
这条流程让文章既不是聊天摘录，也不是把源码换成中文。
如何避免知识体系再次变成文档堆
最有效的限制是单一职责和停止条件：
- 当前能力只在一个状态文档维护；
- 未完成事项只进入路线图；
- 每个文章包只回答一个中心问题；
- 相同结论只保留一个权威指针；
- 新证据若推翻旧结论，标记 superseded，不静默覆盖；
- 没有新能力、反例或验证时，不继续增加文章。
26 篇不是越多越好，而是当前范围内已经去重后的上限。
当前边界
这个知识体系目前由个人与 AI 协作维护，没有真实多人团队的信息架构实验，也没有衡量检索时间、文章维护成本或新成员上手速度。文章包校验只能证明文件合同完整，不能证明所有技术结论正确；源码和外部网页变化后仍需要人工刷新。
常见问题与设计边界
为什么不用 Notion 或向量数据库统一保存？
工具可以提供搜索，但不能自动解决权威、版本和证据状态。当前先用 Git 可追踪文件形成合同，之后可以增加索引，不让索引替代来源。
如何处理过时文章？
对比 sourceCommit 与当前基线，重新检查 material claims；若结论失效，创建修订或标记 superseded，而不是只更新发布日期。
AI 会不会把不存在的讨论补出来？
会，所以公开文章的关键 claim 必须回到源码、可执行证据或明确的用户事实；找不到来源就标 partial/blocked 或删除。
参考资料
- The GDS Way：Documenting architecture decisions
- Martin Fowler：Architecture Decision Record
- 5W2H 分析法参考
- TeachFlow
ARTICLE_SERIES_MAP.md、DESIGN_DECISIONS.md、项目亮点与演进.md与各文章claims.md
结论
个人知识体系不是“把所有记录永久保存”，而是让重要结论始终能回到来源、状态和边界。聊天帮助发现问题，源码决定当前事实，证据决定能说多大，地图帮助读者理解关系，文章负责把一个问题讲清楚。只有这几层彼此分工，长期项目才不会被自己的历史淹没。