本文参考《用 AI 复活停更开源项目是一个务实的选择》中的 Knife4j Next 维护经验，抽象成一套与具体模型、IDE 和开源项目无关的仓库维护方法。

Coding Agent 最容易展示的是“根据一句话生成很多代码”，但真实维护的难点通常不在代码量，而在它是否理解同一个问题、有没有越界、怎样证明改动有效，以及下次换会话后状态是否还在。

与其问 Agent 能不能接管仓库，不如先建立一条更小的闭环：一个边界明确的问题，由一个 Agent 完成最小改动，并留下可复查证据。

先选适合的仓库和任务

适合交给 Agent 推进的任务通常具有：

  • 真实用户或维护者提出的明确问题；
  • 能稳定复现的失败；
  • 清晰的模块边界；
  • 可以运行的测试、构建或静态检查；
  • 改错后能够快速回滚；
  • 完成条件可以写成列表。

例如：

  • 修复一个有复现步骤的 bug；
  • 补上缺失的边界测试；
  • 更新与代码不一致的文档；
  • 将手工发布检查脚本化；
  • 迁移一个有官方升级指南的依赖；
  • 清理一段确定没有调用方的代码。

不适合直接自治推进的任务包括：产品要不要转型、架构要不要重写、体验怎样才“更现代”、权限核心链路的大改，以及没有测试和回滚手段的数据迁移。

Agent 可以帮助调研开放问题，但在约束收敛前不应直接改仓库。

把维护者脑中的规则写进仓库

每次对话都重新解释规则，既浪费上下文，也容易漏项。至少应有下面这些持久文件：

文件内容
README.md项目用途、快速开始、主要入口
CONTRIBUTING.md分支、提交、测试和 PR 约定
AGENTS.md 或同类说明Agent 的范围、禁止项和验证命令
docs/architecture.md模块职责、依赖方向、重要不变量
docs/releasing.md版本、构件、发布和回滚步骤
scripts/test-*.sh可重复执行的验证入口

规则应尽量可操作。例如“保持高质量”无法验证；下面这些可以：

  • 不修改 legacy-v2/，除非 Issue 明确要求；
  • bug 修复必须先添加失败测试；
  • 数据库 schema 修改需要兼容上一版本应用；
  • 前端变更运行 npm test 和视觉回归；
  • 未经人工批准不得推送 tag、发布包或修改生产配置。

这些规则同样帮助新加入的人类维护者，并不是只为 AI 准备。

Issue 是任务契约，不是一句标题

一个可交付 Issue 至少包含：

背景：为什么要做
当前行为：现在发生什么
期望行为：改完应发生什么
复现步骤：命令、输入和证据
范围：允许修改的模块
非目标：这次明确不处理什么
完成条件：测试、文档、兼容性
风险：权限、数据、性能、发布

“优化登录体验”不是可执行任务。“连续三次 OAuth 回调后 session 丢失；补回归测试，不修改 token 格式”才是。

如果无法稳定复现，任务状态应是 blocked 或 investigation，而不是让 Agent 先写一个看起来合理的空值判断。

状态放在 Issue 和 PR，不放在聊天里

聊天上下文会结束，仓库状态不会。可以使用一个简单状态机：

triage
  → ready
  → in-progress
  → review
  → done

任何阶段 → blocked
  • ready：目标、范围和验收条件齐全；
  • in-progress：已有负责人和工作分支；
  • review：本地验证完成，PR 和 CI 等待审查；
  • blocked：缺少复现、权限、环境或产品决策；
  • done：合并、发布和文档状态都满足定义。

Agent 每次结束前把结论写回 Issue 或 PR：做了什么、验证结果、剩余风险和下一步。不要让“为什么这样改”只存在于某段不可检索的会话中。

默认一个 Agent 端到端

