Skip to main content

项目规范

项目规范是团队协作的契约，目的是：让不同人写出的代码看起来像同一个人写的。

两个层次​

1. 编码规范​

针对单个文件的代码风格，影响可读性。

  • 命名：变量/函数/类/常量/文件名
  • 格式：缩进、引号、分号、换行
  • 注释：何时写、写什么
  • 语法：避免的语言特性、推荐的写法

自动化：ESLint + Prettier + Stylelint，在保存和提交时自动检查

详见 统一编码规范

2. 项目级规范​

针对整个项目的约定，影响可维护性和协作效率。

维度内容
技术栈框架、UI 库、状态管理、构建工具
目录结构src 组织、命名、别名
命名约定组件、文件、变量、接口
环境配置dev/test/staging/prod 区分
路由约定懒加载、meta 字段
数据管理状态分层、action 命名
接口调用三层结构：基础请求 → 业务封装 → useRequest
提交规范commit message、PR 模板
Git 流程分支模型、Code Review

详见 制定项目规范

3. AI 编码工具协同规范（2025+ 必补）​

让 Cursor / Claude Code / Copilot / Trae 等 AI 工具真正吃透项目规范，避免 AI 写出"过时代码"或"风格不一致"的 PR。

详见 AI 编码工具协同规范

关键原则​

  1. 约定优于配置：能约定的就不要让人选
  2. 能自动的就不手动：规范尽量通过工具落地
  3. 不要过度规范：1-2 人小项目，规范是负担
  4. 持续迭代：规范要随项目演进，而不是一锤定音
  5. Code Review 兜底：自动化工具覆盖不到的，靠 review 补

落地 Checklist​

  • ESLint + Prettier + Stylelint 配置完成
  • husky + lint-staged 接入
  • commitlint 规范 commit message
  • PR 模板（标题、描述、checklist）
  • README 含项目结构说明
  • .editorconfig 统一编辑器行为
  • .npmrc 统一源
  • CI 跑 lint + test + build
  • .cursorrules / AGENTS.md 配 AI 工具上下文
  • AI 生成的代码走相同 CI 流程