Back to Details

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文件作为你的「磁盘工作记忆」。

The Core Pattern

核心模式

Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)

Anything important gets written to disk.
Context Window = RAM (易失性，容量有限)
Filesystem = Disk (持久化，容量无限)

任何重要内容都要写入磁盘。

Quick Start

快速开始

Before ANY complex task:
  1. Create 
    task_plan.md
     - Use the template below
  2. Create 
    findings.md
     - For research and discoveries
  3. Create 
    progress.md
     - For session logging
  4. Re-read plan before decisions - Refreshes goals in attention window
  5. Update after each phase - Mark complete, log errors
在开始任何复杂任务之前：
  1. 创建
    task_plan.md
     - 使用下方模板
  2. 创建
    findings.md
     - 用于记录研究和发现内容
  3. 创建
    progress.md
     - 用于会话日志记录
  4. 做决策前重新阅读规划 - 刷新注意力窗口中的目标
  5. 每个阶段结束后更新文件 - 标记完成状态，记录错误

File Purposes

文件用途

FilePurposeWhen to Update
task_plan.md
Phases, progress, decisionsAfter each phase
findings.md
Research, discoveriesAfter ANY discovery
progress.md
Session log, test resultsThroughout 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

遇到的错误

ErrorAttemptResolution
FileNotFoundError1Created default config
API timeout2Added retry logic
undefined
错误尝试次数解决方法
FileNotFoundError1创建默认配置
API timeout2添加重试逻辑
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
尝试1：诊断与修复
  -> 仔细阅读错误信息
  -> 确定根本原因
  -> 应用针对性修复

尝试2：替代方案
  -> 仍出现相同错误？尝试不同方法
  -> 换用其他工具？其他库？
  -> 绝对不要重复完全相同的失败操作

尝试3：重新审视全局
  -> 质疑之前的假设
  -> 搜索解决方案
  -> 考虑更新规划

三次尝试后：向用户求助
  -> 说明你尝试过的方法
  -> 共享具体错误信息
  -> 请求指导

Read vs Write Decision Matrix

读取/写入决策矩阵

SituationActionReason
Just wrote a fileDON'T readContent still in context
Viewed image/PDFWrite findings NOWMultimodal -> text before lost
Browser returned dataWrite to fileScreenshots don't persist
Starting new phaseRead plan/findingsRe-orient if context stale
Error occurredRead relevant fileNeed current state to fix
Resuming after gapRead all planning filesRecover state
场景操作原因
刚写完一个文件不要读取内容仍在上下文窗口中
查看了图片/PDF立即写入发现多模态信息需转为文本后保存，防止丢失
浏览器返回数据写入文件截图无法持久化保存
启动新阶段阅读规划/发现文件若上下文已过期，重新定位方向
发生错误阅读相关文件需要当前状态来修复问题
间隔后恢复工作阅读所有规划文件恢复工作状态

The 5-Question Reboot Test

五问题重启测试

If you can answer these, your context management is solid:
QuestionAnswer 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

Templates

模板

task_plan.md Template

task_plan.md模板

markdown
undefined
markdown
undefined

Task Plan: [Task Name]

任务规划: [任务名称]

Goal

目标

[Clear statement of what we're trying to accomplish]
[清晰说明我们要完成的内容]

Phases

阶段划分

Phase 1: [Name]

阶段1: [名称]

  • Status: pending | in_progress | complete
  • Tasks:
    • Task 1
    • Task 2
  • 状态: pending（待开始）| in_progress（进行中）| complete（已完成）
  • 任务:
    • 任务1
    • 任务2

Phase 2: [Name]

阶段2: [名称]

  • Status: pending
  • Tasks:
    • Task 1
  • 状态: pending
  • 任务:
    • 任务1

Errors Encountered

遇到的错误

ErrorAttemptResolution
错误尝试次数解决方法

Decisions Made

已做决策

DecisionRationaleDate
决策理由日期

Files Modified

修改的文件

  • [file1.py] - [what changed]
undefined
  • [file1.py] - [修改内容]
undefined

findings.md Template

findings.md模板

markdown
undefined
markdown
undefined

Research Findings

研究发现

[Topic 1]

[主题1]

  • Key insight 1
  • Key insight 2
  • Source: [where found]
  • 关键见解1
  • 关键见解2
  • 来源: [获取位置]

[Topic 2]

[主题2]

  • Finding 1
  • Finding 2
undefined
  • 发现1
  • 发现2
undefined

progress.md Template

progress.md模板

markdown
undefined
markdown
undefined

Session Progress

会话进度

[Date/Time]

[日期/时间]

  • Started: [task]
  • Completed: [what]
  • Blocked on: [if any]
  • Next: [what's next]
undefined
  • 开始: [任务]
  • 完成: [已完成内容]
  • 阻塞原因: [如有]
  • 下一步: [接下来的任务]
undefined

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步及以上）
  • 研究任务
  • 构建/创建项目
  • 需要调用多次工具的任务
  • 任何需要组织管理的任务
不适用场景：
  • 简单问题
  • 单文件编辑
  • 快速查询

Anti-Patterns

反模式

Don'tDo Instead
Use TodoWrite for persistenceCreate task_plan.md file
State goals once and forgetRe-read plan before decisions
Hide errors and retry silentlyLog errors to plan file
Stuff everything in contextStore large content in files
Start executing immediatelyCreate plan file FIRST
Repeat failed actionsTrack attempts, mutate approach
不要做应该做
使用TodoWrite进行持久化记录创建task_plan.md文件
只陈述一次目标就遗忘做决策前重新阅读规划
隐藏错误并静默重试将错误记录到规划文件中
把所有内容塞进上下文窗口将大内容存储到文件中
立即开始执行任务先创建规划文件
重复失败的操作记录尝试过的方法，调整方案