Estudio de caso: Arquitectura de un bot de revisión de código y un pipeline de procesamiento de documentos

Esta lista de verificación recorre la arquitectura de dos compilaciones de producción ilustrativas: un bot automatizado de revisión de código que comenta las solicitudes de extracción (pull requests) y un pipeline de procesamiento de documentos que clasifica y extrae datos estructurados de los archivos entrantes.

Ambas son arquitecturas de ejemplo realistas destinadas a sintetizar los dominios del examen CCA Foundations, no estudios de caso publicados reales de Anthropic, y los detalles a continuación son ilustrativos en lugar de números de producción medidos.

Se presentan juntas porque comparten un tema arquitectónico que vale la pena interiorizar para el examen: limitar la superficie de salida del modelo lo suficiente como para que un error sea barato y fácil de detectar, ya sea que el error sea un mal comentario de código o un documento mal clasificado.

Cómo usar esta lista de verificación

Trate las dos compilaciones como estudios de caso paralelos; trabaje completamente en una antes de comenzar la otra, ya que intercalarlas puede difuminar qué decisión pertenece a qué sistema.
Preste atención a dónde dibuja cada sistema su "límite de confianza" (trust boundary), el punto más allá del cual un humano, no el modelo, toma la decisión final.
Utilice los pasos numerados como plantilla para diseñar un sistema similar propio, no solo como hechos para memorizar.

Bot de revisión de código: Pasos de arquitectura (1-8)

Defina el desencadenador. El bot se ejecuta en los eventos de creación y actualización de solicitudes de extracción (pull requests), no en cada commit, para evitar comentar envíos en progreso (work-in-progress).
Recupere solo el diff, no el repositorio completo. Extraer la base de código completa en contexto para cada revisión desperdicia tokens y diluye la relevancia; limite la entrada a los archivos modificados y a una pequeña ventana de contexto circundante.
Defina la herramienta de comentarios de forma restrictiva. Una única herramienta post_review_comment que acepte file_path, line_number y comment_text mantiene la superficie de salida del bot limitada y auditable, en lugar de permitirle reescribir archivos libremente.
Separe la severidad del contenido. Exija al modelo que etiquete cada comentario con una severidad (blocking, suggestion, nitpick) como un campo estructurado, no incrustado en prosa, para que las herramientas posteriores puedan filtrarlo o controlarlo.
Establezca un presupuesto de comentarios por solicitud de extracción. Limite el número de comentarios que el bot publica por PR (por ejemplo, 15) para evitar la fatiga de revisión por un pase demasiado hablador sobre un diff grande.
Exija al bot que explique su razonamiento, no solo que lo afirme. Un comentario como "esto podría causar una condición de carrera porque X lee la variable antes de que se complete la escritura de Y" es revisable; "esto parece incorrecto" no lo es.
Controle los comentarios de bloqueo (blocking) detrás de un umbral de confianza. Solo los comentarios etiquetados como blocking deberían ser capaces de fallar una verificación de CI; la salida de menor confianza sigue siendo consultiva.
Registre cada ejecución de revisión con el par diff y salida. Almacene el diff que vio el bot junto con los comentarios que produjo, para que una revisión incorrecta o inútil sea depurable después del hecho.

Pipeline de procesamiento de documentos: Pasos de arquitectura (9-16)

