planning-with-files 是一个面向复杂、多步骤任务的持久化规划与进度管理 skill，核心思想是把 AI 在执行任务过程中产生的目标、计划、调研结果、技术决策、操作记录、测试结果和错误信息，从容易丢失的对话上下文中保存到项目目录中的 Markdown 文件里，从而让 AI 即使经历长时间工作、上下文压缩、会话中断或重新启动，也能够根据文件恢复任务状态并继续执行。这个 skill 通常会围绕 task_plan.md、findings.md 和 progress.md 三个文档展开工作，其中 task_plan.md 用于记录整个任务的最终目标、当前阶段、下一步行动、阶段划分、重要决策以及遇到的错误，是任务的总体路线图；findings.md 用于保存需求分析、网页或资料调研、技术发现、平台规则、参考链接、视觉观察结果以及决策依据，是任务的外部知识库；progress.md 则用于按照时间和阶段记录已经完成的具体操作、修改过的文件、测试过程、测试结果以及错误处理情况，是任务的执行日志。特别适合网站开发、软件项目、内容投放助手建设、论文或报告撰写、资料整理、竞品分析、数据处理以及任何需要多次工具调用和跨多个阶段完成的任务，而对于简单问答、短文本修改或一次性查询则没有必要启用。
0
评论 0
更多
登录后可点赞、收藏、评论和举报。
还没有评论，先发起一个具体问题。
Skill 内容与版本
planning-with-files
Manus-style persistent file-based planning for AI coding agents: keeps task_plan.md, findings.md, and progress.md on disk so work survives context loss and /clear. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Supports automatic session recovery after /clear.
# Windows PowerShell
python "$env:USERPROFILE\.codex\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)
If catchup report shows unsynced context: 1. Run `git diff --stat` to see actual code changes 2. Read current planning files 3. Update planning files based on catchup + git diff 4. Then proceed with task
Important: Where Files Go
**Templates** are in `~/.codex/skills/planning-with-files/templates/`
**Your planning files** go in **your project directory**
| Location | What Goes There | |----------|-----------------| | Skill directory (`~/.codex/skills/planning-with-files/`) | Templates, scripts, reference docs | | Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
Quick Start
Before ANY complex task:
1. **Create `task_plan.md`** — Use [templates/task_plan.md](templates/task_plan.md) as reference 2. **Create `findings.md`** — Use [templates/findings.md](templates/findings.md) as reference 3. **Create `progress.md`** — Use [templates/progress.md](templates/progress.md) as reference 4. **Re-read plan before decisions** — Refreshes goals in attention window 5. **Update after each phase** — Mark complete, log errors
> **Note:** Planning files go in your project root, not the skill installation folder.
The Core Pattern
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
File Purposes
| File | Purpose | When to Update | |------|---------|----------------| | `task_plan.md` | Phases, progress, decisions | After each phase | | `findings.md` | Research, discoveries | After ANY discovery | | `progress.md` | Session log, test results | Throughout session |
Critical Rules
1. Create Plan First
Never start a complex task without `task_plan.md`. Non-negotiable.
2. The 2-Action Rule
> "After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."
This prevents visual/multimodal information from being lost.
3. Read Before Decide
Before major decisions, read the plan file. This keeps goals in your attention window.
4. Update After Act
After completing any phase:
Mark phase status: `in_progress` → `complete`
Log any errors encountered
Note files created/modified
5. Log ALL Errors
Every error goes in the plan file. This builds knowledge and prevents repetition.
ATTEMPT 1: Diagnose & Fix
→ Read error carefully
→ Identify root cause
→ Apply targeted fix
ATTEMPT 2: Alternative Approach
→ Same error? Try different method
→ Different tool? Different library?
→ NEVER repeat exact same failing action
ATTEMPT 3: Broader Rethink
→ Question assumptions
→ Search for solutions
→ Consider updating the plan
AFTER 3 FAILURES: Escalate to User
→ Explain what you tried
→ Share the specific error
→ Ask for guidance
Read vs Write Decision Matrix
| Situation | Action | Reason | |-----------|--------|--------| | Just wrote a file | DON'T read | Content still in context | | Viewed image/PDF | Write findings NOW | Multimodal → text before lost | | Browser returned data | Write to file | Screenshots don't persist | | Starting new phase | Read plan/findings | Re-orient if context stale | | Error occurred | Read relevant file | Need current state to fix | | Resuming after gap | Read all planning files | Recover state |
The 5-Question Reboot Test
If you can answer these, your context management is solid:
| Question | Answer Source | |----------|---------------| | Where am I? | Current phase in task_plan.md | | Where am I going? | Remaining phases | | What's the goal? | Goal statement in plan | | What have I learned? | findings.md | | What have I done? | progress.md |
`scripts/init-session.sh` — Initialize all planning files
`scripts/check-complete.sh` — Verify all phases complete
`scripts/session-catchup.py` — Recover context from previous session (v2.2.0)
Advanced Topics
**Manus Principles:** See [references/reference.md](references/reference.md)
**Real Examples:** See [references/examples.md](references/examples.md)
Anti-Patterns
| Don't | Do Instead | |-------|------------| | Use TodoWrite for persistence | Create task_plan.md file | | State goals once and forget | Re-read plan before decisions | | Hide errors and retry silently | Log errors to plan file | | Stuff everything in context | Store large content in files | | Start executing immediately | Create plan file FIRST | | Repeat failed actions | Track attempts, mutate approach | | Create files in skill directory | Create files in your project |
还没有评论，先发起一个具体问题。