ECC Git 工作流规范：Conventional Commits 提交约定与高质量 Pull Request 实战指南

导读

本文面向在 ECC（Efficient Claude/Codex 等 Harness 的编排系统） 仓库内开展协作开发的工程师与 AI Agent，系统讲解由 steering 指南 .kiro/steering/git-workflow.md 确立的 Git 协作纪律：<type>: <description> 的 Conventional Commits 提交格式、Claude Code 提交归属（Co-Authored-By）的默认行为与覆写规则，以及"先读全量提交历史 → 用三段式 diff 审查 → 写完整 PR 摘要与测试计划"的五步 Pull Request 流程。读完本文，你将能够按照与仓库实际 lint 规则（commitlint.config.js）和源码实现（scripts/lib/claude-commit-attribution.js）完全一致的约定，产出可被 CI 直接校验的提交与可被评审者快速合入的 PR。

一、Steering 指南的定位：一份贯穿全仓的 Git 协作基线

.kiro/steering/git-workflow.md 属于仓库中 steering（舵向）类规则：它以少量 frontmatter 元数据声明自身身份，正文则是所有 ECC 开发者与 AI 代理在触碰 Git 操作前必须遵守的基线规范。

从文件头可以看到三个字段：

---
inclusion: auto
name: git-workflow
description: Git workflow guidelines for conventional commits and pull request process
---

• name: git-workflow 是规则的稳定标识，供各类 harness（Claude Code、Codex、OpenCode 等）的规则加载机制按名引用；
• description 用一句话概括本规则管辖范围——提交信息格式与 Pull Request 流程；
• inclusion: auto 表明该指南属于可被工具自动纳入上下文的规则，而不依赖人工手动粘贴。

这份指南并非孤立文件。它在仓库规则树中存在同源的完整版本 rules/common/git-workflow.md，并且已被同步到多语言文档树（例如 docs/zh-CN/rules/common/git-workflow.md）。这意味着：你在 .kiro、rules 或任意本地化文档目录中看到的 Git 工作流条款，语义都是一致的，遵守任意一处即可与全仓纪律对齐。

补充阅读：steering 指南在结尾明确提示"完整的开发流程（规划、TDD、代码评审）发生在 git 操作之前，详见开发工作流规则"，对应文件为 rules/common/development-workflow.md。本文第 5 节会把它与 Git 操作衔接起来。

二、提交信息格式：<type>: <description> 的精确语义

2.1 语法骨架与允许的 type

指南给出的提交信息骨架为：

<type>: <description>

<optional body>

即一条提交由**单行头（subject）和可选正文（body）**组成，type 与 description 之间以冒号加空格分隔。指南明确允许的 type 为：

feat, fix, refactor, docs, test, chore, perf, ci

这 8 个 type 是协作基线中最常使用的子集。仓库根目录的 commitlint.config.js 给出了更完整的合法集合，它继承 @commitlint/config-conventional 并对 type-enum 施加如下约束：

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', [
      'feat', 'fix', 'docs', 'style', 'refactor',
      'perf', 'test', 'chore', 'ci', 'build', 'revert'
    ]],
    'subject-case': [2, 'never', ['sentence-case', 'start-case', 'pascal-case', 'upper-case']],
    'header-max-length': [2, 'always', 100]
  }
};

两相对照可以得到一张实用的 type 语义表：

Type	适用场景	仓库落地示例
feat	新增用户可见功能	新增某个命令、skill 或模块入口
fix	修复缺陷	修复 hook 未按预期触发的问题
refactor	不改变行为的结构调整	提取公共 lib 函数
docs	仅文档变更	更新规则/文档翻译
test	增加或修改测试	为 lib 模块补充单测
chore	杂务、依赖、构建相关非功能性变更	更新 package.json 依赖
perf	性能优化	减少重复文件扫描
ci	CI 配置与脚本	修改 tests/ci 下校验脚本

