用途
这套规则用于指导 React 与 TypeScript 前端开发的实现与代码评审，目标是在类型安全、组件可维护性、状态归属、异步与错误处理、性能优化等方面形成一致的工程约定。规则本身强调：当与既有项目约定或组件职责冲突时，既有约定优先。
主要能力与规则内容
注释规则
代码优先：命名与类型承载语义，注释只补充代码无法表达的内容，一个决策一条注释即可。注释应解释组件为何做记忆化、守卫或重渲染，而不是描述 JSX 渲染了什么；记录决策与理由，时间顺序的历史交给版本控制。
类型安全
默认规则是优先使用 unknown、泛型或联合类型，而非 any。仅在以下情形保留 any：既有外部、生成或遗留的公共签名要求；或替换 any 会导致项目类型检查无法表达安全的泛型关系。此时需记录证明该约束的声明路径或类型检查结果。若局部适配器能在兼容的前提下暴露更安全的类型，应实现该适配器；否则将 any 限制在最小的适配器或公共签名边界内，记录原因，并确保不可信数据在进入有类型的应用代码前完成校验。
前端边界
- React Props/State：使用声明好的应用类型。
- 外部 API 响应：把未校验的载荷视为 unknown，在边界处校验；生成式客户端若在运行时也强制契约，则可保留其声明类型。
- localStorage / sessionStorage：处理 string | null，解析后的数据在校验前视为 unknown。
- URL 参数：先处理路由或平台的可空字符串形态，解析并校验后再转换为领域类型。
- 对外导出的 API 与重要边界：声明返回类型；局部实现若契约清晰，允许依赖类型推断。
类型复杂度评审信号
以下作为评审提示而非通过或不通过的阈值，既有项目约定与组件职责优先：Props 超过 10 个时复核归属或拆分；可选 Props 超过一半时复核默认值或归属；嵌套 Props 结构超过两层时复核扁平化；需要 3 个以上类型断言时复核边界；外部 API 类型应表达真实外部形态并在应用边界转换。
编码约定
组件与文件：新代码优先使用函数组件与 Hooks；除已接受的工作要求迁移外，保留可运行的 class 组件，class 在实现 Error Boundary 时仍然有效；通过仓库既有的组件、Hook 或模块模式复用逻辑；遵循项目已采纳的组件架构与文件布局，只有在既定或获批为新结构时才采用同目录放置。
服务端与客户端边界（仅适用于 RSC 框架）：默认在服务端获取并渲染，把交互性隔离在最小的需要 use client 的边界内；仅浏览器可用的 API 与事件处理器保留在客户端组件内；项目没有服务端组件运行时则跳过这些规则。
状态归属：保留仓库现有的本地、共享与服务端状态归属边界；只有已接受的设计需要既有边界无法表达的归属或生命周期时，才引入 Context、共享状态层或服务端状态依赖；每个状态值保持唯一权威所有者，并使用 React 变更检测所需的不可变更新。
函数与 Props 边界：优先 0 到 2 个参数；3 个以上相关值时，若对象能澄清名称或代表单一领域输入则使用对象，仓库约定或外部 API 要求位置参数时保留位置参数；按仓库既定的状态与依赖边界，通过有类型的 props、Hooks、Context 或注入模块声明组件依赖。
环境变量：通过项目的打包器访问器与公开前缀读取客户端环境变量；通过仓库的类型化配置层校验必需值，仅对可选值或明确定义的本地开发模式添加默认值。
客户端安全：凭据与密钥保留在服务端；浏览器交付的代码与公开环境变量对客户端可见；本地环境文件排除在版本控制之外，错误输出不包含敏感值。
异步处理
遵循仓库的 promise 风格，当 async/await 能澄清时序与错误传播时使用它；在拥有职责的边界处理事件处理器与异步失败，Error Boundary 覆盖后代渲染失败，而非普通回调或异步工作；通过仓库的取消或服务端状态机制，防止由副作用驱动的请求产生过期或卸载后更新。
格式化
遵循仓库的格式化、命名、模块解析与包边界配置；仅在项目配置能解析时使用导入别名。
错误处理
每个被捕获的错误都有唯一且有意为之的结局：向上传播、转换为仓库的类型化边界结果，或表示为面向用户的错误状态。保留上下文，并在拥有诊断或恢复职责的边界记录一次日志，同时脱敏敏感数据。Error Boundary 放在后代渲染失败有明确 UI 恢复结果的位置；自定义 Hook 保留应用既有的错误契约；API 层把传输失败转换为仓库既定的领域或边界表示；事件处理器与异步工作流使用所属层的异常、结果或 UI 状态契约。
性能优化
启用 React Compiler 时依赖它；仅在实测瓶颈或外部 API/副作用边界需要稳定引用时，手动添加 React.memo、useMemo 或 useCallback。当已配置的包体积预算出现回退，或已接受的任务把包体积列为结果且仓库打包报告将相关增长归因于变更的导入时，才应用代码分割或导入变更，并遵循仓库既有的加载模式，在变更后验证同一信号。
非功能性要求
浏览器兼容：按 PRD、设计文档、Browserslist 或构建配置中的支持策略实现；未定义时保持仓库当前的转译与 polyfill 基线，并把任何新的依赖浏览器的 API 作为未解决的兼容性决策提出。性能：按项目定义的预算与代表受影响体验的指标验证；无预算时测量变更路径并报告观察结果，而不是自行发明阈值。
使用方式
资料未提供该规则的安装命令、引入方式或具体调用步骤。它作为 shinpr/claude-code-workflows 仓库下的一个规则条目发布，页面地址为 https://www.skills.sh/shinpr/claude-code-workflows/typescript-rules。具体接入与使用流程暂未提供。
适用场景
适合在 React + TypeScript 前端项目中作为编码规范与代码评审清单使用，尤其适用于存在外部 API、localStorage、URL 参数等不可信数据边界，以及使用 RSC 框架、React Compiler 的项目。
限制
规则中的数量与阈值均为评审提示而非硬性门槛；服务端与客户端边界规则仅在具备服务端组件运行时的项目中适用；浏览器兼容与性能要求在项目未定义基线或预算时，需自行测量并上报结果，规则不提供固定数值。其余信息暂未提供。