Qué es k0lmenIA

Un equipo de agentes especializados en QA para Claude Code, pensado para profesionales de testing manual: no hace falta programar, se trabaja conversando dentro de VS Code.

Ponés un insumo (una historia, una observación de bug, un contrato de API, o directamente una key de Jira o un link de Figma), pedís lo que necesitás en lenguaje natural y el agente que corresponde genera el resultado: análisis, planes, casos en Excel o Gherkin, datos, bugs, reportes HTML, automatización y carga en la herramienta de gestión.

Principios

Agentes

Claude Code elige el agente según lo que pidas. Están en .claude/agents/ y se agrupan en cuatro familias. El catálogo completo (cuándo usar cada uno, pedido de ejemplo, entradas, salidas y qué confirma) está en AGENTES.md.

Requisitos

Instalá solo lo que vayas a usar.

Instalación

En cinco minutos tenés los agentes andando; k0lmena y el resto se suman cuando los necesites.

1. Instalá Claude Code

   curl -fsSL https://claude.ai/install.sh | bash     # macOS / Linux
   npm install -g @anthropic-ai/claude-code           # alternativa (con Node.js 22 LTS cubrís todo)
   claude --version

   En Windows, seguí la guía oficial.
2. Cloná el repositorio

   git clone https://github.com/underc0delabs/k0lmenIA.git
   cd k0lmenIA                                        # o la carpeta donde lo clonaste
   pip install -r requirements.txt                    # Mac/Linux: pip3
   npm install                                        # k0lmena
   cp .env.example .env                               # y completalo (PowerShell: copy)

   En Windows el comando es python; en Mac y Linux, python3 y pip3 (si pip3 responde externally-managed-environment, usá un entorno virtual: python3 -m venv .venv).
3. Revisá que esté todo listo

   npm run doctor                                     # dice qué falta y cómo resolverlo

4. Abrí VS Code y lanzá Claude Code

   code .
   claude                                             # la primera vez pide autenticarte

5. Sumá lo opcional

   npx playwright install                             # ejecución E2E en vivo
   npm install -g newman                              # colecciones de Postman
   cd herramientas/k0lmena
   npx playwright install chromium               # + firefox webkit para el cross-browser
   npm run bootstrap:k6                               # performance de APIs con k6
   npm run bootstrap:jmeter                           # performance con JMeter (Java 8+)

Configuración: el archivo .env

Hay un solo .env, en la raíz del repo. Lo usan los agentes, k0lmena y los scripts de gestión. Está en .gitignore y la plantilla comentada es .env.example.

Carpetas de entrada

Investigación de contexto y "Falta información"

Antes de analizar, planificar, escribir casos o automatizar, los agentes investigan el contexto completo de la historia en lugar de suponer. Lo que no encuentran en ninguna fuente queda marcado como Falta información en todos los reportes.

Dónde buscan

El resultado es una ficha de contexto reutilizable, output/contexto/contexto-HU-XXX.md: fuentes consultadas, hallazgos por criterio, decisiones, contradicciones y lo que falta. Si la historia no cambió, los demás agentes la reusan sin volver a investigar. Si un conector no está activo, la fuente queda como "No disponible" en lugar de suponerla.

Falta información (FI-XX)

Cada dato que no aparece en ninguna fuente (o aparece contradictorio) recibe un ID por historia, con qué falta, dónde se buscó, a qué afecta y la pregunta para el PO. El mismo ID viaja a todos los artefactos. La app no es fuente de requisitos: si el resultado esperado depende de un dato faltante, el escenario no se "acomoda" a lo que hace la aplicación; se automatiza con el supuesto marcado o queda @bloqueado hasta que el PO responda.

Diseño y ejecución

Qué pedir, qué hace cada agente y qué deja.

Automatización con k0lmena

El framework integrado en herramientas/k0lmena/. Un agente mapper recorre la aplicación una sola vez y escribe la automatización; desde ahí la suite corre con npm, sin agentes y sin tokens.

Correr la suite

cd herramientas/k0lmena
npm test                                  # web + API
npm run test:web                          # también: test:api · test:mobile · test:all
TAGS=@HU-001 npm test                     # filtrar por tag (bash)
$env:TAGS="@HU-001"; npm test             # filtrar por tag (PowerShell)
npm run report:web                        # también: report:api · report:mobile

Si EVIDENCE está vacía, npm test pregunta al arrancar qué guardar de los tests que pasan: solo captura, o captura + GIF del recorrido.

Evidencias en el reporte

Herramientas extra

Pruebas de performance

