04-Git提交发布与复盘 - 从0开始的AI Coding 学习

用途

前面三页已经把 TODO 小工具的需求、协作、实现、测试和审查走了一遍。本页继续沿用同一个项目：在 todo.py 中加入按序号完成待办的功能，并把这次改动从工作区交付到可发布版本。本页关注的不是某个 GitHub 按钮的位置，而是一条可以重复执行的交付链：

确认工作区
  -> 提交前清单
  -> 拆分可审查的 commit
  -> 创建并更新 PR
  -> 等待 CI 和人工审查
  -> 发布审批
  -> 小流量验证
  -> 完整交付记录
  -> 必要时回滚
  -> 复盘并沉淀规则

示例假设如下：

项目目录为 todo-cli，入口是 todo.py。
主分支为 main，功能分支为 feat/todo-done。
项目使用 Python 3 标准库，不引入第三方依赖。
python -m unittest 是本项目的测试命令。
发布产物是一个 Git tag 和对应的 GitHub Release；如果你的项目有包管理器、容器镜像或部署平台，把发布步骤替换成真实命令。
所有命令都先在测试环境演练。示例中的哈希、时间、版本号和 URL 只用于说明，不能当作你的真实值。

Git、GitHub Actions、Codex 和发布平台的界面或参数可能随版本变化。命令执行前先用 git --help、gh --help、项目脚本和平台文档确认；不要因为示例看起来熟悉，就跳过影响范围检查。

本页完成标准

读完并实际演练后，你应当能够：

在提交前确认分支、差异、测试、密钥和发布范围。
把一个混杂改动拆成容易 review、容易回滚的多个 commit。
创建包含背景、验证证据和回滚方案的 PR。
看懂 CI 的状态、日志和门禁，不把本地通过误认为合并通过。
区分合并审批、发布审批和生产操作授权。
发布后按同一路径做冒烟验证，并在异常时选择合适的回滚方式。
写出可交接的完整交付记录，并把重复问题转成项目规则。

01 先固定这次交付的边界

本次连续实战的需求是：用户执行 done <序号> 后，将待办标记为完成；list 能清楚显示状态；输入非数字或越界序号时给出友好提示。在动 Git 之前，先把目标和非目标写下来。一个可交付的范围表如下：

项目	本次范围	不在本次范围
功能	`done <序号>`、状态展示、边界提示	登录、同步、数据库持久化
文件	`todo.py`、`test_todo.py`、必要的项目说明	无关目录、个人配置、生产配置
验证	单元测试、命令行冒烟、差异审查	未准备好的真实外部服务
发布	版本标签、Release 说明、测试环境验证	未审批的生产发布
回滚	删除错误标签或回退应用版本	改写共享分支历史

用一句话写出本次交付声明：

本次发布只包含 todo.py 的完成状态功能和对应测试；不改变存储格式、依赖和部署配置；发布前必须通过 unittest、命令行冒烟和人工 PR 审查；生产发布需要单独审批。

这句话的作用是限制范围。它不是提交信息，也不是 PR 的全部内容，而是后面检查“有没有夹带改动”的比较基准。

先确认仓库位置

pwd
git rev-parse --show-toplevel
git branch --show-current
git status --short --branch

预期输出类似：

/e/work/todo-cli
/e/work/todo-cli
feat/todo-done
## feat/todo-done...origin/feat/todo-done
 M todo.py
 M test_todo.py

检查重点：

git rev-parse --show-toplevel 必须是当前项目根目录。
当前分支必须是本次功能分支，不要在 main 上直接开发。
status 中列出的文件应当能解释清楚；出现 .env、密钥、数据库备份、构建缓存或陌生文件时先停下。
分支后面的远端跟踪关系要正确。若显示与预期不同，先确认远端和分支，不要直接推送。

查看远端和近期历史：

git remote -v
git log --oneline --decorate --graph -8

预期输出类似：

origin  https://github.com/example/todo-cli.git (fetch)
origin  https://github.com/example/todo-cli.git (push)
* 8f2a1c4 (HEAD -> feat/todo-done) wip: 完成状态初版
* 31d9e02 (origin/main, main) chore: 初始化 TODO 工具

如果工作区中已有同事的未提交改动，不要用 git restore .、git reset --hard 或删除命令清理。先保存现状，按文件和补丁判断哪些属于本次工作。

02 提交前清单：先检查，再落锤

提交是把当前状态写进项目历史。它不是临时保存按钮，也不是“先提交再慢慢看”的替代品。提交前至少完成以下六类检查：范围、内容、测试、敏感信息、可运行性和回滚点。

2.1 检查工作区范围

git status --short
git diff --stat
git diff --name-only

预期输出类似：

 M test_todo.py
 M todo.py
 test_todo.py | 24 ++++++++++++++++++++++++
 todo.py      | 17 ++++++++++++++++-
 2 files changed, 40 insertions(+), 1 deletion(-)
test_todo.py
todo.py

看到以下情况要先处理：

