Katas Headless Code Review

Qué es

Claude Code corre en CI sin TTY (claude -p) y produce JSON estructurado con anotaciones por línea (file,line,severity,rule_id,message). El pipeline valida la salida contra un schema declarado y publica comentarios deterministas en el PR. Cero parsing de prosa libre: el modelo anota, el pipeline valida, el humano decide el merge.

Por qué importa (falla que evita)

Un reviewer humano no escala a 100 PRs/día. Un reviewer LLM en CI encuentra issues consistentes, pero solo si su salida es estructurada. Si se parsea prosa con regex (grep -E 'ERROR|WARNING'), el pipeline rompe el primer día que el modelo cambie de redacción o de idioma. La estructura no es cosmética: es la única forma de que la integración sobreviva a la variabilidad del modelo.

Modelo mental

• claude -p 'prompt' --output-format=json produce JSON validable contra un schema declarado, no prosa para humanos.
• El schema es una lista de Annotation: {file, line, severity, rule_id, message}.
• Si la salida no valida contra el schema, el job falla — no se "ajusta" el parser ni se publican comentarios parciales.
• El humano sigue siendo el gate final de merge: el LLM anota, no aprueba. Puede tener falsos positivos y falsos negativos y no asume responsabilidad legal del merge.
• Combina tres katas: extracción defensiva con schema (Kata 5), control por señal de salida (Kata 1) y el flag --output-format=json.

Patrón correcto

# .github/workflows/review.yml
# workspace-example: the consuming repository supplies annotations.schema.json
# and scripts/post_annotations.py; they are not toolkit package resources.
- name: LLM review
  run: |
    claude -p "$REVIEW_PROMPT" \
      --output-format=json \
      --schema annotations.schema.json > out.json
    python scripts/post_annotations.py out.json

The workspace-example script workspace-example:scripts/post_annotations.py validates out.json against the consuming repository's annotations.schema.json before publishing. If validation fails, it exits nonzero and the job fails. Neither example path is claimed as a resource shipped by this skill.

Anti-patrón

claude -p "$REVIEW_PROMPT" > review.txt
grep -E 'ERROR|WARNING|issue' review.txt | awk '{...}' | xargs gh pr comment

Parsea prosa libre con grep/awk: se rompe en cuanto el modelo cambie de redacción, idioma o formato. No hay contrato, solo heurística frágil.

Argumento de certificación

El flag --output-format=json fuerza salida estructurada; la validación contra schema declarado es extracción defensiva (Kata 5); el control por señal de salida (Kata 1) decide éxito o fallo del job sin parsear prosa. Si el JSON no valida, el job falla y ningún comentario se publica: un humano investiga. El humano sigue siendo el gate final de merge porque el LLM puede tener FP/FN y no asume responsabilidad del merge.

Cuándo activar

• Se pide correr code review automatizado en CI/CD con claude -p.
• Se necesita salida estructurada (JSON) validada contra schema para publicar anotaciones en un PR.
• Se quiere reemplazar parsing de prosa por un contrato declarado y determinista.
• NO activar para code review interactivo en local sin pipeline, ni cuando el objetivo es aprobar/mergear automáticamente sin humano.

Skills relacionadas

• katas-defensive-structured-extraction
• katas-mcp-structured-errors
• katas-human-handoff-protocol

Packet

Capas del packet, cargables bajo demanda (disciplina ICM: una capa por vez, nunca todas juntas): knowledge/ cuerpo de conocimiento · prompts/ prompts listos · examples/ salida de ejemplo · agents/ subagentes del packet · templates/ plantilla de output.