1. 项目概述：为什么你的代码库需要一个“AI 友好度”检查器

如果你和我一样，最近几个月的工作流里已经离不开 Claude Code、Cursor 或者 GitHub Copilot 这类 AI 编程助手，那你肯定也经历过类似的困惑：为什么有时候 AI 助手能精准地理解你的意图，重构代码、编写测试一气呵成；而有时候它却像个“人工智障”，反复忽略你写在文档里的规则，甚至做出一些危险的、不符合项目约定的操作？问题的根源，往往不在于模型本身，而在于我们为它准备的“工作环境”——也就是我们的代码仓库。

传统的代码质量检查工具，比如 ESLint、Prettier，关注的是人类开发者能读懂的代码风格和潜在错误。但 AI 助手“阅读”和理解代码库的方式与人类截然不同。它们依赖特定的入口文件（如 CLAUDE.md 、 .cursorrules ）、受限于硬性的上下文长度（如 Claude Code 的 40K 字符上限）、并且会主动执行 git push 或运行 CI 流水线。一个对人类开发者来说“整洁”的仓库，对 AI 来说可能充满了陷阱：找不到指令文件、指令自相矛盾、CI 配置无法运行、甚至无意中暴露了密钥。

这就是 AgentLint 要解决的问题。它不是一个通用的代码检查器，而是一个专门为“AI 原生开发”设计的诊断与修复工具包。它基于对 Anthropic 官方 265 个版本 Claude Code 系统提示词的逆向工程、对 4533 个真实 Claude Code 仓库的审计分析，以及多篇学术论文的研究，提炼出了 58 项具体的检查项，覆盖了 可发现性、指令质量、可工作性、连续性、安全性和约束配置 这 8 个维度。简单来说，它用数据和事实告诉你：你的仓库里，有哪些地方正在让 AI 助手“犯迷糊”或“干坏事”，并且能帮你一键修复大部分问题。

2. 核心设计思路：从“人类友好”到“AI 友好”的范式转变

AgentLint 的设计哲学建立在一个核心认知上：为 AI 助手优化代码库，是一项独立的工程实践，它需要一套全新的、数据驱动的质量标准。这套标准不是凭空想象的，而是从 AI 助手（尤其是 Claude Code）的实际行为模式、失败案例和性能瓶颈中总结出来的。

2.1 数据驱动的检查项设计

AgentLint 的每一项检查背后都有坚实的证据支撑，这使其区别于基于“最佳实践猜想”的工具。例如：

  • 指令长度检查（I7） ：它强制检查 CLAUDE.md 文件是否超过 40,000 字符。这不是一个建议，而是一个 硬性限制 。超过这个长度，Claude Code 会直接截断你的文件，后半部分的规则对 AI 完全不可见。这个数字来源于对 Claude Code 内部机制的逆向分析。
  • 关键词密度检查（I2） ：它警告你文件中 IMPORTANT 、 CRITICAL 这类强调性关键词的密度过高。Anthropic 在其 265 个系统提示词版本的迭代中，将 IMPORTANT 的出现频率从每千字 7.5 次降低到了 1.4 次。数据表明，过度使用强调词反而会降低模型的指令遵从率，因为模型会因“狼来了”效应而麻木。
  • 文件大小检查（W5） ：它会标记任何超过 256 KB 的源代码文件。因为 Claude Code 的“读取”工具有一个硬性错误限制，尝试读取超过此大小的文件会直接失败，导致 AI 无法分析该模块。

这种基于真实限制和实证数据的检查，确保了建议的针对性和有效性。你修复的不是“可能有问题”的地方，而是“已知会出问题”的地方。

2.2 多维度的评分体系

