用 Skills 建立智能体可接手的软件项目知识库

在一个商业软件项目的实施过程中，我们开始尝试让智能体（Agent）真正进入研发流程。

一开始，我们最关心的是：它能不能读懂代码、完成修改、跑通测试。这些工作通常很容易看到结果：文件变了，功能跑起来了，任务似乎也完成了。

真正让我们停下来重新思考的，是另一个反复出现的场景。

项目推进几周后，智能体接手一项新任务。它读了 README，翻了 issue，又看过设计文档和最近的提交，最后很认真地问了一个团队已经讨论过几次的问题：这个功能到底算不算第一版范围？

答案当然存在。它可能在一次会议里，在某条 issue 的评论里，在一个已经关闭的 PR 里，也可能只存在于某位成员的记忆中。问题在于，这个答案没有进入一个后来接手的人和智能体都能稳定找到的位置。

这不是智能体不够努力，也不只是文档不够多。

常规的软件研发流程本身并没有失效。需求需要澄清，决策需要记录，任务需要拆解，验收需要证据，复盘也需要回到项目里。这些做法的价值早已得到广泛认可。真正麻烦的是执行成本：项目一忙，文档维护最容易被延后；任务做完了，验证证据没有写回去；讨论形成了结论，却没有进入下一次接手时能读到的位置。

为了解决这些反复出现的问题，我们开始把零散的知识维护动作整理成一组 Skills，并把这套工作方法称为 knowledge-workflow。它不是先被完整设计出来，再放进项目里执行。我们先针对信息误写、任务脱节、交付缺少证据等具体问题提出做法，再随着项目推进反复应用、调整和补充。

它不是一套新的软件工程方法，也不是要求团队多写几篇文档。它做的事情其实更朴素：让智能体在合适的阶段参与知识摄入、确认写入、交付规划、实现复核和状态报告，以更低的成本落实那些本来就应该执行的工程动作。

什么时候你会需要这套方法

不是每个项目都需要完整的知识工作流。如果项目只有一个 README、少量边界清楚的 issue，而且任务当天就能完成，引入更多结构反而可能增加负担。

这里的关键并不是人数。一人公司（OPC）或独立开发者，也可能同时维护产品、客户反馈、销售线索、技术债和发布计划。表面上只有一个人在工作，实际上已经有多条工作流同时推进。只要信息和判断开始分散，知识库就会从“备忘录”变成“协作系统”，哪怕协作者暂时只有你和智能体。

当下面这些情况开始反复出现时，问题通常已经不只是缺少文档：

• 需求、设计、架构、任务和测试分散在不同地方。
• 团队经常需要重新解释“为什么当时这么决定”。
• 智能体每次接手都读了很多文件，却仍然误解当前状态。
• 任务板上有很多卡片，但看不出来源、依赖和验收条件。
• 实现完成后，新发现的约束没有写回项目知识。

到了这个阶段，更长的提示词（prompt）和更大的上下文窗口（context window）都不够。项目知识需要有稳定的入口、明确的状态和可执行的维护规则；智能体也需要知道自己正处在哪个阶段、具有什么权限、需要留下什么证据，以及什么时候必须停下来让人确认。

这些 Skills 不是一组松散的提示词

如果把需求整理、文档写入、任务规划、代码实现和项目检查全部塞进一个大提示词，智能体当然也能做一些事情。可一旦进入真实项目，权限和责任很快就会混在一起：它是在提出建议，还是执行已经批准的写入？是在汇报状态，还是修改任务？发现一条新信息后，应该先请求确认，还是直接把它写成项目事实？

所以，knowledge-workflow 并不是按“能生成什么内容”组织 skills，而是按工作阶段、写入权限和交付责任来划分职责。

在这个商业软件项目的实施过程中，这套方法经历了提出、应用、调整和总结，最终被整理为一组 Knowledge Workflow Skills。下面列出的是其中的主干：

表中的名称来自这项商业实践对协作职责的划分，用来说明不同环节如何配合，并不是一份要求团队照搬的安装清单。真正值得参考的，是每项职责为什么存在、能做什么，以及必须在哪里停下来。

这张表真正重要的，不是 skill 的数量，而是边界。配置维护、共享知识写入、只读诊断、看板变更和个人执行被明确分开。智能体进入下一步之前，必须先知道自己现在站在哪里。

先判断当前处在哪一步

入口 skill knowledge-assistant 不急着修改知识库。它先判断用户带来的内容更接近一条待确认信息、一次共享知识更新、一个交付任务，还是一次状态查询，再把工作路由给更窄的 skill。

这个入口看起来只是在分流，实际解决的却是一个很常见的问题：智能体一收到信息就开始执行。先判断阶段，意味着它要先弄清楚，用户现在是在讨论、确认、交付，还是复盘。

待判断的信息和已批准的写入分开

knowledge-intake 负责知识摄入（intake）。它搜索已有内容，判断新信息可能属于需求、决策、反馈、风险还是任务，并指出冲突和缺口，但不擅自把讨论写成共享事实。

