现在的编码 Agent 已经很会写代码了，但真正把一个仓库任务做完，往往仍然不够可靠。

它可能在错误的分支上开工，相信过期的交接文档，把显眼的代码缺口当成当前目标；也可能越做范围越大，跑完几个 Mock 测试就宣布完成，甚至在没有授权的情况下准备合并、发布或部署。

问题通常不是模型不会写，而是它缺少一套维护者视角的工作方式。

为了解决这个问题，我把自己在多个长期项目中逐步形成的 Agent 协作习惯整理成了一个开源 Skill：Maintainer Workflow。

让你的编码 Agent 像维护者一样完成整个仓库任务，而不只是写几段代码。

项目地址：https://github.com/xuwei777/maintainer-workflow

它解决的不是代码生成，而是交付失控

我遇到过的典型问题包括：

• Agent 没有先核对真实仓库、分支、HEAD 和工作区，就根据旧对话继续修改；
• 一个功能已经有明确路线，却被随手发现的代码缺口带偏；
• 用户只授权了当前任务，Agent 却顺便重构、升级依赖或开下一阶段；
• 子 Agent 声称“完成”，主 Agent 没有复核实际 diff 和测试证据；
• 自动化测试通过了，但真实页面、设备或部署环境根本没有验证；
• 功能写完后仍继续“顺手优化”，把一个可评审变更拖成大杂烩；
• 把 Ready、合并、发布和部署当成默认授权。

这些问题很难靠一句“认真一点”解决，因为模型需要明确知道：从哪里读取事实、如何判断当前工作、什么证据才足以宣称完成，以及什么时候必须停下来。

Maintainer Workflow 的五步闭环

整个工作流保持为五个动作：

定向  →  定界  →  执行  →  验证  →  交接

1. 定向：先确认真实现场

修改前先核对：

• 当前目录和仓库根目录；
• 分支、HEAD、上游和目标基线；
• 未提交改动及其归属；
• 当前 Issue、PR、工作包和权威文档；
• 可用的依赖、凭据、测试环境及限制。

如果 Git、Issue、PR、路线图和交接文档互相冲突，Agent 不应该挑一个方便的继续，而应该先暴露冲突。

2. 定界：把“做什么”和“不做什么”说清楚

非琐碎任务需要明确：

• 可观察的最终结果；
• 非目标和不能顺手改动的模块；
• 锁定接口、迁移和兼容边界；
• 安全、隐私、成本及权限要求；
• 成功、失败、恢复和停止条件；
• 最终用什么命令或真实操作验收。

这样可以避免一个小功能一路膨胀成框架、插件系统或大规模重构。

3. 执行：只做最小且完整的切片

工作流要求 Agent 沿着仓库已有的职责边界实现，而不是另造一套平行架构。

它允许把明确、独立的检查交给子 Agent，但主 Agent 必须复核实际文件、diff、测试和安全边界。子 Agent 的“已经完成”不算交付证据。

4. 验证：不同证据不能互相冒充

Maintainer Workflow 把证据分为五级：

1. 静态代码检查；
2. 单元测试或 Mock 测试；
3. 合成或一次性集成环境；
4. 真实隔离环境或设备验收；
5. 生产或线上验收。

低等级证据不能证明高等级结果。
比如路由存在、服务能启动、CI 变绿、Fake Executor 通过，都不能单独证明真实用户流程、部署恢复或权限边界已经正确。只要环境可用，用户可见的功能就应该真正打开页面或设备走一遍，而不是等用户发现问题。

5. 交接：准确报告，而不是宣布胜利

每次交接至少要说明：

• 实际改了什么；
• 当前分支和精确 HEAD；
• 真正运行过哪些命令，结果如何；
• 哪些检查没有运行以及原因；
• 剩余风险、回滚状态和唯一最安全的下一步。

没有验证的内容明确写成 NOT_RUN，不会用“理论上可行”包装成已完成。