Clasifique antes de extraer. Enrute cada documento entrante a través de un paso de clasificación ligero (factura, contrato, currículum, otro) antes de aplicar un prompt de extracción específico del tipo de documento.
Utilice un modelo más barato y rápido para la clasificación. Claude Haiku 4.5 es adecuado para la etapa de clasificación, ya que es una tarea limitada y de baja ambigüedad, reservando un modelo más potente para la extracción donde el matiz importa más.
Defina un esquema de salida estricto por tipo de documento. La extracción debe dirigirse a un esquema JSON fijo por tipo de documento (por ejemplo, factura: proveedor, monto, fecha de vencimiento), no a un resumen de texto libre, para que los sistemas posteriores puedan consumirlo de manera confiable.
Valide los campos extraídos contra tipos y rangos esperados. Una fecha de vencimiento que se analice como un año 300 años en el futuro, o un monto de cero en una factura, debería marcarse para revisión, no aceptarse silenciosamente.
Enrute las extracciones de baja confianza a una cola de revisión humana. En lugar de forzar cada documento a través de la automatización completa, defina un umbral de confianza o de fallo de validación por debajo del cual un humano confirme la extracción.
Mantenga el documento original vinculado a su extracción. Cada registro estructurado debe hacer referencia al archivo de origen del que se extrajo, para que un error posterior sea rastreable hasta el documento original.
Procese los documentos de forma asíncrona, no en línea con la carga. Desacople la ingesta de documentos (carga) del procesamiento (clasificar, extraer, validar) con una cola, para que un paso de procesamiento lento o fallido no bloquee la ruta de carga.
Rastree la precisión de la extracción por tipo de documento con el tiempo. Diferentes tipos de documentos tendrán diferentes perfiles de precisión; las métricas agregadas por sí solas pueden ocultar un tipo de documento con un rendimiento deficiente detrás de números generales sólidos.

Aplicación de la lista de verificación en orden

Bot de revisión de código, pasos 1-4: primero asegúrese de que el alcance y el diseño de la herramienta sean correctos; un bot con una herramienta de comentarios ilimitada es difícil de confiar independientemente de la calidad del prompt.
Bot de revisión de código, pasos 5-8: agregue presupuesto, control de confianza y registro una vez que el bucle principal funcione, ya que estos son los controles que hacen que el bot sea seguro para ejecutarlo sin supervisión.
Pipeline de documentos, pasos 9-12: la clasificación, la selección del modelo y la estrictez del esquema forman la columna vertebral del pipeline; asegúrese de que estos sean correctos antes de agregar automatización a su alrededor.
Pipeline de documentos, pasos 13-16: el enrutamiento de revisión humana, la trazabilidad y el procesamiento asíncrono son los controles operativos que hacen que el pipeline sea confiable a escala.

Preguntas frecuentes

¿Son estas dos compilaciones estudios de caso reales publicados por Anthropic?

No. Ambas son arquitecturas de ejemplo ilustrativas creadas para sintetizar los dominios del examen CCA Foundations, no estudios de caso publicados reales de Anthropic; los detalles son realistas pero construidos con fines de enseñanza.

¿Por qué el bot de revisión de código recupera solo el diff, no el repositorio completo?

Extraer la base de código completa en contexto para cada revisión desperdicia tokens y diluye la relevancia del cambio real; limitar el contexto a la diferencia más una pequeña ventana circundante mantiene el contexto enfocado y el costo proporcional al tamaño del cambio.

¿Por qué limitar el número de comentarios por solicitud de extracción?

Un bot sin límites puede producir fatiga de revisión al publicar una cantidad abrumadora de comentarios de bajo valor en un diff grande; un presupuesto obliga al bot a priorizar la retroalimentación de mayor valor.

¿Cuál es el propósito de etiquetar los comentarios con severidad como un campo estructurado?

Un campo de severidad estructurado (bloqueante, sugerencia, nitpick) permite que las herramientas posteriores lo filtren o controlen programáticamente, lo cual no se puede lograr de manera confiable con el lenguaje de severidad de texto libre incrustado en un comentario.

¿Por qué usar Claude Haiku 4.5 para la clasificación de documentos pero no para la extracción?

La clasificación es una tarea limitada y de relativa baja ambigüedad, bien adaptada a un modelo más rápido y económico, mientras que la extracción a menudo implica más matices (interpretar diversos diseños y lenguajes de documentos) que se benefician de un modelo más potente.

¿Por qué validar los campos extraídos en lugar de confiar directamente en la salida estructurada del modelo?

Un modelo puede producir una salida sintácticamente válida pero semánticamente incorrecta, como una fecha de vencimiento muy lejana o un monto de factura de cero; la validación de los campos extraídos contra tipos y rangos esperados detecta estos problemas antes de que lleguen a los sistemas posteriores.

¿Por qué procesar documentos de forma asíncrona en lugar de en línea con la carga?

