使用 AI 助手提升代码质量

I’m happy to help translate the article, but I need the full text you’d like translated. Could you please paste the content (excluding the source line you already provided) here? Once I have the text, I’ll translate it into Simplified Chinese while preserving the original formatting, markdown syntax, and technical terms.

当前状态

本文展示了一个实际的代码库，该代码库已超过五年未进行积极维护，但仍在运行一个被积极使用的产品。它对业务至关重要，却没有必要的安全保障措施。让我们逐步——包括提示——了解如何一次一个提示地提升此仓库的代码质量。

该项目是一个 Django 后端应用，提供 API。快速浏览可以看到有测试和一些文档，但缺乏一致的运行和测试应用的方式。

Source: …

旅程

我假设你正在使用 Claude Code（大多数情况下是 Claude Sonnet 4）运行这些命令。相同的方法也适用于任何编码助手；结果会因模型、提示和代码库的不同而有所差异。

设置基础文档和一些自动化

如果你使用类似 Claude Code 的工具，在你的仓库中运行 /init，就会得到这份文档的大部分内容。

Can you analyse the code and write up documentation in README.md that
clearly summarises how to set up, run, test and lint the application.
Please make sure the file is concise and does not repeat itself.
Write it like technical documentation. Short and sweet.

接下来，开始设置一些自动化（例如 just 文件），让项目更易使用。这可能需要几次尝试才能做好，但下面的提示可以帮助你起步：

Please write up a just file. I would like the following commands:
`just setup` – set up all the dependencies of the project  
`just run`   – start up the application including any dependencies  
`just test`  – run all tests  

If you require clarifications, please ask questions.
Think hard about what other requirements I need to fulfill.
Be critical and question everything.
Do not make code changes till you are clear on what needs to be done.

这会给你一个基础结构，便于快速修改。如果你的 README.md 已经描述了运行应用的首选方式（本地 vs. Docker），just 文件会自动使用它；否则你需要提供进一步说明。

为早期反馈设置 pre‑commit

先从小处入手，逐步扩展。

Please setup pre‑commit with a single task to run all tests on every push.
Update the just script to ensure pre‑commit hooks are installed locally
during the setup process.

保持上下文简洁、任务聚焦，有助于你更快推进。

筛选代码质量工具

首先，寻找合适的工具，制定计划，然后执行。将 Claude Code 切换到 Plan mode（Shift + Tab 两次），并询问：

What's a good tool to check the complexity of the Python code in this
repository and lint it to provide the team feedback as a pre‑commit hook?

助手会推荐一套工具。在一个技术债务沉重的大型代码库中，你不会立刻得到绿色构建。进一步细化请求：

The list of tools you suggested sounds good.
The codebase currently has a very large number of violations.
I want the ability to incrementally improve things with every commit.
How do we achieve this?

制定计划

在对上一个提示进行迭代后，你会收到一个具体的计划。在助手执行之前，创建一个“保存状态”（类似于视频游戏的存档），以便出现问题时可以回滚。这也会清空上下文，因为所有内容都会被转储到磁盘上的 markdown 文件中。

Can you create a plan that is executable in steps?
Write that plan to `docs/code-quality-improvements`.
Try to use multiple background agents if it helps speed up this process.

给助手几分钟时间分析代码。以我为例，以下文件被创建。生成的 README.md 中注明：“同一阶段的任务可以由多个 Claude Code 助手并行执行，只要前置条件已满足。”

概览

您已经准备好使用 /clear 并清除上下文窗口。

任务计划

• 第 1 阶段 – 设置基本工具
• 第 2 阶段 – 配置这些工具
• 第 3 阶段 – 专注于集成和自动化
• 第 4 阶段 – 添加监控并提升代码质量

在执行计划之前，请将其提交到 docs/code-quality-improvement。这样可以跟踪已进行的任何更改。执行计划时，不要将对计划所做的更改提交；您可以在过程结束时删除该计划。

如果您想将计划保留为工件，需要让 Claude Code 使用 相对路径（默认情况下，它在请求更新文件时会使用绝对路径）。

Source:

执行计划

I would like to improve code quality and I have come up with a plan to do 
so under `docs/code-quality-improvement`.
Can you analyse the plan and start executing it? The `README.md` has a 
quick‑start section which tasks about how to execute different phases of the 
plan. As you execute the plan, mark tasks as done to track state.

Note: Claude Code 将向 requirements-dev.txt 添加依赖，并尝试在未安装它们的情况下运行。它也可能会添加不存在的依赖。
停止执行（按 Esc）并使用以下提示进行纠正：

For every pip dependency you add to `requirements-dev.txt`, please run 
`pip install`. 
Before adding a dependency to the dependency file, please check if it is 
available on pip.

第 1 阶段和第 2 阶段之后

以下文件已创建并准备提交。

当在 第 3 阶段 添加质量门时，运行一次命令以测试一切是否正常并创建另一次提交。之后，提示 Claude Code 将 lint 步骤集成到简化的开发者体验中：

Please add `just lint` as a command to run all quality checks

测试新的 lint 命令，然后提交并让 Claude Code 继续进行 第 4 阶段。

你可能会看到 Claude Code 对它自己创建的计划产生怀疑。系统是可用的，但如果你希望进行更高级的检查，请请求它继续执行 第 4 阶段 实现。

Result After Phase 4

代码库现在会在每次开发者推送代码时检查代码质量：

• Pre‑commit hooks 在推送前运行 lint 检查。
• 如果更改的文件包含以下问题，质量检查将失败：
  • 未格式化的代码
  • 导入顺序错误
  • flake8 lint 问题
  • 循环复杂度过高的函数

仅检查被修改的文件（我们告诉 Claude 存在需要降低的技术债务，所以默认情况下并非所有检查都会通过）。

修复现有债务

像 isort 这样的工具可以自动突出显示并修复许多问题。在大多数代码库中，这将涉及几乎每个文件。无法自动修复的问题（例如通配符导入）必须手动处理。

成本提示： 如果你有大量问题，使用 Claude Code 可能会变得昂贵（对一个体量适中的代码库可能超过 $10）。考虑切换到 GitHub Copilot 的代理以降低成本。

建议的工作流程

1. 让你的编码助手运行 lint 命令并修复这些问题。
2. 如果助手在尝试了几次后停止，指示它继续执行任务，直到 没有 lint 错误 为止。
3. 如果你的上下文文件（CLAUDE.md）未说明如何进行 lint，请明确提供完整的命令。

还剩下什么？

The gradual-tightening 任务创建了一个分析代码并逐步变得更严格的命令。它可以手动运行，也可以在 CI 流水线中自动运行。其参数之一 max‑complexity 默认值为 20，并将在以后逐步降低。

Similarly, the complexity‑check 任务从较低的标准开始，并应定期收紧，以提升仓库的质量标准。

在很大程度上，最后的一公里必须由我们所有的团队成员共同完成。
我们现在拥有一个强有力的反馈机制，针对会导致流水线失败并阻止代码提交或推送的糟糕代码。
最后这一步需要建立团队文化。 在我的一个团队中，我们在每次回顾时都会进行一次软检查，以确认每位成员在一个冲刺周期内是否让代码库稍微变好一点。 冲刺周期为 10 天，“稍微变好”可以包括重构一个只有 2–3 行的微小函数并改进它。 标准设得非常低，但想要改进的社会压力激励我们所有人推动积极的改变。
拥有高质量的代码库和良好的开发者体验并非空想，借助 Claude Code 或 Copilot 等 AI 编码助手，将其变为现实比以往任何时候都更容易。
你最近能够改进什么？ 😃