用 pre-commit hook 自动修复 AI 编程代理生成的代码格式问题

这次我们聊的场景很具体：团队开始用 AI coding agent 写代码之后，PR 里最吵的不是业务逻辑，而是格式问题。标题里的“代理”指的是 AI Coding Agent，也就是 AI 编程代理工具。这类工具生成的代码经常能跑通，但风格五花八门：有的文件是双引号，有的文件是单引号；有的函数后面空三行，有的文件结尾没有换行；团队里只要有两个以上的人在用不同型号的 AI 工具，代码库的格式一定会乱。最后这些格式化工作被压到 code review 环节，reviewer 被迫在“讨论逻辑”和“改引号”之间来回切换。

解决思路其实早就存在：在 Git 提交之前放一个 pre-commit hook，让代码在进入仓库前先被自动修复。本篇文章会完整演示这套流程，包括环境准备、hook 配置、提交验证、全库批量修复、CI 集成和常见问题排查。这套方案不需要 GPU、不增加推理成本，本质上只是在本地多装一个 Python 工具，然后让 Git 在 commit 前多跑一段自动化检查。下面的内容不挑 IDE、不挑语言，只要仓库已经用 Git 管理，就能照做。

适合的读者有两类。一类是个人开发者，自己用 AI coding 工具写代码，想让格式化这件事彻底自动化；另一类是技术负责人，团队里有多个 AI coding agent 在产出代码，需要一个统一的、可落地的格式检查层。看完这篇，你可以在自己的仓库里复现完整流程，也能把同一份配置推广到整个团队。

1. 核心能力速览

先把这套方案的关键能力列出来，方便判断它适不适合你的仓库。

从这张表能看出两个重点：第一，这套方案不挑显卡，也不增加任何推理成本；第二，它解决问题的位置是“代码进 Git 之前”，而不是“代码生成之后”。AI 代理可以继续生成杂乱代码，但只要它走 Git 提交，pre-commit 就会把格式问题挡在仓库外面。这个设计的好处是：不需要给每个 AI 工具单独做提示词训练，不需要约束团队用同一个模型，只要统一提交前这一条路。

为什么选择 pre-commit 而不是直接给 AI 工具写“请格式化后再输出”的提示词？因为提示词不保证生效。不同工具、不同模型、不同上下文轮次下，输出风格都会漂移。pre-commit 是在 Git 层面强制执行，规则明确、结果可复现，而且可以批量修复历史存量，这是单纯依赖提示词做不到的。

2. AI Coding 场景下为什么会有格式问题

AI coding agent 的核心优势是快速生成大量代码。真正进入工程化阶段后，问题也随之而来：它一次可能生成几十个文件，跨越多个语言和目录；不同会话之间的代码风格不会保持稳定，甚至同一个模型在上下文变长之后，输出风格也会逐渐漂移。这不是模型能力问题，而是概率生成的自然结果——只要有上下文窗口，前面写过的代码风格就会影响后面，而不同任务、不同输入素材会带来不同的“风格记忆”。于是代码库出现格式混乱是必然的。

具体表现通常是这些：

• 引号风格不统一，同一份代码里单引号、双引号混合。
• 缩进混乱，尤其是 Python 项目里混合了 Tab 和空格。
• 文件末尾缺少换行，或者出现多余空行。
• import 顺序没有排序。
• 行尾有多余空格。
• Markdown、YAML、JSON 等配置文件的格式不统一。
• 一行代码过长，超过团队约定的长度限制。

这类问题单独看不致命，但叠加在 AI 高频迭代的场景里就会产生持续噪音。每次 AI 代理改完代码，PR diff 里都混入大量格式变更，reviewer 需要花额外时间判断“这行是逻辑改动还是格式改动”。时间一长，团队会形成两个坏结果：一是 review 质量下降，格式噪音掩盖了真正的逻辑变更；二是对 AI 生成的代码产生惯性放行，反正格式乱也没人管了。

pre-commit 的定位就是把这些机械的格式问题从 review 环节挪到提交前，用自动化直接处理掉。它不负责判断业务逻辑对不对，也不负责检查架构合不合理，它只解决“机械、可重复、有明确规则”的那部分问题。这个边界很重要，后面很多配置决策都基于这条边界。格式检查属于计算机能稳定判断的问题，适合交给 hook；代码是否满足业务需求、是否引入安全隐患，则需要人工 review 和专门的自动化测试来保证。

