long-horizon-tasks

name

long-horizon-tasks

description

Manage long-running, multi-hour AI agent tasks using durable project memory — a structured 4-file system (SPEC, PLAN, RULES, STATUS) that prevents drift, ensures verification, and keeps work coherent across extended sessions. Use when the user asks to build something complex from scratch, run a multi-milestone project, delegate large autonomous coding work, set up a long-running agent session, create a project with 5+ milestones, or mentions "long horizon", "长任务", "长时间运行", "多里程碑", "自主编码", "autonomous coding", "durable memory". Based on OpenAI's Codex 25-hour design-tool experiment documented at https://developers.openai.com/cookbook/examples/codex/long_horizon_tasks.

Long Horizon Tasks — 持久化项目记忆系统

将大型、复杂的多小时任务转化为可控、可验证、可追溯的里程碑序列。

核心公式

长任务成功率 = f(意图清晰度 × 分解粒度 × 验证频率 × 状态可见度)

4 个 Markdown 文件各最大化一个变量，构成闭环控制系统。

执行流程

[!CAUTION] 先规划再动手：创建 PLAN.md 之前禁止写任何项目代码。SPEC.md 和 PLAN.md 必须先存在且连贯，才能开始编码。

1. 收集需求 → 用户描述项目目标
2. 创建 SPEC.md → 冻结目标（写好不改）
3. 创建 PLAN.md → 里程碑 + 架构 + 风险登记 + 验证清单
4. 创建 RULES.md → Agent 行为约束 + 完成标准
5. 开始执行 → Agent Loop（7步循环，见下方）
6. 每个里程碑完成后：跑验证 → 修复失败 → 更新决策日志 → 更新 STATUS.md → 提交
7. 全部完成 → 最终验证扫描 → 交付

Agent Loop（7步循环）

每个里程碑严格执行以下 7 步：

Plan → Edit code → Run verification → Observe results → Repair failures → Update STATUS.md → Commit → Repeat

1. Plan — 阅读当前里程碑的范围和验收标准
2. Edit — 编写代码，保持 diff 小且可审查
3. Run — 执行验证命令（lint、typecheck、test、build）
4. Observe — 仔细阅读输出，理解每个错误和警告
5. Repair — 立即修复所有失败，不留到下一个里程碑
6. Update — 更新 STATUS.md 的状态表 + PLAN.md 的决策日志
7. Commit — 清晰的 commit message 引用里程碑名称

Session 恢复

[!IMPORTANT] 长任务的核心优势：4 个文件不会因 session 中断而丢失。

如果 session 中断（context 满、超时、手动中止），新 session 按以下顺序恢复：

1. 读取 SPEC.md — 恢复目标锚定
2. 读取 PLAN.md — 查看当前进度（哪个里程碑完成了）+ 决策日志
3. 读取 RULES.md — 恢复行为约束
4. 读取 STATUS.md — 了解最新状态和已知问题
5. 从下一个未完成的里程碑继续执行

4 文件系统

文件 1: SPEC.md — 意图锚定（写好后冻结）

防止目标漂移。使用模板 assets/SPEC.template.md。

关键节：核心目标、非目标、硬约束、目标受众、交付物、产品规格（按功能模块细分）、完成判定标准。

文件 2: PLAN.md — 执行路径（唯一的 source of truth）

将开放式工作转化为可验证的检查点序列。使用模板 assets/PLAN.template.md。

关键节：验证清单、里程碑列表（每个含范围/关键文件/验收标准/验证命令）、风险登记表、架构概述、决策日志。

里程碑数量基准：至少 14 个（原始实验用了 24 个），复杂项目可扩展。每个里程碑应在约 1 小时内完成。

文件 3: RULES.md — 行为约束

定义 Agent 的操作规范。使用模板 assets/RULES.template.md。

核心规则：不要停下来问（自主决策+记录）、小步提交、每个里程碑后跑验证并立即修复、出 bug 先写测试再修、保持 STATUS.md 实时更新。

文件 4: STATUS.md — 状态外化（为人类而写）

让任何人都能理解当前进度。使用模板 assets/STATUS.template.md。

关键节：项目简介、里程碑状态表、环境设置命令、验证命令、演示指南、数据模型概览、模块实现摘要、仓库结构、决策记录、已知问题、故障排除。

7 个设计模式

详细说明见 references/design-patterns.md：

1. 「先不要停下来问我」 — 中断成本 > 小错误成本
2. 「错误即测试」自加固 — 每个 bug 转化为永久回归保护
3. 「目标/非目标」对偶定义 — 约束比扩展更重要
4. 「确定性至上」 — 可自动验证的基础设施
5. 「里程碑粒度黄金法则」 — 按可独立验证的最小单元划分（约 1h/个）
6. 「决策日志即振荡抑制器」 — 记录决策防止反复修改
7. 「风险登记表前置」 — Fail Fast 在规划中的体现

快速开始

新项目

1. 收集需求（目标、约束、交付物、目标受众）
2. 复制 assets/SPEC.template.md → 填充为项目的 SPEC.md，确认后冻结
3. 复制 assets/PLAN.template.md → 制定至少 14 个里程碑，填写风险登记表和架构概述
4. 复制 assets/RULES.template.md → 按需调整规则
5. 创建空的 STATUS.md（用 assets/STATUS.template.md）
6. 开始 Agent Loop — 从 Milestone 01 执行

进行中的项目

1. 从当前代码库出发，创建 SPEC.md 固定剩余目标
2. 将剩余工作拆分为里程碑写入 PLAN.md
3. 创建 STATUS.md 记录现状
4. 按 Agent Loop 继续执行

项目完成后

利用 PLAN.md 的决策日志进行复盘，提炼可复用的经验。

参考资料

• 7 个设计模式详解：references/design-patterns.md
• 原始实验数据：references/experiment-data.md