Aprendizajes - Claude Certified Architect

Chuleta rápida

Si el problema es ambigüedad:

Instrucción vaga: haz el criterio más explícito.
Formato inconsistente: usa few-shot examples.
Transformaciones mal entendidas: da ejemplos input-output.
Clasificaciones inestables: usa rúbrica absoluta con ejemplos.

Si el problema es automatización fiable:

Salida consumida por máquinas: usa JSON/schema nativo.
Secuencia obligatoria: enforcement programático.
Normalización determinista: hooks o código, no prompt.
Tool misuse: restringe la tool, no solo lo prohíbas.

Si el problema es contexto:

Falta información: añade contexto relevante.
Duplicados: muestra qué ya existe o qué ya se revisó.
Contexto largo: resumen clave al inicio y secciones claras.
Discovery ruidoso: usa subagente o context: fork.

Si hay que elegir entre síncrono y batch:

Blocking, pre-merge, dev esperando: síncrono.
Nocturno, semanal, diferible: Message Batches API.
Tool use iterativo: no batch.
Polling no convierte batch en tiempo real.

Claude Code en CI/CD

Preguntas 1-15

Modo no interactivo

Para ejecutar Claude Code en pipelines se usa claude -p "prompt" o claude --print "prompt". Procesa el prompt, escribe en stdout y termina.

Trampa: variables como CLAUDE_HEADLESS=true, redirecciones de stdin o flags inventados como --batch no son la respuesta documentada.

Prompt specificity

Cuando el análisis es inconsistente por una tarea mal definida, la raíz suele ser un criterio ambiguo. Ejemplo: “check that comments are accurate” debe convertirse en “flag comments only when their claimed behavior contradicts actual code behavior”.

Batch processing

Workflow	API adecuada	Razón
Pre-merge checks, style checks bloqueantes, hooks que impiden merge	Síncrona	El desarrollador está esperando; batch puede tardar hasta 24 horas.
Informes nocturnos, auditorías semanales, generación de tests offline	Message Batches API	Son tareas diferibles y aprovechan el ahorro de coste.
Review que necesita pedir archivos mediante tools y continuar	Síncrona/interactiva	Batch no permite ejecutar tools a mitad de request y devolver resultados para continuar.

Falsos positivos y confianza

Si no se permite filtrar findings, reduce el coste de investigación: incluye razonamiento y confidence inline.
Si ciertas categorías tienen falsos positivos muy altos, desactívalas temporalmente y conserva categorías de alta precisión.
No apliques reducción de strictness uniforme si security/correctness ya funcionan bien.

Contexto para evitar duplicados

Sugerencias de tests duplicadas: incluye el archivo de tests existente.
Comentarios repetidos tras nuevos commits: incluye findings previos e instruye reportar solo nuevos o aún no resueltos.
Reducir el número de sugerencias no da a Claude información para evitar duplicados.

Formato y severidad

Feedback accionable inconsistente: añade 3-4 few-shot examples con ubicación, problema, severidad y fix concreto.
Severity inconsistente: usa criterios explícitos, absolutos y ejemplos de código por nivel.
Salida para PR comments automatizados: usa --output-format json y --json-schema.

Revisión de PRs grandes

Si un single-pass review de muchos archivos da resultados superficiales o contradictorios, descompón: pase por archivo para issues locales y pase separado de integración para flujos cross-file.

Verificación independiente

Cuando Claude genera código y su propia revisión no detecta fallos sutiles que otro revisor sí ve, usa una segunda instancia independiente que no vea el razonamiento del generador. Eso reduce confirmation bias.

Sistemas multiagente de investigación

Preguntas 16-30

Contratos compactos entre agentes

Si web search y document analysis devuelven 155K tokens pero síntesis funciona mejor con menos de 50K, no metas un agente resumidor como parche inicial. Cambia el contrato upstream: hechos clave, citas, relevance scores y datos estructurados en lugar de páginas completas y cadenas de razonamiento.

Lost in the middle

Si el agente cita bien el principio y el final pero omite hallazgos críticos del medio, coloca un key findings summary al inicio y organiza el detalle con encabezados claros. Aprovecha la primacía y mejora navegación.

Orchestrator-workers

