git

Imported from aascer39/codeagent (.agents/skills/git/SKILL.md). Install upstream with npx skills add aascer39/codeagent --skill git. Copyright stays with the author.

Git 变更与提交协议

适用范围与边界

本 Skill 只负责本仓库的 Git 状态、差异、暂存范围、Commit Message、验证记录和 Issue/阶段归档。它不规定 Java 语言（见 java/SKILL.md）、Spring 装配（见 spring/SKILL.md）、数据库（见 database/SKILL.md）、Redis（见 redis/SKILL.md）、配置与密钥（见 configuration/SKILL.md）、日志（见 logging/SKILL.md）或前端实现（见 frontend-design/SKILL.md）。

本 Skill 约束的是开发本仓库的人与 AI；codeagent 运行时 Agent 不得例行调用 Git 工具（Issue-07），只有用户显式要求时才执行 Git 操作。除非用户明确要求，不自动推送远端、改写历史、删除分支或覆盖他人修改。提交是归档动作，不是完成任务的替代品。

1. 目的

统一 CodeAgent 项目的 Git 使用和提交规范：如何查看工作区状态、分析代码变更、创建 Commit、选择前缀、编写 Commit Message、记录实现内容与人工修正、记录验证结果、避免提交无关文件、保持 Commit 历史清晰，并在任务完成后形成可追溯的变更记录。

核心目标：每一个 Commit 都能清晰说明「为什么改、改了什么、人工修正了什么、如何验证」，并且只包含与当前任务相关的变更。

2. 核心原则

2.1 提交必须具有明确目的

每一次 Commit 必须对应一个明确的代码变更目的。禁止 update、修改、test、aaa、fix bug、change、临时提交 这类无意义 Message；Message 必须让其他开发者不查看 Diff 也能大致理解本次提交做了什么。

2.2 提交必须经过验证

固定流程：修改 → 检查 Diff → 验证 → 确认无误 → Commit。禁止修改后未经验证直接 Commit。验证方式按变更风险选择（见 §10），至少执行与本次修改直接相关的验证。

2.3 Commit 只包含当前任务相关修改

提交前必须检查 git status --short，并检查 git diff，必要时检查 git diff --cached。不得提交 IDE 配置、临时文件、日志、缓存、构建产物、本地环境配置、.env、临时测试文件，以及与当前任务无关的代码修改。

3. Commit 前缀规范

项目统一采用 Conventional Commits 风格，基本格式 <type>: <简述>；本仓库进一步要求带阶段号或 Issue（完整格式见 §6.1）。类型取值见 §4，选择规则见 §5。

feat: V1-03 implement shell command execution tool
fix: Issue-03 CLI 输出编码
docs: update git skill

4. Commit Type

4.1 feat

新增功能：新模块、新 API、新 Tool、新 Agent 能力、新业务流程。feat: add shell execution tool

4.2 fix

修复 Bug 或错误行为：异常处理错误、错误逻辑、边界条件错误、配置读取错误、API 调用错误。fix: prevent null pointer in tool execution

4.3 refactor

重构代码但不改变外部功能行为：类拆分、方法提取、重命名、消除重复代码、调整内部结构。refactor: extract process execution logic

若重构同时修复了 Bug，优先使用 fix:。

4.4 test

新增或修改测试代码。test: cover command timeout scenario

若本次主要目的是修复 Bug，即使同时增加了测试也优先使用 fix:，新增的测试记录在 Message 正文。

4.5 docs

只修改文档：README.md、TARGET.md、TASKS.md、SKILL.md、docs/、JavaDoc。docs: update configuration skill

文档修改是功能开发的一部分时，按主要目的选择其他类型。

4.6 chore

不属于业务功能、Bug 修复、重构、测试、文档的维护性修改：依赖升级、构建配置、Git 配置、CI 配置、开发工具配置、项目维护。chore: update Maven dependencies

4.7 perf

性能优化。perf: reduce repeated tool metadata lookup

