othmanadi-planning-with-files

idea-refine Skill 多维度简评

类别:上下文工程 / 任务规划 仓库:OthmanAdi/planning-with-files 维护者:OthmanAdi

一、核心定位与价值

planning-with-files 的核心思想来自 Manus 的上下文工程方法论——用文件系统替代易失的 Context Window，把抽象的”上下文工程”变成可落地的 3 文件工作流。

关键洞见:真正限制 AI 能力的不是模型参数,而是”上下文管理”——通过结构化的文件系统持久化,可以让 AI 在处理复杂多步骤任务时保持专注。

6 大核心原则

适用场景

• 复杂多步骤任务
• 长会话(超过 50 轮)
• 频繁上下文溢出
• 复杂项目(> 1 周)

不适用场景

• 简单问答
• 1 行修改
• 短会话

二、3 文件工作流(核心)

2.1 文件结构

# 项目目录
my-project/
├── task_plan.md    # 指令寄存器:目标 / 状态 / 错误日志
├── findings.md     # 知识库:调研数据 / 中间成果
└── deliverable.md  # 成果输出:最终产物

2.2 task_plan.md(指令寄存器)

作用:Agent 的”中央处理器”,不存储具体知识,只维护元数据。

# Task Plan

## Goal
[用户需求 → 1 句话目标]

## Milestones
- [x] Phase 1: 需求澄清
- [ ] Phase 2: 架构设计
- [ ] Phase 3: 实施
- [ ] Phase 4: 测试
- [ ] Phase 5: 部署

## Sub-tasks
- [x] 1.1 收集需求
- [x] 1.2 风险评估
- [ ] 2.1 架构图
- [ ] 2.2 技术选型
...

## Errors / Blockers
- 2026-06-15 14:30: API 限流,需等待 1 小时
- 2026-06-15 15:00: 找到 workaround:加 retry 逻辑

## Key Decisions
- 选 PostgreSQL 而非 MongoDB:团队熟悉 + 强一致性需求
- 用 TanStack Query 而非 SWR:生态更广

## Read-Before-Decide
每次重要决策前必读此文件

关键规则:

• 每次关键决策前必读(Read-Before-Decide)
• 失败显式记录(避免重复)
• 状态用复选框([x] / [ ])

2.3 findings.md(知识库)

作用:存储所有调研数据 + 中间成果。

# Findings

## 技术调研
### TensorFlow 优化
- XLA 编译加速
- 静态图模式 batch_size 建议 64
- 官方文档: https://...

### 数据库选型对比
| DB | 性能 | 团队熟悉度 | 运维成本 |
|---|---|---|---|
| Postgres | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
| MongoDB | ⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐ |
| ClickHouse | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |

## 错误案例
- API 超时 → 加 retry + exponential backoff
- 内存爆炸 → 流式处理 + chunking

## 用户反馈
- 用户 A:希望支持暗黑模式
- 用户 B:移动端体验差
- 用户 C:需要导出 CSV

设计哲学:“Store, Don’t Stuff”——不要在 Context 中塞入太多信息,只保留关键结论。

2.4 deliverable.md(成果输出)

作用:最终产物的唯一载体。

# Deliverable

## 项目名称
[项目名]

## 版本
v1.0.0 - 2026-06-15

## 核心功能
- 功能 1
- 功能 2
- 功能 3

## 技术栈
- Next.js 14
- PostgreSQL 16
- TailwindCSS 3