El coordinador recoge resultados, mantiene visibilidad global y decide el siguiente paso.
Los workers ejecutan tareas especializadas y devuelven al coordinador.
La síntesis integra hallazgos; concatenar raw outputs no es síntesis.
Evita comunicación directa entre subagentes si rompe control central.

Particionar antes de delegar

Si agentes investigan subtemas solapados, el coordinador debe particionar explícitamente el espacio: por fuente, dominio, subpregunta o responsabilidad. Deduplicar al final no recupera tokens ya gastados.

Cobertura global

Si todos los subagentes hacen bien sus tareas pero el informe final omite dominios completos, revisa la descomposición del coordinador. La síntesis no puede integrar áreas que nunca fueron investigadas.

Error propagation

Situación	Respuesta correcta
Error transitorio que el subagente puede resolver	Recuperación local; escalar solo si no puede resolver.
Timeout o fallo no resuelto	Enviar error estructurado: tipo, query, parciales, intentos, alternativas.
Fuentes parciales disponibles	Sintetizar con coverage annotations y gaps explícitos.
`0 results found`	Resultado vacío válido, no fallo.
`Connection timeout`	Fallo de acceso que puede requerir retry o fuente alternativa.

Tool distribution y least privilege

Misrouting por nombres ambiguos: renombra y redefine tools para eliminar solapamiento semántico.
Si document analysis usa fetch_url para hacer búsquedas, reemplázalo por load_document que valide formatos documentales.
Si synthesis verifica facts simples en el 85% de casos, dale un verify_fact scoped; delega investigaciones complejas vía coordinador.

Conflictos entre fuentes

Si dos fuentes creíbles dan estadísticas incompatibles, el subagente debe incluir ambas, atribuirlas, marcar el conflicto y dejar la reconciliación al coordinador o a la fase con contexto global.

Customer Support Resolution Agent

Preguntas 31-45

Calidad de respuesta

Si la resolución es técnicamente correcta pero a veces incompleta en política, plazos o próximos pasos, usa evaluator-optimizer: redactar, autoevaluar contra criterios de completitud y mejorar antes de responder.

Tool use eficiente

Demasiados round trips porque Claude pide tools secuenciales: instruye a pedir tools relacionadas en paralelo y devuelve resultados juntos.
Solicitudes complejas con subproblemas: descomponer concerns, compartir contexto de cliente e investigar en paralelo antes de sintetizar.
El loop agentic se controla con stop_reason: continuar en tool_use, parar en end_turn.

Selección de tools

Si llama la tool incorrecta, revisa primero nombres y descripciones.
Descripciones mínimas no bastan: incluye input formats, ejemplos, edge cases y boundaries.
Si el fallo ocurre en casos ambiguos, usa few-shot examples de esos casos, con razonamiento comparativo.
Si una palabra dispara un patrón pese a buenas tools, busca instrucciones keyword-based en el system prompt.

Escalation y autonomía

Escalado mal calibrado: criterios explícitos + few-shot de resolver vs escalar.
Policy gap real: escalar a humano.
Multi-concern no implica escalar; puede descomponerse.
Incomodidad al presentar datos contradictorios no exige escalar si política y datos son claros.

Identidad, ambigüedad y reglas críticas

Múltiples matches de cliente: pedir identificador adicional antes de actuar.
No usar “más reciente”, ranking o confidence como sustituto de verificación.
Verificación obligatoria antes de operaciones de pedido/reembolso: imponer precondición programática.

Memoria y datos precisos

Progressive summarization pierde detalles. Para importes, fechas, porcentajes, order IDs y expectativas del cliente, extrae datos a un bloque persistente de case facts incluido en cada prompt.

Hooks

Si herramientas MCP devuelven formatos heterogéneos, usa un PostToolUse hook para normalizar outputs antes de que Claude los procese. Es determinista y centralizado.

Code Generation con Claude Code

Preguntas 46-60

Plan mode vs direct execution

Usa plan mode cuando...	Usa direct execution cuando...
Hay ambigüedad arquitectónica, varias opciones válidas o trade-offs grandes.	El patrón existente y el requisito están claros.
La decisión afecta capacidades futuras, permisos o integración externa.	La tarea es local, acotada y no cambia arquitectura.
Hay reestructuración amplia, como monolito a microservicios.	Solo hay que aplicar un patrón ya establecido.

Subagentes, skills y contexto aislado

