Quartz 4

🔍 搜索

Planning_with_Files_文件化规划系统调研

12 min read

Planning with Files —— 文件化规划系统调研

把 AI 的工作记忆从”内存”搬到”硬盘”，长任务再也不怕上下文压缩丢失规划

一、它解决什么问题

Claude Code 默认的 Plan Mode 将规划存储在对话上下文中。当对话变长、触发上下文压缩时，规划内容可能被部分或全部丢失。结果就是：

  • Claude 做到一半忘了自己在干嘛
  • 跨会话无法恢复之前的工作状态
  • 复杂多阶段任务容易丢失进度和中间发现

planning-with-files 是一个社区开源的 Claude Code Skill（github.com/OthmanAdi/planning-with-files），通过将规划、进度、知识全部写入 Markdown 文件来解决这个问题。截至 2026 年 4 月，GitHub 19K+ stars，v2.34.1，支持 17+ IDE。

二、核心设计：三文件模式

整个系统围绕三个 Markdown 文件运转，放在项目根目录：

文件作用类比
task_plan.md任务的完整规划：目标、阶段、步骤、依赖施工蓝图
findings.md执行过程中发现的技术细节、决策、坑施工日志
progress.md当前进度：哪些完成了、正在做什么、下一步进度看板

task_plan.md 结构示例

# Task Plan
 
## Objective
实现用户认证模块
 
## Phases
### Phase 1: Database Schema
- [x] 创建 users 表
- [x] 创建 sessions 表
- [ ] 添加索引
 
### Phase 2: API Endpoints
- [ ] POST /auth/login
- [ ] POST /auth/register
- [ ] POST /auth/logout
 
## Dependencies
- PostgreSQL 15+
- bcrypt for password hashing
 
## Constraints
- 必须支持 OAuth 2.0
- Session 过期时间 24h

findings.md 结构示例

# Findings
 
## 2026-04-22
- bcrypt 在 Node 20 下需要 native addon 重编译
- PostgreSQL 的 uuid_generate_v4() 需要启用 pgcrypto 扩展
- 现有 middleware 已有 rate limiting，不需要重复实现

progress.md 结构示例

# Progress
 
## Current Phase: Phase 1 - Database Schema
## Current Step: 添加索引
## Status: IN_PROGRESS
 
## Completed
- [x] Phase 1, Step 1: 创建 users 表
- [x] Phase 1, Step 2: 创建 sessions 表
 
## Next
- Phase 1, Step 3: 添加索引
- Phase 2, Step 1: POST /auth/login

三、工作原理：Hooks 驱动

planning-with-files 的核心机制是利用 Claude Code 的 Hooks 系统，在关键时刻自动读写这三个文件，让 Claude 始终”记得”规划内容。

Hook 触发点

Hook 事件触发时机动作
UserPromptSubmit用户每次发送消息时读取 task_plan.md 头部 + progress.md 尾部，注入上下文
PreToolUse (Write/Edit/Bash/Read/Glob/Grep)Claude 调用工具前读取 task_plan.md 头部 30 行，提醒当前规划
PostToolUse (Write/Edit)Claude 修改文件后提醒更新 progress.md
StopClaude 结束回复时运行 check-complete.sh 验证所有阶段是否完成

数据流示意

用户发消息
    │
    ▼
[UserPromptSubmit Hook]
    │ 读取 task_plan.md 头部
    │ 读取 progress.md 尾部
    │ 注入到 Claude 上下文
    ▼
Claude 开始思考和工作
    │
    ├──► [PreToolUse Hook] ──► 每次调工具前重读规划
    │
    ├──► Claude 执行操作（编辑代码等）
    │
    ├──► [PostToolUse Hook] ──► 提醒更新进度
    │
    ▼
[Stop Hook] ──► 检查任务是否全部完成

关键规则

2-Action Rule（两步规则）： 每次修改代码文件后，必须更新 progress.md。防止做了事但没记录，下次上下文压缩后丢失进度。

3-Strike Error Protocol（三振出局协议）： 同一个错误连续出现 3 次，必须停下来重新评估方案，把分析写入 findings.md，而不是继续盲目重试。

Session Recovery（会话恢复）： 新会话开始时，Claude 通过读取三个文件即可恢复完整状态——不需要回顾对话历史，不依赖上下文窗口。

四、安装方式

方式 1：作为 Skill 安装（推荐）

# 在项目根目录
mkdir -p .claude/skills/planning-with-files
# 将 SKILL.md 放入该目录

然后在 .claude/commands/ 添加 plan.md 命令文件，用 /plan 触发。

方式 2：作为 Plugin 安装

项目提供了 .claude-plugin/ 目录结构，可以作为 Claude Code Plugin 安装。

方式 3：手动配置 Hooks

如果不想安装完整 skill/plugin，可以只配置核心 hooks：

// .claude/settings.json 的 hooks 部分
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "command": "head -30 task_plan.md 2>/dev/null; echo '---'; tail -20 progress.md 2>/dev/null"
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Write|Edit|Bash|Read|Glob|Grep",
        "command": "head -30 task_plan.md 2>/dev/null"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "echo 'Remember to update progress.md with current status'"
      }
    ]
  }
}

配套命令

命令作用
/plan开始规划任务，创建/更新 task_plan.md
/plan start开始执行规划
/plan status查看当前进度

五、适用场景分析

适合使用的场景

