企业官网建设流程全解析

3个Markdown文件让AI智能体规划不断线

【免费下载链接】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

你让AI智能体连干两小时，回来它开口问"我们在做什么来着"——这不是模型笨，是上下文窗口天生易失：一次/clear、一次自动压缩、一次意外崩溃，之前立的计划就蒸发了。planning-with-files 的做法是把计划写进磁盘上的三个 Markdown 文件，并在每一轮对话开始时把计划重新注回上下文，让规划扛过上下文清空与压缩。

效果有实测数字：在仓库内置的恢复基准里，会话被强制中断后，新会话凭磁盘上的三个文件平均 5.0 轮就回到正轨，裸智能体要 13.3 轮；30 条可验证断言里，启用技能后通过 29 条，裸跑只通过 2 条（方法详见 docs/evals.md）。

先看清失忆的四类损失

把计划只留在窗口里跑长任务，你会反复撞上四个坑：

• 待办清单活在窗口里，窗口一清，清单跟着消失
• 50+ 次工具调用之后，最初的目标被后续细节挤出注意力，智能体开始"打偏"
• 错误不落盘，同一个坑第二次还得再踩一遍
• 所有信息都硬塞窗口，窗口填得更快，压缩来得更早

上下文窗口就那么点，你打算拿它扛多长的任务？这四个坑的根子其实是同一个：智能体把易失内存当成了档案库。对策也随之简单——把计划请出窗口，放到磁盘上。

核心机制：一份计划在盘上，每回合注入一次

整套机制的实体就是项目目录里的三个文件：

注意，这三个文件生成在你的项目目录里，技能目录只存放模板和脚本，别把它们埋进安装目录。

真正把循环转起来的是生命周期钩子（Claude Code 插件路线默认注册 5 个）：

每回合重注入是对抗"上下文腐化"的关键：对话越长，窗口里越早的指令越容易被挤掉，但目标和当前阶段状态是刚从磁盘读进来的，永远在注意力窗口里。

窗口真断了还有兜底。执行/clear或开新会话后，session-catchup 脚本会去 IDE 的会话存储里找上一次会话的数据，对齐三个文件的最后修改时间，提取中间发生过的工作，生成一份补位报告。智能体对照报告和git diff重新回答"我在哪、我做了什么"，然后直接续跑当前阶段——不用你再复述一遍需求。

让智能体自律的4条铁律

文件是骨架，规则才是肌肉。这些规则写进了 SKILL.md，靠钩子逐回合执行：

1. 无计划不开工——任务预计超过 3 步或 5 次工具调用，先把三个文件建出来再动手，顺序不可颠倒。
2. 2-Action 规则——每 2 次查看/浏览/搜索操作后，立即把关键发现写入findings.md。截图、PDF 和浏览器结果都不会持久化，不写下来等于没看过。
3. 三击错误协议——第一次失败：诊断修复；第二次：换方法；第三次：质疑前提。失败的原始动作不许原样重试，每个错误连同尝试次数、解决方式记进错误表，哪怕你十秒就修好了。
4. 不让智能体提前下班——gated 模式下只要还有 in_progress 阶段，Stop 钩子不放行；长时间无人值守跑任务时，还可以用/plan-attest给计划上 SHA-256 锁，被篡改的计划会拒绝注入。

再补一个实用技巧：同一个仓库并行跑多个任务时，给每个任务起一个 slug，文件会隔离到.planning/日期-slug/下，用set-active-plan.sh切换活动计划，两套工作互不踩踏。

场景走查：一次跨/clear的取消率归因

拿一个真实复杂度跑一遍：你给智能体一句话加一份全年订单流水 orders.csv——"查一下近 30 天订单取消率为什么涨了 20%"。

• 智能体用数据分析模板（仓库自带--template analytics）立出四个阶段：数据探查、探索分析、假设验证、报告输出。阶段一就发现承运商字段缺失 2000 行，数据质量问题与清洗口径当场写进findings.md。
• 阶段二做时间线拆解，尖峰集中在第 3 周；维度拆解把范围缩到一个物流区域，发现照样落盘。
• 这时上下文已经快满，你执行了/clear。新会话启动，session-catchup 读完三个文件与会话存储，补位报告明确写着：当前阶段三，假设"该区域取消率尖峰与某承运商时效劣化相关"尚未验证。智能体不问你要一句背景，直接从假设验证续跑。
• 阶段三用留出数据交叉验证假设，测试输入、预期、实际结果记入progress.md；阶段四产出报告：尖峰归因于某承运商区域时效劣化，附应对建议。

最后落盘的不只有一份能交付的报告，还有三个完整规划文件——人直接打开也能读懂整个推导过程，这算一个意外收获。

收束：计划住在智能体外面

带走三条要点就够了：

• 计划住盘上，回合回合注入，检索两次落盘一次
• 错误全部进表，失败动作不许原样重试
• 想收工先过闸门，让检查脚本替智能体把关

安装也是一行命令的事：npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g；Claude Code 走插件路线则钩子和斜杠命令一步到位，装完觉得钩子没动静，跑一次/plan-doctor自检（完整路线见 docs/installation.md）。

最后留一句可以贴在显示器上的话：脑子只记下一步，其余都落盘。上下文窗口是当班人的脑子，容量有限还会断片；三个 Markdown 文件是换班交接本，谁来接班都从本子上读起——没写进本子的，对下一个人来说就等于没发生过。

【免费下载链接】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