القائمة
TypeScript 和 React 开发的编码标准与最佳实践。在编写或审查代码时激活。提供命名、类型、组件设计、Hook 提取、状态管理等规范。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
在进行任何创造性工作前必须使用——创建功能、构建组件、添加新功能或修改行为。在实现之前先探索用户意图、需求和设计。
在用户确认要提交代码变更时使用——安全检查 diff 中的敏感数据后执行 git commit
在面对 2 个以上互不依赖、无共享状态的独立任务时使用
当有已编写的实现计划需要在独立会话中执行时使用，包含评审检查点
在实现完成、测试通过后，引导决定如何集成工作——提供合并、PR 或清理的结构化选项
收到代码评审反馈后、实现建议之前使用，尤其当反馈不清楚或技术上存疑时——要求技术严谨性和验证，而非表演性附和或盲目实现
| name | coding-standards |
| description | TypeScript 和 React 开发的编码标准与最佳实践。在编写或审查代码时激活。提供命名、类型、组件设计、Hook 提取、状态管理等规范。 |
| 原则 | 说明 |
|---|---|
| 可读性优先 | 代码被阅读的次数多于被编写的次数 |
| KISS | 最简单的解决方案就是有效的，避免过度工程 |
| DRY | 将通用逻辑提取到函数中，避免复制粘贴 |
| YAGNI | 不要构建不需要的功能 |
| 异味 | 阈值 | 解决方案 |
|---|---|---|
| 大组件 | >200 行 | 拆分组件 |
| 大工具文件 | >100 行 | 按功能拆分文件 |
| 长函数 | >50 行 | 拆分成小函数 |
| useState 过多 | >5 个 | 提取 Hook 或拆分 |
| useEffect 过多 | >3 个 | 提取到独立 Hook |
| 深嵌套 | >4 层 | 尽早返回 |
| Props 过多 | >7 个 | 合并为对象或拆分 |
| Props 透传 | >2 层 | 使用 Context |
当组件包含以下任一情况时，必须提取自定义 Hook：
| 信号 | 判断标准 | 重构方向 |
|---|---|---|
| 多个关联 useEffect | ≥2 个 useEffect 处理同一业务 | 提取为 use<Feature> Hook |
| 表单逻辑内嵌 | useForm + reset + watch + 自定义提交 | 提取为 use<Entity>Form Hook |
| 状态+副作用耦合 | useState + useEffect 共同管理数据流 | 提取为自定义 Hook |
| 可复用的有状态逻辑 | 状态逻辑在多处重复或明显可复用 | 提取为共享 Hook |
| 场景 | 是否需要注释 | 说明 |
|---|---|---|
| 复杂业务逻辑 | 必须 | 解释 why，不解释 what |
| 临时方案 / Tech Debt | 必须 | // TODO: xxx 或 // FIXME: xxx |
| Hack / Workaround | 必须 | 说明原因和移除条件 |
| 自解释的代码 | 不需要 | 好的命名胜过注释 |
// 使用 BigNumber 避免 JS 浮点数精度问题
const total = new BigNumber(price).times(amount);
// TODO: 等后端支持批量接口后重构为单次请求
for (const order of orders) {
await submitOrder(order);
}