AI 编程 Agent 每天帮你写几百行代码，但它也会犯"低级错误"——忘记更新文档、引入不该用的依赖、生成过时的配置文件。Pokayoke 这个新工具，就是 AI Agent 时代的 ESLint，但它管的不是代码风格，而是你的项目"约定"。

一个真实场景

你跟 Claude Code 说："帮我加一个新 API 端点。"

Agent 很高效，5 分钟内写好了路由、控制器、类型定义。你把代码合并了，CI 通过了，上线了。

三天后你发现：路由文档没更新、package.json 里多了个 npx 脚本（你们团队用的是 bun）、AGENTS.md 和 CLAUDE.md 各有不同的项目指令——Agent 只更新了其中一个。

这些不是 Bug，是"约定漂移"。Agent 遵守了语法规则，但违反了你的项目约定。传统 linter 管不到这些，因为它们是你团队口口相传的"潜规则"。

这就是 Pokayoke 要解决的问题。

Pokayoke 是什么？

Pokayoke（ポカヨケ，发音 po-ka-yo-ke）是日语"防错"（Poka-Yoke）的编程工具版。这个概念源自丰田生产系统——在产品设计中加入物理约束，让错误"不可能发生"。

放到编程语境：Pokayoke 把你的项目约定变成机器可检查的规则。不仅是人类开发者能运行，AI Agent 也能运行、理解、甚至自己修复。

核心设计理念：

Agent-First：规则设计成 AI 可以自己编写和维护。你告诉 Agent "加上一条规则：禁止在 Bun 项目里用 npx"，Agent 自己写规则代码、加测试、跑验证
非侵入式：不取代 ESLint/Biome/TypeScript，而是填补它们之间的缝隙——那些"太特定于本项目、不适合放进通用 linter"的规则
可修复：支持 --fix 模式，确定性场景下自动修复

传统工具链：           Pokayoke 填补的缝隙：
┌─────────────┐        ┌─────────────────────────┐
│  Biome      │ 格式   │ • Agent 指令文件同步     │
│  TypeScript │ 类型   │ • 生成产物 vs 源文件     │
│  Knip       │ 死代码 │ • Package 策略强制       │
│  ESLint     │ 风格   │ • 项目级架构边界         │
└─────────────┘        │ • 本 repo 特定约定        │
                       └─────────────────────────┘

3 分钟上手

Pokayoke 目前基于 Bun 运行时，安装只需要两条命令：

# 安装
bun add --save-dev pokayoke

# 初始化（创建配置文件和规则目录）
bun run pokayoke init

pokayoke init 会在你的项目根目录生成：

pokayoke.jsonc          # 全局配置
.pokayoke/
  tsconfig.json          # 规则的 TypeScript 配置
  rules/                 # 放你的本地规则
    *.rule.ts            # 规则文件
    *.test.ts            # 规则测试

然后把 pokayoke 挂进你现有的检查流程：

// package.json
{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "test": "bun test",
    "pokayoke": "pokayoke check",
    "check": "bun run typecheck && bun run test && bun run pokayoke"
  }
}

现在运行 bun run check——你的类型检查、测试和项目约定检查一次性全部执行。

Agent 端设置更简单，一行命令：

npx skills add rorz/pokayoke

这会安装 Pokayoke 的 Agent Skill。之后你可以直接用自然语言让 AI 编程助手添加规则：

"用 pokayoke skill。给这个 Bun 项目添加一条规则：
禁止在 package scripts 里使用 npx。加上测试，然后跑 check。"

写你的第一条规则

假设你的团队有个约定：AGENTS.md 和 CLAUDE.md 必须保持同步（两个文件都是给 AI 看项目指令的，但很容易出现一个更新了另一个没更新）。

用 Pokayoke 把这个约定变成规则：

// .pokayoke/rules/sync-agent-docs.rule.ts
import { defineRule } from "pokayoke";
import { readFileSync, existsSync } from "node:fs";

export default defineRule({
  id: "sync-agent-docs",
  description: "AGENTS.md 和 CLAUDE.md 内容必须一致",

  async check(ctx) {
    const agentsPath = ctx.root("AGENTS.md");
    const claudePath = ctx.root("CLAUDE.md");

    if (!existsSync(agentsPath) || !existsSync(claudePath)) {
      return; // 其中一个不存在就跳过
    }

    const agentsContent = readFileSync(agentsPath, "utf-8");
    const claudeContent = readFileSync(claudePath, "utf-8");

    if (agentsContent !== claudeContent) {
      ctx.report({
        message: "CLAUDE.md 与 AGENTS.md 内容不一致，请从 AGENTS.md 同步",
        file: "CLAUDE.md",
        fix: () => {
          // --fix 模式下自动同步
          const { writeFileSync } = require("node:fs");
          writeFileSync(claudePath, agentsContent);
        }
      });
    }
  }
});

对应的测试：

// .pokayoke/rules/sync-agent-docs.test.ts
import { describe, it, expect } from "bun:test";
import { createTestContext } from "pokayoke/test";
import rule from "./sync-agent-docs.rule";

