planning-with-files

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Planning with Files Skill

Planning with Files 技能

Operator Context

操作上下文

This skill operates as an operator for file-based planning workflows, configuring Claude's behavior for persistent, structured task execution. It implements the External Memory architectural pattern — store on disk, re-read to maintain focus, update after each action — with Context Engineering principles from Manus-style agent design.

本技能作为基于文件的规划工作流的操作器，配置Claude的行为以实现持久化、结构化的任务执行。它采用**外部内存（External Memory）架构模式——将内容存储在磁盘上，重新读取以保持专注，每次操作后更新——同时遵循Manus风格Agent设计中的上下文工程（Context Engineering）**原则。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终适用）

CLAUDE.md Compliance: Read and follow repository CLAUDE.md before starting any planned work
Over-Engineering Prevention: Plan only the phases needed. No speculative phases, no "future-proofing" empty sections
Plan Before Execute: NEVER start complex work without creating
```
task_plan.md
```
first
Re-Read Before Decide: Read plan file before every major decision to combat context drift
Update After Act: Mark phases complete and update status immediately after each phase
Store, Don't Stuff: Large outputs go to files, not context. Keep only file paths in working memory

CLAUDE.md 合规性：在开始任何规划工作前，阅读并遵循仓库中的CLAUDE.md文件
避免过度设计：仅规划所需的阶段。不设置推测性阶段，不预留“面向未来”的空章节
先规划后执行：在未创建
```
task_plan.md
```
之前，绝不能启动复杂工作
决策前重读：在每次重大决策前，阅读规划文件以避免上下文漂移
操作后更新：完成每个阶段后立即标记阶段为已完成并更新状态
存储而非塞入上下文：大型输出内容存入文件，而非上下文。仅在工作记忆中保留文件路径

Default Behaviors (ON unless disabled)

默认行为（除非禁用否则启用）

3-File Pattern: Create
```
task_plan.md
```
,
```
notes.md
```
, and deliverable file for non-trivial tasks
Error Logging: Record all errors in the "Errors Encountered" section of plan file
Phase Checkboxes: Use
```
- [ ]
```
/
```
- [x]
```
for phase tracking
Status Line: Maintain a "Currently in Phase X" status at bottom of plan
Findings Synthesis: Consolidate research notes into categorized findings before generating deliverables
Cleanup at Completion: Remove temporary scratch files, keep plan and deliverable

三文件模式：对于非琐碎任务，创建
```
task_plan.md
```
、
```
notes.md
```
和交付文件
错误日志记录：在规划文件的“遇到的错误”部分记录所有错误
阶段复选框：使用
```
- [ ]
```
/
```
- [x]
```
来跟踪阶段进度
状态行：在规划文件底部维护“当前处于第X阶段”的状态信息
研究结果整合：在生成交付成果前，将研究笔记整理为分类化的结果
完成后清理：删除临时草稿文件，保留规划文件和交付成果

Optional Behaviors (OFF unless enabled)

可选行为（除非启用否则禁用）

Timestamp Entries: Add
```
[YYYY-MM-DD]
```
timestamps to errors and decisions
Git Integration: Create commits at phase boundaries
Parallel Research: Launch multiple search queries simultaneously in research phase

时间戳条目：为错误和决策添加
```
[YYYY-MM-DD]
```
时间戳
Git集成：在阶段节点创建提交记录
并行调研：在调研阶段同时发起多个搜索查询

What This Skill CAN Do

本技能可实现的功能

Structure complex tasks into trackable phases with file-based persistence
Maintain focus across long sessions by re-reading goals into attention window
Store and synthesize research findings across multiple sources
Recover from context drift by grounding decisions in written plans
Preserve failure traces for error recovery and institutional knowledge

将复杂任务结构化，通过基于文件的持久化方式实现可跟踪的阶段管理
通过重新读取目标来维持长会话中的专注度
存储并整合来自多个来源的研究结果
通过以书面规划为依据制定决策，从上下文漂移中恢复
保留失败痕迹，用于错误恢复和积累机构知识

What This Skill CANNOT Do

