核心机制
ia-planning 是一套面向 AI 辅助软件开发的结构化规划方法论，核心解决「上下文窗口有限 vs 复杂任务需要持久化状态」的矛盾。它将上下文窗口视为易失的 RAM，文件系统视为无限容量的 Disk——所有重要决策、发现、进度均写入 .plan/ 目录，实现跨会话的状态恢复。
关键设计
目标质量门（Goal Quality Gate）：强制回答 5 个问题后才允许规划——具体成果物、验证证据、成功阈值、范围边界、需用户决策点。拒绝纯活动型目标（如"改进 X"），必须转化为可验证结果。
三级规划策略：
- 完整计划（.plan/ 目录）：多文件变更、新功能、重构、>5 个工具调用
- 扁平清单（内联检查表）：3-5 文件变更、范围清晰、无需研究
- 跳过规划：单原子提交、无关键技术决策、无范围歧义（如修复拼写错误）
阶段 sizing 规则：每阶段最多 5-8 文件、最多 2 个跨阶段依赖、单任务≤2 小时，确保上下文安全。
模板化输出
.plan/ 包含三文件：
task_plan.md：阶段、任务、决策、错误findings.md：研究发现、代码分析progress.md：会话日志、测试结果、文件变更
正式计划输出至 docs/plans/（可提交），.plan/ 为临时工作态（加入 .gitignore）。
质量约束
- 禁止占位符：任务必须含具体代码模式、命令、文件路径，禁 "TBD/TODO/适当处理错误"
- 类型一致性检查：跨任务函数名、变量名必须一致
- 垂直切片：按用户可见能力分解，非技术分层
- 检查点机制：每 2-3 任务暂停验证集成
- 偏差文档化：实施偏离计划时必须 inline 记录原因
决策权限划分
| Claude 决定 | 用户决定 |
|------------|---------|
| 语言、框架、架构、库、文件结构、命名、测试策略、错误处理、数据库细节 | 范围权衡、UX 选择、数据模型决策、影响用户 outcome 的选项 |
执行交接
计划完成后提供两种模式：
1. 子代理驱动（推荐）：多阶段/独立切片/隔离工作树，每阶段分派专注子代理
2. 内联执行：主会话逐阶段运行，适用于紧耦合或单会话可完成的工作
集成扩展
/ia-adr：重大架构决策记录ia-security-sentinel：auth/支付/外部 API 的 threat modelingia-brainstorming：需求模糊时的前置步骤ia-writing：计划文档润色/ia-work：计划批准后执行
局限与注意
- ceremony 开销：小变更的轻量计划仍有固定成本
- 模板依赖：需 init-plan.sh 或手动维护 .plan/ 结构
- 不适用场景：纯研究/扫描/审计工作（产出报告而非代码）、单文件拼写修复
- 学习曲线：质量门、垂直切片、决策权限等规则需熟悉后才高效
适合需要可追溯、可恢复、可协作的中大型软件变更场景，对「代码即对话」的轻量模式形成互补。