工作包是可选的，不是流程负担

这个 Skill 支持父 Issue 下的多个 WP（Work Package，工作包），但不会强迫每个任务都建 Issue 或套固定模板。

例如一个“安全导入 CSV”的完整功能，可以按真实产品结果拆分：

父工作项目标：用户可以安全导入 CSV

WP1  预览解析结果并解释无效记录
WP2  确认后幂等写入，重复提交不产生重复数据
WP3  下载失败记录，并只重试这些记录

每个 WP 都是可独立验收的纵向切片，并拥有自己的成功、失败和恢复行为。

它不会机械套用“基础设施 → 核心功能 → 测试 → 文档”这种通用流水线，也不会单独制造一个“测试 WP”。简单修改完全可以不使用 WP。

如果用户已经授权了精确的 WP 序列，而且下一阶段进入条件仍然成立，Agent 可以继续推进，不需要每一步反复询问。但如果前一个 WP 的证据推翻了后续前提，它必须停止或重新规划。

三种使用模式

Maintainer Workflow 会根据仓库当前状态选择工作方式：

模式	适用场景	默认行为
Bootstrap	新仓库缺少有效治理	分析项目后提出最小规则，得到授权再写入
Adopt	项目已经开发一半，但状态混乱	对齐 Git、Issue、PR 和文档，恢复主线而不是猜测
Deliver	当前任务和权限已经明确	推进到实现、自动检查、真实验收、评审和准确交接

仓库没有 AGENTS.md 或路线图时，它不会擅自生成一大套治理文件，而是根据项目规模提出最小配置。项目自己的规则始终优先于这个通用 Skill。

有意保持精简，只在重要的地方严格

这是整个项目最重要的设计原则之一。

它不是项目管理框架，也不是常驻服务或安全沙盒。整个可安装包只有：

skills/maintainer-workflow/
├── SKILL.md
├── agents/openai.yaml
├── assets/AGENTS.template.md
├── assets/work-package.template.md
├── references/project-profiles.md
└── scripts/preflight.ps1

没有数据库、后台进程、Bot、钩子系统或强制运行时。简单任务仍然保持简单；只有合并、发布、部署、生产操作等真正重要的边界才要求重新确认。

一条命令安装

需要 Node.js 18 或更高版本：

npx skills add xuwei777/maintainer-workflow --skill maintainer-workflow -g

安装后新开一个 Agent 会话，告诉它：

使用 $maintainer-workflow 检查并继续当前仓库任务。

如果是明确的更新或重新安装，可以使用非交互命令：

npx -y skills@latest add xuwei777/maintainer-workflow --skill maintainer-workflow -g --yes

它遵循可移植的 Agent Skills 格式，可用于 Codex、Claude Code、Cursor、Qoder 以及其他支持 Skill 的编码 Agent。目标 Agent 已知时可以增加 --agent <agent-id>。

它不会替你做什么

安装 Skill 不会自动创建 Issue、分支、PR、提交或路线图，也不会自行合并、发布、部署或执行破坏性清理。

CI 和测试继续负责提供证据，项目文档继续负责项目事实；这个 Skill 负责的是 Agent 如何读取事实、选择工作、控制范围、匹配证据，并准确报告尚未验证的内容。

它也无法把能力较弱的模型变成更强的模型，但可以显著减少一类常见错误：在错误的目标上非常努力，然后用不充分的证据宣布完成。

最后

我希望 Maintainer Workflow 解决的是一个很朴素的问题：

当一次对话结束后，仓库是否真的处于一个更清晰、更可靠、更容易继续维护的状态？

如果你也在使用编码 Agent 维护长期项目，欢迎试用、提出 Issue 或根据自己的仓库规则调整它。

• GitHub：https://github.com/xuwei777/maintainer-workflow
• Release：https://github.com/xuwei777/maintainer-workflow/releases/tag/v1.0.0
• License：MIT