Documentación de K0lmenIA

Agentes de QA para Claude Code: diseño de pruebas, automatización con k0lmena e integración con Xray, QMetry, AIO Tests y Azure DevOps.

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, 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.

Arquitectura

Cómo se usa

1. Poné tus insumos en input/, o pasá una key de Jira, una página de Confluence o un link de Figma con el conector activo.
2. Pedí en lenguaje natural. Claude Code elige el agente; también podés nombrarlo.
3. Revisá el resultado en output/ o en herramientas/k0lmena/.
4. Automatizá lo que se repite y corrélo con npm test todas las veces que quieras, sin tokens.

Ver el catálogo de los 28 agentes

Requisitos

Instalá solo lo que vayas a usar.

Instalación

1. Instalá Claude Code

curl -fsSL https://claude.ai/install.sh | bash    # macOS / Linux
npm install -g @anthropic-ai/claude-code          # alternativa
claude --version

En Windows, seguí la guía oficial.

2. Cloná el repositorio

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

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               # Postman
cd herramientas/k0lmena
npx playwright install chromium     # + firefox webkit (cross-browser)
npm run bootstrap:k6                # k6
npm run bootstrap:jmeter            # 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.

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: descripción y criterios en Jira, todos los comentarios, subtareas, épica, issues vinculados, Confluence, Figma, contratos y la carpeta input/. El resultado es una ficha de contexto reutilizable en output/contexto/.

Cada dato que no aparece en ninguna fuente recibe un ID (FI-01) con qué falta, dónde se buscó, a qué afecta y la pregunta para el PO. El mismo ID viaja a la planilla de casos, los .feature (tags @falta-info @FI-01), los reportes y el informe de cierre. La aplicación nunca se usa como fuente de requisitos.

Automatización con k0lmena

El framework viene 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.

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
npm run report:web             # también: report:api · report:mobile

Si un paso no se puede ejecutar, el escenario queda @bloqueado con el motivo y no corre hasta que se resuelva.

Performance

El performance-mapper arma pruebas de carga, estrés, soak y picos. Nunca usa valores por defecto: te guía paso a paso para definir objetivo, herramienta, ambiente, usuarios, rampa, duración y umbrales, y pide confirmación antes de cada corrida con carga.

npm run perf                             # lista los scripts
npm run perf -- <script> smoke           # valida con carga mínima
npm run perf -- <script> load            # carga objetivo (pide confirmación)
npm run perf -- <script> stress --confirmar

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. Se configura en el .env con GESTION_HERRAMIENTA (xray-cloud, xray-dc, qtm4j o aio) y GESTION_PROYECTO.

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 publicar-resultados --ciclo PROJ-60 --resultados <resultados.json> --traza HU-001

Azure DevOps Test Plans se integra por su conector MCP oficial con ADO_ORGANIZACION, ADO_PAT y ADO_PROYECTO: los agentes leen historias y Wiki, y crean Test Cases vinculados a una suite.

Verificación en base de datos

El verificador-datos revisa qué quedó guardado, en qué estado y con qué valores, en PostgreSQL, MySQL / MariaDB, SQL Server y MongoDB, con varias conexiones con nombre. Es de solo lectura por defecto, enmascara datos sensibles y para escribir requiere habilitarlo y confirmar cada operación.

DB_CONEXIONES=principal,pagos
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_ESCRITURA=no
DB_PRINCIPAL_PRODUCCION=no

Calidad web: exploratorias, accesibilidad, rendimiento, visual, cross-browser y seguridad

Conectores MCP

npm run conector                          # lista los disponibles
npm run conector -- activar azure-devops  # activa uno (solo para vos)

Después reiniciá Claude Code y verificá la conexión con /mcp.

Convenciones

Problemas frecuentes

No sé qué me falta instalar

Corré npm run doctor: revisa Python, Node, k0lmena, Playwright, Newman, Java, Docker, el .env y los conectores, y dice cómo resolver lo que falta.

Un agente devuelve "Necesito que confirmes"

Es a propósito: los subagentes no pueden preguntar a mitad del trabajo. Respondé y Claude continúa con el mismo agente.

npm test corre 0 escenarios

Todavía no automatizaste nada (las carpetas vienen vacías) o el filtro TAGS no coincide con ningún escenario.

Un conector MCP no conecta

Las variables tienen que estar en el entorno donde lanzás claude. Atlassian y Figma se autorizan desde /mcp.

Ver todos los problemas frecuentes en la documentación completa

Extender el proyecto

• Agente: un archivo .claude/agents/mi-agente.md con name y description; la descripción es lo que usa Claude Code para decidir cuándo invocarlo.
• Skill: una carpeta en .claude/skills/ con su SKILL.md.
• Conector MCP: una entrada en .mcp.json, sin secretos.
• Herramienta: una subcarpeta en herramientas/ con su README.

Licencia

K0lmenIA es open source con licencia MIT. Hecho por la comunidad de QARMY y Underc0de.