本技能无法实现的功能

Replace domain-specific skills (use systematic-debugging for bugs, systematic-refactoring for refactoring)
Execute without a written plan for complex tasks
Store sensitive data (credentials, tokens) in plan files
Skip the re-read step before major decisions

替代特定领域技能（调试问题请使用systematic-debugging，重构请使用systematic-refactoring）
在无书面规划的情况下执行复杂任务
在规划文件中存储敏感数据（凭证、令牌等）
跳过重大决策前的重读步骤

Instructions

使用说明

Phase 1: CREATE PLAN

阶段1：创建规划

Goal: Establish written plan before any execution begins.

Step 1: Assess complexity

Determine if planning is needed:

3+ steps or phases required → Plan needed
Research or information gathering involved → Plan needed
Task spans multiple files or systems → Plan needed
Simple lookup or single edit → Skip planning

Step 2: Create
task_plan.md

markdown

undefined

目标：在执行任何操作前，建立书面规划。

步骤1：评估复杂度

判断是否需要规划：

需要3个及以上步骤或阶段 → 需要规划
涉及调研或信息收集 → 需要规划
任务跨多个文件或系统 → 需要规划
简单查询或单文件编辑 → 跳过规划

步骤2：创建
task_plan.md

markdown

undefined

Task Plan: [Brief Description]

任务规划：[简要描述]

Goal

目标

[One sentence describing the end state]

[一句话描述最终状态]

Phases

阶段

Key Questions

关键问题

[Question to answer before proceeding]

[执行前需要回答的问题]

Decisions Made

已做决策

[决策内容]：[决策依据]

Errors Encountered

遇到的错误

[错误内容]：[解决方法]

Status

状态

Currently in Phase 1 - Creating plan


**Gate**: `task_plan.md` exists with goal, phases, and key questions defined. Proceed only when gate passes.

当前处于阶段1 - 创建规划


**准入条件**：`task_plan.md`已存在，且包含目标、阶段和关键问题。仅当满足条件时才可进入下一阶段。

Phase 2: RESEARCH AND GATHER

阶段2：调研与信息收集

Goal: Collect all information needed before execution.

Step 1: Re-read plan

Read

task_plan.md

to refresh goals in attention window. This is mandatory, not optional.

Step 2: Gather information

Search, read, explore. Store findings in

notes.md

markdown

undefined

目标：收集执行所需的所有信息。

步骤1：重读规划

阅读

task_plan.md

以重新聚焦目标。此步骤为强制性操作，不可省略。

步骤2：收集信息

进行搜索、阅读、探索。将研究结果存入

notes.md

：

markdown

undefined

Notes: [Topic]

笔记：[主题]

Sources

来源

Source 1: [Name]

来源1：[名称]

Key points:
- [Finding]
- [Finding]

关键点：
- [研究结果]
- [研究结果]

Synthesized Findings

整合后的研究结果

[Category]

[分类]

[Finding with context]


**Step 3: Update plan**

Mark Phase 2 complete. Log any decisions made. Update status line.

**Gate**: All key questions from Phase 1 answered. Findings stored in `notes.md`. Proceed only when gate passes.

[带上下文的研究结果]


**步骤3：更新规划**

标记阶段2为已完成。记录已做出的决策。更新状态行。

**准入条件**：阶段1的所有关键问题均已得到解答。研究结果已存入`notes.md`。仅当满足条件时才可进入下一阶段。

Phase 3: EXECUTE

阶段3：执行

Goal: Build the deliverable using gathered information.

Step 1: Re-read plan and notes

Read

task_plan.md

then

notes.md

. Both reads are mandatory before generating output.

Step 2: Create deliverable

Build the output artifact. Reference notes for accuracy. Write to the deliverable file.

Step 3: Update plan

Mark Phase 3 complete. Log any errors encountered during execution.

Gate: Deliverable file exists and addresses the goal stated in the plan. Proceed only when gate passes.

目标：利用收集到的信息生成交付成果。

步骤1：重读规划与笔记

先阅读

task_plan.md

，再阅读

notes.md

