Pokayoke: Stop Bugs at the Source with Policies AI Can Actually Understand

Back in the 1960s, Japanese manufacturing legend Shigeo Shingo came up with a brilliant concept: pokayoke. The core question he was tackling sounds eerily familiar to what we face in software today—how do you design systems that make errors either impossible or instantly detectable?

The beauty of the idea lies in its simplicity. Rather than hoping people follow procedures perfectly every time, you build guardrails that catch problems automatically. A plug that only goes in one way. A sensor that stops the assembly line the moment something's off. In manufacturing, this keeps defective products from reaching customers. In our world, it keeps convention violations from reaching production.

Pokayoke.codes takes this decades-old philosophy and applies it directly to your codebase—specifically, for the era where AI assistants are becoming genuine development partners.

Where Linters Fall Short

Let's be honest: most teams already have solid linting in place. ESLint catches unused variables. Prettier handles formatting. TypeScript enforces type safety. These tools are excellent at what they do. But here's the problem—they can't capture the tacit knowledge that lives in everyone's heads. The unwritten rules. The "we always do it this way" agreements that somehow never made it into a config file.

Maybe your API endpoints need to follow a specific naming pattern. Perhaps there are approved packages for security-sensitive areas. Or your team has conventions about folder structure that nobody ever wrote down. These are exactly the gaps traditional linting simply cannot fill.

That's the void pokayoke aims to address. It gives you a way to codify the repository-specific rules that fall outside any standard tool's scope but matter just as much to keeping your codebase coherent.

Built for AI First

Here's where things get genuinely interesting: pokayoke is designed for AI agents as the primary audience.

Today's coding assistants can navigate your project, write features, and refactor code. But keeping them aligned with your team's specific standards? That's still largely manual work. You might stuff rules into a system prompt, but models forget, hallucinate, or simply lack context about what you actually care about.

Pokayoke flips this by treating policy rules as first-class citizens—something agents can parse, comprehend, and follow autonomously. Running pokayoke agent SKILL.md initializes agents with your conventions, and the rules themselves are crafted to be written and maintained by AI, not just for human developers.

If you're leaning into a Vibe Coding workflow where AI does most of the heavy lifting, pokayoke gives you a way to communicate your standards in a format that actually sticks.

Plays Well with Others

Adding new tooling always risks creating chaos. You've already got ESLint, Prettier, Husky, and plenty more keeping your project in check. Bringing in pokayoke doesn't mean replacing any of that—it means augmenting your pipeline with something those tools simply can't provide.

The docs make clear that pokayoke stays out of formatting debates (that's Prettier's territory) and general code quality (ESLint's job). Instead, it focuses purely on the project-specific invariants that only your team would know. The TypeScript rules live in your repo and validate against constraints tailored to your setup. Consider it a custom validation layer sitting on top of your existing tooling.

Quick Start

Ready to put the brakes on convention drift? Getting started takes seconds:

npx skills add rorz/pokayoke

From there, you can define rules that capture your team's specific conventions. The rules are written to be self-documenting—humans and agents alike can read them to understand which policies are active and why they exist.

Looking Ahead

Pokayoke signals something worth paying attention to: a shift in how we approach code quality tools. Traditional linters enforce syntax and style. Static analyzers hunt for bugs. But as AI coding assistants become primary collaborators, we need entirely new categories of tools that communicate intent in ways agents can actually consume and act upon.

This isn't just about catching mistakes anymore. It's about making your standards machine-readable, agent-friendly, and difficult to bypass—whether the code comes from a developer or an AI.

In that sense, pokayoke might be among the first tools purpose-built for how we'll all be writing software in the near future. Definitely worth keeping an eye on.