style、build、revert 在仓库 lint 中同样被放行，但 steering 指南刻意收敛到前 8 个高频 type，避免团队口径发散。

2.2 三条硬性边界（来自 commitlint 约束）

commitlint.config.js 还编码了三条机器可校验的规则，任何进入 CI 的提交头都应满足：

1. type 必须是上表枚举之一——乱写 update、improve 会被直接判为错误（severity 为 2，即 error 级别）；
2. subject 禁止使用句子式/首字母大写式大小写——即不能写成 Fix bug（sentence-case）、Fix Bug（start-case）、FixBug（pascal-case）或全大写；标准写法是纯小写开头的祈使短语，如 fix unicode check false positive；
3. header 总长不超过 100 字符——保证提交信息在各种终端与 git log 渲染下都能完整阅读。

这也解释了为什么指南里 refactor、perf、ci 这类在 Conventional Commits 生态中通常可选的 type，在此处被列为必须掌握的基础项——因为该仓库的 CI 管线（见 package.json 中 npm test 串联的 validate-* 系列校验）对提交纪律有完整的自动化守护。

2.3 何时使用正文（optional body）

当单行头不足以说明"为什么改"时，在空行后补充正文。推荐的正文结构：

feat: add per-harness git hook install for codex

Codex does not read the same settings path as Claude Code, so hooks
must be installed at the git global level when bootstrapping a codex
workspace.

Test plan:
- run install-apply on a fresh codex workspace
- verify `git config --global core.hooksPath` points at the managed hooks dir

正文应解释动机与影响，而非复述 diff；涉及多步验证时，把可执行的测试步骤放在正文中，正好衔接 PR 的 test plan 要求。

三、提交归属：includeCoAuthoredBy 与 Co-Authored-By Trailer 的默认关闭

这是 steering 指南中一段极易被忽略、但源码实现最重的细节。指南原文指出：

ECC-managed installs set "includeCoAuthoredBy": false in ~/.claude/settings.json, so commits carry no Co-Authored-By trailer by default. To keep Claude attribution, set "includeCoAuthoredBy": true or configure attribution; ECC never overwrites an explicit choice.

背景事实（来自 scripts/lib/claude-commit-attribution.js 的文件头注释）：Claude Code 默认会在 commit 与 PR 上追加 Co-Authored-By trailer，除非用户显式关闭。为了不让 ECC 托管安装被动改变用户提交的元数据，ECC 在托管安装时默认把该开关写为 false。

3.1 两个配置键的优先级

同一个文件中说明了两个设置键的协作关系：

• attribution: { commit, pr }：Claude Code 2.1.x 之后当前生效的配置项，设置后优先生效；
• includeCoAuthoredBy：旧版键，已被标记为 deprecated 但仍被旧版本识别。

ECC 之所以在托管安装中写旧的 includeCoAuthoredBy 键而不是新键，是因为"未知键会导致 settings 校验失败"——直接写入 attribution 会让旧版 Claude Code 用户无法通过配置校验。无论哪一键出现，都被视为用户的显式选择，ECC 一律不得覆盖。

3.2 源码如何判定"用户显式选择"

scripts/lib/claude-commit-attribution.js 的核心判定函数 hasExplicitCommitAttributionPreference 逻辑如下（源码第 14–27 行）：

function hasExplicitCommitAttributionPreference(settings) {
  if (!settings || typeof settings !== 'object') {
    return false;
  }
  if (typeof settings[COAUTHOR_SETTING_KEY] === 'boolean') {
    return true;
  }
  const attribution = settings.attribution;
  return Boolean(attribution)
    && typeof attribution === 'object'
    && !Array.isArray(attribution)
    && (attribution.commit !== undefined || attribution.pr !== undefined);
}

可以概括为三条判定：

