核心定位
ia-planning 是一套面向 AI 辅助软件开发的系统化规划方法论，核心目标是通过文件化持久化（.plan/ 目录）解决大模型上下文窗口有限、易丢失的先天缺陷，将"内存思维"转为"磁盘思维"。
核心用法
1. Goal Quality Gate：五问过滤——明确成果物、验证证据、成功阈值、范围边界、需用户决策点，拒绝"改进 X"等纯活动型目标
2. 三级路径选择：
3. .plan/ 三文件结构：task_plan.md（阶段任务）、findings.md（研究发现）、progress.md（会话日志）
4. Plan Template 强制规范：含 Approach、Scope、Global Constraints、Key Decisions、File Structure、Phase（含 Files/Posture/Tasks/Verify/Exit）、Deferred、Open Questions
- Full plan（.plan/ 目录）：多文件变更、新功能、重构、>5 工具调用
- Flat list（行内清单）：3-5 文件、范围清晰、无研究
- Skip：单文件 typo、无关键决策、范围自明的原子操作
显著优点
- Token 经济学：规划 token 成本远低于实现 token，前置思考可规模化投入
- 决策显性化：Key Decisions 前置，避免返工；文件结构表锁定分解，防漂移
- 可验证性：每个阶段含 Verify 定义（如 "POST /api/users → 201"），拒绝"测试功能"模糊表述
- 任务原子化：2-5 分钟/任务，动词开头、文件路径明确、无 placeholder
- 安全网设计：3-尝试升级错误协议、5-问题上下文检查、恢复协议
潜在局限
- 仪式负担：小改动仍需判断路径，存在认知开销
- 模板刚性：强制结构对探索型任务可能过度约束
- 工具依赖：init-plan.sh 需正确配置 SKILL_DIR 绝对路径
- 未覆盖场景：纯研究/审计报告类工作（输出非代码）明确排除
适合人群
- 使用 Claude Code / Codex 等 AI 编码工具的中高级开发者
- 负责多文件重构、新功能模块、技术迁移的 Tech Lead
- 需要可审计、可交接的规范化开发流程的团队
常规风险
- 范围蔓延：8+ 文件或 2+ 新类/服务时强制挑战拆分
- Gold-plating：明确禁止超规格实现，要求一版基础实现
- 类型漂移：任务间命名不一致需显式检查
- KTD 遗漏："添加缓存"等看似简单需求常隐藏 TTL、失效策略等关键决策，需强制规划
安全与集成
- 安全等级 S：纯方法论，无代码执行
- 来源可信度 T1：Claude Code 官方技能集
- 关键集成：前置 ia-brainstorming，威胁建模时调用 ia-security-sentinel，架构决策走 ia-adr，执行走 /ia-work 或子代理