OpenParable
Skip to content
← Back to skills

Code Conventions

Development
code-conventions

Code Conventions is an Agent Skill for development published in the iflytek/skillhub repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Code style, logging, and testing conventions for SkillHub backend (Java) and frontend (TypeScript). Use when writing or reviewing code.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/iflytek/skillhub/blob/HEAD/.agents/skills/code-conventions/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/code-conventions, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Code Conventions Skill

Java / Backend Conventions

User Identity Type

User identity is always String throughout the codebase. This covers:

  • Authentication and authorization
  • API parameters and responses
  • Permission checks
  • Audit logs
  • Resource owner, creator, reviewer, actor, submittedBy fields

Never introduce int, long, or bigint as user identifiers. The platform needs to support external SSO/OIDC/SCIM identity sources whose UIDs are typically stable strings.

Exception Handling

  • Use LocalizedDomainException for user-facing error messages (supports i18n)
  • Use DomainBadRequestException for invalid client input
  • Use DomainNotFoundException for missing resources
  • Use DomainForbiddenException for authorization failures
  • Exception classes live in skillhub-domain/shared/exception/

Domain Services

  • Return domain objects, not DTOs
  • Contain business rules and state transitions
  • Use domain events for cross-cutting side effects (publishing, notifications)
  • Located in domain/{submodule}/service/

Controllers

  • Transport only: extract auth context, bind request params, wrap responses
  • No business logic in controllers
  • Located in com.iflytek.skillhub.controller/

Query Repositories

  • Handle read-model joins and presentation projection
  • Return DTOs or presentation models
  • Located in com.iflytek.skillhub.repository/
  • Named like *QueryRepository (e.g., GovernanceQueryRepository, MySkillQueryRepository)

App Services

  • Workflow orchestration: coordinate domain services and query repositories
  • Should express "what this endpoint does", not "how it assembles DTOs"
  • Located in com.iflytek.skillhub.service/

Logging

  • Use SLF4J with structured logging
  • Use MDC for request tracing
  • Log at appropriate levels: INFO for business events, DEBUG for troubleshooting, ERROR for failures

TypeScript / Frontend Conventions

Type Safety

  • Strict TypeScript mode. No any types.
  • Use generated OpenAPI types from web/src/api/generated/schema.d.ts for all API interactions.
  • Additional types in web/src/types/

Data Fetching

  • Always use TanStack Query (@tanstack/react-query) for server state
  • Never use useEffect for data fetching
  • Use openapi-fetch client for type-safe API calls

Component Composition

  • Radix UI primitives: @radix-ui/react-dropdown-menu, @radix-ui/react-select
  • class-variance-authority (cva) for component variants
  • clsx + tailwind-merge for class merging
  • cn() utility: web/src/shared/lib/utils.ts
  • shadcn/ui is NOT used as a library

State Management

  • TanStack Query for server state (API data, caching, invalidation)
  • Zustand for local/UI state (theme, sidebar, modals, form state)

Feature-Sliced Design

LayerPathPurpose
Pagesweb/src/pages/Route-level page components
Featuresweb/src/features/Self-contained business features
Entitiesweb/src/entities/Domain entity display logic
Sharedweb/src/shared/Reusable UI components, hooks, utilities

Place code at the lowest appropriate layer. Do not put page-level logic in shared.

Styling

  • Tailwind CSS for all styling
  • Follow existing component patterns
  • Use cn() for conditional class merging

Internationalization

  • Use i18next + react-i18next
  • All user-facing text must be translatable
  • Translation keys in web/src/i18n/

Testing Philosophy

Backend

  • JUnit 5 + Mockito + AssertJ
  • Use Spring Boot test slices where possible (@WebMvcTest, @DataJpaTest)
  • Test behaviors, not implementations
  • Use make test-backend-app (includes -am for dependent modules)
  • Never run ./mvnw -pl skillhub-app clean test directly — stale Maven cache causes misleading errors

Frontend

  • Vitest for unit tests
  • Playwright for E2E tests
  • Test component behavior and user interactions

Common Pitfalls

  • Maven multi-module: Always use -am flag or Makefile targets to include dependent modules
  • OpenAPI types: Must regenerate and commit after API contract changes
  • String identity: Never use numeric types for user identifiers
  • Controller business logic: Move to domain service or app service
  • Complex read-models in app service: Extract to query repository