为每个阶段配置“产品 Agent、架构 Agent、开发 Agent、测试 Agent”看起来完整，但会引入上下文压缩和责任转移。多数中小任务更适合一个 Agent 从复现走到 PR：

  1. 读取 Issue 和仓库规则；
  2. 在未修改基线上复现；
  3. 找到最小原因；
  4. 添加失败测试或其他证据；
  5. 实现最小修复；
  6. 运行受影响范围和全局必要检查；
  7. 检查 diff 是否越界；
  8. 创建 PR，记录验证与风险；
  9. 等待 CI 和人工审查；
  10. 把最终结果写回 Issue。

只有当探索会撑爆主上下文、工作可以真正独立，或高风险改动需要独立第二意见时，才拆分并行 Agent。多 Agent 是容量和独立审查工具，不是必须凑齐的组织架构。

Bug 必须先复现

没有复现证据时，Agent 很容易生成“防御性修复”：增加 try-catch、空值回退或重试，表面不报错，却把真实原因藏起来。

推荐证据顺序：

未修改基线：失败
最小测试或复现脚本：稳定失败
实施修复：同一证据通过
相关回归：全部通过

如果生产条件无法本地复现，也应留下日志、trace、输入样本、版本组合和已经排除的假设。信息不足时停止，比提交一个没有约束的补丁更负责。

给不同改动定义验证矩阵

改动类型最低验证
Java 业务逻辑单元测试、模块测试、编译
API 契约schema/contract test、兼容检查
数据库迁移前后版本兼容、回滚或前滚演练
前端交互单测、构建、关键流程浏览器验证
CI/CD配置校验、最小真实运行、权限检查
文档链接、命令、示例可执行性
依赖升级变更日志、漏洞、全量测试、产物对比

“CI 绿了”只有在 CI 覆盖完成条件时才有意义。验证命令应放进仓库脚本，避免每个 Agent 自己猜一套。

为高风险动作保留人工门槛

Agent 可以自主完成低风险、可回滚、可验证的仓库内修改。下面这些动作通常需要明确审批：

  • 删除或不可逆迁移数据；
  • 修改认证、授权和密钥管理；
  • 增加付费资源或扩大基础设施；
  • 推送正式 tag、发布包和生产部署；
  • 修改公共 API 或兼容承诺；
  • 关闭安全问题或用户数据事件；
  • 大范围重构和依赖替换。

审批点要写在流程中，而不是等 Agent 做到一半再临时阻止。

发布完成条件也要可验证

合并 PR 不一定等于发布完成。按项目类型检查：

  • tag 是否存在且指向预期 commit；
  • CI workflow 是否成功；
  • 包、镜像或二进制能否从公开仓库获取；
  • checksum、签名和 SBOM 是否生成；
  • release notes 是否对应实际改动；
  • 文档站版本是否更新；
  • 升级和回滚说明是否可用；
  • Issue 与里程碑是否关闭。

把这些条件做成 verify-release 脚本后，Agent 才能客观回答“发完了吗”。

评估 Agent 的指标

不要只统计生成代码行数。更有意义的是：

  • 首次提交就通过验证的比例；
  • 因范围扩大被退回的比例；
  • bug 是否有回归测试；
  • PR 从 ready 到 merge 的时间；
  • 人工审查发现的高风险问题；
  • 合并后回滚和线上回归次数；
  • 因信息不足正确停止的次数。

“正确地 blocked”也是好结果。它说明系统没有用猜测伪装进展。

最小仓库检查清单

  • 项目目标、非目标和模块边界写在仓库；
  • Issue 包含复现、范围和完成条件；
  • 状态以 Issue/PR 为准，而不是聊天记录；
  • bug 在修复前有失败证据；
  • 每类改动有固定验证入口；
  • 默认一个 Agent 端到端，必要时才拆分；
  • 高风险动作需要人工审批；
  • 发布完成条件可以脚本检查；
  • Agent 的结论、风险和阻塞项写回长期记录。

参考资料