El performance-mapper arma pruebas de carga, estrés, soak y picos. Nunca usa valores por defecto: la carga y los umbrales los definís vos.

Comandos

npm run perf                                       # lista los scripts
npm run perf -- <script> smoke                     # valida el script con carga mínima
npm run perf -- <script> load                      # carga objetivo (pide confirmación)
npm run perf -- <script> stress --confirmar        # sin pregunta: CI o con autorización
npm run perf -- <script> load --vus 20 --duracion 2m   # k6 y JMeter: pisa la carga

Cada corrida deja en reports/performance/<k6|artillery|jmeter>/ un reporte HTML con el veredicto, requests, req/s, errores, latencias p50/p95/p99, umbrales con el valor medido, detalle por endpoint o paso, códigos de respuesta, checks y, en Artillery, la evolución en el tiempo. Si un umbral no se cumple, el comando termina con error.

Xray, QMetry, AIO Tests y Azure DevOps

gestor-pruebas y publicador-resultados trabajan con Xray Cloud, Xray Server/Data Center, QMetry para Jira (QTM4J) y AIO Tests, con los mismos comandos para todas.

Se configura en el .env: GESTION_HERRAMIENTA (xray-cloud, xray-dc, qtm4j o aio), GESTION_PROYECTO (la key del proyecto de Jira) y las credenciales de tu herramienta, explicadas en .env.example.

Equivalencias

Comandos manuales

python scripts/gestion/gestion.py --dry-run carpeta --ruta "HU-001 Registro"
python scripts/gestion/gestion.py subir-casos --origen <casos.xlsx> --carpeta "HU-001 Registro" --historia PROJ-12 --traza HU-001
python scripts/gestion/gestion.py crear-ciclo --nombre "Sprint 5" --historia PROJ-12 --traza HU-001
python scripts/gestion/gestion.py extraer-resultados --reporte <cucumber-report.json>
python scripts/gestion/gestion.py publicar-resultados --ciclo PROJ-60 --resultados <resultados.json> --traza HU-001

Las carpetas van sin barra inicial (en Git Bash, /HU-001 se convierte en una ruta de Windows). Referencia completa en scripts/gestion/README.md.

Azure DevOps (Test Plans)

Azure DevOps no pasa por gestion.py: se integra por su conector MCP oficial (azure-devops), con ADO_ORGANIZACION, ADO_PAT y ADO_PROYECTO en el .env. Los agentes leen las historias (con comentarios, tareas, padre y vínculos) y la Wiki, y gestor-pruebas crea los Test Cases con sus pasos (los arma scripts/gestion/para_azure_devops.py), los vincula a la historia y los agrega a una suite. Todavía no se publican resultados de ejecución en Azure DevOps.

Verificación en base de datos

El verificador-datos revisa lo que las pruebas no ven: qué quedó guardado, en qué estado y con qué valores. Soporta PostgreSQL, MySQL / MariaDB, SQL Server y MongoDB, con varias conexiones con nombre.

Configuración

DB_CONEXIONES=principal,pagos              # la primera es la de por defecto
DB_PRINCIPAL_MOTOR=postgres                # postgres | mysql | mariadb | sqlserver | mongodb
DB_PRINCIPAL_HOST=localhost
DB_PRINCIPAL_PUERTO=5432
DB_PRINCIPAL_BASE=tienda
DB_PRINCIPAL_USUARIO=qa_lectura
DB_PRINCIPAL_CLAVE=...
DB_PRINCIPAL_ESCRITURA=no                  # si = permite escribir con confirmación
DB_PRINCIPAL_PRODUCCION=no                 # si = nunca escribe

Steps para los tests

When envío un POST a "/usuarios" con el body: ...
And guardo el campo "id" de la respuesta como "idUsuario"
Then existe en la base de datos un registro en "usuarios" donde "id" es "{idUsuario}"
And el registro de "usuarios" donde "id" es "{idUsuario}" tiene:
  | campo  | valor  |
  | estado | ACTIVO |
  | baja   | (nulo) |
And la base de datos "pagos" tiene 1 registro en "movimientos" donde:
  | campo      | valor       |
  | usuario_id | {idUsuario} |

También: no existe en la base de datos …, consulto en la base de datos: (SQL, o JSON en MongoDB), la consulta devuelve N filas, el campo "x" de la consulta es "y" y guardo el campo "x" de la consulta como "var". Si el dato se guarda de forma asíncrona, los steps reintentan hasta DB_ESPERA_MS. Cada verificación deja en el reporte la consulta y las filas encontradas.

