Revisión Well-Architected de tu SaaS en AWS con Claude Code

Si tienes un SaaS o un agente en AWS y nunca has pasado una revisión Well-Architected, ya puedes hacer un primer borrador tú solo desde Claude Code. Instala el plugin aws-core, empieza por una revisión de un solo pilar y trata el informe como una lista de preguntas, no como un aprobado.

Qué es

El AWS Well-Architected Framework es la lista de buenas prácticas con la que AWS evalúa una arquitectura: seis pilares (excelencia operativa, seguridad, fiabilidad, eficiencia, coste y sostenibilidad) y, encima, “lentes” para tipos de carga concretos, como serverless, SaaS o IA agéntica. Una revisión consiste en ir pregunta por pregunta comprobando si tu sistema cumple cada práctica. Hecha a mano lleva días.

El 28 de octubre, el blog de arquitectura de AWS publicó cómo Smarsh, una empresa de archivo de comunicaciones, automatizó esa revisión para sus agentes. Usaron el Agentic AI Lens, que tiene 150 buenas prácticas en 41 preguntas, y que todavía no se puede elegir en la consola de Well-Architected. Lo empaquetaron como una skill de Claude (un paquete de instrucciones, datos y scripts que el modelo carga cuando lo necesita) con tres piezas:

Un JSON con las 150 prácticas, que es la única fuente de verdad. La skill tiene prohibido inventar o renumerar prácticas.
Una guía de evaluación con cinco estados posibles. Cada estado tiene que citar evidencia del repositorio y, si no la hay, la práctica queda como “Not Reviewed”, sin adivinar.
Un script en Python que genera el Excel final y rechaza cualquier identificador o estado que no exista.

Según el artículo, el borrador completo sale en “hours instead of a multi-day manual effort”. En sus pruebas con dos repositorios de ejemplo, la skill cumplió 16 de 16 expectativas y Claude sin la skill, 8 de 16. Son repositorios sintéticos y resultados de la propia empresa, así que tómalo como una señal, no como un benchmark.

El código de Smarsh no es público. Lo que sí es público es lo que AWS ha sacado alrededor.

Qué puedes instalar hoy

La fuente del tema era el repositorio aws-samples/sample-well-architected-skills-and-steering: skills con licencia MIT-0 que cubren 307 buenas prácticas, 57 preguntas y 27 lentes, entre ellas Agentic AI, Serverless y SaaS. Pero al revisarlo me encontré con que su README ya lo marca como obsoleto y deja de aceptar contribuciones. Su sucesor es la skill aws-well-architected-review de Agent Toolkit for AWS, con licencia Apache 2.0.

La diferencia importa: el repo antiguo lleva una copia de la documentación de AWS hecha en una fecha concreta, y el propio README te avisa de que mantenerla al día es cosa tuya. La skill nueva lee la documentación de AWS en el momento de la revisión.

En Claude Code se instala desde el marketplace oficial, que viene añadido por defecto:

/plugin install aws-core@claude-plugins-official

Si te dice Plugin not found, actualiza antes el índice con /plugin marketplace update claude-plugins-official. El plugin trae también la configuración del AWS MCP Server, que la skill recomienda para leer la documentación. Para buscar documentación no hacen falta credenciales de AWS; solo para llamar a la API de tu cuenta.

Cómo usarlo

Abre Claude Code en el repo que quieres revisar. La skill descubre la carga a partir de tu código, tu infraestructura como código (CDK, CloudFormation, Terraform) y tus pipelines de CI.
Elige el modo con la frase que usas. La skill tiene cuatro: puntuación por pilar (“score this architecture”), revisión rápida a nivel de pregunta, revisión de uno o dos pilares (“review only security and reliability”) y revisión completa.
Pide la lente si aplica. Por ejemplo: “Haz una revisión Well-Architected de este repo solo de seguridad y fiabilidad, y aplica el Serverless Lens”. Las lentes se suman a las preguntas del framework y salen en una sección aparte del informe.
Lee primero lo que no pudo comprobar. Cada práctica sale con uno de cinco estados, y uno de ellos es “Cannot Determine”. La skill explica qué dato le falta, normalmente algo que está en tu cuenta de AWS y no en el código.

El informe trae puntuación de 1 a 5 por pilar, una tabla por pregunta, los hallazgos ordenados por riesgo y un plan de arreglos por prioridad.

Mi opinión

Lo usaría antes de una conversación con AWS o con el equipo de seguridad de un cliente grande, y no como un certificado. El caso de Smarsh lo deja claro: los huecos que el repo no podía responder se convirtieron en la agenda de la reunión con los arquitectos de AWS. Para alguien que construye solo, ese es el valor real: llegar a la reunión sabiendo qué preguntar.

No empezaría por la revisión completa. Es el modo más pesado, carga los seis pilares y su coste en tokens crece con lo que encuentra. Para un SaaS pequeño, seguridad y fiabilidad son los dos pilares donde un fallo le llega directo al cliente: datos de un tenant que ve otro, o una caída sin vuelta atrás. Empieza por ahí.

Lo que más me gusta del caso de Smarsh es la regla de honestidad: si no hay evidencia, no se marca nada. Un agente que rellena 150 casillas con “cumple” es peor que no tener revisión, porque te da una tranquilidad que no te has ganado. Si haces tu propia skill para otra lista de control, copia esa regla y el script que rechaza identificadores inventados.

Y una advertencia de sentido común: el informe describe tu infraestructura y tus agujeros. Trátalo como confidencial y no lo subas a un repo público.

Fuentes

Si te interesa cómo reviso arquitecturas en AWS con agentes y sin equipo, sígueme en LinkedIn.