Usando Claude Code para Arquitectura FrontendUsando Claude Code para Arquitectura Frontend

La IA ha llegado para quedarse. Sin duda. Vamos a ver cada vez más código generado por IA. La pregunta es, ¿cómo mantenemos la calidad de ese código? ¿Sabrá la IA mejor que nosotros qué significa bueno? ¿Importa siquiera?

Déjame enseñarte cómo trabajo con la IA de una forma que es genuinamente inteligente, no solo rápida.

#¿Qué agente de IA debería usar?

El que más he probado es Claude CodeSe abre en una nueva pestaña de AnthropicSe abre en una nueva pestaña. En algún momento me pasaré probablemente a una herramienta que abstraiga el modelo subyacente, como OpencodeSe abre en una nueva pestaña.

Por ahora, dado que Claude está bloqueando el acceso a tercerosSe abre en una nueva pestaña, prefiero maximizar la inferencia hasta que el ecosistema se asiente.

Como siempre, usa la mejor herramienta para ti. Prueba nuevas de vez en cuando, el tooling sigue mejorando y los modelos cambian todo el tiempo.

#Skills para Arquitectura Frontend

He creado un set de 10 skills de alta calidad que representan cómo escribo código. He invertido más tiempo afinándolas del que me gustaría admitir. Esta es la lista:

1. architecture-guardrails
2. bugfix
3. create-delivery
4. create-domain-model
5. create-infrastructure
6. create-repository-contract
7. create-use-case
8. refactor
9. tdd-bdd
10. validate

Cada una codifica una decisión específica que he tomado sobre cómo debe construirse la Arquitectura Frontend: dónde vive el dominio, cómo se conectan los casos de uso, cómo la capa de delivery se mantiene fina, cómo los tests guían el diseño.

Para crearlas, uso el skill-creatorSe abre en una nueva pestaña.

#Hacer que las herramientas de IA recuerden

Hay otra skill que me ha resultado extremadamente útil:

remember

Esta skill es para cuando quiero que mi agente de IA recuerde una información importante. Esta es la descripción:

---
description: Capture and persist learnings to improve the agentic system over time. Use when (1) a pattern, solution, or pitfall is discovered during a session that should be remembered, (2) the user explicitly says "remember this", "learn this", or "add this to the guidelines", (3) a workaround or best practice emerges that would benefit future sessions, (4) project-specific conventions are established. Routes learnings to CLAUDE.md, existing skills, or creates new skills based on the learning type.
---

Puedes encontrar la skill completa en mi web.

#Una única fuente de verdad para las convenciones

Múltiples herramientas de IA usan múltiples convenciones para sus archivos de configuración. Yo prefiero abstraerlo y generar los archivos necesarios en el hook postinstall:

"postinstall": "node scripts/postinstall.ts"

Después tengo un script de NodeJS que ejecuta múltiples scripts de postinstall:

import { spawnSync } from 'node:child_process'

if (process.env['CI'] === 'true') {
  console.log('[postinstall] CI detected — skipping local setup steps.')
  process.exit(0)
}

function run(cmd: string, args: string[]) {
  console.log(`[postinstall] $ ${cmd} ${args.join(' ')}`)
  const result = spawnSync(cmd, args, {
    stdio: 'inherit',
    cwd: process.cwd(),
    env: process.env,
    shell: process.platform === 'win32',
  })
  if (result.status !== 0) {
    const code = result.status == null ? 1 : result.status
    console.error(`[postinstall] Command failed: ${cmd} ${args.join(' ')}`)
    process.exit(code)
  }
}

// 1) Install git hooks via lefthook
run('lefthook', ['install'])
// 2) Install Playwright browsers
run('npx', ['playwright', 'install'])
// 3) Sync AI guidelines
run('node', ['scripts/sync-ai-guidelines.ts'])

console.log('[postinstall] All steps completed.')

Y este es el script sync-ai-guidelines.ts:

