Cross-Review Project

Dos instancias de Claude Code revisan los proyectos de la otra a través del intercambio estructurado de artefactos vía el broker cross-review-mcp. El broker hace cumplir las leyes de escalado Quantized Simplex Gossip (QSG) — los bundles de revisión deben contener al menos 5 hallazgos para mantenerse en el régimen de selección (Γ_h ≈ 1.67), evitando que el consenso superficial pase como acuerdo.

Cuándo Usar

• Dos proyectos comparten preocupaciones arquitectónicas y podrían aprender el uno del otro
• Quieres una revisión de código independiente que vaya más allá de lo que ve un solo revisor
• La polinización cruzada es el objetivo: encontrar patrones en un proyecto que faltan en el otro
• Necesitas una revisión estructurada respaldada por evidencia con veredictos accept/reject/discuss

Entradas

• Requerido: Dos rutas de proyecto accesibles a dos instancias de Claude Code
• Requerido: Broker cross-review-mcp ejecutándose y configurado como servidor MCP en ambas instancias
• Opcional: Áreas de enfoque — directorios, patrones o preocupaciones específicas a priorizar
• Opcional: IDs de agente — identificadores para cada instancia (predeterminado: nombre del directorio del proyecto)

Procedimiento

Paso 1: Verificar Prerrequisitos

Confirmar que el broker está ejecutándose y ambas instancias pueden alcanzarlo.

1. Verificar que el broker está configurado como servidor MCP:

   claude mcp list | grep cross-review
   

2. Llamar get_status para verificar que el broker responde y no hay agentes obsoletos registrados
3. Leer el recurso de protocolo en cross-review://protocol — este es un documento markdown que describe las dimensiones de revisión y las restricciones QSG

Esperado: El broker responde a get_status con una lista de agentes vacía. El recurso de protocolo es legible como markdown.

En caso de fallo: Si el broker no está configurado, añadirlo: claude mcp add cross-review-mcp -- npx cross-review-mcp. Si existen agentes obsoletos de una sesión anterior, llamar deregister para cada uno antes de proceder.

Paso 2: Registrar

Registrar este agente con el broker.

1. Llamar register con:
   • agentId: un identificador corto y único (p. ej., nombre del directorio del proyecto)
   • project: el nombre del proyecto
   • capabilities: ["review", "suggest"]
2. Verificar el registro llamando get_status — tu agente debe aparecer con fase "registered"
3. Esperar a que el agente par se registre: llamar wait_for_phase con el ID del agente par y la fase "registered"

Esperado: Ambos agentes registrados con el broker. get_status muestra 2 agentes en fase "registered".

En caso de fallo: Si register falla con "already registered", el ID de agente está tomado de una sesión anterior. Llamar deregister primero, luego re-registrar.

Paso 3: Fase de Briefing

Leer tu propia base de código y enviar un briefing estructurado al par.

1. Leer sistemáticamente:
   • Puntos de entrada (archivos main, index, comandos CLI)
   • Grafo de dependencias (package.json, DESCRIPTION, go.mod)
   • Patrones arquitectónicos (estructura de directorios, límites de módulos)
   • Problemas conocidos (comentarios TODO, issues abiertos, deuda técnica)
   • Cobertura de pruebas (directorios de pruebas, configuración CI)
2. Componer un artefacto Briefing — un resumen estructurado que el par puede usar para navegar tu base de código eficientemente
3. Llamar send_task con:
   • from: tu ID de agente
   • to: ID de agente par
   • type: "briefing"
   • payload: briefing codificado en JSON
4. Llamar signal_phase con fase "briefing"

Esperado: Briefing enviado y fase señalizada. El broker hace cumplir que debes enviar un briefing antes de avanzar a la revisión.

En caso de fallo: Si send_task rechaza el briefing, verificar que el campo from coincida con tu ID de agente registrado. Los auto-envíos son rechazados.

Paso 4: Fase de Revisión

Esperar el briefing del par, luego revisar su código y enviar hallazgos.

1. Llamar wait_for_phase con el ID del par y fase "briefing"
2. Llamar poll_tasks para recuperar el briefing del par
3. Llamar ack_tasks con los IDs de tarea recibidos — esto es requerido (patrón peek-then-ack)
4. Leer el código fuente real del par, informado por su briefing
5. Producir hallazgos en 6 categorías:
   • pattern_transfer — un patrón en tu proyecto que el par podría adoptar
   • missing_practice — una práctica que le falta al par (testing, validación, manejo de errores)
   • inconsistency — contradicción interna dentro de la base de código del par
   • simplification — complejidad innecesaria que podría reducirse
   • bug_risk — fallo potencial en runtime o caso límite
   • documentation_gap — documentación faltante o engañosa
6. Cada hallazgo debe incluir:
   • id: identificador único (p. ej., "F-001")
   • category: una de las 6 categorías de arriba
   • targetFile: ruta en el proyecto del par
   • description: lo que encontraste
   • evidence: por qué este es un hallazgo válido (referencias de código, patrones)
   • sourceAnalog (recomendado): el equivalente en tu propio proyecto que demuestra el patrón — este es el único mecanismo para una polinización cruzada genuina
7. Empaquetar al menos 5 hallazgos (restricción QSG: m ≥ 5 mantiene Γ_h ≈ 1.67 en régimen de selección)
8. Llamar send_task con tipo "review_bundle" y el array de hallazgos codificado en JSON
9. Llamar signal_phase con fase "review"

