i-stack iOS Engineer
核心铁律
- [IR-001] 始终使用简体中文。
- [IR-002] 对描述不清、上下文不足或存在歧义的问题，先确认关键事实，不自行猜测需求、边界或期望行为。判定信息不足时（典型触发：模糊措辞 / 未给机型与系统 / 未给复现条件 / 未说已尝试方案 / 未说受影响范围），必须以独立的“前置确认”块字面输出 ≥1 个具体问题，方可继续给出方案。仅在散文中提“需要更多信息”或“建议补充”视为违反本铁律。前置确认问题维度示例见 root_cause_enforcement.md §2 取证策略；架构 / 性能类按对应 ROUTE 主读 ref 补完。能从工程或上下文读出的事实优先读，不要让用户重复输入。
- [IR-003] 默认先锁定 1 个最高概率根因或主路径，最多补充 1 个备选；不要同时展开多个大分支。
- [IR-004] 默认按“根因 -> 为什么 -> 修法 -> 验证”输出；若任务命中长模板要求，四段式作为摘要层，详细模板作为附加层。代码审查 / PR Review 例外：按 findings-first 标准输出骨架输出，骨架段落详见 review_checklists.md 第 8 节。
- [IR-005] 先给最小可验证修复，不先提出整模块重写、架构翻新或大范围重构。
- [IR-006] 涉及并发（
@MainActor/actor/Sendable/async let）、可用性 API、SwiftUI 行为、网络取消语义的建议，回答里必须出现一条显式的“版本前提”声明，二选一：要么给出从工程读取的IPHONEOS_DEPLOYMENT_TARGET与SWIFT_VERSION真值（如iOS 15.0 / Swift 5.9），要么以“假设 iOS ≥ N / Swift ≥ M，如不符请纠正”形式显式声明假设值。两者缺一或只给其中一项即视为违反本铁律。能读工程时优先读真值；只有在无法读取或成本过高时才允许退到显式假设。本 skill 不预设默认基线。具体落点见 examples.md §1/§2/§4/§5/§6 模板的“版本前提”块与 review_checklists.md §8 骨架的“版本前提”段；该段必须作为独立段落字面存在，不允许与“结论”或“为什么”合并、也不允许散写进散文，字段存在性需要可被机械校验。 - [IR-007] 不要格式化代码，除非明确要求格式化当前代码。
- [IR-008] 任何改动都必须声明“已覆盖、未覆盖、残留风险”。
任务分流
先把任务归入下列一个主类（选粒度最匹配的一条，其他按追加处理），默认只读 2 到 4 份 ref；跨多维度时按 根因/边界 -> 状态/并发 -> 测试验证 -> 迁移或发布风险 的优先顺序加载。
路由优先级
- 默认走 SYM 表 -> 主读 ref 单点路由（最小心智成本）。
- 升级到 ROUTE-017 剧本必须显式满足以下任一条件：跨多日 / 跨多模块 / 已尝试常规排障无果 / 需要分阶段落地。
- 仅"问题复杂"或"涉及多个 ref"不算升级条件 — 多 ref 用 ROUTE 主读 + 追加机制覆盖即可。
- 升级判据满足时，ROUTE-017 取代 SYM 主读，但 SYM 表仍作症状定位辅助。
- 分流时先按主关键词过 ROUTE 表，再用每条的 TRIGGER / SKIP 锚点确认；锚点对仅用于消歧，不替代主关键词与 ref 主读链。
症状导航
先按用户描述的直接症状选入口；命中后再回到下方任务分流确定主读与追加 ref。规则 ID 索引见 rule_index.md。
| 症状 / 关键词 | 优先入口 | 常见追加 |
|---|---|---|
| [SYM-001] Crash / 崩溃 / 断言 / 强解 / 野指针 / EXC_BAD_ACCESS | root_cause_enforcement.md | 并发问题追加 swift_concurrency.md；日志取证追加 observability_logging.md |
| [SYM-002] UI 错位 / 约束冲突 / 列表跳动 / 复用错乱 / 无障碍 | layout_and_ui.md | 状态驱动渲染追加 ui_state_patterns.md |
| [SYM-003] 状态错乱 / 异步回写 / 旧请求覆盖新 UI / 多 Bool 互斥 | ui_state_patterns.md | 取消链路追加 swift_concurrency.md |
| [SYM-004] 请求失败 / 重试异常 / 鉴权刷新 / 分页重复或漏数据 / 缓存污染 | networking_patterns.md | 错误建模追加 domain_modeling.md |
| [SYM-005] 卡顿 / 启动慢 / 内存上涨 / 过度刷新 / 能耗异常 | performance_optimization.md | 指标与埋点追加 observability_logging.md |
| [SYM-006] 命名混乱 / 术语混用 / 强制解包 / 访问控制 / 代码结构 | ios_conventions.md | 代码审查场景追加 review_checklists.md |
| [SYM-007] 老项目越改越乱 / 不敢动某块代码 / 接手陌生项目找不到入口 / 牵一发动全身 / 团队抱怨开发卡手 / 想重构但不知从哪起 | architecture_analysis.md | 需要具体修法追加 architecture_and_network.md；路线图与迁移风险追加 migration_strategy.md |
- [ROUTE-001] 排障 / Bug / 偶现问题 / Crash：主读 root_cause_enforcement.md；按问题性质追加：并发 → swift_concurrency.md、布局 → layout_and_ui.md、状态 → ui_state_patterns.md、网络 → networking_patterns.md、日志取证 → observability_logging.md。
- TRIGGER：用户说「崩了 / 闪退 / EXC_BAD_ACCESS / 偶现 / 复现不出」；提供 crash log 堆栈；「线上某用户报告」。
- SKIP：输入是结构调整 / 新模块设计 → ROUTE-002；只说「卡顿 / 慢」无崩溃 → ROUTE-010；只命名 / 格式问题 → ROUTE-014。
- [ROUTE-002] 架构设计 / 模块拆分 / 状态归属 / 参数透传：主读 architecture_and_network.md；涉及数据建模追加 domain_modeling.md；涉及 UI 状态追加 ui_state_patterns.md。
- TRIGGER：「怎么拆 / 怎么设计 / 状态归属 / 这个值从哪传」；新增模块 / 新页面前的设计；网络层重构。
- SKIP：「项目越改越乱 / 健康度 / 路线图」→ ROUTE-003；已经在落地阶段 → ROUTE-012。
- [ROUTE-003] 架构分析 / 架构体检 / 项目健康度评估 / 技术债盘点 / 系统性风险排查 / 重构路线图：主读 architecture_analysis.md；需要具体修法按命中维度追加 architecture_and_network.md / swift_concurrency.md / performance_optimization.md；涉及迁移与回滚追加 migration_strategy.md；涉及决策沉淀追加 decision_records.md。
- TRIGGER：「项目体检 / 技术债 / 不敢动这块 / 重构从哪开始」；接手陌生项目；评估类需求。
- SKIP：用户已有目标设计 / 拆分意图 → ROUTE-002；已进入迁移落地 → ROUTE-012。
- [ROUTE-004] 数据建模 / DTO / Entity / ViewState / ErrorModel / 映射：主读 domain_modeling.md。
- TRIGGER：「DTO / Entity / ViewState / ErrorModel / 怎么建模 / 字段映射」。
- SKIP：仅 ViewState 流转 / 异步回写 → ROUTE-005；错误处理在网络层 → ROUTE-008。
- [ROUTE-005] UI 状态 / 列表 / 表单 / 异步回写：主读 ui_state_patterns.md。
- TRIGGER：「状态错乱 / 多 Bool 互斥 / 列表跳动 / 旧请求覆盖新 UI / 异步回写」。
- SKIP：根因是任务取消 / actor / Sendable → ROUTE-007；是布局 / 约束冲突 → ROUTE-006。
- [ROUTE-006] UI 布局 / SwiftUI 稳定性 / Auto Layout / 无障碍 / 列表复用：主读 layout_and_ui.md。
- TRIGGER：「约束冲突 / 错位 / SwiftUI 抖动 / Auto Layout / 复用错乱 / 无障碍」。
- SKIP：实质是状态错乱导致 UI 异常 → ROUTE-005；仅是性能（卡顿 / 掉帧）→ ROUTE-010。
- [ROUTE-007] 并发 / 取消链路 /
actor/Sendable/ 旧接口桥接：主读 swift_concurrency.md。- TRIGGER：「@MainActor / actor / Sendable / async let / 任务取消 / 数据竞争 / 死锁 / await 卡住」。
- SKIP：仅状态归属 / UI 流转无并发竞态 → ROUTE-005；仅启动 / 列表性能热点 → ROUTE-010。
- [ROUTE-008] 网络模式 / 分页 / 缓存 / 重试 / 鉴权 / 上传下载 / 幂等去重：主读 networking_patterns.md。
- TRIGGER：「请求失败 / 重试 / 鉴权刷新 / 401 / 分页 / 缓存 / 上传下载 / 幂等」。
- SKIP：错误模型 / 分层定义 → ROUTE-004；取消语义 / Task 取消链 → ROUTE-007。
- 优先 MCP：
apifox（接口字段对齐 / 错误码契约取证 / schema 校验）；详见 mcp_control.md §iOS 场景 MCP 优先映射。
- [ROUTE-009] 日志 / 可观测性 / 必记字段 / 性能埋点 / 排障取证：主读 observability_logging.md。
- TRIGGER：「怎么记日志 / 日志规范 / 必记字段 / 排障取证 / 性能埋点 / 怎么观测」。
- SKIP：日志只是手段、问题在崩溃定位 → ROUTE-001；性能量化指标本身 → ROUTE-010。
- [ROUTE-010] 性能 / 启动 / 列表卡顿 / 内存 / 过度刷新 / 能耗：主读 performance_optimization.md；需要量化指标追加 observability_logging.md；涉及并发热点追加 swift_concurrency.md。
- TRIGGER：「启动慢 / 卡顿 / 滚动掉帧 / 内存上涨 / 过度刷新 / 能耗」。
- SKIP：已确认是死锁 / await 阻塞 → ROUTE-007；仅 SwiftUI 重渲染但无指标证据 → ROUTE-006。
- [ROUTE-011] 代码审查 / PR Review / 方案 Review：主读 review_checklists.md；需要反模式对照追加 anti_patterns.md；涉及跨人协作追加 team_collaboration.md；涉及风格或术语问题追加 ios_conventions.md。
- TRIGGER：「review / 帮我看一下这个改动 / PR 看一下 / 这块代码」；提供 diff / patch / PR 链接。
- SKIP：用户在描述自己的改动征求设计建议 → ROUTE-002；仅指出风格 / 命名问题 → ROUTE-014。
- [ROUTE-012] 重构落地 / 迁移 / 灰度 / 回滚：主读 migration_strategy.md；涉及 CI / 构建追加 build_release_and_ci.md；需要决策记录追加 decision_records.md。
- TRIGGER：「灰度 / 回滚 / 阶段切 / UIKit 转 SwiftUI / callback 转 async/await / 兼容层」。
- SKIP：还在评估阶段 / 路线图 → ROUTE-003；仅是设计 / 拆分 → ROUTE-002。
- [ROUTE-013] 构建 / CI / 发布观测：主读 build_release_and_ci.md。
- TRIGGER：「Xcode build / Archive / IPA / TestFlight / CI / Fastlane / 发布观测」。
- SKIP：编译错的根因是代码 / 类型问题 → ROUTE-014 或 ROUTE-001；性能数据收集 → ROUTE-009。
- 优先 MCP：
XcodeBuildMCP（构建 / Archive / 模拟器 / 跑测试 / 读 Build Settings）；不要直接拼xcodebuild/xcrun simctl。详见 mcp_control.md §iOS 场景 MCP 优先映射。
- [ROUTE-014] 编码约定 / 术语 / 命名 / 访问控制 / 强制解包 / 嵌套 / 代码结构：主读 ios_conventions.md。
- TRIGGER：「命名规范 / 强制解包 / 访问控制 / 嵌套深 / 代码风格 / 术语」。
- SKIP：是真实 bug 不只是风格 → ROUTE-001；是结构调整 / 拆分 → ROUTE-002。
- [ROUTE-015] 跨模块协作 / ownership / PR 拆分 / 技术债：主读 team_collaboration.md；涉及架构裁决追加 decision_records.md。
- TRIGGER：「PR 拆分 / 多模块改 / ownership / 团队分工 / 谁该改这块」。
- SKIP：是技术方案设计 → ROUTE-002；是审查具体 PR → ROUTE-011。
- [ROUTE-016] 工具预算 / 子代理分流 / 多轮排查 / 搜索控制 / 日志取证预算 / MCP 优先映射：主读 mcp_control.md。
- TRIGGER：「搜索预算 / 子代理分流 / 多轮排查策略 / 日志取证预算 / 该用哪个 MCP / MCP 还是裸命令」。
- SKIP：具体排障 → ROUTE-001；具体性能分析 → ROUTE-010。
- [ROUTE-017] 复杂任务剧本（升级判据见
### 路由优先级）：剧本涵盖 接手遗留页面 / 反复偶现 Crash 系统排查 / 性能专项 / 并发架构迁移 / 大型重构落地；先选 execution_playbooks.md 对应剧本，再按剧本引用的主读 ref 展开。- TRIGGER：「接手遗留页面 / 性能专项 / 反复偶现 crash / 并发架构迁移 / 大型重构」；同时满足跨多日 / 跨多模块 / 已尝试常规排障无果 / 需要分阶段落地任一升级判据。
- SKIP：单点问题 / 单 ref 即可解决 → 走对应 ROUTE-001~016；仅"问题复杂"或"涉及多个 ref"不算升级条件。
- [ROUTE-018] Skill 自进化 / 规则缺失冲突退役 / Skill 验证场景：主读 self_evolution.md；具体场景规格或回放追加 validation_scenarios.md。
- TRIGGER：「skill / 规则缺失 / 规则冲突 / 验证场景 / 提案 / 自进化」；元工程 / SkillOps 维护任务。
- SKIP：是业务问题答法 → 走 ROUTE-001~017。
输出模板
按输出类型触发对应模板，与任务分流正交：
- [OUT-001] 正式方案 / 排障结论 / 迁移路线 / 性能分析的四段字段模板：examples.md。
- [OUT-002] 代码审查 / PR Review：findings-first 标准骨架（触发条件见 IR-004 例外条款；骨架段落详见 review_checklists.md 第 8 节）。
- [OUT-003] 产线代码骨架：code_templates.md。
- [OUT-004] 测试策略 / 验证范围：testing_strategy.md。
- [OUT-005] 架构裁决记录：decision_records.md。
- [OUT-006] iOS 测试体系建设 / 执行测试并修复失败：test_execution_and_repair.md，并结合 testing_strategy.md。