import { constants } from 'node:fs'
import { access, copyFile, mkdir } from 'node:fs/promises'
import { dirname, resolve } from 'node:path'

const src = resolve(process.cwd(), 'ai/GUIDELINES.md')
const targets = [
  '.github/copilot-instructions.md',
  '.cursor/rules/Core.md',
  '.junie/guidelines.md',
  '.windsurfrules',
  'CLAUDE.md',
].map((p) => resolve(process.cwd(), p))

async function ensureDirFor(file: string) {
  await mkdir(dirname(file), { recursive: true })
}

async function safeCopy(from: string, to: string) {
  await ensureDirFor(to)
  await copyFile(from, to)
}

async function main() {
  try {
    await access(src, constants.R_OK)
  } catch {
    console.warn(`[sync-ai-guidelines] Source not found: ${src}. Skipping.`)
    return
  }

  await Promise.all(targets.map((t) => safeCopy(src, t)))
}

main()

Y luego mantengo un único ai/GUIDELINES.md como única fuente de verdad:

# Development Guidelines

Code Style and Structure

- Write concise, best-practice code with accurate examples. Follow Code Craftsmanship patterns.
- This is a React-based project.
- This is a Next.js-based project.
- Favor object-oriented programming (OOP) and declarative programming patterns.
- Prefer iteration and modularization over code duplication.
- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
- Prefer one export per file.
- Ensure a clear separation between UI, state management, and business logic to maintain a clean architecture.
- Use lowercase with dashes for directories (e.g., components/auth-wizard).
- Always use named exports for consistency and maintainability.
- Use npm as the package manager and lock versions using package-lock.json for consistency.
- Use ?? instead of || for nullish coalescing.
- Use conventional commit messages (feat:, fix:, chore:, etc.).
- Ensure all code changes include relevant test cases.
- Use declarative JSX.

TypeScript Usage

- Use TypeScript for all code.
- Prefer interfaces over types, except for utility types or mapped types.
- Avoid enums due to runtime overhead; prefer object maps or union types instead.
- Use strict mode in TypeScript for better type safety, avoid usages of `any`.

UI and Styling

- Use Styled Components for styling.
- Ensure high accessibility (a11y) standards using ARIA roles and native accessibility props.
- Avoid hardcoding padding or margins.
- Implement proper keyboard handling.
- Use CSS variables for theming when necessary.

Performance Optimization

- Minimize the use of useState and useEffect.
- Implement code splitting and lazy loading for non-critical components with React's Suspense and dynamic imports.
- Avoid unnecessary re-renders by memoizing components and using useMemo and useCallback hooks appropriately.

State Management

- Use React Context sparingly to avoid unnecessary re-renders.

Error Handling and Validation

- Prioritize error handling and edge cases.
- Handle errors at the beginning of functions.
- Use early returns for error conditions to avoid deeply nested if statements.
- Avoid unnecessary else statements; use the if-return pattern instead.
- Use domain errors to handle errors in the domain layer.
- Use Next.js's ErrorBoundary components for error handling at the route level.

Testing

- Write unit tests using Vitest.
- Implement integration tests for critical user flows using Playwright.
- Write test cases for both success and failure scenarios.

React Components

- Use a variable (const) for the components.
- Use FC to type the variable.
- If a component has children, use PropsWithChildren to type the component.
- Props should be typed within the component's type definition.

Un archivo. Un único sitio que editar, así seguimos el patrón D.R.Y.

#IA + TDD

Las IAs (y los humanos) trabajan mejor cuando hay una forma automatizada de validar el trabajo realizado. Cuando se practica TDD, las IAs generan código significativamente mejor. Esto me recuerda a un experimento mental de Martin Fowler:

“

Si tuvieras que elegir entre borrar todo tu código o todo tu suite de tests, deberías borrar el código. Es más fácil recrear el código que recrear los tests.

”

