planning-with-files 是 OthmanAdi 维护的 AI 编程 Agent 规划 Skill，解决的是长任务里“计划只停在聊天窗口，一清上下文就断线”的问题。它把执行状态写到项目目录的 task_plan.md、findings.md、progress.md，Agent 每次继续前都能重新读计划、发现和进度。适合多步骤开发、研究整理、批量改造、跨会话排查；简单问答或一次性小改动不用上它，文件反而会显得重。

它把哪些信息落到文件里

官方 SKILL.md 写得很直接：task_plan.md 放阶段、状态和决策；findings.md 放研究发现；progress.md 放会话日志、测试结果和已做动作。这个设计的日常影响很明显：你不必在新一轮提示词里复述所有背景，只要让 Agent 先读三份文件，再看 Git Diff，就能知道自己停在哪一步。

什么时候值得使用

它不是记忆库，也不是简历式待办清单。它更像给 Agent 放在项目根目录的施工日志：目标、阶段、错误和修复路线都能被版本管理看到。Codex、Claude Code、Cursor、OpenCode 等支持 Skill 标准的工具都能按各自目录接入，具体命令以官方 README 和对应 docs 为准。

落地时别把三份文件放进 Skill 安装目录，官方说明要求它们留在项目根目录。这样 Git Diff 能看到计划是否跟代码同步，团队成员也能判断 Agent 改动是不是按 phase 推进。若计划文件只创建不更新，它就退化成摆设；每完成一段功能、跑完一轮测试、遇到一次报错，都要把结果写回对应文件。

如果你已经有普通 TODO，也不用二选一。TODO 管“今天做什么”，planning-with-files 管“为什么这么做、做到哪、哪些路走不通”。这层记录越清楚，换模型、换窗口、换人接手时越不容易把旧问题重新踩一遍。

判断清单

• 任务超过 3 个步骤，或预计会调用多次工具。
• 中途可能 /clear、压缩上下文、换终端或换 Agent。
• 需要把失败尝试、测试结果和文件改动留给下一轮。
• 希望用 Git Diff 检查计划文件有没有被同步更新。