ruan-cat do-long-task
这是一个面向长任务执行的入口 skill。它不负责替你决定“大任务做什么”，而是负责把已经确定的长任务稳定推进到底。
提示词生成模式
当用户要求“生成 Claude Code /goal 或 Codex /goal 提示词”“生成长任务执行提示词”“用 do-long-task 写 1500 字以内提示词”时，进入提示词生成模式。
提示词生成模式只做一件事：输出一段可复制给 Claude Code /goal 或 Codex /goal 使用的长任务执行提示词。不要开始执行该长任务。
生成提示词时：
- 不修改 OpenSpec 工件。
- 不创建或更新
agent-progress.md/agent-findings.md。 - 不运行测试、lint、typecheck 或 validate 命令。
- 不把聊天 checklist 当任务源。
- 默认把最终提示词控制在 1500 字以内；如果用户指定更短或更长的字数限制，以用户指定为准。
- 如果用户没有提供
openspec/changes/<change-name>或tasks.md路径，不要臆造路径；输出带<change-name>的占位模板，并列出需要用户补齐的占位符。
提示词必须保留 do-long-task 的核心纪律：读取 OpenSpec 工件、只使用 tasks.md 作为唯一任务源、小步推进、动态补全遗漏任务、严格定位 agent-progress.md / agent-findings.md、维护进度与失败记录、验证后再勾选完成、遇到真正阻塞才暂停。
详细模板、占位符策略和裁剪规则见 references/codex-goal-prompt.md。按 AGENT_LONGTASK.md 的读取路由只加载相关 reference，不要无脑读取全部长文。
协作声明
- 需要协作的全局技能是
openspec。执行 OpenSpec change 时，先使用openspec理解proposal.md、design.md、specs/和tasks.md的工件链。 - 业务项目内如果存在项目级 OpenSpec 技能，必须先发现并读取，再执行 change。按项目根目录优先检查
.claude/skills、.codex/skills、.agents/skills、.agent/skills中与openspec相关的技能入口；只读取当前任务需要的技能与 reference，不把外部分发 skill 的默认规则置于项目规则之上。 - 当检测到当前任务位于
openspec/changes/<change>下时，必须以当前 OpenSpec 工件链为准，tasks.md是唯一可执行任务源。 - 长任务执行中发现遗漏任务时，先更新当前 change 的
tasks.md，再继续执行。 - 不得只把遗漏任务写在聊天 checklist、
agent-progress.md或子代理报告里。
固定产物位置门禁
执行模式下，必须先确定唯一的 OpenSpec change 根目录，再创建或更新 agent-progress.md / agent-findings.md。
规范位置只有两类：
- 正在执行的 change：
openspec/changes/<change-name>/agent-progress.md与openspec/changes/<change-name>/agent-findings.md - 已归档的 change：
openspec/changes/archive/**/<change-name>/agent-progress.md与openspec/changes/archive/**/<change-name>/agent-findings.md
确定 change 根目录时，按优先级判定：
- 用户明确给出的
openspec/changes/<change-name>、openspec/changes/<change-name>/tasks.md或 archive 下的具体 change 目录。 - 当前工作目录位于某个
openspec/changes/<change-name>或openspec/changes/archive/**/<change-name>内。 - 扫描到唯一一个与用户目标、
tasks.md标题或当前 checkpoint 明确匹配的 change 目录。
如果无法唯一确定 change 根目录，不要在当前目录、仓库根目录、openspec/changes/ 顶层、openspec/changes/archive/ 顶层、普通报告目录或 skill 目录中创建这两个文件；先提示用户补齐 change 路径。
错位文件检查与迁移
执行模式每次启动、恢复、上下文压缩后、创建固定产物前，以及完成前，都要检查工作区内是否已有错位文件。可使用 rg --files -g agent-progress.md -g agent-findings.md 或等价文件搜索。
对每个命中的 agent-progress.md / agent-findings.md：
- 判断路径是否位于规范 active change 根目录或 archive change 根目录。
- 若路径不规范，立即警告用户：列出相对路径、为什么不规范、准备迁移到哪个 change 目录、归属证据是什么。
- 若当前任务已唯一确定 active change，把错位内容迁移或合并到该 change 根目录对应文件；目标文件已存在时，追加一个
## Migrated from <relative-path> on <YYYY-MM-DD>小节，保留原文和迁移原因。 - 若内容属于已归档任务，且能唯一识别 archive 下的具体 change 目录，把内容迁移或合并到
openspec/changes/archive/**/<change-name>/的对应文件。 - 若存在多个候选 change、无法从内容识别归属，或迁移可能覆盖已有记录，停止并询问用户；不要猜测、不要把多个长任务继续累积到同一个文件。
- 迁移后回读目标文件确认内容存在，再删除错位源文件；不能确认时保留源文件并记录风险到目标
agent-findings.md或当前汇报。
不要把迁移理解为“整理到 reports”。这两个文件是 OpenSpec change 的附属状态文件，只能跟随具体 active change 或 archive change。
什么时候用
- 需要跨多个步骤持续推进的开发、修复、重构、迁移或验收任务。
- 任务会经历上下文压缩、会话中断、测试失败、恢复续跑。
- 任务必须把计划、进度、发现、失败和验证写入文件，而不能依赖聊天记忆。
- 任务已经有明确的唯一主任务源，通常是 OpenSpec 的
tasks.md。
什么时候不要用
- 单文件小改动或一次性格式化。
- 只是在回答问题、解释方案，或者还在做需求探索。
- 写
changeset、提交信息、更新日志这类短任务。 - 不需要 checkpoint、恢复续跑、失败记录的简单操作。
先读什么
开始前先读这些文件，再动手：
AGENT_LONGTASK.md（如果存在）- 按
AGENT_LONGTASK.md读取路由选中的references/*.md - 当前 skill 的
SKILL.md - 业务项目内
.claude/skills、.codex/skills、.agents/skills、.agent/skills中与 OpenSpec 相关的项目级技能 - 当前 OpenSpec change 的
proposal.md - 当前 OpenSpec change 的
design.md - 当前 OpenSpec change 的
specs/*/spec.md - 当前 OpenSpec change 的
tasks.md - 先扫描并处理错位的
agent-progress.md/agent-findings.md - change 根目录的
agent-progress.md - change 根目录的
agent-findings.md
如果这些文件里有缺失，就先补齐，再继续。
核心纪律
- 任务源只用一份。若项目使用 OpenSpec，就以
openspec/changes/<change-name>/tasks.md为唯一任务清单。 - 不要再创建第二套任务系统，也不要把聊天里的临时 checklist 当主任务源。
- 每次只处理一个明确的 task 或一个明确 checkpoint。
- 不要跳过未完成任务。
- 不要把未验证的内容标记为完成。
- 代码修改后必须做相关验证。
- OpenSpec 工件链必须完整维护：先读
proposal.md、design.md、specs/*/spec.md、tasks.md，再动手；发现遗漏任务先扩展tasks.md；改变用户可见行为先同步specs/*/spec.md；改变技术路线先同步design.md。 - 过程报告、进度文档、调研文档若需要保存在当前 OpenSpec change 内，必须放入
tasks.md或项目 OpenSpec 规范明确指定的子目录，并使用YYYY-MM-DD-*.md命名；不得在 change 根目录散放 markdown。 - change 根目录只保留 OpenSpec 核心工件、
agent-progress.md、agent-findings.md以及项目规范明确允许的根级文件；不要把阶段报告、验证报告、调研记录直接写到根目录。 agent-progress.md固定在 change 根目录，不能移动、改名或日期化；只记录 checkpoint、当前 task、核心进度、验证摘要和下一步，不承载超长执行流水。agent-findings.md固定在 change 根目录，不能移动、改名或日期化；只记录核心痛点、风险、失败索引、禁止重复路径和待办入口，不承载完整长报告。- 新建、读取、写入这两个文件前必须先通过位置门禁；若发现仓库根目录、普通 reports 目录、skill 目录或多个任务共用的错位文件，先警告并迁移到具体 active/archive change，再继续执行。
- 当
agent-progress.md或agent-findings.md过长时，先压缩为摘要和索引；详细日志、证据或调研内容迁入tasks.md指定的日期化子目录或证据文件。 - 不要每个小步骤都问用户是否继续，除非遇到真正阻塞。
- 只有遇到权限问题、破坏性风险、需求冲突、产品决策问题，或连续 3 次同类失败时，才暂停并请求用户介入。
状态文件 harness 控制
agent-progress.md 与 agent-findings.md 是交接状态文件，不是事件日志、聊天转储或原始输出仓库。违反以下写入契约会制造上下文噪音：
agent-progress.md：覆盖式快照
- 每次 checkpoint 或 task 边界更新当前快照；修改现有状态，不按命令或对话逐条追加。
- 快照只保留：当前 checkpoint、当前 task、状态、最近验证摘要、阻塞点、下一步和证据索引。
- 默认软上限为 40 行；超过后必须先合并重复内容、删除过期状态，再继续写入。不得用空行或大段日志规避上限。
- 只保留最近 3 个证据索引；完整命令输出必须留在命令结果、
tasks.md已指定的日期化证据文件或其他项目规定位置。
agent-findings.md：去重后的持久发现
- 每条发现必须回答：结论是什么、证据在哪里、状态是什么、后续动作是什么。
- 状态只使用
active、superseded、resolved；新证据推翻旧判断时更新或删除旧条目，不重复追加同一发现。 - 只保留会改变后续 agent 决策的根因、风险、失败索引、禁止重复路径和待办入口；不记录聊天摘要、完整 traceback、重复版本树或普通成功日志。
- 默认软上限为 80 行或 20 条有效发现；达到任一上限时先压缩、合并或移除已解决条目。
写入前门禁
写入前逐项检查：
- 下一位 agent 是否会因为这条信息采取不同动作？不会则不写。
- 是否有证据索引或明确状态？没有则先验证或标记为待验证，不写成结论。
- 是否已经存在同义条目？存在则更新原条目，不新增重复条目。
- 是否属于任务清单？属于则写入
tasks.md，不要把它藏进状态文件。
每个 checkpoint 结束时，必须覆盖更新 agent-progress.md，并对 agent-findings.md 做一次去重和过期条目清理；这两个文件都不允许演变成长期流水账。
标准推进方式
- 开始前刷新文件状态。
- 确定唯一 change 根目录，并扫描、警告、迁移错位的
agent-progress.md/agent-findings.md。 - 选定一个 task。
- 理清该 task 的验收标准和验证命令。
- 核对本轮是否需要同步
design.md、specs/*/spec.md或补写tasks.md，先维护工件链再实现。 - 如需生成过程报告、进度文档或调研文档，先确认
tasks.md或项目 OpenSpec 规范已经定义落点和命名规则。 - 只做最小可验证改动。
- 运行相关测试、lint、typecheck、OpenSpec validate 或其他必要验证。
- 把 checkpoint、文件变化和验证摘要写进规范 change 根目录的
agent-progress.md。 - 把失败索引、风险和不能重复走的路径写进规范 change 根目录的
agent-findings.md。 - 只有满足验收标准才把 task 勾为完成。
- 再进入下一个 task 前，重新读取文件状态。
完成前检查
在标记完成前，确认下面几项都成立：
- 代码已经实现。
- task 的验收标准已经满足。
- 相关验证命令已经通过，或者已经明确记录无法自动验证的替代方式。
agent-progress.md已记录本轮进展和验证结果。agent-findings.md已记录重要发现、失败尝试或剩余风险。- 新增 markdown 文档没有散落在 change 根目录；所有过程报告、进度文档、调研文档都位于
tasks.md或项目 OpenSpec 规范定义的日期化子目录或证据文件中。 agent-progress.md和agent-findings.md仍在 change 根目录，未移动、未改名、未日期化，且只保留摘要、checkpoint、索引和核心风险。- 工作区不存在错位的
agent-progress.md/agent-findings.md；若曾发现错位文件，已警告、迁移到唯一 active/archive change，并回读确认。 - 没有未解决的 CRITICAL 问题。
你要记住的事
- 长任务靠文件，不靠聊天记忆。
- 只保留一个任务源。
- 小步推进。
- 每步都要能恢复。
- 先验证，再完成。