Contextual Commits 实战指南用结构化 Action Lines 在 Git 提交中保留代码背后的 WHY【免费下载链接】repomix Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.项目地址: https://gitcode.com/GitHub_Trending/rep/repomix导读Contextual Commits 是 Repomix 项目内置的一门 Agent 技能Skill用于在提交代码时生成携带上下文的提交信息除了标准的 Conventional Commits 主题行之外还在提交正文中追加一系列带类型action-type与范围scope的动作行action lines把代码变更背后为什么这么写的意图、决策、约束与经验沉淀进版本历史。读完本文你将掌握 action lines 的完整语法、五种动作类型的适用场景、提交前的分析流程以及在缺少对话上下文时如何避免编造事实——让每一个 commit 都成为后续会话与协作者可直接消费的推理档案。一、Contextual Commits 要解决的问题标准提交信息只记录了 WHAT——改动的内容而这恰恰也是git diff能展示的。真正会丢失的是 WHY用户到底要求了什么实现时考虑过哪些备选方案哪些约束塑造了最终实现过程中学到了什么经验。这些推理上下文在会话结束后就会蒸发。Contextual Commits 的作用就是阻止这种丢失把 diff 本身无法体现的开发推理写进提交正文让未来读到这段提交的 Agent 或人类协作者而不是你能够立刻理解变更背后的完整决策链路。在 Repomix 仓库中这一约定已被固化为核心开发规范根目录 CLAUDE.md 与 .agents/rules/base.md 的 Commit Messages 一节明确要求——主题行遵循 Conventional Commitstype(scope): Description如feat(cli): Add new --no-progress flag提交正文遵循contextual-commit技能而 skills-lock.json 记录了该技能的锁定版本与来源berserkdisruptors/contextual-commits。也就是说任何人人类或 Agent在 Repomix 上提交代码都被期望输出这种带上下文的提交信息。二、提交格式总览Contextual Commits 的整体结构非常简单主题行是标准的 Conventional Commit正文是若干条 action lines。type(scope): subject line (standard conventional commit) action-type(scope): description of reasoning or context action-type(scope): another entry主题行Subject Line主题行严格遵循 Conventional Commits不做任何改变feat(auth): implement Google OAuth providerfix(payments): handle currency rounding edge caserefactor(notifications): extract digest scheduling logicAction Lines动作行正文中每一行遵循action-type(scope): description格式。其中action-type动作类型必须是后文列出的五种之一intent/decision/rejected/constraint/learnedscope人类可读的概念标签——领域、模块或关注点例如auth、payment-flow、oauth-library、session-store、api-contracts。使用项目自身的词汇体系并且同一概念在不同提交中要保持 scope 一致第一次用auth下次就不要写成authentication。需要强调action lines 不是填充模板的装饰品。多数提交只需要 13 条永远不要为了凑数而添加噪音行。三、五种 Action Types 详解1.intent(scope): ...—— 记录用户意图记录用户想达成什么、为什么。这一类型强调的是用户本人的声音而不是你对实现的转述。intent(auth): social login starting with Google, then GitHub and Apple intent(notifications): users want batch notifications instead of per-event emails intent(payment-flow): must support EUR and GBP alongside USD for enterprise clients适用时机大部分功能开发、有明确目的的重构以及任何从主题行看不出动机的变更。2.decision(scope): ...—— 记录方案选择记录存在备选方案时选择了哪种做法并给出简短理由。decision(oauth-library): passport.js over auth0-sdk for multi-provider flexibility decision(digest-schedule): weekly on Monday 9am, not daily — matches user research decision(currency-handling): per-transaction currency over account-level default适用时机当你确实评估过多个选项时。如果选择显而易见、根本没有真正的备选方案跳过这一类型。3.rejected(scope): ...—— 记录被否决的方案最高价值记录考虑过但明确放弃的方案以及放弃的原因。文档中明确指出这是价值最高的动作类型——它防止未来的会话可能是完全失忆的新 Agent再次提出同样的方案重复踩坑。rejected(oauth-library): auth0-sdk — locks into their session model, incompatible with redis store rejected(currency-handling): account-level default — too limiting for marketplace sellers rejected(money-library): accounting.js — lacks support for sub-unit (cents) arithmetic适用时机每一次你或用户认真考虑过一个有意义的备选方案并决定不采用时。必须始终附带理由——没有理由的 rejection 毫无价值下一个 Agent 只会把它重新提出来。4.constraint(scope): ...—— 记录硬性限制记录实现过程中发现的、塑造了实现方式的硬性限制、依赖或边界条件。constraint(callback-routes): must follow /api/auth/callback/:provider pattern per existing convention constraint(stripe-integration): currency required at PaymentIntent creation, cannot change after constraint(session-store): redis 24h TTL means tokens must refresh within that window适用时机当存在不那么显而易见的限制影响了实现时——也就是下一个在这里工作的人必须知道的事情。5.learned(scope): ...—— 记录实现中获得的经验记录实现过程中发现、能在未来会话中节省时间的东西API 怪癖、未文档化的行为、性能特征。learned(passport-google): requires explicit offline_access scope for refresh tokens, undocumented in quickstart learned(stripe-multicurrency): presentment currency and settlement currency are different concepts learned(exchange-rates): Stripe handles conversion — do NOT store our own rates适用时机要是我早知道就好了的时刻——库的坑、API 的意外行为、非显而易见的特性。四、写提交之前确定 scope 并判断上下文动手写 action lines 之前按以下流程分析提交范围先检查已暂存staged的变更——运行git diff --cached --stat。如果存在已暂存变更这些就是本次提交的范围。不要考虑未暂存或未跟踪的文件——用户通过暂存操作已经表达了这个提交该包含什么。如果没有任何暂存内容把未暂存的修改和未跟踪文件都作为候选结合会话上下文和 diff 决定暂存并提交哪些。识别你有会话上下文的变更——本次对话中你亲手产出、讨论过或观察到其推理过程的改动。识别你没有上下文的变更——来自之前会话的文件、其他 Agent 的改动或本对话之外的手动编辑。据此撰写 action lines有上下文的变更基于会话知识写出完整的 action lines没有上下文的变更遵循下文缺乏对话上下文时的规则只写 diff 能证明的内容。关键原则提交信息必须覆盖提交范围内的全部变更而不只是你经手的那部分。忽略你没产出的变更比给它们写几条单薄的动作行更糟糕。五、完整示例从简单修复到架构级变更场景一简单修复——不需要 action linesfix(button): correct alignment on mobile viewportConventional Commit 主题行已经足够不要添加噪音。场景二中等规模功能feat(notifications): add email digest for weekly summaries intent(notifications): users want batch notifications instead of per-event emails decision(digest-schedule): weekly on Monday 9am — matches user research feedback constraint(email-provider): SendGrid batch API limited to 1000 recipients per call场景三复杂架构变更refactor(payments): migrate from single to multi-currency support intent(payments): enterprise customers need EUR and GBP alongside USD intent(payment-architecture): must be backward compatible, existing USD flows unchanged decision(currency-handling): per-transaction currency over account-level default rejected(currency-handling): account-level default too limiting for marketplace sellers rejected(money-library): accounting.js — lacks sub-unit arithmetic, using currency.js instead constraint(stripe-integration): Stripe requires currency at PaymentIntent creation, cannot change after constraint(database-migration): existing amount columns need companion currency columns, not replacement learned(stripe-multicurrency): presentment currency vs settlement currency are different Stripe concepts learned(exchange-rates): Stripe handles conversion, we should NOT store our own rates注意这个示例的编排逻辑先记录用户意图两条 intent再记录选型decision随后把被否决的方案与原因固化下来两条 rejected接着是外部系统与数据库的硬约束两条 constraint最后是两条来自实现现场的经验learned。五类动作行各有各的信息载荷互相不重复。场景四中途转向Mid-implementation Pivot当需求在实现中途发生改变时把转向记录在转向发生的那个提交上refactor(auth): switch from session-based to JWT tokens intent(auth): original session approach incompatible with redis cluster setup rejected(auth-sessions): redis cluster doesnt support session stickiness needed by passport sessions decision(auth-tokens): JWT with short expiry refresh token pattern learned(redis-cluster): session affinity requires sticky sessions at load balancer level — too invasive这个例子展示了转向本身如何成为有价值的历史记录未来的会话能看到为什么放弃 session 方案的完整推理而不是面对一段孤立的、无法解释的技术路线切换。六、当缺少对话上下文时绝不编造有时候暂存区里的变更并非本次会话的产物——可能是之前会话的输出、其他 Agent 的改动、粘贴的代码、外部生成的文件或手动编辑。对于任何你缺乏推理线索的变更只为你能在 diff 中清楚看到证据的变更写 action lines。不要推测你无法观察到的意图或约束。仅凭 diff 就能推断的内容decision(scope)—— diff 中存在清晰的技术选择新增了依赖、采用了某种模式、切换了库。例如decision(http-client): switched from axios to native fetch从 diff 中可以直接看到。仅凭 diff 无法推断、严禁虚构的内容intent(scope)—— 变更原因不在 diff 里。不要复述 diff 已经展示的东西rejected(scope)—— 没被选择的东西在已提交的内容里是看不见的constraint(scope)—— 硬性限制几乎不会显式出现在代码变更中learned(scope)—— 经验来自过程而不是产出物。文档给出的底线非常明确一个干净的、不带任何 action lines 的 Conventional Commit 主题行永远好过编造的上下文。宁可少写不可瞎写。七、与标准 Git 工作流的兼容性Contextual Commits 与所有标准 Git 工作流天然兼容无需特殊处理常规合并Regular merges提交正文原样保留Squash 合并所有提交正文拼接进 squash 提交的正文最终形成一条按时间排列的、带类型与范围的 action lines 序列——Agent 可以毫无障碍地解析、过滤、分组这些行Rebase 与 cherry-pick提交正文同样完整保留。这意味着这套格式既能适应单人开发的小仓库也能适应重度使用 squash merge 的团队协作流程推理信息在合并过程中不会丢失。八、九条硬性规则主题行必须是 Conventional Commit——绝不破坏现有提交约定或相关工具链。Action lines 只进正文——绝不放进主题行。只写携带信息的 action lines——如果 diff 已经解释了就不要重复如果既没有决策、也没有否决、也没有新发现就不写。简洁但完整——每条 action line 是一句清晰的陈述没有人为的长度限制但也不要写成小作文。项目内 scope 保持一致——auth就是auth别下次写成authentication。intent 行要复述用户的原话——反映人类真正要求的内容而不是你的实现摘要。rejected 行必须解释原因——没有原因的否决毫无价值下一个 Agent 只会把它重新提出。琐碎提交不要发明 action lines——错字修复、依赖升级、格式调整Conventional Commit 主题行就足够了。不要编造你没有的上下文——如果你没有参与那段推理就不要假装参与过见缺乏对话上下文时一节。九、在 Repomix 仓库中如何落地如果你是 Agent 或开发者在 Repomix 仓库提交代码时这套流程已经无缝接入仓库的提交规范由根目录 CLAUDE.md与 .agents/rules/base.md 同源统一声明主题行遵循type(scope): Description正文遵循 contextual-commit 技能预置的 Git 命令技能 .agents/commands/git/git-commit.md 与 .agents/commands/git/git-commit-push.md 会直接要求按 CLAUDE.md 的规则生成提交信息即提交时自动进入写主题行 按需写 action lines的流程技能的来源与版本通过 skills-lock.json 锁定保证所有协作者使用同一份规则不会因技能更新而漂移。十、结语Contextual Commits 的核心哲学可以浓缩为一句话提交信息是代码的持久记忆而不仅仅是变更的收据。通过intent、decision、rejected、constraint、learned五种带类型与范围的动作行配合 Conventional Commits 主题行每一次提交都变成可检索、可解析、可引用的决策档案。对于以 AI 辅助开发为主、会话切换频繁的现代工作流而言这套格式让下一个会话和下一个协作者无需重新推导就能站在前人的推理之上——这恰恰也是 Repomix 这类以 LLM 协作为核心的项目把该技能写入根目录规范的原因。【免费下载链接】repomix Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.项目地址: https://gitcode.com/GitHub_Trending/rep/repomix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考