Files
praxis/docs/03-git-workflow.md
T
阿白叔andClaude Opus 4.7 154f592f3c docs: split language by audience, add Codex / AGENTS.md spec
Language policy: Chinese for human-facing files (README, docs/,
human-fillable templates), English for AI-facing files (CLAUDE.md,
AGENTS.md, AI templates). Commits / PRs / branches / tags stay
English.

- Translate docs/01-06 to Chinese
- Translate README.md, PR / handoff / project README templates to Chinese
- Drop README.en.md (redundant once language policy is explicit)
- Rewrite CLAUDE.md and CLAUDE.md.template under the new policy
- Add AGENTS.md (root) and templates/AGENTS.md.template for Codex
- Add docs/07-codex.md covering Codex usage and AGENTS.md / CLAUDE.md sync rules

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 09:44:15 +08:00

4.3 KiB
Raw Blame History

03 — Git 工作流

小团队,流程从轻。分支、commit、PR、review、tag。

分支

  • main 永远可发。不直接 push,没有例外。
  • 功能分支:<owner>/<short-slug> —— 比如 bai/auth-retry、 bai/eval-agent-rerun。小写、连字符、你的 handle 做前缀。
  • 长期集成分支:integration/<topic> —— 团队同意才用。
  • 合并完删分支。老分支会污染搜索结果。

Commit

格式:

<area>: <祈使句小结,60 字符以内>

<可选 body —— 写改了什么、为什么,不写怎么改>
  • <area> 是目录或组件,小写:eval-agent、task_assistant、 docs、git-workflow。
  • 祈使句:add、fix、rename,不要 added / adding。
  • Body 在 ~72 字符换行。普通改动跳过 body。
  • 一个 commit 一个主题。摘要里出现"and"——拆。
  • AI 协作的 commit 保留 Claude Code 默认加的 Co-Authored-By trailer。 别去掉。
  • Commit message 用英文(vibe coding 守则之一:给 AI 看的内容用英文)。

例:

eval-agent: rerun failed tasks with stable seed
docs: clarify branch naming in git-workflow
task_assistant: drop unused legacy export path

Pull Request

  • 一个 PR 一个主题。一句话说不清楚——拆成多个 PR。
  • 标题 70 字符以内,跟 commit 摘要同一形态。
  • Description 用 templates/PR_DESCRIPTION.template.md。
  • 第一次 push feature 分支用 -u,让它跟踪远端。
  • 有可跑的东西就开 PR,draft 也行。边写边 review 比写完再 review 好。

Review

每个 PR 都要 review,包括 AI 协作出的,自己也不能跳。

Reviewer 检查清单:

  1. Description 跟 diff 对得上吗?diff 有惊喜——发问。
  2. 改的每个文件都看一遍。文件跟主题无关——发问为什么进了 PR。
  3. 改动不是显而易见就本地跑一遍。
  4. 新依赖、schema 变更、env var、动 auth 的代码——讲清楚理由前 block。
  5. 评论先发最不重要的;merge-blocker 留到最后,让它明显是闸门。

作者收尾:

  • 每条评论都回应,哪怕只是"同意,已在 修"。
  • 不同意写出来 push back,不要默默忽略。
  • 合并前把噪音 commit 压一下(squash fixup commits)。

合并

  • Feature 分支用 squash。Merge commit 留给集成分支。
  • 最终 squash message 按 commit 格式写。PR 标题通常就是好起点。
  • 合并完删分支。

Tag(版本管理)

按日期打 tag:YYYYMMDD(比如 20260520)。每个 tag 是 main 某一时刻的快照——值得指着说"我们就按这版来"。

规则:

  • 只在 main 上打 tag。功能分支打 tag 是 smell。
  • 一天最多一个 tag。同一天再切一个,加 -N 后缀:20260520-2、 20260520-3。
  • 用 annotated tag,不用 lightweight。git tag -a 加一两句说自上次 tag 以来改了什么。
  • Tag 一旦推到远端就不能改、不能删、不能 force-tag。错了就再切一个。
  • Tag commit、push tag、告诉大家 tag 名字——这就是发布。

切 tag:

git checkout main
git pull --ff-only
git tag -a 20260520 -m "team-guide 20260520: bilingual README, dated tags"
git push origin 20260520

查看 / 对比:

git tag --sort=-creatordate           # 按时间倒序
git show 20260520                     # 看一个 tag 里有什么
git log --oneline 20260513..20260520  # 两个 tag 之间改了什么

什么时候切 tag:

  • 本仓库的 docs 改了,队友需要重新读。
  • 加了、删了或重组了 template。
  • 新的约定正式生效(不是还在讨论)。

什么时候不切 tag:

  • 改错别字、调格式、修死链 → 直接 push 到 main。
  • 还在讨论的草稿 → 走 PR,不打 tag。

不要做的事

  • 不要 git push --force 到 main。永远不要。push 到自己分支 也只在确定没人 pull 过的情况下。
  • 不要 --no-verify 跳 hook。修 hook 报的问题。
  • 不要 amend 已经 push 的 commit。已经在远端的就加新 commit。
  • 不要删或移已经 push 的 tag。错了就切新的。
  • 不要提交 .env、密钥、或者 ~5 MB 以上的文件——大文件先聊 Git LFS。
  • 有不认识的 untracked 文件时,不要 git add . / git add -A。 按文件名加。