改动文件超过本次范围。
新增了没有解释的脚本、二进制文件或构建目录。
只有测试改动，没有对应实现改动，或者反过来只有实现没有测试。
文件名大小写、换行符或生成文件发生大面积变化。

检查未跟踪文件时用：

git status --short --untracked-files=all
git check-ignore -v .env dist/ __pycache__/

预期可能是：

?? .env
.gitignore:3:.env .env
.gitignore:5:__pycache__/ __pycache__/

如果 .env 同时显示为 ?? .env，说明它没有被忽略。不要把真实凭据加入暂存区；先移出工作目录或补充合适的忽略规则，并确认忽略规则本身符合团队约定。

2.2 阅读完整 diff

不要只看统计数字。先看未暂存差异：

git diff -- todo.py test_todo.py

如果已经暂存，再看暂存区：

git diff --cached -- todo.py test_todo.py

阅读时按这张表逐项问自己：

检查项	要回答的问题
行为	`done 1`、`done 0`、`done abc` 分别会发生什么？
状态	已完成待办再次执行会不会重复计数或破坏数据？
输入	空参数、额外参数、负数和超大数字如何处理？
输出	正常输出和错误输出是否稳定、可读、可测试？
兼容性	原来的 `add` 和 `list` 行为是否保留？
测试	每个验收条件是否有测试，测试是否真的会失败于旧实现？
范围	是否顺手重命名、格式化或重构了不相关代码？
安全	是否把路径、令牌、用户数据或调试输出写进代码？

2.3 运行项目验证

先运行完整测试：

python -m unittest -v

预期输出类似：

test_done_marks_item_complete (test_todo.TestTodo) ... ok
test_done_rejects_non_numeric_index (test_todo.TestTodo) ... ok
test_done_rejects_out_of_range_index (test_todo.TestTodo) ... ok
test_list_keeps_pending_behavior (test_todo.TestTodo) ... ok

----------------------------------------------------------------------
Ran 4 tests in 0.002s

OK

测试通过后做命令行冒烟：

python todo.py add 买咖啡豆
python todo.py add 写发布记录
python todo.py list
python todo.py done 1
python todo.py list
python todo.py done abc
python todo.py done 99

预期输出示意：

已添加：买咖啡豆
已添加：写发布记录
1. [未完成] 买咖啡豆
2. [未完成] 写发布记录
已完成：买咖啡豆
1. [已完成] 买咖啡豆
2. [未完成] 写发布记录
序号必须是数字
没有找到序号为 99 的待办

示例项目如果仍然只把数据放在内存中，那么每次启动都是新进程，跨命令保存不会成立。此时命令行冒烟只验证进程内行为，持久化行为必须由测试或另一个明确的存储实现验证。不要把“能打印一次”写成“数据已经保存”。

2.4 检查空白和差异边界

git diff --check

没有输出通常表示没有发现 Git 能识别的空白错误。若有输出，示例为：

todo.py:42: trailing whitespace.

修复后重新检查。不要为了让命令安静而关闭检查。确认当前提交与主分支的差异：

git fetch origin main
git diff --stat origin/main...HEAD
git diff --name-status origin/main...HEAD

预期应只出现本次功能需要的文件，例如：

M	todo.py
M	test_todo.py

2.5 搜索敏感信息和本地产物

用仓库已有的扫描工具优先；没有工具时至少做一轮人工和文本搜索：

rg -n --hidden -g '!.git' -g '!__pycache__' -g '!dist' '(sk-[A-Za-z0-9]|BEGIN .* PRIVATE KEY|password\s*=|token\s*=|Authorization:)' .

预期的合格结果是没有真实敏感值命中。占位符可以保留，例如：

OPENAI_API_KEY=<set-in-github-secrets>
Authorization: Bearer <redacted>

命令历史、终端日志、测试快照和 CI artifact 也可能含有凭据。发现泄露时不要只删除当前行：立即撤销或轮换凭据，检查历史和日志可见范围，再按安全流程处理。

2.6 形成提交前结论

在提交前写一段简短结论，方便自己和 reviewer 对照：

提交前结论：
- 范围：只改 todo.py、test_todo.py
- 功能：done 正常路径和两个错误路径已覆盖
- 验证：python -m unittest -v 通过；命令行冒烟通过
- 安全：未发现密钥、用户数据和临时产物
- 回滚：可通过反向提交撤销功能，或回退到 31d9e02
- 未验证：内存存储不支持跨进程持久化，不属于本次范围

这段结论可以放在本地交付记录中，也可以改写后放到 PR 描述。它的价值在于把“我觉得没问题”变成可核对的事实和明确的未知项。

03 commit 拆分：让每个提交只有一个理由

一个 PR 可以包含多个 commit，但每个 commit 最好都有单一目的。这样 reviewer 能按逻辑阅读，回滚时也能选择范围，git bisect 才更容易定位问题。本次 TODO 改动可以拆成三个提交：

顺序	commit 目的	典型文件
1	先补充会失败的测试，固定需求	`test_todo.py`
2	实现完成状态和输入校验	`todo.py`
3	更新运行说明和变更记录	`AGENTS.md` 或 `CHANGELOG.md`