AgentLint 没有给出一个笼统的分数，而是将 AI 友好度分解为 6 个加权维度，每个维度下包含若干检查项。这种设计让你能快速定位问题的类别：

  1. 可发现性（Findability, 20%） ：AI 能找到它需要的东西吗？核心是入口文件（ CLAUDE.md 等）的存在、位置和内容组织。如果 AI 连“说明书”都找不到或看不懂，后续一切免谈。
  2. 指令质量（Instructions, 25%） ：你的规则写得好吗？这是权重最高的维度，因为清晰、具体、符合模型认知习惯的指令是发挥 AI 能力的杠杆。检查内容包括指令的明确性、长度、关键词使用等。
  3. 可工作性（Workability, 18%） ：AI 能实际构建和测试你的项目吗？这关乎 package.json 中的脚本、CI/CD 配置、测试套件的完备性以及构建命令的文档化。一个无法 npm run build 的仓库，AI 助手寸步难行。
  4. 连续性（Continuity, 12%） ：下一个 AI 会话能接得上手吗？这检查诸如 HANDOFF.md 交接文件的存在、文档的新鲜度、变更日志是否包含“原因”等信息。确保知识能在不同 AI 会话间传递，避免重复劳动。
  5. 安全性（Safety, 15%） ：AI 是在安全地工作吗？这是最容易忽视但后果最严重的维度。检查包括 .gitignore 是否排除了 .env 、GitHub Actions 是否使用了固定 SHA 而非浮动标签、工作流权限是否最小化等。AI 助手拥有 git push 能力，错误配置可能导致供应链攻击或密钥泄露。
  6. 约束配置（Harness, 10%） ：你的 Claude Code 钩子和权限配置正确吗？这是针对深度使用 Claude Code 用户的专项检查，确保自定义的 pre-commit 钩子不会因性能问题卡住提交、 Stop 钩子不会陷入无限循环、权限配置不会意外授予 AI rm -rf 的能力。

这个评分体系像一个诊断报告，不仅告诉你“身体不适”，还精确指出是“消化系统”还是“神经系统”出了问题。

3. 实战部署：从安装到集成 CI 的完整流程

理解了 AgentLint 的“为什么”之后，我们来看看“怎么做”。它的使用流程非常直观，分为设置、检查、修复三步。

3.1 环境准备与安装

AgentLint 的核心扫描器是一个 Bash 脚本，因此它需要一个 POSIX 兼容的 Shell 环境。

  • macOS / Linux ：开箱即用。只需确保系统已安装 git 和 jq （一个轻量级 JSON 处理工具），通常通过包管理器即可安装（如 brew install jq 或 apt-get install jq ）。
  • Windows ： 不能 在原生 CMD 或 PowerShell 中运行。你必须使用 Git Bash （随 Git for Windows 安装）或 WSL （Windows Subsystem for Linux）。安装 Node.js 20+ 后，在 Bash 环境中执行安装命令。

安装命令非常简单，通过 npm 进行全局安装：

npm install -g @0xmariowu/agent-lint

安装完成后，在 Claude Code 中新建一个会话，直接输入 /al 命令，AgentLint 就会自动扫描当前项目并给出报告。这种与 IDE 深度集成的使用方式，让检查变得像调用一个内置命令一样自然。

3.2 核心命令详解

AgentLint 提供了三个核心子命令，对应开发工作流的不同阶段：

  1. agentlint setup ：项目初始化。这个命令会为你的仓库搭建一整套 AI 原生开发的基础设施。它不仅仅是创建一个 CLAUDE.md 模板，而是会生成：

    • 12 个预配置的 GitHub Actions CI 工作流 ，覆盖从代码检查、测试到安全扫描和发布的全流程。
    • 优化的 Git 钩子 ，确保 AI 的提交能通过必要的检查。
    • 符合最佳实践的 CLAUDE.md 模板 ，包含项目描述、构建指令、规则示例等。
    • 项目计划格式 和 合规性测试 框架。 使用方式： agentlint setup --lang python ~/Projects/my-repo 。这相当于为你的项目做了一次“AI 友好化”的精装修。

  2. agentlint check ：诊断扫描。这是最常用的命令，会对指定项目目录运行全部 58 项检查，并生成一份包含总分、各维度分和详细问题列表的报告。

    agentlint check --project-dir ~/Projects/my-repo

    报告会以终端彩色输出、Markdown、JSONL 或 HTML 格式呈现。HTML 报告尤其直观，包含可展开的维度详情和问题优先级排序。

  3. agentlint fix ：自动修复。这是 AgentLint 的“魔法”所在。对于它能自动修复的问题（如创建缺失的 HANDOFF.md 、将 .env 加入 .gitignore ），你可以一键应用。

    # 修复所有可自动修复的问题
