用途
coding-standards 是一个跨项目通用的编码规范技能，提供命名、可读性、不可变性和代码质量审查的基线约定。它被定位为“共享底线”，而不是某个框架的详细操作手册。当需要更具体的框架指导时，资料建议改用 frontend-patterns（React、状态、表单、渲染、UI 架构）、backend-patterns 或 api-design（仓储/服务层、端点设计、校验、服务端关注点），或使用 rules/common/coding-style.md 作为更短的可复用规则层。
何时启用
资料列出以下启用场景：启动新项目或新模块；审查代码质量与可维护性；按约定重构现有代码；强制命名、格式或结构一致性；设置 lint、格式化或类型检查规则；帮助新贡献者了解编码约定。
范围边界
该技能适用于：描述性命名、默认不可变性、可读性/KISS/DRY/YAGNI 的落实、错误处理预期与代码坏味道审查。不应作为主要来源用于：React 组合、Hook 或渲染模式；后端架构、API 设计或数据库分层；以及已有更窄 ECC 技能覆盖的领域特定框架指导。
代码质量原则
- 可读性优先：代码被阅读多于被编写；变量和函数名清晰；优先自文档化代码而非注释；格式一致。
- KISS：采用能工作的最简单方案；避免过度工程；不做过早优化；易理解优于炫技。
- DRY：把公共逻辑提取为函数；创建可复用组件；跨模块共享工具；避免复制粘贴式编程。
- YAGNI：不要提前构建尚未需要的功能；避免推测性通用化；仅在需要时增加复杂度；从简单开始，需要时再重构。
TypeScript/JavaScript 标准
变量命名：使用描述性名称，如 marketSearchQuery、isUserAuthenticated、totalRevenue；避免 q、flag、x 这类不清晰名称。函数命名：采用动词-名词模式，如 fetchMarketData、calculateSimilarity、isValidEmail；避免仅名词或含义不清的命名。
不可变性（关键）：始终使用展开运算符创建新对象或新数组，如 { ...user, name: 'New Name' }、[...items, newItem]；绝不直接修改，如 user.name = 'New Name' 或 items.push(newItem)。
错误处理：应包含完整错误处理，检查 response.ok 并抛出带状态码的错误，捕获后记录并重新抛出；避免无错误处理的直接返回。
异步最佳实践：在可能时使用 Promise.all 并行执行；避免不必要的顺序 await。
类型安全：使用明确接口与联合类型，如 status: 'active' | 'resolved' | 'closed'；避免使用 any。
React 最佳实践
组件结构：使用带类型的函数组件，定义 ButtonProps 等接口，为可选属性提供默认值；避免无类型、结构不清的组件。自定义 Hook：可复用 Hook 如 useDebounce，内部使用 useState 与 useEffect 并清理定时器。状态管理：基于先前状态使用函数式更新 setCount(prev => prev + 1)；避免直接引用可能过期的状态。条件渲染：使用清晰的 && 表达式分别渲染加载、错误和数据；避免三元表达式嵌套地狱。
API 设计标准
REST 约定：GET /api/markets 列出、GET /api/markets/:id 获取、POST 创建、PUT 全量更新、PATCH 部分更新、DELETE 删除；查询参数用于过滤，如 ?status=active&limit=10&offset=0。响应格式：统一结构包含 success、data、error、meta（total、page、limit）；成功与错误响应分别返回。输入校验：使用 zod 定义 schema，如 CreateMarketSchema，解析失败时返回校验失败与 details。
文件组织
项目结构示例：src/app（Next.js App Router，含 api、markets、(auth)）、components（ui、forms、layouts）、hooks、lib（api、utils、constants）、types、styles。文件命名：组件用 PascalCase（Button.tsx）；Hook 用 camelCase 加 use 前缀（useAuth.ts）；工具用 camelCase（formatDate.ts）；类型用 camelCase 加 .types 后缀（market.types.ts）。
注释与文档
注释应解释“为什么”而非“是什么”，例如说明指数退避原因或刻意使用变更的性能考虑；避免陈述显而易见的内容。公共 API 使用 JSDoc，包含参数、返回值、抛出异常与示例。
性能最佳实践
记忆化：使用 useMemo 缓存昂贵计算（排序前先复制，因为 sort 会原地修改），使用 useCallback 缓存回调。懒加载：使用 lazy 与 Suspense 加载重型组件。数据库查询：只选择需要的列，如 select('id, name, status')，避免 select('*')。
测试标准
测试结构采用 AAA 模式：Arrange、Act、Assert。测试命名应描述具体行为，如“returns empty array when no markets match query”；避免“works”“test search”这类模糊名称。
代码坏味道检测
关注以下反模式：长函数（超过 50 行应拆分）；深层嵌套（5 层以上应改用提前返回）；魔法数字（应改为命名常量，如 MAX_RETRIES、DEBOUNCE_DELAY_MS）。资料最后强调：代码质量不可妥协，清晰可维护的代码能支持快速开发与自信重构。
限制
资料未提供该技能的安装命令、收费方式、价格、平台支持或具体效果数据，这些信息暂未提供。