如果本次任务明确只允许改 todo.py 和测试，就不要为了“完整”新增无关文档。提交拆分服务于审查，不是制造提交数量。

3.1 先查看已有暂存状态

git reset
git status --short
git diff --stat

git reset 在这里仅撤销暂存，不会删除工作区内容。执行前确认命令没有写成 git reset --hard。

3.2 用交互暂存拆分内容

git add -p test_todo.py
git diff --cached -- test_todo.py
git commit -m "test: 覆盖待办完成状态和边界输入"

预期输出类似：

[feat/todo-done 6c8f7a1] test: 覆盖待办完成状态和边界输入
 1 file changed, 24 insertions(+)

交互暂存常见选项：

选项	含义
`y`	暂存当前块
`n`	不暂存当前块
`s`	尝试把当前块进一步拆小
`e`	手工编辑当前块
`q`	退出

如果一个函数实现和测试混在同一个大块里，优先用 s 拆分；拆不开时先不要强行提交，手工整理代码后重新检查。

3.3 提交实现

git add todo.py
git diff --cached --check
git diff --cached --stat
git commit -m "feat: 支持按序号完成待办"

预期输出：

[feat/todo-done 9b71d2e] feat: 支持按序号完成待办
 1 file changed, 17 insertions(+), 1 deletion(-)

3.4 提交前后检查历史

git status --short
git log --oneline --decorate --max-count=4
git show --stat --oneline HEAD

预期类似：

9b71d2e (HEAD -> feat/todo-done) feat: 支持按序号完成待办
6c8f7a1 test: 覆盖待办完成状态和边界输入
31d9e02 (origin/main, main) chore: 初始化 TODO 工具

合格的提交历史应当满足：

每个 commit 都能用一句话解释。
测试提交和实现提交都能单独阅读。
没有把格式化、重命名和业务逻辑混在一个提交里。
每个提交都不包含凭据或无关文件。

3.5 什么时候可以合并 commit

在提交到远端前，如果团队允许整理分支历史，可以用交互式 rebase 合并明显的修正提交：

git rebase -i origin/main

这会改写当前功能分支的本地历史。只对自己独占、尚未被他人基于它开发的分支这样做；已经被同事拉取的共享分支不要随意 rebase 后强推。常见策略：

需要展示测试先行和实现过程：保留多个逻辑清晰的 commit。
团队要求一个 PR 一个可回退版本：在确认规则后 squash 成一个提交。
已经公开、有人基于其开发：保留历史，追加修复提交。

无论采用哪种策略，都不能用“历史整洁”掩盖未验证的改动。

04 推送功能分支并创建 PR

提交前再次确认不会把改动推到主分支：

git branch --show-current
git status --short --branch
git log --oneline origin/main..HEAD

预期当前分支为 feat/todo-done，且只列出本次两个或三个 commit。推送功能分支：

git push -u origin feat/todo-done

预期类似：

Enumerating objects: 9, done.
Writing objects: 100% (9/9), done.
branch 'feat/todo-done' set up to track 'origin/feat/todo-done'.

推送是外部写入动作。第一次推送前要核对：远端仓库、分支名、提交内容、账号和是否包含敏感信息。不要使用 git push --force 作为“推不上去”的第一反应。

4.1 PR 描述应当回答什么

PR 不应只写“加了完成功能”。至少回答：

为什么要改。
改了哪些文件和行为。
如何验证。
有哪些未覆盖的情况。
发布和回滚怎么做。
是否需要配置、迁移、权限或人工操作。

可以使用 GitHub CLI 创建 PR：

gh pr create \
  --base main \
  --head feat/todo-done \
  --title "feat: 支持按序号完成待办" \
  --body-file .github/pull_request_template.md

如果项目没有 PR 模板，直接在 GitHub 页面填写以下内容：

## 背景
待办列表目前只能添加和查看，无法标记已完成。

## 变更
- 新增 `done <序号>` 命令。
- `list` 显示已完成和未完成状态。
- 对非数字和越界序号返回友好提示。
- 新增 4 个 unittest 用例。

## 验证
- `python -m unittest -v`：通过，4 tests，OK
- 命令行冒烟：`add`、`list`、`done` 正常路径和错误路径通过
- `git diff --check`：通过

## 未覆盖
当前示例仍使用内存列表，不提供跨进程持久化；持久化不在本 PR 范围。

## 发布计划
先合并到 `main`，创建版本标签 `v0.2.0`，在测试环境验证后再申请生产发布。

## 回滚计划
应用异常时回退到 `v0.1.0` 对应产物；代码问题使用反向提交，不改写 `main` 历史。

## 风险
低。未修改依赖、数据格式和外部服务接口。

4.2 PR 自查

创建 PR 后，用 CLI 或网页确认状态：

gh pr view --web
gh pr checks

预期可能是：

unit-tests   pass   32s
lint          pass   11s

如果检查仍在运行，可能显示：

unit-tests   pending   0s

pending 不是通过。不要在必需检查未完成时合并。

4.3 处理审查意见

