AI Agent 总是不守规矩？Pokayoke 把代码规范变成可检查规则，再也不用指望 AGENTS.md
问题：AI 编码 Agent 对 AGENTS.md 里的约定视而不见
你用 Claude Code、Codex 或 Cursor 写代码时，肯定遇到过这个问题——你在项目里写了详细的 AGENTS.md 或 CLAUDE.md，列出了团队的代码约定，比如「模块不超过 350 行」、「不要使用自定义 Tailwind 颜色」、「文件名统一用小写下划线」、「package.json 脚本中不要用 npx」。Agent 一开始表现得还不错，但过一会儿就开始忽略这些约定，该超的行数照超，该用的颜色照用。
问题不在于 Agent 不听话，而在于 文本形式的约定缺乏可执行性。AGENTS.md 里的规则是人读的，不是机器检查的——Agent 在执行过程中不会逐条对照 AGENTS.md 做断言检查。传统的 linter（ESLint、Biome）能解决一部分通用问题，但团队特定的约定（repo conventions）不在它们的覆盖范围内。你不可能为「不要用 #f5f5f5 这个灰色」写一条 ESLint 规则，这种约定太特定于项目了。
Pokayoke 就是来解决这个问题的。它把代码约定变成可执行的 TypeScript 规则文件，每次运行 pokayoke check 就能验证所有约定是否被遵守。更妙的是——你可以让 Agent 自己来写这些规则。
快速上手
Pokayoke 由 Rory McMeekin（sarreph）开发，MIT 开源，目前 v0.0.7 alpha。需要 Bun 运行时。安装和初始化只需两条命令：
bun add --save-dev pokayoke bun run pokayoke init
这会创建 pokayoke.jsonc 配置文件和 .pokayoke/rules/ 规则目录。然后把它加入你项目的 check 脚本：
{
"scripts": {
"check": "bun run typecheck && bun run test && bun run pokayoke"
}
}
AI Agent 也可以一键接入，在 Claude Code 或 Codex 中：
npx skills add rorz/pokayoke
然后告诉 Agent：「使用 pokayoke skill，添加一个规则，禁止在 package.json 脚本中使用 npx，然后用 bun run pokayoke 验证一下。」
Pokayoke 的两个设计原则值得注意：
第一，它和现有工具共存。Biome 负责格式化，TypeScript 负责类型检查，Knip 负责发现死代码——Pokayoke 负责那些「属于你的仓库而非通用工具」的约定。它不会取代任何已有工具，而是在 check 流程中增加一层。
第二，Agent-first 设计。Pokayoke 自带了完整的 SKILL.md，Agent 第一次运行 npx skills add 后就能理解如何创建、修改和运行规则。开发者不需要手动编写规则文件——描述你的约定，让 Agent 转换成可执行代码。
规则怎么写
Pokayoke 的规则是 TypeScript 文件，存放在 .pokayoke/rules/ 目录下，命名格式为 *.rule.ts。有两种规则类型：
file规则：逐文件检查 AST 或字符串模式，适合行数限制、命名约定、导入风格等project规则：检查整个仓库的结构、依赖图、生成文件一致性等跨文件的约定
配置示例（pokayoke.jsonc）：
{
"$schema": "https://pokayoke.codes/schema.json",
"extends": ["pokayoke/recommended"],
"localRules": [".pokayoke/rules/**/*.rule.ts"],
"files": ["AGENTS.md", "README.md", "apps/**/*.ts", "packages/**/*.ts"],
"ignores": ["**/node_modules/**", "**/dist/**", "**/*.d.ts"],
"rules": {
"structure/max-file-lines": "error"
}
}
Pokayoke 内置了多组规则预设：
pokayoke/recommended：包含structure/max-file-lines（默认 350 行上限）和suppressions/no-unused（清理无用的抑制注释）pokayoke/typescript/recommended：包含typescript/no-forward-reference（禁止类型前向引用）、typescript/no-optional-env（禁止可选环境变量访问）、typescript/no-swallowed-errors（禁止吞没错误）pokayoke/package-policy/bun-workspaces：包含package/catalog（强制使用 catalog 协议）、package/workspace-protocol（强制 workspace 协议）、package/no-npx-in-scripts（禁止在 Bun 脚本中用 npx）
自定义规则的核心结构很简单。写一个规则之前，问五个问题：
- 这个规则保护什么约定？
- 哪个源可以作为判断依据？
- 它需要检查哪些文件？
- 规则失败时，人或 Agent 应该怎么做？
- 结果是 warning 还是 error？
规则文件本身就是一个 TypeScript 模块，可以使用任意 AST 遍历、正则匹配或文件系统操作。例如一个「禁止直接引用其他 workspace 内部文件」的规则，可以解析所有 import 路径，检查是否指向 ../packages/*/src/internal/ 模式。
实战场景
场景一：维护生成文档的时效性
你的项目用 Markdown 生成 API 文档，路由文件更新后文档经常不同步。Pokayoke 可以写一个 project 规则：读取路由文件的导出路径，与文档目录中的文件列表做 diff。不一致时报告错误，Agent 收到反馈后自动生成缺失的文档页面。这比在代码 review 中提醒「文档没更新」自动化得多。
场景二：约束 workspace 跨包引用
在 monorepo 中，A 包通过 import { something } from 'b' 引入 B 包是合理的，但 import { helper } from 'b/src/internal/helper' 直接引用内部文件就不合适了——这样 B 包的内部重构会波及 A 包。用 Pokayoke 写一个规则，检查所有跨包 import 是否使用了 workspace 协议或只引用了公开入口。规则失败时，Agent 自动修复导入路径。
场景三：限制模块复杂度
规定 TypeScript 函数的圈复杂度不超过 10。Pokayoke 的 file 规则可以逐文件遍历 AST，找到每个函数并计算其分支数（if、switch、for、while 等），超过阈值的函数报告具体行号和当前复杂度值。Agent 收到报告后可以建议分解方案。
场景四：Agent 指令文件的自检
AGENTS.md 和 CLAUDE.md 本身也容易和实际命令脱节。你写「运行 npm run build」，但项目已经切换到 bun run build。Pokayoke 可以写一个 file 规则扫描 AGENTS.md，提取所有命令行引用，与 package.json 中的 scripts 做交叉验证——不一致时报告差异，Agent 自动修正指令文件。
Fix Mode：不仅是检查
有些规则支持 fix mode——当修复路径是确定性的，Pokayoke 可以直接生成修复后的文件内容，无需人工介入。这对生成文件同步（场景一）和导入路径修正（场景二）特别有用：规则发现不一致，Agent 自动生成修复代码，减少人工介入。
Suppressions：特殊情况豁免
总有某些文件需要绕过特定规则（比如自动生成的文件确实会超过行数限制）。Pokayoke 支持在 pokayoke.jsonc 的 ignores 中排除文件和目录，也支持在单个规则中配置排除模式。对临时豁免，可以在代码或文件中添加 suppression 注释，Pokayoke 会跟踪哪些 suppression 已不再需要，通过 suppressions/no-unused 规则提醒清理。
总结
Pokayoke 填补了 linter 和 AGENTS.md 之间的空白——它为那些「太特定于项目、不值得写通用 linter 规则」的约定提供了一个轻量的执行框架。加上 Agent-first 的设计（npx skills 一键安装），它可以作为 AI 编码 Agent 工作流中的 约定验证层，把团队规范从「可读的文本」变成「可执行的检查」。
如果你也在头疼 Agent 总是忽略你的代码约定，不妨试试 Pokayoke：让 Agent 自己为它的行为写出检查规则，形成「约定 → 规则 → 验证 → 修复」的闭环。
相关链接