核心定位
ia-planning 是一套面向 AI 辅助软件开发的轻量级规划方法论，核心解决「上下文窗口有限 vs. 复杂任务需要持久记忆」的矛盾。它将文件系统视为磁盘（持久、无限），对话上下文视为 RAM（易失、受限），强制将重要决策写入磁盘。
核心用法
1. 何时规划（When to Plan）
- 完整规划（.plan/ 目录）：多文件变更、新功能、重构、>5 次工具调用
- 扁平清单（内联任务列表）：3-5 文件变更、范围清晰、无需调研
- 跳过规划：原子级任务（单 commit、无设计决策、无范围边界争议），如「修复 README 第 47 行错别字」
关键启发：许多「看起来原子」的请求实际隐藏设计决策——如「给端点加缓存」涉及 TTL、失效策略、键设计，必须写计划。
2. 目标质量门控（Goal Quality Gate）
执行规划前必须通过 5 问检验：
1. 完成时什么具体事物将为真？（命名产物、系统状态、用户可见行为）
2. 什么证据能证明它？（具体测试、命令、截图、指标）
3. 量化的成功阈值是什么？
4. 哪些范围边界重要？（明确包含/排除）
5. 哪些决策必须问用户而非 AI 决定？
拒绝纯活动目标（「取得进展」「继续调研」），必须转化为可验证结果。
3. 规划文件结构
通过 init-plan.sh "Feature Name" 生成：
.plan/task_plan.md：阶段、任务、决策、错误.plan/findings.md：调研发现、代码分析.plan/progress.md：会话日志、测试结果、变更文件
重要区分：.plan/ 是临时工作状态（不提交），docs/plans/ 是正式规划文档（需提交）。
4. 计划模板核心要素
- Scope：明确 In/Out 边界
- File Structure：全量文件映射（创建/修改）+ 单行职责说明
- 分阶段（Phase）：每阶段 5-8 文件上限、2 小时内可完成、独立可交付
- 执行姿态（Posture）：test-first / characterization-first / external-delegate
- 零占位符规则：禁止 "TBD"/"TODO"/"类似上文"，每个任务必须自包含（具体文件路径、代码模式、命令）
5. 垂直切片 vs. 水平切片
- 垂直切片：按用户可见能力分解（如「用户可以登录」同时触及 UI/API/DB），每片独立可演示
- 水平切片：按技术分层（「建完所有模型」）在计划中被禁止——零价值交付直至全部完成
6. 决策权限分配
- AI 决定：技术实现细节（语言、框架、架构、库、命名、测试策略、错误处理）
- 用户决定：影响用户体验的权衡（范围裁剪、UX 选择、数据模型约束未来产品选项）
启发式：改变用户体验 → 问用户；改变代码工作方式 → AI 决定。
显著优点
1. 上下文安全：通过磁盘持久化防止长会话中的记忆丢失，支持会话中断后无缝恢复
2. 成本优化：规划 token 成本远低于实现 token，前置思考减少返工
3. 强制清晰：5 问门控和零占位符规则消除模糊目标导致的无效工作
4. 可追溯性：SHA 记录（Task 1.1 abc1234``）和偏差文档化建立计划→代码的信任链
5. 弹性执行：支持子代理并行（external-delegate）或主会话串行执行
潜在局限
1. 仪式开销：小任务可能感觉「过度规划」，作者明确承认「薄规划对小工作是轻度仪式」作为权衡
2. 学习曲线：需要掌握垂直切片、执行姿态、门控检查等概念，新手易混淆 .plan/ 与 docs/plans/ 的用法区别
3. 工具依赖：依赖 init-plan.sh 和特定目录结构，非 Unix 环境或禁 shell 场景需适配
4. 「弱目标」识别主观：虽然提供 5 问框架，但「是否比『修复第 47 行错别字』更模糊」的判断仍需经验
适合人群
- 使用 AI 编码助手处理多文件复杂变更的开发者
- 需要中断/恢复长周期功能的团队（支持编号中间文件如
01-setup.md） - 追求计划→实现→验证闭环而非即兴编码的工程文化
- 需要并行执行（多子代理）的复杂项目协调者
常规风险
- 计划漂移：实现偏离计划时若未文档化偏差（
**Deviation**: ...），将破坏协调者信任 - 过度工程：忽视「跳过规划」条件，对真正原子的任务仍创建
.plan/结构 - 范围蔓延：未严格执行「无镀金」规则，在计划中偷偷加入非需求功能
- 恢复失败：会话恢复时未按流程读取
.plan/progress.md→ 检查完成状态 → 审阅当前阶段，导致重复或遗漏工作