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
causeoption 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