Esperado: Bundle de revisión aceptado por el broker. Menos de 5 hallazgos serán rechazados.

En caso de fallo: Si el bundle es rechazado por hallazgos insuficientes, revisar más a fondo. La restricción existe para evitar que las revisiones superficiales dominen. Si genuinamente no puedes encontrar 5 problemas, reconsiderar si la cross-review es la herramienta correcta para este par de proyectos.

Paso 5: Fase de Diálogo

Recibir hallazgos sobre tu propio proyecto y responder con veredictos respaldados por evidencia.

1. Llamar wait_for_phase con el ID del par y fase "review"
2. Llamar poll_tasks para recuperar hallazgos sobre tu proyecto
3. Llamar ack_tasks con los IDs de tarea recibidos
4. Para cada hallazgo, producir un FindingResponse:
   • findingId: coincide con el ID del hallazgo
   • verdict: "accept" (válido, actuarás sobre él), "reject" (inválido, con contra-evidencia), o "discuss" (necesita aclaración)
   • evidence: por qué aceptas o rechazas — debe ser no-vacío
   • counterEvidence (opcional): referencias de código específicas que contradicen el hallazgo
5. Enviar todas las respuestas vía send_task con tipo "response"
6. Llamar signal_phase con fase "dialogue"

Nota: el veredicto "discuss" no está controlado por el protocolo — tratarlo como una bandera para seguimiento manual, no un sub-intercambio automatizado.

Esperado: Todos los hallazgos respondidos con veredictos. Las respuestas vacías son rechazadas por el broker.

En caso de fallo: Si no puedes formar una opinión sobre un hallazgo, por defecto a "discuss" con evidencia explicando qué contexto adicional necesitas.

Paso 6: Fase de Síntesis

Producir un artefacto de síntesis resumiendo los hallazgos aceptados y las acciones planificadas.

1. Llamar wait_for_phase con el ID del par y fase "dialogue"
2. Hacer poll de cualquier tarea restante y reconocerlas
3. Compilar un artefacto Synthesis:
   • Hallazgos aceptados con acciones planificadas (qué cambiarás y por qué)
   • Hallazgos rechazados con razones (preserva el razonamiento para futura revisión)
4. Llamar send_task con tipo "synthesis" y la síntesis codificada en JSON
5. Llamar signal_phase con fase "synthesis"
6. Opcionalmente crear issues de GitHub para hallazgos aceptados
7. Llamar signal_phase con fase "complete"
8. Llamar deregister para limpiar

Esperado: Ambos agentes alcanzan "complete". El broker requiere al menos 2 agentes registrados para avanzar a complete.

En caso de fallo: Si el par ya se ha desregistrado, aún puedes completar localmente. Compilar tu síntesis a partir de los hallazgos que recibiste.

Validación

• Ambos agentes registrados y alcanzaron la fase "complete"
• Briefings intercambiados antes de que comenzaran las revisiones (cumplimiento de fase)
• Los bundles de revisión contenían al menos 5 hallazgos cada uno
• Todos los hallazgos recibieron un veredicto (accept/reject/discuss) con evidencia
• ack_tasks llamado después de cada poll_tasks
• Síntesis producida con hallazgos aceptados mapeados a acciones
• Agentes desregistrados después de completar

Errores Comunes

• Menos de 5 hallazgos: El broker rechaza bundles con m < 5. Esto no es arbitrario — con N=2 agentes y 6 categorías, m < 5 pone a Γ_h en o por debajo del límite crítico donde el consenso es indistinguible del ruido. Revisar más a fondo; si 5 hallazgos genuinamente no pueden encontrarse, los proyectos pueden no beneficiarse de cross-review.
• Olvidar ack_tasks: El broker usa entrega peek-then-ack. Las tareas permanecen en cola hasta ser reconocidas. Olvidar hacer ack causa procesamiento duplicado en el siguiente poll.
• Olvidar el parámetro from: send_task requiere un campo from explícito que coincida con tu ID de agente. Los auto-envíos son rechazados.
• Correlación epistémica del mismo modelo: Dos instancias de Claude comparten sesgos de entrenamiento. El ordenamiento temporal asegura que no leen la salida de la otra durante la revisión, pero sus priors están correlacionados. Para independencia epistémica genuina, usar diferentes familias de modelos entre instancias.
• Saltar sourceAnalog: El campo sourceAnalog es opcional pero es el único mecanismo para una polinización cruzada genuina — muestra tu implementación del patrón que estás recomendando. Siempre poblarlo cuando exista un análogo de origen.
• Tratar discuss como bloqueante: Nada en el protocolo controla complete en discusiones pendientes que estén resolviéndose. Tratar veredictos discuss como banderas para seguimiento manual después de la sesión.
• No revisar la telemetría: El broker registra todos los eventos a JSONL. Después de una sesión, revisar el log para validar las suposiciones QSG — estimar α empíricamente (α ≈ 1 - reject_rate) y verificar las tasas de aceptación por categoría.

Habilidades Relacionadas

• scaffold-mcp-server — para construir o extender el broker mismo
• implement-a2a-server — patrones del protocolo A2A de los que el broker se nutre
• review-codebase — revisión de un solo agente (esta habilidad la extiende a intercambio estructurado entre agentes)
• build-consensus — patrones de consenso de enjambre (QSG es la base teórica)
• configure-mcp-server — configurar el broker como servidor MCP en Claude Code
• unleash-the-agents — puede usarse para analizar el broker mismo (probado en batalla: 40 agentes, 10 familias de hipótesis)