docs(specs): add AGENTS.md and engineering guidelines
项目尚无统一工程规范，AI 助手与研发各自发挥导致返工风险。建立 总纲 + 细则两层结构：AGENTS.md 只写硬约束与索引（14 条红线、技术栈 基线、仓库结构、命令契约），细则拆为 10 份文档覆盖 Git、代码风格、 格式化、API 与路由、数据库、测试与 CI、Review、日志、密钥、资产命名。 影响面：仅文档。约束力从本轮起对新建代码生效；与现状冲突处以文档为准。 回滚方式：git revert 本提交。
This commit is contained in:
Stev_Wang committed
1 parent
d062d79465
commit
00ae12435e
12 files changed
+1562
No files matched your search
@@ -0,0 +1,122 @@
|
||||
# 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` 禁止直接 push `main`；分支保护开启：必须 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-05` `subject` 用英文祈使句，≤ 72 字符，**不加句号**；中文放正文。
|
||||
- `GIT-06` `scope` 必填，取值见 `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-12` PR 标题遵循提交规范（Squash 后即主干提交信息）。
|
||||
- `GIT-13` 合并方式统一 **Squash Merge**，保持 `main` 线性；禁止 Merge commit。
|
||||
- `GIT-14` 单个 PR 变更 ≤ 400 行（含测试，不含 lock 文件与生成代码）；超出须拆分并在描述说明依赖关系。
|
||||
- `GIT-15` 禁止 force push `main` / 已有人 Review 的公共分支；个人分支允许 `--force-with-lease`。
|
||||
- `GIT-16` PR 描述模板与双人 Review 场景见 [07-CodeReview与PR规范](07-CodeReview与PR规范.md)。
|
||||
|
||||
---
|
||||
|
||||
## 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-19` `pnpm-lock.yaml` 必须提交且与 `package.json` 同步；**禁止**手工编辑 lock 文件。
|
||||
- `GIT-20` 误提交敏感信息：立即轮换密钥 → 用 `git filter-repo` 清理历史 → 全员重新 clone → 记录复盘。
|
||||
|
||||
---
|
||||
|
||||
## 6 检查清单（提交前 / 合并前）
|
||||
|
||||
- [ ] 分支名符合 `GIT-01`，从最新 `main` 拉出
|
||||
- [ ] 提交信息符合 Conventional Commits，含 `scope`
|
||||
- [ ] 提交粒度单一，无无关文件
|
||||
- [ ] 无 `.env` / 密钥 / 大文件
|
||||
- [ ] PR 描述含背景 / 影响面 / 回滚方式 / 验证证据
|
||||
- [ ] CI 全绿，Review 通过，Squash 合并
|
||||
Reference in new issue
Block a user