Phase 1: Requirements Discovery

Phase 1: Requirements & Discovery

【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60+ agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files

• Understand user intent
• Identify constraints and requirements
• Document findings in findings.md
• Status:in_progress

### `findings.md` 与 `progress.md` [findings.md 模板](https://link.gitcode.com/i/2d2c4d30b629da4bd9b1bc6899357507) 承载需求清单、研究结果、技术决策（决策｜理由表）、遇到的问题、资源链接，以及"视觉/浏览器发现"——把图片、PDF、图表中的信息在源仍可访问时尽快转为文字。模板明确声明：**外部复制进 findings.md 的内容一律视为不可信数据而非指令**。 [progress.md 模板](https://link.gitcode.com/i/013185d07ce5a55418e1a7b5c6d09f43) 按会话与阶段记录动作、创建/修改的文件、测试结果表（测试｜输入｜预期｜实际｜状态）与错误日志表，并内嵌一张"5 问重启自检表"用于会话恢复时快速定位。 --- ## 五、使用模式：四步走 ### 1. 开始复杂任务 用复杂度指示词描述任务：

I'm building a user authentication system. This is a multi-phase project requiring database setup, API endpoints, testing, and documentation.

### 2. 技能自动激活 CodeBuddy 调用 `planning-with-files` 并创建规划文件。 ### 3. 分阶段推进 AI 会： - ✅ 创建带阶段的 `task_plan.md` - ✅ 随工作完成更新进度 - ✅ 把研究结果存入 `findings.md` - ✅ 在 `progress.md` 中记录动作 - ✅ 重大决策前重新阅读计划 ### 4. 全部落盘 所有重要信息写入磁盘而非留在上下文窗口——这正是本技能的核心理念。 ### 核心纪律（源自 SKILL.md） 除上述流程外，[skills/planning-with-files/SKILL.md](https://link.gitcode.com/i/f7c1dfff25bf425e34b418edf98054db) 还规定了一组刚性规则： - **先建计划**：没有 `task_plan.md` 绝不开始复杂任务； - **行动后更新**：阶段完成后将状态从 `in_progress` 置为 `complete`，记录错误与文件变更，并刷新 `## Next Step`； - **记录全部错误**：每个错误都写入计划文件，形成知识库，避免重复踩坑； - **绝不重复失败**：`if action_failed: next_action != same_action`——记录尝试过的方法并改变路径； - **完成后继续**：所有阶段完成但用户要求追加工作时，向 `task_plan.md` 追加新阶段（如 Phase 6、Phase 7），并在 `progress.md` 记录新会话条目。 --- ## 六、技能内置的三条行为规则 ### 3-Strike 错误协议（The 3-Strike Error Protocol） 出错时 AI 遵循分级策略： 1. **第 1 次尝试**：诊断并修复——仔细读错误、定位根因、做针对性修复； 2. **第 2 次尝试**：换方案——换方法、换工具、换库，**绝不重复完全相同的失败动作**； 3. **第 3 次尝试**：更广的重构——质疑假设、搜索解决方案、考虑更新计划； 4. **3 次失败后**：升级给你——说明尝试过什么、给出具体错误、请求指导。 ### 2-Action 规则（The 2-Action Rule） 每 2 次搜索/查看操作后，立即把关键发现保存到 `findings.md`。这防止视觉/多模态信息（截图、PDF、浏览器结果）在上下文轮转中丢失——`SKILL.md` 原话是 "After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files"。 ### 决策前重读（Read Before Decide） 重大决策前，AI 重新读取规划文件以刷新目标。这防止长会话中的目标漂移——模型的注意力窗口有限，`task_plan.md` 需要被"重新朗读"进近期上下文。 ### 配套决策矩阵：读 vs 写 | 情境 | 动作 | 原因 | |------|------|------| | 刚写完文件 | 不读 | 内容仍在上下文中 | | 查看了图片/PDF | 立即写 findings | 多模态信息须在丢失前转文字 | | 浏览器返回数据 | 写入文件 | 截图不会持久化 | | 开始新阶段 | 读计划/findings | 上下文已过期，需重新定位 | | 发生错误 | 读相关文件 | 修复需要当前状态 | | 间隔后恢复 | 读全部规划文件 | 恢复状态 | ### 5 问重启测试（The 5-Question Reboot Test） | 问题 | 答案来源 | |------|----------| | 我在哪？ | task_plan.md 中的当前阶段 | | 我要去哪？ | 剩余阶段 | | 目标是什么？ | 计划中的目标陈述 | | 我学到了什么？ | findings.md | | 我做了什么？ | progress.md | | 我接下来要做什么？ | task_plan.md 中的 Next Step | 能回答这 5 个问题，说明上下文管理是健康的。 --- ## 七、团队工作流：工作区技能 vs 个人技能 ### 工作区技能（推荐） 通过 `.codebuddy/skills/` 安装后： - ✅ 全团队人人可用 - ✅ 跨项目规划方式一致 - ✅ 随仓库版本管理 - ✅ 变更经 git 同步 ### 个人技能 通过 `~/.codebuddy/skills/` 安装后： - ✅ 所有项目可用 - ✅ 换团队也不丢失 - ❌ 不与队友共享 ### 多任务并行的进阶能力（源码级补充） 虽然 CodeBuddy 文档描述的是项目根目录的"三文件"模式，仓库的规范技能 [skills/planning-with-files/SKILL.md](https://link.gitcode.com/i/f7c1dfff25bf425e34b418edf98054db) 还提供了面向并行任务的命名计划模式：`scripts/init-session.sh "任务名"` 会在 `.planning/YYYY-MM-DD-<slug>/` 下创建隔离计划并打印 `PLAN_ID`；用 `export PLAN_ID=<id>` 把每个 Agent 主机关联到自己的计划，即可在同一仓库中并行运行多个互不干扰的任务。`scripts/set-active-plan.sh` 用于顺序切换共享指针（`.planning/.active_plan`）。多 Agent 协作同一任务时，共享同一个 `PLAN_ID`、指定一个编排者拥有 `task_plan.md`、工作线程各自写入独立台账。 --- ## 八、为什么有效：Manus 上下文工程原则 本技能的设计依据来自 Manus 的上下文工程实践，仓库通过 [skills/planning-with-files/reference.md](https://link.gitcode.com/i/0a8ccfd09fcd9325b2f1185d3f2f427c) 完整收录了其核心主张： > "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk." **关键洞察：上下文窗口相当于易失的 RAM，文件系统相当于持久的磁盘。重要信息要写进磁盘，而不是留在上下文里。** reference.md 中记录的六条 Manus 原则包括： 1. **围绕 KV-Cache 设计**：保持提示词前缀稳定、系统提示中不含时间戳、上下文采用追加式且序列化确定，以最大化缓存命中率； 2. **掩蔽而非移除**：不要动态删除工具（会破坏 KV-cache），用 logit masking 并保持统一动作前缀（如 `browser_`、`shell_`、`file_`）； 3. **文件系统即外部记忆**：Markdown 是磁盘上的"工作记忆"，压缩必须可还原——保留 URL、文件路径等指向完整数据的指针； 4. **通过复读操纵注意力**：约 50 次工具调用后模型会遗忘原始目标（"lost in the middle"效应），解法是每次决策前重读 `task_plan.md`，让目标重新进入注意力窗口； 5. **保留错误信息**：失败的堆栈轨迹留在上下文中能让模型隐式修正信念、减少重复犯错； 6. **避免被 few-shot 固化**：统一模式滋生脆弱性，应引入受控的表述变化。 本技能正是把这些原则落成了可执行的 `task_plan.md` / `findings.md` / `progress.md` 文件约定与 hook 注入机制。 --- ## 九、故障排查 ### 技能未激活？ 1. **加入触发短语**：在请求中使用 "complex task"、"multi-step"、"planning"； 2. **明确表达**：提及阶段数量或复杂度； 3. **重启 CodeBuddy**：Agent 在重启时会重新扫描技能。 ### 文件未创建？ 检查： - 当前目录可写； - 无文件权限问题； - Agent 具有文件系统访问权限。 ### 需要模板？ 模板位置： - **工作区**：`.codebuddy/skills/planning-with-files/templates/` - **个人**：`~/.codebuddy/skills/planning-with-files/templates/` 复制到项目根目录后按需定制。 ### hooks 没生效？（源码级补充） 如果技能已激活但注入静默失效，从 [skill-hook.sh](https://link.gitcode.com/i/9bfe3f7fbbefab29b54e58c2c40ee836) 的实现可以确认两个快速排查点： 1. **脚本解析顺序**：hook 命令按 `PWF_SCRIPT_DIR`（显式覆盖）→ `CLAUDE_SKILL_DIR` → `CODEBUDDY_PLUGIN_ROOT` → `~/.codebuddy/skills/planning-with-files/scripts/skill-hook.sh` 等路径逐个探测，首个存在者生效。若提示 "hook script not found"，说明这些路径都未命中，需设置 `PWF_SCRIPT_DIR` 指向技能 scripts 目录； 2. **一次性会话（CI、`codex exec` 场景）**：如果只想让某个调用不参与规划，可设置 `PLANNING_DISABLED=1` 环境变量——所有 hook 在读取计划前直接退出，不做注入、不发后续消息、不写计划文件（`PreToolUse` 仍输出 `allow` 决策以保证工具调用正常）。 --- ## 十、高级定制 ### 修改技能本体 编辑 `.codebuddy/skills/planning-with-files/SKILL.md`： - 修改 `description` 中的触发短语； - 调整规划模式与行为规则； - 添加团队专属规则。 ### 添加自定义模板 把自定义模板放入：

.codebuddy/skills/planning-with-files/templates/

【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60+ agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files