Pokayoke: Protege tu repositorio contra errores con políticas amigables para agentes IA

Si alguna vez has trabajado en una línea de ensamblaje japonesa de los años 60, probablemente conoces el término pokayoke. Shigeo Shingo lo acuñó para describir algo brillante: en lugar de confiar en que las personas nunca cometan errores, mejor diseñas sistemas que los hacen imposibles o, como mínimo, imposible pasarlos por alto.

Piensa en un enchufe que solo encaja de una forma. O en un sensor que detiene la producción si algo está mal alineado. En manufactura, esto evita que los defectos lleguen al cliente. En desarrollo de software, lo que evitas es que el caos llegue a producción.

Pokayoke.codes trae esta filosofía a tu repositorio con una herramienta pensada desde cero para la era del desarrollo asistido por IA.

Más allá del linting: la política como documentación

La mayoría de los equipos ya tienen linters. ESLint te avisa de variables sin usar. Prettier impone un formato consistente. TypeScript atrapa errores de tipos. Funcionan bien, sí. Pero ninguno captura ese conocimiento implícito que vive en la cabeza de tu equipo: convenciones que todos conocen pero que nadie ha escrito en ningún lado.

Quizás tus endpoints de API siguen un patrón de nombres específico. Tal vez tienes reglas sobre qué paquetes son aceptables para ciertos contextos. O quizás existe un acuerdo sobre cómo organizar los archivos que no está enforced en ningún lugar.

Ahí es donde entra pokayoke. Te permite codificar invariantes específicas del repositorio que caen fuera del alcance del linting tradicional pero importan igual para la consistencia del código.

Diseñado para agentes primero

Aquí está lo que hace a pokayoke genuinamente interesante: está construido para agentes IA desde el principio.

Los asistentes de código modernos pueden navegar tu codebase, escribir features nuevas y refactorizar código existente. ¿Pero mantenerlos alineados con las convenciones de tu equipo? Eso sigue siendo un proceso manual. Puedes agregar reglas al system prompt, pero los agentes olvidan, alucinan, o simplemente no saben qué consideras importante.

Pokayoke resuelve esto tratando las reglas de política como ciudadanos de primera clase que los agentes pueden leer, entender y seguir. El comando pokayoke agent SKILL.md pone a los agentes en marcha de forma autónoma, y las reglas mismas están diseñadas para ser escritas y mantenidas por IA, no solo por desarrolladores humanos.

Si estás construyendo un workflow de Vibe Coding donde la IA maneja el trabajo pesado, pokayoke te da una forma de comunicar tus estándares en un formato que realmente permanece.

Se lleva bien con tu stack

Una preocupación común al agregar nuevas herramientas es el riesgo de fragmentación. Ya tienes ESLint, Prettier, Husky, y una docena de otras cosas manteniendo tu código en orden. Agregar pokayoke no significa reemplazar nada de eso: significa extender tu pipeline existente.

La documentación deja claro que pokayoke es unopinionated. No le importa el formateo (eso es trabajo de Prettier) ni la calidad general del código (que ESLint maneje eso). En cambio, se enfoca en las invariantes específicas del proyecto que solo tu equipo conoce.

Las reglas de TypeScript son locales a tu repo y verifican contra las restricciones que importan para tu setup particular. Piénsalo como una capa de validación custom built sobre tu tooling estándar.

Empezando

¿Listo para proteger tu repositorio contra errores? La instalación es directa:

npx skills add rorz/pokayoke

Desde ahí, puedes definir reglas que capturen las convenciones de tu equipo. Las reglas están diseñadas para ser autodescriptivas: tanto humanos como agentes pueden leerlas para entender qué políticas están vigentes y por qué.

El panorama completo

Pokayoke representa un cambio interesante en cómo pensamos las herramientas de calidad de código. Los linters tradicionales enforce sintaxis y estilo. Los analizadores estáticos atrapan bugs. Pero conforme los asistentes de código IA se convierten en colaboradores principales, necesitamos nuevas categorías de herramientas que comuniquen intención de formas que los agentes realmente puedan consumir y seguir.

Ya no se trata solo de atrapar errores. Se trata de hacer tus estándares legibles por máquinas, amigables para agentes, y difíciles de violar, ya sea que el código venga de un desarrollador humano o de un asistente IA.

En ese sentido, pokayoke podría ser una de las primeras herramientas construidas específicamente para cómo todos estaremos escribiendo código en unos años. Vale la pena mantenerlo en el radar.