mcpField
B
busirocket-core-conventions

busirocket-core-conventions

github.com/busirocket开发141 次安装15 周前更新
代码仓库

关于 busirocket-core-conventions

为 AI Agent 提供与项目无关的代码组织和边界约定。重点是保持文件小而专注、明确代码放置规则，并避免 barrel 文件和内联类型等模式。

主要功能

  1. 01每个模块文件仅导出一个符号
  2. 02不使用 barrel 或 index 文件
  3. 03分离类型、工具函数和服务
  4. 04规定应用代码的放置位置
  5. 05涵盖命名、导入和反模式

适用场景

  1. 01开发新功能时确定代码位置
  2. 02重构代码库以提升可维护性
  3. 03制定文件、命名和导入约定
  4. 04检查代码是否违反边界规则

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/busirocket/agents-skills --skill busirocket-core-conventions

安装后在 Claude Code 中输入/busirocket-core-conventions确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

rules/
core-agent-defaults.md
core-anti-patterns-app-router.md
core-anti-patterns-dependencies.md
core-anti-patterns-file-structure.md
core-anti-patterns-react.md
core-anti-patterns-types.md
core-anti-patterns-vite-browser.md
core-boundaries-decision-tree.md
core-boundaries-hard-rules.md
core-code-style.md
core-naming-exports.md
core-naming-file-naming.md
core-naming-folder-layout.md
core-naming-imports.md
core-repo-hygiene.md
core-services-vs-utils-api.md
core-services-vs-utils-contract.md
core-services-vs-utils-route-handlers.md

详细介绍

核心约定

可复用、与项目无关的约定，旨在让代码库易于扩展，也便于 AI Agent 浏览。

适用场景

在以下情况下使用此技能：

  • 开始开发新功能，并决定代码应放在哪里
  • 重构以提高可维护性
  • 落实“每个文件只做一件事”的原则
  • 建立命名、布局约定和边界规则

不可妥协的要求（MUST）

  • 保持大量小型、职责明确的文件，并明确划分边界。
  • 自有模块（组件／Hook／函数／类型）每个文件只导出一个符号。
  • 不要使用隐藏依赖关系的 barrel/index 文件（例如 index.ts）。
  • types/ 以外不要定义内联类型。
  • 不要在组件或 Hook 内定义辅助函数；应将其提取到 utils/。
  • 除非获得明确批准，否则不要为简单的辅助功能添加新依赖。

文件位置／边界

  • 路由／页面：app/**
  • 可复用 UI：components/<area>/...
  • 编排（状态／副作用）：hooks/<area>/useXxx.ts
  • 纯逻辑：utils/<area>/xxx.ts
  • 外部边界（网络／数据库／认证／存储）：services/<area>/xxx.ts
  • 共享结构：types/<area>/Xxx.ts

规则

核心原则
  • core-agent-defaults - Agent 行为默认规则（小幅修改、提出问题、避免依赖）
  • core-code-style - 代码风格指南（仅使用英文、纯函数、避免嵌套）
  • core-repo-hygiene - 仓库卫生规范（不使用 barrel 文件、单一职责、保持处理器精简）
边界与文件位置
  • core-boundaries-decision-tree - 代码归属位置的决策树（app、components、hooks、utils、services、types）
  • core-boundaries-hard-rules - 边界硬性规则（单一导出、不使用内联类型、组件中不定义辅助函数）
命名与布局
  • core-naming-folder-layout - 文件夹结构约定
  • core-naming-file-naming - 文件命名约定（PascalCase、camelCase、kebab-case）
  • core-naming-exports - 导出约定（默认导出与命名导出、Next.js 例外情况）
  • core-naming-imports - 导入约定（不使用 barrel 文件、相对路径与别名）
服务与工具函数
  • core-services-vs-utils-contract - 何时使用 services/ 或 utils/
  • core-services-vs-utils-api - services 和 utils 的 API 指南
  • core-services-vs-utils-route-handlers - 路由处理器要求
反模式
  • core-anti-patterns-file-structure - 文件结构反模式（多个导出、barrel 文件、杂项模块）
  • 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／Browser 运行时反模式（process.env、Node 全局变量）

相关技能

  • busirocket-typescript-standards - TypeScript 专用规范
  • busirocket-react - React 组件、Hook 和状态（Zustand）模式
  • busirocket-refactor-workflow - 重构工作流

使用方法

阅读各规则文件，了解详细说明和代码示例：

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

每个规则文件都包含：

  • 简要说明其重要性
  • 代码示例（正确和错误的模式）
  • 补充背景信息和最佳实践

评论

支持 Markdown