code-style

Oak AI 项目 TypeScript 编码约定,包括命名模式(kebab-case 文件、PascalCase 组件、camelCase 函数)、组件结构、带原因的错误处理、状态管理模式和 tRPC 实现。编写、审查或重构代码时使用。

📖 中文导读:Oak AI 项目 TypeScript 编码约定,包括命名模式(kebab-case 文件、PascalCase 组件、camelCase 函数)、组件结构、带原因的错误处理、状态管理模式和 tRPC 实现。编写、审查或重构代码时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: code-style description: Oak AI project TypeScript coding conventions including naming patterns (kebab-case files, PascalCase components, camelCase functions), component structure, error handling with cause, state management patterns, and tRPC implementation. Use when writing, reviewing, or refactoring code.

Code Style Guide

General Principles

  • TypeScript: Strict types with noUncheckedIndexedAccess. Prefer explicit return types.
  • Imports: Sorted: React → Third-party → Project → Relative
  • Formatting: 2-space indents, 80 char width, double quotes, trailing commas
  • Function style: Functional, declarative programming. Avoid classes.
  • Organization: Modular architecture with clear separation of concerns

Naming Conventions

  • Files/Directories: kebab-case (lowercase with dashes)
  • Components: PascalCase
  • Variables/Functions: camelCase
  • Types/Interfaces: PascalCase
  • Constants: UPPER_CASE for true constants, camelCase for config objects
  • Hooks: Always prefix with "use" (e.g., useAnalytics)

Component Structure

  • Component Pattern: Functional components with hooks
  • Client Components: Add "use client" directive at the top of file
  • File Organization:
    • Exported component first
    • Sub-components next
    • Helper functions
    • Type definitions at the end

State Management

  • Global State: Zustand stores organized by domain
  • Local State: React hooks (useState, useReducer)
  • Remote State: tRPC queries and mutations with TanStack Query

Error Handling

  • Promise Handling: Always await promises or use .catch() (enforced by no-floating-promises)
  • Error Patterns:
    • Early returns with guard clauses
    • Structured error types
    • User-friendly error messages
    • Proper logging
  • Error Cause: When rethrowing errors, use the cause option for better error context:
    throw new Error("High-level error message", { cause: originalError });
    

tRPC Implementation

  • Router Organization: By domain/feature
  • Procedure Types: Query for read, Mutation for write operations
  • Error Handling: Consistent error responses
  • Middleware: Authentication, rate limiting, etc.

Testing Patterns

  • Unit Tests: Jest for utilities and hooks
  • Component Tests: React Testing Library
  • E2E Tests: Playwright
  • Mocking: Mock external dependencies appropriately