busirocket-core-conventions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Core Conventions

核心规范

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

可复用、与项目无关的规范，旨在保持代码库的可扩展性，便于AI Agent导航。

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.

保持多个小而专注的文件，边界明确。
自有模块每个文件仅导出一个符号（组件/钩子/函数/类型）。
禁止使用桶文件/索引文件（如
```
index.ts
```
），这类文件会隐藏依赖关系。
```
types/
```
目录外禁止使用内联类型。
组件或钩子内部禁止包含辅助函数；需提取至
```
utils/
```
目录。
除非获得明确批准，否则避免为简单的辅助功能添加新依赖。

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

路由/页面：
```
app/**
```
可复用UI：
```
components/<area>/...
```
编排（状态/副作用）：
```
hooks/<area>/useXxx.ts
```
纯逻辑：
```
utils/<area>/xxx.ts
```
外部边界（网络/数据库/认证/存储）：
```
services/<area>/xxx.ts
```
共享类型：
```
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)

```
core-agent-defaults
```
- Agent行为默认值（小改动、询问问题、避免依赖）
```
core-code-style
```
- 代码风格指南（仅英文、纯函数、避免嵌套）
```
core-repo-hygiene
```
- 代码库卫生规则（无桶文件、单一职责、轻量处理器）

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)

```
core-boundaries-decision-tree
```
- 代码归属决策树（app、components、hooks、utils、services、types）
```
core-boundaries-hard-rules
```
- 边界硬规则（单一导出、无内联类型、组件内无辅助函数）

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)

```
core-naming-folder-layout
```
- 文件夹结构规范
```
core-naming-file-naming
```
- 文件命名规范（大驼峰、小驼峰、短横线命名）
```
core-naming-exports
```
- 导出规范（默认导出 vs 命名导出、Next.js例外情况）
```
core-naming-imports
```
- 导入规范（无桶文件、相对路径 vs 别名）

Services vs Utils

Services与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

```
core-services-vs-utils-contract
```
- 何时使用services/ vs utils/
```
core-services-vs-utils-api
```
- Services与Utils的API指南
```
core-services-vs-utils-route-handlers
```
- 路由处理器要求

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)

```
core-anti-patterns-file-structure
```
- 文件结构反模式（多导出、桶文件、杂项模块）
```
core-anti-patterns-types
```
- 类型反模式（内联类型、大型类型文件）
```
core-anti-patterns-react
```
- React反模式（组件内获取数据、组件内包含辅助函数）
```
core-anti-patterns-app-router
```
- App Router反模式（臃肿处理器、未验证输入）
```
core-anti-patterns-dependencies
```
- 依赖反模式（简单辅助功能添加依赖）
```
core-anti-patterns-vite-browser
```
- Vite/浏览器运行时反模式（process.env、Node全局变量）

Related Skills

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

阅读单个规则文件以获取详细说明及代码示例：

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

每个规则文件包含：

规则重要性的简要说明
代码示例（正确与错误模式）
额外背景信息及最佳实践