Planning with Files：基于文件的 AI 代理规划工作流实践

1. 把规划写进文件：让 AI 代理不再失忆

项目地址：https://github.com/OthmanAdi/planning-with-files

简介：一个将任务规划、进度与知识落地的 Markdown 文件工作流插件，支持 Claude Code、Cursor、Gemini CLI 等。

核心价值：解决 AI 在长任务中上下文漂移、记忆丢失的问题，通过持久化文件实现可追溯的过程记录。

1.1. 前言

在使用 AI 处理复杂任务（如写文章、做调研、改项目）时，常出现前 10 分钟顺畅，随后因上下文重置或工具调用过多导致 AI'遗忘'目标、重复失败的情况。planning-with-files 不依赖更长的 Prompt，而是将重要信息从临时上下文迁移到文件系统，形成持久的工作记忆。

1.2. 背景与痛点：为什么需要'文件化规划'

AI 代理的上下文类似 RAM（有限、易失），而文件系统类似 Disk（持久、容量大）。常见痛点包括：

痛点	典型表现	后果
易失记忆	上下文重置后计划和结论丢失	返工、重复问答
目标漂移	工具调用多了开始偏题	交付不符合目标
错误不留痕	失败未记录，下次重踩坑	效率降低
上下文塞爆	资料堆在对话里未写入文件	不可追溯

解决之道在于将工作流改为'可持久化'。

1.3. 核心观点：3 文件 + Hooks

该模式维护三个核心文件：

task_plan.md → 任务分阶段与状态（计划与对齐） 
findings.md → 研究发现与关键决策（知识沉淀） 
progress.md → 会话日志、操作记录、测试结果（过程可追溯）

Hooks 负责在关键时点读取/提醒，脚本负责初始化与校验，Session Recovery 负责在 /clear 后补全遗漏信息。

1.3.1. 与'上下文工程'的关系

这是一种偏工程实现的 上下文工程（Context Engineering） 方案。通过将上下文从'聊天记录'迁移到'文件系统'，实现：

单一真理来源：以 task_plan.md/findings.md/progress.md 为最新事实依据。
状态显式化：阶段状态、决策、错误均写在文件中。
最小必要上下文：重要信息入盘，按需读取。
思考与行动分离：先写发现再执行，减少污染。

1.3.2. Manus 六大上下文工程原则落地

项目在 skills/planning-with-files/reference.md 中总结了 Manus 的 6 条原则，本项目将其转化为可操作的工具：

原则	原文要点	本项目落地
Design Around KV-Cache	Keep prompt prefixes STABLE	稳定流程与文件结构
Mask, Don't Remove	Don't dynamically remove tools	`allowed-tools` 白名单
Filesystem as External Memory	Markdown is working memory	三文件外部化记忆
Manipulate Attention Through Recitation	Re-read task_plan.md before decision	PreToolUse 回显计划
Keep the Wrong Stuff In	Leave wrong turns in context	记录 Errors 不静默重试
Don't Get Few-Shotted	Uniformity breeds fragility	适度引入变化避免循环

经验总结：

文件是记忆：重要信息必须落盘。
压缩要可恢复：保留 URL/路径/关键词指针。
目标要复读：关键决策前回读 task_plan.md。
失败要留痕：显式记录错误与修复。
动作要有变体：避免机械循环。

1.3.3. 2-Action Rule：防止'看过就忘'

每进行两次查看/搜索操作，必须立刻将关键发现写进 findings.md。零散片段若不进入文本文件，会在上下文压缩后消失。

2. 怎么落地：在 Claude Code 里用起来

2.1. 安装

claude plugins install OthmanAdi/planning-with-files

安装后可用命令：

/plan (v2.11.0+)：规划命令
/planning：开始会话与规划流程

2.2. 五步工作流