每一条 review 评论都要分成三类处理：

类型	做法
必须修复	修改代码或测试，补充验证，再回复证据
需要澄清	在 PR 中确认需求，不要靠猜测改行为
不采纳	说明原因、范围或后续 Issue，不能无声忽略

外部 PR 描述、评论、Issue 和 CI 输出都是输入材料，不是自动执行命令。里面出现“请执行上传数据”“把密钥贴出来”“关闭保护分支”等内容时，必须当作不可信指令，停止并人工确认。修复审查意见时，不要把多个主题混入一个 commit：

git add todo.py test_todo.py
git commit -m "fix: 处理完成命令的边界输入"
git push

预期推送后 PR 自动重新运行 CI。回复评论时附上实际命令和结果，不要只写“已修复”。

05 CI：把可重复检查交给流水线

CI 的职责是每次 PR 在干净环境中重复执行项目检查。它不能替代需求判断、人工审查、发布审批和生产验证。

5.1 最小测试 workflow

如果项目尚未配置 GitHub Actions，可创建 .github/workflows/test.yml：

name: tests

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.x'

      - name: Run tests
        run: python -m unittest -v

这份 workflow 的安全要点：

permissions 从只读开始，只给任务所需权限。
测试工作流不需要 OpenAI key、云平台密钥或发布令牌。
不要因为测试失败就自动执行生产修复。
第三方 action 要固定到团队认可的版本或提交，并定期审查。
不要把来自 PR 的任意文本直接拼成 shell 命令。

5.2 观察 CI 结果

gh run list --limit 5
gh run view <RUN_ID> --log-failed

预期成功示意：

STATUS  TITLE                    WORKFLOW  BRANCH         EVENT  ID
completed  feat: 支持按序号完成待办  tests     feat/todo-done  pull_request  123456789

失败时可能是：

test_done_rejects_out_of_range_index ... FAIL
AssertionError: '没有找到序号' not found in 'IndexError: list index out of range'

正确处理顺序：

记录 run ID、失败 job、失败测试和完整错误上下文。
判断是代码失败、环境失败、依赖不可用还是 CI 配置错误。
在本地复现同一个命令，不要盲改 workflow。
修复后重新运行测试并推送小范围 commit。
确认新 run 通过，旧失败 run 保留为审查记录。

5.3 CI 通过不等于可以发布

至少区分四个结论：

结论	证明什么	没证明什么
单元测试通过	已覆盖的输入行为通过	未覆盖路径、真实环境和发布产物
CI 通过	干净 runner 上检查通过	需求一定正确、生产一定可用
PR 批准	指定 reviewer 接受变更	生产发布已经获批
冒烟通过	指定环境和路径当前正常	未来流量、长时间运行和所有用户正常

因此 PR 合并前的最低门槛应当是：必需 CI 通过、至少一名合适 reviewer 批准、范围和风险已确认、发布和回滚方案已写明。

5.4 自动化的边界

可以把重复、只读、容易验证的检查交给 Codex 或 CI，例如：

运行测试、lint、类型检查。
生成 PR 摘要和变更清单。
检查是否缺少测试或是否出现明显敏感信息。
在隔离分支生成候选修复。

不要无人值守地交给自动化：

合并受保护主分支。
强制推送或删除远端历史。
直接修改生产数据、权限、计费、通知和可见性。
读取并外发密钥、客户数据或完整生产日志。
未经审批发布到真实用户可见的环境。

如果在 CI 中运行 Codex，纯审查任务优先 read-only；需要写文件时才使用最小的 workspace-write。密钥只作为单个步骤的输入，不要设置为整个 job 的环境变量。自动生成的修改必须像人工修改一样经过 diff、测试、PR 和审批。

06 合并和发布审批：两个不同的放行点

“合并到 main”和“发布到生产”不是同一个动作。合并表示代码进入主干；发布表示产物对外生效，影响用户、数据和服务。

6.1 合并前审批清单

合并人应逐项确认：

[ ] PR 基于最新 main，或明确知道没有冲突风险
[ ] 必需 CI 全部通过
[ ] 业务 reviewer 已批准
[ ] diff 只包含本次需求
[ ] 测试、配置、迁移和依赖变化已说明
[ ] 兼容性和安全影响已判断
[ ] 发布窗口、负责人和回滚方式已确定
[ ] 没有把“以后再处理”的高风险问题藏在评论里

预期的合并前状态应类似：

Required checks: 3 passed
Review: 1 approving review
Merge conflicts: none
Branch protection: satisfied

如果平台显示“可以合并”，仍要由明确的责任人判断是否现在合并。机器状态是证据，不是授权。

6.2 创建发布候选版本

合并完成后，在本地同步并确认主干：

git switch main
git pull --ff-only origin main
git log --oneline --decorate -5

--ff-only 能避免在不知情时自动制造合并提交。若失败，先查看分叉原因，不要用强制方式覆盖历史。创建候选标签前检查版本和提交：

git tag --list 'v*' --sort=-version:refname | head -5
git show --stat --oneline HEAD

示例输出：