使用边界也要同步说清楚。pre-commit hook 不替代 code review，不替代单测，更不替代架构设计。它只负责在最低成本处拦截低级问题。AI 生成代码如果涉及敏感数据、越权访问、未授权素材，这些问题不会被 pre-commit 拦住，必须靠安全意识、权限审查和合规流程解决。后面配置敏感信息扫描 hook 的时候会再展开。

3. 环境准备与前置条件

在开始配置之前，先确认本机环境满足条件。这套方案要求不高，但每一项都跟后续排错有关。

3.1 基础环境清单

• Git：仓库必须使用 Git 管理，因为 pre-commit 本质上是向.git/hooks目录注入一个钩子脚本。
• Python：安装 pre-commit 需要 Python 3.8 以上版本，建议 3.10 及以上。
• pip：用来安装 Python 包，通常随 Python 一起安装。
• Node.js：如果你配置 Prettier、ESLint、Markdownlint 等前端 hook，需要 Node.js 环境。
• Ruby：部分旧式 hook 工具（如某些 Markdown 工具）可能需要 Ruby，但现代配置一般用 Node 或 Python 就够了。

用下面的命令快速确认环境：

git --version python --version pip --version node --version

如果命令行返回了版本号，说明基础环境可用。没有 Node.js 也不影响先跑通 Python hook，可以根据实际项目再补装。

3.2 仓库初始化

如果项目还没有初始化 Git 仓库，先执行：

git init

如果已经是 Git 仓库，确认当前分支、暂存区状态正常：

git status

这一步很重要。pre-commit 安装后只对“后续的提交”生效，历史提交不会被自动重写。想要修复历史代码，需要后面单独跑全量扫描。

3.3 关于 hook 仓库下载的说明

pre-commit 安装 hook 时，会根据.pre-commit-config.yaml中声明的仓库地址去拉取 hook 代码。如果你的机器能正常访问这些代码托管源，安装会很顺利。企业内网环境如果无法直接访问，可以配置镜像源，或者把 hook 仓库缓存到内网自建服务。遇到下载失败时，先检查网络连通性和镜像配置，再检查拼写和版本号，不要无脑重试。

3.4 IDE 设置建议

如果你在用 VS Code、PyCharm 等 IDE，有一个建议：先关掉编辑器保存时自动格式化，或者把自动格式化规则和 pre-commit 规则对齐。否则会出现一种情况：pre-commit 刚把文件格式修好，编辑器保存时又按自己的规则改回去，两边反复打架。这是工程里最常见的格式冲突来源之一。

4. 安装部署与启动方式

整个部署过程分为三步：安装 pre-commit、编写.pre-commit-config.yaml、执行pre-commit install把 hook 挂到当前仓库。

4.1 安装 pre-commit

命令行执行：

pip install pre-commit

安装完成后验证版本：

pre-commit --version

正常情况下会输出类似pre-commit 3.x.x的信息。如果你在团队内统一管理依赖，也可以把pre-commit写进requirements-dev.txt或项目依赖文件里。

4.2 编写 .pre-commit-config.yaml

在仓库根目录创建.pre-commit-config.yaml。这是一个通用配置示例，覆盖了最常见的格式问题：

repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.6.0 hooks: - id: trailing-whitespace - id: end-of-file-fixer - id: check-yaml - id: check-json - id: check-added-large-files - id: check-merge-conflict - repo: https://github.com/psf/black rev: 24.4.2 hooks: - id: black - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.4.9 hooks: - id: ruff args: [--fix] - id: ruff-format - repo: https://github.com/pre-commit/mirrors-prettier rev: v3.1.0 hooks: - id: prettier types_or: [javascript, jsx, ts, tsx, json, yaml, markdown]

这个配置里每个 repo 的作用：

• pre-commit-hooks是官方基础 hook 集合，负责尾随空格、文件结尾换行、合并冲突标记、大文件检查等通用问题。
• black是 Python 代码格式化器，自动把 Python 代码格式化为统一风格。
• ruff是 Python 静态检查工具，配合--fix参数可以自动修复可修复的问题；ruff-format是独立格式化器，和 black 二选一即可，团队按习惯选择。
• prettier是前端格式化器，覆盖 JS、TS、JSON、YAML、Markdown。

注意版本号rev可以理解为“hook 仓库的 tag”，实际使用时以对应仓库的 release 为准。版本锁定很重要，团队所有成员用同一份配置、同一批版本，格式化结果才会一致。这边给出的是示例版本，你可以按需升级。

