用途
frontend-ai-guide 是一份面向 React/TypeScript 的前端 AI 开发指南，属于 shinpr/claude-code-workflows 工作流集合中的一个技能。它把前端开发中的技术决策标准、反模式检测、调试方法和质量门禁整理为可复用的规则，供在组件评审、缺陷调试和前端质量把控等场景中应用。核心立场是价值优先工程：在证据指向最低总复杂度、同时交付所需用户价值或维护者价值的前提下开展检查与修改。
主要能力
价值优先的工程原则
在确认范围或成果所需依赖内解决已证实的问题；其他发现只按其归属边界和证据报告，不扩大当前改动。只有当当前成果、已验证约束或证据支撑的实质风险需要时，才引入 state、props、变体、抽象或推测性边界处理。按每个被激活的用户决策、prop、state、变体、概念、输出、持久状态以及组件或 hook 路径，结合其 UX、运行时、实现、测试、文档与维护成本来评估总复杂度；只比较可行方案之间存在差异的维度。当复用或不引入新机制能以更低总复杂度交付相同价值与证明时，优先复用。
技术反模式（红旗模式）
代码质量类反模式包括：把同一 UI 职责分散在独立维护的多个组件中；单个组件混合多种职责（违反单一职责原则）；在多个组件中定义相同内容（违反 DRY）；变更前不检查依赖；用注释禁用代码；错误抑制（隐藏问题会积累技术债）；用类型断言代替保证；使状态归属模糊的 prop 透传链；组件混合独立变化的职责。设计类反模式包括：“先让它跑起来”的思维、补丁式实现、对不确定技术的乐观实现、治标不治本的修复、无计划的大规模改动。检测到这些模式时应暂停受影响的决策并审查设计。
兜底设计原则
核心是失败优先（Fail-Fast）：优先提升主代码可靠性，而非堆叠兜底实现。只有当已接受的需求、边界契约、项目策略或设计文档定义了降级结果与恢复责任人时，才实现兜底。渲染失败（含渲染期抛出的 hook）交由项目的错误边界处理；事件处理、普通异步回调、SSR 及渲染之外的 hook/API 操作，在拥有该职责的事件、hook、API 或服务端边界按错误契约处理。对重复或割裂既有恢复职责的 catch、或同一失败在多层被捕获而无单一恢复责任人、或嵌套处理器掩盖可见 UI 状态的情况，要求设计评审。兜底激活应通过边界上已有的 UI、日志或指标通道可观测。
代码重复与通用化判定
当相似性属于偶然或 UI 归属不同时，保持具体实现分离；当仓库证据显示存在共享交互、校验规则、视觉契约或协同变更职责时再合并。适合通用化的情况包括：业务逻辑重复、复杂处理算法、组件模式（表单字段、卡片等）、自定义 hook、校验规则。应避免通用化的情况包括：偶然相同的代码、可能朝不同方向演进、通用化显著降低可读性、测试代码中的简单辅助函数。
常见失败模式与规避
五种模式：错误修复链（表面修复引发新错误，应先用 5 Whys 定位根因）；绕过类型保证（用 any 或 as 声明无检查或契约支撑的类型，应让声明由检查或既有契约背书）；测试不足就实现（忽视 Red-Green-Refactor，新行为或可复现缺陷修复应先有失败测试，保行为重构需前后测试通过）；忽视技术不确定性（假定“按官方文档应该能跑”，应先记录确定性水平，低确定性时先写最小验证代码）；既有代码调研不足（实现前按领域、职责、组件模式等关键词搜索相似功能，按可复用、需扩展、应分离或应修复分别处理并保留证据）。
质量检查工作流
发现仓库配置的质量入口及其覆盖类别。适用检查类别包括：lint/format（项目配置的格式化器与 linter）、类型检查、构建（配置的生产或打包构建）、行为检查（覆盖变更行为的最小配置测试，跨越边界时加集成或 E2E 套件）。遵循仓库声明的命令组合或顺序；不存在时选择尊重命令依赖并提供有效反馈的顺序。完成要求所有适用的已配置检查通过。排障提示：端口被占用时停止持有端口的陈旧进程；缓存过期时使用项目的新鲜/清缓存选项重跑；依赖错误时清理并重装依赖。
技术决策
抽象时机：在仓库证据确立共享 UI 职责与协同变更模式后再提取共享抽象，注意 YAGNI，只实现当前需要的功能，优先当前简单性。性能与可读性：除非项目性能预算或 React DevTools Profiler 对比表明受影响交互存在有意义瓶颈，否则优先可读性；优化前先测量，优化时用注释记录原因。组件/类型粒度：过细会降低可维护性，应设计恰当表达 UI 模式的组件，优先组合而非继承。
影响分析流程
完成标准为完成三个阶段。对无共享契约、路由、状态归属或构建/配置影响的孤立组件改动，简明的搜索/检查笔记即可；跨组件或高风险改动使用结构化报告。三个阶段：发现（搜索仓库中对变更组件或 hook、其导入函数及 Props/State 类型的全部引用）、理解（阅读文件以确立调用方目的与上下文、组件层级、数据流 Props → State → 事件处理器 → 回调）、识别（跨组件或高风险改动产出结构化影响报告，含直接影响、间接影响与处理流程）。在范围、消费方、状态流、所需相邻改动与适用检查都识别后再继续。
未使用代码删除规则
当请求的改动使某组件、hook、工具函数、文档或配置项过时时，检查其消费方及生成/运维用途后删除。对不确定或超出范围的清理予以保留并报告；无关的休眠代码不纳入实现范围。既有代码删除决策：请求改动是否必需？否 → 除非变更证明其已过时，否则保留；是 → 是否可正常工作且兼容？是 → 修复/扩展；否 → 在具备迁移/回滚证据的情况下修复或替换。
使用方式
该技能以规则文档形式提供，在 React/TypeScript 前端开发与代码评审过程中作为技术决策、反模式识别和质量检查的参考依据。
适用场景
React/TypeScript 组件评审与设计、前端缺陷调试、前端质量门禁执行、影响分析与未使用代码清理决策。
限制
资料未提供具体的安装命令、依赖要求、收费方式或平台支持信息。