task_plan.md
记录阶段、目标、状态、决策和错误，是任务执行的主控清单。
Persistent Planning Skill
Planning with Files 调研报告
这是一个面向 Claude Code、Codex 和多 IDE Agent 的文件化规划技能。它把有限上下文窗口中的目标、发现和进展落盘到 Markdown 文件，让长任务在清空上下文、压缩上下文或多轮工作后仍能恢复。
task_plan.md
findings.md
progress.md
hooks + attestation
1. 结论摘要
核心价值
把 Agent 的“工作记忆”从对话上下文迁移到项目文件：计划、研究发现、执行日志可被反复读取、修改、审计和提交，适合复杂研发、调研、迁移、修复和多阶段任务。
关键边界
它提升的是任务连续性，不是自动保证质量。计划文件也可能被污染、过期或泄露敏感信息，所以要配合 attestation、git diff、人工复核和敏感信息清理。
21,565GitHub stars，调研时 API 返回值
1,905forks
v2.38.1最新 release，2026-05-16
17+README 标注支持的平台/IDE
2. 当前状态
| 项目 | 观察 |
|---|---|
| 仓库 | OthmanAdi/planning-with-files，默认分支 master，MIT License。 |
| 定位 | README 描述为 Claude Code skill，实现 Manus 风格的 persistent markdown planning。 |
| 最新版本 | v2.38.1，修复 Claude Code skill picker 中 description 被 YAML 文档分隔符截断的问题，将 plan 数据分隔符从 --- 改为 ===。 |
| 语言 | 主要为 Python、Shell、PowerShell，说明它更像技能/钩子/脚本集合，不是传统应用。 |
| 平台 | 仓库包含 .claude-plugin、.codex、.cursor、.gemini、.opencode、.kiro、.pi 等适配目录。 |
3. 工作机制
1. 创建计划复杂任务开始前生成
task_plan.md、findings.md、progress.md。2. 读取上下文每次决策前重读计划，避免上下文窗口遗忘目标。
3. 工具前注入hooks 在用户消息或工具调用前注入计划片段和近期进展。
4. 执行后记录写入或执行后提醒更新进展、错误、产物和阶段状态。
5. 完成检查Stop hook 检查计划是否完成，不完整时提醒继续。
findings.md
记录调研发现、代码定位、外部来源和关键证据，避免重复搜索。
progress.md
记录每轮做了什么、测试结果、失败原因和下一步，便于 session recovery。
4. 安装与使用
Claude Code
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-filesCodex
Codex 集成包含 .codex/skills/planning-with-files/、.codex/hooks.json 和 hook 脚本。需要在 ~/.codex/config.toml 中启用 codex_hooks = true。官方文档说明当前 Codex hooks 在 Windows 上不可用。
适用提示词
“为这个迁移任务创建文件化计划，拆成阶段并在每阶段结束后更新 progress.md。”
“先读取 task_plan.md、findings.md、progress.md，再继续上次调研，不要重复已经完成的搜索。”
“执行前检查计划 attestation，如果 task_plan.md 被改过，先暂停并报告差异。”
“每两次搜索后把关键发现写入 findings.md，并在最终报告引用来源。”
5. 风险分析
计划文件注入
计划文件会被 hooks 注入给 Agent。若文件内混入“忽略规则、泄露密钥、执行删除”等指令，就可能成为 prompt injection 载体。v2.37+ 的 SHA-256 attestation 与 v2.38.1 的分隔符修复是重要缓解，但不能替代人工审查。
Hook 脚本执行
技能声明允许 Read Write Edit Bash Glob Grep，且生命周期 hooks 会执行 shell/PowerShell/Python 脚本。安装前应审查脚本，团队环境应通过代码审查合入。
敏感信息落盘
findings 和 progress 很容易记录 token、路径、客户名、日志、错误输出和内部 URL。它们位于项目目录，可能被 git add 或同步工具带走。
过度相信计划
文件化计划会让 Agent 更“坚定”，但旧计划可能已经不适配当前代码。恢复会话时必须结合 git diff、测试和最新用户指令重新校准。
控制建议
| 风险 | 建议 |
|---|---|
| prompt injection | 把计划内容视为数据，不允许计划文件覆盖系统/用户指令；启用 /plan-attest 或等价哈希确认。 |
| 泄露 | 把 task_plan.md、findings.md、progress.md 加入敏感信息扫描；不记录 raw token。 |
| hook 冲突 | Codex 全局 hooks 与项目 hooks 不要重复安装；已有 hooks.json 时手动 merge。 |
| 供应链 | 固定 release 版本，插件升级走 PR 审查，不直接覆盖全局配置。 |