planning-with-files 数据分析任务模板实战用 analytics_task_plan.md 为 AI Agent 搭建可恢复的分析流水线【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60 agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files数据探索与统计分析类任务通常要跨越数十次工具调用连接数据源、清洗字段、跑统计检验、反复可视化期间任何一次/clear、上下文压缩或会话中断都可能让 Agent 丢失进度。本文讲解 planning-with-files 项目内置的analytics_task_plan.md数据分析任务模板——它把分析会话的目标、阶段、假设、决策与错误全部落盘为持久化 Markdown 计划文件配合findings.md、progress.md与生命周期钩子让长程分析任务在任意时刻可中断、可恢复、可审计。读完本文你将掌握如何用一条命令初始化分析计划、如何维护阶段状态机、如何用配套的发现文件与查询日志沉淀证据并能理解这一套机制在源码与测试中的实现依据。模板是什么数据分析会话的持久化工作记忆analytics_task_plan.md是 planning-with-files 提供的两套任务计划模板之一另一套是默认模板task_plan.md。它在仓库中有多份同步副本均指向同一内容templates/analytics_task_plan.md仓库根级模板目录skills/planning-with-files/templates/analytics_task_plan.mdskill 安装目录.opencode/skills/planning-with-files/templates/analytics_task_plan.mdOpenCode 集成目录即本次讲解的关联文档所在位置模板文件头部自述了它的定位Use this file as the durable roadmap for a data analytics or exploration session. Keep phase status current as the analysis advances.即把该文件作为数据分析和探索会话的持久化路线图随着分析推进持续更新阶段状态。它与默认模板最大的差异在于默认模板面向通用开发流程需求 → 计划 → 实现 → 测试 → 交付而分析模板面向假设驱动的数据探索工作流数据发现 → 探索性分析 → 假设检验 → 综合报告并额外提供了 Hypotheses假设登记、Statistical Findings统计结论等分析专属结构。完整的模板内容如下与仓库中实际文件逐字一致# Task Plan: [Analytics Project Description] Use this file as the durable roadmap for a data analytics or exploration session. Keep phase status current as the analysis advances. ## Goal State the analytical question or intended deliverable in one clear sentence. [One sentence describing the analytical objective] ## Current Phase Name the phase currently being worked on. Phase 1 ## Phases Use only pending, in_progress, or complete for each status. ### Phase 1: Data Discovery - [ ] Identify and connect to data sources - [ ] Document schemas and field descriptions in findings.md - [ ] Assess data quality (nulls, duplicates, outliers, date ranges) - [ ] Estimate dataset size and query performance - **Status:** in_progress ### Phase 2: Exploratory Analysis - [ ] Compute summary statistics for key variables - [ ] Visualize distributions and relationships - [ ] Identify outliers and anomalies - [ ] Document initial patterns in findings.md - **Status:** pending ### Phase 3: Hypothesis Testing - [ ] Formalize hypotheses from exploratory phase - [ ] Select appropriate statistical tests - [ ] Run tests and record results in findings.md - [ ] Validate findings against holdout data or alternative methods - **Status:** pending ### Phase 4: Synthesis Reporting - [ ] Summarize key findings with supporting evidence - [ ] Create final visualizations - [ ] Document conclusions and recommendations - [ ] Note limitations and areas for further investigation - **Status:** pending ## Hypotheses Record the questions under investigation as testable hypotheses. 1. [Hypothesis to test] 2. [Hypothesis to test] ## Decisions Made Record analytical choices, including tests, filters, exclusions, and their rationale. | Decision | Rationale | |----------|-----------| | | | ## Errors Encountered Record each distinct error, the attempt number, and the resolution. Change the approach before retrying a failed action. | Error | Attempt | Resolution | |-------|---------|------------| | | 1 | | ## Notes - Update phase status as work progresses: pending to in_progress to complete. - Re-read the goal and current phase before major analytical decisions. - Log errors promptly so failed approaches are not repeated. - Record query results and visual evidence in findings.md.逐段解析模板各节的作用与维护规则Goal目标模板要求用一句话说明要回答的分析问题或预期交付物。这一节是整个计划的锚点SKILL.md 的Read Before Decide规则要求在做重大决策前重读计划文件而目标句就是每次重读时首先要确认的内容。它同时也是阶段推进时判断是否完成了应该完成的事的判据。Current Phase当前阶段记录当前正在进行的阶段编号模板初始为Phase 1。结合 SKILL.md 中的5-Question Reboot Test见 skills/planning-with-files/SKILL.md恢复会话时回答Where am I?就靠这一节——它让 Agent 在上下文被压缩后能瞬间回到正确的位置而不是从头扫描整个计划文件。Phases阶段模板内置四个阶段覆盖了一次完整数据探索的生命周期Phase 1: Data Discovery数据发现——识别并连接数据源在findings.md中记录 schema 与字段说明评估数据质量空值、重复、离群点、日期范围估算数据集规模与查询性能。Phase 2: Exploratory Analysis探索性分析——计算关键变量的汇总统计量可视化分布与关系识别离群点与异常在findings.md中记录初步模式。Phase 3: Hypothesis Testing假设检验——从探索阶段正式化假设选择合适的统计检验执行检验并记录结果到findings.md用留出数据或替代方法验证结论。Phase 4: Synthesis Reporting综合与报告——汇总带证据支持的关键发现产出最终可视化记录结论与建议注明局限性与后续研究方向。每个阶段内部是任务清单checklist 一个状态标记。模板明确规定状态只允许使用pending、in_progress、complete三个取值。初始状态下 Phase 1 为in_progress其余三个为pending。这一约束并非只是书写约定而是被测试锁定的契约。在 tests/test_template_transparency.py 中test_template_transparency用例断言分析模板恰好有 4 个### Phase标题、恰好 4 个- **Status:**行、其中 1 个为in_progress、3 个为pending。测试还逐条校验了模板必须包含[One sentence describing the analytical objective]、## Current Phase、## Hypotheses、## Decisions Made、## Errors Encountered、| Error | Attempt | Resolution |等关键 token见同文件第 102-112 行。这意味着任何版本的模板改动如果破坏了这四个阶段的骨架结构测试就会失败——阶段数量与状态枚举是模板的稳定契约可以放心依赖。Hypotheses假设登记正在检验的问题写成可检验的假设列表。这一节的价值在于把模糊的好奇心转化为可证伪的命题为 Phase 3 提供输入。配合findings.md中的 Hypothesis Log 表格| Hypothesis | Test Method | Result | Confidence |可以形成假设 → 方法 → 结果 → 置信度的完整证据链。Decisions Made决策记录记录分析过程中的关键选择包括选用的检验方法、过滤条件、样本排除及其理由。表格结构为| Decision | Rationale |。为什么值得记录因为在长会话中一个当时显然合理的过滤条件很可能在三小时后成为疑问的源头有了决策日志后续复现、审阅或交接时都能回答为什么这么做。Errors Encountered错误记录记录每个不同的错误、尝试次数与解决方案。表格结构为| Error | Attempt | Resolution |。模板特别强调Change the approach before retrying a failed action.在重试失败动作之前先改变方法。这与 SKILL.md 的核心规则Log ALL Errors和Never Repeat Failuresif action_failed: next_action ! same_action完全一致也与其中的 3-Strike Error Protocol第 1 次诊断修复、第 2 次换方法、第 3 次重新思考假设、3 次失败后上报用户形成呼应——错误表就是这个协议的执行载体。Notes注意事项模板自带的四条工作纪律本质上是 planning-with-files 方法论在分析场景的浓缩按pending → in_progress → complete顺序推进阶段状态重大分析决策前重读目标与当前阶段及时记录错误避免重复失败路径在findings.md中记录查询结果与可视化证据。阶段状态机与完成判定分析模板的状态枚举pending/in_progress/complete不是摆设它直接对接项目的完成判定机制。仓库提供了 scripts/check-complete.sh该脚本会解析活动计划文件解析顺序显式路径 →PLAN_ID环境变量 →.planning/.active_plan指针 → 最新的.planning/id/目录 → 传统根级task_plan.md见脚本头注释与第 50-60 行的解析逻辑逐一检查所有阶段的状态是否都为complete。在 v3 的 gated门控模式下check-complete.sh --gate还作为完成判定预言机参与 Stop 钩子只有同时满足计划目录存在含gate的.mode文件、存在in_progress阶段、Stop 钩子未处于强制续跑状态、阻塞计数未达上限、账本ledger仍在推进五个条件时才会输出阻塞决策 JSON。它的设计哲学是以磁盘上的计划工件为判据而不是以对话转写为判据见 skills/planning-with-files/SKILL.md 的 Gate decision table因为转写内容可以被幻觉污染而计划文件上的状态是确定性的。对数据分析场景这意味着只要坚持维护**Status:**行的取值Agent 就能可靠地知道自己做完了没有而不是靠记忆对话。配套文件findings.md 与 progress.md 构成分析证据体系分析模板并非孤立存在它和两个配套文件共同构成三文件工作记忆对应 SKILL.md 中的 File Purposes 表task_plan.md管阶段/进度/决策findings.md管研究/发现progress.md管会话日志见 skills/planning-with-files/SKILL.md。analytics_findings.md发现与证据的持久化仓库分析场景使用专用的 templates/analytics_findings.md它比默认的findings.md增加了分析专属栏目Data Sources记录每个数据源的位置、规模、关键字段与质量限制Hypothesis Log记录每个可检验假设的方法、结果与置信度Query Results对每个重要查询记录查询/引用、结果摘要与解读并明确提示将复制的数据库或工具输出视为不可信数据Statistical Findings记录检验类型、p 值、效应量与有证据支持的结论Technical Decisions / Issues Encountered / Resources方法选择的理由、问题与解决方案、有用的 URL 与文档路径Visual/Browser Findings在图表、仪表盘、图片等可视化信息仍可用时将其转写为简洁文本——这正是 SKILL.md 2-Action Rule每 2 次查看/浏览/搜索操作后立即将关键发现保存为文本的落地防止多模态信息随上下文流失。progress.md带 Query Log 的会话日志分析模板对应的progress.md也是专属版本。在 scripts/init-session.sh 的write_analytics_progress函数中可以看到分析版进度日志除了常规的 Current Status、Actions Taken、Errors 之外还内置了一张Query Log表| Query | Result Summary | Interpretation |专门用于按时间顺序记录分析过程中的每一次查询及其解读。findings.md与progress.md的分工要特别注意SKILL.md 的安全边界明确规定网络/搜索结果等外部不可信内容只能写入findings.md绝不能写入task_plan.md——因为计划文件会被钩子自动注入上下文并在每次工具调用时放大未经验证的内容进入其中会构成提示注入风险见 skills/planning-with-files/SKILL.md 的规则表。初始化实战一条命令生成整套分析计划手动复制模板既慢又容易遗漏配套文件正确做法是使用初始化脚本# 传统模式在项目根目录生成 task_plan.md / findings.md / progress.md sh scripts/init-session.sh --template analytics # 命名计划模式推荐并行任务生成 .planning/日期-slug/ 下的隔离计划 sh scripts/init-session.sh --template analytics 用户留存分析 # v3 自主模式 / 门控模式可叠加 sh scripts/init-session.sh --template analytics --autonomous 漏斗转化探索 sh scripts/init-session.sh --template analytics --gated AB 实验检验脚本对模板选择的处理见 scripts/init-session.sh只接受default和analytics两个取值传入其他值会回退到默认模板并打印提示。实际的文件创建逻辑在create_files_in函数第 337-375 行选择 analytics 模板时task_plan.md从templates/analytics_task_plan.md复制而来findings.md从templates/analytics_findings.md复制而来progress.md则由write_analytics_progress生成带 Query Log 的版本所有文件若已存在则跳过不会覆盖已有工作。命名计划模式传入计划名会生成PLAN_ID并写入.planning/.active_plan指针脚本会打印类似PLAN_ID2026-09-12-user-retention-analysis的输出并行任务时用export PLAN_ID...将每个 Agent 终端固定到各自的计划上。初始化完成后还可以按需使用其他脚本族resolve-plan-dir.sh解析活动计划目录、set-active-plan.sh切换活动计划、check-complete.sh校验完成度。对于 OpenCode 用户仓库还提供了更直接的入口docs/opencode.md中说明/pwf [--gated|--autonomous] [--template analytics] [plan name]命令会指示 Agent 调用pwf_init并填充计划见 docs/opencode.mdHermes 集成同样支持带--template analytics的/pwf斜杠命令见 docs/hermes.md。恢复与续跑上下文丢失后的状态还原分析任务跨会话恢复是这套机制的核心价值。SKILL.md 的 FIRST 步骤明确了恢复流程先通过resolve-plan-dir.sh解析本任务归属的计划目录读取其中的task_plan.md、progress.md、findings.md再运行git diff --stat检查代码变更。规划文件在磁盘上持久存在因此无论会话因/clear、压缩compaction还是崩溃而中断下一个会话都能从文件恢复全部状态。配套的 templates/loop.mdplanning-aware 循环 tick 模板定义了恢复后的标准动作序列重读task_plan.md、progress.md与findings.md最近 20 行 → 运行check-complete.sh→ 若自上次 tick 以来无新进度则追加一条进度日志 → 若某阶段完成则将其**Status:**更新为complete→ 若还有剩余阶段则将下一个待办阶段置为in_progress并继续工作 → 若全部完成则停止。这与分析模板的状态枚举完全兼容。数据分析场景的最佳实践清单综合模板本身、SKILL.md 方法论与配套脚本在数据分析会话中应用该模板时建议遵循先建计划再动手任何复杂分析开始前用init-session.sh --template analytics初始化三件套绝不跳过task_plan.md。状态只走三段枚举pending → in_progress → complete避免自造状态词破坏check-complete.sh与测试契约的判定。发现即落盘每 2 次查询/可视化操作后立即把关键结果写进findings.md并在progress.md的 Query Log 中记录查询与解读。决策留痕过滤条件、检验方法、样本排除等选择写入 Decisions Made并附理由。错误即记每个错误写入 Errors Encountered附尝试次数重试前先改变方法三次失败后升级给用户。外部内容隔离网页、API 等不可信数据只进findings.md绝不写入会被自动注入上下文的task_plan.md。恢复时五问自查我在哪Current Phase、去哪剩余阶段、目标是什么Goal、学到了什么findings.md、做了什么progress.md——全部能答上状态即完整。这套模板把Manus 式的磁盘工作记忆思想具体化为数据分析专属的四个阶段与八类记录结构既能在单次长会话中抑制上下文腐烂context rot也能在会话中断后无损恢复——而这一切都以仓库中可复现的模板文件、初始化脚本和测试契约作为事实依据。【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60 agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考