agentlint fix --project-dir ~/Projects/my-repo
# 仅修复特定的检查项，例如 W11（要求特性/修复提交必须关联测试）
agentlint fix W11 --project-dir ~/Projects/my-repo

    修复过程是交互式的。对于需要人工决策的修复（如“是否将 GitHub Actions 固定到 SHA”），它会给出引导式的问题让你选择。修复完成后，它会自动重新扫描，并生成一份“修复前后”对比的 HTML 报告。

3.3 集成到 GitHub Actions CI/CD

为了让 AI 友好度成为团队的一项强制标准，将其集成到 CI 流水线中是至关重要的一步。AgentLint 提供了官方的 GitHub Action，配置极其简单。

基础集成示例： 

name: AI-friendliness check
on: [pull_request, push]
jobs:
  agentlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: 0xmariowu/agent-lint@v0
        with:
          fail-below: '60'  # 如果总分低于60分，则CI失败

这段配置会在每次 Pull Request 或推送时运行 AgentLint 检查。 fail-below 参数允许你设置一个质量门槛，低于此分数的变更将被阻止合并，从而确保代码库的 AI 友好度不会倒退。

高级集成：SARIF 报告与安全选项卡 对于更深入的集成，你可以启用 SARIF（静态分析结果交换格式）报告上传。这会将 AgentLint 的检查结果直接显示在仓库的 GitHub Security（安全） 选项卡中，并在 Pull Request 的代码行旁提供内联注释。

name: AI-friendliness check with SARIF
on: [pull_request]
jobs:
  agentlint:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write  # 必须授权以写入安全事件
    steps:
      - uses: actions/checkout@v4
      - uses: 0xmariowu/agent-lint@v0
        with:
          sarif-upload: 'true'
          fail-below: '50'

实操心得 ：对于公开仓库，SARIF 上传是免费的。对于私有仓库，你需要启用 GitHub Advanced Security (GHAS)。即使没有 GHAS，使用 ::warning 命令的内联 PR 注释功能在所有仓库中都有效，这是快速获得反馈的轻量级方案。

4. 深度解析：关键检查项背后的原理与实操

AgentLint 的 58 项检查覆盖了从文件结构到安全配置的方方面面。这里我们挑出几个最具代表性、也最容易出问题的检查项，深入探讨其原理和修复方案。

4.1 指令质量维度的核心：I1/I2 - 强调关键词滥用

  • 问题 ：很多开发者习惯在 CLAUDE.md 里大量使用 IMPORTANT 、 CRITICAL 、 MUST 等词汇，试图引起 AI 的注意。但 Anthropic 的内部数据表明，在 265 个系统提示词版本的迭代中，他们将 IMPORTANT 的出现频率从每千字 7.5 次大幅削减至 1.4 次。
  • 原理 ：大语言模型对指令的遵从存在“注意力稀释”效应。当强调词过多时，模型无法区分真正关键的要求和一般性建议，导致所有指令的权重被平均化，反而降低了关键指令的遵从率。这就像老师在课堂上对每句话都大喊“这是重点！”，学生最终会无所适从。
  • 修复 ：AgentLint 会统计这些关键词的数量和密度。修复建议是： 保留最关键、最易被违反的 3-4 条规则使用 IMPORTANT ，其余规则使用更平实的语言描述。例如，将“ IMPORTANT: Write tests. ”改为“ All new features must be accompanied by unit tests. ”，后者提供了更明确的行动指令和上下文。

