需求生命周期与 Git 协作说明

本文面向开发同事和 AI，说明一个需求如何从提出、设计、开发、测试走到稳定分支。详细 Gate 规则以同目录的 SKILL.md 和仓库生命周期流程为准。

核心原则

master 是稳定基线，禁止直接提交。
一个需求使用一个 feature_id 和一个共享 feature 分支。
需求和设计先进入 master，通过开发 Gate 后再拉 feature 分支。
已推送的共享 feature 分支只允许 merge，不允许 rebase 或 force-push。
feature 分支通过测试和评审后，以 merge commit 合入 master。
团队不强制普通提交格式、提交粒度或个人任务分支。

完整生命周期

flowchart TD
    A["提出需求并分配 feature_id"] --> B["docs/FEAT-... 编写需求、设计、测试与开发计划"]
    B --> C{"文档评审通过?"}
    C -->|否| B
    C -->|是| D["通过 PR 合入 master"]
    D --> E{"ready_for_development Gate"}
    E -->|未通过| B
    E -->|通过| F["从已记录的 origin/master SHA 创建 feature/FEAT-..."]
    F --> G["团队在共享 feature 分支开发"]
    G --> H["合入最新 origin/master 并执行测试"]
    H --> I{"ready_for_merge Gate"}
    I -->|未通过| G
    I -->|通过| J["feature PR 以 merge commit 合入 master"]
    J --> K["docs/FEAT-...-closeout 记录合并 SHA 与最终结论"]
    K --> L["需求完成并删除远程 feature 分支"]

分支关系

gitGraph
    commit id: "稳定 master"
    branch docs/FEAT
    checkout docs/FEAT
    commit id: "需求与设计"
    commit id: "测试与开发计划"
    checkout main
    merge docs/FEAT id: "文档评审通过"
    branch feature/FEAT
    checkout feature/FEAT
    commit id: "开发提交 A"
    commit id: "开发提交 B"
    checkout main
    commit id: "其他稳定变更"
    checkout feature/FEAT
    merge main id: "同步 master"
    commit id: "测试结果"
    checkout main
    merge feature/FEAT id: "需求合并"
    branch docs/FEAT-closeout
    checkout docs/FEAT-closeout
    commit id: "收尾记录"
    checkout main
    merge docs/FEAT-closeout id: "生命周期完成"

图中的 main 表示本仓库实际使用的 master。部分 Mermaid 渲染器将主线固定显示为 main，不影响真实分支名称。

分支命名

用途	名称
需求和设计文档	`docs/FEAT-YYYYMM-NNN-short-name`
共享开发	`feature/FEAT-YYYYMM-NNN-short-name`
合并后收尾	`docs/FEAT-YYYYMM-NNN-short-name-closeout`
生产紧急修复	`hotfix/<short-name>`
跨需求临时联调	`integration/<feature-a>-<feature-b>`

开始开发

开发负责人确认 ready_for_development Gate 通过后，记录准确的 origin/master 基线 SHA，再创建共享分支：

git fetch origin
git switch master
git pull --ff-only origin master
git switch -c feature/FEAT-YYYYMM-NNN-short-name
git push -u origin feature/FEAT-YYYYMM-NNN-short-name

创建分支和 push 必须获得明确授权。不要从尚未同步的本地 master 创建需求分支。

日常开发

首次拉取共享分支：

git fetch origin
git switch --track origin/feature/FEAT-YYYYMM-NNN-short-name

已有本地分支时，在开始工作和 push 前同步团队提交：

git switch feature/FEAT-YYYYMM-NNN-short-name
git pull --no-rebase origin feature/FEAT-YYYYMM-NNN-short-name

完成一个可工作的改动后正常提交和推送：

git add <本次相关文件>
git commit -m "简要说明本次改动"
git push origin feature/FEAT-YYYYMM-NNN-short-name

普通提交信息不要求固定前缀。不要使用 git push --force，也不要对已共享的 feature 分支执行 rebase。

同步 master

最终评审前必须把最新稳定代码合入 feature 分支：

git fetch origin
git switch feature/FEAT-YYYYMM-NNN-short-name
git merge origin/master

解决冲突后重新执行改动模块的编译、测试和适用的架构测试。同步完成后再 push feature 分支并发起 feature/FEAT-... -> master PR。

两个硬 Gate

进入开发 `ready_for_development`

需求录入和 PRD 已批准，验收标准与非目标明确。
必需的概要设计、详细设计、ADR、接口和安全文档已批准。
测试计划已批准，开发计划可执行。
没有阻塞性待确认项。
已确认 origin/master 并记录基线 SHA。

合入稳定分支 `ready_for_merge`

已合入最新 origin/master，不存在未解决冲突。
需求、设计、实现和接口契约一致。
测试结果已记录，规定的编译、测试和架构检查通过。
没有阻塞缺陷、安全问题或接口差异。
feature 到 master 的 PR 已通过人工评审。

特殊情况

需求暂停：专题状态改为 paused，保留 feature 分支；恢复时重新同步 master 并检查 Gate。
需求取消：专题状态改为 cancelled，未完成代码不得合入 master。
需求实质变化：暂停相关实现，更新需求或设计并重新过 Gate；独立范围建立新的 feature_id。
跨需求依赖：feature 分支不得互相合并。依赖需求先合入 master；确需并行联调时使用一次性 integration 分支，该分支不能直接合入 master。
生产紧急修复：使用 hotfix/<short-name>，至少记录故障、修复范围和验证结果，仍通过 PR 合入 master，事后补齐需求记录。

AI 执行边界

AI 可以自动检查文档、分支、工作区、远程同步状态和 Gate，也可以给出推荐命令。创建分支、提交、push、创建或合并 PR、删除远程分支前，必须获得用户明确授权。

开发协作说明.md 5.7 KB História Raw