Planning with Files：Manus 风格的上下文工程

仓库: https://github.com/OthmanAdi/planning-with-files | 版本: 2.1.2 | 语言: Markdown/Shell | 许可证: MIT

摘要

Planning with Files 是一个 Claude Code 插件/Skill，它将 Manus AI 的"上下文工程"（Context Engineering）方法论带入 Claude Code 工作流。核心思想简单而深刻：将上下文窗口视为 RAM（易失性、有限），将文件系统视为磁盘（持久化、无限）。通过三个 Markdown 文件（task_plan.md、findings.md、progress.md）构建"磁盘上的工作记忆"，配合 Hooks 机制实现自动化的注意力管理，解决了 AI Agent 在长任务中常见的目标漂移、错误重复等问题。

1. 项目概览

1.1 解决的问题

AI Agent（包括 Claude Code）在处理复杂任务时面临四大核心挑战：

问题	表现	后果
易失性记忆	TodoWrite 工具在上下文重置后丢失	任务状态无法持久化
目标漂移	50+ 次工具调用后忘记原始目标	偏离用户意图
隐藏错误	失败不被追踪，无声重试	同样的错误反复发生
上下文填塞	所有信息都塞入上下文窗口	Token 消耗大，效率低

这些问题在 2025 年 12 月 Meta 以 20 亿美元收购 Manus AI 后引起广泛关注——Manus 仅用 8 个月就实现了 1 亿美元收入，其核心秘诀就是上下文工程。

1.2 核心价值主张

"Markdown is my 'working memory' on disk." — Manus AI

项目提出的核心公式：

Context Window = RAM（易失性、有限）
Filesystem = Disk（持久化、无限）

→ 任何重要信息都写入磁盘

1.3 技术栈

组件	技术	用途
Skill 定义	SKILL.md (YAML frontmatter)	声明 Hooks、权限、元数据
模板	Markdown	三文件模式的结构化模板
自动化	Shell 脚本	初始化和完成检查
分发	Claude Plugin Marketplace	一键安装

2. 架构设计

2.1 整体架构图

mermaid

flowchart TB
    subgraph 用户项目目录
        TP[task_plan.md<br/>任务计划]
        FD[findings.md<br/>发现记录]
        PG[progress.md<br/>进度日志]
    end

    subgraph Claude Code
        CC[Claude Agent]
        HK[Hooks 系统]
    end

    subgraph Skill
        SM[SKILL.md]
        TPL[templates/]
        SCR[scripts/]
    end

    CC -->|执行工具| HK
    HK -->|PreToolUse| TP
    HK -->|PostToolUse| CC
    HK -->|Stop| SCR

    SM -->|定义| HK
    TPL -->|初始化| TP
    TPL -->|初始化| FD
    TPL -->|初始化| PG

    CC -->|读写| TP
    CC -->|读写| FD
    CC -->|读写| PG

2.2 核心模块说明

三文件模式

文件	职责	更新时机
`task_plan.md`	阶段追踪、决策记录、错误日志	完成阶段后
`findings.md`	研究发现、技术决策、资源链接	任何发现后
`progress.md`	会话日志、测试结果、详细错误	整个会话中

Hooks 机制

yaml

hooks:
  SessionStart:    # 会话开始时提示就绪
  PreToolUse:      # Write/Edit/Bash 前读取 task_plan.md
  PostToolUse:     # Write/Edit 后提醒更新状态
  Stop:            # 停止前验证所有阶段完成

2.3 数据流

┌─────────────────────────────────────────────────────────────┐
│                    任务开始                                   │
│  用户请求复杂任务（预计 >5 次工具调用）                         │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        ▼
        ┌───────────────────────────────┐
        │  步骤 1: 创建 task_plan.md    │  ← 绝不跳过！
        └───────────────┬───────────────┘
                        │
                        ▼
    ┌────────────────────────────────────────────┐
    │              工作循环（迭代）                │
    │                                            │
    │  PreToolUse Hook ─→ 读取 task_plan.md      │
    │       ↓                                    │
    │  执行工具调用                               │
    │       ↓                                    │
    │  PostToolUse Hook ─→ 提醒更新状态          │
    │       ↓                                    │
    │  2-Action Rule ─→ 更新 findings.md         │
    │                                            │
    └────────────────────────────────────────────┘
                        │
                        ▼
        ┌───────────────────────────────┐
        │  Stop Hook: 验证所有阶段完成   │
        └───────────────────────────────┘