1. settings 为空或非对象 → 未配置（返回 false，允许 ECC 写入默认值）；
2. includeCoAuthoredBy 出现且为布尔值 → 显式选择，无论 true/false 都不再覆盖；
3. attribution 存在且包含 commit 或 pr 任一字段 → 显式选择；只有纯空对象、数组、字符串或只含 sessionUrl 等无关字段时，才视为未配置。

而写默认值的 withCommitAttributionDisabled 只有在"用户未显式表态"时才向 settings 中注入 includeCoAuthoredBy: false，其余场景原样返回（源码第 29–37 行）。

3.3 测试用例如何验证"不覆盖显式选择"

该实现由专门的单测覆盖：tests/lib/claude-commit-attribution.test.js。其中值得注意的断言包括：

• { includeCoAuthoredBy: true } 与 { includeCoAuthoredBy: false } 都被判为显式选择；
• 自定义 attribution: { commit: 'Co-Authored-By: Someone <a@b.c>' } 同样被尊重；
• 只有 attribution: {}、attribution: null、attribution: []、attribution: 'off' 这类不含 commit/pr 键的值才不被当作显式选择；
• 注入默认值时保留无关设置，例如 { theme: 'dark' } 会被写成 { theme: 'dark', includeCoAuthoredBy: false }，而不是覆盖整个文件。

与此配合，tests/scripts/install-apply.test.js 验证了安装链路的行为（如第 838 行断言"Claude co-author attribution should be disabled by default"），并专门有名为 reinstall preserves an explicit includeCoAuthoredBy opt-in 的用例，确认用户一旦显式设为 true，重复安装也不会把它改回去；scripts/lib/claude-scope-migration.js 的迁移逻辑中同样写入 includeCoAuthoredBy: false 作为托管默认值。

对你（开发者/Agent）的实际含义：如果你希望保留 Claude Code 生成的 Co-Authored-By 归属信息，只需在 ~/.claude/settings.json 中显式写 "includeCoAuthoredBy": true，或在 attribution 下显式配置 commit/pr；ECC 的安装与修复流程（例如 npm run test 触发的 install-apply 校验）会识别并尊重这一选择，绝不回写。

四、Pull Request 工作流：五步产出可评审的变更

指南的 PR 环节给出了硬性的五步流程。下面逐条结合仓库实践展开，并提供可直接执行的关键命令。

4.1 分析完整提交历史（而非只看最新一条）

git log --oneline origin/<base-branch>..HEAD

PR 评审关注的是这组变更的完整脉络：每个 commit 的 type 是否与改动吻合、信息是否自洽、是否有遗留的临时提交。只盯着最后一次提交会漏掉中途引入又回滚的噪音。

4.2 用三段式 diff 检查全部变更

git diff <base-branch>...HEAD

注意这里必须是三个点（...）：A...B 计算的是 A 与 A、B 的共同祖先之间的差异，只包含本分支真正引入的改动；若误写成两个点（A..B），会把 A 上领先的提交也卷进 diff，造成误导。提交 PR 前，用 git diff --stat <base-branch>...HEAD 先看变更规模，再对逐文件 diff 做自查。

4.3 撰写完整 PR 摘要

摘要应当做到"评审者不看代码也能理解改动意图"，至少覆盖：

• 动机：这个 PR 解决什么问题，关联哪个功能或缺陷；
• 变更范围：涉及哪些模块（给出仓库相对路径），核心改动点是什么；
• 行为影响：是否改变配置默认值、是否需要迁移、对存量用户是否向后兼容。

仓库同时维护有 PR 模板（发布包 files 列表中包含 .github/PULL_REQUEST_TEMPLATE.md，见 package.json），可直接在创建 PR 时作为骨架填充。

4.4 内置带 TODO 的测试计划（test plan with TODOs）

在 PR 描述中列出人工或 Agent 可执行的验证步骤，并显式标注尚未完成项。一个合格的 test plan 形如：

