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