3. 核心实现

3.1 关键代码解析

SKILL.md 的 Hooks 定义

yaml

# 文件: planning-with-files/SKILL.md:15-34
hooks:
  SessionStart:
    - hooks:
        - type: command
          command: "echo '[planning-with-files] Ready...'"

  PreToolUse:
    - matcher: "Write|Edit|Bash"  # 匹配这些工具
      hooks:
        - type: command
          command: "cat task_plan.md 2>/dev/null | head -30 || true"
          # 在执行写入/编辑/命令前，自动读取计划文件
          # 将目标重新注入注意力窗口

  PostToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "echo '[planning-with-files] File updated...'"

  Stop:
    - hooks:
        - type: command
          command: "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.sh"

设计亮点：PreToolUse Hook 在每次写入操作前自动读取计划文件，这实现了 Manus 的"注意力操控"（Attention Manipulation）——通过将目标重新注入上下文末尾，确保 AI 不会忘记原始任务。

完成验证脚本

bash

# 文件: scripts/check-complete.sh:17-44
# 统计各状态的阶段数量
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
COMPLETE=$(grep -cF "**Status:** complete" "$PLAN_FILE" || true)
IN_PROGRESS=$(grep -cF "**Status:** in_progress" "$PLAN_FILE" || true)
PENDING=$(grep -cF "**Status:** pending" "$PLAN_FILE" || true)

# 验证是否全部完成
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
    echo "ALL PHASES COMPLETE"
    exit 0  # 允许停止
else
    echo "TASK NOT COMPLETE"
    exit 1  # 阻止停止，继续工作
fi

设计亮点：通过 exit 1 返回值阻止 Claude 过早停止，确保所有阶段都标记为完成才能结束任务。

3.2 设计模式应用

Manus 六大原则的实现

原则	实现方式
KV-Cache 优化	保持 prompt 前缀稳定，追加式上下文
掩码而非移除	使用一致的工具前缀便于逻辑掩码
文件系统作外部记忆	三文件模式持久化所有重要信息
注意力操控	PreToolUse Hook 重读计划文件
保留错误尝试	错误表格记录所有失败，避免重复
避免 Few-Shot 陷阱	引入变化，不盲目复制模式

2-Action Rule（二操作规则）

操作 1: WebSearch → 记下结果
操作 2: WebFetch → 必须立即更新 findings.md！
操作 3: Read file → 记下发现
操作 4: Grep search → 必须立即更新 findings.md！

这个规则解决了多模态信息（图像、浏览器截图）易失性的问题——视觉信息在上下文重置后无法恢复，必须立即转为文本存储。

3.3 亮点与技巧

5-Question Reboot Test（五问重启测试）

一个优雅的自检机制，用于验证上下文管理是否健全：

问题	答案来源
我在哪？	`task_plan.md` 当前阶段
我要去哪？	`task_plan.md` 剩余阶段
目标是什么？	`task_plan.md` 目标声明
我学到了什么？	`findings.md`
我做了什么？	`progress.md`

3-Strike Error Protocol（三击错误协议）

尝试 1: 诊断 & 修复
  → 仔细阅读错误
  → 识别根本原因
  → 应用针对性修复

尝试 2: 替代方案
  → 同样错误？换一种方法
  → 换工具？换库？
  → 绝不重复完全相同的失败操作

尝试 3: 全面反思
  → 质疑假设
  → 搜索解决方案
  → 考虑更新计划

3 次失败后: 上报用户
  → 解释尝试了什么
  → 分享具体错误
  → 请求指导

4. 使用指南

