Planning-With-Files 完整教程

项目仓库: OthmanAdi/planning-with-files

📝 前言

当 Claude Code 会话结束后，如何让下一个会话快速了解项目的当前状态？Planning-With-Files-Skill 提供了完美的解决方案——它通过基于文件的规划方式，让 Claude 能够自我管理任务、恢复上下文、追踪进度，实现更可靠和可审计的 AI 辅助开发流程。

Planning-With-Files-Skill 是一个为 Claude Code 实现类 Manus 工作流模式的技能。它通过基于文件的规划方式，让 Claude 能够自我管理任务、恢复上下文、追踪进度，从而实现更可靠和可审计的 AI 辅助开发流程。

项目特点： - 🎯 类 Manus 工作流模式: 让 Claude 具备类似 AI Agent 的自主规划能力 - 📁 三文件架构: 通过计划文件、日志文件、摘要文件实现结构化管理 - 🔄 会话恢复: 无限续写能力,即使会话中断也能无缝恢复 - 🚀 自动创建: 首次使用时自动生成必要的目录和文件结构

二、核心功能

2.1 三文件模式（The Three-File Pattern）

项目的核心是基于三个关键文件的规划架构：

PLAN.md - 计划文件

作用: 定义项目目标、任务列表和里程碑
内容: 结构化的任务分解、优先级排序
格式: Markdown 格式,便于人类和 AI 共同阅读
更新: 随项目进展动态调整

LOG.md - 日志文件

作用: 记录所有已完成的任务和决策过程
内容: 时间戳、执行动作、结果摘要
价值: 提供完整的执行轨迹和审计线索
用法: 每次 Claude 执行任务后自动追加记录

SUMMARY.md - 摘要文件

作用: 维护项目当前状态的简洁概览
内容: 进度百分比、关键成就、阻塞项
用途: 快速恢复上下文,了解项目整体状况
更新: 在重要里程碑时更新

2.2 自动初始化

🏗️ 首次使用自动创建 .planning/ 目录
📝 自动生成三个核心文件模板
⚙️ 零配置开箱即用

2.3 会话恢复机制

🔄 无限续写能力
📍 通过读取 SUMMARY.md 快速恢复上下文
🧠 Claude 自动理解项目当前状态
⏭️ 从上次中断处继续执行

2.4 人类可审计

👀 所有文件采用 Markdown 纯文本格式
📖 开发者可随时查看计划、日志和摘要
🔍 透明的决策过程
🤝 人机协作友好

三、安装方法

3.1 通过 Skill Registry 安装（推荐）

1	skill install https://github.com/OthmanAdi/planning-with-files

3.2 使用 skill-creator 安装

1 2	# 如果你已经安装了 skill-creator skill create planning-with-files https://github.com/OthmanAdi/planning-with-files

3.3 手动安装

克隆仓库

1 2	git clone https://github.com/OthmanAdi/planning-with-files.git cd planning-with-files

复制到技能目录

1 2	# 复制到 Claude Code 的 skills 目录 cp -r . ~/.claude/skills/planning-with-files-skill

在配置中注册

在项目的 .claude/settings.json 中添加：

1
2
3

{
  "skills": ["planning-with-files"]
}

3.4 使用 MCP 服务器注册

1 2	# 访问 MCP Servers 注册中心 # https://mcpservers.org/claude-skills/OthmanAdi/planning-with-files

四、使用场景和示例

4.1 启动新项目

用户指令:

1 2	我想开发一个 Python CLI 工具，用于自动化文件整理。使用 planning-with-files-skill 来规划这个项目。

Claude 的操作流程:

自动创建目录结构

.planning/
├── PLAN.md      # 项目计划
├── LOG.md       # 执行日志
└── SUMMARY.md   # 项目摘要

生成 PLAN.md

# 文件整理 CLI 工具 - 项目计划

## 项目目标
开发一个 Python CLI 工具,根据文件类型自动整理文件到对应文件夹。

## 任务列表
- [ ] 1. 项目初始化
  - [ ] 1.1 创建项目结构
  - [ ] 1.2 配置依赖管理
  - [ ] 1.3 设置测试框架
