Task Plan: [项目描述]【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running agentic tasks. Crash-proof markdown plans that survive context loss and /clear, plus a deterministic completion gate and multi-agent shared state on disk. Manus-style. Works with Claude Code, Codex CLI, Cursor, Kiro, OpenCode and 60 agents via the SKILL.md standard.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-filesGoal[一句话描述最终目标]PhasesPhase 1: 需求分析与研究理解用户需求调研现有解决方案Status:in_progressPhase 2: 架构设计设计技术方案创建项目结构Status:pending**关键特性** - 阶段状态追踪pending → in_progress → complete - 技术决策记录表 - 错误记录表 - 自动重新注入机制通过钩子 ### 2. findings.md研究发现知识库 这是你的外部记忆存储所有研究结果和技术发现 markdown # 研究发现 ## 研究结果 - [日期] 发现1详细描述 - [日期] 发现2详细描述 ## 技术决策 | 决策 | 理由 | |------|------| | 使用Python而不是Node.js | 更好的数据处理库支持 | | 选择SQLite而不是PostgreSQL | 轻量级无需外部依赖 | ## 有用资源 - [链接1] 相关文档 - [链接2] 参考实现2-Action规则在每2次查看/浏览/搜索操作后必须立即更新findings.md文件防止视觉信息丢失。3. progress.md会话日志按时间顺序记录所有操作、测试结果和错误# 进度记录 ## 2026-06-17 19:30:00 ### Phase 1: 需求分析 - 分析了用户需求文档 - 创建了系统架构图 - 确定了技术栈选择 ## 测试结果 | 测试项 | 预期结果 | 实际结果 | 状态 | |--------|----------|----------|------| | 单元测试 | 100%通过 | 100%通过 | ✅ | | 集成测试 | 系统启动 | 系统启动成功 | ✅ | 技术架构与实现原理Planning-with-Files通过一系列钩子脚本实现自动化规划管理主要包含以下核心组件核心脚本模块初始化与配置scripts/init-session.sh- 创建新的规划会话scripts/set-active-plan.sh- 设置活动规划scripts/resolve-plan-dir.sh- 解析规划目录状态管理scripts/check-complete.sh- 检查任务完成状态scripts/phase-status.sh- 更新阶段状态scripts/ledger-append.sh- 追加运行日志安全与验证scripts/attest-plan.sh- 规划文件哈希验证scripts/gate-stop.sh- 完成门控检查钩子系统架构Planning-with-Files通过以下钩子实现自动化规划管理钩子名称触发时机功能描述SessionStart会话开始时通知技能已就绪PreToolUse执行工具前重新读取task_plan.md刷新目标PostToolUse执行工具后提醒更新阶段状态Stop尝试停止时验证所有阶段是否完成工作流程示意图用户请求复杂任务 ↓ 创建task_plan.md永远不要跳过这一步 ↓ 创建findings.md和progress.md ↓ ┌─────────────────────────────────────┐ │ 工作循环迭代 │ │ │ │ PreToolUse钩子 → 重新读取规划 │ │ ↓ │ │ 执行工作工具调用 │ │ - 研究 → 更新findings.md │ │ - 实现 → 更新progress.md │ │ ↓ │ │ PostToolUse钩子 → 提醒更新状态 │ │ ↓ │ │ 2次浏览器操作 → 必须更新findings.md │ │ ↓ │ │ 完成阶段 → 更新状态和日志 │ │ ↓ │ │ 发生错误 → 记录错误和解决方案 │ └─────────────────────────────────────┘ ↓ Stop钩子验证完成状态 ↓ 所有阶段完成 → 是任务完成交付成果 ↓ 否继续工作循环 高级功能V3自治和门控模式Planning-with-Files v3.0.0引入了革命性的自治和门控模式专门为长时间运行的AI代理任务设计自治模式Autonomous Mode./scripts/init-session.sh --autonomous 长期运行任务特性降低每次工具调用的规划重新注入频率仅在会话开始和阶段转换时注入规划适用于强大模型减少上下文开销门控模式Gated Mode./scripts/init-session.sh --gated 门控运行任务特性在停止时添加完成门控检查只有当五个条件同时满足时才阻止停止处于门控模式有进行中的阶段stop_hook_active为false阻止计数未超过上限运行日志自上次阻止后有进展防止不完整的规划导致会话卡死运行合同Run Contract自治模式引入了运行合同概念在规划文件中明确定义运行规则## Run Contract - **Mode:** gated - **Gate cap:** 20 - **Stall window:** 1 tick - **Attestation policy:** default-on - **Single-writer rule:** the orchestrator owns this file 多平台支持与安装Planning-with-Files支持60个AI代理平台通过SKILL.md开放标准实现一键安装# 标准安装 npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g # 中文版安装 npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zh -g支持的IDE平台增强支持钩子生命周期自动化Claude Code - 完整钩子支持Cursor - Skills hooks.jsonGitHub Copilot - 钩子配置Codex - Skills HooksGemini CLI - Skills HooksKiro - Agent SkillsOpenCode - 自定义会话存储标准代理技能支持Continue -.continue/skills/Pi Agent -.pi/skills/OpenClaw -.openclaw/skills/Antigravity -.agent/skills/Kilocode -.kilocode/skills/AdaL CLI -.adal/skills/ 性能与评估结果根据Anthropic的skill-creator框架评估Planning-with-Files在复杂任务中表现出色测试指标使用技能未使用技能通过率30个断言96.7%(29/30)6.7% (2/30)3文件模式遵循率5/5 评估0/5 评估盲测A/B获胜率3/3 (100%)0/3平均评分10.0/106.8/10️ 实战技巧与最佳实践1. 启动复杂任务的5步流程# 步骤1初始化规划会话 ./scripts/init-session.sh 后端重构项目 # 步骤2定义任务目标 # 编辑task_plan.md中的Goal部分 # 步骤3划分3-7个逻辑阶段 # 每个阶段都应该是可完成的 # 步骤4开始工作遵守2-Action规则 # 每2次浏览器操作后更新findings.md # 步骤5定期检查完成状态 ./scripts/check-complete.sh2. 并行任务隔离对于多个并行任务使用隔离的规划目录# 创建独立的规划目录 ./scripts/init-session.sh backend-refactor ./scripts/init-session.sh production-incident # 切换活动规划 ./scripts/set-active-plan.sh 2026-01-10-backend-refactor3. 会话恢复机制Planning-with-Files自动处理会话恢复检查IDE会话存储中的先前会话数据查找规划文件最后更新时间提取可能丢失的上下文对话显示恢复报告以便同步专业提示禁用自动压缩以最大化上下文{ autoCompact: false }4. 错误处理策略3次尝试协议尝试1诊断并修复尝试2使用不同方法尝试3重新思考方法所有错误必须记录在task_plan.md的Errors Encountered表中即使立即解决了也要记录。 5问题重启测试如果你的上下文管理是可靠的你应该能够回答这5个问题问题答案来源我在哪里task_plan.md中的当前阶段我要去哪里task_plan.md中的剩余阶段目标是什么task_plan.md中的目标声明我学到了什么findings.md我做了什么progress.md 常见陷阱与避免方法错误做法 vs 正确做法❌不创建task_plan.md就开始工作✅ 始终先创建规划文件❌忘记在2次浏览器操作后更新findings.md✅ 设置提醒2次查看/浏览操作 更新findings.md❌不记录错误因为快速解决了✅ 记录所有错误即使你立即解决了❌重复相同的失败操作✅ 如果某件事失败记录下来并尝试不同的方法❌只更新一个文件✅ 三个文件协同工作 - 作为一个集合更新它们 项目结构与核心模块Planning-with-Files项目采用模块化设计planning-with-files/ ├── commands/ # 插件命令 │ ├── plan.md # /planning-with-files:plan命令 │ ├── plan-zh.md # 中文/plan命令 │ └── start.md # /planning-with-files:start命令 ├── templates/ # 模板文件 │ ├── task_plan_autonomous.md # 自治模式模板 │ ├── analytics_findings.md # 分析任务模板 │ └── loop.md # 循环模板 ├── scripts/ # 核心脚本 │ ├── init-session.sh # 初始化会话 │ ├── check-complete.sh # 检查完成状态 │ ├── attest-plan.sh # 规划验证 │ └── gate-stop.sh # 门控停止 ├── skills/ # 技能变体 │ ├── planning-with-files/ # 英文默认 │ ├── planning-with-files-zh/ # 中文简体 │ └── planning-with-files-zht/ # 中文繁体 └── docs/ # 文档 ├── quickstart.md # 快速开始指南 ├── workflow.md # 工作流程图 └── installation.md # 安装指南 高级用例多代理协作Planning-with-Files v3支持多代理协作工作流协调者-工作者模式## Run Contract - **Single-writer rule:** the orchestrator owns this file - **Mode:** gated - **Attestation policy:** default-on规则协调者代理是task_plan.md的唯一写入者工作者子代理从不编辑task_plan.md工作者追加到自己的代理日志.planning/ /ledger- .jsonl状态更改通过scripts/phase-status.sh在写入锁下进行模型路由建议## Model Routing | Phase kind | Tier | Example model | |------------|------|---------------| | Research / triage / discovery | small-fast | Sonnet | | Build / implementation / verification | frontier | Opus or Fable 5 | 开始使用Planning-with-Files快速开始克隆仓库git clone https://gitcode.com/gh_mirrors/pl/planning-with-files安装技能npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g启动规划会话# 在Claude Code中使用 /planning-with-files:plan 构建Python REST API【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running agentic tasks. Crash-proof markdown plans that survive context loss and /clear, plus a deterministic completion gate and multi-agent shared state on disk. Manus-style. Works with Claude Code, Codex CLI, Cursor, Kiro, OpenCode and 60 agents via the SKILL.md standard.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考