若主要目的是修复性能 Bug，也可以使用 fix:，但必须保持整个项目一致。

4.8 style

不改变程序逻辑的代码格式调整：格式化、空格、换行、import 排序、代码风格调整。style: format tool implementation

禁止把实际逻辑修改伪装成 style:。

5. Type 选择规则

按主要目的选择 Commit Type，优先顺序：功能新增 → feat；Bug 修复 → fix；内部重构 → refactor；测试 → test；文档 → docs；性能优化 → perf；格式调整 → style；项目维护 → chore。

新增功能 + 测试

使用 feat: add shell command execution，而不是 test: add shell command execution tests，因为主要变更是新增功能。

修复 Bug + 增加测试

使用 fix: prevent unauthorized command execution，而不是 test: add authorization tests。

6. Commit Message 规则

6.1 基本格式

<type>: <阶段号或 Issue> <简述>

What changed: <改了什么>
Why: <为什么这么改>
Human Corrections: <实际人工修正；没有则写 None>
Verification: <实际执行的命令与结果>

6.2 description 必须描述做了什么

禁止 fix: bug，应写 fix: prevent command timeout from blocking agent execution；禁止 feat: update，应写 feat: add command execution permission validation。描述必须让读者知道对象与行为。

6.3 使用动词描述变更

推荐 add / fix / remove / update / refactor / extract / prevent / support / implement / improve。例如 feat: add command permission validation。

6.4 不要描述没有发生的事情

Commit Message 必须与实际 Git Diff 一致。禁止声称实现了 HITL 审批而实际只修改了 README.md。

7. Commit Body 规则

简单修改可以只写一行 Message，不强制 Body。涉及复杂逻辑、Bug 修复、Agent 行为、配置变化或人工修正时，必须写 Body（What changed / Why / Human Corrections / Verification，见 §6.1），逐条说明改动点与原因，不能只留一行标题。

8. 人工修正记录

AI 完成代码后可能经过「人工检查 → 人工修正 → 再次验证 → Commit」。人工修正影响最终代码时，修正内容必须写入 Commit Message Body 的 Human Corrections 段，不得只提交最终代码而丢失人工修正信息。

8.1 人工修正格式

在 Body 中逐条列出实际发生的人工修正，每条写清「改了什么、为什么」（记录原则见 §9），完整 Message 模板见 §24。

8.2 如果没有人工修正

写作 Human Corrections: None，不得凭空编造或含糊带过。按 §25 使用单行 Message 的极简改动可以不写 Body，视为没有人工修正流程。

9. Human Corrections 的记录原则

人工修正必须可追溯，描述「改了什么 + 为什么」：

- changed command timeout from 30s to 60s because long-running commands are expected
- replaced manual LoggerFactory with @Slf4j
- moved configuration to environment variables

禁止只写 fixed some things 或 manually changed code。

10. 验证记录

复杂 Commit 必须记录实际执行的验证命令与结果，验证方式按变更风险选择：

验证失败但已解决时，记录失败原因与最终通过结果；未解决的写明阻塞命令与原因，不得改写成「通过」。静态推断不能写成「验证通过」。

10.1 验证必须基于实际执行

禁止伪造：如果实际上没有执行验证命令，就不得写入 Verification: <该命令>。只记录真实运行过的命令、观察到的结果，以及未执行的项及原因。

11. Commit 前检查流程

按顺序执行，不跳步：

1. 一次跑完范围审查：git status --short; git diff --stat; git diff --cached --stat; git log -5 --oneline。
2. 查看限定路径的 git diff -- <paths>，确认修改内容与范围。
3. 确认没有无关文件、敏感信息、构建产物、临时代码。
4. 执行与本次修改相关的验证并记录结果。
5. 再次检查 status / diff，确定 Commit Type，编写 Commit Message。
6. git add -- <paths>，再 git diff --cached 确认暂存内容与预期一致。
7. git commit。
8. 提交后 git status --short 确认工作区干净，并报告 commit id 与文件范围。

