三条“禁止内联 import”指令没拦住 Claude:换成一条 lint 规则
CLAUDE.md 写三遍不如一条能退出码 1 的规则:把团队规范编码成自定义 linter,让 agent 自己跑、自己修。
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 表达的东西 | 同一条规矩在评审里被指出三次以上 |
两个移植要点:
- 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' });
},
};
},
};
- 规则报错文本要写给人(和 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 + 自定义规则串起来,跑一周再决定要不要加第三条。
来源
- 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/
- 文中指令原文、代码、Makefile 与运行输出均译自原文;版权归原作者
本文属于「AI 编程 / Vibe Coding」专题,由汇智网编译整理,转载请注明出处。
这是「AI 编程 / Vibe Coding」专题的一部分。完整地图见:AI 编程 / Vibe Coding 完全指南