planning-with-files

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Planning with Files

基于文件的规划

Work like Manus: Use persistent markdown files as your "working memory on disk."

像Manus一样工作：将持久化的Markdown文件作为你的「磁盘工作内存」。

FIRST: Check for Previous Session (v2.2.0)

第一步：检查之前的会话（v2.2.0）

Before starting work, check for unsynced context from a previous session:

bash

undefined

开始工作前，检查上一个会话中未同步的上下文：

bash

undefined

Linux/macOS

$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"


```powershell

$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"


```powershell

Windows PowerShell

& (Get-Command python -ErrorAction SilentlyContinue).Source "$env:USERPROFILE.claude\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

& (Get-Command python -ErrorAction SilentlyContinue).Source "$env:USERPROFILE.claude\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)


如果恢复报告显示存在未同步的上下文：
1. 运行 `git diff --stat` 查看实际的代码变更
2. 阅读当前的规划文件
3. 根据恢复内容和git diff更新规划文件
4. 然后再继续执行任务

Important: Where Files Go

重要提示：文件存放位置

Templates are in
```
${CLAUDE_PLUGIN_ROOT}/templates/
```
Your planning files go in your project directory

Location	What Goes There
Skill directory ( `${CLAUDE_PLUGIN_ROOT}/` )	Templates, scripts, reference docs
Your project directory	`task_plan.md` , `findings.md` , `progress.md`

模板文件位于
```
${CLAUDE_PLUGIN_ROOT}/templates/
```
你的规划文件要放在你的项目目录中

位置	存放内容
技能目录（ `${CLAUDE_PLUGIN_ROOT}/` ）	模板、脚本、参考文档
你的项目目录	`task_plan.md` 、 `findings.md` 、 `progress.md`

Quick Start

快速开始

Before ANY complex task:

Create
task_plan.md
— Use templates/task_plan.md as reference
Create
findings.md
— Use templates/findings.md as reference
Create
progress.md
— Use templates/progress.md as reference
Re-read plan before decisions — Refreshes goals in attention window
Update after each phase — Mark complete, log errors

Note: Planning files go in your project root, not the skill installation folder.

在执行任何复杂任务前：

创建
task_plan.md
— 参考templates/task_plan.md
创建
findings.md
— 参考templates/findings.md
创建
progress.md
— 参考templates/progress.md
做决策前重新阅读规划 — 刷新注意力窗口中的目标
每个阶段结束后更新文件 — 标记完成状态，记录错误

注意： 规划文件要放在你的项目根目录，而不是技能安装文件夹中。

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

文件	用途	更新时机
`task_plan.md`	阶段、进度、决策记录	每个阶段结束后
`findings.md`	研究成果、发现内容	任何发现之后
`progress.md`	会话日志、测试结果	会话全程

Critical Rules

关键规则

1. Create Plan First

1. 先创建规划

Never start a complex task without

task_plan.md

. Non-negotiable.

执行复杂任务前必须先创建

task_plan.md

，这是硬性要求。

2. The 2-Action Rule

2. 两操作规则

"After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."

This prevents visual/multimodal information from being lost.

“每完成2次查看/浏览/搜索操作后，立即将关键发现保存到文本文件中。”

这可以防止视觉/多模态信息丢失。

3. Read Before Decide

3. 先阅读再决策

Before major decisions, read the plan file. This keeps goals in your attention window.

做重大决策前，先阅读规划文件，确保目标始终在你的注意力窗口中。

4. Update After Act

4. 执行后更新

After completing any phase:

Mark phase status:
```
in_progress
```
→
```
complete
```
Log any errors encountered
Note files created/modified

完成任何阶段后：

更新阶段状态：
```
in_progress
```
→
```
complete
```
记录遇到的所有错误
记录创建/修改的文件

5. Log ALL Errors

5. 记录所有错误

Every error goes in the plan file. This builds knowledge and prevents repetition.

markdown

undefined

每个错误都要写入规划文件，这能积累经验并避免重复犯错。

markdown

undefined

Errors Encountered

遇到的错误

Error	Attempt	Resolution
FileNotFoundError	1	Created default config
API timeout	2	Added retry logic

undefined

错误	尝试次数	解决方案
FileNotFoundError	1	创建默认配置
API timeout	2	添加重试逻辑

undefined

6. Never Repeat Failures

6. 永不重复失败操作

if action_failed:
    next_action != same_action

Track what you tried. Mutate the approach.

if action_failed:
    next_action != same_action

记录你尝试过的方法，调整解决思路。

The 3-Strike Error Protocol

三次错误重试协议

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

场景	操作	原因
刚写完一个文件	不要读取	内容还在上下文中
查看了图片/PDF	立即写入发现内容	多模态信息要转成文本，避免丢失
浏览器返回数据	写入文件	截图无法持久保存
开始新阶段	阅读规划/发现文件	如果上下文已过期，重新定位
发生错误	阅读相关文件	需要当前状态来修复
间隔后恢复工作	阅读所有规划文件	恢复状态

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

如果你能回答这些问题，说明你的上下文管理做得很好：

问题	答案来源
我现在处于什么阶段？	task_plan.md中的当前阶段
我接下来要去哪里？	剩余的阶段
目标是什么？	规划中的目标说明
我学到了什么？	findings.md
我已经完成了什么？	progress.md

When to Use This Pattern

何时使用此模式

Use for:

Multi-step tasks (3+ steps)
Research tasks
Building/creating projects
Tasks spanning many tool calls
Anything requiring organization

Skip for:

Simple questions
Single-file edits
Quick lookups

适用场景：

多步骤任务（3步及以上）
研究任务
项目构建/创建
需要多次工具调用的任务
任何需要组织管理的任务

不适用场景：

简单问题
单文件编辑
快速查询

Templates

模板

Copy these templates to start:

templates/task_plan.md — Phase tracking
templates/findings.md — Research storage
templates/progress.md — Session logging

复制以下模板开始使用：

templates/task_plan.md — 阶段跟踪
templates/findings.md — 研究成果存储
templates/progress.md — 会话日志

Scripts

脚本

Helper scripts for automation:

```
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)

用于自动化的辅助脚本：

```
scripts/init-session.sh
```
— 初始化所有规划文件
```
scripts/check-complete.sh
```
— 验证所有阶段是否完成
```
scripts/session-catchup.py
```
— 从之前的会话中恢复上下文（v2.2.0）

Advanced Topics

高级主题

Manus Principles: See reference.md
Real Examples: See examples.md

Manus原则： 查看reference.md
实际示例： 查看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

不要做	应该做
用TodoWrite做持久化存储	创建task_plan.md文件
只声明一次目标就忘记	做决策前重新阅读规划
隐藏错误并默默重试	将错误记录到规划文件
把所有内容都塞进上下文	将大内容存储到文件中
立即开始执行任务	先创建规划文件
重复失败的操作	记录尝试过的方法，调整思路
在技能目录中创建文件	在你的项目目录中创建文件