第 38 期 | `planning-with-files` 插件入门
🎯 学习目标
- 理解
planning-with-files插件的核心作用及其在复杂任务管理中的价值。 - 掌握
task_plan.md、findings.md和progress.md这“铁三角”文件的设计理念与实际应用。 - 学会引导 Claude 利用外部文件系统进行任务规划、进度跟踪和结果汇报，实现更透明、可控的 AI 协作。
- 能够通过观察和修改这些文件，对 Claude 的工作流程进行干预和调试，提升 AI 代理的开发效率。
📖 核心概念讲解
38.1 planning-with-files 插件概述及其哲学
在复杂的开发任务中，人类工程师会习惯性地使用各种工具来辅助思考和管理：笔记本记录想法，TODO 列表规划步骤，日报总结进展，日志文件记录运行细节。这些外部化、结构化的信息是项目成功的关键。对于 AI 代理，尤其是像 Claude 这样强大的大语言模型，当它需要处理多步骤、长周期、需要持续记忆和自我反思的任务时，也同样需要一套机制来“外部化”它的思考过程和工作状态。
planning-with-files 插件正是为此而生。它不是一个单一的功能，而是一套设计哲学和工具集，允许 Claude 将其内部的“思维过程”和“任务状态”写入到外部文件系统中的特定 Markdown 文件。这样做有几个核心优势：
- 持久化记忆与上下文管理：克服 LLM 的上下文窗口限制，将关键信息存储在文件中，确保即使在多次交互或长时间任务中也能保持一致的上下文。
- 透明度与可解释性：将 AI 的规划、发现和进展以人类可读的格式呈现出来，让用户清楚地了解 AI 正在做什么、为什么这样做、遇到了什么问题。
- 可控性与可干预性：用户可以直接查看甚至修改这些文件，从而在 AI 工作过程中进行干预、纠正方向或提供新的输入，实现更精细的控制。
- 结构化自我反思：AI 可以通过阅读自己之前写入的文件来反思、学习和调整策略，提升任务执行的鲁棒性。
简单来说，planning-with-files 插件让 Claude 拥有了“写日记”和“写工作报告”的能力，从而能够更好地组织和管理自己的工作。
38.2 铁三角体系：task_plan.md、findings.md、progress.md
planning-with-files 插件通常会引导 Claude 围绕三个核心 Markdown 文件来管理项目，我们称之为“铁三角体系”：
task_plan.md(任务计划):- 用途：这是 AI 的“项目蓝图”或“待办事项清单”。Claude 在开始一项新任务之前，会首先在这里详细规划任务的分解步骤、预期目标、所需工具和可能遇到的挑战。它应该是一个结构化的、可执行的计划。
- 内容示例：
# 任务计划：开发一个目录文件统计脚本 ## 1. 理解并确认需求 - 明确用户需求：递归遍历指定目录，统计所有文件类型及其数量。 - 确认输出格式：以表格形式展示，包含文件类型和计数。 ## 2. 环境准备与工具选择 - 确认 Python 版本 (假设 Python 3.9+) - 确认所需库：`os` 模块（内置） - 编写脚本文件：`file_counter.py` ## 3. 核心逻辑实现 ### 3.1 遍历目录 - 使用 `os.walk()` 递归遍历。 - 过滤出文件，忽略目录。 ### 3.2 提取文件类型 - 使用 `os.path.splitext()` 获取文件扩展名。 - 处理无扩展名文件（例如 `.gitkeep` 或无后缀文件）。 ### 3.3 统计数量 - 使用字典存储文件类型和对应的计数。 ## 4. 结果输出 - 格式化输出为 Markdown 表格。 - 考虑错误处理：目录不存在等。 ## 5. 测试与验证 - 创建一个测试目录结构。 - 运行脚本并验证输出是否正确。 - 何时使用：任务开始时，或任务方向需要调整时。
findings.md(发现与洞察):用途：这是 AI 的“研究日志”或“发现笔记”。在执行任务过程中，Claude 会将所有的观察结果、命令输出、错误信息、关键数据点、遇到的问题以及由此产生的洞察记录在这里。它是一个时间序列的、非结构化但有用的信息流。
内容示例：
# 任务发现日志 ## 2023-10-27 10:30:00 - 开始任务，创建测试目录 ```bash mkdir -p test_dir/sub_dir touch test_dir/file1.txt test_dir/file2.json test_dir/sub_dir/file3.py touch test_dir/no_ext ls -R test_dirtest_dir: file1.txt file2.json no_ext sub_dir test_dir/sub_dir: file3.py2023-10-27 10:45:15 - 初步脚本运行结果
- 编写了
file_counter.py初版。 - 运行脚本时发现
os.path.splitext对于no_ext文件会返回('', '.no_ext')或('no_ext', '')，需要处理空扩展名的情况。 - 发现
os.path.splitext返回的是(root, ext)，其中ext包含.。在统计时需要去除.。
2023-10-27 11:05:30 - 处理空扩展名和点号
- 已修改脚本，将
no_ext识别为(无扩展名)。 - 已修改脚本，确保扩展名统计时去除前导
.。
- 编写了
何时使用：执行命令后、遇到错误时、获取到重要信息时。
progress.md(任务进展):- 用途：这是 AI 的“状态报告”或“每日站会更新”。Claude 会定期或在完成阶段性工作后，在这里总结当前任务的进展、已完成的步骤、下一步计划、遇到的障碍以及需要用户协助的地方。它是一个高层次的、结构化的状态更新。
- 内容示例：
# 任务进展报告 ## 当前状态：进行中 ## 已完成工作 - [x] 理解并确认用户需求。 - [x] 搭建测试目录环境。 - [x] 完成 `file_counter.py` 脚本的核心逻辑编写，包括目录遍历、文件类型提取和计数。 - [x] 处理了无扩展名文件和扩展名前导点的问题。 ## 下一步计划 - [ ] 完善错误处理机制（例如，目标目录不存在）。 - [ ] 编写详细的测试用例并全面验证脚本功能。 - [ ] 优化输出格式，确保 Markdown 表格美观且易读。 ## 遇到的问题/障碍 - 暂无重大障碍，进展顺利。 ## 需要用户协助 - 暂无。 - 何时使用：阶段性工作完成时，或用户请求状态更新时。
铁三角互动流程示意图：
用户需求 (Prompt)
|
v
+-----------------------+
| Claude (AI 代理) |
+-----------------------+
| (1. 规划) ^ (5. 反思/调整)
v |
+------------------------------------------------+
| 文件系统 (持久化记忆) |
| |
| +------------------+ +------------------+ |
| | task_plan.md |<-->| findings.md | |
| | (任务蓝图/待办) | | (发现/日志/洞察) | |
| +------------------+ +------------------+ |
| ^ | ^ | |
| | v (2. 执行) | v (3. 记录) |
| +------------------+ +------------------+ |
| | progress.md |<-->| (工具执行/bash) | |
| | (状态报告/更新) | | (外部环境交互) | |
| +------------------+ +------------------+ |
+------------------------------------------------+
| (4. 汇报)
v
Claude 回应用户
通过这三个文件，Claude 能够像一个有条不紊的工程师一样，将自己的工作分解、记录和汇报，极大地提升了其处理复杂任务的能力。
💻 模拟 Claude TUI 交互
以下是使用 planning-with-files 插件时，Claude 在终端（TUI）中的典型交互流程。
场景一：初始化任务并生成计划
用户请求 Claude 帮助编写一个简单的 Python 脚本，用于统计目录中的文件类型。
> 你好 Claude，请帮我编写一个 Python 脚本，它能递归遍历指定目录，统计所有文件类型（例如 `.txt`, `.py`, `.json` 等）的数量，并以 Markdown 表格的形式输出统计结果。
╭─ Claude ────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ 好的，这是一个有趣且实用的任务。为了确保我们能高效地完成，我将使用 `planning-with-files` 插件来为你规划整个开发过程。 │
│ 我将首先创建一个 `task_plan.md` 文件来详细列出我将采取的步骤。 │
│ │
│ **Thinking:** │
│ 我需要创建一个 `task_plan.md` 文件，其中包含： │
│ 1. 理解需求：确认输入（目录路径），输出（Markdown 表格），核心逻辑（递归遍历，文件类型提取，计数）。 │
│ 2. 环境设置：Python 脚本文件 `file_counter.py`。 │
│ 3. 核心功能实现：`os.walk` 遍历，`os.path.splitext` 提取扩展名，字典计数。 │
│ 4. 结果输出：格式化为 Markdown 表格。 │
│ 5. 测试与验证：创建测试目录，运行脚本，验证结果。 │
│ 6. 错误处理：考虑目录不存在等情况。 │
│ │
│ **Tool Call:** │
│ `write_file`({ │
│ "path": "task_plan.md", │
│ "content": "# 任务计划：开发一个目录文件统计脚本\n\n## 1. 理解并确认需求\n- 明确用户需求：递归遍历指定目录，统计所有文件类型及其数量。\n- 确认输出格式：以表格形式展示，包含文件类型和计数。\n\n## 2. 环境准备与工具选择\n- 确认 Python 版本 (假设 Python 3.9+)\n- 确认所需库：`os` 模块（内置）\n- 编写脚本文件：`file_counter.py`\n\n## 3. 核心逻辑实现\n### 3.1 遍历目录\n- 使用 `os.walk()` 递归遍历。\n- 过滤出文件，忽略目录。\n### 3.2 提取文件类型\n- 使用 `os.path.splitext()` 获取文件扩展名。\n- 处理无扩展名文件（例如 `.gitkeep` 或无后缀文件）。\n### 3.3 统计数量\n- 使用字典存储文件类型和对应的计数。\n\n## 4. 结果输出\n- 格式化输出为 Markdown 表格。\n- 考虑错误处理：目录不存在等。\n\n## 5. 测试与验证\n- 创建一个测试目录结构。\n- 运行脚本并验证输出是否正确。\n"
> ls -R
╭─ Claude ────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ls -R will list the files in the directory. │
│ │
│ Tool Call: │
│ execute_bash({ │
│ "command": "ls -R" │
│ }) │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```bash
> ls -R
.
task_plan.md
╭─ Claude ────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ 好的，我已成功创建了 task_plan.md 文件。请你阅读这个计划，看看是否符合你的预期，或者是否有需要调整的地方。 │
│ 当你准备好让我开始执行时，请告诉我。 │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
### 场景二：执行计划并记录发现
用户确认计划后，Claude 开始执行，并在此过程中记录发现。
计划看起来很棒，请开始执行吧！
╭─ Claude ────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ 好的，我将按照 task_plan.md 中的计划开始执行。首先，我将创建测试目录结构，并把相关操作和结果记录到 findings.md。│
│ 同时，我也会更新 progress.md 来反映当前的进展。 │
│ │
│ Thinking: │
│ 1. 根据 task_plan.md 的步骤 5，创建测试目录。 │
│ 2. 将创建目录的命令和 ls -R 的输出记录到 findings.md。 │
│ 3. 更新 progress.md，标记“创建测试目录环境”已