Agent Loop:一个让 AI 编程 Agent 从"会写代码"进化到"闭环交付"的开源 Skill(适配国内外主流 Code Agent)

项目地址:github.com/Shadow-linu... (当前稳定版 stable-v1.5.8,MIT 协议)

一、为什么做这个项目:AI 编程不缺"写代码",缺"闭环"

现在的 AI 编程 Agent(Claude Code、Codex、Kimi Code CLI、OpenCode......)写代码的能力已经很强了。但在真实项目里,痛点往往不是"写不出来",而是:

说一句改一句,没有流程:需求没澄清就开写,写完没人验证;
没有记忆:换个会话,Agent 就不认识这个项目了------过去的决策、约束、踩过的坑全部重来;
没有边界:该问人的时候不问,不该碰的生产、发布动作乱碰;
"代码写完"被当成"事情做完":没有测试、没有评审、没有收尾,更谈不上可恢复。

Agent Loop 就是为解决这个问题而生的。它不是一个新的 Agent,也不是框架或平台,而是一个控制器型(Controller)Skill:面向"一个人类 + 一个 CLI Agent"的开发模式,让 Agent 拥有项目诊断、流程编排、实现、验证、记忆维护的主导权,而人类始终掌握目标、产品语义和关键决策。

一句话概括它的设计哲学:

Human-directed · Agent-owned · Evidence-verified(人类定向、Agent 主导、证据验证)

二、Agent Loop 是什么

形态 :一个标准的 Agent Skill(SKILL.md + references/ 规则集 + templates/ 模板),安装进你现有的 Code Agent 即可使用,不改换你的工作习惯;
适配 :兼容国内外主流 CLI Code Agent,官方一键安装命令覆盖 Claude Code、Codex、Kimi Code CLI、OpenCode 等;不支持 npx 的环境也提供 Git 克隆安装路径;
定位:它是"控制器"------决定当前处于哪个阶段、加载哪份规则、产出或更新哪些工件,并在人类闸门(Human Gate)前停下来。

主循环只有一条:

markdown 复制代码

人类目标 → Agent Loop 控制器 → 产品定义 → 设计就绪判断(需要时做 ADR)
        → 合适粒度的交付 → 新鲜验证与评审 → 项目记忆与验证闭环

三、核心能力

1. 理解并接管一个项目

Message Intent Guard(消息意图守卫):先判断你这句话是闲聊、需求、运维支持、Feature、Bug 还是归档维护,再决定是否产出工件------不会"随便聊两句就给你建一堆工作区";
Project Entry:初始化、恢复、重新接管本地或远程项目,给出被接受的项目记忆根和安全的下一步;
Project Entry Scan + 证据图谱 Onboarding :扫描仓库结构、命令、边界、在途工作与不确定点,产出有证据支撑、对新人友好的项目认知库(.agent-loop/onboarding-db/);
Root Guidance :检测项目根 AGENTS.md / CLAUDE.md 是否缺失或过期,并提议受管理的修复。

2. 在写代码之前,先把需求塑形清楚

Agent Loop 用**自适应产品定义(Adaptive Product Definition)**把一个模糊的人类诉求变成被接受的产品定义:

根据范围与不确定性选择简报级或标准级深度,而不是动辄一份大 PRD;
Requirement Product Model:推导出角色、权限、命令、事件、流程、状态、不变式、异常与恢复,形成带稳定 ID、可评审的产品视图;
Product Consensus :先查证据、给出推荐答案,一次只问一个关键问题;
Requirement Lifecycle:需求从提出、接受、延期、实现到被取代的全生命周期管理,不污染项目记忆;
Design Readiness / ADR :判断是否需要共享技术设计,需要时落成人类审定的 ADR(.agent-loop/decisions/)。

3. 按"最小安全工作流"分级交付

Agent Loop 不会对所有任务一刀切走重流程,而是按风险选择最小安全路由:

