三条“禁止内联 import”指令没拦住 Claude:换成一条 lint 规则

CLAUDE.md 写三遍不如一条能退出码 1 的规则:把团队规范编码成自定义 linter,让 agent 自己跑、自己修。

分享
三条“禁止内联 import”指令没拦住 Claude:换成一条 lint 规则

AI agent 很好用,这点没什么可争的。但 Jan Giacomelli 反复看到的是同一件事:它们的产出高度依赖代码库现状,以及反馈回路的质量。

CLAUDE.md、AGENTS.md、skills、memories 这些文件当然重要,但反馈回路比任何静态指令都更重要。他举了一个自己踩过的例子。

在 Ren 团队,有一段时间他们有三条指令在告诉 Claude 不要用内联 import:

6. Add imports on top of the module. Never add them as inline imports.
...
**IMPORTANT: Don't use inline imports. Imports should always be at the top of the module.**
...
**DO NOT USE INLINE IMPORTS!!!**

注意最后那条已经加了三个感叹号。

猜结果?Claude Code 还是经常用内联 import。

那怎么改善反馈回路,让这类违规在没有人工评审的情况下被抓到?

把质量检查自动化

给 AI agent 反馈最好的方式,是给它一个能执行的工具,让它在改完代码之后自己跑。

举例:与其在代码评审时一个个去抓内联 import,不如做一个工具让 agent 执行——工具会告诉它"你不能用内联 import!",然后以退出码 1 结束。

一个好的起点是把代码格式化、lint、安全检查(比如检测硬编码密码)加进代码库,并且让它们跑在每条 CI/CD 流水线里:检查不通过的 PR 不许合并。

现在 ruff 基本覆盖了这些——lint、格式化,以及通过 S 规则集实现的一部分安全规则。所以如果你不知道从哪开始,装上 ruff 并让它跑在 CI/CD 里就行。

再进一步:自定义 linter

装上 ruff 很好,但在 AI agent 时代这还不够快。

ruff 这类工具检查的是 PEP-8 及更广范围内的通用标准——是很好的第一步,但只是第一步。

他的想法很简单:把尽量多的团队编码规范,编码成自定义 lint 规则。

  • 想禁止内联 import?写一条规则。
  • 想禁止测试里出现 if?一样。
  • 想强制测试里的邮箱都用公司域名?一样。
  • 想禁止叫 jan 的变量?(对,那是他自己的名字。)也可以,加一条规则。

顺着这个思路,他做了 jg-lint——"带 Rust 内核的可扩展 Python linter"。它提供了做 linter 所需的全部样板代码和一些内置规则,同时允许你定义自己的规则:

uv add jg-lint        # 需要 Python >= 3.12

用 AST 解析器写第一条规则

假设我们真的很讨厌内联 import,那就实现一条规则。

第一步,把 jg-lint 加进项目:

$ uv add jg-lint

第二步,在 pyproject.toml 里配置它:

[tool.jg-lint]
rules_path = "./rules"

这样就是告诉 jg-lint 去 rules 目录里找规则定义。

第三步,创建 rules 包(带 __init__.py 的目录),并加上 no_inline_imports.py 模块:

import ast
from jg_linter import Rule, Violation


class NoInlineImports(Rule):
    code = "JGL001"
    message = "Inline import; move it to the module top level"

    def check(self, file_path: str, content: str) -> list[Violation]:
        if not file_path.endswith(".py"):
            return []

        try:
            tree = ast.parse(content)
        except SyntaxError:
            return []

        violations: list[Violation] = []

        def visit(node: ast.AST, inside_function: bool) -> None:
            if inside_function and isinstance(node, (ast.Import, ast.ImportFrom)):
                violations.append(
                    Violation(
                        file_path,
                        node.lineno,
                        node.col_offset + 1,
                        self.code,
                        self.message,
                    )
                )
            in_func = inside_function or isinstance(
                node, (ast.FunctionDef, ast.AsyncFunctionDef)
            )
            for child in ast.iter_child_nodes(node):
                visit(child, in_func)

        visit(tree, False)
        return violations

这里发生了什么?

第一,忽略掉 linter 的 Rust 内核在遍历目录时返回的所有非 Python 文件。

第二,用 Python 内置的 ast 模块构建抽象语法树(AST)。简单说,这个模块让你能走进 Python 代码里的各个节点并检查它们。每个节点代表 Python 语法中的一种构造,对每个节点都可以判断它的类型——比如它是不是常量、变量、函数等等;也可以检查函数参数的类型或返回类型。linters 这类工具就是靠它来检查代码、甚至自动改代码的。jg-lint 也一样。如果有语法错误,直接返回空列表——基础错误交给 ruff 这类工具处理。

第三,定义一个 visit 函数递归遍历 AST 节点,同时跟踪"当前是否在函数内部"。如果在函数内部发现 import 语句,就往 violations 里追加一条违规。每条违规包含文件路径、行号、列号、规则代码和规则消息。

最后,check 方法返回所有发现的违规。jg-lint 会遍历文件、把文件路径交给规则并执行规则。

规则写好之后,随手加一个内联 import:

