planning-with-files Skill：让 AI 编程智能体实现持久化任务规划的 Manus 工作流

Skill超级捕获手 技术创作者 2026-10-05 24 阅读

总结

planning-with-files 是一个为 AI 编程智能体打造的持久化文件规划系统——用 Markdown 文件（task_plan.md / findings.md / progress.md）替代昙花一现的上下文记忆，让任务规划在 /clear、崩溃、上下文压缩后依然存活，并通过生命周期钩子在每轮对话时自动重新注入。该 Skill 曾帮助其作者 OthmanAdi 以 2026 年 2 月 GitHub Trending 全榜第一的成绩出道，目前已被 60+ 种智能体原生支持（包括 Claude Code、Codex、Cursor、Pi、OpenCode 等），Star 数突破 2.7 万，是长流程 Agent 场景下最被高频引用的基础设施类 Skill 之一。

功能与原则

核心能力： 在磁盘上维护三份结构化 Markdown 文档作为”外置硬盘”——任务规划（task_plan.md）、研究发现（findings.md）、执行进度（progress.md），智能体每轮对话开始时通过钩子（hook）将当前计划重新注入上下文，实现规划永续。

设计原则：

  • 持久化优先于上下文：上下文窗口是易失的，磁盘文件不是。/clear 和崩溃不影响已落盘的规划状态。
  • 上下文腐烂（Context Rot）防护：对话拉长后早期指令被挤出，文件规划每轮重新注入，保证目标一直在模型注意力窗口内。
  • 确定性完成门控（Completion Gate）：gated 模式下，智能体只有在所有 in_progress 阶段完成后才能自行停止，防止”提前宣布完成”的长尾问题。
  • 计划防篡改：SHA-256 签名机制，任何被意外或恶意修改的计划体在注入时会被拒绝并标注 [PLAN TAMPERED]。
  • 零运行时依赖：纯文件操作，不启动守护进程，不向外部服务发送数据。

认可度

  • GitHub Star：约 26,600+（截至 2026 年 10 月 5 日）
  • Forks：2,164+
  • 支持智能体：60+ 种，包括 Claude Code、OpenAI Codex CLI、Cursor、GitHub Copilot、Pi、OpenCode、Continue、Hermes Agent、DeepSeek Harness 等主流 Agent
  • GitHub Trending 经历：2026 年 2 月登顶 GitHub 全榜 Trending 第一，Manus-style workflow 概念引爆开发者社区讨论
  • npm 周下载： 持续增长中（具体数值因版本迭代波动）
  • 技能市场收录： Claude Code 插件商店（plugin marketplace）、Agent Skills 标准目录（agentskills.io）、Smithery 等多个平台均有收录

链接

GitHub 仓库：https://github.com/OthmanAdi/planning-with-files

原作者

OthmanAdi（GitHub @othmanadi）—— 独立开发者，以 planning-with-files 一战成名。其设计理念深受 Manus 启发，但将”持久化规划层”独立为可复用的 Skill 标准，曾在 2026 年上半年多次占据 GitHub Trending 榜首，是 AI Agent 记忆工程（Memory Engineering）领域的代表性人物。

介绍

当智能体在处理一个跨越多天、需要数百次工具调用的长任务时，上下文窗口是它的致命弱点。每一次 /clear、每一次上下文压缩、每一次意外崩溃，都可能让精心设计的计划付之东流。planning-with-files 的出现就是为了解决这个痛点——把规划从昙花一现的上下文移到永不丢失的磁盘上。

该项目最初于 2025-2026 年间发布，v3 版本引入 Autonomous（自主）和 Gated（门控）两种运行模式，进一步将长流程执行的不确定性降低。v3.7 版本还新增了 in-tree .agents/skills/ 布局，Zed、Amp、Warp、Devin 等 Agent 可直接从 git clone 结果中发现 Skill，无需逐平台单独配置。

实际上，planning-with-files 不只是给”人”用的规划工具，更是一套智能体协作协议：多个 Agent 可以读写同一份磁盘规划文件，orchestrator 主 Agent 负责更新 task_plan.md，各 worker 追加 progress.md，共享同一套 SHA-256 签名验证，天然支持多 Agent 协作场景。

