Git 流程规范
这份文档规定 world-map 项目的 git 协作规则——分支策略、commit 粒度、commit message 规范、PR 流程（如果有的话）。
1. 仓库现状
- 仓库：
~/world-map/ - 远端：暂未配置（本地优先，等内容成型再推）
- 主分支：
master - 作者配置：
world-map-agent <agent@world-map.local>（AI 提交用这个身份） - 人类提交可以用你自己的 git config
2. 分支策略
主分支 master 始终是"可部署/可构建"状态——任何 commit 之后 npx vitepress build 必须能通过。
日常工作在 master 直接做——因为：
- 单人 + AI 双人协作，分支开销大于收益
- AI 每次会话都从 master 拉最新，没有跨会话分支概念
例外——以下两种情况开 feature branch：
- 重大骨架重构（新增/合并/拆分 L 层）：
refactor/skeleton-<short-desc> - 多文件批量改动（>10 个文件）：
feat/<short-desc>
feature branch 合入前必须：
npx vitepress build通过- evolution-log 同步更新
- 注明回退方案
3. Commit 粒度
细粒度优先——一个 commit = 一个逻辑完整的改动单元。
| 改动类型 | 建议粒度 |
|---|---|
| 新建一篇文档 | 1 个 commit |
| 修改一篇文档的多处 | 1 个 commit |
| sidebar 配置变更（多文件） | 1 个 commit |
| 骨架重构 | 1 个 commit + evolution-log 同步 |
| 占位文件批量生成 | 1 个 commit（标注 chore: scaffold） |
反例（不推荐）：
- ❌ 一次 commit 写 5 篇文档（出问题难回退）
- ❌ 一次 commit 改骨架 + 写文章（原子性破坏）
4. Commit Message 规范
采用 Conventional Commits 中文适配版。
格式
<type>(<scope>): <中文简述>
<正文——做了什么、为什么>
<页脚——关联的文档路径或 evolution-log 条目>type 取值
| type | 用途 | 例 |
|---|---|---|
feat | 新增内容（文档、group、文档结构） | feat(L1): 新增限界上下文文章 |
chore | 占位/脚手架/工具配置 | chore: 初始化 5 层骨架 |
refactor | 骨架重构/归档/合并 | refactor: 合并 L3 02-code/03-testing |
fix | 修复死链/格式错误/事实错误 | fix: 修复 L1→L2 链接死链 |
docs | 元文档/约定的修改 | docs: 修订文档撰写约定 |
style | 格式/排版（不改语义） | style: 统一表格对齐 |
scope 取值
- L 层简写：
L1/L2/L3/L4/L5 - 元文档：
meta - 跨 L 层改动：留空
完整示例
feat(L1): 新增限界上下文文章
完成 l1-modeling/02-strategic/bounded-context.md 实质内容。
正文:
- 定义 Bounded Context 与 Subdomain 的关系
- 给出 4 个判定边界的方法
- 列出 3 个常见误区
关联:
- evolution-log 暂无（仅内容填充，未触发骨架变更）
- 源典：Vernon IDDD Ch.25. Commit 前自检
每次 commit 前：
bash
cd ~/world-map && npx vitepress build必须看到 build complete in X.XXs.。绝对不能带着 dead link 警告 commit。
6. 撤销与回退
| 需求 | 命令 |
|---|---|
| 撤销最近一次 commit（保留改动） | git reset --soft HEAD~1 |
| 撤销最近一次 commit（丢弃改动） | git reset --hard HEAD~1 |
| 撤销某次 commit 但保留其后的提交 | git revert <commit-hash> |
| 看历史 | git log --oneline |
骨架重构必须用 git revert 而不是 git reset --hard——因为我们可能有跨会话引用。
7. 协作场景
场景 A：AI 单人写一篇文档
bash
cd ~/world-map
# 1. 写文件
# 2. 自检
npx vitepress build
# 3. 提交
git add l1-modeling/02-strategic/bounded-context.md
git commit -m "feat(L1): 新增限界上下文文章
[正文]"场景 B：AI 提议骨架重构
bash
cd ~/world-map
# 1. 写 evolution-log
# 2. 改 sidebar + 文档
# 3. 自检
npx vitepress build
# 4. 在 feature branch 提交
git checkout -b refactor/skeleton-L3-split
git add -A
git commit -m "refactor: 拆分 L3 实现层为代码+工程化
[正文 + 关联 evolution-log 条目]"
# 5. 等用户审批
# 6. 审批后合入
git checkout master
git merge refactor/skeleton-L3-split场景 C：发现死链
bash
cd ~/world-map
# 1. 跑 build 看死链
npx vitepress build 2>&1 | grep "dead link"
# 2. 修复
# 3. 重新 build 确认
npx vitepress build
# 4. 提交
git add <fixed-file>
git commit -m "fix: 修复 <具体死链描述>"