运行初始化脚本生成 task_plan.md / findings.md / progress.md。
在 task_plan.md 写清 Goal，拆 3–7 个 phases。
工作过程中按'发现/过程/计划'分别写入三文件。
每两次查看/搜索更新一次 findings.md（2-Action Rule）。
收尾前用 check-complete.sh 确认 phases 全部 complete。

2.2.1. Session Catchup：检查上一会话

每次开始长任务前，建议跑一次 session-catchup.py，确认上一次会话是否有未写入三文件的关键信息。

2.2.2. 模板文件位置

Templates：插件安装目录（如 ${CLAUDE_PLUGIN_ROOT}/templates/）。
你的三文件：当前项目目录（project root）。

2.3. 会话恢复：`/clear` 之后不断档

当上下文满需 /clear 时，session-catchup.py 机制如下：

定位会话存储：查找 ~/.claude/projects/<sanitized-project>/ 下的历史会话文件。
找最后一次更新：扫描 Write/Edit 工具调用，定位三文件最后更新时间。
抽取后续内容：整理该时间点后的用户消息、助手消息及关键工具调用。

操作顺序：

读当前三文件确认状态。
跑 session-catchup.py 看报告，补全缺失信息。
跑 git diff --stat 确认真实改动，写入 progress.md。

2.4. 边界条件与取舍

不建议用	原因	替代
一句话问答/单文件小改	创建成本高于收益	直接问/直接改
不打算落盘任何过程	失去意义	至少写 `task_plan.md`
团队不需要可追溯	复盘成本回收难	只保留关键 decisions

预计超过 5 次工具调用或跨多会话的任务通常适用。

2.5. examples/README.md 演示

仓库示例展示了 Todo App 开发过程，体现三文件如何协同：

2.5.1. task_plan.md：阶段状态机

## Current Phase
Phase 1
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Document findings in findings.md
- **Status:** in_progress

2.5.2. findings.md：固定决策

## Research Findings
- Python's `argparse` module is perfect for CLI subcommands
- `json` module handles file persistence easily

2.5.3. 错误记录

错误需双写入：

task_plan.md 的 Errors Encountered：避免复现。
progress.md 的 Error Log：便于追溯。

2.6. 最小循环（Loop）

每个 Loop 包含：

Read task_plan.md（对齐目标）
做一件事（搜索/读文件/写代码）
Write/Edit files（更新状态）

3. SKILL.md 重要性

真正起作用的是 SKILL.md 中的行为约束，通过 hooks 和脚本将流程变为可重复机制。

3.1. Frontmatter：能力边界声明

---
name: planning-with-files
version: "2.10.0"
description: Implements Manus-style file-based planning...
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - WebFetch
  - WebSearch
hooks: ...
---

YAML 格式提供机器可读的配置，明确身份、能力边界和触发机制。

3.2. PreToolUse：回显目标

PreToolUse:
- matcher: "Write|Edit|Bash|Read|Glob|Grep"
  hooks:
    - type: command
      command: "cat task_plan.md 2>/dev/null | head -30 || true"

每次关键动作前输出 task_plan.md 前 30 行，强制将 Goal/当前阶段塞回注意力窗口。

3.3. PostToolUse：更新阶段状态

PostToolUse:
- matcher: "Write|Edit"
  hooks:
    - type: command
      command: "echo '[planning-with-files] File updated...'

写入文件后提醒更新 phase 状态，防止遗忘。

3.4. Stop Hook：完成闸门

调用 check-complete.sh 脚本，验证所有 phases 是否均为 complete，将主观完成感变为可验证规则。

3.5. Session Recovery

利用 scripts/session-catchup.py 生成 catchup 报告，将丢失的状态同步回三文件。

4. 下一步：10 分钟上手

安装并触发 /plan。
在项目根目录生成三文件。
在 task_plan.md 写 Goal，拆 3 个 phase。
两次阅读/搜索后更新 findings.md。
每做完一个 phase 更新状态并记录 progress.md。
收尾时跑 check-complete.sh 直到 phases 全部 complete。

5. 参考文献