codebase-conventions

代码库约定

适用于一般情况的代码编写与组织约定。请阅读以下所有约定。如果某条约定与你即将进行的工作相关，就遵照执行。 这些是用户项目的默认约定；如果某个项目显然已遵循不同的约定，则应与项目保持一致，并说明原因。

何时参考此技能

在以下情况下：

• 创建新文件，或决定新模块（组件、钩子、工具函数、服务端操作、类型等）的存放位置
• 为文件、组件或导出项命名
• 编写导入语句
• 运行项目命令（安装、构建、测试、脚本）
• 添加注释

约定

文件放置与就近组织

将每个功能/路由文件夹视为独立单元——几乎就像它是自己的小型仓库。功能代码离使用它的位置越近，就越容易进行试验、理解，最终也更容易迁移或删除。默认就近组织；只有在使用范围确实很广时，才提升到全局文件夹。

根据使用该代码的功能数量决定存放位置：

• 仅由单个功能/路由使用 → 将其放在该功能自己的文件夹内（例如功能中的本地 components/、hooks/、actions/ 或 lib/ 子文件夹），紧邻使用它的代码。不要将其提升到全局文件夹。
• 由少数几个同级功能共享 → 将其提升到这些使用方共享的最近共同祖先文件夹，而不是一路提升到顶层全局文件夹。找到包含所有用法的最低层文件夹，并将其放在那里。
• 真正全局——由许多功能使用 → 放在根目录下的共享文件夹（例如 components/、lib/、hooks/、actions/，或项目中相应的目录）是合适的。

其他指导：

• 设计系统/UI 基础组件（共享组件库，例如 components/ui/ 文件夹）无论有多少功能使用，都应留在全局位置。
• 第三方服务的初始化/配置客户端（数据库客户端、邮件、向量存储、队列、分析等）应放在全局共享文件夹中——它们属于横切基础设施，而不是功能代码。
• 功能组件留在其所在位置是正确的，即使功能外部的代码会导入它。外部导入本身并不足以成为将其提升到全局文件夹的理由——只有在多个功能广泛使用时才应提升。只有当它确实成为共享代码时才提升。

工具与导入

• 所有项目命令（安装、运行脚本、添加/移除依赖）都使用 pnpm。除非项目显然已配置为使用 npm/yarn，否则不要使用它们。
• 对于非相对导入，使用项目的路径别名（通常为 @/），而不是冗长的 ../../../ 路径。遵循项目现有的别名配置。

命名

• 文件使用 kebab-case。
• React 组件使用 PascalCase。
• 仅使用命名导出——避免默认导出（框架要求时除外，例如路由/页面入口文件）。

注释

• 对涉及不明显的假设、特定于产品的逻辑、特定于代码仓库的机制，或任何非行业标准做法的代码，在旁边添加简短的行内注释。一句话即可。
• 不要添加只是复述代码已有明确信息的注释。如果有能力的读者仅凭代码就能理解，就不需要注释。

后续约定

此技能会随时间扩展。新增约定应添加到上方的约定部分，并表述为 Agent 能够机械执行的规则。