Desacoplar la carga del procesamiento con una cola significa que un paso de procesamiento lento o fallido no bloquea la ruta de carga visible para el usuario, lo cual es importante ya que la latencia de extracción puede variar mucho según la complejidad del documento.

¿Qué debería suceder cuando la extracción de un documento tiene baja confianza?

Enrútelo a una cola de revisión humana en lugar de forzar la automatización completa en cada documento; definir un umbral de confianza o de fallo de validación es lo que hace que esa decisión de enrutamiento sea consistente en lugar de ad hoc.

¿Por qué los comentarios de revisión de código de bloqueo (blocking) deberían requerir un umbral de confianza?

Solo los comentarios de alta confianza deberían ser capaces de fallar una verificación de CI, ya que un falso positivo de bloqueo en un comentario de baja confianza erosiona la confianza del desarrollador en el bot y anima a las personas a ignorarlo o evitarlo.

¿Por qué mantener el documento original vinculado a su registro extraído?

La trazabilidad hasta el archivo de origen permite investigar un error posterior (como un monto incorrecto utilizado en un pago) en el documento original real, no solo en los datos extraídos.

¿Qué tienen en común estas dos estudios de caso arquitectónicamente?

Ambos limitan estrechamente la superficie de salida del modelo (una herramienta de comentarios restrictiva, un esquema de extracción estricto) para que los errores sean baratos y fáciles de detectar y corregir, en lugar de depender de que el modelo acierte siempre.

¿Por qué rastrear la precisión de la extracción por tipo de documento en lugar de solo en general?

Los números de precisión agregados pueden ocultar un tipo de documento con un rendimiento deficiente detrás de un rendimiento sólido en tipos más fáciles; el seguimiento por tipo expone problemas que las métricas generales ocultarían.

Relacionado

Estudio de la arquitectura de agentes y la orquestación: el dominio más grande del examen CCA - principios de orquestación detrás del enrutamiento de documentos a través de etapas de clasificación y extracción.
Diseño de herramientas, integración MCP y gestión de contexto: Lista de verificación del dominio CCA - la disciplina de alcance de herramientas detrás de la herramienta de comentarios del bot de revisión de código.
Estudio de caso: Un asistente de conocimiento interno con RAG y citas - otra compilación centrada en documentos, enfocada en la recuperación en lugar de la clasificación y extracción.
Estudio de caso Antes y Después: Refactorización de un agente Claude para reducir costos - cómo las opciones de selección de modelos como la división Haiku/Sonnet aquí afectan el costo a escala.
Mejores prácticas de CCA - prácticas de las que se derivan estas dos arquitecturas.

Versiones de la pila: Escrito contra la línea de modelos Claude actual hasta ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5 - y el SDK oficial de Python anthropic (última versión 0.x). Los nombres de los modelos, los precios, el formato del examen y las versiones del SDK cambian rápidamente; verifique los detalles actuales en platform.claude.com/docs y la guía oficial del examen CCA antes de confiar en ellos.

Estudio de caso: Arquitectura de un bot de revisión de código y un pipeline de procesamiento de documentos

Cómo usar esta lista de verificación

Trate las dos compilaciones como estudios de caso paralelos; trabaje completamente en una antes de comenzar la otra, ya que intercalarlas puede difuminar qué decisión pertenece a qué sistema.
Preste atención a dónde dibuja cada sistema su "límite de confianza" (trust boundary), el punto más allá del cual un humano, no el modelo, toma la decisión final.
Utilice los pasos numerados como plantilla para diseñar un sistema similar propio, no solo como hechos para memorizar.

Bot de revisión de código: Pasos de arquitectura (1-8)

