Headless Planner：为无监督AI代理设计的系统化工作流框架

Headless Planner是专为Claude Code无头模式设计的规划与执行工作流框架，旨在解决无监督AI代理运行的可靠性问题。框架通过强制实施"先规划、后执行"的严格循环，包含四阶段工作流、状态持久化和失败处理机制，确保决策可记录、依赖明确、失败可追溯，为生产环境部署AI代理提供重要参考。

随着AI编程助手在CI/CD流水线、定时任务等自动化场景的广泛应用，无头环境下的可靠性问题凸显：传统交互式助手依赖人类反馈纠正偏差，但无头代理自主运行时易出现跳过关键步骤、吞掉错误、无记录或阻塞等失败模式，事后调试困难且代价高昂。

任务理解

需识别目标、范围、约束及模糊点，对模糊点采用"记录并继续"策略（合理默认选择+假设记录）避免阻塞。

规划写入磁盘

执行前必须将计划写入.headless-plan.md，包含元数据、假设列表、带依赖关系的步骤清单，依赖显式声明防止顺序混乱。

逐步执行

按依赖顺序执行，检查阻塞项状态、标记步骤状态、验证结果；支持中断恢复（从进行中/待处理步骤继续）。

失败处理

步骤失败时标记状态、写入.headless-error.md（含失败详情、上下文、恢复措施）并非零退出。

1. 强调可观测性：计划和错误文件提供代理内部状态可见性；
2. 融合软件工程最佳实践：依赖管理、状态持久化、错误处理提升AI代理可预测性与可维护性；
3. 平衡自主性与可控性：代理自主决策但记录在案，受明确约束（如一次重试限制）。

通过Claude Code技能系统实现（技能文件SKILL.md定义行为规范），支持版本控制与复用；与任务系统集成，步骤注册为任务并通过addBlockedBy属性建立依赖，与磁盘计划文件形成冗余增强可靠性。

适用场景：CI/CD自动化代码审查、定时维护任务、批量处理作业等无实时监督的长时间运行场景。 局限性：假设任务可分解为明确步骤序列，不适用于探索性/创造性任务；强制规划阶段增加延迟，不适合极快响应场景。

Headless Planner推动AI代理从"黑盒智能"转向"可审计、可恢复、可维护"的自动化组件，为生产环境部署提供参考。随着AI代理在关键业务系统的普及，注重可靠性与可观测性的设计模式将愈发重要，结构化约束是确保其可靠运行的核心。