Planning-with-files 教程系列：Manus 式上下文工程实践

系列前言

2025 年 12 月，Meta 以 20 亿美元收购了 AI 创业公司 Manus。在短短 8 个月内，Manus 从零做到年营收超 1 亿美元。他们成功的核心秘诀是什么？上下文工程（Context Engineering）。

“Markdown 是我在磁盘上的’工作记忆’。由于我迭代处理信息，活跃上下文有限，Markdown 文件作为便签用于记录、检查点和构建模块。” — Manus AI

Planning-with-files 是一个开源项目，将 Manus 的上下文工程方法论转化为可立即使用的 AI 编程工具。通过简单的 3-File Pattern，让你的 AI 助手拥有持久化的"工作记忆"。

为什么需要 Planning-with-files？

AI 编程助手的常见痛点

如果你正在使用 Claude Code、Cursor、Copilot 等 AI 编程工具，可能遇到过这些问题：

flowchart LR
    A[开始任务] --> B[AI 理解需求]
    B --> C[执行多步操作]
    C --> D[上下文膨胀]
    D --> E[目标漂移]
    E --> F[遗忘早期决策]
    F --> G[重复犯错]
    G --> H[任务失败/质量下降]

    style D fill:#ffcccc
    style E fill:#ffcccc
    style F fill:#ffcccc
    style G fill:#ffcccc

问题根源

痛点	根源	后果
易失记忆	TodoWrite 在上下文重置后消失	任务进度丢失
目标漂移	50+ 工具调用后忘记原始目标	偏离需求
错误隐藏	失败未追踪	同样错误重复
上下文塞满	信息塞入上下文而非存储	Token 浪费

Planning-with-files 的解决方案

flowchart TD
    A[上下文窗口 = RAM] --> B[易失、有限]
    C[文件系统 = Disk] --> D[持久、无限]

    B --> E[任何重要内容写入磁盘]
    D --> E

    E --> F[3-File Pattern]

    style C fill:#e1f5ff
    style D fill:#e1f5ff
    style F fill:#e1f5ff

核心原则：任何重要的内容都写入文件，而不是塞入上下文。

3-File Pattern 核心概念

对于每个复杂任务，创建 三个文件：

task_plan.md      → 阶段与进度追踪（大脑）
findings.md       → 研究与发现存储（知识库）
progress.md       → 会话日志与测试结果（日记）

三个文件的协作关系

flowchart TB
    subgraph 任务生命周期
        A[任务开始] --> B[创建 task_plan.md]
        B --> C[创建 findings.md]
        B --> D[创建 progress.md]
    end

    subgraph 工作循环
        E[研究/探索] --> F[更新 findings.md]
        G[实现/编码] --> H[更新 progress.md]
        I[完成阶段] --> J[更新 task_plan.md 状态]
        F --> K[PreToolUse Hook 重读 task_plan.md]
        H --> K
        K --> E
        K --> G
    end

    C --> E
    D --> G
    J --> L{所有阶段完成?}
    L -->|否| E
    L -->|是| M[任务完成]

    style B fill:#e1f5ff
    style C fill:#fff3e0
    style D fill:#e8f5e9

文件职责一览

文件	职责	何时更新
`task_plan.md`	大脑 - 存储目标、阶段、决策、错误	开始任务、完成阶段、遇到错误
`findings.md`	知识库 - 存储研究、发现、技术决策	每 2 次查看操作、发现新信息
`progress.md`	日记 - 存储动作、测试结果、会话历史	完成操作、运行测试、出错时

task_plan.md 结构预览

# Task Plan: [任务名称]

## Goal
[一句话描述任务目标]

## Phases

### Phase 1: [阶段名称]
- [ ] 任务项 1
- [ ] 任务项 2
- **Status:** in_progress
- **Started:** 2026-03-26 10:00

### Phase 2: [阶段名称]
- [ ] 任务项
- **Status:** pending

## Decisions
| Decision | Rationale | Date |
|----------|-----------|------|
| [决策内容] | [决策理由] | [日期] |

## Errors Encountered
| Error | Attempt | Resolution | Date |
|-------|---------|------------|------|
| [错误描述] | [尝试次数] | [解决方案] | [日期] |

findings.md 结构预览

# Findings: [任务名称]

## Research Findings
- 发现 1
- 发现 2

## Technical Decisions
- 决策 1：选择 X 而非 Y，因为...

## Resources & References
- [相关文档](url)
- [代码文件](path)

progress.md 结构预览

# Progress: [任务名称]

## Session Log
| Time | Action | Files Modified |
|------|--------|----------------|
| 10:00 | 开始 Phase 1 | - |
| 10:30 | 完成数据模型 | schema.sql |

## Test Results
| Test | Status | Notes |
|------|--------|-------|
| 单元测试 | ✅ Pass | 覆盖率 85% |

