简述

项目地址在 

https://github.com/OthmanAdi/planning-with-fileshttps://github.com/OthmanAdi/planning-with-files

用 Claude Code 做过稍微复杂一点的开发，大概率都遇到过这些问题：上下文一重置，TodoWrite 就消失；工具调用一多目标开始漂移；错误没有被持续记录，最后上下文越来越重，但真正有用的信息却越来越少。

你：帮我重构这个用户模块，记得用TypeScript，遵循ESLint规则
AI：好的，开始分析...

[50轮对话后]

AI：*突然用JavaScript写了个新文件*
你：？？？我不是说了用TypeScript吗？
AI：抱歉，我没注意到这个要求...

这些问题并不是使用方式不对，而是当前 AI 编程的结构性痛点 。传统AI助手就像一个"金鱼记忆"的实习生：你说一句他干一件，干完就忘。上下文窗口一满，前面的规则、约束、目标全被挤出去，AI开始"自由发挥"，你只能当保姆一样不断提醒。

问题的本质：Context Window 的先天局限

AI需要"无限记忆"来完成复杂任务，但它的"工作台"（Context Window）却非常有限

2025年底，Meta以20亿美元收购AI代理公司Manus。外界好奇：他们到底做对了什么？

技术分析师Lance Martin通过逆向工程发现，Manus的核心竞争力不是模型更强，而是Context Engineering（上下文工程） 的工作流设计

GitHub开发者 @OthmanAdi 将这些观察提炼成一套基于Markdown的协作协议，通过Claude Code的插件系统实现自动化——这就是 planning-with-files 的诞生, planning-with-files是一个很有用的插件，借鉴了 Manus 的设计思路，用持久化的 Markdown 文件来做规划、进度跟踪和知识存储

核心原理

一个形象的比喻

传统AI工作流：
你说话 → AI记在"脑子"里 → 干活 → 脑子满了 → 忘记前面 → 跑偏

planning-with-files工作流：
你说话 → AI写进"笔记本" → 干活前先看笔记本 → 边干边记 → 随时可回溯

三文件模式（3-File Pattern）详解

项目要求每个复杂任务维护三个Markdown文件，分工明确如团队协作：

文件名	角色定位	核心内容	类比人类认知
task_plan.md	🗺️ 导航员	目标、阶段、待办、状态	元认知（规划能力）
findings.md	📒 研究员	调研发现、技术决策、踩坑记录	长期记忆（知识库）
progress.md	📋 记录员	执行日志、测试结果、错误追踪	情景记忆（过程回溯）

文件结构深度拆解

task_plan.md：AI的"宪法"

# 🎯 Task Plan

## 📊 Current Status
- Status: `in_progress`      # 当前状态：pending/in_progress/completed
- Phase: 2/4                 # 阶段进度，帮助AI定位"我现在在哪"
- Last Updated: 2026-02-25   # 最后更新时间，便于人工审计

## ✅ Next Steps (带复选框的待办清单)
- [x] 分析项目需求与依赖
- [x] 设计技术方案架构  
- [ ] 实现核心业务逻辑    # ← AI会优先处理未完成的项
- [ ] 编写单元测试用例
- [ ] 集成测试与文档

## 🏁 Final Goal (不可动摇的终极目标)
> 完成用户认证模块开发，支持JWT+Refresh Token双机制，
> 兼容旧版API v1.x，密码加密使用bcrypt(salt rounds=12)

## ⚠️ Constraints & Notes (约束条件)
- 必须使用TypeScript，禁用any类型
- 遵循项目ESLint配置，禁止修改.eslintrc
- 数据库操作需添加事务回滚机制

设计巧思：使用Markdown复选框[ ]/[x]，AI能直观识别任务完成状态，无需复杂解析

findings.md：知识的"卸载区"

# 🔍 Findings & Knowledge Base

## 💡 Key Discoveries (关键发现)
- 库`auth-lib@2.0`在Node 18.15+有兼容问题，建议锁定18.12版本
- API v2.0的认证头从`X-Token`改为`Authorization: Bearer`
- 项目使用PostgreSQL 14，需注意JSONB字段的索引优化

## ❌ Errors Encountered (错误日志表)
| Error | Attempt | Root Cause | Resolution |
|-------|---------|------------|------------|
| JWT验证失败 | 1 | 时区配置错误，token生成与验证时区不一致 | 统一使用UTC时间戳 |
| 数据库连接超时 | 2 | 连接池配置过小，高并发时耗尽 | 调整max_connections=20，添加重试机制 |
| bcrypt加密慢 | 1 | salt rounds=14导致单请求>500ms | 降为12，平衡安全与性能 |

