Pokayoke: Colocando as Regras do Seu Projeto ao Alcance dos Agentes

Nos anos 1960, o japonês Shigeo Shingo criou o termo pokayoke para resolver um problema que todo desenvolvedor conhece: como tornar erros impossíveis — ou pelo menos, impossíveis de ignorar?

A ideia é elegante. Em vez de depender de pessoas seguindo regras à risca, você projeta sistemas que detectam desvios automaticamente. Uma tomada que só encaixa de um jeito. Um sensor que para a linha quando algo está errado. Na indústria, isso evita que produtos com defeito cheguem ao cliente. Em software, evita que bad practices cheguem à produção.

O pokayoke.codes traz essa filosofia para o seu repositório com uma ferramenta feita sob medida para a era do desenvolvimento assistido por IA.

Mais Que Linting: Políticas Como Documentação

A maioria dos times já tem linters. O ESLint pega variáveis não utilizadas. O Prettier padroniza formatação. O TypeScript detecta erros de tipo. Essas ferramentas funcionam bem, mas não capturam o conhecimento implícito que mora na cabeça do time — aquelas convenções que todo mundo sabe, mas ninguém documentou.

Talvez suas rotas de API sigam um padrão específico de nomenclatura. Talvez existam regras sobre quais packages são aceitáveis para determinados contextos. Ou talvez haja um acordo sobre organização de arquivos que não está sendo aplicado em lugar nenhum.

É aqui que o pokayoke entra. Ele permite codificar invariantes específicas do repositório que estão fora do escopo do linting tradicional, mas são tão importantes quanto para a consistência do código.

Feito Para Agentes Primeiro

O que torna o pokayoke realmente interessante: ele foi construído para agentes de IA em primeiro lugar.

Assistentes de programação modernos conseguem navegar pelo seu código, escrever novas funcionalidades e refatorar código existente. Mas mantê-los alinhados com as convenções do time? Isso ainda é um processo manual. Você pode adicionar regras ao system prompt, mas os agentes esquecem, alucinam, ou simplesmente não sabem o que é importante para você.

O pokayoke resolve isso tratando as regras de política como cidadãos de primeira classe — algo que os agentes podem ler, entender e agir. O comando pokayoke agent SKILL.md coloca os agentes para funcionar de forma autônoma, e as próprias regras são feitas para serem escritas e mantidas por IA — não só por humanos.

Se você está construindo um fluxo de Vibe Coding onde a IA cuida do trabalho pesado, o pokayoke te dá uma forma de comunicar seus padrões de um jeito que realmente gruda.

Convive Bem Com Sua Stack

Uma preocupação ao adicionar uma ferramenta nova é o risco de fragmentação. Você já tem ESLint, Prettier, Husky, e uma dezena de outras ferramentas mantendo o código na linha. Adicionar pokayoke não significa substituir nenhuma delas — significa estender seu pipeline existente.

A documentação deixa claro que o pokayoke não tem opinião sobre formatação (isso é trabalho do Prettier) ou qualidade geral de código (deixe o ESLint cuidar disso). Em vez disso, ele foca nas invariantes específicas do projeto que só o seu time conhece.

As regras em TypeScript ficam no seu repositório e verificam exatamente as restrições que importam para a sua configuração particular. Pense nele como uma camada extra de validação sobre as ferramentas padrão.

Começando

Pronto para proteger seu repositório contra deslizes? A instalação é simples:

npx skills add rorz/pokayoke

A partir daí, você pode definir regras que capturam as convenções do seu time. As regras são feitas para se auto-documentar — tanto humanos quanto agentes podem ler para entender quais políticas estão em vigor e por quê.

O Panorama Geral

O pokayoke representa uma mudança interessante na forma como pensamos sobre ferramentas de qualidade de código. Linters tradicionais aplicam sintaxe e estilo. Analisadores estáticos pegam bugs. Mas à medida que assistentes de IA se tornam colaboradores principais, precisamos de novas categorias de ferramentas que comuniquem intenção de um jeito que os agentes realmente consigam consumir e seguir.

Não é mais só sobre pegar erros. É sobre tornar seus padrões legíveis por máquinas, amigáveis para agentes, e difíceis de violar — seja o código escrito por um desenvolvedor humano ou por um assistente de IA.

nesse sentido, o pokayoke pode ser uma das primeiras ferramentas construídas de propósito para como todos nós estaremos escrevendo código em alguns anos. Vale ficar de olho.