/ 目录 / 演练场 / planning-with-files
● 社区 OthmanAdi ⚡ 即开即用

planning-with-files

作者 OthmanAdi · OthmanAdi/planning-with-files

强制 Claude 使用基于磁盘的 Markdown 文件作为持久化内存——task_plan.md、findings.md、progress.md——而不是在上下文重置时丢失状态。

一个实现 Manus AI 3 文件规划模式的 Claude Code 技能。安装后,Claude 会在开始多步骤工作前自动写入 task_plan.md,将发现记录到 findings.md,并在整个会话中更新 progress.md。基准测试显示在多步骤任务上通过率为 96.7%,相比之下无技能为 6.7%。最适合跨越 3 步或更多工具调用的工作。

为什么要用

核心特性

实时演示

实际使用效果

planning-with-files-skill.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "planning-with-files-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/OthmanAdi/planning-with-files",
        "~/.claude/skills/planning-with-files"
      ],
      "_inferred": true
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "planning-with-files-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/OthmanAdi/planning-with-files",
        "~/.claude/skills/planning-with-files"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "planning-with-files-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/OthmanAdi/planning-with-files",
        "~/.claude/skills/planning-with-files"
      ],
      "_inferred": true
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "planning-with-files-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/OthmanAdi/planning-with-files",
        "~/.claude/skills/planning-with-files"
      ],
      "_inferred": true
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "planning-with-files-skill",
      "command": "git",
      "args": [
        "clone",
        "https://github.com/OthmanAdi/planning-with-files",
        "~/.claude/skills/planning-with-files"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "planning-with-files-skill": {
      "command": {
        "path": "git",
        "args": [
          "clone",
          "https://github.com/OthmanAdi/planning-with-files",
          "~/.claude/skills/planning-with-files"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add planning-with-files-skill -- git clone https://github.com/OthmanAdi/planning-with-files ~/.claude/skills/planning-with-files

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: planning-with-files

运行多天重构而不失线索

👤 使用 Claude Code 进行迁移或大型重构的工程师 ⏱ ~30 min intermediate

何时使用: 你正在分解单体应用、迁移框架或进行任何跨越多个会话的工作。

前置条件
  • 技能克隆到 ~/.claude/skills/planning-with-files — git clone https://github.com/OthmanAdi/planning-with-files ~/.claude/skills/planning-with-files
步骤
  1. 使用技能明确启动工作
    我们正在将身份验证模块从 JWT 迁移到会话 Cookie。在你开始之前,使用 planning-with-files 技能来规划这一点。✓ 已复制
    → Claude 在接触代码前用阶段编写 task_plan.md
  2. 让 Claude 运行;跨天暂停和恢复
    从我们停下的地方继续——阅读 progress.md 并继续。✓ 已复制
    → Claude 重新阅读计划,确切知道下一阶段是什么
  3. 查看 findings.md 以发现意外发现
    总结 findings.md——有什么改变了原始计划吗?✓ 已复制
    → 否则会丢失的发现列表

结果: 一个能在上下文重置中继续进行的重构,且拥有完整的可审查审计跟踪。

注意事项
  • 技能被调用进行琐碎的单行编辑,增加开销 — 告诉 Claude 'skip planning-with-files, this is a one-shot fix'
搭配使用: filesystem · git

使用持久化发现文档进行研究调查

👤 任何使用 Claude 进行多源研究的人 ⏱ ~45 min beginner

何时使用: 你将要求 Claude 从许多来源收集信息并进行综合。

步骤
  1. 从研究问题开始
    研究现代限流器如何处理突发流量。使用 planning-with-files——我希望 findings.md 在会话中逐步充实。✓ 已复制
    → Claude 在搜索时逐步写入 findings.md
  2. 在最后要求进行综合
    现在将 findings.md 综合成 1 页简报。✓ 已复制
    → 基于持久化笔记的简报,而不是幻想的内容

结果: 一个你可以重新使用的发现文档和有其支持的简报。

注意事项
  • findings.md 被噪音淹没 — 指示 Claude 在阶段边界处清理,只保留关键信息
搭配使用: firecrawl · fetch

组合

与其他 MCP 搭配,撬动十倍杠杆

planning-with-files-skill + filesystem

技能写入 markdown 文件;filesystem MCP 让 Claude 也能在同一会话中编辑代码

使用 planning-with-files 进行规划,然后通过 filesystem 将修复应用于仓库。✓ 已复制
planning-with-files-skill + git

在阶段边界处提交 progress.md 和 findings.md,这样你就可以在多台机器上留下持久化的跟踪

阶段结束——使用总结已完成工作的消息提交 3 个规划文件。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
create_plan task description 任何具有 3 个或更多步骤的任务的开始 0 — local file write
log_finding discovery text 每当研究发现值得记住的东西时 0
update_progress step completed 在每次重要的工具调用或阶段之后 0
resume_session none 同一工作目录中任何后续会话的开始 0

成本与限制

运行它的成本

API 配额
每次调用 Token 数
适度——3 个文件在重新读取时消耗 token,通常每个文件不到 2k
费用
免费——技能纯粹是提示和钩子脚本
提示
让 Claude 定期清理 progress.md,防止长项目中无限增长。

安全

权限、密钥、影响范围

凭据存储: 无凭据——技能纯粹是提示和本地文件操作
数据出站: 无——所有状态都保留在工作目录中的你的磁盘上

故障排查

常见错误与修复

Claude 忽略了技能并且没有创建 task_plan.md

在你的提示中通过名称引用它:'use the planning-with-files skill'。确认克隆已落地在 ~/.claude/skills/planning-with-files。

验证: ls ~/.claude/skills/planning-with-files/SKILL.md
钩子在工具调用之间没有触发

检查 SKILL.md 的前置信息是否完整;如果克隆不完整,请重新安装。

验证: head ~/.claude/skills/planning-with-files/SKILL.md
3 个文件意外被提交到 git

将 task_plan.md、findings.md、progress.md 添加到 .gitignore。

验证: git check-ignore task_plan.md

替代方案

planning-with-files 对比其他方案

替代方案何时用它替代权衡
skillforge你想要一个创建其他技能的技能,而不仅仅是规划不同的目标——skillforge 构建技能;planning-with-files 运行任务
Native TodoWrite tool轻量级的上下文内待办事项就足够了,你不需要跨会话持久化免费但在上下文重置时消失

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills