docs 分支并入主分支——终止本地隔离约定，恢复正常 git 跟踪 #149

Merged

Yushu merged 1 commit from migrate/docs-into-main into main

2026-08-17 10:17:40 +00:00

KumaAgent commented

2026-08-17 10:12:32 +00:00

Member

背景

docs 分支自建立以来一直独立于 main：main 此前完全没有 docs/、CONTEXT.md、CLAUDE.md 任一文件，采用"本地提交、永不推送"的隔离约定。

排查发现这套约定的根因：实现侧的工作环境是与本仓库完全独立、从未建立过同步路径的另一个 clone——docs 分支"永不推送"意味着两边永远不会 fetch/pull 到对方，导致实现侧在自己那边逐票正确提交的 ADR 更新节，从共享仓库这边看始终不存在（此前评估侧误判为"共享工作树并发切换导致丢提交"，先后记为四起独立事件——issue #112/#133/#137/#101，实际是两个物理隔离的仓库从未有过连接，一次性解释了全部四起）。

应用户要求终止这套隔离约定，改为文档与代码同样纳入 main 的正常 PR 流程。

内容

取自实现侧那边 docs 分支的真实最新状态（commit aa9529f，经 git bundle 传输后核实为共享仓库 refs/heads/docs（1b61cf1）的干净线性后继，完整覆盖 issue #101/#112/#115-117/#123-127/#133-138/#144 等此前误判为"丢失"的全部更新节）。

按路径整体迁入，不改动任何 src//tests/ 文件——docs 分支这些路径下的代码文件自分叉后从未随主线代码演进（如 config.py 停留在 14 行的远古版本），与当前 main 无关，不参与本次迁移。

Test plan

确认改动只涉及 docs/**、CONTEXT.md、CLAUDE.md，未触及 src//tests/
确认 aa9529f 是共享仓库 refs/heads/docs（1b61cf1）的干净线性后继，非分叉历史
合并后建议废弃本地的 docs 分支隔离约定，后续 ADR/CONTEXT/design.md 更新走正常 feature branch + PR

🤖 Generated with Claude Code

## 背景 `docs` 分支自建立以来一直独立于 `main`：main 此前完全没有 `docs/`、`CONTEXT.md`、`CLAUDE.md` 任一文件，采用"本地提交、永不推送"的隔离约定。排查发现这套约定的根因：实现侧的工作环境是与本仓库完全独立、从未建立过同步路径的另一个 clone——`docs` 分支"永不推送"意味着两边永远不会 fetch/pull 到对方，导致实现侧在自己那边逐票正确提交的 ADR 更新节，从共享仓库这边看始终不存在（此前评估侧误判为"共享工作树并发切换导致丢提交"，先后记为四起独立事件——issue #112/#133/#137/#101，实际是两个物理隔离的仓库从未有过连接，一次性解释了全部四起）。应用户要求终止这套隔离约定，改为文档与代码同样纳入 `main` 的正常 PR 流程。 ## 内容取自实现侧那边 `docs` 分支的真实最新状态（commit `aa9529f`，经 git bundle 传输后核实为共享仓库 `refs/heads/docs`（`1b61cf1`）的干净线性后继，完整覆盖 issue #101/#112/#115-117/#123-127/#133-138/#144 等此前误判为"丢失"的全部更新节）。按路径整体迁入，**不改动任何 `src/`/`tests/` 文件**——`docs` 分支这些路径下的代码文件自分叉后从未随主线代码演进（如 `config.py` 停留在 14 行的远古版本），与当前 `main` 无关，不参与本次迁移。 ## Test plan - [x] 确认改动只涉及 `docs/**`、`CONTEXT.md`、`CLAUDE.md`，未触及 `src/`/`tests/` - [x] 确认 `aa9529f` 是共享仓库 `refs/heads/docs`（`1b61cf1`）的干净线性后继，非分叉历史 - [ ] 合并后建议废弃本地的 `docs` 分支隔离约定，后续 ADR/CONTEXT/design.md 更新走正常 feature branch + PR 🤖 Generated with [Claude Code](https://claude.com/claude-code)

KumaAgent added 1 commit

2026-08-17 10:12:32 +00:00

docs: 合并 docs 分支的全部文档到主分支，恢复正常 git 跟踪 f4f24eec6a

docs 分支自建立以来一直独立于 main（分叉点早于绝大部分 src/ 代码，
main 此前完全没有 docs/、CONTEXT.md、CLAUDE.md 任一文件），采用
"本地提交、永不推送"的隔离约定。

排查发现这套约定的根因比预想的更简单：实现侧的工作环境是与本仓库
完全独立、从未建立过同步路径的另一个 clone——docs 分支"永不推送"
意味着两边永远不会 fetch/pull 到对方，导致实现侧在自己那边逐票正确
提交的 ADR 更新节，从这边看始终不存在（此前误判为"共享工作树并发
切换导致丢提交"，实际是两个物理隔离的仓库从未有过连接）。应用户
要求终止这套隔离约定，改为文档与代码同样纳入主分支的正常 PR 流程。

内容取自实现侧那边 docs 分支的真实最新状态（commit aa9529f，经由
git bundle 传输后核实为 refs/heads/docs@1b61cf1 的干净线性后继，
完整覆盖 issue #101/#112/#115-117/#123-127/#133-138/#144 等全部
此前误判为"丢失"的更新节），按路径整体迁入主分支，不改动任何
src/tests 文件——docs 分支这些路径自分叉后从未随代码演进，其内容
与当前 main 无关，不参与本次迁移。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>