4.3 安装 hook 到当前仓库

执行：

pre-commit install

安装成功后，.git/hooks/pre-commit会被创建。从这时开始，每次执行git commit，Git 都会先调用 pre-commit 运行配置里的检查项。

4.4 手动运行一次全量检查

首次安装后建议先全量跑一遍，而不是直接 commit：

pre-commit run --all-files

这条命令会扫描仓库全部文件，而不是只检查本次暂存的文件。好处有两个：一是确认配置本身没问题，二是提前发现历史存量问题。第一次运行会下载 hook 仓库，耗时较长，属于正常现象。后续运行会走本地缓存，速度明显提升。

5. 功能测试与效果验证

配置完成以后，用一个实际提交来验证效果。这里设计一个小实验，手动制造格式问题，再观察 pre-commit 是否自动修复。

5.1 制造一个坏格式样例

在仓库里新建一个 Python 文件，故意写成不规范格式：

def add(a,b): result=a+b return result

再新建一个 JSON 文件，故意多加一个逗号：

{ "name": "ai-coding", "version": "1.0", }

这两个文件包含了尾随空格、多余空行、多余逗号的典型问题。

5.2 观察提交过程

将文件加入暂存区并提交：

git add . git commit -m "test: pre-commit demo"

因为已经执行过pre-commit install，提交时 git 会自动触发 pre-commit。预期输出中可以看到类似这样的信息：

• trailing-whitespace检查到行尾空格并自动修复。
• end-of-file-fixer检查到文件结尾缺少换行并自动追加。
• ruff检查到 Python 文件的缩进和空格问题，输出修改提示。
• check-json检查到 JSON 文件里有多余逗号并报错。

注意一个关键细节：部分 hook 在“发现问题并自动修复”之后，会让本次 commit 失败。这是正确的安全行为，防止未复查的修复结果直接进入仓库。你会看到一个类似下面的流程：

1. pre-commit 运行，修改了文件。
2. commit 被中止。
3. 你需要git add把修改后的文件重新放入暂存区。
4. 再执行一次git commit。

第二次提交时，因为格式已经被修复，检查通常能通过。这就是“修复后重新暂存”的标准流程。

5.3 区分“自动修复”和“只检查不修复”

不是所有 hook 都会自动修。比如check-json检测到非法 JSON 时，如果修复规则无法安全确定，它就会直接报错，不会帮你改。check-merge-conflict检测到冲突标记时同样只报错。这个设计是对的：机器能安全判断的，自动修；不能安全判断的，必须让人来处理。

验证时先看输出里的关键字段：

• 如果显示Passed，说明检查通过。
• 如果显示Failed，说明发现问题。
• 如果显示Fixing，说明 hook 正在自动修复。
• 如果显示Skipped，说明该 hook 因为文件类型不匹配等原因没有运行。

5.4 判断成功的标准

一个完整的验证流程是否成功，可以用下面的标准判断：

• 非规范格式文件被 hook 自动修改或拦截。
• 修改后的文件经过git add后，第二次 commit 顺利通过。
• 仓库中不再出现行尾空格、文件末无换行、JSON 语法错误等低级问题。
• 团队成员拿到同一份配置文件后，本地运行结果一致。

如果 commit 总是失败，也不要急着怀疑配置。先跑pre-commit run --all-files --verbose查看每个 hook 的详细输出，定位是哪个 hook 拦截，再针对处理。

6. 批量修复历史代码与 CI 流水线集成

pre-commit 不只对“新提交”有效，它同样适合批量修复历史代码。对 AI coding 团队来说，这个能力尤其重要，因为历史问题往往比新问题更多。

6.1 全量批量修复存量代码

在接入 pre-commit 之前，仓库里很可能已经积累了大量格式问题。不要手动一个个文件修改，直接跑：

pre-commit run --all-files

这条命令会遍历仓库里的所有文件，把能自动修复的问题全部修掉。执行完以后，先看git diff --stat确认改动范围，再人工抽查几个 diff，确认没有误改，然后提交。如果你的仓库很大，建议先在一个分支上执行，确认没问题再合入主干。对于不能自动修复的问题，比如 JSON 语法错误、合并冲突标记，它会明确报错，不会静默跳过。

6.2 只修复指定文件或指定目录

如果你是局部修改，不需要跑全库，可以指定文件：

pre-commit run --files src/agent/model.py src/agent/prompt.py

