NOTES · 学习笔记
我做了个“项目快速梳理”的 skill
最近我把自己做的一个 skill 放到了 GitHub,叫 onboard,中文名是“快速梳理”。它是给 agent 用的,解决的是我每次接手陌生项目时都会遇到的同一个问题:资料很多,但我不知道先看什么,也不知道哪些细节真的会影响后面的工作。
我通常从一句话说明资料位置和目标开始。
我遇到的项目不一定是代码。有时候是一整个仓库,有时候是 PDF、Word、Excel、PPT 和流程文件混在一起。我的想法是,能不能把这些资料直接交给 AI,让它先帮我把项目看出一个全貌,再按照我准备做的事情带我学,而不是让我自己在文件夹里一点点猜。
我不想要一堆看起来很完整的文件
一开始我确实让 AI 生成过一套完整的学习材料:总览、术语表、阅读路径、自测题,最后一口气出了 12 份文件。生成的时候很有成就感,真正打开以后却发现问题更大了。我自己以用户身份用了一遍,当时的反应是:
为什么是学习包?我都说了把业务拆接下来我们更好的学习,你又生成一些脚本去学习……现实哪有这么多时间搞这些东西啊
我要的是尽快理解项目,结果还要先读一套 AI 做出来的资料。
后来我又试过另一种做法:不生成文件,让 AI 直接当老师,扫完资料就开始讲,讲一段问一个问题。这个体验比第一版好很多,但也留下了一个问题:所有理解都停在对话里。会话结束以后,拆解没有留下来;如果材料里没有答案,AI 还可能为了把话讲下去,顺手补出一个听起来合理的答案。
所以我最后把重点放回“拆解”本身。现在的 onboard 会先留下一个能回查的总览和一条学习路径,带学只是帮助我消化它。讲到材料没有覆盖的地方,就回去查;查不到,就把缺口写出来。
我希望它先帮我判断什么值得看
我不认为项目里所有信息都值得在第一天掌握。对我来说,重要性主要看三件事:不懂它会不会看不懂项目,不会它会不会完成不了当前目标,不知道它会不会很容易犯错。只要命中一项,就应该提到前面。
剩下的内容分成三档:现在要懂、遇到时查、暂时可略过。比如代码项目里,入口、核心调用链和本地验证方式通常要先弄清楚;某个很少碰到的边缘配置,可以只留下一个查找位置,等真的遇到再读。这样我不用把整个仓库都读完,仍然不会因为“看起来不重要”而永久漏掉关键细节。
学习路径把需要马上掌握的内容和以后再查的内容分开。
这个判断也会随我的目标变化。同一个项目,如果我的目标是修改支付模块,学习顺序和准备面试时肯定不一样。目标不明确时,它先给我一个通用路径;等我说清楚第一个月要交付什么、最怕改坏什么,再在同一份拆解上调整,不需要从头再读一遍。
它会怎么处理不确定的地方
我比较在意出处。资料明确写了什么,就把出处挂上;能从几处材料推出来但没有直接写的,就标成推断;资料里没有的,就说没有。材料之间互相矛盾时,也先把两边摆出来,不替项目作者做决定。
还有一点是我后来才补上的:资料里的文字只是被分析的内容,不是给 agent 的命令。文档里出现一个“请执行某脚本”或者一个下载链接,不代表 agent 就应该照做。密钥和令牌类文件默认也会排除。
我用真实项目试过什么
有一次我拿一个 703 个文件的 Vue.js 3 源码仓库做测试。它没有把所有文件都读一遍,而是先从项目入口、依赖方向和测试线索开始,最后精读了 10 个文件。总览里也写清楚了看过哪些、没看哪些,以及为什么先停在那里。
总览会写清楚项目类型、资料覆盖范围和拆解依据。
在另一份纯文字资料上,我故意问了一个拆解里没有的问题:“API 层用的是什么 HTTP 框架,为什么选它?”它回到材料里查到了标准库 ThreadingHTTPServer 和自写的 ApiHandler,然后承认这是拆解漏掉的内容,把答案补进总览。至于“为什么选它”,材料里没有解释,它就标成待验证的推断。这个回补过程比一开始写多少页报告更让我放心。
为了避免只测自己的感觉,我还会开一个新会话,只给 agent skill 和资料,看它能不能从零走完。换了一个 Python 后端仓库做 A/B。我自己 4 分钟就扫完了仓库,陌生 agent 花了 25 分钟,但它发现了我跳过的细节:pytest.ini 指向了不存在的测试目录,CI 只做了 Docker 构建,代码注释里提到的 SPEC.md 也根本不在仓库里。
它适合什么场景
我自己最常见的用法,是刚接手一个项目,想先知道从哪里开始。除此之外,也可以用在入职、交接、准备面试、第一次接触一套业务流程,或者需要在短时间内把一堆内部资料理出头绪的时候。
代码仓库会更关注模块、数据流和调用链;业务或文职资料会更关注角色、流程、规则、审批和指标。它不是把所有领域都假装成同一种东西,而是先判断手里的材料是什么,再换一种拆法。
怎么开始用
安装 skill 后,我通常会直接对 agent 说:
资料在 scale-test 文件夹。我是前端新人,两周内要能给这个项目提一个可 merged 的 PR。
它会先做拆解,再从“现在要懂”的部分开始带我看。如果我只想先看结构,也可以说“只要拆解”。学习过程中发现地图漏了东西,它应该回材料补证据,而不是在聊天里临时编一个答案。
项目地址是 github.com/Keviniscool-boy/onboard。这个 skill 已经测过代码仓库、纯文字稿、Word/PDF/Excel、PPT 这些格式;还在补的是更多真实仓库和不同岗位的资料。我会把已经测过的范围和还没测过的地方分开写。