前端全栈项目的开发规范链：让 AI 写代码也有门禁
前言
一个产品往往对应多个仓库：后端 API、管理后台、用户前台。单靠口头约定，很难让协作者和 AI 保持一致。
更稳妥的做法是把规范拆成一条可执行的链——本地快检、远程 CI、PR 审阅、合并上线，每一环都有工具兜底。这篇文章分享的是这条链本身，不涉及具体业务。
你也可以把下文直接贴给 Cursor / Copilot 当上下文，减少「能跑但没 lint、没类型、没走 PR」的代码。
分支策略（建议）
多仓库可以统一采用 develop + main 双分支：
| 分支 | 用途 |
|---|---|
develop | 日常开发、联调、测试环境 |
main | 生产发布，只通过 PR 合并 |
推荐流程：
本地开发 → commit → push develop
→ 在测试环境验证
→ 开 PR：develop → main
→ CI 全绿 + 看过 diff
→ 合并 → 生产更新
个别老仓库生产分支可能叫 master，思路一样，注意 PR 的 base 分支即可。
规范链总览
┌─────────────────────────────────────────────────────────┐
│ ① 本地 │
│ lint-staged（暂存文件）+ commitlint（提交信息） │
└──────────────────────────┬──────────────────────────────┘
│ push develop
▼
┌─────────────────────────────────────────────────────────┐
│ ② 远程 develop │
│ CI 全量：lint / typecheck / test / build │
└──────────────────────────┬──────────────────────────────┘
│ 开 PR
▼
┌─────────────────────────────────────────────────────────┐
│ ③ Pull Request │
│ CI 再跑 + 自动 review + 人工看 diff（建议） │
│ Test plan：手动验收清单 │
└──────────────────────────┬──────────────────────────────┘
│ merge
▼
┌─────────────────────────────────────────────────────────┐
│ ④ 生产 main │
│ 按各仓库既有发布方式更新 │
└─────────────────────────────────────────────────────────┘
三条设计原则：
- 本地要快：只检查本次改动的文件，避免每次 commit 跑全量 test。
- 远程要严：CI 跑全量 lint、类型、测试、构建，作为合并门槛。
- 测试与生产分离：
develop先验证，稳定后再 PR 到生产分支。
① 本地：提交前门禁
用 Husky 挂两个钩子：
| 钩子 | 作用 |
|---|---|
pre-commit | lint-staged，只处理暂存区文件 |
commit-msg | commitlint，强制约定式提交（如 feat:、fix:、ci:） |
不同技术栈可以选不同格式化 / lint 工具，常见组合：
| 类型 | 常见工具 |
|---|---|
| Node 后端（Nest 等） | ESLint + Prettier |
| React 管理端 | Biome，或 ESLint + Prettier |
| Next.js 前台 | ESLint + Prettier |
刻意不在 pre-commit 做的： 全量 typecheck、test、build——这些交给 CI，避免本地提交卡顿。
另外可以提交共享的 .vscode/settings.json 与 extensions.json，统一保存时格式化；个人主题、字体等不要写进仓库。
② CI：push / PR 时的全量检查
触发时机： main / develop 的 push，以及指向这两者的 PR。
按仓库类型划分 job，思路一致，内容可按栈调整：
后端 API
| Job | 典型内容 |
|---|---|
| lint | 全量 ESLint |
| typecheck | tsc --noEmit |
| test | 单元测试（如 Jest） |
| build | 框架构建命令 |
| e2e | 可选，独立 workflow |
管理后台
| Job | 典型内容 |
|---|---|
| lint | Biome / ESLint |
| typecheck | tsc |
| test | Vitest / Jest |
| build | 生产构建 |
| coverage | 可选，独立 workflow |
用户前台
| Job | 典型内容 |
|---|---|
| lint | ESLint |
| typecheck | tsc |
| build | next build 等 |
| test | 有则加，没有可后续补 |
要点： CI 是合并前的硬门槛，红灯不应被忽视。
③ PR：审阅与依赖更新
自动 Code Review（PR-Agent）
可在 PR 打开、更新时自动：
- 给出 review 意见
- 辅助生成 PR 描述
需要配置对应 LLM 的 API Key（如 DeepSeek、OpenAI 等），放在仓库 Secrets。
Dependabot
建议统一策略，避免和 Renovate 等工具重复：
- 包管理器（npm / pnpm）：定期检查，可忽略 patch、分组合并
- GitHub Actions：定期检查 workflow 依赖
Test plan 是什么？
PR 模板里的 Test plan 是人工验收清单，不是自动测试，例如：
- CI 全绿
- 测试环境核心流程点过
- 合并后生产环境关键项确认
合并前建议逐项勾选。
人工 Review
小团队或免费版 GitHub 往往开不了完整的分支保护，因此：
- 可能无法强制「必须有人 Approve」
- 可能无法从技术上禁止直推
main
这时更要靠流程习惯：走 PR、看 diff、CI 不过不合并。
给 AI 的协作约定
把下面几段放进对话，或写入仓库根目录的 AGENTS.md / CLAUDE.md，可显著减少「能跑但不符合项目规范」的代码。
必须遵守
- 提交信息使用约定式格式：
feat:/fix:/chore:/ci:等。 - 改完代码确保能通过该仓库的
lint与typecheck；有单测的仓库改动需考虑测试。 - 不要手改自动生成代码（如 OpenAPI client、ORM entity 生成物等），走项目规定的生成命令。
- 环境变量、密钥不要写进仓库。
- 合并到生产走 PR，并在 Test plan 里说明如何验证。
建议 AI 改完后的自检
按仓库 package.json 里的脚本跑一遍，常见组合：
npm run lint && npm run typecheck && npm run test && npm run build
有 monorepo 或多包时，在对应子包目录执行。
PR 描述建议结构
## Summary
- 改了什么、为什么
## Test plan
- [ ] CI 通过
- [ ] 测试 / 本地关键路径验证
- [ ] 合并后需确认的事项
常见薄弱项
诚实列出来，方便后续补强：
| 项目 | 说明 |
|---|---|
| 分支保护 | 免费版可能开不了，靠流程约束 |
| 强制 Approve | 小团队常未配置 |
| 前台单测 | 很多项目初期没有，可逐步补 |
| 多仓库分支命名不一致 | main vs master，开 PR 时注意 base |
小结
规范链不是 paperwork，而是分层门禁：
- 本地
lint-staged拦住低级格式问题； - CI 拦住类型、测试、构建；
- PR + 自动 review 拦住设计疏漏；
- 分支策略拦住「没测就上生产」。
把这篇文章或 AGENTS.md 交给 AI，等于告诉它：不仅要写出能跑的代码，还要写出能过门禁、能合并、能上线的代码。