Sin agente

cd herramientas/k0lmena
npm run bd -- conexiones                                   # lista y prueba las conexiones
npm run bd -- esquema --tabla usuarios                     # columnas de una tabla
npm run bd -- existe --tabla usuarios --donde email=ana@test.com
npm run bd -- consultar --sql "SELECT id, estado FROM usuarios WHERE email = ?" --param ana@test.com

Pruebas exploratorias

El explorador-web recorre tu sitio (el APP_URL del .env o la URL que le digas) y busca lo que se rompe sin que nadie lo note. Primero un recorrido automático con un script, sin gastar tokens por página; después explora a mano con Playwright MCP lo que necesita criterio.

npm run explorar -- --url https://staging.mi-app.com --max-paginas 50 # sin agentes ni tokens
npm run explorar -- --resoluciones 360x740,768x1024,1366x768 --video no

Accesibilidad

El analista-accesibilidad audita tu sitio contra WCAG 2.2 (nivel AA por defecto): primero una auditoría automática, sin gastar tokens por página, y después una revisión manual de lo que una herramienta no puede juzgar.

npm run accesibilidad -- --url https://staging.mi-app.com --nivel AA # sin agentes ni tokens
npm run accesibilidad -- --paginas https://mi-app.com/registro,https://mi-app.com/login --historia HU-001

Rendimiento web

El auditor-rendimiento-web mide qué tan rápido carga cada página para una persona y por qué, con Lighthouse en mobile y desktop. No es una prueba de carga con muchos usuarios: eso es el performance-mapper.

npm run rendimiento -- --url https://staging.mi-app.com --max-paginas 5 # sin agentes ni tokens
npm run rendimiento -- --paginas https://mi-app.com/,https://mi-app.com/login --repeticiones 3

Análisis de fallos

Cuando npm test falla, el analista-fallos separa los bugs reales de los tests rotos, inestables, de datos o de ambiente, para no revisar falla por falla.

python scripts/analizar_fallos.py                       # la última corrida de npm test
python scripts/analizar_fallos.py --agregar-reintento   # después de volver a correr los fallidos

Logs del servidor

El analista-logs lee los logs de la aplicación y los cruza con la corrida de npm test: qué errores hubo, cuándo, y qué error del servidor había detrás de cada escenario que falló.

python scripts/analizar_logs.py --logs "input/logs/*.log" --corrida web
python scripts/analizar_logs.py --logs input/logs/app.log --desde 2026-10-11T10:00 --hasta 2026-10-11T11:00

Cobertura y trazabilidad

El analista-cobertura responde “¿qué nos falta probar?”: cruza criterios, casos, automatización, gestión, resultados y bugs de cada historia y marca dónde se corta la cadena.

python scripts/analizar_cobertura.py --historia HU-001
python scripts/analizar_cobertura.py                    # todas las historias del repo

Regresión visual (pixel perfect)

El pixel-perfect detecta qué cambió visualmente entre la versión aceptada de tu sitio (la referencia) y la actual: qué se corrió y cuántos píxeles, qué cambió de tamaño, de texto o de color, qué falta y qué apareció.

npm run pixel-perfect -- --url https://staging.tu-app.com --resoluciones 390x844,1366x768 # sin agentes ni tokens
npm run pixel-perfect -- --ocultar ".banner,.fecha"     # zonas que cambian solas
npm run pixel-perfect -- --aceptar todas                # lo actual pasa a ser la referencia (con tu ok)

Cross-browser

El cross-browser encuentra lo que funciona o se ve distinto según el navegador: Chromium (Chrome y Edge), Firefox y WebKit (el motor de Safari), en desktop y mobile.

npm run cross-browser -- --historia HU-003                              # modo suite (corre contra el ambiente: con tu ok)
npm run cross-browser -- --modo paginas --url https://staging.tu-app.com # solo GET
cd herramientas/k0lmena && npx playwright install firefox webkit        # si faltan los navegadores

Reparación de la automatización

Cuando un test falla porque la pantalla cambió (un botón con otro nombre, un selector que ahora encuentra varios elementos), el reparador-automatizacion propone el locator nuevo, lo aplica y verifica que el test vuelva a pasar. Si falla porque la aplicación tiene un bug, no toca el test.

npm run reparar -- --historia HU-001                    # diagnóstico y propuestas
npm run reparar -- --aplicar seguras --historia HU-001  # o --aplicar R-01,R-03
npm run reparar -- --verificar --historia HU-001        # vuelve a correr los reparados

Selección de casos para un cambio