4.2 安全性维度的致命陷阱：S1 - .env 文件未忽略 与 S2 - Actions 未固定 SHA

  • 问题 S1 ： .env 文件包含数据库密码、API 密钥等敏感信息。虽然开发者通常会将其加入 .gitignore ，但 Claude Code 的 Glob 工具在默认情况下会忽略 .gitignore 规则 。这意味着 AI 在搜索或读取文件时，可能会意外读取并处理 .env 文件的内容，导致密钥泄露在生成的代码或提交信息中。

  • 修复 S1 ：AgentLint 的 fix 命令可以自动将 .env 、 .env.local 、 .env.production 等常见变体添加到 .gitignore 。但更重要的是，你需要在 CLAUDE.md 中明确加入一条规则：“ Never read, write, or mention the contents of any .env* file. ” 从指令层面禁止 AI 触碰这些文件。

  • 问题 S2 ：在 GitHub Actions 工作流中，使用 uses: actions/checkout@v4 这样的浮动标签（ @v4 ）存在供应链攻击风险。如果 actions/checkout 仓库的 v4 标签被恶意篡改（虽然概率低，但并非不可能），那么 AI 助手执行的 git push 触发的 CI 流程，就会运行恶意代码。

  • 修复 S2 ：AgentLint 会检查所有 Action 引用，并建议将其替换为完整的 Git SHA 校验和，例如 uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 。 fix 命令可以以“引导模式”完成此操作，因为它需要联网查询每个 Action 当前版本对应的 SHA。这是将安全性左移，防范“一行配置引发的血案”的典范。

