ECC Git 工作流规则解析：Conventional Commits 提交规范、Co-Authored-By 归因控制与 PR 实战流程-创锋一号

ECC Git 工作流规则解析：Conventional Commits 提交规范、Co-Authored-By 归因控制与 PR 实战流程

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC

本文以 ECC（The agent harness performance optimization system）仓库中的 common-git-workflow.md 规则文件为核心，完整解析其定义的 Conventional Commits 提交格式、8 种提交类型、Claude 提交归因（Co-Authored-By）的默认关闭机制，以及五步 PR 工作流程。读完本文，你可以直接照搬这套规范约束团队或 AI Agent 的 Git 操作，并理解 ECC 安装器是如何在源码层面保证"不覆盖用户显式选择"的。

规则文件的定位与生效机制

该规则位于 ECC 的 Cursor 规则层.cursor/rules/目录，其 YAML frontmatter 为：

--- description: "Git workflow: conventional commits, PR process" alwaysApply: true ---

两个关键点决定了它的行为：

alwaysApply: true：该规则不是按需触发的，而是对 Cursor 会话中所有任务始终生效，因此它适合作为提交信息格式和 PR 流程这类"全局硬约束"。
通用（common）前缀：文件名common-git-workflow.md表明它属于 ECC 规则的通用层。按照 rules/README.md 的分层设计，rules/common/存放与语言无关的通用原则（该规则的内容源文件即 rules/common/git-workflow.md），而rules/typescript/、rules/golang/等语言目录可覆盖其中与语言习惯冲突的默认值，冲突时"特定优先于通用"。.cursor/rules/下的common-git-workflow.md与rules/common/git-workflow.md内容基本一致，只是尾部引用链接的相对路径不同（前者指向 Cursor 规则体系内的 development workflow 规则，后者指向 development-workflow.md）。