# src/example.py
def greet(name: str) -> str:
    import logging
    logging.info("Greeting %s", name)
    return f"Hello, {name}!"

然后这样跑:

$ uv run jg-lint check src
src/example.py:3:5: JGL001 Inline import; move it to the module top level

Found 1 violation in 1 file.

这就行了。从此评审代码时不用再操心内联 import——jg-lint 会自动检查。

给 AI agent 的自定义 linter 工作流

AI agent 虽然厉害,但也很容易被带偏。所以他强烈建议用 make 或 just 把工作流步骤定义下来,这样就能把 agent 的检查步骤定义成一条命令:make cq-agent。

在 cq-agent 的定义里,把所有需要执行的命令收在一起,包括 jg-lint:

.PHONY: cq-agent
cq-agent:
    uv run ruff check --fix .
    uv run jg-lint check src

这样 AI agent 就能自己跑质量检查并修复报告出来的问题。最坏情况是 CI/CD 里的质量检查任务失败——但那也比在代码评审时一个个抓内联 import 好得多,对吧?

同样的办法可以给其他事情写规则,比如"测试里不许出现 if""测试里所有邮箱必须是公司域名"。

(注:jg-lint 里已经内置了"禁止内联 import"这条规则,但作为例子实在太合适,所以他又写了一遍。)

结论

关于 AI agent 已经聊了很多。但这一切即使没有 AI agent 也成立、也有用——只是以前产出同样多的代码要花更长时间,所以这些问题没那么显眼。

所以他给出的建议是:与其追着写更多代码,不如投资在一条更紧的反馈回路上,你会跑得快得多。把编码规范实现成自定义 lint 规则,jg-lint 让这件事非常简单;完全自己实现也可以。关键只有一点:AI agent 能快速、可靠地拿到反馈。

Happy engineering!

我们的整理:三层规则,从"能装"到"能表达"

原文是按"从 ruff 到自建规则"这条线讲的。换成落地顺序更清楚:

层 用什么 能表达什么 什么时候该往上走
第一层 ruff(lint + 格式化 + S 安全规则集) PEP-8、常见 bug、常见安全问题 装完就跑,几乎没有理由不做
第二层 现成 linter 的配置项(如 ESLint 的 no-console、max-lines) 团队偏好、阈值 需要"我们团队特有"的约束时
第三层 自建规则(jg-lint / ESLint 插件 / ast-grep) 命名、目录、调用方式、import 位置等任何能用 AST 表达的东西 同一条规矩在评审里被指出三次以上

两个移植要点:

  1. JS/TS 项目不用另起炉灶:同样的"内联 import"规则可以写成 ESLint 自定义规则或用 ast-grep 的 YAML 规则,前提是语法树能区分"函数体内"和"模块顶层"。ESLint 里对应的是监听 ImportDeclaration,再用祖先节点判断最近的父级是不是函数:
// eslint 规则骨架:函数体内的 import 报错
module.exports = {
  meta: { type: 'problem', messages: { inline: '内联 import;请提到模块顶层' } },
  create(ctx) {
    return {
      ImportDeclaration(node) {
        let p = node.parent;
        while (p && !['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression'].includes(p.type)) p = p.parent;
        if (p) ctx.report({ node, messageId: 'inline' });
      },
    };
  },
};
  1. 规则报错文本要写给人(和 agent)看:JGL001 Inline import; move it to the module top level 这类消息同时说明了哪里错和怎么改,agent 拿到就能自己修;写成"violation detected"就退化成了人工评审。

三条容易踩的坑

  • 本地与 CI 必须是同一条命令。原文用 make cq-agent 收口的意义就在这里:agent 跑的那条、人手动跑的那条、CI 跑的那条如果是三份配置,早晚会出现"本地绿、CI 红",而 agent 会照着绿的那份反复提交。
  • 规则宁少勿多。误报会让 agent 反复改一段本来就对的代码(以及为了过规则而加的无意义抽象)。原文的顺序是:先 ruff 打底,再一条一条加上去,每加一条都观察它有没有带来额外噪音。
  • 规则要能解释自己。同一条规则在三个月后由别人(或另一个 agent)遇到时,报错消息里那句"为什么"就是唯一的上下文来源——这也是为什么原文明明只返回 JGL001 加一行英文,也值得认真写。

这套做法的位置在整条链上很明确:它解决的是"规范已经想清楚了、但 agent 记不住"这一类问题。至于"规范本身对不对"(复杂度阈值怎么定、跨文件耦合怎么判断),属于另一个话题——那部分需要能读代码的评审,可对照我们整理的可维护性传感器实测;而"lint 之后还剩什么抓不到",见lint 不够用。

边界:jg-lint 是作者自己维护的项目(Rust 内核 + Python 规则),选它之前先看一眼维护活跃度;规则写得越细,误报带来的改造成本越高——建议像原文那样,先用一条 make cq-agent 把 ruff + 自定义规则串起来,跑一周再决定要不要加第三条。

来源

本文属于「AI 编程 / Vibe Coding」专题,由汇智网编译整理,转载请注明出处。

这是「AI 编程 / Vibe Coding」专题的一部分。完整地图见:AI 编程 / Vibe Coding 完全指南