v0.1.0
v0.0.1
9b71d2e (HEAD -> main, origin/main) feat: 支持按序号完成待办

给版本打标签：

git tag -a v0.2.0 -m "release: TODO 工具 v0.2.0"
git show v0.2.0 --no-patch

预期：

tag v0.2.0
Tagger: Developer <developer@example.com>
release: TODO 工具 v0.2.0

标签也是外部发布信号。推送前必须经过发布审批：

git push origin v0.2.0

如果团队把标签推送视为正式发布触发器，就不要在审批前执行这条命令。可以先在本地打标签、让审批人检查，再推送。

6.3 发布记录必须包含的内容

发布审批至少包含：

发布版本和对应 commit SHA。
变更摘要、影响用户和不影响的范围。
CI run 链接及关键结果。
测试环境和冒烟验证证据。
数据库、配置、依赖和权限变化。
发布开始和结束时间、负责人、观察窗口。
明确的回滚版本和回滚命令。
监控指标、日志位置和异常升级联系人。

审批人不能只看到“测试绿了”。如果找不到 commit、产物校验值或回滚版本，发布应暂停。

07 外部发布红线

发布会改变仓库、服务、用户体验或外部系统状态。以下动作必须由人明确确认，不能因为命令写在脚本里就默认允许：

红线动作	原因	最低要求
推送主分支或发布标签	改变远端协作和发布触发状态	核对仓库、分支、commit、审批人
合并 PR	让代码成为团队基线	CI 通过、review 批准、责任人确认
部署生产	对真实用户和数据生效	发布窗口、监控、回滚准备就绪
修改生产数据	可能不可逆并影响合规	变更单、备份、最小范围、复核
轮换或写入密钥	影响外部访问权限	密钥管理系统、审计和回收计划
发送通知或公开 Release	对外形成事实	脱敏、内容审核、明确受众
`git push --force`	可能覆盖他人历史	默认禁止；确有必要时人工双重确认

以下内容永远不要放进公开 PR、Release、Issue、日志或交付记录：

API key、密码、Cookie、SSH 私钥和完整令牌。
客户姓名、邮箱、手机号、订单号和完整请求体。
内部主机名、私有 URL、未公开漏洞细节和完整 IP。
未经批准的截图、数据库导出和生产日志。

脱敏不能把证据删成空白。可以保留时间、状态码、错误类型、路由形状和关联 ID 的不可逆摘要：

原始：Authorization: Bearer eyJhbGciOi...secret
记录：Authorization: Bearer <redacted>

原始：user=alice@example.com order=order_20260905_123456
记录：user=<user-email> order=<order-id>

原始：2026-09-05 14:03:22 POST /internal/payments/123 500
记录：2026-09-05 14:03:22 POST /<payment-id> 500

如果工具输出含有敏感信息，不要复制粘贴到聊天中让自动化处理。先截取必要上下文、脱敏，再继续。

08 发布后的验证：从用户路径开始

发布完成后不要只检查部署平台显示绿色。沿着用户真正使用的路径验证：

python todo.py add 发布后验证
python todo.py list
python todo.py done 1
python todo.py list

预期：

已添加：发布后验证
1. [未完成] 发布后验证
已完成：发布后验证
1. [已完成] 发布后验证

如果是 Web 服务或 API，记录以下信息：

发布版本和 commit SHA。
请求时间、环境、路由和状态码。
关键响应字段是否符合预期，敏感值已脱敏。
错误率、延迟、队列积压和资源使用是否异常。
一次正常路径和一次错误路径是否都符合预期。

发布观察窗口内，持续查看指标和日志。不要因为一次人工请求成功就立即关闭观察。若系统有 feature flag，先以小范围、低风险用户验证，再扩大范围。合格的发布结论类似：

v0.2.0 已部署到 staging，commit 9b71d2e。
冒烟：add/list/done 正常路径、非数字和越界路径均通过。
观察 15 分钟：错误率 0%，无新增异常日志。
生产发布：等待产品负责人和当班发布人批准。

09 回滚：先判断类型，再选择动作

回滚不是一句“把代码退回去”。先判断故障发生在哪一层：代码、配置、数据、依赖、发布产物还是外部服务。不同层级的回滚方式不同。

9.1 未提交的工作区错误

如果只是本次未提交的明确单文件改动，且已确认没有同事工作，可以保存补丁后恢复：

git diff -- todo.py > /tmp/todo-before-restore.patch
git restore --source=HEAD -- todo.py

预期：todo.py 回到当前提交，补丁保存在临时位置。Windows 环境请把临时路径替换成合适位置，并确认补丁没有包含敏感信息。不要对存在他人改动的文件直接执行 restore。先分离、备份或通过交接确认。

9.2 已合并代码的修复

如果错误代码已经进入 main，共享分支通常使用新的反向提交：

git revert <BAD_COMMIT_SHA>
git log --oneline --decorate -3
git push origin main

预期会产生类似：

Revert "feat: 支持按序号完成待办"

这会保留历史，方便审计和定位。不要为了“让历史看起来干净”在共享主分支上 reset 后强推。

