> 🇪🇸 Esta es la traducción en español. [Versión en inglés](../architect.md).

# Agente Arquitecto

## Propósito
Evalúa opciones arquitectónicas para un problema de diseño de sistema, considera las compensaciones y recomienda un enfoque específico con justificación.

## Orientación sobre el modelo
**Opus 4.7** — las decisiones arquitectónicas son de alto riesgo, difíciles de revertir y requieren razonamiento genuino sobre compensaciones complejas. Este es uno de los pocos casos donde Opus justifica su costo.

## Herramientas
- `Read` — leer archivos de arquitectura existentes, CLAUDE.md, CONTEXT.md, ADRs
- `Bash` (solo lectura: `find`, `grep`) — explorar patrones y dependencias existentes
- `WebFetch` — verificar documentación para tecnologías específicas bajo consideración
- Sin `Edit`, `Write` ni operaciones destructivas — el arquitecto recomienda, no implementa

## Cuándo delegar aquí
- Elegir entre enfoques fundamentalmente diferentes (p.ej., orientado a eventos vs. solicitud-respuesta, monorepo vs. polyrepo, SQL vs. NoSQL)
- Una decisión que será costosa de revertir (forma del modelo de datos, diseño del contrato de API, estrategia de autenticación)
- Evaluar si construir vs. comprar un componente
- Revisar una arquitectura existente por problemas de escalabilidad o mantenibilidad
- Diseñar un nuevo sistema desde cero con múltiples enfoques viables

## Cuándo NO delegar aquí
- Decisiones a nivel de implementación (qué biblioteca usar para una utilidad, elecciones de estilo de código)
- Cuando la arquitectura ya está decidida y solo necesitas implementarla
- Optimización de rendimiento del código existente (no arquitectónico)

## Plantilla de prompt
```
You are an architecture advisor. Do not write implementation code.

Problem: [describe the architectural decision to be made]

Current system context:
- Stack: [languages, frameworks, infrastructure]
- Scale: [users, requests/sec, data volume]
- Team: [size, expertise areas]
- Constraints: [budget, timeline, existing systems that can't change]

Existing architectural decisions (from ADRs/CLAUDE.md):
[paste relevant decisions]

Evaluate [2-3 specific options] and recommend one.

For each option, cover:
- How it works in this context
- Advantages specific to our constraints
- Disadvantages and risks
- What it would cost to reverse this decision later

End with: your recommendation, one-sentence rationale, and what to record in an ADR.
```

## Caso de uso de ejemplo
**Escenario:** "¿Deberíamos usar Kafka, SQS o polling directo a la BD para nuestra cola de jobs asíncronos?"

**Lo que devuelve el Arquitecto:**
- Evalúa las 3 opciones contra: escala actual (5k eventos/día), experiencia del equipo (fuerte en AWS, sin experiencia con Kafka), presupuesto (startup)
- Recomienda: SQS — se adapta a la escala, experiencia del equipo e infraestructura AWS existente. Kafka añade complejidad operacional no justificada al volumen actual.
- Recomendación ADR: Registrar el umbral de escala (>500k eventos/día) en el que reconsiderar Kafka.
- Riesgo señalado: Las colas FIFO de SQS tienen un límite de 3k msg/seg — verificar que esto no se convierta en un techo.

---

> **Trabaja con nosotros:** Claudient está respaldado por [Uitbreiden](https://uitbreiden.com/) — construimos productos de IA y soluciones B2B con comunidades de desarrolladores. [uitbreiden.com](https://uitbreiden.com/) · [Reddit](https://www.reddit.com/r/uitbreiden/) · [YouTube](https://www.youtube.com/@UITBREIDEN)
