planning-with-files by oimiragieo/agent-studio
npx skills add https://github.com/oimiragieo/agent-studio --skill planning-with-files像 Manus(被 Meta 以 20 亿美元收购的 AI 智能体)一样工作:使用持久的 Markdown 文件作为你的“磁盘工作记忆”。
Context Window = RAM(易失,有限)
Filesystem = Disk(持久,无限)
→ 任何重要的内容都要写入磁盘。
对于每个复杂任务,在你的项目目录中创建三个文件:
task_plan.md → 跟踪阶段和进度
findings.md → 存储研究和发现
progress.md → 会话日志和测试结果
模板位于: .claude/templates/planning/
适用于:
不适用于:
这些规则模拟钩子以确保正确的工作流程:
必须 在进行任何其他工作之前首先创建所有三个文件:
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
task_plan.mdfindings.mdprogress.md原因: 没有规划文件,在超过 50 次工具调用后你会忘记目标。
必须 在以下操作前重新阅读 task_plan.md:
方法: 使用 Read 工具在你的上下文中刷新计划。
原因: 这使目标保持在你的注意力窗口中(Manus 的“注意力操控”)。
必须 在以下操作后立即更新状态:
方法: 编辑 task_plan.md 以更新阶段状态:
- **Status:** pending → in_progress → complete
原因: 跟踪进度,防止忘记已完成的工作。
必须 验证完成情况:
complete原因: 防止因工作缺失而过早完成。
没有 task_plan.md 绝不开始复杂任务。没有商量余地。
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- **Status:** in_progress
“每进行 2 次查看/浏览器/搜索操作后,立即将关键发现保存到 findings.md。”
这可以防止视觉/多模态信息丢失。
## Visual/Browser Findings
- Screenshot shows login form with email and password fields
- API documentation indicates JSON response format
在做出重大决策前,阅读计划文件。这使目标保持在你的注意力窗口中。
# Before implementing a feature:
Read tool → task_plan.md
# Now proceed with implementation
完成任何阶段后:
pending → in_progress → complete ## Errors Encountered
| Error | Attempt | Resolution |
| ----------------- | ------- | ---------------------- |
| FileNotFoundError | 1 | Created default config |
每个错误都要记录在计划文件中。这可以积累知识并防止重复。
if action_failed:
next_action != same_action
记录你尝试过的内容。改变方法。
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
| 文件 | 用途 | 何时更新 |
|---|---|---|
task_plan.md | 阶段、进度、决策 | 每个阶段后 |
findings.md | 研究、发现 | 任何发现后 |
progress.md | 会话日志、测试结果 | 整个会话期间 |
| 情况 | 操作 | 原因 |
|---|---|---|
| 刚写完文件 | 不要读 | 内容仍在上下文中 |
| 查看了图像/PDF | 立即写入发现 | 多模态 → 在丢失前转为文本 |
| 浏览器返回数据 | 写入文件 | 截图不会持久化 |
| 开始新阶段 | 阅读计划/发现 | 如果上下文陈旧则重新定位 |
| 发生错误 | 阅读相关文件 | 需要当前状态来修复 |
| 中断后恢复 | 阅读所有规划文件 | 恢复状态 |
如果你能回答这些问题,说明你的上下文管理很扎实:
| 问题 | 答案来源 |
|---|---|
| 我在哪里? | task_plan.md 中的当前阶段 |
| 我要去哪里? | 剩余阶段 |
| 目标是什么? | 计划中的目标陈述 |
| 我学到了什么? | findings.md |
| 我做了什么? | progress.md |
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending
### Phase 5: Delivery
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending
## Key Questions
1. [Question to answer]
2. [Question to answer]
## Decisions Made
| Decision | Rationale |
| -------- | --------- |
| | |
## Errors Encountered
| Error | Attempt | Resolution |
| ----- | ------- | ---------- |
| | 1 | |
# Findings & Decisions
## Requirements
_Add requirements captured from user request here._
## Research Findings
_Document key discoveries during exploration here._
## Technical Decisions
_Record decisions made with rationale._
| Decision | Rationale |
| -------- | --------- |
| | |
## Issues Encountered
_Document errors and how they were resolved._
| Issue | Resolution |
| ----- | ---------- |
| | |
## Resources
_Add URLs, file paths, and API references here._
## Visual/Browser Findings
_CRITICAL: Update after every 2 view/browser operations._
# Progress Log
## Session: [DATE]
### Phase 1: [Title]
- **Status:** in_progress
- **Started:** [timestamp]
- Actions taken:
- Files created/modified:
## Test Results
| Test | Input | Expected | Actual | Status |
| ---- | ----- | -------- | ------ | ------ |
| | | | | |
## Error Log
| Timestamp | Error | Attempt | Resolution |
| --------- | ----- | ------- | ---------- |
| | | 1 | |
## 5-Question Reboot Check
| Question | Answer |
| -------------------- | ---------------- |
| Where am I? | Phase X |
| Where am I going? | Remaining phases |
| What's the goal? | [goal statement] |
| What have I learned? | See findings.md |
| What have I done? | See above |
task_plan.md、findings.md 和 progress.md —— 文件系统内存能在上下文重置后存活,工作内存则不能。task_plan.md —— 上下文窗口是易失的,文件是持久存在的。findings.md —— 视觉上下文一旦离开注意力窗口就无法检索。complete 且所有交付成果都已存在于进度文件中的情况下标记任务完成。| 反模式 | 失败原因 | 正确方法 |
|---|---|---|
| 使用会话任务工具进行持久化 | 内存中的任务跟踪是易失的;上下文重置时会丢失 | 在磁盘上创建 task_plan.md 文件 —— 能在重置后存活 |
| 陈述一次目标后就忘记 | 上下文被填满;没有锚定目标会漂移 | 在每次重大决策前重新阅读计划文件 |
| 隐藏错误并静默重试 | 静默重试会无限重复相同的失败 | 将每个错误连同尝试次数记录到计划文件中 |
| 将所有研究塞进上下文 | 上下文窗口被填满;较早的内容会丢失 | 将大量内容和发现存储在 findings.md 中 |
| 没有计划就开始执行 | 未定义的范围导致工作浪费和步骤遗漏 | 在进行任何操作之前首先创建所有三个规划文件 |
| 原则 | 实现 |
|---|---|
| 文件系统即内存 | 存储在文件中,而非上下文中 |
| 注意力操控 | 决策前重新阅读计划 |
| 错误持久化 | 将失败记录在计划文件中 |
| 目标跟踪 | 复选框显示进度 |
| 完成验证 | 在停止前检查所有阶段 |
记住: 你预先收集并写入磁盘的上下文越多,你的执行效果就越好。文件是你的持久内存。
每周安装数
68
仓库
GitHub 星标数
23
首次出现
2026年2月8日
安全审计
安装于
gemini-cli67
github-copilot67
opencode67
codex67
amp66
cursor66
Work like Manus (the $2B AI agent Meta acquired): Use persistent markdown files as your "working memory on disk."
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
For every complex task, create THREE files in your project directory:
task_plan.md → Track phases and progress
findings.md → Store research and findings
progress.md → Session log and test results
Templates are available at: .claude/templates/planning/
Use for:
Skip for:
These rules simulate hooks to ensure proper workflow:
MUST create all three files FIRST before any other work:
task_plan.md using the templatefindings.md using the templateprogress.md using the templateWhy: Without planning files, you'll forget goals after 50+ tool calls.
MUST re-read task_plan.md before:
How: Use the Read tool to refresh the plan in your context.
Why: This keeps goals fresh in your attention window (Manus's "attention manipulation").
MUST update status immediately after:
How: Edit task_plan.md to update phase status:
- **Status:** pending → in_progress → complete
Why: Tracks progress and prevents losing track of what's done.
MUST verify completion:
completeWhy: Prevents premature completion with missing work.
Never start a complex task without task_plan.md. Non-negotiable.
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- **Status:** in_progress
"After every 2 view/browser/search operations, IMMEDIATELY save key findings to findings.md."
This prevents visual/multimodal information from being lost.
## Visual/Browser Findings
- Screenshot shows login form with email and password fields
- API documentation indicates JSON response format
Before major decisions, read the plan file. This keeps goals in your attention window.
# Before implementing a feature:
Read tool → task_plan.md
# Now proceed with implementation
After completing any phase:
Mark phase status: pending → in_progress → complete
Log any errors encountered
Note files created/modified
| Error | Attempt | Resolution |
|---|---|---|
| FileNotFoundError | 1 | Created default config |
Every error goes in the plan file. This builds knowledge and prevents repetition.
if action_failed:
next_action != same_action
Track what you tried. Mutate the approach.
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
| 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 |
| 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 |
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: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending
### Phase 5: Delivery
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending
## Key Questions
1. [Question to answer]
2. [Question to answer]
## Decisions Made
| Decision | Rationale |
| -------- | --------- |
| | |
## Errors Encountered
| Error | Attempt | Resolution |
| ----- | ------- | ---------- |
| | 1 | |
# Findings & Decisions
## Requirements
_Add requirements captured from user request here._
## Research Findings
_Document key discoveries during exploration here._
## Technical Decisions
_Record decisions made with rationale._
| Decision | Rationale |
| -------- | --------- |
| | |
## Issues Encountered
_Document errors and how they were resolved._
| Issue | Resolution |
| ----- | ---------- |
| | |
## Resources
_Add URLs, file paths, and API references here._
## Visual/Browser Findings
_CRITICAL: Update after every 2 view/browser operations._
# Progress Log
## Session: [DATE]
### Phase 1: [Title]
- **Status:** in_progress
- **Started:** [timestamp]
- Actions taken:
- Files created/modified:
## Test Results
| Test | Input | Expected | Actual | Status |
| ---- | ----- | -------- | ------ | ------ |
| | | | | |
## Error Log
| Timestamp | Error | Attempt | Resolution |
| --------- | ----- | ------- | ---------- |
| | | 1 | |
## 5-Question Reboot Check
| Question | Answer |
| -------------------- | ---------------- |
| Where am I? | Phase X |
| Where am I going? | Remaining phases |
| What's the goal? | [goal statement] |
| What have I learned? | See findings.md |
| What have I done? | See above |
task_plan.md, findings.md, and progress.md before starting any complex task — filesystem memory survives context resets, working memory does not.task_plan.md before making major decisions — context windows are volatile, files persist indefinitely.findings.md immediately after capture — visual context cannot be retrieved once it leaves the attention window.complete and all deliverables are present in the progress file.| Anti-Pattern | Why It Fails | Correct Approach |
|---|---|---|
| Using session task tools for persistence | In-memory task tracking is volatile; lost on context reset | Create task_plan.md file on disk — survives resets |
| Stating goals once and forgetting them | Context fills; goals drift without anchoring | Re-read plan file before every major decision |
| Hiding errors and retrying silently | Silent retries repeat the same failure endlessly | Log every error to plan file with attempt count |
| Stuffing all research into context | Context window fills; earlier content gets lost | Store large content and discoveries in findings.md |
| Starting execution without a plan | Undefined scope leads to wasted work and missed steps | Create all three planning files FIRST before any action |
| Principle | Implementation |
|---|---|
| Filesystem as memory | Store in files, not context |
| Attention manipulation | Re-read plan before decisions |
| Error persistence | Log failures in plan file |
| Goal tracking | Checkboxes show progress |
| Completion verification | Check all phases before stopping |
Remember: The more context you gather upfront and write to disk, the better your execution will be. Files are your persistent memory.
Weekly Installs
68
Repository
GitHub Stars
23
First Seen
Feb 8, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
gemini-cli67
github-copilot67
opencode67
codex67
amp66
cursor66
AI 代码实施计划编写技能 | 自动化开发任务分解与 TDD 流程规划工具
50,900 周安装