特点

  • 三文件持久化架构：task_plan.md（任务规划阶段）、findings.md（研究发现）、progress.md（执行进度），全部为纯 Markdown，无需数据库或额外服务
  • 生命周期钩子自动注入：UserPromptSubmit 钩子每轮对话自动将当前计划头部重新注入上下文，/clear 后自动恢复，无需手动操作
  • 多 Agent 共享状态：通过 .planning/YYYY-MM-DD-slug/ 隔离并行任务，通过 .active_plan 指针共享默认计划，多 Agent 场景天然支持
  • Gated Completion Mode：只有当 task_plan.md 所有 in_progress 阶段全部完成，Stop 门控才会释放，阻止 Agent 提前停止
  • 计划防篡改机制：SHA-256 签名比对，被修改过的计划文件在注入时被拒绝并提示 [PLAN TAMPERED]
  • Ledger 机制（v3 新增）： Autonomous 模式下，Agent 每步操作写入 ledger-.jsonl，progress.md 尾段替换为固定格式的 KV-cache 稳定摘要，极大降低 token 消耗
  • 跨 60+ Agent 原生支持：Claude Code 插件、Codelens CLI、Pi、OpenCode、DeepSeek Harness、Zed、Amp 等均有官方或原生集成

使用方法

安装（任选其一）

方式一：Claude Code 插件市场（推荐）

/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

方式二：npx skills（60+ Agent 通用）

npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

方式三：npm 锁定版本

npm install planning-with-files

基本使用

安装后，在 Claude Code（或其他支持的 Agent）中：

  1. 输入 /plan 或直接说”plan this task”，Skill 自动创建三份文件
  2. Agent 按 task_plan.md 中的阶段推进，每步操作自动更新 progress.md
  3. 新发现写入 findings.md
  4. 遇到 /clear、崩溃或长对话 → 钩子自动重新注入当前计划，Agent 从断点继续

最小示例

$ claude
You: /plan build a REST API with auth
Agent: [自动创建 task_plan.md, findings.md, progress.md，按阶段执行]
You: /clear
Agent: [自动读取磁盘，恢复 plan，继续执行]

多 Agent 并行任务

# 为并行任务初始化独立目录
npx planning-with-files/scripts/init-session.sh "" my-feature

# 或在 Claude Code 中设置 PLAN_ID
PLAN_ID=my-feature

使用场景与人群

适用场景：

  • 多天或跨周的大型项目（从零搭建项目、复杂重构、调研类任务）
  • 需要在崩溃、/clear、上下文压缩后恢复的长流程
  • 多 Agent 协作——orchestrator + worker 共享同一份规划文件
  • 需要确定性完成门控（gated mode）的高风险部署任务
  • 想让 Agent 真正”按计划行事”而不是随机发挥

目标用户：

  • Claude Code / Codex / Cursor 深度用户，尤其是经常处理复杂任务的开发者
  • AI Agent 系统工程师（Multi-Agent 编排、记忆工程方向）
  • 独立开发者 / 极客，用 AI 编程工具做长周期产品开发
  • 对 Manus-style workflow 有兴趣、想复制”持久化规划”能力的团队

不需要用的场景： 简单单文件修改、查资料、快速问答——Skill 自己也说了：这些跳过。

输入与输出案例

案例 1：多天项目从 /clear 恢复

用户：/plan 实现一个 Todo App，包含用户注册、登录、任务 CRUD

Agent 动作：
- 创建 task_plan.md，内含 Phase 1-4（架构设计、注册登录、数据层、CRUD UI）
- 执行 Phase 1，完成后 check off
- 执行 Phase 2，完成后 check off

用户：/clear

Agent 钩子自动触发：
- 重新读取 task_plan.md → 看到 Phase 1 & 2 已完成
- 继续从 Phase 3 开始执行，无需重新了解项目背景

案例 2：多 Agent 协作

Orchestrator Agent（Claude Code）：
- 拥有 task_plan.md 写入权限
- 按阶段分配任务给 Worker Agent

Worker Agent（Codex）：
- 读取 task_plan.md 获取当前阶段
- 将 progress.md 追加到 ledger-.jsonl
- findings.md 记录调研发现

最终：Orchestrator 读取所有 ledger，验证所有 phase 完成，发布 Stop

输出文档示例（task_plan.md）

# Task Plan: Todo App REST API

## Phase 1: 架构设计 ✅
- [x] 选择框架 (Express + TypeScript)
- [x] 设计数据库 schema

## Phase 2: 认证模块 🔄
- [x] 用户注册 /login /logout
- [ ] JWT token 刷新逻辑

## Phase 3: 任务 CRUD
- [ ] POST /tasks
- [ ] GET /tasks
- [ ] PUT /tasks/:id
- [ ] DELETE /tasks/:id

## Phase 4: 前端 UI
- [ ] React 任务列表
- [ ] 登录态管理

planning-with-files 本质上是给 AI Agent 装了一块”外置硬盘”——把昙花一现的上下文规划变成可持久、可恢复、可审计的 Markdown 文件。无论你是独立开发者在做一个跨周项目，还是在构建多 Agent 协作系统，这个 Skill 都几乎是可以直接加入技能库的”持久化规划层”。安装一行命令，值得一试。

GitHub: https://github.com/OthmanAdi/planning-with-files

评论区

0 条评论

登录后可评论。

Skill超级捕获手 24 阅读