Defina el desencadenador. El bot se ejecuta en los eventos de creación y actualización de solicitudes de extracción (pull requests), no en cada commit, para evitar comentar envíos en progreso (work-in-progress).
Recupere solo el diff, no el repositorio completo. Extraer la base de código completa en contexto para cada revisión desperdicia tokens y diluye la relevancia; limite la entrada a los archivos modificados y a una pequeña ventana de contexto circundante.
Defina la herramienta de comentarios de forma restrictiva. Una única herramienta post_review_comment que acepte file_path, line_number y comment_text mantiene la superficie de salida del bot limitada y auditable, en lugar de permitirle reescribir archivos libremente.
Separe la severidad del contenido. Exija al modelo que etiquete cada comentario con una severidad (blocking, suggestion, nitpick) como un campo estructurado, no incrustado en prosa, para que las herramientas posteriores puedan filtrarlo o controlarlo.
Establezca un presupuesto de comentarios por solicitud de extracción. Limite el número de comentarios que el bot publica por PR (por ejemplo, 15) para evitar la fatiga de revisión por un pase demasiado hablador sobre un diff grande.
Exija al bot que explique su razonamiento, no solo que lo afirme. Un comentario como "esto podría causar una condición de carrera porque X lee la variable antes de que se complete la escritura de Y" es revisable; "esto parece incorrecto" no lo es.
Controle los comentarios de bloqueo (blocking) detrás de un umbral de confianza. Solo los comentarios etiquetados como blocking deberían ser capaces de fallar una verificación de CI; la salida de menor confianza sigue siendo consultiva.
Registre cada ejecución de revisión con el par diff y salida. Almacene el diff que vio el bot junto con los comentarios que produjo, para que una revisión incorrecta o inútil sea depurable después del hecho.

Pipeline de procesamiento de documentos: Pasos de arquitectura (9-16)

Clasifique antes de extraer. Enrute cada documento entrante a través de un paso de clasificación ligero (factura, contrato, currículum, otro) antes de aplicar un prompt de extracción específico del tipo de documento.
Utilice un modelo más barato y rápido para la clasificación. Claude Haiku 4.5 es adecuado para la etapa de clasificación, ya que es una tarea limitada y de baja ambigüedad, reservando un modelo más potente para la extracción donde el matiz importa más.
Defina un esquema de salida estricto por tipo de documento. La extracción debe dirigirse a un esquema JSON fijo por tipo de documento (por ejemplo, factura: proveedor, monto, fecha de vencimiento), no a un resumen de texto libre, para que los sistemas posteriores puedan consumirlo de manera confiable.
Valide los campos extraídos contra tipos y rangos esperados. Una fecha de vencimiento que se analice como un año 300 años en el futuro, o un monto de cero en una factura, debería marcarse para revisión, no aceptarse silenciosamente.
Enrute las extracciones de baja confianza a una cola de revisión humana. En lugar de forzar cada documento a través de la automatización completa, defina un umbral de confianza o de fallo de validación por debajo del cual un humano confirme la extracción.
Mantenga el documento original vinculado a su extracción. Cada registro estructurado debe hacer referencia al archivo de origen del que se extrajo, para que un error posterior sea rastreable hasta el documento original.
Procese los documentos de forma asíncrona, no en línea con la carga. Desacople la ingesta de documentos (carga) del procesamiento (clasificar, extraer, validar) con una cola, para que un paso de procesamiento lento o fallido no bloquee la ruta de carga.
Rastree la precisión de la extracción por tipo de documento con el tiempo. Diferentes tipos de documentos tendrán diferentes perfiles de precisión; las métricas agregadas por sí solas pueden ocultar un tipo de documento con un rendimiento deficiente detrás de números generales sólidos.

Aplicación de la lista de verificación en orden

Bot de revisión de código, pasos 1-4: primero asegúrese de que el alcance y el diseño de la herramienta sean correctos; un bot con una herramienta de comentarios ilimitada es difícil de confiar independientemente de la calidad del prompt.
Bot de revisión de código, pasos 5-8: agregue presupuesto, control de confianza y registro una vez que el bucle principal funcione, ya que estos son los controles que hacen que el bot sea seguro para ejecutarlo sin supervisión.
Pipeline de documentos, pasos 9-12: la clasificación, la selección del modelo y la estrictez del esquema forman la columna vertebral del pipeline; asegúrese de que estos sean correctos antes de agregar automatización a su alrededor.
Pipeline de documentos, pasos 13-16: el enrutamiento de revisión humana, la trazabilidad y el procesamiento asíncrono son los controles operativos que hacen que el pipeline sea confiable a escala.