> ## Content Index
> Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# 三条“禁止内联 import”指令没拦住 Claude：换成一条 lint 规则
- URL: https://www.hubwiz.com/blog/custom-linter-feedback-loop-ai-agents/
- Published: 2026-11-18T15:05:36.000Z
- Updated: 2026-11-18T15:15:50.000Z
- Description: CLAUDE.md 写三遍不如一条能退出码 1 的规则：把团队规范编码成自定义 linter，让 agent 自己跑、自己修。
- Author: admin
- Tags: AI 编程, lint, Python, Claude, 代码规范

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 所需的全部样板代码和一些内置规则，同时允许你定义自己的规则：

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

```

## 用 AST 解析器写第一条规则

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

**第一步**，把 jg-lint 加进项目：

```bash
$ uv add jg-lint

```

**第二步**，在 `pyproject.toml` 里配置它：

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

```

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

**第三步**，创建 rules 包（带 `__init__.py` 的目录），并加上 `no_inline_imports.py` 模块：

```python
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：

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

```

然后这样跑：

```bash
$ 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：

```makefile
.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`，再用祖先节点判断最近的父级是不是函数：

```js
// 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 记不住**"这一类问题。至于"规范本身对不对"（复杂度阈值怎么定、跨文件耦合怎么判断），属于另一个话题——那部分需要能读代码的评审，可对照我们整理的[可维护性传感器实测](https://www.hubwiz.com/blog/maintainability-sensors-coding-agents/)；而"lint 之后还剩什么抓不到"，见[lint 不够用](https://www.hubwiz.com/blog/when-linting-is-not-enough-ai-code/)。

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

### 来源

- Jan Giacomelli, *Improve feedback loop for AI agents with custom linter*, 2026-06-17：[jangiacomelli.com/blog/improve-feedback-loop-for-ai-agents-with-custom-linter/](https://jangiacomelli.com/blog/improve-feedback-loop-for-ai-agents-with-custom-linter/?ref=hubwiz.com)
- 文中指令原文、代码、Makefile 与运行输出均译自原文；版权归原作者

本文属于「[AI 编程 / Vibe Coding](https://www.hubwiz.com/blog/vibe-coding-stack/)」专题，由汇智网编译整理，转载请注明出处。

> **这是「AI 编程 / Vibe Coding」专题的一部分。**完整地图见：[AI 编程 / Vibe Coding 完全指南](https://www.hubwiz.com/blog/vibe-coding-stack/)