路由	适用场景	控制与证据
Chat	问答、讨论、状态	默认不创建任何需求或 Feature
Operational Support	基于代码的测试、诊断、发布演练	只读分析优先,变更必须过闸门
Direct Edit Fast Path(1.5.8 新增)	真正琐碎、确定、有界、可逆的小改动	零工件,一次精确的最终检查
Lightweight Change Lane	需要持久化、回滚、更广检查的普通变更	月度变更卡 + 自适应计划 + 修复优先验证
Feature	涉及行为 / API / 状态 / 数据 / 权限 / 架构	Spec → Tasks → Tests → TDD → Verify → Review
Bug Follow-up	明确的 Bug:身份、证据、去重、修复、关闭	`bugs/` 目录 + Feature 托管的 TDD 修复

配套机制还包括:全工作区 Git 提交快速通道(一次展示全部变更、人类确认后才 git add -A),以及 1.5.8 引入的全量测试一次精确确认------新提议的完整测试矩阵或发布套件必须明确命令、分支、环境、成本和结论主张,一次授权默认只执行一次。

4. 验证、评审与闭环:"代码写完" ≠ "完成"

完成需要成比例的、新鲜的证据:

sql 复制代码

Execute → Verify → Review → Drift Check → Memory Update → Completion Check
        → 人类审定的 Submit / Pause / Close

初始 Feature 实现与显式 Bug 修复强制 TDD(真实的 RED/GREEN 证据);
Feature 建设只有两次有意义的评审(定义评审 + 实现就绪评审),不拿内部质量阶段打断你;
Agent 会检查实现、测试、需求与决策覆盖、无关改动、过期文档、回滚与残余风险。

5. 可长期维护的项目记忆

.agent-loop/ 目录持久化项目稳定事实、在途工作、恢复点、命令、约束与已接受决策;
换会话、换机器都不怕:一句"继续上一个 Agent Loop 任务"即可从最安全点恢复;
Drift & Recovery:检测记忆与代码的漂移,从当前代码、环境与人类权威回填;
完整的 Bug 管理、Feature 月度归档 / 恢复、合并后记忆调和机制。

四、人机权责:Agent 拥有什么,人类保留什么

Agent 拥有:

先查证据再提问;
判断当前阶段与最小安全路径;
按风险所需深度规划;
实现、测试、验证、评审、漂移修复与文档回填;
保持工作可恢复,并推荐下一步;
在授权范围内持续工作,直到验证完成或遇到真正的 Human Gate。

人类保留:

目标、范围、源需求与被接受的产品语义;
有重大影响的产品或技术决策;
生产、付费、密钥、破坏性、外部服务动作;
分支变更、commit、push、PR、合并、tag、发布;
ADR、Feature 关闭、Bug 关闭等生命周期闸门的验收。

关键原则:批准一个闸门,绝不等于批准另一个闸门。 Tag、Push、Release、Publish 都是独立的人类决策。

五、五分钟上手

一键安装(需要 Node.js 18+):

bash 复制代码

npx -y skills add Shadow-linux/agent-loop \
  --global \
  --skill agent-loop \
  --agent codex \
  --agent kimi-code-cli \
  --agent claude-code \
  --agent opencode \
  --yes

也可以交互式选择要装到哪些 Agent:npx skills add Shadow-linux/agent-loop -g

接管一个项目,对你的 Agent 说:

vbnet 复制代码

Use Agent Loop to take over this project.
先看看现状,然后把我们商定的工作推进到需要我做决策为止。

从需求开始,而不是从流程名词开始:

复制代码

我有一个产品想法,还比较粗糙,动手之前先帮我澄清。

安全恢复:

vbnet 复制代码

继续上一个 Agent Loop 任务。先检查当前状态,从最安全的点恢复。

六、写在最后

AI 编程的下一步,不是让模型写得更快,而是让交付过程可信:需求有据、实现有证、收尾有记忆、关键决策始终在人手里。Agent Loop 把这套工程实践压缩成一个 Skill,装进你已经在用的 Code Agent 里。

如果它对你有帮助,欢迎 Star、提 Issue,或在评论区聊聊你在"单人 + Agent"开发中遇到的流程问题:

GitHub:github.com/Shadow-linu...
稳定分支:stable-v1.5.8