## 🎯 Decisions Made (技术决策记录)
### 决策：选择`passport-jwt`而非原生`jsonwebtoken`
- Reason: 
  - 内置refresh token自动续期逻辑，减少自定义代码
  - 社区活跃，文档完善，降低维护成本
- Trade-offs:
  - 增加一个依赖包（+15KB bundle size）
  - 需要学习passport中间件配置方式

Action Rule（双动作原则）：AI每执行2次搜索/浏览/API调用，必须将关键信息总结写入findings.md，防止重要发现被上下文冲刷丢失

progress.md：防愚蠢的"纠错本"

# 📈 Progress Log & Session History

## Session 1 - 2026-02-25 14:00-15:30
### ✅ Completed
- [x] 初始化项目结构：创建auth/目录，配置tsconfig.json
- [x] 安装核心依赖：passport-jwt@4.0.1, bcrypt@5.1.1, dotenv@16.3.1
- [x] 实现JWT token生成函数（src/auth/utils.ts）

### ❌ Failed Attempts
- 尝试方案A：同步验证中间件
  - 原因：阻塞Node.js事件循环，/login接口P99延迟从80ms→320ms
  - 决策：切换到异步中间件方案

### 🔄 In Progress
- 实现refresh token自动续期逻辑（预计30分钟完成）

## Session 2 - 2026-02-25 16:00-17:15
### ✅ Completed  
- [x] 完成JWT验证中间件（src/auth/middleware.ts）
- [x] 添加refresh token端点：POST /auth/refresh
- [x] 编写单元测试：覆盖率85%，通过所有case

### 🔍 Key Observation
- 发现时区问题：本地开发用CST，生产环境UTC，导致token验证失败
- 解决方案：所有时间戳统一转UTC存储，展示层再转本地时区
- 已同步更新到findings.md

### 🎯 Next Action
- 编写集成测试：模拟完整登录→刷新→登出流程
- 更新API文档：Swagger注解补充

Strike Error Protocol（纠错协议）：同一错误第1次记录分析，第2次必须换方案，第3次触发全局反思并向用户求助，彻底打破"死循环式调试"

什么是Hooks？为什么需要？

如果仅仅是创建三个文件，那和普通用户手动记笔记没有本质区别。planning-with-files 真正的技术壁垒，在于利用Claude Code的 Hooks（钩子） 机制，将行为规范"硬编码"进AI的决策流程

Hook = 事件拦截器 + 自动执行脚本

类比：就像给AI装了"行为监控摄像头"，
在关键节点自动提醒："嘿，你该看计划了！" "这个错误记下来没？"

核心Hook配置解析（以Cursor为例）

项目通过.cursor/hooks.json定义钩子行为：

{
  "hooks": {
    "PreToolUse": {
      "description": "在AI使用任何工具（写文件/运行命令）前触发",
      "script": "hooks/pre-tool-use.sh",
      "args": ["--check-plan", "--refresh-context"]
    },
    "PostToolUse": {
      "description": "AI完成工具调用后触发", 
      "script": "hooks/post-tool-use.sh",
      "args": ["--log-progress", "--check-findings"]
    },
    "Stop": {
      "description": "AI试图结束任务时触发",
      "script": "hooks/check-complete.sh", 
      "args": ["--validate-phases", "--report-status"]
    }
  }
}

PreToolUse Hook 代码

hooks/pre-tool-use.sh 的核心逻辑：

#!/bin/bash
# pre-tool-use.sh - 在AI执行任何操作前，强制刷新目标认知

PLAN_FILE="task_plan.md"

# 1️⃣ 检查计划文件是否存在
if [[ ! -f "$PLAN_FILE" ]]; then
  echo "⚠️ 警告：未找到 $PLAN_FILE，请先创建任务计划！"
  echo "建议命令：/planning-with-files:plan 描述你的任务"
  exit 1
fi

# 2️⃣ 提取当前阶段和下一步动作（用grep+awk简单解析Markdown）
CURRENT_PHASE=$(grep -A2 "## 📊 Current Status" "$PLAN_FILE" | grep "Phase:" | awk '{print $2}')
NEXT_STEP=$(grep -A10 "## ✅ Next Steps" "$PLAN_FILE" | grep "- \[ \]" | head -1 | sed 's/.*- \[ \] //')

# 3️⃣ 输出提醒到AI的上下文（关键！）
cat << EOF
🔍 [PreToolUse Hook 提醒]
当前阶段：Phase $CURRENT_PHASE
下一步待办：$NEXT_STEP
⚠️ 请确认：你即将执行的操作是否服务于上述目标？
   如果不确定，请先读取完整的 task_plan.md 再决策。