9.3 已发布版本的回退

如果发布平台支持按版本回退，回退到上一个已验证产物：

当前版本：v0.2.0 / 9b71d2e
回退版本：v0.1.0 / 31d9e02
原因：生产冒烟发现 done 命令在真实存储适配器上返回 500
执行人：发布负责人
审批人：当班技术负责人

回退后必须重新走用户路径验证，并记录回退不是“成功”而是“恢复到了哪个可用版本”。

9.4 配置、数据和依赖问题

配置错误：恢复上一个已验证配置版本，并检查配置缓存和重启范围。
数据迁移错误：使用经过演练的 down migration、备份恢复或平台提供的恢复点；不要用代码回退代替数据修复。
依赖漏洞或不兼容：固定到已验证版本，重新跑完整 CI 和安全扫描。
外部服务异常：启用降级、重试或 feature flag，记录外部依赖状态；不要盲目反复发布。

9.5 回滚后的确认

[ ] 用户主要路径恢复
[ ] 错误率和延迟回到基线
[ ] 没有遗留半完成数据或重复任务
[ ] 相关通知已发送并脱敏
[ ] 故障时间线和操作人已记录
[ ] 已创建后续修复任务

回滚结束后不要立刻删除失败产物、CI 日志或审查记录。它们是复盘所需证据。

10 完整交付记录模板

下面的模板可以复制到 PR、发布单、Issue 或内部交接记录中。只填事实；没有验证的内容写“未验证”和原因，不要用猜测补齐。

# 交付记录：<项目> <版本>

## 1. 基本信息
- 项目：<项目名称>
- 需求：<Issue / 任务链接>
- 版本：<vX.Y.Z>
- commit：<完整 SHA>
- 分支：<分支名>
- 发布环境：<staging / production>
- 发布窗口：<开始时间> - <结束时间，含时区>
- 负责人：<姓名或团队>
- 审批人：<姓名或团队>

## 2. 变更范围
- 做了什么：
  - <变更 1>
  - <变更 2>
- 明确没做什么：
  - <非目标 1>
  - <非目标 2>
- 涉及文件、服务、配置或数据：
  - <列表>

## 3. 提交记录
- <SHA> <type>: <message>
- <SHA> <type>: <message>
- 是否整理历史：<否 / 是，说明方式>

## 4. 验证证据
- 命令：`<command>`
  - 结果：<通过 / 失败>
  - 摘要：<例如 Ran 4 tests; OK>
- 命令：`<command>`
  - 结果：<通过 / 失败>
  - 摘要：<关键输出>
- CI：<workflow、run ID、链接、结果>
- 人工冒烟：<用户路径、环境、结果>
- 未验证项：<内容、原因、补验证计划>

## 5. 审查与审批
- PR：<链接>
- reviewer：<人员>
- 必需检查：<列表和结果>
- 高风险问题：<无 / 列表>
- 发布批准：<人员、时间、依据>

## 6. 发布动作
- 产物：<包、镜像、标签或部署版本>
- 校验：<SHA256 或平台版本号>
- 执行动作：<命令或平台操作的摘要>
- 观察窗口：<时长>
- 监控结果：<错误率、延迟、日志、队列等>

## 7. 回滚方案
- 触发条件：<具体阈值或用户症状>
- 回滚目标：<版本 / SHA / 配置版本>
- 执行命令：`<command>`
- 数据处理：<无需处理 / 备份 / 迁移回退>
- 回滚负责人：<人员>
- 回滚后验证：<路径和结果>

## 8. 风险和后续
- 当前已知风险：<列表>
- 后续任务：<Issue 链接和截止时间>
- 需要沉淀的规则：<规则候选>
- 记录完成时间：<时间>

10.1 示例交付记录

# 交付记录：todo-cli v0.2.0

## 1. 基本信息
- 项目：todo-cli
- 需求：TASK-42
- 版本：v0.2.0
- commit：9b71d2e
- 分支：main
- 发布环境：staging
- 发布窗口：2026-09-05 10:00-10:20 Asia/Shanghai
- 负责人：开发组 A
- 审批人：值班技术负责人

## 2. 变更范围
- 新增 `done <序号>`，支持标记待办完成。
- `list` 增加完成状态显示。
- 增加非数字和越界输入提示。
- 未改变存储格式、第三方依赖和外部服务。

## 3. 提交记录
- 6c8f7a1 test: 覆盖待办完成状态和边界输入
- 9b71d2e feat: 支持按序号完成待办

## 4. 验证证据
- `python -m unittest -v`：通过，4 tests，OK。
- 命令行冒烟：`add`、`list`、`done 1`、`done abc`、`done 99` 均符合预期。
- `git diff --check`：通过。
- CI run 123456789：通过。
- 未验证：跨进程持久化，本版本不提供该能力。

## 5. 审查与审批
- PR：<PR-链接>
- reviewer：<reviewer>
- 必需检查：tests 通过，branch protection 满足。
- 发布批准：<审批人>，2026-09-05 09:55。