Test plan:
- [ ] npm install && npm test 通过（CI 全绿）
- [ ] 在全新 workspace 上运行 install-apply，验证 settings 注入 includeCoAuthoredBy:false
- [x] 已有 includeCoAuthoredBy:true 的用户重装后设置保持 true
- [ ] 人工冒烟：创建一次带 co-author 的提交，确认 trailer 正常

把未验证项写成 checkbox TODO，比笼统写 "tested" 更能让评审者判断风险边界。

4.5 新分支首推使用 -u

git push -u origin feature/my-change

-u（即 --set-upstream）会把本地分支与远端分支建立追踪关系，之后可直接用 git push/git pull，并让 PR 的提交历史能被 git diff <base>...HEAD 正确解析——这正是第 4.2 步三段式 diff 的前提。

五、与上游开发流程的衔接：Git 只是最后一公里

steering 指南末尾的引用块提醒：Git 操作之前，还存在完整的开发工作流。对应的 rules/common/development-workflow.md 定义了一个典型的 research-first 流水线：

0. Research & Reuse（强制前置）：先用 gh search repos / gh search code 寻找可复用实现，再查库文档确认 API，最后才用通用搜索补盲，并优先复用成熟的第三方库；
1. Plan First：调用 planner（对应 agents/planner.md）产出 PRD、架构、设计、任务拆解；
2. TDD：依据 agents/tdd-guide.md 走 RED → GREEN → IMPROVE，并把覆盖率维持在 80% 以上；
3. Code Review：写完代码立即交给 code-reviewer（agents/code-reviewer.md），至少修掉 CRITICAL 与 HIGH 级问题；
4. Commit & Push：进入本指南管辖的 Git 阶段——遵循 Conventional Commits 格式、写详细提交信息；
5. Pre-Review Checks：确认 CI 全绿、无合并冲突、分支已与目标分支同步后，再发起评审。

仓库在 package.json 的 test 脚本中串联了完整的自动校验（unicode 安全检查、agents/commands/rules/skills/hooks/install-manifests 的格式校验、catalog 一致性检查等），所以"CI 通过"对 ECC 仓库意味着远超单元测试的全方位一致性校验。PR 提交前先跑一遍：

npm install
npm test

再处理任何标红的校验项，是最稳妥的做法。

六、实战自查清单

把本指南浓缩成一份可逐项打勾的清单，适用于每次提交与每个 PR：

提交前（Commit）

• [ ] header 形如 <type>: <description>，type 属于 feat/fix/refactor/docs/test/chore/perf/ci
• [ ] description 小写开头、祈使句、总长 ≤ 100 字符
• [ ] 需要说明动机时补充空行 + body
• [ ] 归属元数据符合预期：默认无 Co-Authored-By；如需归属，已在 ~/.claude/settings.json 显式开启且未被覆盖

PR 前（Pull Request）

• [ ] git log <base>...HEAD 确认提交脉络完整、无噪音提交
• [ ] git diff <base>...HEAD（三段式）审阅全部实际变更
• [ ] PR 摘要含动机、范围、行为影响
• [ ] test plan 含可执行步骤与 TODO checkbox
• [ ] 新分支已用 git push -u 建立追踪
• [ ] CI 全绿、无冲突、分支已同步目标分支后再请求评审

结语

ECC 的 Git 工作流并不复杂，它的价值在于把提交纪律沉淀为可自动校验、可跨语言树同步、可被 Agent 稳定执行的规则：header 的 type/大小写/长度由 commitlint.config.js 守护，提交归属的默认值与"不覆盖用户显式选择"原则由 scripts/lib/claude-commit-attribution.js 及配套测试保障，PR 的五步流程则与 development-workflow 中的 research → plan → TDD → review 阶段首尾相接。对任何在 ECC 上做二次开发、贡献 skill/rule/脚本，或接入其安装链路的开发者而言，遵循本文所整理的约定，就等于让每一次 git 操作都自动通过仓库自身的全部规则校验。