planning-with-files 的核心思路是把上下文窗口视为易失且有限的 RAM，把文件系统视为持久且近乎无限的磁盘，凡重要信息都写入磁盘，因此用固定的三个 markdown 文件充当「磁盘上的工作记忆」。三个文件分工明确：task_plan.md 记录阶段、进度与决策，findings.md 存放研究与发现，progress.md 记录会话日志与测试结果。规划文件默认写在项目根目录，模板与脚本位于技能安装目录，二者不要混淆；未特别说明时不要写入项目根目录以外的位置。
使用方式上，先检查并读取已有的规划文件，再创建 task_plan.md、findings.md、progress.md（参考 templates/ 下的模板），做重大决策前重读计划，每完成一个阶段就更新状态、记录错误与改动文件。技能内置若干规则：没有 task_plan.md 就不开始复杂任务；每两次查看/浏览器/搜索操作后立即把关键发现写入文本文件；所有错误都记入计划文件；失败动作不重复，尝试改变方法，连续三次失败后升级给用户。会话恢复可运行 scripts/session-catchup.py（Linux/macOS 与 Windows PowerShell 命令不同），先查看 catchup 报告与 git diff --stat，再更新规划文件。
脚本方面提供 init-session.sh（带名称参数时在 .planning/YYYY-MM-DD-<slug>/ 下创建隔离计划，不带参数则在项目根写入 task_plan.md）、set-active-plan.sh、resolve-plan-dir.sh、check-complete.sh、session-catchup.py、attest-plan.sh/.ps1 等，支持同一仓库多任务并行。v2.38.0 起接入 Claude Code 的 PreCompact 钩子、/plan-goal 与 /plan-loop 斜杠命令，并提供 templates/loop.md 模板。
安全边界上，钩子注入的计划内容被包裹在 ---BEGIN PLAN DATA--- 与 ---END PLAN DATA--- 分隔符之间，视为结构化数据而非指令；可选用 /plan-attest 或 sh scripts/attest-plan.sh 对 task_plan.md 做 SHA-256 锁定，哈希不匹配时阻断注入。外部网页与 API 内容视为不可信，只写入 findings.md；具体收费、价格与更多平台细节暂未提供。