让 LLM 维护可追溯的项目决策日志
作者只让 LLM 在 Wiki 中维护决策及其理由、移动端与后端的跨端流程,每项决策保留原始讨论链接。首批手工页面整理了41条有来源的决策,其他信息继续留在各自的权威来源中。
AI 深度解读
让 LLM 写团队 Wiki,最容易走偏的地方,是把所有资料都搬进去。作者只让它补两类信息:有出处的决策理由,以及跨移动端和后端的业务流程。代码、接口规范、设计稿继续留在原处。
这套做法已经整理出 41 条带来源的决策,但页面是否被实际使用,还没有确认。值得读的是它如何划定知识边界、保留证据,以及为什么作者最终同时保留了 Wiki 和实体图谱。
为什么只让 LLM 写两类内容
作者是一款面向美容院的移动应用的 PM,文中涉及皮肤诊断功能。团队原本想用 Wiki 记录技术选型理由,但更新逐渐落后,最后只剩实现,丢了原因。
代码能告诉你系统怎么运行,却未必解释当初为什么接受某个限制,也不容易直接呈现移动端与后端之间的完整流程。因此,作者把 LLM 的写入范围压得很窄:
- 决策及其理由,而且理由必须已经写在来源中,每条附上 Backlog 评论或 PR 的引用。
- 跨移动端和后端的流程,用 Mermaid 时序图表达。
其余资料继续各归其位:视觉信息留在 Figma 和代码里,API 规范留在 OpenAPI,已经写在代码注释中的决策理由也不搬家。
这套 Wiki 的价值,是补上现有资料之间缺失的解释。
例如,团队只在后端检查 20 项上限,并接受并发创建时出现 21 项。记录的理由是:计数列或排他锁不适合面向会员的表单;达到 21 项后不会继续增长,删除一项就回到上限。来源是 2 张工单中的 3 条评论。
另一条决策是,保存数值字段时,同时保存当时的正常范围。原因很具体:以后调整正常范围,不应改写过去的判断。这样的记录保留了取舍,后续维护者才能判断原来的前提是否仍然成立。
Wiki 怎样积累知识,又不替来源编理由
作者采用的是 Karpathy 在 2026 年 4 月发布的「LLM Wiki」思路:在原始资料与读者之间,增加一层持久保存、相互链接、由 LLM 维护的 Wiki。
原文将它与常见 RAG 流程对比:每次提问都重新检索,答案不会自然积累成可维护的知识页。不过,这是作者对常见工作流的概括,不能据此认定所有 RAG 系统都无法积累知识。
这套结构分三层:人收集且保持不变的原始资料、LLM 维护的 Wiki,以及规定结构和规则的 schema。操作分为 Ingest、Query、Lint,即导入、查询和检查。
落到团队里,资料来自发布分支上的移动端与后端代码、PR 正文与评审、Backlog 工单与评论。团队直接利用开发过程中已有的材料,没有另外建立一套人工采集流程。
承载工具也是现成的 GitHub Wiki。规则写在技能 update-llm-wiki 的 SKILL.md 中,索引用 _Sidebar.md,变更记录依靠 Wiki 的 git 历史。
关键约束是:理由必须来自资料。模型可以整理和关联,不能把自己推测的动机写成团队已经作出的解释。
首次提交发生在 2026-11-17 19:37,涉及 5 个文件,新增 270 行。页面包括功能总览,其中有 API 和 8 张表;两张决策页;以及数据流页面中的两张时序图。两张手工整理的决策页共计 41 条有来源的决策,其中 OCR 导入页 24 条,自定义字段页 17 条,数量按页面中的来源行统计。
已经有实体图谱,为什么还要 Wiki
作者此前在 2026-10-02 向同一 Wiki 加入过实体图谱,把屏幕、API、用例和数据表表示成节点及关系,规模为 30 个文件、20,947 行,通过 ask-entity-graph 技能查询,用于故障排查和新人入职。
图谱和决策日志承担不同任务。图谱保存能从代码中机械提取的结构关系,例如某个屏幕调用哪些 API、最终关联哪些表。决策日志保存代码之外的理由,例如为什么允许并发时短暂超出数量上限。
原文提到,有人认为代码知识主要是关系,Markdown 不适合,图谱更好。作者最后选择两者并用。这种分工有道理:查影响范围需要关系,理解历史取舍需要带出处的解释。
我的判断
我认同作者先限制写入范围的做法。维护对象越明确,越容易检查模型有没有越界,也更容易避免 Wiki 与 OpenAPI、Figma、代码之间出现多份答案。
但它依赖一个前提:团队已经在工单或 PR 中写下理由。如果讨论只发生在口头交流里,LLM 无法从实现结果可靠还原当时的考虑。来源链接能支持核查,也不能自动证明整理后的解释准确、完整。
效果目前也要打个问号。41 条决策、270 行新增内容说明资料已经落地,不等于检索效率或入职效率得到改善。作者明确说尚未确认页面是否被使用,也没有给出与人工维护、直接搜索工单或 RAG 的对照数据。这仍是一套值得参考的实践,尚不足以证明维护收益。
至于无人参与的自动更新,作者留给了后续文章,本篇没有交代具体实现。
能拿来做什么
- 给现有项目补决策日志时,先从一项争议较多的功能开始,每条只写决策、来源中明确记录的理由和出处,缺少理由就标明缺失。
- 前端与后端联调时,可以把跨端流程整理成 Mermaid 时序图,并让接口细节继续以 OpenAPI 为准,减少重复维护。
- 把「当时为什么这样做」和「现在代码如何连接」分开查询;已有代码关系图谱的团队,可以用带来源的决策页补充历史取舍。
- 试用后记录页面是否帮助解决了真实问题,例如解释数量限制或追溯字段规则,再决定是否扩大维护范围。