Stev_Wang
00ae12435e
项目尚无统一工程规范，AI 助手与研发各自发挥导致返工风险。建立 总纲 + 细则两层结构：AGENTS.md 只写硬约束与索引（14 条红线、技术栈 基线、仓库结构、命令契约），细则拆为 10 份文档覆盖 Git、代码风格、 格式化、API 与路由、数据库、测试与 CI、Review、日志、密钥、资产命名。 影响面：仅文档。约束力从本轮起对新建代码生效；与现状冲突处以文档为准。 回滚方式：git revert 本提交。
4.8 KiB
4.8 KiB
01 · Git 规范
| 项 | 内容 |
|---|---|
| 文档版本 | V1.0（2026-11-02） |
| 依据 | 技术架构 §4.6（CI/CD）、§10.1（仓库结构） |
| 适用范围 | 全仓库（代码、文档、配置、迁移） |
| 强制级别 | 强制 |
1 分支模型
采用 trunk-based（主干 + 短生命周期分支），不建 develop、不建长期 release 分支。
| 类型 | 命名 | 用途 | 生命周期 |
|---|---|---|---|
| 主干 | main |
始终可发布 | 永久 |
| 功能 | feat/<scope>-<简述> |
新功能 | ≤ 5 天，超过须拆分 |
| 修复 | fix/<scope>-<简述> |
缺陷修复 | ≤ 2 天 |
| 文档 | docs/<简述> |
仅文档 | ≤ 1 天 |
| 重构 | refactor/<scope>-<简述> |
行为不变的结构调整 | ≤ 3 天 |
| 其他 | chore/ test/ perf/ build/ ci/ |
对应类型 | ≤ 2 天 |
规则：
GIT-01分支名全小写 kebab-case，≤ 50 字符，不含中文；scope用模块或包名（api/web/worker/media/db/ci/docs）。GIT-02分支必须从最新main拉出，合并前 rebase 到main最新。GIT-03禁止直接 pushmain；分支保护开启：必须 PR + CI 绿 + ≥1 批准。GIT-04合并后立即删除远端分支。
2 提交信息（Conventional Commits 1.0）
<type>(<scope>): <subject>
<body：为什么改 + 影响面，中文>
<footer：BREAKING CHANGE / Refs: R-xx / Closes #12>
type |
用途 |
|---|---|
feat |
新功能 |
fix |
缺陷修复 |
docs |
文档 |
style |
仅格式（不影响逻辑） |
refactor |
重构（不改行为） |
perf |
性能 |
test |
测试 |
build |
构建 / 依赖 |
ci |
CI / 脚本 |
chore |
杂项 |
revert |
回滚 |
规则：
GIT-05subject用英文祈使句，≤ 72 字符，不加句号；中文放正文。GIT-06scope必填，取值见GIT-01。GIT-07正文说明「为什么」与「影响面 / 回滚方式」；纯重命名类可仅一行 subject。GIT-08破坏性变更：type后加!且 footer 写BREAKING CHANGE: <说明与迁移方式>。GIT-09关联业务规则写Refs: R-04；关联 issue 写Closes #123。GIT-10一个提交只做一件事；禁止在功能提交里顺带格式化无关文件。GIT-11禁止WIP、fix bug、update等无信息量信息；禁止--no-verify绕过钩子。
示例：
feat(media): 图片批次支持按规格矩阵展开任务项
批量生产原先按「模板 × 商品图」展开，导致同素材多规格重复建素材，
违反 PRD R-25「素材为主对象、规格为属性」。改为展开到 task_item，
规格作为属性写入 material_specs。
影响面：production_tasks 新增 spec_key 列（expand 迁移，兼容旧数据）。
回滚方式：关闭 FEATURE_MATRIX_SPEC 开关，旧路径仍可用。
Refs: R-25
3 PR 与合并
GIT-12PR 标题遵循提交规范（Squash 后即主干提交信息）。GIT-13合并方式统一 Squash Merge，保持main线性；禁止 Merge commit。GIT-14单个 PR 变更 ≤ 400 行（含测试，不含 lock 文件与生成代码）；超出须拆分并在描述说明依赖关系。GIT-15禁止 force pushmain/ 已有人 Review 的公共分支；个人分支允许--force-with-lease。GIT-16PR 描述模板与双人 Review 场景见 07-CodeReview与PR规范。
4 Tag 与发布
| 项 | 规则 |
|---|---|
| 版本号 | 语义化 v<主>.<次>.<补> |
| 打 Tag 时机 | 生产发布前，由发布负责人在 main 打 annotated tag |
| 里程碑 Tag | m0 / m1 / m2…（对应 PRD 分期），仅标记不进版本链 |
| 发布记录 | 每个 Tag 必须写变更摘要（可复用 PR 标题集合） |
| 回滚 | 回滚用新 Tag（v1.2.1 回滚 v1.2.0 内容），禁止删除已发布 Tag |
5 大文件与二进制
GIT-17禁止入库 > 10 MB 的二进制（PSD 模板、成片、视频、字体包），一律走对象存储；确需入库（如开源字体）用 Git LFS 并在 PR 说明。GIT-18禁止入库：.env*、密钥、证书私钥、构建产物、node_modules/、日志、项目参考/。GIT-19pnpm-lock.yaml必须提交且与package.json同步；禁止手工编辑 lock 文件。GIT-20误提交敏感信息：立即轮换密钥 → 用git filter-repo清理历史 → 全员重新 clone → 记录复盘。
6 检查清单（提交前 / 合并前）
- 分支名符合
GIT-01，从最新main拉出 - 提交信息符合 Conventional Commits，含
scope - 提交粒度单一，无无关文件
- 无
.env/ 密钥 / 大文件 - PR 描述含背景 / 影响面 / 回滚方式 / 验证证据
- CI 全绿，Review 通过，Squash 合并