- [ ] 2. 核心功能开发
  - [ ] 2.1 文件分类逻辑
  - [ ] 2.2 CLI 参数解析
  - [ ] 2.3 文件移动功能
- [ ] 3. 测试与文档
  - [ ] 3.1 单元测试
  - [ ] 3.2 集成测试
  - [ ] 3.3 README 文档

## 里程碑
- M1: MVP 版本 (任务 1-2)
- M2: 完整版本 (任务 3)

初始化 LOG.md

# 执行日志

## 2026-02-13 10:00
- ✅ 创建项目计划
- ✅ 定义任务结构

初始化 SUMMARY.md

# 项目摘要

**进度**: 0%
**当前阶段**: 项目启动
**已完成**: 0/10 任务
**下一步**: 开始项目初始化

4.2 继续中断的项目

背景: 你昨天开发到一半会话结束了,今天想继续。

用户指令:

1	继续开发昨天的文件整理工具项目

Claude 的操作流程:

读取 SUMMARY.md

**进度**: 40%
**当前阶段**: 核心功能开发中
**已完成**: 4/10 任务
  - ✅ 项目初始化
  - ✅ 文件分类逻辑
  - ❌ CLI 参数解析 (进行中)
**阻塞项**: 无

自动恢复上下文

1 2	我看到项目已经完成了 40%,正在开发 CLI 参数解析功能。让我继续完成这个任务...

继续执行并记录

## 2026-02-14 09:15
- ✅ 完成 CLI 参数解析
- ✅ 实现文件移动功能
- 📝 更新项目进度至 60%

4.3 复杂的多阶段项目

项目: 构建一个完整的 Web 应用

PLAN.md 示例:

# Web 应用开发计划

## 项目信息
- **项目名称**: TaskFlow
- **技术栈**: FastAPI + React + PostgreSQL
- **预计周期**: 4 周

## 阶段划分

### 第一阶段: 后端基础 (Week 1)
- [ ] 1.1 项目脚手架
- [ ] 1.2 数据库模型设计
- [ ] 1.3 API 路由设计
- [ ] 1.4 用户认证系统

### 第二阶段: 前端开发 (Week 2)
- [ ] 2.1 React 项目初始化
- [ ] 2.2 组件库搭建
- [ ] 2.3 API 集成
- [ ] 2.4 状态管理

### 第三阶段: 功能完善 (Week 3)
- [ ] 3.1 任务 CRUD 功能
- [ ] 3.2 实时通知
- [ ] 3.3 文件上传

### 第四阶段: 测试与部署 (Week 4)
- [ ] 4.1 单元测试
- [ ] 4.2 集成测试
- [ ] 4.3 CI/CD 配置
- [ ] 4.4 生产部署

## 当前进度
🎯 **正在执行**: 阶段 1.2 - 数据库模型设计

SUMMARY.md 示例:

# 项目摘要 - TaskFlow

**总体进度**: 15%
**当前阶段**: 第一阶段 - 后端基础
**已完成**: 3/20 任务

### 最近成就 ✨
- ✅ 搭建 FastAPI 项目结构
- ✅ 配置 SQLAlchemy
- ✅ 实现基础用户模型

### 进行中 🚧
- 🔄 设计任务关联模型
- 🔄 添加数据库索引

### 阻塞项 ⚠️
- 无

### 下一步 📋
- 完成数据库迁移
- 实现用户注册 API

五、核心功能列表

5.1 规划功能

✅ 自动创建 .planning/ 目录
✅ 生成结构化 PLAN.md
✅ 任务优先级排序
✅ 里程碑定义
✅ 依赖关系管理

5.2 执行跟踪

✅ 实时更新 LOG.md
✅ 时间戳记录
✅ 决策过程文档化
✅ 错误与重试记录

5.3 状态管理

✅ 进度百分比计算
✅ 当前任务高亮
✅ 阻塞项标记
✅ 快速上下文恢复

5.4 交互特性

✅ 人类可读的 Markdown 格式
✅ 版本控制友好
✅ 支持团队协作
✅ 可审计的决策轨迹

六、最佳实践

6.1 任务粒度控制

