| 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
- Plan — 阅读当前里程碑的范围和验收标准
- Edit — 编写代码，保持 diff 小且可审查
- Run — 执行验证命令（lint、typecheck、test、build）
- Observe — 仔细阅读输出，理解每个错误和警告
- Repair — 立即修复所有失败，不留到下一个里程碑
- Update — 更新 STATUS.md 的状态表 + PLAN.md 的决策日志
- Commit — 清晰的 commit message 引用里程碑名称
Session 恢复
[!IMPORTANT]
长任务的核心优势：4 个文件不会因 session 中断而丢失。
如果 session 中断（context 满、超时、手动中止），新 session 按以下顺序恢复：
- 读取 SPEC.md — 恢复目标锚定
- 读取 PLAN.md — 查看当前进度（哪个里程碑完成了）+ 决策日志
- 读取 RULES.md — 恢复行为约束
- 读取 STATUS.md — 了解最新状态和已知问题
- 从下一个未完成的里程碑继续执行
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：
- 「先不要停下来问我」 — 中断成本 > 小错误成本
- 「错误即测试」自加固 — 每个 bug 转化为永久回归保护
- 「目标/非目标」对偶定义 — 约束比扩展更重要
- 「确定性至上」 — 可自动验证的基础设施
- 「里程碑粒度黄金法则」 — 按可独立验证的最小单元划分（约 1h/个）
- 「决策日志即振荡抑制器」 — 记录决策防止反复修改
- 「风险登记表前置」 — Fail Fast 在规划中的体现
快速开始
新项目
- 收集需求（目标、约束、交付物、目标受众）
- 复制
assets/SPEC.template.md → 填充为项目的 SPEC.md，确认后冻结
- 复制
assets/PLAN.template.md → 制定至少 14 个里程碑，填写风险登记表和架构概述
- 复制
assets/RULES.template.md → 按需调整规则
- 创建空的
STATUS.md（用 assets/STATUS.template.md）
- 开始 Agent Loop — 从 Milestone 01 执行
进行中的项目
- 从当前代码库出发，创建 SPEC.md 固定剩余目标
- 将剩余工作拆分为里程碑写入 PLAN.md
- 创建 STATUS.md 记录现状
- 按 Agent Loop 继续执行
项目完成后
利用 PLAN.md 的决策日志进行复盘，提炼可复用的经验。
参考资料
- 7 个设计模式详解：
references/design-patterns.md
- 原始实验数据：
references/experiment-data.md