## 6. 发布动作
- 产物：Git tag `v0.2.0`。
- staging 冒烟通过，观察 15 分钟无异常。

## 7. 回滚方案
- 触发条件：done 正常路径报错、错误率升高或状态展示异常。
- 回滚目标：`v0.1.0`。
- 代码问题：创建 `git revert` PR；发布问题：恢复 `v0.1.0` 产物。

## 8. 风险和后续
- 已知风险：内存数据不会跨进程保存。
- 后续：TASK-43 评估文件存储，不在本次发布处理。

11 复盘：从一次发布变成下一次规则

复盘不是追责会议，也不是把“大家以后注意”写进文档。有效复盘要回答：发生了什么、证据是什么、为什么没有更早发现、下一次由什么机制阻止重复发生。

11.1 四段式复盘

用以下顺序写，不要先写结论：

事实：按时间线记录命令、commit、CI、审批、发布和用户症状。
影响：影响了哪些用户、环境、数据、时间和服务指标。
原因：区分直接原因、促成条件和没有拦住它的流程缺口。
行动：每项行动有负责人、截止时间和验收证据。

时间线示例：

10  PR 创建，包含 done 功能和 4 个测试
14  CI 通过，review 批准
20  v0.2.0 部署 staging
23  staging 冒烟通过
35  生产发布
41  真实存储适配器出现 500
45  关闭 feature flag，恢复 v0.1.0
05  用户路径恢复，创建 TASK-44

11.2 五个为什么的使用边界

例如：

问题：生产环境执行 done 返回 500。
为什么 1：真实存储适配器未实现新状态字段。
为什么 2：测试只覆盖内存实现。
为什么 3：集成测试没有进入必需 CI 检查。
为什么 4：发布清单没有要求真实适配器验证。
为什么 5：项目规则只写了 unit test，没有写发布前的适配器矩阵。

最后的改进不应是“开发更仔细”，而应是可执行机制：

增加真实适配器集成测试。
将该测试加入必需 CI。
在发布模板中列出适配器矩阵。
staging 冒烟必须覆盖真实存储路径。

11.3 行动项写成可验收任务

不合格写法	合格写法
加强测试	为真实存储适配器增加 `done` 正常和异常用例，CI run 通过
注意发布	在发布模板增加 commit、产物、冒烟和回滚字段，下一次发布使用
优化 review	在 `AGENTS.md` 的 Review guidelines 增加状态迁移检查
避免再出问题	增加 feature flag 和恢复演练，记录演练输出

每项行动都应有：

行动：<要改变的机制>
负责人：<人或团队>
截止时间：<时间>
验收：<命令、PR、监控或演练证据>
状态：<未开始 / 进行中 / 完成>

12 规则沉淀：把复盘结论放到正确位置

不是所有经验都应该写进同一个文件。按照寿命和作用分层：

内容	放置位置
本次一次性范围、版本和审批	PR、发布单、交付记录
每次都适用的运行和测试命令	`AGENTS.md`
代码审查重点	`AGENTS.md` 的 `Review guidelines`
可重复的多步操作	脚本、Makefile、任务配置
需要定时执行的稳定检查	CI workflow 或自动化任务
长期架构决定	ADR 或项目设计记录
个人偏好	个人配置，不要污染团队规则

项目根目录可以保留一份短而准确的 AGENTS.md：

# todo-cli

## 运行
- 添加：`python todo.py add <内容>`
- 列出：`python todo.py list`
- 完成：`python todo.py done <序号>`

## 测试
- `python -m unittest -v`
- 修改行为时必须新增或更新测试。

## 提交与 PR
- 一个 commit 只表达一个目的。
- PR 必须包含变更范围、验证命令、未验证项和回滚方式。
- 不要提交 `.env`、凭据、客户数据或构建产物。

## Review guidelines
- 检查序号边界、空输入和重复完成行为。
- 保持原有命令兼容性。
- 不要把用户数据或敏感值写入日志。
- 修改存储、权限或外部服务时，必须补充集成验证和回滚说明。

把一次性要求写进每次 PR，而不是永久污染规则。例如“本次只发布 staging”“本次不修改存储格式”属于本次交付，不应永久写进 AGENTS.md。规则改变后也要像代码一样审查：

git diff -- AGENTS.md
git diff --check

避免把未经验证的失败经验写成绝对规则。先确认问题可重复、规则可执行，再提交规则变更。

13 最终验收表

在宣布交付完成前，逐项打勾并保留证据：

范围与工作区
[ ] 仓库根目录、远端和当前分支已确认
[ ] diff 文件范围与需求一致
[ ] 未跟踪文件和生成物已处理
[ ] 未发现凭据、用户数据和内部敏感信息

提交与 PR
[ ] commit 按单一目的拆分
[ ] 提交信息说明了真实变化
[ ] PR 写明背景、变更、验证、风险和回滚
[ ] PR 讨论中的高优先级问题已处理

验证与 CI
[ ] 单元测试通过
[ ] 必要的集成或端到端检查通过
[ ] 命令行或用户路径冒烟通过
[ ] `git diff --check` 通过
[ ] 必需 CI 全部通过，run ID 已记录