12. Git Status 检查

提交前必须执行 git status --short，确认 M（修改）/ A（新增）/ D（删除）分别是什么。重点检查 .env、.idea/、*.log、target/、node_modules/、临时文件是否错误进入提交范围。

13. Git Diff 检查

提交前必须查看 git diff -- <paths>（限定路径，避免全量 diff 输出被截断），并执行 git diff --check。确认：修改内容符合当前任务、没有误删代码、没有调试代码、没有临时日志、没有敏感信息、没有无关修改、没有意外格式化整个文件。

14. Staged Diff 检查

执行 git add -- <paths> 之后必须再次执行 git diff --cached，确认真正准备提交的内容与预期一致。禁止 git add . 后完全不检查就 git commit。

15. 不允许提交敏感信息

以下内容禁止进入 Git：.env、API Key、Secret Key、Password、Access Token、JWT Secret、数据库密码、Redis 密码、OAuth Secret、MCP Token。若 .env 已被 Git 跟踪，先用 git ls-files .env 确认，再按实际情况处理（移出跟踪并轮换密钥）。密钥命名、存放与 .env.example 规则见 configuration/SKILL.md。

16. 不允许提交构建产物

禁止提交 target/、build/、out/、node_modules/、*.class、*.log、.env 以及前端构建产物（frontend/dist 等），除非项目明确要求。构建产物由构建命令重新生成。

17. 单次 Commit 的修改范围

一个 Commit 应保持单一职责：fix: V1-03 resolve shell timeout handling 只包含 ShellTool、ProcessRunner 及相关测试，不应同时包含 README、数据库结构、前端页面、IDE 配置。只暂存当前已完成阶段（任务项或 Issue）范围内的文件；互不相关的改动拆分 Commit。

18. 不要为了 Commit 修改代码

禁止为了让 Commit 看起来「干净」而重排整个项目格式、批量修改变量名、修改无关 JavaDoc、调整无关日志或重排无关代码。Commit 的目标是记录实际完成的工作，而不是制造一个漂亮的 Diff。

19. Commit 与任务关系

一个任务完成后应形成：TASK → 代码修改 → 验证 → Commit。Commit Message 必须对应当前任务，例如 TASKS.md 的 V1-03 ShellTool 对应 feat: V1-03 implement shell command execution tool。

仓库特有的提交资格与 Issue 轮转：

• 阶段只有在 Acceptance Criteria 已满足且对应验证实际通过后才具备提交资格；未完成或验证失败的阶段保留工作区改动并说明原因，不得伪装成已完成阶段提交。
• 只有与当前阶段存在直接依赖关系的 issues/open/ Issue 才阻止提交；无关的 open Issue 不阻止已完成阶段的提交，必须单独创建 Issue / 任务项，不得为凑整塞入当前提交。
• Issue 状态轮转：OPEN 表示未解决，FIXED 表示代码已修复，VERIFIED 表示修复已验证，CLOSED 表示已确认解决并归档；Issue 状态与提交状态相互独立，不能仅因创建或关闭 Issue 就决定是否提交，提交资格由阶段完成状态、验证结果和阻塞 Issue 决定。
• 阶段完成后可继续后续工作，下一次会话统一归档，不要求在完成瞬间提交；没有已完成且已验证的范围时不产生空提交，工作区干净则跳过提交。

20. AI 开发 + 人工修正流程

流程：AI 生成代码 → 人工 Review → 人工修改 → AI/开发者再次验证 → Commit。最终 Commit 的 Body 必须同时保留三部分信息：AI 做了什么（What changed）、人改了什么（Human Corrections）、最终如何验证（Verification）；无人工修正时按 §8.2 写 None，不得省略。

21. AI 不得覆盖人工修改

发现工作区存在未提交修改时，先用 git status --short 判断这些修改属于当前任务还是人工修改。不得执行 git reset --hard，不得执行 git checkout .，不得执行 git restore .，不得覆盖、删除或回滚未知来源的工作区修改。