4.3 可工作性维度的隐蔽缺陷：W11 - 未对 feat/fix 提交门控测试

  • 问题 ：许多项目虽然有测试，但 CI 配置只会在合并到主分支时运行。这意味着 AI（或开发者）可以直接将未经测试的新功能（ feat ）或修复（ fix ）提交到特性分支，而 CI 不会运行。这些未经测试的代码在合并前可能一直处于未知状态。
  • 原理 ：AI 助手基于给定的规则和上下文生成代码和提交。如果规则中没有强制要求“每个 feat / fix 提交都必须包含并通过相关测试”，AI 可能会生成逻辑正确但缺乏测试覆盖的代码，并直接提交。
  • 修复 ：AgentLint 会检查是否存在一个名为 test-required.yml （或类似）的 GitHub Actions 工作流，该工作流配置了 paths 过滤器，确保任何修改了 src/ 目录下文件的 feat/* 或 fix/* 分支的推送，都必须先通过测试。 agentlint setup 命令生成的 CI 模板中就包含了这样的工作流。修复不仅仅是添加文件，更是建立一种“测试驱动”的 AI 协作文化。

4.4 约束配置维度的专业陷阱：H2 - PreToolUse 钩子缺少匹配器

  • 问题 ：这是深度使用 Claude Code 自定义钩子时的高频性能陷阱。在 .claude/settings.json 中，你可以定义 preToolUse 钩子在 AI 使用任何工具（如 Read、Grep、Glob）前执行。然而，AgentLint 对 4533 个仓库的分析发现， 91% 的此类钩子没有设置 matcher 字段 。
  • 后果 ：没有 matcher 的 preToolUse 钩子会在 每一次 AI 尝试使用工具时触发。想象一下，AI 在一次会话中可能调用 Read 工具几十次，每次调用前都执行一个外部脚本（例如检查网络连接、验证权限），这会带来巨大的、不必要的性能开销，严重拖慢 AI 的响应速度。
  • 修复 ： matcher 字段允许你精确指定该钩子应对哪些工具生效。例如，如果你只想在 AI 执行 Bash 命令前进行安全检查，就应该配置 "matcher": "Bash(*)" 。AgentLint 会识别出缺少 matcher 的钩子，并建议你将其范围缩小到具体的工具集，这是提升 Claude Code 会话流畅度的关键优化。

5. 避坑指南与进阶技巧

在实际使用和推广 AgentLint 的过程中，我积累了一些宝贵的经验教训和进阶用法，能帮你更好地发挥其价值。

5.1 常见问题与排查

  1. 安装后 /al 命令无效 ：

    • 症状 ：在 Claude Code 中输入 /al 无反应或报错。
    • 排查 ：首先确认是在 Claude Code 桌面应用 中，而非网页版。然后，在系统终端执行 which agentlint ，确认全局安装路径在系统的 PATH 环境变量中。Claude Code 插件会调用系统命令。对于 Windows Git Bash，有时需要重启终端或 IDE 以使新的 PATH 生效。

  2. 扫描速度慢 ：

    • 症状 ：对大型仓库（如包含 node_modules ）执行 check 时耗时很长。
    • 优化 ：AgentLint 默认会扫描整个项目目录。你可以通过 .agentlintignore 文件（类似于 .gitignore ）来排除不需要扫描的目录，如 node_modules/ , build/ , .git/ 等。这能显著提升扫描速度。

  3. CI 中分数波动大 ：

    • 症状 ：同一个仓库，本地扫描和 CI 扫描分数不一致。
    • 排查 ：重点检查 环境差异 。CI 环境通常是“干净”的，缺少某些本地存在的配置文件（如 .env.local , CLAUDE.local.md ）。确保你的检查逻辑对这些文件的存在与否是鲁棒的，或者使用 agentlint check 的 --exclude 参数在 CI 中忽略它们。另外，确认 CI 中拉取的是完整的 Git 历史（ actions/checkout 使用 fetch-depth: 0 ），因为某些连续性检查（如 C1 文档新鲜度）可能需要 Git 日志。

  4. “自动修复”破坏了现有格式 ：

    • 注意 ： agentlint fix 在修改文件（如 CLAUDE.md ）时，会尽量保持原有格式，但对于复杂或非标准的 Markdown 结构，可能无法完美处理。
    • 建议 ： 在运行 fix 前，务必先提交当前工作状态 。这样，如果修复结果不理想，你可以轻松地回退。更好的工作流是：先运行 check 生成报告，手动评估问题列表，然后选择性地对单个检查项使用 fix （如 agentlint fix W11 ），这样风险更可控。

5.2 将 AgentLint 融入团队工作流

  1. 作为预提交钩子 ：除了 CI，你还可以将 agentlint check 设置为 Git 的 pre-commit 钩子。这能在代码提交前就拦截 AI 友好度下降的变更。可以使用 husky 或 pre-commit 框架来管理。

    # 在 .husky/pre-commit 文件中添加
agentlint check --fail-below 70 || exit 1

    注意：确保钩子脚本执行速度够快，避免拖慢提交体验。

  2. 设定阶梯式质量门禁 ：不要一刀切地要求所有项目立刻达到 90 分。可以设定阶段性目标：

    • 第一阶段（>50分） ：阻塞性错误清零。确保没有安全漏洞（S1， S2）、指令可被找到（F1）、项目可被构建（W1）。
    • 第二阶段（>70分） ：良好实践。指令清晰（I系列）、基础 CI 和测试完备（W系列）、有基本的交接文档（C2）。
    • 第三阶段（>85分） ：优秀配置。深度优化了钩子性能（H系列）、实现了完整的测试门禁（W11）、文档新鲜且详细。

  3. 利用 HTML 报告进行评审 ：在 Pull Request 中，除了 CI 状态，可以要求开发者附上 AgentLint 生成的 HTML 报告。这份可视化的报告比终端输出更易于非技术成员或管理者理解，能清晰地展示本次修改在 AI 友好度各个维度上的影响，让代码评审更有依据。

5.3 超越机械检查：理解评分的本质

最后，也是最重要的一点： 不要盲目追求满分 。AgentLint 的分数是一个 测量工具 ，而非 评判标准 。它的每一项检查都基于数据和最佳实践，但你的项目可能有其特殊性。

例如，检查 I6（入口文件长度） 建议 60-120 行为佳。但如果你维护的是一个极其复杂、有特殊合规要求的框架，可能需要 200 行指令才能说清楚。这时，低于“理想”分数是可以接受的，前提是你 清楚为什么需要这么长，并且接受了可能带来的指令稀释风险 。

再比如，检查 F4（大型目录需有索引） 建议超过 10 个文件的目录应有 INDEX.md 。但对于一个自动生成的 dist/ 或 build/ 目录，这显然不必要。你可以通过 .agentlintignore 忽略该目录，或者坦然接受这一项扣分，因为这对 AI 的实际工作并无影响。

AgentLint 的价值在于，它将这些原本模糊的、依赖个人经验的“AI 友好度”概念，转化为了可测量、可追踪、可改进的客观指标。它为你和你的团队提供了一个共同的基准和沟通语言，让“优化 AI 协作体验”这件事，从玄学变成了工程。

Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

Agent 状态机设计：为什么你的工具调用总失控？

avatar DeepSeek技术社区
cover

DeepSeek路由别名漂移实战：为什么一次模型表更新能引发客服工单风暴？

avatar DeepSeek技术社区
cover

换 embedding 模型必须重建索引？新旧向量空间混搭检索的工程真相

avatar DeepSeek技术社区