也可以指定目录：

pre-commit run --files src/

这种方式适合在 AI 代理生成一组文件之后，只对这一批文件做格式校验，速度比全量扫描快很多。实际使用中，我更推荐把它作为 AI Coding 工作流里的固定步骤：代理生成代码 -> 本地跑git diff检查 -> 执行pre-commit run --all-files-> 人工确认 -> 提交。

6.3 与 AI Coding agent 的协作顺序

AI coding agent 生成代码后，不要让它在“生成时”强行保证格式，而是让它先生成，再由 pre-commit 做统一收口。这样的好处是：

• 对 agent 的工具链没有限制，任何模型、任何提示词策略都可以。
• 格式规则由团队统一维护，不依赖模型的偶然表现。
• 即使 agent 后续换模型、换平台，格式约束依然生效。

如果你希望更省事，可以在项目 README 或开发文档里写清楚流程：所有 AI 生成的代码，先执行pre-commit run --all-files，再提交。也可以把pre-commit run --all-files写进 Makefile 或 npm scripts，降低使用门槛。

6.4 CI 流水线集成

本地 hook 只约束本地提交，如果某位同事用git commit --no-verify跳过检查，或者直接推送了未格式化代码，CI 应该兜底。这里给出 GitHub Actions 的示例配置：

name: pre-commit on: push: pull_request: jobs: pre-commit: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: "3.12" - uses: pre-commit/action@v3.0.0

这个 workflow 会在每次 push 和 pull request 时运行 pre-commit，并检查所有变更文件。如果 hook 发现问题，CI 任务会失败，直到开发者在本地修复并重新推送。

GitLab CI 也可以实现同样的效果，示例：

pre-commit: stage: test image: python:3.12 before_script: - pip install pre-commit script: - pre-commit run --all-files

在 CI 里跑全量还是增量，取决于仓库规模。仓库很大时，全量扫描可能耗时较长，更稳妥的做法是只检查本次 MR 变更的文件；仓库不大时，直接全量扫描更简单，还能顺带发现历史问题。实际配置时可以根据团队节奏调整。

6.5 团队统一配置实践

多人协作时，建议把pre-commit写进项目依赖，把.pre-commit-config.yaml提交到仓库根目录。新成员克隆代码后，只需执行两条命令：

pip install pre-commit pre-commit install

就能和团队完全一致的检查规则。不要用不同人维护不同版本 hook 的方式，否则还是会出现“我本地过了，你本地过不了”的协作问题。

7. 本地资源占用与执行性能观察

预判执行时长，对日常开发体验影响很大。很多开发者的第一个反馈是“为什么我 commit 一下要等这么久”。这通常是首次运行 hook 时的下载耗时，而不是真正检查耗时。

7.1 hook 下载缓存

pre-commit 会把下载的 hook 仓库缓存在本机，默认缓存目录在 Linux/macOS 下通常是~/.cache/pre-commit，Windows 下在%USERPROFILE%\.cache\pre-commit。可以通过环境变量PRE_COMMIT_HOME修改缓存位置。缓存大小取决于 hook 数量，几十 MB 到几百 MB 都属于正常范围，具体以本机实际为准。

查看缓存占用：

du -sh ~/.cache/pre-commit

清空缓存：

pre-commit clean

清理未使用的缓存环境：

pre-commit gc

7.2 首次运行与增量运行

首次运行pre-commit run --all-files时，它要下载并创建 hook 环境，所以比较慢。之后的运行会优先使用缓存，速度明显提升。关键在于：让 pre-commit 只检查“暂存区中变更的文件”，而不是每次全量扫描。提交时默认就会这样做：

git commit -m "feat: xxx"

pre-commit 默认对本次暂存的文件执行检查，所以日常提交很快。只有当你手动执行pre-commit run --all-files时，才会扫描全部文件。

7.3 性能优化建议

如果仓库很大，或者配置了大量 hook，可以在 commit 阶段精简配置，把更重的检查放到 CI 或 pre-push 阶段。例如：

• 本地 commit：只跑轻量格式化 hook。
• CI：跑全量静态检查、安全扫描、类型检查。
• 本地 push 前：跑更完整的检查。

pre-commit 支持pre-push钩子，安装方式类似：

pre-commit install -t pre-push

配置里用stages: [pre-push]指定只在 push 阶段运行的 hook。

8. 常见问题与排查方法

8.1 常见问题速查表

8.2 详细排查说明