EOF

# 4️⃣ 可选：如果AI即将修改计划文件，备份历史版本
if [[ "$1" == *"$PLAN_FILE"* ]]; then
  cp "$PLAN_FILE" "${PLAN_FILE}.bak.$(date +%s)"
  echo "📦 已备份 $PLAN_FILE 到历史版本"
fi

Hook脚本通过echo输出内容，这些内容会被Claude Code自动注入到AI的下一轮上下文中，实现"注意力注入"（Attention Injection）

Stop Hook：质量门禁的实现

hooks/check-complete.sh 确保AI不会"偷懒提前下班"：

#!/bin/bash
# check-complete.sh - 任务结束前的完整性校验

PLAN_FILE="task_plan.md"

# 1️⃣ 统计待办事项（未勾选的复选框）
PENDING_COUNT=$(grep -c "\- \[ \]" "$PLAN_FILE" 2>/dev/null || echo "0")

# 2️⃣ 如果有未完成项，阻止AI结束并给出明确指引
if [[ "$PENDING_COUNT" -gt 0 ]]; then
  echo "❌ [Stop Hook 拦截] 任务未完成！"
  echo "📋 剩余待办事项（$PENDING_COUNT项）:"
  grep "\- \[ \]" "$PLAN_FILE" | sed 's/.*- \[ \] /  • /'
  echo ""
  echo "💡 建议：继续完成上述任务，或明确说明跳过的原因并更新task_plan.md"
  exit 1  # 非零退出码会让Claude Code认为"任务未正常结束"
fi

# 3️⃣ 全部完成：生成完成报告
echo "✅ [Stop Hook 通过] 所有阶段已完成！"
echo "📊 建议下一步：1) 运行最终测试 2) 更新progress.md标记completed 3) 提交PR"
exit 0

用简单的Shell脚本+Markdown解析，实现复杂的行为约束，避免过度工程化

快速安装

# 推荐：项目级安装（仅当前项目生效）
claude plugins install OthmanAdi/planning-with-files

# 或：全局安装（所有项目可用）
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

安装后，AI会自动识别复杂任务并激活插件，也可手动触发：

/planning-with-files:plan 帮我开发一个带refresh token的用户认证系统

多IDE支持

项目通过为不同IDE提供适配配置，实现"一次编写，处处运行"

IDE	配置方式	关键文件
Claude Code	插件市场安装	.claude-plugin/manifest.json
Cursor	Skills + Hooks	.cursor/hooks.json + skills/
VS Code + Continue	Prompt文件 + Skills	.continue/prompts/
GitHub Copilot	Hooks配置	.github/hooks/planning-with-files.json
Gemini CLI	Agent Skills	.gemini/skills/

Windows用户注意：项目提供PowerShell版本的Hook脚本（.ps1），避免bash兼容性问题

观察AI自动行为

✅ AI自动创建三个文件：
   - task_plan.md（含5个阶段计划）
   - findings.md（记录性发现）  
   - progress.md（初始化日志）

✅ 执行过程中：
   - 每次写代码前，Hook提醒"确认当前阶段目标"
   - 遇到依赖冲突时，自动记录到findings.md
   - 完成一个阶段后，progress.md更新状态

✅ 最终输出：
   - 可运行的Todo App代码
   - 完整的决策记录（为什么选localStorage不用IndexedDB）
   - 可复现的调试过程（某个hook失效的排查记录）

手动模式：无Hooks也能用（Prompt Engineering方案）

如果使用的IDE不支持Hooks，可通过系统提示词模拟工作流

# 在.cursorrules 或 .clinerules 中添加：

你是一个专家级AI助手，遵循"三文件工作流"：

🔹 启动任何复杂任务前，必须检查并读取 task_plan.md
🔹 每完成2次信息收集操作（搜索/浏览/API），必须总结写入 findings.md  
🔹 每次工具调用后，必须在 progress.md 记录：动作+结果+耗时
🔹 做技术决策时，必须引用 findings.md 中的历史依据
🔹 任务结束前，必须验证 task_plan.md 所有复选框为 [x]

如果发现用户未创建规划文件，请主动建议：
"建议先运行 /planning-with-files:plan 或手动创建三个Markdown文件，
这样可以避免目标漂移和重复踩坑，提升长任务完成质量。"

发挥最大价值

六大铁律：让AI越用越聪明的秘诀

项目作者总结的Manus-style工作流核心原则，我提炼成"六大铁律"

