planning-with-files 数据分析任务模板实战：用 analytics_task_plan.md 为 AI Agent 搭建可恢复的分析流水线-编程实验室

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.md（skill 安装目录）
.opencode/skills/planning-with-files/templates/analytics_task_plan.md（OpenCode 集成目录，即本次讲解的关联文档所在位置）

模板文件头部自述了它的定位："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（假设）

Decisions Made（决策记录）

记录分析过程中的关键选择，包括选用的检验方法、过滤条件、样本排除及其理由。表格结构为| Decision | Rationale |。为什么值得记录？因为在长会话中，一个"当时显然合理"的过滤条件很可能在三小时后成为疑问的源头；有了决策日志，后续复现、审阅或交接时都能回答"为什么这么做"。

Errors Encountered（错误记录）

记录每个不同的错误、尝试次数与解决方案。表格结构为| Error | Attempt | Resolution |。模板特别强调："Change the approach before retrying a failed action."（在重试失败动作之前先改变方法）。这与 SKILL.md 的核心规则"Log ALL Errors"和"Never Repeat Failures"（if 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_ID=2026-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.md）；Hermes 集成同样支持带--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.md（planning-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），也能在会话中断后无损恢复——而这一切都以仓库中可复现的模板文件、初始化脚本和测试契约作为事实依据。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

planning-with-files 数据分析任务模板实战：用 analytics_task_plan.md 为 AI Agent 搭建可恢复的分析流水线