只有目标和内容得到确认后，knowledge-capture 才负责知识捕获（capture）。它按照现有结构定义（schema）、模板（template）和规则（rules）更新知识库，并保留来源、状态和必要链接。

两者分开后，智能体就不该再因为一句话“听起来很合理”，便把临时想法直接升级成团队结论。

检查知识和修改知识分开

知识检查类 skills 默认只读。它们可以发现字段缺失、引用断开、任务没有来源，以及完成项缺少验证证据，也可以提出修复建议，但不会一边检查，一边悄悄改写项目事实。

knowledge-status-report 也是如此。它负责把当前范围、未决问题、任务状态和知识健康重新摊开给人看。报告首先要可信，然后才谈修复。

规划建议和任务板变更分开

delivery-planning 先做任务规划预演（dry run）。它从需求、决策和验收意图中推导候选任务、依赖关系和就绪状态，但不直接改变看板（Kanban）。

只有人确认规划结果后，任务板维护 skill 才会更新状态。这样一来，智能体可以承担整理和推导的成本，又不会在用户还没看清计划之前替团队承诺范围。

实现和复核各自留下证据

delivery-implementation 从已经接受的任务出发，先读取来源知识和验收条件，再修改代码或文档。执行完成后，它需要报告改动、检查命令、测试结果、剩余风险，以及过程中发现的新约束。

delivery-review 则站在原始意图一侧重新检查结果。它关心的不只是代码能不能运行，也包括实现是否满足需求、验证证据是否充分、任务是否真的具备完成条件。

把实现和复核分开，是为了让“智能体说完成了”不再等同于“任务已经完成”。

这些 skills 放在一起，形成的不是一条僵硬的流水线，而是一组可以按需组合的协作边界。不同项目可以裁剪其中的环节，但几个基本区别最好保留下来：讨论不等于事实，建议不等于批准，执行不等于完成；项目状态也不能只靠聊天记录来判断。

为什么不直接使用项目管理工具

谈到这里，一个很自然的问题是：既然 GitHub Issues/Projects、Jira、飞书项目已经能管理需求和任务，为什么还要在仓库里维护一层项目知识？

这些工具当然有价值。它们很适合做任务协作、状态流转、负责人分配、讨论通知和跨团队看板。很多团队也确实应该继续使用它们。

不过，它们主要解决的是“任务如何被协作推进”，不一定同时解决“项目知识如何被长期维护和接手”。

一个 issue 可以记录一次讨论，一个 Jira ticket 可以承载一个需求，一个飞书项目任务可以推动一次交付。可几个月后，接手的人和智能体仍然需要判断：哪条评论才是最终决策？这次状态变化背后的范围取舍在哪里？验收证据是否和代码、文档、测试一起留了下来？某条规则现在仍然有效，还是只属于当时的迭代？

知识工作流并不替代这些产品。任务可以继续在熟悉的工具里推进，仓库内的知识条目则用来保存外部链接、关键判断、可复核证据和维护规则。智能体接手时，可以先从项目知识层理解背景，再沿着引用进入 GitHub、Jira、飞书或设计工具查看过程材料。

外部工具负责推进协作，知识库负责沉淀可接手的上下文。两者结合，才更接近真实团队会长期使用的工作方式。

用一个软件项目看它怎么工作

为了不披露真实商业项目的具体信息，也避免把这套方法讲成一套抽象流程，下面用一个模拟项目还原它在项目推进中的工作方式。

假设你和一个小团队正在开发 issue triage dashboard。它不是一套完整的项目管理平台，而是一个面向开源维护者的轻量工具：读取 GitHub issues，按类型、优先级、影响范围和可复现程度做初步整理，再给出下一步处理建议。

项目开始时，手里的材料通常不会像需求文档那样完整，而是一些半成型信息：

• 一段产品想法：维护者每天要处理大量 issue，希望先自动分组和初筛。
• 几条用户反馈：有人关心 duplicate，有人只想找到 release blocker。
• 一些技术判断：是否调用 GitHub API，是否需要本地缓存，是否接入大语言模型（LLM）做摘要。
• 几个初始任务：搭建项目、定义分类、实现 dashboard、补测试、准备 release note。
• 一些尚未确认的问题：先服务个人维护者还是小团队？先支持一个 repository 还是多个？

如果此时直接让智能体“开始做”，它大概率能写出一些代码。可那些真正决定项目能否继续推进的范围、假设和依赖，仍然没有稳定下来。

想法刚出现时，先不要急着写入

你可能对智能体说：

我们先做一个工具，帮维护者快速判断哪些 issue 是 bug、哪些是 duplicate、哪些需要更多信息。以后也许可以接 GitHub Actions，但第一版先在本地跑通。

如果没有阶段边界，智能体很容易把这段话当成直接任务：搭项目、写 dashboard、接 API。

进入知识摄入（intake）阶段后，它会先拆开这段话：这里有产品目标，有用户场景，有技术假设，也有潜在任务。它会搜索已有知识，确认是否已经存在类似需求或决策，并把需要人回答的问题摆出来：第一版是否只支持单 repository？是否保存 triage 结果？GitHub Actions 是明确延期，还是尚未决定？