6.2 定期更新摘要

建议频率: - 每完成一个主要任务 - 每个工作会话结束 - 遇到阻塞时

6.3 利用版本控制

1
2
3

# 将 .planning/ 目录纳入 Git
git add .planning/
git commit -m "更新项目计划: 完成用户认证模块"

好处: - 追踪计划变更历史 - 团队成员同步进度 - 回滚到之前的状态

6.4 与其他 Skill 配合使用

# 配合 test-gen skill
"根据 PLAN.md 中的测试任务,生成测试代码"

# 配合 code-review skill
"审查 LOG.md 中记录的最近提交"

# 配合 doc-gen skill
"基于 SUMMARY.md 生成项目文档"

6.5 会话恢复最佳实践

高效恢复流程: 1. Claude 自动读取 SUMMARY.md 2. 理解当前进度和阻塞项 3. 查看 LOG.md 了解最近操作 4. 从断点继续执行

提示词示例:

1	请继续上次的项目,根据 .planning/ 中的计划执行下一个任务

6.6 任务完成标记

使用清晰的标记:

- [ ] 未开始
- [🔄] 进行中
- [✅] 已完成
- [❌] 已取消
- [⚠️] 有阻塞

七、社区分支项目

7.1 Planning-With-Tests-Skill

仓库: 社区贡献
特点: 结合测试驱动开发(TDD)
功能: 在 PLAN.md 中自动生成测试任务

7.2 Planning-With-Git-Skill

特点: 与 Git 工作流深度集成
功能:
- 自动为每个任务创建分支
- 根据 PLAN.md 生成提交信息
- 自动关联 PR 与任务

7.3 Planning-With-Notion-Skill

特点: 同步到 Notion
功能:
- 将 PLAN.md 同步到 Notion 看板
- 双向更新项目状态
- 团队可视化协作

7.4 Planning-Dashboard

特点: Web 可视化界面
功能:
- 图表化展示进度
- 甘特图视图
- 团队协作面板

八、快速命令参考

8.1 安装

# 方法 1: 通过 skill 命令
skill install https://github.com/OthmanAdi/planning-with-files

# 方法 2: 手动克隆
git clone https://github.com/disler/planning-with-files-skill.git

8.2 在 Claude Code 中使用

# 启动新项目规划
"使用 planning-with-files-skill 创建一个新项目计划"

# 继续项目
"继续执行 .planning/PLAN.md 中的下一个任务"

# 查看进度
"显示项目的当前进度和状态"

# 更新计划
"在 PLAN.md 中添加新的任务项"

8.3 文件操作

# 查看计划
cat .planning/PLAN.md

# 查看日志
tail -f .planning/LOG.md

# 查看摘要
cat .planning/SUMMARY.md

# Git 提交
git add .planning/
git commit -m "更新项目计划"

九、常见问题

Q1: 如何在团队中使用?

A: 将 .planning/ 目录纳入版本控制,团队成员通过 Git 同步计划和进度。

Q2: 可以自定义文件名吗?

A: 可以修改 skill 配置,但建议使用默认的 PLAN.md、LOG.md、SUMMARY.md 以保持一致性。

Q3: 支持多项目管理吗?

A: 支持。每个项目可以有独立的 .planning/ 目录。

Q4: 如何与其他 AI Agent 工具集成?

A: Planning-With-Files-Skill 使用标准 Markdown 格式,可与其他工具互操作。

Q5: 会话恢复时上下文会丢失吗?

A: 不会。Claude 通过读取三个文件完全恢复上下文,包括项目历史和当前状态。

十、相关资源

官方文档

社区文章

十一、结语

Planning-With-Files-Skill 通过简单的三文件模式,为 Claude Code 带来了强大的项目规划和执行跟踪能力。它不仅让 AI 辅助开发更加可靠,还提供了完整的人类可审计轨迹。

核心优势总结: - 🎯 结构化的任务规划 - 🔄 无缝的会话恢复 - 👀 透明的决策过程 - 🤝 友好的人机协作

开始使用 Planning-With-Files-Skill,让你的 Claude Code 开发体验更加专业和高效!

Happy Planning! 🚀