🗂️ 快速定位 >>>

• 一句话理解：不是"自动生成计划"，而是把 AI 的临时上下文变成可恢复的文件化流程，v3 增加了 autonomous/gated 两种运行模式。
• 核心指标：⭐ 24,374 | Benchmark 96.7%（v2.21.0, claude-sonnet-4-6）| A/B 3/3 胜出 | SkillCheck 验证通过 | 安全审计通过
• npx skills add ... /plan <任务>：→ → 按三个文件工作
• --autonomous --gated：无 mode 标记 = 原样 v2.43 行为，新增 / 才激活新模式

🚀 安装

一行安装（通用，适用 Claude Code / Codex / Cursor 等）

npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

Claude Code 完整插件（含 /plan 命令）

/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

平台快速对照

多语言版本

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zh -g   # 简体中文
npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zht -g  # 正體中文
npx skills add OthmanAdi/planning-with-files --skill planning-with-files-ar -g   # العربية
npx skills add OthmanAdi/planning-with-files --skill planning-with-files-de -g   # Deutsch
npx skills add OthmanAdi/planning-with-files --skill planning-with-files-es -g   # Español

验证安装

/planning-with-files:plan

💾 核心心智模型

v3 三种运行模式（新增）

Gated 模式门控条件（5 个同时满足才阻塞）

Host 能力分级

📄 三个核心文件

task_plan.md — 任务总控

# Task Plan

## Goal
说明本次任务的最终目标。

## Phases
### Phase 1: 需求理解与调研
- [ ] 明确输入和约束
- [ ] 阅读相关文件
- **Status:** in_progress

### Phase 2: 实现
- [ ] 修改核心逻辑
- [ ] 补充测试
- **Status:** pending

## Decisions
| Time | Decision | Reason |
|---|---|---|

## Errors Encountered
| Time | Error | Attempted Fix | Resolution |
|---|---|---|---|

• task_plan.md
• [x] complete
• Errors Encountered
• Decisions

findings.md — 研究发现仓库

# Findings

## Research Findings
- 发现 A：xxx
- 发现 B：xxx

## Technical Decisions
| Decision | Reason | Source |
|---|---|---|

## Useful Resources
- 文档链接
- API 说明
- 相关代码位置

读了两个文件     → 更新 findings.md
查了两个网页     → 更新 findings.md
看了两个错误日志 → 更新 findings.md
比较了两个方案   → 更新 findings.md

progress.md — 执行日志和恢复入口

# Progress

## Current Status
当前处于 Phase 2，实现核心逻辑。

## Session Log
| Time | Action | Files Modified |
|---|---|---|

## Test Results
| Time | Command | Result | Notes |
|---|---|---|---|

## Error Log
| Time | Error | Resolution |
|---|---|---|

## Resume Checklist
- Where am I?
- What is the next action?
- What did I already test?
- What remains incomplete?

• progress.md
• findings.md
• task_plan.md

v3 新增字段（Autonomous / Gated 模式）

### Phase 2: 实现
- **Status:** in_progress
- **DependsOn:** Phase 1
- **Owner:** agent-frontend
- **AcceptanceCheck:** npm test -- --grep "login"

最短工作流

Step 1：启动计划

/plan 实现一个用户登录页面，包含表单校验、接口对接、错误提示、单元测试

Step 2：拆分阶段

## Phases

### Phase 1: 需求确认
- [ ] 明确输入字段
- [ ] 明确校验规则
- [ ] **Status:** in_progress

### Phase 2: 技术调研
- [ ] 阅读现有代码
- [ ] 对比 API 文档
- **Status:** pending

### Phase 3: 组件实现
- [ ] 实现核心逻辑
- [ ] 实现校验
- **Status:** pending

Step 3：边做边写

创建三个文件
    ↓
进入迭代工作循环
    ↓
关键操作前读取 task_plan.md
    ↓
调研后更新 findings.md（每 2 次操作）
    ↓
实现后更新 progress.md
    ↓
阶段完成后更新 task_plan.md 和 progress.md
    ↓
错误发生后写入两个文件
    ↓
Stop Hook 检查阶段是否全部完成

Step 4：恢复上下文

请基于 task_plan.md、findings.md、progress.md 回答：
1. 当前任务目标是什么？
2. 当前处于哪个阶段？
3. 已经完成了什么？
4. 发现了哪些关键结论？
5. 下一步最小动作是什么？

Step 5：完成检查

ls -la task_plan.md findings.md progress.md

v3 Attestation（计划完整性哈希）

# 手动重新哈希（修改计划后必须）
./scripts/attest-plan.sh

# 查看当前哈希
./scripts/attest-plan.sh --check

常用提示词模板

启动复杂开发任务

请使用 planning-with-files 工作流处理这个任务。

任务：实现一个 Vue3 + ElementPlus 的可视化表单设计器。
要求：
1. 先创建 task_plan.md、findings.md、progress.md
2. task_plan.md 拆分为 4-6 个阶段
3. 每阅读 2 个文件或搜索 2 次后，更新 findings.md
4. 每完成一个阶段，更新 task_plan.md 和 progress.md
5. 遇到错误必须记录到 task_plan.md 和 progress.md

启动代码排错任务

请使用 planning-with-files 工作流排查这个问题。

问题：项目启动时报错 xxx。
要求：
1. 先创建 task_plan.md、findings.md、progress.md
2. 不要直接改代码，先阅读相关配置和错误日志
3. 每两个排查动作后更新 findings.md
4. 每次失败尝试都记录到 Errors Encountered
5. 最后给出根因、修改点、验证命令和回滚方案

让 Agent 恢复任务

请读取当前项目的 task_plan.md、findings.md、progress.md，恢复上下文。
请输出：
1. 当前目标
2. 已完成阶段
3. 当前阶段
4. 关键发现
5. 未解决问题
6. 下一步建议

强制防止目标漂移

在继续之前，请先重读 task_plan.md。
然后回答：
1. 当前操作是否仍然服务于原始目标？
2. 是否存在目标漂移？
3. 是否需要调整计划？
如果需要调整，请先更新 task_plan.md，再继续。

结束前检查

请执行 planning-with-files 完成检查：
1. 检查 task_plan.md 中所有 Phase 是否 complete
2. 检查 progress.md 是否记录了每个阶段的执行动作
3. 检查 findings.md 是否包含关键技术结论
4. 如果未完成，请列出 remaining tasks
5. 如果完成，请输出最终交付摘要

Benchmark 数据

常见坑点

改了 task_plan.md 但注入内容不变

./scripts/attest-plan.sh

Stop Hook 不生效（Claude Code 正常，但其他平台无反应）

上下文压缩后丢失计划

{ "autoCompact": false }

v2 → v3 迁移后旧文件不能用

Windows Git Bash 安装失败（hooks 脚本无执行权限）

chmod +x .claude/hooks/planning-with-files/*.sh

社区 Fork 与扩展

v2 → v3 迁移速查