Arcgentic：基于状态机的严格轮次驱动开发智能体框架

标题：Arcgentic：基于状态机的严格轮次驱动开发智能体框架

Arcgentic将规划、开发+自审计、外部审计和引用跟踪四个角色转化为机械强制的状态机驱动工作流，通过质量门控和子智能体调度实现工程纪律的自动化执行。

原作者/维护者：Arch1eSUN (Arc Studio)，来源平台：GitHub，版本：v0.2.2-alpha.3，许可证：MIT，原始链接：https://github.com/Arch1eSUN/Arcgentic

关键词：智能体框架, 状态机, 开发工作流, Claude Code, 质量门控, 审计, 子智能体, 工程纪律

问题背景

大型语言模型辅助开发工作流通常有严格的"意图"，但执行层面往往松散。开发者需要"记得运行审计检查"、"记得先扫描引用"、"记得更新技术债务"，随着项目推进，这种纪律往往会逐渐松懈。

核心洞察

Arcgentic的核心洞察是：将纪律转化为机械执行。如果门控检查失败，状态机拒绝推进。没有"记得做某事"——系统会强制执行，不通过就阻塞。

核心架构

Arcgentic采用四层架构设计：

1. 技能（Skills）：指导Claude角色思考的Markdown文档（如plan-round、execute-round等）；
2. 智能体（Agents）：平台无关的子智能体定义（如编排者、审计者、规划者等）；
3. 脚本（Scripts）：Bash实现的状态机和门控强制执行（状态管理、质量门控、工具库）；
4. 钩子（Hooks）：可选的提交级强制执行。

状态机设计

核心状态机流程： intake → planning → awaiting_dev_start → dev_in_progress → awaiting_audit → audit_in_progress → passed/needs_fix → closed （needs_fix可转回fix_in_progress）

每个状态转换需通过transition.sh验证：目标状态是否合法、门控脚本是否通过、更新状态历史。

关键门控机制

• 交接文档门控：验证规划文档包含目标陈述、范围定义、足够章节、验收标准；
• 提交链门控：验证开发产出形成连贯提交链、每个提交意图明确且符合规范；
• 裁决事实表门控：验证审计裁决包含独立可验证事实表、明确裁决结果。

四个核心角色

角色	职责	关键产出
规划者	读取范围→编写16节交接文档	详细的手off文档
开发者	执行任务→内联自审计→产生N提交链	符合规范的提交链
外部审计者	读取交接+提交链→编写裁决	带事实表的裁决文档
引用跟踪者	每日git fetch→分类→维护INDEX.md	更新的引用索引

运行模式

• 单会话模式：一个Claude会话加载编排者技能，按需委派子智能体，适用于个人/小型项目；
• 多会话模式：多个Claude会话各加载不同角色技能，以state.yaml为协议，适用于团队/长期项目。

两种模式共享state.yaml和门控脚本，可中途切换。

实际应用价值

1. 质量保证：每个产出都经过机械验证；
2. 知识保留：状态文件成为项目记忆载体；
3. 团队协作：明确角色边界和交接协议；
4. 可审计性：完整历史记录和决策追溯；
5. 持续改进：经验编码机制推动团队学习。

成本纪律原则

• ❌ 插件代码中无付费API调用；
• ❌ 无后台进程/守护进程/cron触发；
• ❌ 无自动云端LLM拉取；
• ✅ 所有LLM推理在Claude Code订阅内进行；
• ✅ 引用仅通过手动git fetch更新。

经验编码协议

Arcgentic的经验学习机制：

1. 观察：lesson-codifier子智能体扫描最近N轮；
2. 检测模式：同一问题出现3次→提议新mandate；
3. 验证：新颖的保留类型→声明经验迭代；
4. 编码：将经验编码为可复用规则。

此机制源自Moirai项目30+轮严格开发的经验总结。

路线图

• 当前版本：v0.2.2-alpha.3（核心状态机、10个技能、9个智能体、Python CLI、Claude Code/Codex插件）；
• 即将发布：v0.3.0（OpenSpec摄取层、Superpowers市场集成、GitHub引用发现、丰富的执行轮次事实生成）；
• 目标版本：v1.0.0（在2-3个非Moirai项目通过Gate3后发布稳定版）。

Arcgentic代表了LLM辅助开发工作流的一次重要进化——从"建议性"到"强制性"。通过状态机、质量门控和子智能体调度的组合，它将工程纪律从人的记忆转移到系统执行。对于追求高质量、可维护、可审计代码的团队，Arcgentic提供了一套可落地的技术方案。