。在生成输出前，这两次阅读均为强制性操作。

步骤2：创建交付成果

构建输出工件。参考笔记以确保准确性。写入交付文件。

步骤3：更新规划

标记阶段3为已完成。记录执行过程中遇到的所有错误。

准入条件：交付文件已存在，且符合规划中陈述的目标。仅当满足条件时才可进入下一阶段。

Phase 4: VERIFY AND DELIVER

阶段4：验证与交付

Goal: Confirm deliverable meets the plan's stated goal.

Step 1: Re-read plan one final time

Compare deliverable against original goal and key questions. Every question should be addressed.

Step 2: Verify completeness

All phases marked
```
[x]
```
All key questions answered
Deliverable matches stated goal
Errors section documents any issues encountered

Step 3: Deliver and clean up

Present the deliverable. Remove temporary scratch files. Keep

task_plan.md

and deliverable as artifacts.

Gate: All verification checks pass. Deliverable is complete.

目标：确认交付成果符合规划中陈述的目标。

步骤1：最后一次重读规划

将交付成果与原始目标和关键问题进行对比。每个问题都应得到解答。

步骤2：验证完整性

所有阶段均标记为
```
[x]
```
所有关键问题均已解答
交付成果与陈述的目标一致
错误部分记录了所有遇到的问题

步骤3：交付与清理

提交交付成果。删除临时草稿文件。保留

task_plan.md

和交付成果作为工件。

准入条件：所有验证检查均通过。交付成果已完成。

Examples

示例

Example 1: Research Task

示例1：调研任务

User says: "Research morning exercise benefits and write a summary" Actions:

Create
```
task_plan.md
```
with goal and 4 phases (CREATE PLAN)
Search sources, store findings in
```
notes.md
```
(RESEARCH)
Re-read notes, write
```
morning_exercise_summary.md
```
(EXECUTE)
Verify summary covers all key questions, deliver (VERIFY) Result: Structured summary grounded in documented research

用户需求：“调研晨练的益处并撰写一份总结” 操作步骤：

创建包含目标和4个阶段的
```
task_plan.md
```
（创建规划阶段）
搜索来源，将研究结果存入
```
notes.md
```
（调研阶段）
重读笔记，撰写
```
morning_exercise_summary.md
```
（执行阶段）
验证总结涵盖所有关键问题，交付成果（验证阶段）结果：基于有据可查的调研内容生成结构化总结

Example 2: Multi-File Refactoring Plan

示例2：多文件重构规划

User says: "Plan the migration from REST to GraphQL" Actions:

Create
```
task_plan.md
```
with migration phases (CREATE PLAN)
Inventory endpoints, dependencies, store in
```
notes.md
```
(RESEARCH)
Write
```
migration_plan.md
```
with ordered steps (EXECUTE)
Verify all endpoints covered, deliver plan (VERIFY) Result: Actionable migration plan with nothing missed

用户需求：“规划从REST到GraphQL的迁移工作” 操作步骤：

创建包含迁移阶段的
```
task_plan.md
```
（创建规划阶段）
盘点端点、依赖关系，存入
```
notes.md
```
（调研阶段）
撰写包含有序步骤的
```
migration_plan.md
```
（执行阶段）
验证所有端点均已覆盖，交付规划（验证阶段）结果：生成可执行的迁移规划，无遗漏内容

Error Handling

错误处理

Error: "Context Drift — Forgot Original Goal"

错误：“上下文漂移——忘记原始目标”

Cause: Too many tool calls without re-reading the plan Solution:

Immediately read
```
task_plan.md
```
Compare current work against stated goal
Correct course if diverged
Increase re-read frequency for remainder of task

原因：未重读规划的情况下进行了过多工具调用解决方案：

立即阅读
```
task_plan.md
```
将当前工作与陈述的目标进行对比
若偏离则调整方向
在剩余任务中增加重读频率

Error: "Plan Becomes Stale or Inaccurate"

错误：“规划过时或不准确”

Cause: New information invalidates original phases or decisions Solution:

Update plan with new information and revised phases
Log the change in Decisions Made with rationale
Continue from updated plan

