busirocket-core-conventions（Busiroket 核心约定）

Core Conventions

Reusable, project-agnostic conventions designed to keep codebases scalable and easy for AI agents to navigate.

When to Use

Use this skill when:

• Starting a new feature and deciding where code should live
• Refactoring to improve maintainability
• Enforcing “one-thing-per-file” discipline
• Establishing naming/layout conventions and boundary rules

Non-Negotiables (MUST)

• Keep many small, focused files with explicit boundaries.
• One exported symbol per file for your own modules (component/hook/function/type).
• No barrel/index files (e.g. index.ts) that hide dependencies.
• No inline types outside types/.
• No helper functions inside components or hooks; extract to utils/.
• Avoid adding new dependencies for trivial helpers unless explicitly approved.

Placement / Boundaries

• Route/pages: app/**
• Reusable UI: components/<area>/...
• Orchestration (state/effects): hooks/<area>/useXxx.ts
• Pure logic: utils/<area>/xxx.ts
• External boundaries (network/DB/auth/storage): services/<area>/xxx.ts
• Shared shapes: types/<area>/Xxx.ts

Rules

Core Principles

• core-agent-defaults - Agent behavior defaults (small changes, ask questions, avoid dependencies)
• core-code-style - Code style guidelines (English-only, pure functions, avoid nesting)
• core-repo-hygiene - Repository hygiene (no barrel files, one responsibility, thin handlers)

Boundaries & Placement

• core-boundaries-decision-tree - Decision tree for where code belongs (app, components, hooks, utils, services, types)
• core-boundaries-hard-rules - Hard rules for boundaries (one export, no inline types, no helpers in components)

Naming & Layout

• core-naming-folder-layout - Folder structure conventions
• core-naming-file-naming - File naming conventions (PascalCase, camelCase, kebab-case)
• core-naming-exports - Export conventions (default vs named, Next.js exceptions)
• core-naming-imports - Import conventions (no barrel files, relative vs aliases)

Services vs Utils

• core-services-vs-utils-contract - When to use services/ vs utils/
• core-services-vs-utils-api - API guidance for services and utils
• core-services-vs-utils-route-handlers - Route handler requirements

Anti-Patterns

• core-anti-patterns-file-structure - File structure anti-patterns (multiple exports, barrel files, misc modules)
• core-anti-patterns-types - Type anti-patterns (inline types, huge type files)
• core-anti-patterns-react - React anti-patterns (fetching in components, helpers in components)
• core-anti-patterns-app-router - App Router anti-patterns (fat handlers, unvalidated input)
• core-anti-patterns-dependencies - Dependency anti-patterns (trivial helpers)
• core-anti-patterns-vite-browser - Vite/Browser runtime anti-patterns (process.env, Node globals)

Related Skills

• busirocket-typescript-standards - TypeScript-specific standards
• busirocket-react - React component, hook, and state (Zustand) patterns
• busirocket-refactor-workflow - Refactoring workflow

How to Use

Read individual rule files for detailed explanations and code examples:

rules/core-agent-defaults.md
rules/core-boundaries-decision-tree.md
rules/core-naming-folder-layout.md

Each rule file contains:

• Brief explanation of why it matters
• Code examples (correct and incorrect patterns)
• Additional context and best practices