4.1 快速开始

安装（二选一）：

bash

# 方式 1: Plugin Marketplace（推荐）
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

# 方式 2: 手动安装
git clone https://github.com/OthmanAdi/planning-with-files ~/.claude/skills/planning-with-files

使用：

安装后，Claude 会自动：

复杂任务开始时创建 task_plan.md
写入/编辑/命令执行前重读计划（PreToolUse Hook）
文件更新后提醒更新状态（PostToolUse Hook）
停止前验证所有阶段完成（Stop Hook）

也可手动调用：/planning-with-files

4.2 核心 API / CLI

命令/文件	用途
`/planning-with-files`	手动调用 Skill
`scripts/init-session.sh`	初始化三个计划文件
`scripts/check-complete.sh`	验证任务完成状态

4.3 配置说明

何时使用此模式：

使用 ✅	跳过 ❌
多步骤任务（3+ 步）	简单问答
研究任务	单文件编辑
项目构建	快速查询
多次工具调用的任务	—

模板自定义：

编辑 templates/ 目录下的文件即可自定义阶段结构、表格格式等。

5. 总结

5.1 优势与局限

优势：

✅ 解决了 AI Agent 的上下文持久化问题
✅ Hooks 机制实现自动化，无需手动干预
✅ 三文件模式结构清晰，易于理解和扩展
✅ 基于 Manus 验证过的方法论，有实战基础
✅ 轻量级实现，仅依赖 Markdown 和 Shell

局限：

⚠️ 需要用户理解并配合维护文件状态
⚠️ 对简单任务可能是过度设计
⚠️ PreToolUse Hook 增加了每次操作的开销
⚠️ 文件状态检查依赖特定格式（**Status:** complete）

5.2 适用场景

场景	适用度	原因
复杂功能开发	⭐⭐⭐⭐⭐	多阶段、多文件、易漂移
研究调研任务	⭐⭐⭐⭐⭐	信息量大、需持久化
Bug 修复	⭐⭐⭐⭐	需追踪尝试和错误
简单代码修改	⭐⭐	可能过度设计
问答交互	⭐	无需此模式

5.3 延伸阅读

Manus Context Engineering Blog — 原始方法论
Lance Martin 的 Manus 架构分析 — 深度技术解读
Claude Code Hooks 文档 — Hooks 系统详解

附录

术语表

术语	英文	解释
上下文工程	Context Engineering	优化 AI 上下文窗口使用的方法论
KV-Cache	Key-Value Cache	LLM 推理时缓存已处理 Token 的机制
注意力操控	Attention Manipulation	通过重读信息将其注入注意力窗口
目标漂移	Goal Drift	AI 在长任务中逐渐忘记原始目标
Hooks	Hooks	在特定事件触发时自动执行的代码

参考资源

仓库地址: https://github.com/OthmanAdi/planning-with-files
作者: Ahmad Othman Ammar Adi
版本: 2.1.2
许可证: MIT

Planning with Files：Manus 风格的上下文工程 ​

摘要 ​

目录 ​

1. 项目概览 ​

1.1 解决的问题 ​

1.2 核心价值主张 ​

1.3 技术栈 ​

2. 架构设计 ​

2.1 整体架构图 ​

2.2 核心模块说明 ​

三文件模式 ​

Hooks 机制 ​

2.3 数据流 ​

3. 核心实现 ​

3.1 关键代码解析 ​

SKILL.md 的 Hooks 定义 ​

完成验证脚本 ​

3.2 设计模式应用 ​

Manus 六大原则的实现 ​

2-Action Rule（二操作规则） ​

3.3 亮点与技巧 ​

5-Question Reboot Test（五问重启测试） ​

3-Strike Error Protocol（三击错误协议） ​

4. 使用指南 ​

4.1 快速开始 ​

4.2 核心 API / CLI ​

4.3 配置说明 ​

5. 总结 ​

5.1 优势与局限 ​

5.2 适用场景 ​

5.3 延伸阅读 ​

附录 ​

术语表 ​

参考资源 ​