铁律	具体做法	避免的坑
🔹 先计划，后动手	没有task_plan.md不启动复杂任务	目标模糊，边做边改，最终交付物偏离需求
🔹 边干边记	每2次外部操作，强制写入findings.md	关键信息被上下文冲刷，重复调研浪费时间
🔹 决策前回顾	做关键判断前，重读计划拉回注意力	陷入局部优化，忘记全局目标（目标漂移）
🔹 阶段完成必更新	每完成一个阶段，同步状态+记录错误	进度不透明，难回溯，难协作
🔹 错误入库	所有失败尝试写进findings.md	重复踩同一个坑，调试效率低下
🔹 绝不重蹈覆辙	同一错误第2次出现，必须换方案；第3次，全局反思	死循环式调试，浪费token和时间

会话恢复（Session Recovery）：真正的不间断协作

场景：你下午让Claude Code写代码，写到一半去吃饭。回来时上下文已重置...

❌ 传统方式：重新描述需求，从零开始
✅ planning-with-files：AI读取progress.md，自动续上昨天的进度！

启用方法

在项目settings.json或IDE配置中添加：

        

{
  "env": {
    "PLANNING_WITH_FILES_AUTO_RECOVER": "1"
  }
}

恢复原理简析

# scripts/recover-session.sh 核心逻辑：

1️⃣ 扫描 ~/.claude/projects/ 下最近修改的 planning 文件
2️⃣ 提取 progress.md 中最后一条记录的时间戳 T
3️⃣ 检索 Claude 会话日志中 T 之后的对话内容（可能因上下文压缩丢失）
4️⃣ 生成"会话补全报告"，提示AI："上次你做到这里，接下来应该..."

# 输出示例：
🔄 [Session Recovery] 检测到中断的会话 (2026-02-25 15:30)
📋 最后进度：完成JWT验证中间件，待实现refresh token端点
💡 建议下一步：1) 创建 /auth/refresh 路由 2) 编写token续期逻辑

多Agent协同：进阶玩法

项目社区已衍生出multi-manus-planning等扩展，支持多项目/多Agent协作

项目结构示例：
my-app/
├── .planning/                    # 集中管理所有规划
│   ├── auth-service/            # 认证模块规划
│   │   ├── task_plan.md
│   │   ├── findings.md
│   │   └── progress.md
│   └── payment-service/         # 支付模块规划
│       └── ...
├── packages/
│   ├── auth/                    # 认证模块代码
│   └── payment/                 # 支付模块代码
└── planning-root.md             # 顶层协调计划（可选）

协调策略

# planning-root.md 示例

## 🤝 Cross-Service Dependencies
- auth-service 完成 Phase 2 后，payment-service 才能开始 Phase 1
- 共享配置：JWT密钥、数据库连接池参数需同步更新

## 🔄 Sync Protocol
1. 每个子模块完成阶段后，在 root 文件标记 [x] 
2. 阻塞依赖的模块自动等待（通过Hook检查依赖状态）
3. 冲突检测：当两个模块修改同一配置时，触发人工Review

场景分析与边界讨论

推荐场景

场景类型	具体例子	收益点
🔧 多步骤重构	迁移React Class组件到Hooks，涉及10+文件	避免遗漏边界case，记录决策依据便于Review
🔍 技术预研	对比Next.js vs Remix vs Astro	findings.md沉淀调研结论，避免重复劳动
🧪 复杂Bug排查	生产环境偶发内存泄漏，需多轮实验	progress.md记录每次尝试，快速定位根因
📦 从零搭建项目	新项目初始化+技术选型+CI/CD配置	task_plan.md确保不遗漏关键步骤
🔄 跨会话长任务	周末写一半，周一继续	Session Recovery无缝续接

没必要用的场景

场景类型	具体例子	原因
✏️ 单文件小修改	改个文案、调整CSS样式	overhead > 收益，直接对话更高效
❓ 简单问答	"这个API怎么用？" "解释下Promise"	无需持久记忆，一次性交互即可
⚡ 一次性脚本	写个Python脚本处理CSV	任务短平快，三文件反而拖慢节奏

工作方式的范式升级

planning-with-files的本质，不是"更聪明的AI"，而是"会积累经验的数字助理"。

当你开始用这套工作流，你会发现：

🔄 从 "每次重新教AI" → "AI越用越懂你"
🔄 从 "盯着AI别跑偏" → "放心让它自主推进"  
🔄 从 "重复踩坑" → "经验持续沉淀"
🔄 从 "黑盒交付" → "过程可审计、决策可追溯"