场景为什么需要
多阶段重构（3+ 阶段）阶段多，上下文压缩后容易丢失全局视图
跨会话的长期任务新会话自动恢复，不需要重新解释
多人协作的 AI 辅助开发文件化的规划可以被团队成员 review
探索性任务（调研 → 方案 → 实施）findings.md 积累的知识不会丢失
需要严格进度追踪的任务progress.md 提供清晰的完成状态

不需要使用的场景

场景为什么不需要
单文件 bug 修复太简单，三文件反而是负担
快速问答无需规划
短对话内能完成的任务上下文不会压缩，Plan Mode 够用
一次性脚本编写没有跨会话需求

六、与 Claude Code 内置 Plan Mode 的对比

维度内置 Plan Modeplanning-with-files
存储位置对话上下文（内存）Markdown 文件（磁盘）
上下文压缩后可能丢失完整保留
跨会话恢复不支持自动恢复
进度追踪无专门机制progress.md 实时更新
知识积累在对话中，会被压缩findings.md 永久保留
团队可见性仅当前用户文件可 commit/分享
开销零每次工具调用多读几十行文件
适合任务规模小到中中到大
学习成本零（内置）需理解三文件模式 + hooks

核心区别：Plan Mode 是”工作记忆”（RAM），planning-with-files 是”持久存储”（SSD）。两者不冲突，可以同时使用。

七、潜在问题与注意事项

1. Token 开销

每次用户发消息和每次工具调用都会触发 hook 读取文件。对于 task_plan.md 较大的项目，这会增加每轮对话的 token 消耗。

缓解：hook 只读取 head -30（头 30 行），而非全文。但如果规划内容很长，30 行可能不够覆盖关键信息。

2. 文件冲突

三个文件放在项目根目录，可能：

  • 与现有文件冲突
  • 被误提交到 git
  • 多个 Claude Code 会话同时修改

缓解：添加到 .gitignore；或改用 .claude/ 子目录存放。

3. Hook 的局限性

Hooks 通过 shell 命令注入文本到上下文，但：

  • 注入的文本是 <user-prompt-submit-hook> 标签包裹的，Claude 会当作系统信息处理
  • 如果 Claude 决定忽略 hook 提醒（比如”记得更新 progress.md”），没有强制机制
  • Hook 命令如果执行失败（比如文件不存在），不会阻断 Claude 的操作

4. 维护负担

三个文件需要 Claude 主动维护。如果 Claude 忘记更新（尤其是 findings.md），文件内容会逐渐过时，反而提供误导性信息。

5. 社区项目风险

  • 非 Anthropic 官方维护，可能与 Claude Code 版本更新不兼容
  • Hook API 如果变更，skill 需要跟着适配
  • 19K stars 说明社区活跃，但也意味着 issue 多、PR 多，质量参差

八、社区生态

主要 Fork 和扩展

项目特点
alexarevalo9/planning-with-files增加了 context-window 监控
daoch4/planning-with-files简化版，去掉了 findings.md
ruvnet/planning-with-files增加了 AI 自动评估规划质量
Solla-AI/planning-with-files集成了 Solla 的知识图谱

IDE 支持

官方声称支持 17+ IDE，核心依赖的是 Claude Code 的 Skill/Hook 机制，所以实际支持范围取决于 Claude Code 的 IDE 集成：

  • VS Code (Claude Code Extension)
  • JetBrains (Claude Code Plugin)
  • Terminal (Claude Code CLI)
  • Web (claude.ai/code)

九、我的评估

值得用的点

  1. 跨会话恢复是刚需：对于超过 1 小时的复杂任务，上下文压缩几乎必然发生，这是真实痛点
  2. findings.md 非常实用：调研类任务（像我们现在做的）最怕中间发现丢失
  3. 设计简洁：三个 Markdown 文件 + 四个 Hook，没有引入复杂依赖
  4. 可渐进采用：可以只用 task_plan.md + progress.md，不用 findings.md

需要注意的点

  1. 并非所有任务都需要：简单任务加上三文件反而是噪音
  2. Claude Code 自身在演进：内置的 Plan Mode + Task 系统 + auto memory 在持续改进，部分需求可能被原生满足
  3. Token 成本：每轮额外读文件的开销在长对话中累积可观
  4. 依赖 Claude 自觉性：Hook 只能提醒，不能强制 Claude 更新文件

结论

对于 3 阶段以上、预计跨会话的复杂任务，planning-with-files 是目前最成熟的解决方案。对于日常开发，Claude Code 内置的 Plan Mode + TaskCreate 已经够用。

建议策略：按需启用。不做全局安装，而是在需要时为具体项目配置。

十、快速上手（如果决定安装）

# 1. 克隆到 Claude Code skills 目录
cd your-project
mkdir -p .claude/skills
git clone https://github.com/OthmanAdi/planning-with-files.git .claude/skills/planning-with-files
 
# 2. 复制命令文件
cp .claude/skills/planning-with-files/commands/plan.md .claude/commands/plan.md
 
# 3. 添加到 .gitignore（避免规划文件提交）
echo -e "task_plan.md\nfindings.md\nprogress.md" >> .gitignore
 
# 4. 使用
# 在 Claude Code 中输入 /plan 开始规划

十一、参考资源

资源说明
OthmanAdi/planning-with-files官方仓库
SKILL.md核心实现文件，包含所有 Hook 定义和规则
Claude Code Hooks 文档Hook 机制官方文档
Claude Code Skills 文档Skill 机制官方文档

最后更新：2026-04-22 基于 planning-with-files v2.34.1 调研

Graph View