El selector-casos-de-prueba responde “¿qué pruebo con este cambio?” sin correr toda la regresión: cruza lo que cambió con todos los casos y entrega una lista priorizada, explicada y lista para ejecutar.

python scripts/seleccionar_casos.py --nombre release-2.4 --git main..feature/pagos --repo ../mi-app
python scripts/seleccionar_casos.py --nombre pr-42 --historias HU-003 --presupuesto-min 60
TAGS="(@HU-003 and (@CP-001 or @CP-003))" npm test -- web   # el comando que arma el informe

Revisión de casos y tiempo estimado

El revisor-casos revisa casos que ya existen (manuales en Excel o escenarios BDD) antes de ejecutarlos, subirlos o automatizarlos, y calcula cuánto lleva ejecutarlos a mano.

python scripts/revisar_casos.py --historia HU-001
python scripts/revisar_casos.py --origen output/casos-de-prueba/manuales/casos-HU-001.xlsx,output/casos-de-prueba/bdd/HU-001-registro.feature
python scripts/estimacion.py output/casos-de-prueba/manuales/casos-HU-001.xlsx   # solo el tiempo

Cómo se calcula el tiempo estimado

Cada caso (manual o BDD) lleva el tiempo que tarda una persona que conoce la aplicación en ejecutarlo de punta a punta. Lo calcula scripts/estimacion.py y aparece en la planilla (columna Tiempo estimado (min) con el total), en el .md, en la herramienta de gestión, en la selección de casos y en esta revisión.

tiempo del caso = (preparación + Σ pasos + registro) × factor   # hacia arriba a 0,5 min, mínimo 1
tiempo del paso = acción + datos + verificación

Charters y sesiones exploratorias

El generador-charters planifica pruebas exploratorias por sesiones (session-based testing): cada charter dice qué explorar, con qué foco y heurísticas, con qué datos y en cuánto tiempo. Después arma el informe con lo que encontró cada sesión.

python scripts/generar_charters.py --nombre HU-003             # hojas de sesión
python scripts/generar_charters.py --nombre HU-003 --informe   # informe-sesiones.html desde sesiones/

Correos

El verificador-correos comprueba que los mails que manda tu aplicación (registro, confirmación, recuperar contraseña, pedidos, notificaciones) lleguen bien: a la persona correcta, con el contenido correcto y viéndose bien en los clientes de correo. Usa Mailpit, un buzón de prueba que atrapa los mails del ambiente de pruebas sin entregarlos a nadie.

docker compose -f herramientas/mailpit/docker-compose.yml up -d      # web y API en :8025, SMTP en :1025
npm run correos -- --para ana@test.com --espera input/correos/espera-HU-001.json
npm run correos -- --para ana@test.com --esperar 1 --timeout-s 90   # espera a que llegue

Then llega un correo a "ana@test.com" con el asunto "Confirmá tu cuenta"
And el correo contiene "Hola Ana"
And el correo no contiene "undefined"
When guardo el link del correo que contiene "/confirmar" como "linkConfirmacion"

Traducciones e idiomas

El analista-traductor recorre cada página en cada idioma (el primero es la referencia) y encuentra lo que falta traducir o se ve mal en otro idioma. Propone la traducción de lo que falta.

npm run traductor -- --url https://staging.tu-app.com --idiomas es-AR,en-US,pt-BR # sin agentes ni tokens
npm run traductor -- --url https://tu-app.com --url-idioma "https://tu-app.com/{idioma_corto}/"

Usabilidad

El evaluador-ux revisa qué confunde, frena o hace equivocar a la persona, con las 10 heurísticas de Nielsen: un recorrido automático por las páginas y uno manual por los flujos importantes.

npm run ux -- --url https://staging.tu-app.com   # sin agentes ni tokens
npm run ux -- --url https://tu-app.com/checkout --max-paginas 4 --resoluciones 1440x900,390x844

Formularios

El probador-formularios prueba las validaciones de cada campo de un formulario sin enviarlo: obligatorios, largos, formatos, límites y mensajes de error.

npm run formularios -- --url https://staging.tu-app.com/registro   # sin agentes ni tokens
npm run formularios -- --url https://staging.tu-app.com/registro --enviar-vacio   # solo con confirmación

Historial de corridas

Cada herramienta guarda sus últimas 5 corridas con su evidencia, así podés comparar antes y después de un arreglo sin perder nada.

Seguridad web

El analista-seguridad revisa la seguridad de tu aplicación con OWASP ZAP (libre y gratuito) en modo pasivo: recorre el sitio y analiza las respuestas sin enviar ataques ni modificar datos.