Discovery enorme y ruidoso: Explore subagent para devolver resumen compacto.
Skill de brainstorming o análisis voluminoso: context: fork.
context: fork evita que alternativas abandonadas o outputs enormes contaminen la implementación.

Iterative refinement

Si requisitos en prosa producen estructuras diferentes cada vez, da 2-3 ejemplos concretos input-output. Para transformaciones de API responses, esto comunica nesting, field mapping y formatos de timestamp mejor que más prosa.

CLAUDE.md, rules y skills

Necesidad	Ubicación recomendada
Reglas universales del proyecto	`.claude/CLAUDE.md`
Reglas modulares por tema	`.claude/rules/*.md`
Reglas automáticas por path o tipo de archivo	`.claude/rules/` con frontmatter y globs
Workflow bajo demanda, como review, deployment o migration	Skills o slash commands
Slash command compartido por equipo	`.claude/commands/` en el repo
Skill personal que no afecte al equipo	`~/.claude/skills/` con nombre distinto si existe una project skill igual

Configuración de skills

Argumentos omitidos: argument-hint.
Context bleeding: context: fork.
Riesgo por herramientas amplias: allowed-tools.
Task-specific examples pesados: skill invocada bajo demanda, no CLAUDE.md.

MCP de equipo

Para un GitHub MCP server compartido con tokens personales: versiona .mcp.json en project scope usando expansión ${GITHUB_TOKEN} y documenta la variable en el README. Configuración compartida sí; secretos no.

Precedencia de skills

Las project skills tienen prioridad sobre personal skills con el mismo nombre. Si alguien quiere personalizar /commit sin afectar al equipo, debe crear otra skill personal, por ejemplo /my-commit.

Matriz de decisiones

Señal en la pregunta	Respuesta que suele ganar	Evita caer en...
“Vague”, “inconsistent analysis”, “criteria unclear”	Criterios explícitos y verificables	Añadir contexto irrelevante
“Instructions already detailed but output varies”	Few-shot examples	Más prosa del mismo tipo
“Machine needs to parse output reliably”	Structured output con schema	Templates libres o ejemplos en CLAUDE.md
“Blocking”, “pre-merge”, “developers waiting”	API síncrona	Batch con polling
“Overnight”, “weekly”, “scheduled”, “cost savings”	Message Batches API	Usar síncrono por costumbre
“Tool call, execute, return result, continue”	Flujo interactivo, no batch	Pensar que tool definitions bastan en batch
“Wrong tool selected”	Revisar tool descriptions/names	Fine-tuning o clasificadores antes de arreglar la interfaz
“Tool can do too much”	Tool scoped / least privilege	Solo pedirle al modelo que no la use mal
“Multiple matches”, “wrong account risk”	Pedir identificador adicional	Ranking, recency o confidence
“Required order of operations”	Programmatic prerequisite	Prompt-only enforcement
“Verbose discovery fills context”	Explore subagent / `context: fork`	Seguir en main context y compactar tarde
“Task-specific but not always useful”	Skill/slash command bajo demanda	Cargarlo siempre en CLAUDE.md
“Different conventions by file type/path”	`.claude/rules/` con globs	Skills manuales o CLAUDE.md gigante
“Architectural ambiguity”	Plan mode	Direct execution prematura

Patrón general del examen: la respuesta correcta suele atacar la causa raíz con el mecanismo más determinista y proporcional disponible. Si basta corregir una descripción, no metas un clasificador. Si hace falta una garantía, no uses prompt. Si el problema es workflow, no lo tapes con más contexto.

Resumen final por mecanismos

Humano: policy gaps, excepciones no contempladas, decisiones con juicio empresarial o ambigüedad no resoluble con datos.
Programático: precondiciones, seguridad, normalización, validación, structured output, restricciones de tools.
LLM/prompt: razonamiento flexible, clasificación con rúbricas, few-shot para patrones, síntesis, explicación al cliente.
Coordinador: particionar tareas, mantener visibilidad, manejar recuperación global, decidir routing y reconciliación.
Subagente/tool scoped: trabajo especializado, recuperación local, capacidades limitadas y bien descritas.
Batch: cargas diferibles, independientes y no interactivas.
Síncrono: loops con tools, feedback bloqueante o decisiones en tiempo real.

Documento generado a partir de las 60 preguntas del examen de práctica compartidas en la conversación.