Con la llegada de la IA, codificar ya no es la commodity que solía ser, ni el cuello de botella. El cuello de botella se ha movido a áreas más difíciles de automatizar: describir lo que el sistema necesita hacer y cómo debe comportarse. Que casualmente, eso es lo que es realmente testear.

Es curioso ver cómo todo el mundo persigue ahora las buenas prácticas, dado que la IA se comporta mucho mejor y es más eficiente cuando esas prácticas están en su sitio.

#PRDs: Product Requirements Documents para IA

Generar PRDs (Product Requirements Documents) para migraciones o features complejas es una manera interesante de tener documentación de los cambios que vas a hacer.

Un PRD no es más que un archivo Markdown en tu proyecto. Puedes usar una skill para generarlo. La mejor manera que he encontrado es dejar que la IA te entreviste sobre los cambios. Recoge contexto y luego persiste sus hallazgos en un PRD.

Después genero tareas detalladas a partir del PRD y dejo que la IA las implemente usando las skills ya definidas.

Hay gente que va más allá y ejecuta la implementación bajo un Ralph LoopSe abre en una nueva pestaña, donde la idea es ejecutar un agente de IA infinitamente:

while :; do cat PROMPT.md | claude-code ; done

Locuras que se ven hoy en día.

Me gusta cuando los PRDs siguen esta estructura:

• Executive Summary
• Problem Statement
• Goals and Success Metrics
• User Stories
• Technical Architecture (Overview, Data Models, API Specifications)
• UI/UX Specifications
• Security Considerations
• Testing Strategy
• Risks and Mitigations
• Open Questions

Para esto creé otra skill. Puedes encontrar la skill create-prd aquí. Y una vez el PRD está escrito, plan-tasks lo descompone en archivos de tareas TDD-first, y code-task las implementa una a una, exigiendo tests fallando antes de cada paso.

#Quiero que me dejes ayudarte

Aquí es donde quiero hacer un argumento convincente, para que quizás me dejes ayudarte.

Si eres CTO, VP de Ingeniería o líder técnico con un frontend que está ralentizando a tu equipo — y estás intentando descubrir cómo integrar la IA sin sacrificar la calidad del código — me encantaría hablar contigo.

Esto es exactamente lo que hago para ganarme la vida: ayudo a equipos a diseñar Arquitectura Frontend que sea agradable de mantener hoy, y que los agentes de IA puedan extender con seguridad mañana. Skills, PRDs, TDD enforcement, diseño en capas, contenedores de DI — toda la pila de prácticas de esta newsletter, aplicadas a tu código.

Si alguna vez has sentido que:

• Tu equipo está mergeando código generado por IA que nadie acaba de entender
• Tu frontend es una maraña de componentes, hooks y efectos secundarios sin fronteras claras
• Quieres usar IA de forma más agresiva pero no te puedes fiar del output
• Onboardear nuevos desarrolladores (humanos o agentes) lleva semanas en lugar de días

Entonces deberíamos hablar.

Mira cómo ayudo a equipos o reserva una llamada directamente.

Cojo un número limitado de proyectos a la vez, así que la agenda se llena rápido. Si esto te resuena, escríbeme ya mejor que después.

Si no eres CTO, VP de Ingeniería ni líder técnico pero igualmente quieres ayudar, por favor refiéreme a quien conozcas, te lo agradeceré enormemente.

#Cerrando

La IA no va a reemplazar la buena arquitectura. Va a exponer la falta de ella.

Los equipos que ganen en los próximos años no serán los que adopten más herramientas de IA. Serán los que tengan las abstracciones más limpias, los tests más estrictos y las convenciones más claras, porque eso es lo que la IA puede aprovechar.

Skills, PRDs, convenciones, TDD. Cosas aburridas. Cosas que te definen la carrera.

P.S: Voy a dar charlas en React AlicanteSe abre en una nueva pestaña, React SummitSe abre en una nueva pestaña, Commit ConfSe abre en una nueva pestaña y JSNationSe abre en una nueva pestaña. ¿Quizás nos vemos por allí?