hook 不触发：这是新接入 pre-commit 最常见的坑。很多开发者在编写好配置文件后直接git commit，发现没有生效，其实是忘了执行pre-commit install。这个命令只操作当前仓库，换一个仓库需要重新安装。

修复后 commit 仍失败：pre-commit 修改文件之后，Git 暂存区里还是“修改前”的版本。所以必须重新执行：

git add . git commit -m "feat: xxx"

如果不想每次都手动 add，可以先git add再提交，或者在编辑器里查看变更后统一提交。

某个 hook 没有运行：可能是文件类型不匹配。比如black只处理 Python 文件，你改了一个 JS 文件，它自然跳过。可以用--verbose查看每个 hook 的实际执行状态，再判断是配置问题还是文件类型问题。

临时跳过检查的代价：git commit --no-verify可以绕过 hook，但代价是格式问题进入仓库。建议只在紧急修复时使用，并且事后立即补跑：

pre-commit run --all-files

下载慢或下载失败：pre-commit 从远程仓库拉取 hook 代码时受网络环境影响。企业内网建议提前把所有 hook 仓库镜像到内网，或让团队成员统一使用同一个离线缓存包。如果只是偶发失败，重试一次通常就能解决。

9. 最佳实践与使用建议

9.1 从最小配置开始

不要一开始就把所有检查项塞进去。建议先只配置一个pre-commit-hooks基础库，跑通流程，再逐步增加语言格式化器和静态检查工具。先跑通“commit 被拦截、自动修复、重新提交”的循环，再扩展规则，遇到问题时的排查范围会小很多。

9.2 版本锁定必须做

.pre-commit-config.yaml里每个 repo 都要写明确切的rev，不要用master、main这类浮动分支。否则今天同事拉下来的配置和明天拉下来的配置可能跑出不同结果，团队无法复现同一个检查结论。升级 hook 版本时，单独提交一次配置变更，并跑全量扫描验证效果。

9.3 与 AI Coding 的结合顺序

AI coding agent 生成代码后，先执行一次pre-commit run --all-files，再让 agent 继续下一轮迭代。这比在提示词里反复强调“请保持代码风格统一”更有效。如果 agent 支持执行命令，甚至可以直接让它把pre-commit run --all-files作为生成流程的最后一步。

9.4 安全与合规提醒

AI 生成代码可能包含第三方开源代码片段，也可能无意中写入敏感信息。pre-commit 只负责格式和机械检查，不能验证版权归属。建议在配置中加入敏感信息扫描 hook，例如gitleaks或detect-secrets，在提交阶段避免把密钥、Token 推入仓库。这里给出一个 gitleaks 配置示例：

- repo: https://github.com/gitleaks/gitleaks rev: v8.18.4 hooks: - id: gitleaks

涉及人脸、声音、版权素材等 AI 生成内容时，即便代码仓库层面格式没问题，也必须在生成、分发、商业化前确认授权和合规边界。格式 hook 解决不了这些问题，需要团队有明确的审查流程。

9.5 分阶段执行检查

在本地 commit 阶段，建议只跑轻量、低耗时、自动修复类 hook。在 CI 阶段，跑更重的全量检查、安全扫描和类型检查。在pre-push阶段，跑单元测试、集成测试或需要更长时间的任务。这样本地体验不会被拖垮，CI 又能兜底。

10. 总结与下一步

这套方案最值得尝试的一点，就是把 AI coding agent 生成代码后的“格式收口”从人肉 review 转移到自动化层。你不需要约束团队用同一个 AI 工具，也不需要给每个模型写一套提示词，只要在 Git 提交前加一个 pre-commit hook，格式问题就会被统一拦截。

最先应该验证的功能很简单：装好pre-commit，写一份最小配置，故意制造一个坏格式文件，然后执行git commit，看它是否能自动修复并拦截提交。跑通这个循环，后续加入更多 hook 只是配置层面的工作。最容易踩的坑就一个——hook 修复文件后没有重新git add。记住这个流程，你的二次提交就会顺利通过。

接下来可以扩展的方向有不少：把ruff、prettier、gitleaks的规则逐步加进配置；在 CI 里引入pre-commit任务，保证跳过本地检查的推送也不会漏过；再用pre-commit run --all-files把历史代码统一修复一遍。等你把这一整套流程跑顺，AI coding agent 才能更好地帮你写代码，而不是一边提高产代码速度，一边制造额外的格式债务。