这一步的价值不是多写几个文件，而是帮团队区分：什么已经可以成为项目事实，什么仍然只是方向，什么还需要确认。

范围确认后，再把知识写成稳定形状

当用户确认“第一版只做单 repository、本地运行、支持 issue 分类和优先级建议”之后，才适合进入知识捕获（capture）阶段。

智能体可以把刚才的讨论写入几类稳定知识：

• 在产品知识中记录第一版目标：帮助开源维护者快速处理 issue。
• 在用户故事（user story）中记录典型场景：维护者打开 dashboard，看到需要优先处理的 issue 分组。
• 在决策（decision）中记录范围取舍：第一版不接 GitHub Actions，不支持多个 repository。
• 在任务（tasks）中记录候选工作：定义分类规则、读取 GitHub issues、实现 dashboard、补充测试。

这些分类并不是固定套餐。团队可以按项目需要裁剪 schema、template 和 rules：哪些字段必须留下，哪些状态可以省略，哪些内容只能留在个人草稿，哪些判断一旦确认就必须进入共享知识库。

同样一句“第一版先在本地跑通”，留在聊天里很快会变成模糊记忆；写成 decision 后，后来的人就能知道：这不是忘了做 GitHub Actions，而是第一版明确不做。

文档堆保存内容，知识库还要保存判断。

准备交付时，任务不能只剩标题

很多任务板看起来井井有条，点进去却只有一行标题：“实现 dashboard 页面。”“接 GitHub API。”“补测试。”熟悉项目的人知道它们之间的关系，第一次接手的智能体可不知道。

在这个案例里，交付规划（planning）不会根据一句“做 dashboard”直接改看板，而是从产品范围、用户故事、决策和验收意图中整理出一份预演：

用户确认后，看板才会更新。下一次选择任务时，智能体也可以根据依赖和就绪状态，推荐先定义 issue 分类 schema，而不是直接跳到 dashboard UI。

这时，任务板上的状态不再只代表“有人移动了一张卡片”，而是能够说明一项任务为什么存在、依赖什么，以及怎样才算完成。

执行任务时，留下可复核证据

当“定义 issue 分类 schema”进入 Ready 后，智能体先读取任务来源、验收条件（acceptance criteria）、相关 decision 和项目规则，再开始修改。

实现完成后，它带回来的不应该只有一句“已经完成”，还应该包括：

• 修改了哪些文件。
• 运行了哪些检查。
• 哪些测试通过，哪些边界还没有覆盖。
• 执行中发现了哪些新约束。
• 是否需要更新产品知识、决策、任务或测试用例。

比如，原计划只有 bug、duplicate、needs-info 几类，但测试数据里出现了大量功能建议（feature request）。这个发现不应该只停留在实现总结里。智能体需要提示用户：是把 feature request 纳入分类 schema，还是把它记录为第一版暂不支持的范围边界？

随后，复核（review）会检查本地差异、测试结果和完成就绪状态。此时你看到的，不再是智能体对自己的评价，而是一组可以独立复核的证据。

项目推进后，重新看见全局状态

项目推进几轮后，团队往往会问：第一版到底还缺什么？哪些任务已经准备好？哪些决策仍然没有定？

knowledge-status-report 会从仓库里的项目知识和交付状态出发，汇总当前范围、任务依赖、未决决策，以及缺失的来源和验证证据。它不负责顺手修改这些内容，只负责让团队先看清项目现在处于什么位置。

这类报告真正有用的地方，是它不再重新总结最近一次聊天，而是在读取一个持续维护过的项目状态。

这套实践真正改变了什么

随着这套方法在项目中反复应用和复盘，我们越来越确定：knowledge-workflow 的价值，不是多了一组文档目录，也不是多了一批 skill 名称。

它首先把标准化要求落实到了可验证的文档里。schema 规定同类知识需要留下哪些内容，template 让新内容从正确的形状开始，rules 则明确什么可以写、谁可以写，以及什么时候需要确认。这样，项目规则便不再只存在于成员的记忆和某次对话里。

它也降低了维护这些文档的成本。过去，人需要主动记得更新需求、补充证据、同步看板和回写新约束；现在，智能体可以在对应阶段提醒遗漏、整理材料、检查状态和执行更新，团队则把精力放在确认事实、判断取舍和承担最终责任上。

改变的不是“要不要做软件工程”，而是那些已经被证明有效的工程动作，能不能在真实项目压力下持续发生。

后来，这些做法也在其他商业项目中得到进一步验证，并作为项目知识维护经验逐步推广到公司内部的其他团队。具体落地时，各团队会按自己的流程做相应裁剪；实践中发现的问题和改进建议，也会通过反馈（feedback）机制回到维护团队，继续完善这些 skills 和配套流程。

下一次智能体接手项目时，真正决定它能否继续推进的，不只是代码和文件是否可读，更在于项目是否留下了可判断的状态、可追溯的决策和可复核的证据。knowledge-workflow 让我们看到：智能体不仅可以进入代码，也可以真正进入项目。