安装方式上，ECC 官方文档给出的通用做法是保留目录结构整体拷贝（切勿用cp -r rules/common/*打平，同名文件会互相覆盖）：

# 用户级 Claude 安装（ECC 命名空间） mkdir -p ~/.claude/rules/ecc cp -r rules/common ~/.claude/rules/ecc/ # 项目级安装 mkdir -p .claude/rules/ecc cp -r rules/common .claude/rules/ecc/

也可以直接使用安装脚本./install.sh typescript（自动处理 common 层与语言层）。

Commit Message 格式：类型、结构与校验边界

规则给出的提交信息格式为：

<type>: <description> <optional body>

允许的 8 种类型为：feat, fix, refactor, docs, test, chore, perf, ci。

这 8 种类型覆盖了日常开发的绝大多数场景：feat表示新功能，fix表示缺陷修复，refactor表示不改变外部行为的结构调整，docs/test/chore/perf/ci分别对应文档、测试、杂务、性能优化与 CI 变更。可选的 body 用于补充"为什么改"而不仅是"改了什么"。

与仓库实际 commitlint 配置的对照

该规则并非孤立存在——仓库自身用 commitlint.config.js 对提交信息做了机器校验，值得对照阅读：

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] } };

可以读出三个与规则文件互补的约束细节：

类型白名单更宽：commitlint 的type-enum在规则的 8 种之外还允许style、build、revert三种（severity 为 2 即 error 级别，违反则 CI 失败）。
subject 大小写约束：subject-case规则禁止 sentence-case、start-case、pascal-case、upper-case 四种写法，即 subject 应以小写命令式开头（如fix login redirect loop而非Fix login redirect loop）。
header 长度上限 100 字符：首行（type + subject）不得超过 100 字符，超长内容应放入 body。

如果你希望在自己的项目里复用这套校验，ECC 的 git-workflow skill 还给出了配套的提交模板方案：在仓库根目录创建.gitmessage文件并执行git config commit.template .gitmessage，把类型列表和书写要求固化成编辑器里的提示注释。该 skill 同时给出了正反例对比：

# BAD: 含糊、无上下文 git commit -m "fixed stuff" # GOOD: 清晰、具体、解释原因 git commit -m "fix(api): retry requests on 503 Service Unavailable The external API occasionally returns 503 errors during peak hours. Added exponential backoff retry logic with max 3 attempts. Closes #123"

Co-Authored-By 归因控制：默认关闭且绝不覆盖用户选择

规则中有一段专门说明 AI 提交归因的约定：

ECC-managed installs set"includeCoAuthoredBy": falsein~/.claude/settings.json, so commits carry noCo-Authored-Bytrailer by default. To keep Claude attribution, set"includeCoAuthoredBy": trueor configureattribution; ECC never overwrites an explicit choice.

含义是：在 ECC 托管的安装流程中，ECC 会向~/.claude/settings.json写入"includeCoAuthoredBy": false，使 Claude Code 产生的提交默认不附带Co-Authored-By尾注。若你希望保留 Claude 归因，可显式设置"includeCoAuthoredBy": true或改用attribution配置；ECC 承诺永远不会覆盖用户的显式选择。

这段约定的实现逻辑在 scripts/lib/claude-commit-attribution.js 中，源码注释把设计决策讲得非常清楚：

两个配置键的关系：attribution: { commit, pr }是当前生效的配置且优先级更高；includeCoAuthoredBy自 Claude Code 2.1.x 起已弃用但仍被兼容，并且是旧版本唯一能识别的键。
为什么写的是弃用键：ECC 选择写入includeCoAuthoredBy而非attribution，因为未知键会导致 settings 校验失败——如果对旧版 Claude Code 写入attribution，会直接弄坏用户的设置文件。
显式意图判定：hasExplicitCommitAttributionPreference()检查两个键——只要includeCoAuthoredBy是布尔值，或attribution对象中定义了commit/pr任一字段，即视为用户的刻意选择。
只填空、不覆盖：withCommitAttributionDisabled()只在用户没有显式偏好时追加[COAUTHOR_SETTING_KEY]: false，否则原样返回：

function withCommitAttributionDisabled(settings) { if (hasExplicitCommitAttributionPreference(settings)) { return settings; } return { ...settings, [COAUTHOR_SETTING_KEY]: false, }; }

这一"默认关闭 + 尊重显式选择"的策略，本质是避免工具链替用户做不可逆的决定：归因信息一旦写进 git 历史就无法干净移除。相关行为在 tests/lib/claude-commit-attribution.test.js 中有测试覆盖。

Pull Request 工作流程：五步清单及其命令化实现

规则对创建 PR 给出五步操作清单：

分析完整提交历史（not just latest commit）——PR 描述应基于整个分支相对 base 的全部变更，而不是最后一次 commit；
用git diff [base-branch]...HEAD查看所有变更——注意这里是三点语法base...HEAD，表示从两分支的共同祖先到 HEAD 的差异，正是 PR 语义下"本分支引入了什么"的准确表达；
起草全面的 PR 摘要；
附上带 TODO 的测试计划——明确测试了什么、还欠哪些验证；
新分支首次推送使用-u标志——git push -u origin <branch>建立上游跟踪，后续git push无需再带远端名。

这五步在 ECC 的 commands/pr.md（即/pr命令）中被展开为一条六阶段流水线，是规则在 Agent 场景下的完整落地：

Phase 1 VALIDATE：用git branch --show-current、git status --short、git log origin/<base>..HEAD --oneline做前置检查（不在 base 分支、工作区不干净、无领先提交、已存在 PR，任一命中即中止并给出明确提示）；
Phase 2 DISCOVER：按.github/PULL_REQUEST_TEMPLATE/→.github/PULL_REQUEST_TEMPLATE.md→.github/pull_request_template.md→docs/pull_request_template.md的顺序探测 PR 模板；用git log origin/<base>..HEAD --format="%h %s" --reverse分析提交序列决定 PR 标题（多类型时取主导类型，标题沿用 conventional commit 前缀）；用git diff origin/<base>..HEAD --stat和--name-only将变更文件归类为 source/tests/docs/config/migrations；
Phase 3 PUSH：执行git push -u origin HEAD；若远端分叉则git fetch origin && git rebase origin/<base>后重推，rebase 冲突则停止并告知用户；
Phase 4 CREATE：有模板则填充模板（不删除任何小节，不适用处写 "N/A"）；无模板则使用内置格式（Summary / Changes / Files Changed / Testing / Related Issues 五节）；最终经gh pr create --title ... --base ... --body ...创建；
Phase 5 VERIFY：gh pr view --json number,url,title,state,...与gh pr checks回读校验；
Phase 6 OUTPUT：按固定格式回报 PR 编号、URL、分支方向、增删行数、CI 状态与后续操作。

几个值得注意的工程细节：

强推只允许--force-with-lease：/pr命令的 Edge Cases 明确写了"rebase 后需要 force push 时使用git push --force-with-lease，never--force"，避免覆盖他人的新提交；
大 PR 预警：变更超过 20 个文件时命令会主动建议拆分，与 git-workflow skill 中"PR 理想规模小于 500 行、聚焦单一功能"的反模式清单一致；
环境依赖：/pr依赖 GitHub CLI，未安装或未gh auth login时会停止并给出提示。

与 Development Workflow 规则的前置衔接

规则文件尾部的引用块指向"git 操作之前的完整开发流程"：

For the full development process (planning, TDD, code review) before git operations, see the development workflow rule.

对应的 common-development-workflow.md 将 git 提交定义为开发管线的最后一步，完整管线为：

Plan First：先用 planner agent 产出实现计划，识别依赖与风险，拆分为阶段；
TDD Approach：tdd-guide agent 主导，先写失败测试（RED）→ 实现至通过（GREEN）→ 重构（IMPROVE），并验证 80%+ 覆盖率；
Code Review：写完代码立即用 code-reviewer agent 审查，必须处理 CRITICAL/HIGH 问题，尽量修复 MEDIUM；
Commit & Push：写详细的提交信息、遵循 conventional commits 格式，"详见 git workflow 规则"——即本文所讲的这条规则。

也就是说，common-git-workflow管的是"提交和 PR 应该长什么样"，common-development-workflow管的是"提交之前应该发生什么"，两条alwaysApply: true的规则共同约束 Agent 的完整交付行为。

实战速查表

事项	规则要求 / 命令
提交格式	`<type>: <description>`+ 可选 body
允许类型	feat, fix, refactor, docs, test, chore, perf, ci（commitlint 另放行 style/build/revert）
subject 写法	小写命令式，禁止 sentence/start/pascal/upper-case，首行 ≤ 100 字符
AI 归因	默认无`Co-Authored-By`；需要则设`"includeCoAuthoredBy": true`或`attribution`
查看 PR 全量变更	`git diff [base-branch]...HEAD`
首次推送新分支	`git push -u origin <branch>`
分叉后同步	`git fetch origin && git rebase origin/<base>`，冲突则停下人工处理
需要强推时	只用`git push --force-with-lease`
提交历史参考	`git log origin/<base>..HEAD --format="%h %s" --reverse`

适用前提说明：归因相关的~/.claude/settings.json约定仅作用于 ECC 托管安装的 Claude Code 用户（且includeCoAuthoredBy在 Claude Code 2.1.x 之后属于弃用但兼容的键）；commitlint 校验配置（commitlint.config.js）约束的是 ECC 仓库自身的提交，而规则文件中 8 种类型是面向用户项目的建议集合。如果你要把这套规则移植到其他项目，建议同时引入 commitlint 配置，把"建议"升级为 CI 中的硬校验。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析