22. 已有人工修改的处理

发现工作区存在人工修改时必须：检查 git diff → 判断修改内容 → 保留人工修改 → 当前任务需要时基于人工修改继续工作 → 最终把人工修正内容记录到 Commit Message。禁止「发现人工修改 → 直接覆盖」。

23. Commit 前必须重新验证

人工修正代码后，之前 AI 做的验证不能直接视为最终验证：必须重新验证 → 通过 → 才可 Commit。例如 AI 修改后 mvn test 通过、人工修改后必须再跑一次并通过。

24. Commit Message 推荐模板

复杂任务推荐使用完整 Body：

fix: V7-02 prevent unauthorized shell command execution

What changed: 命令按权限策略校验，拒绝 allowlist 外前缀，返回权限失败
Why: 未校验命令可绕过审批执行
Human Corrections: 前缀匹配改为规范化命令匹配；补充错误日志
Verification: mvnw.cmd -o -B test（340 用例通过）

25. 简单任务可以使用简化格式

对于非常小的修改（例如只改一个文档文件）可以只写一行 Message，不强制添加 Body：

docs: update git skill

但只要任务涉及复杂逻辑、Bug 修复、Agent 行为、配置变化或人工修正，必须使用 §24 的完整 Body。

26. Commit 禁止事项

以下行为属于 MUST NOT：

• MUST NOT 1：模糊 Commit Message（update、fix、change、test、modify、aaa）。
• MUST NOT 2：提交未经验证的代码（见 §10、§10.1）。
• MUST NOT 3：提交敏感信息（见 §15）。
• MUST NOT 4：提交与当前任务无关的修改（见 §17）。
• MUST NOT 5：覆盖人工修改（见 §21）。
• MUST NOT 6：伪造 Verification（见 §10.1）。
• MUST NOT 7：隐瞒人工修正 —— 影响最终代码的修正必须记录在 Human Corrections（见 §8）。
• MUST NOT 8：为了 Commit 而进行无关代码重构（见 §18）。
• MUST NOT 9：使用 git reset --hard 删除未知来源的工作区修改。

27. Commit 前 Checklist

提交前必须逐项确认，全文件唯一一份清单：

[ ] 阶段完成，Acceptance Criteria 满足，验证实际通过
[ ] git status --short、限定路径 git diff、git diff --cached 已检查
[ ] 修改属于当前任务；无无关文件、敏感信息、构建产物、临时代码
[ ] Commit Type 正确，Message 描述实际改动、不含未发生的事
[ ] 已实际执行验证并记录结果，无伪造
[ ] 人工修正已识别并记录（无则 None）
[ ] 提交后工作区干净，已报告 commit id 与文件范围

28. 强制规则总结

以下规则属于 MUST，具体定义见对应章节：

• MUST 1：使用正确的 Type（feat / fix / refactor / test / docs / perf / style / chore）—— §4、§5。
• MUST 2：Commit Message 描述实际完成的工作 —— §6.2、§6.4。
• MUST 3：提交前检查 git status --short 与 git diff —— §12、§13。
• MUST 4：提交前执行与任务相关的验证 —— §10。
• MUST 5：验证必须基于实际执行，不得伪造 —— §10.1。
• MUST 6：人工修正最终代码后必须重新验证 —— §23。
• MUST 7：人工修正影响最终代码时必须记录 Human Corrections 并随提交归档 —— §8。
• MUST 8：Commit 不得包含与当前任务无关的修改 —— §17。
• MUST 9：不得提交敏感信息 —— §15。
• MUST 10：提交前检查 git diff --cached，确认实际提交内容 —— §14。

29. AI 最终检查模板

AI 完成任务并准备提交时，使用 §27 的 Checklist（不另立等价清单），并在交付说明中回答三个问题：

1. 这次改了什么？
2. 人工修正了什么？
3. 最终有没有验证通过？