python herramientas/zap/escanear.py --url https://staging.mi-app.com --historia HU-001

Salida en output/seguridad/<HU o host>/<fecha>/. Detalle en herramientas/zap/README.md.

Conectores MCP

Conectan a Claude Code con sistemas externos. Claude Code arranca directo: vienen activos Playwright y Atlassian, y cada QA activa el resto con npm run conector. Sin secretos: las credenciales se leen del .env. Vienen activos Playwright y Atlassian (Jira y Confluence); el .env.example trae un bloque comentado por herramienta para completar solo los de tu equipo.

1. Completá el .envSi usa token, cargalo en el .env de la raíz. Atlassian y Figma se autorizan con tu cuenta desde /mcp.
2. Activalonpm run conector -- activar azure-devops (queda solo para vos; npm run conector lista los disponibles).
3. VerificáReiniciá Claude Code y revisá la conexión con /mcp.

Para Xray no hace falta MCP: se usa scripts/gestion/. Guía completa en CONECTORES.md.

Convenciones

Tags en k0lmena

Nombres de archivos

Estructura del repositorio

k0lmenIA/
├── CLAUDE.md               Contexto y estándares (Claude Code lo lee siempre)
├── ARQUITECTURA.md         Cómo crece el repo
├── CONECTORES.md           Cómo activar los conectores MCP
├── CHANGELOG.md            Cambios de cada versión
├── LICENSE                 Licencia MIT
├── .env.example            Plantilla de variables (copiar a .env)
├── .mcp.json               Conectores MCP (sin secretos; activos según settings)
├── package.json            Atajos para correr k0lmena desde la raíz (npm test…)
├── docs/                   Este sitio, el PDF y los diagramas
├── tests/                  Tests de los scripts (pytest y node --test)
├── .github/workflows/      CI: los tests en Ubuntu y Windows
├── .claude/
│   ├── agents/             Los 35 agentes
│   ├── skills/             Contexto, diseño, guía de performance, ejecución, k0lmena
│   └── settings.json       Conectores habilitados y permisos
├── input/                  historias/ documentacion/ api/ bugs/ correos/ logs/
├── output/                 Lo que generan los agentes
├── plantillas/             Bug, planilla de casos, cobertura, tiempo estimado
├── scripts/                Casos, tiempo estimado, revisión, charters, logs, informes y doctor
│   ├── gestion/            Xray, QMetry (QTM4J), AIO Tests y casos para Azure DevOps
│   └── mcp/                Lanzadores de los conectores MCP (leen el .env)
└── herramientas/
    ├── newman/             Colecciones de Postman
    ├── zap/                OWASP ZAP: seguridad web (pasivo)
    ├── mailpit/            Mailpit: buzón de prueba para los correos
    └── k0lmena/
        ├── web/            features/ steps/ locators/ + framework
        ├── api/            features/ steps/ (steps genéricos)
        ├── mobile/         features/ steps/ locators/ support/ apps/
        ├── performance/    k6/http/, artillery/ y jmeter/
        ├── reports/        Reportes HTML
        ├── run-tests.js    Runner de npm test
        └── run-perf.js     Runner de npm run perf

Problemas frecuentes

Extender el proyecto

Agregar un agente

1. Creá el archivo.claude/agents/mi-agente.md con frontmatter name y description. La descripción es lo que usa Claude Code para decidir cuándo invocarlo.
2. Escribí el cuerpoEn español: rol, entradas, proceso, salida y reglas.
3. Definí el formatoSi genera un formato propio, sumá su plantilla en plantillas/ o su script en scripts/, y su carpeta en output/.
4. Normalizá las tablasSi genera tablas en un .md, pasalas por scripts/formatear_tablas.py.
5. Si necesita una respuesta de la personaCopiá la sección "Cuando te falta un dato o una confirmación" de cualquier agente: los subagentes no pueden preguntar a mitad del trabajo, así que devuelven "Necesito que confirmes".

Skills, conectores y herramientas

Regenerar esta documentación

node docs/generar.js        # diagramas (PNG) y PDF, con el Playwright de k0lmena

El sitio es docs/index.html (publicado con GitHub Pages en underc0delabs.github.io/k0lmenIA); el PDF sale del mismo HTML con estilos de impresión, y los diagramas de docs/diagramas/.

Licencia

Licencia MIT — © 2026 QARMY. k0lmena es un proyecto open source de Danilo Vezzoni. Hecho por la comunidad de Underc0de.