原因：新信息使原始阶段或决策失效解决方案：

使用新信息更新规划并修订阶段
在“已做决策”部分记录变更及依据
根据更新后的规划继续执行

Error: "Notes File Too Large for Context"

错误：“笔记文件过大无法放入上下文”

Cause: Research phase produced more content than fits in attention window Solution:

Add a "Summary" section at top of
```
notes.md
```
with key takeaways
Reference specific sections by heading when needed
Read only relevant sections, not entire file

原因：调研阶段产生的内容超出了注意力窗口的容量解决方案：

在
```
notes.md
```
顶部添加“摘要”部分，包含关键要点
需要时通过标题引用特定章节
仅阅读相关章节，而非整个文件

Anti-Patterns

反模式

Anti-Pattern 1: Executing Without a Plan

反模式1：未规划即执行

What it looks like: Jumping straight into code or content without creating

task_plan.md

Why wrong: No way to track progress, detect drift, or verify completeness Do instead: Create plan first. Always. Even if it takes 30 seconds.

表现：未创建

task_plan.md

就直接开始编写代码或内容 问题所在：无法跟踪进度、检测漂移或验证完整性 正确做法：始终先创建规划。即使仅需30秒。

Anti-Pattern 2: Writing Plan but Never Re-Reading

反模式2：编写规划但从不重读

What it looks like: Creating

task_plan.md

then never opening it again Why wrong: Plan exists to combat context drift. Unread plans provide zero value. Do instead: Re-read before every major decision and phase transition.

表现：创建

task_plan.md

后再也不打开它 问题所在：规划的作用是防止上下文漂移。未被重读的规划毫无价值 正确做法：在每次重大决策和阶段转换前重读规划。

Anti-Pattern 3: Stuffing Context Instead of Storing

反模式3：塞入上下文而非存储到文件

What it looks like: Keeping all research findings in working memory instead of

notes.md

Why wrong: Context window fills up, earlier information gets pushed out Do instead: Write to files immediately. Read back only what you need.

表现：将所有研究结果保留在工作记忆中，而非存入

notes.md

问题所在：上下文是临时的，而文件是持久化的 正确做法：立即写入

notes.md

。

Anti-Pattern 4: Over-Planning Simple Tasks

反模式4：对简单任务过度规划

What it looks like: Creating 3 files and 8 phases for a single-file edit Why wrong: Planning overhead exceeds task complexity. Wastes time. Do instead: Use complexity check in Phase 1. Skip planning for simple tasks.

表现：为单文件编辑任务创建3个文件和8个阶段 问题所在：规划的开销超过了任务的复杂度，浪费时间 正确做法：先评估复杂度。对简单任务跳过规划。

References

参考资料

This skill uses these shared patterns:

Anti-Rationalization - Prevents shortcut rationalizations
Verification Checklist - Pre-completion checks
Gate Enforcement - Phase transition enforcement

本技能采用以下共享模式：

Anti-Rationalization - 防止找借口走捷径
Verification Checklist - 完成前检查
Gate Enforcement - 阶段转换强制检查

Domain-Specific Anti-Rationalization

特定领域的反合理化

Rationalization	Why It's Wrong	Required Action
"I remember the goal, no need to re-read"	Memory degrades after ~50 tool calls	Read `task_plan.md` before deciding
"Quick task, no plan needed"	Quick tasks become multi-step tasks	Assess complexity first
"Notes are in my context already"	Context is ephemeral, files are persistent	Write to `notes.md`
"Plan is mostly done, close enough"	Mostly ≠ Complete	Mark all phases [x] or explain why not

合理化借口	问题所在	要求操作
“我记得目标，不需要重读”	约50次工具调用后记忆会退化	决策前阅读 `task_plan.md`
“任务很快完成，不需要规划”	快速任务可能演变为多步骤任务	先评估复杂度
“笔记已经在我的上下文中了”	上下文是临时的，文件是持久化的	写入 `notes.md`
“规划差不多完成了，足够了”	差不多≠完成	标记所有阶段为[x]，或解释未完成的原因