核心定位
ia-planning 是一套面向复杂软件工程的实现规划方法论，核心解决大语言模型"上下文窗口有限"与"复杂任务需要持久化思考"之间的矛盾。它将文件系统视为磁盘（持久、无限），将对话上下文视为内存（易失、有限），强制将重要决策写入磁盘。
核心用法
三层规划强度
- 完整规划（
.plan/目录）：多文件变更、新功能、重构、>5 次工具调用 - 扁平清单（对话内编号列表）：3-5 文件变更、范围清晰、无需调研
- 跳过规划：单文件编辑、快速查询、简单问题
`.plan/` 目录结构
通过 init-plan.sh 快速搭建，包含：
task_plan.md：阶段、任务、决策、错误记录findings.md：调研、发现、代码分析progress.md：会话日志、测试结果、变更文件
关键区分：.plan/ 是临时工作状态（不提交），docs/plans/ 是正式计划文档（可提交）。
显著优点
1. 上下文管理策略成熟：明确区分"内存"与"磁盘"，避免长会话中的信息丢失
2. 任务粒度控制严格：单任务限制 2 小时内，阶段限制 5-8 文件，防止过度膨胀
3. 垂直切片优先：按用户可见能力分解，而非技术层（"用户可登录"而非"先写数据库"）
4. 执行姿态信号：支持 test-first、characterization-first、external-delegate 三种模式，指导实现顺序
5. 交接仪式明确：计划完成后提供"子代理驱动"或"内联执行"二选一，避免自动漂移
6. 质量控制清单：7 项验证规则确保计划可被零上下文工程师执行
潜在局限
- 学习曲线陡峭：规则繁多（原子任务、动词优先、无占位符、类型一致性检查等），需要熟练度
- 过度工程风险：简单任务若严格遵循可能产生冗余文档
- 工具链依赖：依赖
init-plan.sh等配套脚本，跨环境迁移需适配 - AI 生成内容仍需人工校验："无占位符"规则理想化，复杂领域仍需人工补全细节
适合人群
- 处理 3+ 文件协同变更 的中大型功能开发
- 需要 跨会话持续工作 的长期项目
- 团队协作中需零上下文交接的场景
- 追求可审计、可回溯的工程实践
常规风险
| 风险 | 说明 |
|------|------|
| 计划漂移 | 实现偏离计划时未记录 `**Deviation**`，导致后续决策基于错误假设 |
| 阶段过大 | 未遵守 5-8 文件限制，导致单次会话无法完成 |
| 伪原子任务 | "实现功能"等模糊描述未拆分到"写失败测试"级别 |
| 进度文件失效 | 未及时更新 `progress.md`，跨会话重复探索 |
| 过度规划 | 对简单任务使用完整 `.plan/` 脚手架，产生无效开销 |
关键决策原则
Claude 决定：技术实现（语言、框架、架构、库、文件结构、测试策略）
用户决定：体验相关（范围权衡、UX 选择、数据模型决策、影响用户结果的路径）
执行衔接
计划完成后，推荐转入 workflows:work（子代理驱动）或 ia-orchestrating-swarms（多代理编排），或选择内联执行。