writing-plans

name	writing-plans
description	Use when Planning Gate triggers (affected files ≥3 or public API change) and an implementation plan is needed

Writing Plans

Type: Technique | Discipline: Rigid

指导如何写好一份实施规划。Planning Gate（见 using-growingio-sdk-skills meta-skill）定义 plan 的格式（四节结构），本 skill 定义内容质量。

核心原则： 写 plan 时多想 10 分钟，实施时少返工 1 小时。

影响面自查清单

按改动类型对照清单列全受影响的文件/路径：

改动类型	必须同时覆盖
公开 API 新增/改/删	模块根 .h（如 GrowingAutotracker/GrowingAutotracker.h）+ GrowingTrackerCore/Public/ + GrowingAutotrackerCore/Public/ + 相关 Modules/*/Public/ + podspec public_header_files + Package.swift targets
事件字段变更	SaaS / CDP 两产品线在"影响产品线"列显式标注（SaaS 用 projectId；CDP 额外需要 dataSourceId）
核心模块 (TrackerCore/Event/ TrackerCore/Database/ TrackerCore/Network/)	实现文件 + 对应 *Tests 目录
GrowingTrackConfiguration 变更	SaaS / CDP 两种模式的默认值；若涉及 useProtobuf，需同时验证 JSON / Protobuf 两条序列化路径
Autotrack 改动	iOS / macOS / tvOS 三平台 + Hybrid / WebCircle 模块（如适用）
Session 改动	前台触发 + 后台 / 终止 + sessionInterval（默认 30s，定义于 GrowingTrackerCore/GrowingTrackConfiguration.m）超时逻辑
事件上报改动	Protobuf 路径（Services/Protobuf/）+ JSON 路径（Services/JSON/），由 trackConfiguration.useProtobuf（默认 YES）切换；压缩/加密 adapter（Modules/DefaultServices/）
模块 (Modules/) 改动	podspec 对应 subspec + SPM target

任务拆分

拆成多任务： 变更逻辑独立且可并行 / 单任务描述 > 200 字还说不清。 合并为单任务： 接口与其使用者（拆开编译不过） / 同模块内部重构。

拆分后按 subagent-driven-development skill 判定是否走 subagent 模式。

Rationalizations

Excuse	Reality
"先动手改两个文件再补 plan"	≥3 文件动手那刻已经违规
"影响文件只列改到的源码"	头文件 / podspec / Package.swift / 测试都算影响
"公开 API 改只动实现文件"	必须同时更新公开头文件 + podspec
"这次规划口述就行"	必须落地到 docs/plans/YYYY-MM-DD-*.md
"事件字段只影响当前产品线"	两产品线字段要求不同，未标注 = 后端数据出错

Red Flags

• "先改两个文件试试，plan 后面再写" → Planning Gate 触发那一刻就必须先写 plan
• "影响面我心里有数" → 没列出来的文件 = 会返工的文件
• "这个字段只涉及 CDP" → 两产品线必须逐一确认

关联 skill

• 完成后交接： plan-document-review → 用户确认 → subagent-driven-development 或直接实施