我怎样用个人 Wiki 记录项目

10 min

写代理网络那篇文章时, 我已经记不清几个月前具体改过什么了.

那套网络每天都在用, 真要写它是怎样搭起来的, 却只能想起一句折腾了很久. 改过哪些配置, 为什么改, 都得重新查.

我和 AI 翻回以前留下的记录. 有些故障查明了原因, 有些只是恢复了连接; 有些备用路径早就写在配置里, 后来才真正验过它能不能接管. 当时觉得不会忘的细节, 到了今天, 已经不能只凭印象分辨.

这些资料存在我的个人 Wiki 里: Markdown 文件, 几页索引, 按项目整理的事实和维护记录. 写文章时, 我从里面找回了不少已经忘掉的细节.

我不想每次都重新交代背景

和 AI 一起做事久了, 我发现, 把背景说清楚本身就是一份工作.

一个项目为什么这样安排, 哪个方案已经试过, 哪一步只是编译通过, 哪一步确实用起来了. 这些事情在当时的对话里都很清楚. 可是换一次任务, 隔一段时间, 又得把它们从头铺开.

重讲一遍也未必能讲全. 人往往记得结论, 却忘了结论成立的条件. 记得那天说过可以, 却未必记得后面还有半句: 在这个环境里可以, 另一端还没有验证.

于是, 我开始把这些东西往固定的地方放. 不再任由它们留在不同的聊天窗口, 等到需要时再凭几个关键词翻找.

项目有项目的页, 做事的方法有工作流的页. 某个决定写下缘由, 某次验证留下边界. 下次接着做, 先读相关记录, 再去看眼前的文件和实际环境.

让记录进入工作流

只有一个文件夹还不够. 文件可以越积越多, 经验却未必更容易找. 一份笔记写在这里, 另一份留在那里, 内容相近, 日期不同, 到最后连自己也说不准该信哪一份.

所以我给这套知识库配了一个 wiki skill. 它是一份交给 AI 的查阅与维护规则: 从哪里找, 先读什么, 哪些内容值得写下, 写到哪里, 又有哪些东西不该放进去.

需要接续项目时, 先看索引, 找到对应的页面, 只读与眼前这件事有关的部分. 完成了有用的工作, 再把新的事实和决定整理回去. 页面确实属于哪个项目, 就写回哪个项目; 归属还拿不准, 先留下待整理的记录.

知识库的位置固定. 我可以在不同项目之间来回切换, 记录仍回到同一个地方, 不会在日后面对许多个副本.

最好在事情刚弄清楚时就整理. 那时还记得为什么改, 验证了什么, 哪个疑问没解决. 等很久以后再补, 常常只记得结果.

一次值得保留的收尾, 也就多了几件小事: 更新相关页面, 写清验过什么, 留下尚未完成的部分, 在维护记录里添上日期和简短说明.

没有新结论的检查不用反复抄写, 已经说清的事情也不用换个措辞再存一遍. 否则下次查资料, 还得从一堆重复内容里找答案.

它在项目里省下了什么

这些规矩的用处, 要在具体事情里才看得出来.

比如这个博客. 第一次上线, 要弄清内容放在哪里, 怎样构建, 怎样部署, 又怎样确认外面的人确实能打开. 这些做完以后, 知识库里便留下了维护记录. 到第二篇文章要发布, 不用再把服务器和目录重新摸一遍. 先找到那份记录, 核对仓库里的发布脚本, 就能沿用已经走通过的流程.

省下来的不只是几条命令. 我知道这套站点不需要数据库, 知道发布前该做哪些检查, 也知道旧版本留在哪里. 真出了问题, 不必一边着急, 一边重新找退路.

代理网络的记录里也有这样的例子. 软路由上曾经有一条为内网互联工具准备的 UDP 直连规则, 后来发现范围太宽, 会让普通的 STUN 请求也直接出去. 后续记录写下了怎样收窄它, 怎样重新验证. 如果只看早先的配置, 很容易又把已经修过的问题改回来.

还有跨设备接着做事的时候. 某一端同步成功, 不等于另一端也拿到了最新内容. 把已确认和待确认的部分分别记清, 下次开始就知道该先检查哪一端, 不必把整套流程再跑一遍, 也不会把旧副本误当成新的起点.

有时, 最有用的甚至是一个没有采用的决定. 当时为什么觉得某个方案收益不大, 为什么暂时保留简单的做法, 如果只留下最后的配置, 这些考虑是看不出来的. 记下理由, 再遇到相似建议时, 就可以先问条件有没有改变, 而不必重新争论一遍.

记录里要分清已经确认和仍待确认

怀疑一个原因和查明原因要分开写, 本地页面能打开和线上可以访问也要分开写. 一端的文件更新了, 另一端尚未核对, 就明确记下哪一端还要检查.

因此, 确认的事实放进项目页, 暂时的线索另行留下. 原始材料也保留自己的位置, 不因为后来有了新的理解, 就回头把旧材料改成新结论. 真要追问一件事, 仍然有来处可以核对.

还有些内容, 本来就不该出现在普通笔记里. 密码, 令牌和密钥, 不会因为一句顺手的总结, 就被带进项目页或维护日志. 需要知道它们在哪里, 和需要把它们写在这里, 是两回事.

旧笔记也可能过时. 曾经正常的服务今天未必正常, 上一次用的配置也可能已经变了. Wiki 用来查过去确认过什么, 当前状态仍要到实际环境里检查.

Task Anchor 和 Wiki 分别记什么

与 Wiki 一起用的, 还有 Task Anchor.

一项长任务还没做完时, Task Anchor 记下目标, 约定, 已确认的进度和下一步. 对话中断或者上下文经过压缩后, 可以先读这份简短记录.

比如, 文章写好了, 但我还没审稿. 那么眼下该做的是本地预览, 而不是发布. 这类约定, 就适合留在任务锚点里.

等这项工作完成, 锚点可以收起来. 工作中形成, 以后仍有用的经验, 再整理进 Wiki. 前者记眼下未完成的事, 后者保存以后还会查的内容.

两者都不需要事事启用. 简单的问题, 直接回答就好. 我不想为了防止遗忘, 让每一件小事都先经过一套仪式.

真正需要它们的时候, 是那些投入过时间, 隔天还要继续, 或者日后值得重访的事情.

写博客时, 这些记录也用上了

以前记这些, 主要是为了继续做项目. 现在写博客, 它们也成了查证材料. 哪次恢复了连接, 哪个猜测后来被推翻, 哪条备用路径实际测过, 都能找到对应记录.

AI 帮我查阅和整理, 我再核对当时的决定和反馈. 这样写出来的经过有具体细节, 不用把几个月的工作概括成一句折腾了很久.

↑ 回到顶部