## 部署说明
```bash
git clone ...
pnpm install
pnpm dev

已知限制

• 不支持 IE11
• 文件上传最大 10MB

---

## 三、与 Context Window 限制的斗争

### 3.1 4 大 LLM 致命痛点 + 3 文件解法

| 痛点 | 症状 | 3 文件解法 |
|---|---|---|
| **易失性记忆** | 多轮对话后变量定义遗忘 | 文件系统持久化,即使会话重置仍能恢复 |
| **目标漂移** | 50 步执行后忘记原始目标 | 强制 Read-Before-Decide |
| **错误隐藏** | API 调用失败后默默重试死循环 | Error Persistence 机制 |
| **上下文过载** | 5000 字协议全文塞进 Context | 数据卸载,仅保留关键结论 |

---

## 四、三层缓存模型

[1] Working Memory(工作记忆)

• 当前 Context Window
• 高频访问
• 容量有限 ↓ [2] Short-term Memory(短期记忆)
• task_plan.md + findings.md
• 中频访问
• 容量大(磁盘) ↓ [3] Long-term Memory(长期记忆)
• 历史项目 + 知识库
• 低频访问
• 容量无限

---

## 五、与其他 Skill 配合

| Skill | 配合方式 |
|---|---|
| **superpowers/brainstorming** | 用 brainstorming 探索需求后,planning-with-files 落地 |
| **superpowers/writing-plans** | writing-plans 的 task 拆解可写入 task_plan.md |
| **superpowers/verification-before-completion** | 在 deliverable.md 标注验证状态 |
| **OpenSpec** | OpenSpec 输出可整理到 findings.md |

完整工作流:

[1] brainstorming (需求探索) ↓ [2] 初始化 3 文件

• task_plan.md (目标 / 阶段)
• findings.md (知识调研)
• deliverable.md (成果占位) ↓ [3] writing-plans (任务拆解 → 写入 task_plan) ↓ [4] 实施
• 每步更新 task_plan 状态
• 失败记录到 Errors
• 新知识写入 findings ↓ [5] 验证
• verification-before-completion
• 更新 deliverable ↓ [6] finishing-a-development-branch (合并)

---

## 六、5 大反模式

### 6.1 3 文件全塞 Context

```python
# ❌ BAD - 把整个 task_plan / findings / deliverable 塞进 Context
prompt = f"任务计划:\n{task_plan}\n调研:\n{findings}\n成果:\n{deliverable}\n请..."
# Context 爆炸

解决:只读必要部分,用 Read 工具按需读。

6.2 任务粒度太粗

# ❌ BAD
- [ ] 实现贪吃蛇游戏

# ✅ GOOD
- [ ] 1.1 画网格
- [ ] 1.2 蛇移动逻辑
- [ ] 1.3 食物生成
- [ ] 1.4 碰撞检测
- [ ] 1.5 分数记录
- [ ] 1.6 难度选择 UI

6.3 不更新 task_plan

解决:每步完成后立即更新。

6.4 Errors 字段不写

# ✅ GOOD
## Errors / Blockers
- 2026-06-15 14:30: API 限流 429
  解决:加 retry with exponential backoff
- 2026-06-15 16:00: 内存爆炸 4GB
  解决:流式处理

6.5 deliverable.md 永远空

解决:每完成里程碑,更新 deliverable。

七、安装

# Clone 仓库
git clone https://github.com/OthmanAdi/planning-with-files.git

# 复制 skill 到 Claude 配置目录
cp -r planning-with-files/skills/* ~/.claude/skills/

# 或通过 npx
npx skills add othmanadi/planning-with-files

八、Q&A

Q: 跟 writing-plans 区别? A: writing-plans 是 1 个 plan;planning-with-files 是持续 3 文件工作流。

Q: 跟 OpenSpec 区别? A: OpenSpec 一次性 propose+archive;planning-with-files 持续追加。

Q: 必须用 Claude 吗? A: 任何支持 Skills 的 Agent 都可。目前已支持 Claude Code、Cursor、Codex、Gemini CLI、GitHub Copilot 等多个平台。

Q: 中文支持? A: 完美。3 文件可全中文。

本文基于官方文档和公开资料整理，未经过 MagicNetWorld 实测。

参考资料

• OthmanAdi/planning-with-files GitHub — 官方仓库
• zread.ai: planning-with-files 详解 — 功能详解
• GitRated: planning-with-files 分析 — 代码质量分析
• ExplainGit: planning-with-files 说明 — 项目说明
• OthmanAdi/planning-with-teams — 多 Agent 协作扩展