Usar codqual con agentes de IA

La superficie de agente de codqual es su API REST — no hay ningún cliente que instalar. Cualquier agente de programación que pueda ejecutar curl (Claude Code, Cursor, Codex, etc.) puede leer los hallazgos de codqual y actuar sobre ellos.

Sáltate la lectura — tu agente puede hacerlo

Pega este prompt en tu agente y recorrerá contigo la guía rápida de abajo:

Quiero añadir codqual (revisión de código con IA) a este proyecto. Lee https://codqual.com/docs/agents y ayúdame a configurarlo paso a paso: la cuenta, los repositorios, la skill, la clave de API y una primera comprobación de que funciona. Pídeme lo que necesites.

Inicio rápido

1. Instala la skill

Un único SKILL.md portátil funciona en Claude Code, Cursor, Windsurf y Codex CLI — descárgalo en el directorio de skills de tu herramienta. Solo necesitas hacerlo una vez: el skill lleva una versión y la compara con codqual.com al inicio de cada sesión, reemplazando su propia copia cuando hay una más reciente.

# Claude Code
mkdir -p ~/.claude/skills/codqual && curl -fsSo ~/.claude/skills/codqual/SKILL.md https://codqual.com/SKILL.md
# Cursor
mkdir -p ~/.cursor/skills/codqual && curl -fsSo ~/.cursor/skills/codqual/SKILL.md https://codqual.com/SKILL.md
# Codex CLI
mkdir -p ~/.codex/skills/codqual && curl -fsSo ~/.codex/skills/codqual/SKILL.md https://codqual.com/SKILL.md
# Windsurf
mkdir -p ~/.codeium/windsurf/skills/codqual && curl -fsSo ~/.codeium/windsurf/skills/codqual/SKILL.md https://codqual.com/SKILL.md

2. Crea una API key

Las cuentas nuevas reciben una key al registrarse (se muestra una sola vez). Crea más cuando quieras en el dashboard, en Settings → API Keys. La skill verifica CODQUAL_API_KEY en el primer uso y te guía para añadirla a tu perfil de shell — nunca pegas la key en el chat del agente.

3. Primera petición

Pide a tu agente algo como "corrige los issues abiertos de codqual en este repo", o verifica el acceso directamente:

curl -fsS -H "Authorization: Bearer $CODQUAL_API_KEY" "https://api.codqual.com/issues?status=open"

Endpoint MCP

Los agentes que hablan el Model Context Protocol pueden saltarse curl por completo: codqual es un servidor MCP en https://api.codqual.com/mcp (HTTP transmisible, sin estado), autenticado con la misma clave de API como token Bearer. Expone la superficie de lectura como siete herramientas — list_issues, get_issue_timeline, list_reviews, get_review, get_maturity, get_repo_memory, get_quota — de solo lectura como todo uso de una clave de API: un agente puede leer resultados y actuar sobre ellos, nunca disparar un análisis.

# Claude Code
claude mcp add --transport http codqual https://api.codqual.com/mcp --header "Authorization: Bearer $CODQUAL_API_KEY"

En cualquier otro cliente MCP, configura un servidor HTTP (transmisible) con la url https://api.codqual.com/mcp y una cabecera Authorization: Bearer con tu clave.

Cerrando el ciclo desde el PR

Tras corregir un hallazgo, el agente responde sobre el propio comentario de codqual en el PR — con el gh del usuario, nunca con credenciales de codqual:

responde /codqual addressed (y reacciona con 👍) cuando el hallazgo era correcto y ya está corregido;
responde /codqual dispute <razón> (y reacciona con 👎) cuando es un falso positivo — codqual lo registra como señal de aprendizaje para revisión humana, nunca lo descarta en silencio;
la supresión sigue siendo humana: un maintainer del repo responde /codqual ignore false-positive (o intentional) para que un hallazgo deje de reaparecer.

Documentación legible por máquinas

Dale a tu agente https://codqual.com/llms.txt (un índice de esta documentación), https://codqual.com/llms-full.txt (todo en un solo archivo), o el gemelo en markdown de cualquier página — por ejemplo https://codqual.com/docs/api.md.

Contrato de la API (OpenAPI)

Toda la superficie de lectura de la API — issues y sus historiales, revisiones, escaneos, repositorios, madurez y el rubric público — está descrita por una especificación OpenAPI 3.1 en https://api.codqual.com/openapi.json — validada en CI contra el código real de las rutas, en ambos sentidos: una ruta documentada debe existir, y una ruta legible debe estar documentada.