## Error Log
| Time | Error | Resolution |
|------|-------|------------|
| 11:00 | 连接超时 | 增加超时配置 |

与 Superpowers 的对比

如果你已经熟悉 Superpowers 教程系列，可能会好奇两者有什么区别。

设计理念差异

维度	Superpowers	Planning-with-files
核心理念	技能驱动的开发流程	文件驱动的工作记忆
结构形式	14 个独立技能	1 个核心模式（3 文件）
触发方式	关键词自动触发	`/plan` 命令或自动检测
存储方式	`.project/designs/`	项目根目录 3 文件

适用场景差异

flowchart LR
    subgraph Superpowers 适合
        A1[功能开发]
        A2[测试驱动开发]
        A3[系统化调试]
        A4[代码审查]
    end

    subgraph Planning-with-files 适合
        B1[研究型任务]
        B2[复杂多步骤任务]
        B3[长会话任务]
        B4[代码库探索]
    end

    subgraph 两者都适合
        C1[新功能实现]
        C2[项目重构]
        C3[技术调研]
    end

功能覆盖对比

功能	Superpowers	Planning-with-files
需求澄清	✅ brainstorming	✅ task_plan Goal
技术方案	✅ writing-plans	✅ task_plan Phases
测试驱动	✅ TDD skill	✅ progress.md 测试记录
错误追踪	❌ 无专门机制	✅ Errors 表格
研究管理	❌ 无专门机制	✅ findings.md
上下文持久化	⚠️ 设计文档	✅ 3 文件实时更新
自动验证	✅ verification skill	✅ Stop Hook

如何选择与配合

场景	推荐方案
快速功能开发	Superpowers 单独使用
技术调研/研究	Planning-with-files 单独使用
复杂项目开发	两者配合使用（教程 10 详解）
团队协作	Planning-with-files + Git

本系列教程结构

本系列共 10 篇 详细教程，涵盖从入门到高级的全部内容：

入门篇

系列介绍与核心概念（本文）- 3-File Pattern 概览、学习路径
多平台安装指南 - 16+ 平台安装配置
快速开始：第一个规划任务 - 5 步完成第一个任务

核心篇

task_plan.md 深度解析 - 阶段划分、状态追踪
findings.md 研究管理 - 2-Action 规则、技术决策
progress.md 会话日志 - 动作记录、会话恢复

实战篇

实战：研究型任务 - 技术选型、代码库探索
实战：开发型任务 - 功能开发、错误追踪

进阶篇

Hooks 机制深度配置 - 四种 Hook 详解
与 Superpowers 协同 - 框架配合使用

谁适合学习本系列？

✅ AI 编程新手 - 建立正确的任务管理习惯
✅ 经验丰富的开发者 - 解决长会话上下文丢失问题
✅ 团队技术负责人 - 规范化团队的 AI 使用方式
✅ 研究人员/分析师 - 管理复杂的研究型任务
✅ Superpowers 用户 - 学习两个框架如何配合

前置要求

熟练使用至少一个 AI 编程工具（Claude Code、Cursor、Codex、Copilot 等）
基本的命令行操作知识
了解 Markdown 基础语法

如何使用本系列

按顺序阅读 - 教程之间有依赖关系，建议按顺序学习
边学边练 - 每篇教程都包含实际操作示例
参照示例 - 结合实战案例理解概念
定制工作流 - 在进阶篇学习如何定制配置

学习路径推荐

flowchart TD
    A[入门篇<br/>教程 1-3] --> B{你的目标?}

    B -->|深入理解核心| C[核心篇<br/>教程 4-6]
    B -->|快速实战| D[实战篇<br/>教程 7-8]

    C --> D
    D --> E[进阶篇<br/>教程 9-10]

    E --> F[精通<br/>Planning-with-files]

    style A fill:#e1f5ff
    style C fill:#fff3e0
    style D fill:#e8f5e9
    style E fill:#fce4ec
    style F fill:#c8e6c9

核心原则预览

在开始之前，记住这些核心原则：

1. 创建计划优先

永远不要在没有 task_plan.md 的情况下开始工作

2. 2-Action 规则

每完成 2 次查看/浏览器操作，必须更新 findings.md

3. 记录所有错误

即使快速修复的错误也要记录，避免重复

4. 不重复失败

如果某个方法失败，记录并尝试不同方法

5. 验证后完成

只有所有阶段都标记为 complete，任务才算完成

系列更新计划

教程 1-3（入门篇）：本周发布
教程 4-6（核心篇）：下周发布
教程 7-10（实战与进阶篇）：后续两周发布

系列导航：

仓库地址：github.com/OthmanAdi/planning-with-files

讨论区：欢迎在评论区分享你的使用经验或提出问题！