describe("sync-agent-docs", () => {
  it("两个文件相同时不报错", async () => {
    const ctx = createTestContext({
      "AGENTS.md": "# Project Rules",
      "CLAUDE.md": "# Project Rules",
    });
    const results = await rule.check(ctx);
    expect(results).toHaveLength(0);
  });

  it("两个文件不同时报错", async () => {
    const ctx = createTestContext({
      "AGENTS.md": "# Project Rules v2",
      "CLAUDE.md": "# Project Rules v1",
    });
    const results = await rule.check(ctx);
    expect(results).toHaveLength(1);
  });
});

AI Agent 协作的 3 个核心场景

场景 1：生成文档同步检查

AI 写代码时经常会更新 README.md、API 文档、路由文档等生成内容。但"源文件改了、生成文档没改"是最常见的问题。

规则思路： 检查 openapi.json 的 hash 是否与路由文件的最新状态匹配。如果不匹配，--fix 模式自动重新生成。

场景 2：禁止特定依赖模式

"这个项目用 Bun，任何地方不能出现 npx"
"依赖版本必须用 catalog: 引用，不能硬编码"
"不能直接 import src/ 以外的路径"

这些不是 ESLint 管得到的——它们是项目级策略。Pokayoke 让 Agent 理解并遵守这些边界。

场景 3：Agent 指令文件一致性

如果你同时用 Claude Code 和 Cursor（或其他 IDE Agent），你的 AGENTS.md、CLAUDE.md、.cursor/rules/ 需要保持一致。Pokayoke 能检查这些"给 AI 看的文件"是否互相矛盾或过时。

为什么这件事对 AI 开发者很重要？

2026 年，AI 编程助手写代码的质量已经超过大部分初级工程师。 SWE-bench 上的分数一涨再涨，Claude Code 2.1.7 能并行调度多个 Agent，Codex 能规划整个 feature 的实现路径。

但有一个问题始终没解决：Agent 不懂你的项目约定。

它能写出语法正确的 TypeScript，但不知道"这个项目禁止用 any"
它能生成完整的配置文件，但不知道"我们团队用 bun 不是 npm"
它能更新 README，但不知道还有一个 CLAUDE.md 也要同步更新

Pokayoke 解决的就是这个"最后 5% 的可靠性问题"。它让项目约定从"人类口口相传"变成"机器可验证的规则"。

这背后是一个更大的趋势：从 Linting 到 Policy-as-Code。

层级	工具	检查什么
格式	Biome / Prettier	代码怎么"看"
类型	TypeScript	代码怎么"运行"
死代码	Knip	代码是否"用到"
项目约定	Pokayoke	代码是否"合规"

这是工具链的自然演进——当格式化和类型检查被自动化后，下一个要自动化的就是"项目约定"。

局限与适用边界

坦白说，Pokayoke 还很早期（v0.0.7，2026 年 7 月 10 日发布），有一些现实限制：

仅支持 Bun 项目：目前需要 Bun 运行时
规则用 TypeScript 写：约定以代码形式表达，需要基础的 TypeScript 能力
规则覆盖靠你自己积累：不像 ESLint 有几千个社区规则，你需要从自己项目最痛的约定开始写
稳定性仍处于实验阶段：API 可能变化

但对于已经开始重度依赖 AI Agent 写代码的团队来说，这个投资是值得的。因为 Agent 违反约定的代价（文档过时、依赖混乱、指令文件不一致）远大于写几条规则的成本。

行动指南

今天就能做的 3 件事：

列出你项目中 Agent 最常违反的 3 个约定（比如：忘记更新 CHANGELOG、引用了不该引用的包、改了 API 路由没更新文档）
安装 Pokayoke，把最痛的那条约定写成规则（10 分钟）
把 pokayoke check 加入 CI pipeline——让违反约定 = CI 失败，Agent 再也绕不过去

# 5 分钟快速启动
bun add --save-dev pokayoke
bun run pokayoke init
# 用 AI Agent 帮你写第一条规则：
# "用 pokayoke skill，给项目加一条规则：禁止直接 import ../../ 跨三层以上"
bun run check  # 看看你的第一条规则生效了没

给 Agent 用的提示词模板：

你是这个项目的 AI 编程助手。使用 pokayoke skill 完成以下任务：

项目约定：[描述你的具体约定，例如"所有 API 路由变更必须同步更新 docs/api.md"]

请完成：
1. 写一条 pokayoke 规则来检查这个约定
2. 加上 bun test
3. 运行 bun run check 验证
4. 如果有 fix 可能，实现 --fix 支持

写在最后： AI Agent 的未来不是"替代人类写代码"，而是"在人类定义的边界内高效工作"。Pokayoke 就是在帮你画那条边界——用代码定义"什么是可接受的"，然后让 Agent 自己遵守。这不只是工具，这是 AI 时代的工程纪律。

AI工具 #Agent工坊 #代码质量 #一人公司 #AI编程