审批与发布
[ ] 合并审批和生产发布审批分别确认
[ ] 发布 commit、标签和产物已核对
[ ] 观察窗口、监控和负责人已确定
[ ] 外部发布内容已脱敏并经过审核

恢复与复盘
[ ] 回滚目标可用且未经过程
[ ] 发布结果和异常已记录
[ ] 未验证项和后续 Issue 已登记
[ ] 可复用经验已沉淀到规则、脚本或 CI

若任何一项只能写“应该没问题”，就还没有完成验收。把它改成命令、链接、日志摘要、截图编号或明确的未验证说明。

小结

本次 TODO 项目的交付闭环可以压缩成八句话：

先确认目录、分支、远端和范围。
用完整 diff 和测试证明改动，而不是凭感觉提交。
一个 commit 只表达一个目的，方便审查和回滚。
PR 必须同时提供变更、验证、风险和恢复方案。
CI 是可重复的质量证据，不是需求判断和发布授权。
合并主干与发布生产分开审批，外部写入动作由人确认。
发布后回到真实用户路径验证，异常时按代码、配置、数据和产物类型回滚。
复盘要产出有负责人和验收标准的机制，并把长期规则放到正确位置。

最终交付不是“代码已经推上去”，而是别人能够回答这几个问题：

这次到底改了什么？
哪些检查真的跑过？
谁批准了合并和发布？
出问题时退回哪个版本？
哪条规则会防止同类问题再次发生？

当这些问题都有记录、证据和负责人时，一次功能开发才真正完成了从代码到交付的闭环。参考资料：参考/codex/34-capstone.md、参考/codex/26-git-github.md、参考/codex/27-automation.md、参考/codex/36-best-practices.md。

​用途

​本页完成标准

​01 先固定这次交付的边界

​先确认仓库位置

​02 提交前清单：先检查，再落锤

​2.1 检查工作区范围

​2.2 阅读完整 diff

​2.3 运行项目验证

​2.4 检查空白和差异边界

​2.5 搜索敏感信息和本地产物

​2.6 形成提交前结论

​03 commit 拆分：让每个提交只有一个理由

​3.1 先查看已有暂存状态

​3.2 用交互暂存拆分内容

​3.3 提交实现

​3.4 提交前后检查历史

​3.5 什么时候可以合并 commit

​04 推送功能分支并创建 PR

​4.1 PR 描述应当回答什么

​4.2 PR 自查

​4.3 处理审查意见

​05 CI：把可重复检查交给流水线

​5.1 最小测试 workflow

​5.2 观察 CI 结果

​5.3 CI 通过不等于可以发布

​5.4 自动化的边界

​06 合并和发布审批：两个不同的放行点

​6.1 合并前审批清单

​6.2 创建发布候选版本

​6.3 发布记录必须包含的内容

​07 外部发布红线

​08 发布后的验证：从用户路径开始

​09 回滚：先判断类型，再选择动作

​9.1 未提交的工作区错误

​9.2 已合并代码的修复

​9.3 已发布版本的回退

​9.4 配置、数据和依赖问题

​9.5 回滚后的确认

​10 完整交付记录模板

​10.1 示例交付记录

​11 复盘：从一次发布变成下一次规则

​11.1 四段式复盘

​11.2 五个为什么的使用边界

​11.3 行动项写成可验收任务

​12 规则沉淀：把复盘结论放到正确位置

​13 最终验收表

​小结

用途

本页完成标准

01 先固定这次交付的边界

先确认仓库位置

02 提交前清单：先检查，再落锤

2.1 检查工作区范围

2.2 阅读完整 diff

2.3 运行项目验证

2.4 检查空白和差异边界

2.5 搜索敏感信息和本地产物

2.6 形成提交前结论

03 commit 拆分：让每个提交只有一个理由

3.1 先查看已有暂存状态

3.2 用交互暂存拆分内容

3.3 提交实现

3.4 提交前后检查历史

3.5 什么时候可以合并 commit

04 推送功能分支并创建 PR

4.1 PR 描述应当回答什么

4.2 PR 自查

4.3 处理审查意见

05 CI：把可重复检查交给流水线

5.1 最小测试 workflow

5.2 观察 CI 结果

5.3 CI 通过不等于可以发布

5.4 自动化的边界

06 合并和发布审批：两个不同的放行点

6.1 合并前审批清单

6.2 创建发布候选版本

6.3 发布记录必须包含的内容

07 外部发布红线

08 发布后的验证：从用户路径开始

09 回滚：先判断类型，再选择动作

9.1 未提交的工作区错误

9.2 已合并代码的修复

9.3 已发布版本的回退

9.4 配置、数据和依赖问题

9.5 回滚后的确认

10 完整交付记录模板

10.1 示例交付记录

11 复盘：从一次发布变成下一次规则

11.1 四段式复盘

11.2 五个为什么的使用边界

11.3 行动项写成可验收任务

12 规则沉淀：把复盘结论放到正确位置

13 最终验收表

小结