核心概览
ia-planning 是一套面向复杂软件开发的结构化规划方法论，核心目标是通过文件持久化和严格的分阶段控制，解决大语言模型上下文窗口有限、易丢失状态的问题。其核心理念是：将上下文窗口视为易失的 RAM，文件系统视为持久的 Disk——所有重要信息必须写入磁盘。
核心用法
三层规划策略
- 完整规划（.plan/ 目录）：多文件变更、新功能、重构、>5 次工具调用
- 扁平清单（内联检查表）：3-5 个文件变更，范围清晰，无需调研
- 跳过规划：单文件编辑、快速查找、简单问题
规划文件结构
使用 init-plan.sh 脚手架生成 .plan/ 目录，包含：
task_plan.md：阶段、任务、决策、错误记录findings.md：调研、发现、代码分析progress.md：会话日志、测试结果、文件变更
重要区分：.plan/ 是实施期间的临时工作状态（不提交），docs/plans/ 是 workflows:plan 生成的正式计划文档（需提交）。
显著优点
1. 上下文安全性：通过文件持久化规避模型上下文压缩导致的状态丢失
2. 成本效率：规划 token 远低于实施 token，前置思考降低返工
3. 严格质量控制：
4. 垂直切片：按用户可见能力分解，而非技术分层，确保每阶段交付可演示价值
5. 阶段安全边界：每阶段最多 5-8 个文件、2 个跨阶段依赖、单次任务 ≤2 小时
- 禁止占位符任务（"TBD"/"TODO"/"add validation"）
- 强制命名一致性检查
- 类型一致性验证
潜在局限
1. 开销成本：简单任务可能过度规划，明确建议跳过单文件修复
2. 学习曲线：严格的模板和规则需要适应期
3. 工具依赖：依赖 shell 脚本和特定文件结构，跨平台需适配
4. 敏捷张力：重型规划流程可能与快速迭代需求冲突
适合人群
- 处理复杂多文件变更的开发团队
- 需要严格状态管理的长期项目
- 上下文窗口受限的 LLM 辅助开发场景
- 追求可审计、可追溯实施过程的工程文化
常规风险
1. 规划漂移：实施偏离计划时未记录原因，破坏信任链
2. 范围蔓延：未明确标记的"锦上添花"功能偏离核心需求
3. 过度工程：对简单任务套用完整规划流程
4. 文件冲突：.plan/ 与 docs/plans/ 概念混淆导致提交错误
5. 会话连续性中断：未按规范更新 progress.md 导致恢复困难
关键集成
- 前置：
ia-brainstorming（需求模糊时） - 并行：
ia-adr（架构决策）、ia-security-sentinel（威胁建模） - 后置：
workflows:work（实施执行）或ia-orchestrating-swarms（子代理编排） - 辅助：
ia-writing（优化文档语言）