Tag: Claude Code

  • Testing en Angular con IA: tests que protegen de verdad

    Testing en Angular con IA: tests que protegen de verdad

    Le pedí a Claude que escribiera los tests de un componente de login. Me devolvió 14 tests. Todos verdes. El CI pasó sin problema.

    Dos semanas después, un bug llegó a producción. El formulario aceptaba contraseñas vacías si el campo estaba touched pero sin valor. Ninguno de esos 14 tests lo detectó.

    Los tests no fallaron porque el bug no existía para ellos. Los tests comprobaban que el componente existía, que el formulario se renderizaba, que el método onSubmit() se llamaba. No comprobaban el comportamiento. Eran tests de que el código había sido escrito, no de que el código hacía lo correcto.

    Este es el problema número uno del testing en Angular con IA: la IA genera tests que pasan, no tests que protegen.


    El problema real de los tests generados por IA

    Cuando le das a un modelo un componente Angular y le pides “escribe los tests”, le estás pidiendo que haga ingeniería inversa de tu implementación. Y eso es exactamente lo que hace.

    Lee el código. Ve que hay un loginForm con dos controles. Ve que hay un método onSubmit(). Ve que hay un AuthService. Y escribe tests que verifican que esas cosas existen y se llaman entre sí.

    El resultado son tests acoplados a la implementación, no al comportamiento. Si renombras onSubmit() a handleSubmit(), los tests fallan. Si cambias el nombre de una variable interna, los tests fallan. Pero si introduces un bug lógico — como que el formulario se envíe con campos vacíos — los tests siguen verdes.

    Esto no es un fallo del modelo. Es un fallo del prompt. Le preguntaste lo que no debías preguntar.

    Sin contexto del comportamiento esperado, la IA no tiene forma de saber qué casos importan. No sabe cuándo debería bloquearse el submit. No sabe qué errores deben mostrarse. Así que copia lo que ve: la implementación.


    El cambio de mentalidad que lo arregla todo

    No le pidas a la IA que escriba tests. Pídele que te ayude a pensar qué testear.

    Son dos tareas completamente distintas. La primera produce código. La segunda produce criterios. Y los criterios son lo que hace que un test sea útil.

    Un test útil parte de una pregunta: “¿qué debería pasar cuando X?” No de “¿qué hace este código?”

    El flujo correcto es este:

    1. Describe el comportamiento, no el código. No copies el componente en el prompt. Describe qué hace desde fuera. Qué ve el usuario. Qué espera. Qué debe pasar si hace algo incorrecto.
    2. Pídele que liste los casos de test. Solo los casos, sin código todavía.
    3. Revisa y aprueba esa lista. Añades los que faltan. Eliminas los redundantes. Este paso es el más valioso de todo el flujo — y es el que la mayoría de devs salta.
    4. Pide el código de test para cada caso. Con Jest y Testing Library, una vez que los criterios están claros.

    Ejemplo práctico con Angular 22

    Este es el componente. Un formulario de login con Reactive Forms en Angular 22:

    // login.component.ts
    import { Component, inject, signal } from '@angular/core';
    import { FormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
    import { Router } from '@angular/router';
    import { firstValueFrom } from 'rxjs';
    import { AuthService } from '../services/auth.service';
    
    @Component({
      selector: 'app-login',
      standalone: true,
      imports: [ReactiveFormsModule],
      template: `
        <form [formGroup]="form" (ngSubmit)="onSubmit()">
          <input formControlName="email" type="email" placeholder="Email" />
          <input formControlName="password" type="password" placeholder="Contraseña" />
          @if (errorMessage()) {
            <p class="error">{{ errorMessage() }}</p>
          }
          <button type="submit" [disabled]="form.invalid || isLoading()">
            {{ isLoading() ? 'Cargando...' : 'Entrar' }}
          </button>
        </form>
      `
    })
    export class LoginComponent {
      private fb = inject(FormBuilder);
      private auth = inject(AuthService);
      private router = inject(Router);
    
      form = this.fb.group({
        email: ['', [Validators.required, Validators.email]],
        password: ['', Validators.required]
      });
    
      errorMessage = signal('');
      isLoading = signal(false);
    
      async onSubmit() {
        if (this.form.invalid) return;
        this.isLoading.set(true);
        this.errorMessage.set('');
        try {
          await firstValueFrom(this.auth.login(this.form.value as { email: string; password: string }));
          this.router.navigate(['/dashboard']);
        } catch (err: any) {
          if (err.status === 401) {
            this.errorMessage.set('Credenciales incorrectas');
          }
        } finally {
          this.isLoading.set(false);
        }
      }
    }

    El prompt malo que genera tests inútiles:

    "Escribe los tests para este componente Angular."

    El prompt bueno, siguiendo el flujo de cuatro pasos:

    "Tengo un componente de login en Angular 22 con Reactive Forms.
    El comportamiento esperado es:
    - El botón está deshabilitado si el formulario es inválido o si está cargando
    - Al enviar credenciales válidas, se llama a AuthService.login()
    - Si AuthService lanza un error 401, se muestra 'Credenciales incorrectas'
    - Si tiene éxito, el router navega a /dashboard
    
    Lista primero los casos de test. Sin código todavía."

    Y estos son los tests resultantes con Jest y Testing Library para Angular:

    // login.component.spec.ts
    import { render, screen } from '@testing-library/angular';
    import userEvent from '@testing-library/user-event';
    import { LoginComponent } from './login.component';
    import { AuthService } from '../services/auth.service';
    import { provideRouter } from '@angular/router';
    import { of, throwError } from 'rxjs';
    
    describe('LoginComponent', () => {
      const mockAuthService = { login: jest.fn() };
    
      async function setup() {
        await render(LoginComponent, {
          providers: [
            { provide: AuthService, useValue: mockAuthService },
            provideRouter([{ path: 'dashboard', component: {} as any }])
          ]
        });
        return userEvent.setup();
      }
    
      beforeEach(() => jest.clearAllMocks());
    
      it('deshabilita el botón cuando el formulario está vacío', async () => {
        await setup();
        expect(screen.getByRole('button', { name: /entrar/i })).toBeDisabled();
      });
    
      it('deshabilita el botón con email inválido aunque haya contraseña', async () => {
        const user = await setup();
        await user.type(screen.getByPlaceholderText('Email'), 'no-es-email');
        await user.type(screen.getByPlaceholderText('Contraseña'), '123456');
        expect(screen.getByRole('button', { name: /entrar/i })).toBeDisabled();
      });
    
      it('habilita el botón con credenciales válidas', async () => {
        const user = await setup();
        await user.type(screen.getByPlaceholderText('Email'), 'user@test.com');
        await user.type(screen.getByPlaceholderText('Contraseña'), '123456');
        expect(screen.getByRole('button', { name: /entrar/i })).not.toBeDisabled();
      });
    
      it('llama a AuthService.login al hacer submit con datos válidos', async () => {
        mockAuthService.login.mockReturnValue(of({}));
        const user = await setup();
        await user.type(screen.getByPlaceholderText('Email'), 'user@test.com');
        await user.type(screen.getByPlaceholderText('Contraseña'), '123456');
        await user.click(screen.getByRole('button', { name: /entrar/i }));
        expect(mockAuthService.login).toHaveBeenCalledWith({
          email: 'user@test.com',
          password: '123456'
        });
      });
    
      it('muestra mensaje de error cuando el servicio responde 401', async () => {
        mockAuthService.login.mockReturnValue(throwError(() => ({ status: 401 })));
        const user = await setup();
        await user.type(screen.getByPlaceholderText('Email'), 'user@test.com');
        await user.type(screen.getByPlaceholderText('Contraseña'), 'wrong');
        await user.click(screen.getByRole('button', { name: /entrar/i }));
        expect(await screen.findByText('Credenciales incorrectas')).toBeInTheDocument();
      });
    });

    La clave está en userEvent.type en lugar de fireEvent.input — con Reactive Forms en Angular, solo userEvent actualiza el FormControl correctamente en el entorno de test. Y el mock usa of({}) y throwError() de RxJS porque AuthService.login() devuelve un Observable.

    Esto es exactamente el enfoque que trabajamos en el curso de Testing en Angular con Jest y Testing Library: probar comportamiento, no implementación.


    Tests de servicios con IA: qué mockear y cómo describirlo

    Los servicios son donde más fácil es equivocarse al usar IA para testing.

    El error más común: pedirle a la IA que mockee el propio servicio para testearlo. Si mockeas AuthService en el test de AuthService, estás probando el mock, no el servicio.

    Lo que debes describirle a la IA es esto:

    "Tengo un AuthService en Angular 22 que inyecta HttpClient.
    El método login() hace POST a /api/auth/login con email y password.
    Devuelve un Observable<User>. En caso de error HTTP lo relanza tal cual.
    Escribe los tests usando provideHttpClient() + provideHttpClientTesting() y HttpTestingController.
    No mockees el servicio. Mockea solo el HttpClient."

    Con ese prompt, la IA sabe exactamente qué nivel de la pila debe sustituir:

    // auth.service.spec.ts
    import { TestBed } from '@angular/core/testing';
    import { HttpTestingController, provideHttpClientTesting } from '@angular/common/http/testing';
    import { provideHttpClient } from '@angular/common/http';
    import { AuthService } from './auth.service';
    
    describe('AuthService', () => {
      let service: AuthService;
      let httpMock: HttpTestingController;
    
      beforeEach(() => {
        TestBed.configureTestingModule({
          providers: [AuthService, provideHttpClient(), provideHttpClientTesting()]
        });
        service = TestBed.inject(AuthService);
        httpMock = TestBed.inject(HttpTestingController);
      });
    
      afterEach(() => httpMock.verify());
    
      it('hace POST a /api/auth/login con las credenciales', () => {
        const credentials = { email: 'user@test.com', password: '123456' };
        service.login(credentials).subscribe();
        const req = httpMock.expectOne('/api/auth/login');
        expect(req.request.method).toBe('POST');
        expect(req.request.body).toEqual(credentials);
        req.flush({ id: 1, email: 'user@test.com' });
      });
    
      it('devuelve el usuario cuando el servidor responde con éxito', () => {
        const mockUser = { id: 1, email: 'user@test.com' };
        let result: any;
        service.login({ email: 'user@test.com', password: '123456' })
          .subscribe(user => (result = user));
        httpMock.expectOne('/api/auth/login').flush(mockUser);
        expect(result).toEqual(mockUser);
      });
    
      it('relanza el error HTTP cuando el servidor responde 401', () => {
        let error: any;
        service.login({ email: 'user@test.com', password: 'wrong' })
          .subscribe({ error: err => (error = err) });
        httpMock.expectOne('/api/auth/login').flush(
          { message: 'Unauthorized' },
          { status: 401, statusText: 'Unauthorized' }
        );
        expect(error.status).toBe(401);
      });
    });

    La clave está en la instrucción: “mockea solo el HttpClient”. Esa precisión es lo que separa un prompt que genera tests útiles de uno que genera ruido.

    Si quieres ver cómo aplicar este patrón a servicios más complejos — con interceptores, state management y Signals — en el curso de Angular Moderno tienes la arquitectura base sobre la que todo esto encaja.


    Lo que la IA no puede hacer por ti

    La IA puede generar el código de test más rápido de lo que tú lo escribirías. No puede decirte qué casos importan en tu dominio de negocio.

    No sabe que en tu aplicación una contraseña vacía tiene un tratamiento especial. No sabe que hay un edge case cuando el usuario tiene sesión expirada y reintenta. No sabe que el botón de carga es crítico porque en producción la red va lenta y los usuarios hacen doble click.

    Ese conocimiento solo lo tienes tú. Tu trabajo es trasladarlo al prompt antes de pedir código. La IA amplifica lo que le das — si le das una descripción de comportamiento, amplifica eso. Si le das solo el código de implementación, amplifica eso.

    El flujo de cuatro pasos no es burocracia. Es el mínimo para que la IA genere tests que protejan algo.

    Si quieres llevar esta forma de trabajar más lejos — combinando especificaciones previas al código con IA para que los tests sean parte del diseño — eso es lo que construimos en el curso Construye con IA: de la Idea al Producto. Y si quieres acceso a los proyectos completos con suites de tests reales, los encontrarás en Dominicode Labs.


    FAQ

    ¿Puedo usar cualquier modelo de IA o Claude es el mejor para esto?

    El flujo de cuatro pasos funciona con cualquier modelo — Claude, GPT-4o, Gemini. La calidad del output depende mucho más de la calidad del prompt que del modelo. Dicho esto, Claude tiene ventaja en identificar casos borde cuando describes comportamientos complejos con muchas condiciones.

    ¿La IA puede generar tests TDD, es decir, antes de escribir el componente?

    Sí, y es el flujo ideal. Describes el comportamiento, pides los casos, apruebas la lista, pides el código de test — y luego le pides que implemente el componente para que esos tests pasen. Es TDD asistido por IA, y es especialmente potente para componentes nuevos.

    ¿Testing Library o Spectator para Angular?

    Testing Library porque te obliga a pensar en términos de comportamiento desde el principio. getByRole, getByPlaceholderText, findByText — todas esas queries buscan lo que el usuario ve, no lo que el código tiene internamente. Spectator facilita demasiado el acceso directo a la instancia del componente, lo que lleva a tests acoplados a implementación.

    ¿Cómo sé si un test generado por IA es bueno?

    Una heurística sencilla: introduce manualmente el bug más obvio en el componente y corre los tests. Si los tests siguen verdes, no valen nada. Por ejemplo, en el componente de login, pon if (true) return; al principio de onSubmit() — si el test de “llama a AuthService.login” sigue pasando, ese test no prueba nada. Esta técnica se llama mutation testing.

    ¿Vale la pena testear componentes de presentación puros?

    Depende de la complejidad. Un componente que solo muestra datos sin lógica condicional no necesita tests exhaustivos. Pero si tiene lógica de visualización — mostrar un badge según el estado, calcular clases CSS condicionalmente — esa lógica sí merece tests. Pregúntale a la IA: “¿qué comportamientos condicionales tiene este template que merecen ser testados?”


    *Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.*

  • MCP explicado para developers: conecta Claude a tus herramientas

    MCP explicado para developers: conecta Claude a tus herramientas

    Hace unos meses estaba trabajando con Claude Code en un proyecto con Supabase. Quería que el agente pudiese consultar la base de datos, leer el schema, revisar los registros. Lo normal cuando construyes algo de verdad.

    El problema: Claude no podía llegar a Supabase por sí solo. Necesitaba que yo le pasase el contexto a mano — copiar y pegar schema, copiar y pegar queries, copiar y pegar resultados. El LLM hacía el trabajo intelectual, pero la conexión a las herramientas era un cuello de botella manual y frustrante.

    Eso era la vida antes de MCP (Model Context Protocol).

    Hoy, con el servidor MCP de Supabase configurado en Claude Code, el agente puede leer tablas, ejecutar queries y revisar logs sin que yo mueva un dedo. La diferencia no es pequeña. Es el salto entre un asistente que responde preguntas y un agente que trabaja de verdad.


    El problema que MCP viene a resolver

    Antes de MCP, si querías conectar un LLM a una herramienta externa — GitHub, una base de datos, Slack, tu sistema de archivos — tenías que construir esa integración desde cero para cada caso.

    Cada proveedor de LLM tenía su forma de hacer “function calling”. OpenAI tenía la suya. Anthropic tenía la suya. Google tenía la suya. Y cada herramienta que querías conectar necesitaba código custom adaptado a ese proveedor específico.

    El resultado: ecosistemas fragmentados. Integraciones que había que reescribir al cambiar de modelo. Código duplicado en cada proyecto. Y una fricción enorme para cualquier developer que quisiese construir algo más allá del chat básico.

    MCP es la respuesta a ese problema. Un protocolo único, abierto y estandarizado para que cualquier LLM se comunique con cualquier herramienta. Escribe el servidor una vez. Funciona con cualquier cliente compatible.


    Qué es MCP exactamente

    Model Context Protocol es un protocolo abierto — especificación pública, SDK con licencia MIT — creado por Anthropic en noviembre de 2024 y adoptado por la industria. Define cómo los LLMs se comunican con herramientas y fuentes de datos externas.

    La arquitectura tiene dos piezas:

    1. Cliente MCP — la aplicación host que aloja al LLM (Claude Code, Claude Desktop). Es quien inicia la conexión, gestiona qué servidores están disponibles y enruta las llamadas del modelo a las herramientas.
    2. Servidor MCP — el servicio que expone las herramientas. Puede ser Supabase, GitHub, tu sistema de archivos, Notion, Slack, o cualquier cosa que hayas construido tú mismo.

    El flujo de una interacción con MCP es el siguiente:

    1. El usuario hace una petición a Claude: “¿Cuántos usuarios se registraron esta semana?”
    2. Claude detecta que necesita datos de la base de datos.
    3. La aplicación host enruta la llamada al servidor MCP de Supabase.
    4. El servidor ejecuta la query y devuelve los resultados.
    5. Claude recibe la respuesta y continúa la conversación con datos reales.

    Todo esto ocurre dentro de la misma sesión, de forma transparente para el usuario. La especificación completa del protocolo está disponible en modelcontextprotocol.io, mantenida como estándar abierto.


    MCP vs Function Calling: la diferencia que importa

    Si llevas tiempo trabajando con LLMs probablemente conoces el concepto de function calling — la capacidad de un modelo de invocar funciones definidas por el developer.

    La confusión es comprensible. MCP y function calling resuelven el mismo problema superficialmente. Pero hay una diferencia fundamental:

    Criterio Function Calling MCP
    Compatibilidad Propietario por proveedor Protocolo abierto
    Portabilidad Reescribir al cambiar de modelo Un servidor, cualquier cliente
    Mantenimiento Código duplicado por proveedor Único punto de actualización
    Adopción Fragmentada Claude Code, Cursor y más

    Function calling es propietario. La especificación de cómo defines una función para OpenAI no es la misma que para Anthropic. Si cambias de modelo, reescribes las integraciones.

    MCP es el estándar universal. El servidor MCP que escribas hoy para conectar Claude a tu base de datos funciona también con cualquier otro cliente MCP que aparezca mañana. El servidor no sabe ni le importa qué LLM hay al otro lado.

    Es la diferencia entre construir sobre propietario y construir sobre estándar. La misma diferencia que existe entre HTTP y el protocolo interno de un servicio concreto.

    Si estás construyendo herramientas que los LLMs van a usar en producción, MCP es la apuesta correcta. Es la razón por la que en el curso Construye con IA trabajamos con MCP desde el principio — no porque sea lo más nuevo, sino porque es lo que tiene sentido en un stack real.


    Casos de uso reales para developers

    Supabase MCP. Claude puede leer el schema de tu base de datos, ejecutar queries, revisar los logs de error, inspeccionar las políticas RLS. Cuando estás debuggeando un problema en producción, tener al agente con acceso directo a la base de datos no es un lujo — es lo que separa minutos de horas.

    GitHub MCP. Claude puede leer Pull Requests, crear issues, revisar el historial de commits, comentar en code reviews. Si trabajas en un equipo o gestionas un proyecto open source, esto te cambia el flujo de trabajo.

    Filesystem MCP. Claude puede leer y escribir archivos en tu proyecto directamente. Esto es lo que usa Claude Code por defecto — el acceso al sistema de archivos es un servidor MCP. Cuando le dices a Claude “edita este archivo”, hay un servidor MCP detrás gestionando esa operación.

    Notion o Confluence MCP. Claude puede leer tu documentación, buscar en tus notas, actualizar páginas. Útil si tienes tu spec o tus decisiones de arquitectura en Notion y quieres que el agente las tenga en contexto sin tener que copiarlas manualmente.

    Slack MCP. Claude puede leer canales, buscar mensajes, enviar notificaciones. Si construyes pipelines de automatización, esto es la pieza que conecta el agente con tu equipo.

    El patrón es siempre el mismo: en lugar de que tú seas el intermediario entre el LLM y la herramienta, el protocolo gestiona esa conexión. Tu rol pasa de “copy-paste operator” a alguien que define qué herramientas el agente puede usar y con qué permisos.


    Cómo configurar un servidor MCP en Claude Code

    La parte práctica. Hay dos formas de configurar servidores MCP en Claude Code:

    Opción 1 — Configuración global (claudedesktopconfig.json) Esta configuración aplica a todas tus sesiones de Claude Code. El archivo vive en:

    • macOS: ~/Library/Application Support/Claude/claudedesktopconfig.json
    • Windows: %APPDATA%\Claude\claudedesktopconfig.json

    Opción 2 — Configuración por proyecto (.mcp.json) Un archivo .mcp.json en la raíz de tu proyecto. Solo aplica a ese proyecto. Es la opción que recomiendo — el contexto de las herramientas debe ser específico al proyecto, no global.

    Ejemplo práctico: MCP de filesystem

    {
      "mcpServers": {
        "filesystem": {
          "command": "npx",
          "args": [
            "-y",
            "@modelcontextprotocol/server-filesystem",
            "/Users/bezael/projects/mi-proyecto"
          ]
        }
      }
    }

    Con esto configurado, Claude puede leer y modificar archivos dentro de la ruta que especifiques. No tiene acceso a nada fuera de ese directorio — los permisos los defines tú.

    Ejemplo: MCP de Supabase

    {
      "mcpServers": {
        "supabase": {
          "command": "npx",
          "args": ["-y", "@supabase/mcp-server-supabase@latest"],
          "env": {
            "SUPABASE_URL": "https://tu-proyecto.supabase.co",
            "SUPABASE_SERVICE_ROLE_KEY": "tu-service-role-key"
          }
        }
      }
    }

    Una vez que reinicias Claude Code con esta configuración, el agente tiene acceso a tu base de datos. Puedes pedirle que revise el schema, que ejecute una query, que busque errores en los logs.

    Qué ocurre cuando Claude usa una herramienta MCP

    Por defecto, Claude Code te muestra cada llamada MCP antes de ejecutarla. Verás algo como:

    Tool call: filesystem.read_file
    Arguments: { "path": "/src/components/UserCard.tsx" }

    Puedes aprobarla, rechazarla o configurar permisos permanentes por servidor. El flujo de trabajo es transparente — no hay caja negra.

    Esto conecta directamente con lo que explico en el post sobre Context Engineering para proyectos de IA: el contexto que tiene el agente determina la calidad de sus decisiones. MCP es una de las palancas más directas para darle al agente contexto real, no simulado.


    El ecosistema MCP hoy

    La adopción ha sido rápida. Hoy existen servidores MCP oficiales o comunitarios para:

    • Supabase, PostgreSQL, SQLite
    • GitHub, GitLab, Linear
    • Notion, Confluence, Obsidian
    • Slack, Discord
    • AWS, Google Cloud
    • Playwright (para automatizar navegadores)
    • Docker
    • Y decenas más

    El registro de servidores MCP crece cada semana. Si la herramienta que necesitas no tiene servidor MCP todavía, puedes construir el tuyo — el SDK oficial de Anthropic para TypeScript y Python hace que crear un servidor MCP básico sea trabajo de pocas horas.


    Por dónde empezar hoy

    Si nunca has configurado un servidor MCP, el camino más corto es este:

    1. Abre Claude Code en un proyecto real tuyo.
    2. Crea un archivo .mcp.json en la raíz con el servidor de filesystem apuntando a tu directorio de trabajo.
    3. Reinicia Claude Code.
    4. Pídele que liste los archivos del proyecto, que lea un componente específico, que analice la estructura.

    No necesitas construir nada. Solo configurar. En menos de 10 minutos tienes un agente que trabaja con el contexto real de tu proyecto en lugar de con lo que tú le describes.

    Si todavía no tienes configurado el contexto base de tu proyecto, el post sobre cómo estructurar tu CLAUDE.md es el punto de partida — MCP y CLAUDE.md son complementarios, no alternativos.

    El siguiente paso natural es conectar tu base de datos si usas Supabase, o GitHub si gestionas un repositorio con actividad. Cada servidor MCP que añades amplía lo que el agente puede hacer sin intervención tuya.

    Y si quieres entender la arquitectura completa — no solo el protocolo MCP sino todo el sistema que lo rodea, de la spec al producto funcionando — eso es exactamente lo que cubrimos en el curso Construye con IA. Si quieres explorar esto con otros developers y ver proyectos reales con MCP en acción, en Dominicode Labs revisamos este tipo de proyectos regularmente.


    FAQ

    ¿MCP es solo para Claude o funciona con otros LLMs?

    MCP es un protocolo abierto — no es propietario de Anthropic en el sentido de que solo funcione con Claude. Otros clientes MCP compatibles pueden usar los mismos servidores. La apuesta de Anthropic fue precisamente crear un estándar que la industria pudiese adoptar, no una ventaja competitiva cerrada. Hoy el ecosistema está centrado en Claude Code y Claude Desktop, pero la adopción por parte de otros clientes está creciendo.

    ¿Es seguro darle acceso a Claude a mi base de datos o sistema de archivos?

    Depende de cómo lo configures. El servidor MCP de filesystem solo puede acceder a las rutas que tú especifiques — no tiene acceso a toda tu máquina. Con Supabase, usas la service role key, que tiene permisos amplios, por lo que hay que ser cuidadoso con qué operaciones permites. Por defecto Claude Code te muestra cada llamada MCP antes de ejecutarla. La regla general: mínimo privilegio — dale al servidor MCP exactamente los permisos que necesita, no más.

    ¿Necesito saber TypeScript o Python para usar MCP?

    Para usar servidores MCP existentes, no. Solo necesitas editar un archivo JSON de configuración y tener Node.js instalado (para los servidores que usan npx). Para construir tu propio servidor MCP, el SDK oficial de Anthropic está disponible en TypeScript y Python, y el punto de partida es sencillo — un servidor básico son menos de 50 líneas.

    ¿Cuál es la diferencia entre MCP y un plugin de ChatGPT?

    Los plugins de ChatGPT fueron un intento propietario de conectar LLMs a herramientas externas, y OpenAI los deprecó en 2024. MCP es un protocolo abierto, no una feature de un producto específico. La diferencia práctica: un servidor MCP que construyas hoy puede ser usado por cualquier cliente MCP compatible mañana. Un plugin de ChatGPT solo funcionaba con ChatGPT, con las restricciones y cambios que OpenAI decidiera unilateralmente.

    ¿MCP reemplaza completamente el function calling tradicional?

    No exactamente. Function calling sigue siendo el mecanismo subyacente — MCP lo usa internamente. Lo que MCP añade es la capa de estandarización: define cómo se describen las herramientas, cómo se comunica el cliente con el servidor, cómo se gestionan los errores. Es más una capa de protocolo sobre function calling que un reemplazo.


    *Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.*

  • Context Engineering: proyectos con IA sin perder el hilo

    Context Engineering: proyectos con IA sin perder el hilo

    La primera vez que me pasó, pensé que era un fallo del modelo.

    Llevaba tres días construyendo una API con Claude Code. Arquitectura decidida, endpoints definidos, estructura de carpetas lista. Todo tenía sentido. Abrí una sesión nueva al cuarto día y le pedí que añadiera autenticación al módulo de usuarios.

    Me devolvió código que contradecía las decisiones que habíamos tomado el día anterior. Naming diferente. Patrón de errores distinto. Como si hubiera arrancado desde cero.

    No era un fallo del modelo. Era un fallo mío. No le había dado context engineering. Le había dado prompts.

    Lo que me faltaba tiene nombre. Y no es lo mismo que prompt engineering.


    El problema real: el modelo no sabe qué decidiste ayer

    Los LLMs no tienen memoria entre sesiones. Cada conversación nueva es, literalmente, una pizarra en blanco.

    Dentro de una misma sesión tienen una ventana de contexto — los modelos actuales manejan ventanas de entre 128k tokens (GPT-4o) y 200k tokens (Claude 3.5/3.7), cifras de junio 2026 que seguirán creciendo — pero esa ventana se llena. Y cuando se llena, el modelo empieza a “olvidar” las partes más antiguas de la conversación. Las decisiones de arquitectura que tomaste al principio. Las convenciones de naming que acordaste. El motivo por el que descartaste la opción B.

    El resultado es predecible: inconsistencia. Código que contradice decisiones previas. Respuestas que suenan razonables pero no encajan con el proyecto real. Y tú volviendo a explicar, sesión tras sesión, qué estás construyendo y cómo.

    Cualquier developer que haya usado IA durante más de dos semanas en un proyecto real lo ha vivido. La inconsistencia entre sesiones es la fricción número uno.


    Context engineering no es prompt engineering

    Mucha gente confunde los dos. No son lo mismo.

    Prompt engineering trata una sola interacción. Cómo formular la pregunta. Qué ejemplos incluir. Qué rol asignarle al modelo. Es útil, pero es táctica de un solo turno.

    Context engineering es la disciplina de estructurar y gestionar toda la información que recibe el modelo para que produzca resultados consistentes a lo largo de un proyecto completo. No en un prompt. En semanas de trabajo.

    La diferencia es la misma que hay entre saber hacer una buena pregunta en una entrevista y saber gestionar a un equipo durante un sprint.

    Prompt Engineering Context Engineering
    Alcance Un turno de conversación Un proyecto completo
    Problema que resuelve Calidad de una respuesta Consistencia entre sesiones
    Habilidad principal Redactar instrucciones claras Diseñar sistemas de información
    Cuándo falla Respuesta ambigua o incorrecta Proyecto incoherente en semana 3
    Herramienta clave El prompt en sí CLAUDE.md, specs, logs de decisiones

    Puedes ser un maestro del prompt engineering y aun así tener un proyecto que se rompe cada semana. El context engineering es lo que lo sostiene.


    Las 4 técnicas que uso en producción

    1. CLAUDE.md / AGENTS.md — la memoria persistente del proyecto

    Este es el punto de partida. Un archivo en la raíz del proyecto que le dice al modelo, al inicio de cada sesión, quién eres, qué estás construyendo y cómo trabajas.

    No es un README. Es un system prompt que el modelo lee antes de hacer nada.

    Lo mínimo que debe tener:

    • Descripción del proyecto en 2-3 líneas (qué es, para quién)
    • Stack técnico con versiones concretas
    • Convenciones de código que no se negocian
    • Lo que NO debe hacer el modelo (igual de importante)
    • Estado actual del proyecto — en qué fase estás

    Un ejemplo mínimo que uso en proyectos reales:

    # CLAUDE.md — API de Usuarios
    
    ## Proyecto
    API REST de gestión de usuarios para SaaS B2B.
    Stack: NestJS 10 + PostgreSQL + Prisma 5.
    
    ## Convenciones
    - Naming: camelCase para variables, PascalCase para clases, kebab-case para archivos
    - Errores: siempre usar HttpException con código y mensaje estructurado
    - No usar `any` en TypeScript — tipos explícitos o `unknown`
    
    ## NO hacer
    - No generar migraciones de Prisma automáticamente — las revisamos manualmente
    - No cambiar el schema sin actualizar architecture.md
    
    ## Estado actual
    Fase 2 — módulo de autenticación JWT. Ver tasks.md para detalle.
    

    Si usas Claude Code, este archivo es CLAUDE.md. Si usas Cursor o Windsurf, es __INLINE_PLACEHOLDER_0__ o __INLINE_PLACEHOLDER_1__ (__INLINE_PLACEHOLDER_2__ sigue siendo compatible pero es el formato legacy de Cursor). El nombre cambia. El concepto es el mismo.

    Ya escribí un post completo sobre cómo estructurar este archivo: CLAUDE.md: el system prompt de tu proyecto con Claude Code. Si no lo has leído, empieza por ahí.

    2. Archivos de estado — lo que el modelo no puede inferir

    El CLAUDE.md da el contexto estático: qué es el proyecto y cómo funciona. Pero los proyectos evolucionan. Necesitas capturar el estado dinámico.

    Yo mantengo tres archivos en cada proyecto:

    __INLINE_PLACEHOLDER_3__ — lista de tareas con estado (pendiente / en progreso / hecho). Una línea por tarea, fecha de última actualización. El modelo la lee y sabe exactamente dónde estás.

    __INLINE_PLACEHOLDER_4__ — log de decisiones arquitectónicas. Cada decisión con su fecha, la opción elegida y el motivo por el que se descartó la alternativa. Este archivo vale oro cuando vuelves a un proyecto tres semanas después.

    __INLINE_PLACEHOLDER_5__ — snapshot de la arquitectura actual. No el diagrama ideal. El diagrama real, con los módulos que existen ahora mismo. El modelo lo usa para no proponer soluciones que contradigan lo ya construido.

    Tres archivos. Ninguno supera las dos páginas. Pero juntos eliminan el 80% de la inconsistencia.

    3. Chunking de tareas — no pidas todo en un prompt

    Este error lo cometo yo también cuando tengo prisa.

    “Implementa el sistema de autenticación completo con JWT, refresh tokens, roles y middleware de autorización.”

    El modelo lo intenta. Genera código. Pero es código que asume cosas sobre tu proyecto que no conoce, o que contradice la arquitectura que ya tienes. Y cuando algo falla, el problema está distribuido en 400 líneas de código que no entiendes del todo.

    La regla que aplico: una tarea por sesión, una función por tarea.

    En lugar de pedir la autenticación completa, pido:

    1. Primero: el módulo de usuarios con su schema y validaciones
    2. Luego: la generación de JWT con los claims que necesito
    3. Luego: el endpoint de login que conecta ambos
    4. Luego: el middleware que verifica el token

    Cuatro sesiones. Cuatro archivos de contexto actualizados al final de cada una. Un sistema que entiendo porque lo construí pieza a pieza.

    El modelo produce mejor código cuando el scope es pequeño y el contexto es preciso. En la práctica, siempre.

    4. Resúmenes de sesión — el handoff entre el tú de hoy y el tú de mañana

    Al final de cada sesión de trabajo, antes de cerrar, escribo este prompt:

    “Resume lo que hemos hecho en esta sesión en 5-7 puntos: qué se implementó, qué decisiones se tomaron, qué problemas encontramos y qué queda pendiente para la siguiente.”

    Copio esa respuesta en un archivo __INLINE_PLACEHOLDER_6__ con la fecha.

    Cuando vuelvo al proyecto al día siguiente, la primera cosa que hago es darle ese log al modelo junto con el CLAUDE.md. El modelo arranca con el contexto exacto de donde lo dejé. Sin tener que re-explicar. Sin inconsistencias.

    Diez minutos al final de cada sesión que ahorran una hora al principio de la siguiente.


    Ejemplo práctico: un proyecto de tres semanas sin perder el hilo

    Semana 1 — Cimentar el contexto

    Antes de escribir una línea de código, genero la spec del proyecto con Spec-Driven Development: visión, usuarios, funcionalidades, arquitectura. Ese documento se convierte en la base del CLAUDE.md.

    Creo los tres archivos de estado vacíos: __INLINE_PLACEHOLDER_7__, __INLINE_PLACEHOLDER_8__, __INLINE_PLACEHOLDER_9__. El modelo los actualiza conforme avanzamos.

    Semana 2 — Construcción en chunks

    Cada sesión tiene una tarea concreta de __INLINE_PLACEHOLDER_10__. Arranca con el CLAUDE.md, el archivo de arquitectura y el log de la sesión anterior. Termina con el modelo actualizando el estado de la tarea y generando el resumen de sesión.

    Semana 3 — Cuando todo se complica

    En la semana 3 es cuando los proyectos sin sistema se rompen. El código empieza a contradecirse. Las decisiones del día 1 ya nadie las recuerda. Las nuevas funcionalidades no encajan con lo que ya existe.

    Con context engineering, la semana 3 es igual de fluida que la semana 1. Porque el modelo tiene, en cada sesión, el mismo nivel de contexto que tenías tú el primer día. El __INLINE_PLACEHOLDER_11__ le dice por qué tomaste las decisiones que tomaste. El __INLINE_PLACEHOLDER_12__ le muestra la estructura real. El log de sesión le dice dónde lo dejaste.

    No es magia. Es sistema.


    Lo que cambia cuando aplicas esto

    La diferencia no es velocidad. Es consistencia.

    Un developer sin context engineering puede ir rápido la primera semana. Pero en la semana 3, la deuda de contexto empieza a pasarle factura. Cada sesión nueva cuesta más porque hay que re-explicar más. Cada funcionalidad nueva tiene más probabilidad de romperse con algo anterior.

    Un developer con context engineering mantiene el mismo ritmo en la semana 8 que en la semana 1. Porque el contexto no es algo que se pierde — es algo que se gestiona.

    Esta es exactamente la mentalidad que enseño en el curso Construye con IA: de la idea al producto con Claude Code. No “cómo usar Claude”. Cómo construir con sistema.


    FAQ

    ¿El context engineering solo funciona con Claude Code?

    No. Los principios aplican a cualquier LLM y cualquier herramienta — Cursor, Windsurf, ChatGPT, Gemini. El CLAUDE.md tiene su equivalente en cada entorno: __INLINE_PLACEHOLDER_13__, __INLINE_PLACEHOLDER_14__, un system prompt inicial. La técnica de chunking y los resúmenes de sesión son agnósticos al modelo.

    ¿Cuánto tiempo añade a mi flujo de trabajo?

    En la práctica, entre 10 y 20 minutos al día. Cinco minutos actualizando el __INLINE_PLACEHOLDER_15__, diez minutos pidiendo y guardando el resumen de sesión. El retorno es que ahorras una o dos horas semanales de re-explicar contexto y corregir inconsistencias. La matemática es clara.

    ¿Necesito crear estos archivos manualmente desde cero?

    Puedes empezar con plantillas. En el curso Construye con IA incluyo las plantillas exactas de CLAUDE.md, __INLINE_PLACEHOLDER_16__ y __INLINE_PLACEHOLDER_17__ que uso en mis proyectos reales. Y si quieres la metodología de especificación completa, el libro SDD cubre el proceso de principio a fin.

    ¿Context engineering resuelve el problema de la ventana de contexto?

    Parcialmente. No puedes ampliar la ventana de contexto del modelo — eso lo determina el proveedor. Lo que puedes hacer es gestionar qué información entra en esa ventana en cada sesión. Context engineering te da control sobre eso: qué es esencial que el modelo sepa, qué puede inferir y qué no necesita en ese momento concreto. No elimina la limitación. La hace manejable.

    ¿Cuál es la diferencia entre context engineering y RAG?

    RAG (Retrieval-Augmented Generation) es una arquitectura técnica para recuperar información de fuentes externas y añadirla al contexto del modelo en tiempo de ejecución. Context engineering es una disciplina de trabajo que aplicas como developer para gestionar el contexto a lo largo de un proyecto. Son complementarios, no equivalentes. RAG es una herramienta. Context engineering es el sistema que decide qué información recuperar, cuándo y por qué.


    Si quieres profundizar en cómo aplicar estas técnicas con proyectos reales y ver el flujo en acción, en Dominicode Labs tenemos sesiones prácticas donde trabajamos esto con proyectos concretos de la comunidad.


    Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

  • Cómo redactar una spec efectiva para Claude Code

    Cómo redactar una spec efectiva para Claude Code

    Anatomía de una buena spec para Claude Code

    Tiempo estimado de lectura: 6 min

    • Una spec compacta y accionable evita suposiciones del agente y reduce iteraciones.
    • La estructura mínima: Requirements → Design → Tasks → Implementation.
    • Para bugs: seguir Report → Analyze → Fix → Verify.
    • Coloca SPEC.md junto al código y versiona la spec con el PR.

    Introducción

    Anatomía de una buena spec para Claude Code: si esperas que un agente genere código alineado con tu arquitectura, la spec es el mínimo imprescindible. Sin ella, Claude Code (o cualquier agente) hará suposiciones; con ella, ejecutará decisiones coherentes desde la primera iteración.

    Claude Code opera sobre repositorios y contexto local; el modelo subyacente (Claude) razona según la información que le entregues. Documenta la intención antes de pedir implementación y evitarás iteraciones costosas. Referencias útiles: Anthropic — Claude Code overview y Claude.

    Resumen rápido (lectores con prisa)

    Qué es: Una spec compacta y accionable que define comportamiento observable, diseño, tareas y criterios de aceptación para que Claude Code ejecute sin inventar.

    Cuándo usarla: Antes de pedir a un agente que implemente features o arregle bugs en un repositorio.

    Por qué importa: Minimiza suposiciones del agente, reduce iteraciones y evita parches superficiales.

    Cómo funciona: Estructura mínima: Requirements → Design → Tasks → Implementation; para bugs: Report → Analyze → Fix → Verify.

    Anatomía de una buena spec para Claude Code: estructura y propósito

    Una spec útil no es un tratado largo. Es un artefacto compacto y accionable, pensado para que un agente pueda ejecutar sin inventar. Su estructura mínima:

    1. Requirements → 2. Design → 3. Tasks → 4. Implementation

    Para bugs: Report → Analyze → Fix → Verify.

    Cada bloque reduce incertidumbre y acota el espacio de decisiones del agente.

    1. Requirements — qué debe hacer el sistema (externo)

    Define el comportamiento observable, no la implementación.

    Incluye:

    • Comportamiento nominal: qué hace la API/función.
    • Casos de borde: inputs nulos, límites, formatos erróneos.
    • Restricciones no funcionales: latencia p95 < 200 ms, tamaño máximo de payload 2 MB.
    • Dependencias permitidas/prohibidas.

    Ejemplo (sin spec vs con spec):

    Sin spec: “Crea endpoint para usuarios”.
    Con spec: “POST /users: recibe {email, name}. Valida email según RFC 5321. Inserta en PostgreSQL usando el ORM X. Devuelve 201 con {id, email, name} o 409 si email existe. No usar nuevas dependencias.”

    2. Design — cómo debe integrarse la solución (interno)

    Define firmas, modelos y patrones. Evita que el agente elija un estilo distinto al del repo.

    Incluye:

    • Firma de funciones/handlers (tipado).
    • Modelos DTO/Entity.
    • Patrones obligatorios (repositorio, servicios, inyección).
    • Efectos secundarios permitidos (logs, eventos, mutaciones).

    Plantilla mínima:

    Function: createUser(payload: CreateUserDto): Promise
    Models: CreateUserDto, UserDto, UserEntity (campos, tipos)
    Patterns: usar userRepository.insert, no acceso directo a SQL.

    3. Tasks — pasos atómicos y ordenados

    Desglosa el trabajo en tareas verificables. Un agente ejecuta mejor secuencias claras.

    Ejemplo de Tasks para feature nueva:

    1. Añadir CreateUserDto en src/models.
    2. Implementar userRepository.insert según patrón existente.
    3. Implementar handler POST /users con validación.
    4. Añadir tests unitarios (caso feliz, email duplicado, payload inválido).
    5. Actualizar documentación OpenAPI.

    Cada tarea debe producir un artefacto comprobable.

    4. Implementation — criterios de aceptación y pruebas

    Define qué significa “terminado”. No dependas solo de que compile o pase CI.

    Incluye:

    • Cobertura mínima (ej. 80% sobre módulo).
    • Tests obligatorios (unit + integración básica).
    • Requisitos de performance y seguridad.
    • Revisión arquitectónica (no introducir dependencias nuevas, mantener separaciones).

    Ejemplo: “Merge solo si tests pasan y cobertura del módulo ≥ 85%; latencia p95 < 200ms en test de integración local.”

    Flujo para bugs: Report → Analyze → Fix → Verify

    Para corrección de errores, no saltes al fix. Sigue este flujo:

    • Report: pasos reproducibles, logs, versión del commit.
    • Analyze: causa raíz documentada (por el agente o humano) con ubicación del código.
    • Fix: parche mínimo que restaure el contrato.
    • Verify: tests que confirmen el caso original y aseguren regresión negativa.

    Pedir “arregla X” sin Analyze genera parches superficiales que reaparecen.

    Ejemplos reales (comparativa rápida)

    Caso: validar emails

    Sin spec: agente instala validator.js y devuelve distinto comportamiento al estándar del proyecto.

    Con spec: “validateEmail(input: string): boolean — RFC 5321, rechaza dominios locales, no usar libs externas.” Resultado: implementación consistente y sin nuevas dependencias.

    Caso: feature auth token

    Sin spec: token store ad-hoc en memoria.

    Con spec: define AuthToken interface, TTL, almacenamiento en redis existente y tests. Resultado: integración correcta con infra existente.

    Práctica recomendada y colocación en repo

    • Coloca SPEC.md junto al test file o en la carpeta del feature.
    • Versiona la spec con el mismo PR.
    • Incluye ejemplos de I/O y criterios de aceptación textuales.
    • Si usas herramientas visuales, añade diagramas Mermaid (https://mermaid.js.org/) o contrato OpenAPI (https://spec.openapis.org/).

    Conclusión

    Claude Code puede automatizar implementaciones, pero su fidelidad depende de tu spec. La diferencia entre un parche plausible y una integración sostenible es específica: Requirements → Design → Tasks → Implementation para features; Report → Analyze → Fix → Verify para bugs. Escribe la spec antes de ejecutar al agente. Lo barato es ahorrar minutos ahora; lo caro es rehacer horas después.

    Dominicode Labs

    Si trabajas con automatización, agentes o workflows, considera recursos prácticos y experimentos en Dominicode Labs. Es una continuación lógica para explorar patrones operativos y plantillas de spec aplicables a pipelines de IA y automatización.

    FAQ

    Respuesta — ¿Qué debe contener la sección Requirements de la spec?

    Debe definir el comportamiento observable: casos nominales, bordes, restricciones no funcionales (p. ej. latencia, tamaño de payload) y dependencias permitidas o prohibidas.

    Respuesta — ¿Por qué es importante definir el Design explícitamente?

    Porque evita que el agente elija un estilo distinto al del repositorio. Definir firmas, modelos y patrones garantiza consistencia con la arquitectura existente.

    Respuesta — ¿Cómo se desglosan las Tasks de forma efectiva?

    Divídelas en pasos atómicos y ordenados que produzcan artefactos comprobables (archivos, tests, cambios en la API). Cada tarea debe ser verificable aisladamente.

    Respuesta — ¿Qué criterios deben incluirse en Implementation?

    Criterios de aceptación claros: cobertura mínima de tests, pruebas obligatorias (unit/integración), requisitos de performance y restricciones de seguridad o dependencias.

    Respuesta — ¿Cuál es el flujo recomendado para corregir bugs?

    Report (pasos reproducibles y logs) → Analyze (causa raíz y ubicación) → Fix (parche mínimo) → Verify (tests que confirmen y prevengan regresiones).

    Respuesta — ¿Dónde debo colocar la SPEC.md en el repo?

    Junto al test file o en la carpeta del feature. Versiona la spec en el mismo PR para mantener trazabilidad.

  • Cómo construir un producto de software desde cero usando IA

    Cómo construir un producto de software desde cero usando IA

    Cómo construyo un producto de software desde cero usando IA (mi proceso real)

    Tiempo estimado de lectura: 4 min

    Ideas clave

    • Construir un producto con IA es un proceso disciplinado: define el problema, escribe una spec como única fuente de verdad y deja que un agente implemente bajo revisión.
    • Spec‑Driven Development (SDD) es la columna vertebral: spec.md debe contener stack, modelado de datos, contratos API, reglas de negocio y casos de aceptación.
    • Uso un agente en terminal (Claude Code) para implementar desde el repo leyendo la spec; interactúo revisando diffs y actualizando la spec cuando cambia el comportamiento.
    • Pipelines: tests, linters y CI antes de merge; deploy en Vercel para front o infra reproducible para backend.

    Construir un producto de software desde cero usando IA no es “pedir código al chat”. Es un proceso disciplinado: idea → spec con SDD → código con Claude Code → deploy. Aquí tienes mi walkthrough real, probado en proyectos que pasaron de prototipo a producción sin incendiar la base de código.

    Resumen rápido (lectores con prisa)

    Qué es: Un proceso disciplinado que usa Spec‑Driven Development (SDD) como única fuente de verdad y un agente en terminal (Claude Code) para ejecutar la implementación bajo revisión humana.

    Cuándo usarlo: Para productos escalables y mantenibles donde la coherencia arquitectónica y la gestión de deuda técnica importan.

    Por qué importa: Evita ambigüedades, reduce deuda técnica y permite iteraciones rápidas sin romper coherencia del sistema.

    Cómo funciona: Define problema → escribe spec.md detallada → ejecuta al agente que lee el repo y la spec → revisa diffs → tests/CI → deploy.

    1) Del problema a la frontera del producto (no a la idea vaga)

    La diferencia entre una idea y un producto es la frontera: cuándo, quién, condiciones y consecuencias. Define el problema en 3–5 oraciones concretas. Quién sufre, cuándo ocurre, qué le frustra hoy y qué mediremos para saber si la solución funciona.

    Usa IA aquí como auditor: hazle preguntas para descubrir supuestos y casos edge. Pero no le pidas código aún. Resultado: una descripción del problema que cualquier dev pueda leer en frío y entender.

    2) Escribir la spec: Spec‑Driven Development (SDD)

    SDD es la columna vertebral. Antes de una sola línea de código:

    • Crea spec.md en el repo. Será la única fuente de verdad.
    • Incluye stack exacto (ej.: Next.js 16, React 19, Tailwind 4).
    • Modelado de datos: tablas, campos, relaciones, índices y restricciones.
    • Contratos API: endpoints, payloads, respuestas, errores y códigos HTTP.
    • Reglas de negocio claras: qué está permitido y qué nunca.
    • Casos de prueba de aceptación (no tests automatizados, sino escenarios).

    La spec elimina ambigüedad. Si algo no está en la spec, no existe para el agente.

    Recurso práctico: Spec-Driven Development

    3) Implementación con Claude Code (agente en terminal)

    Claude Code vive en la terminal, lee archivos y puede ejecutar comandos. No es un chat: es un agente con acceso al repo.

    Flujo estándar

    1. git init + estructura base según spec.md.
    2. Llamada inicial al agente con instrucción precisa:
    Claude Code (Anthropic).
    3. Reviso los diffs que propone como si fueran PRs. Aprobación explícita o feedback.
    4. Si hay cambio de comportamiento, actualizo spec.md y pido refactor.

    Regla innegociable: nunca corregir código sin actualizar la spec. Corrige la spec, suprime la ambigüedad, manda refactor. Así el agente aprende reglas permanentes del proyecto.

    Ejemplo de prompt maestro (simplificado): “Contexto: repo vacío, spec.md adjunto. Tarea: implementar la API de autenticación según spec. Antes de modificar, lista ambigüedades. Compara con stack y patrones del repo.”

    4) Tests, CI y deploy

    El código sigue buenas prácticas: tests unitarios básicos, linters y pipelines en GitHub Actions. Deploy en Vercel para front o en un VPS/Cloud con infra reproducible para backend.

    Pipeline típico:

    • PR generado por agente → revisión humana → GitHub Actions (lint, test) → merge → deploy.

    Cuando necesito añadir features: actualizo spec.md, ejecuto al agente con el repo y la spec actualizada. El contexto persistente evita “olvidos” que generan deuda técnica.

    Buenas prácticas operativas (evitan dolor después)

    • Versiona spec.md. Cada cambio debe tener justificación y número de versión.
    • Usa ejemplos concretos en la spec (payloads de ejemplo, respuestas de error).
    • Limita el scope por iteración. Un sprint = 1–2 features bien especificadas.
    • Rechaza cambios grandes mediante parches rápidos: si la spec cambia radicalmente, crea una rama de arquitectura.
    • Mantén un humano con criterio técnico revisando cada PR del agente.

    Cuándo usar este proceso (y cuándo no)

    Úsalo si necesitas un producto escalable, con datos complejos o que deba mantenerse en el tiempo. No lo burocratices para un script de 100 líneas o un prototipo desechable: ahí el prompt‑driven rápido sigue siendo válido.

    Esto no es un truco mágico: es disciplina. La IA ejecuta, pero la arquitectura y el criterio técnico siguen en tus manos. Si mantienes la spec como la fuente única de verdad y tratas al agente como un colaborador que trabaja sobre ese contrato, podrás iterar rápido sin destruir la coherencia del sistema. Esto es solo la base: la próxima iteración debe cubrir cómo redactar specs resistentes y ejemplos prácticos de prompts maestro para Claude Code.

    Si trabajas en automatización, agentes o workflows, este enfoque encaja con iniciativas prácticas de investigación y experimentación de herramientas y procesos. Sigue explorando en Dominicode Labs como continuación lógica para prototipado y validación de pipelines con agentes.

    FAQ

    ¿Qué es Spec‑Driven Development (SDD)?

    SDD es un marco donde una spec.md actúa como la única fuente de verdad para el desarrollo. Define stack, modelos de datos, contratos API, reglas de negocio y casos de aceptación antes de escribir código.

    ¿Por qué usar un agente en terminal como Claude Code?

    Porque puede leer el repo, ejecutar comandos y proponer cambios como si fueran PRs. Esto permite automatizar implementaciones repetibles mientras el humano revisa y guía el resultado.

    ¿Qué debe contener spec.md?

    Debe incluir stack exacto, modelado de datos (tablas, campos, relaciones), contratos API (endpoints, payloads, respuestas y errores), reglas de negocio y casos de aceptación con ejemplos concretos.

    ¿Cómo se gestionan los cambios de comportamiento?

    Actualiza spec.md y crea un refactor controlado. Nunca corrijas código sin primero cambiar la spec. Esto mantiene la coherencia y enseña al agente las reglas permanentes del proyecto.

    ¿Cuándo no aplicar este proceso?

    No lo burocratices para scripts pequeños o prototipos desechables (por ejemplo, un script de ~100 líneas). En esos casos, un enfoque prompt‑driven rápido es más eficiente.

    ¿Qué herramientas de CI/Deploy recomiendas?

    Usa pipelines en GitHub Actions para lint y tests, y Vercel para frontends. Para backends, despliega en VPS/Cloud con infraestructura reproducible según la spec.

  • Cómo monitorear efectivamente agentes de IA en producción

    Cómo monitorear efectivamente agentes de IA en producción

    Cómo monitorear tus agentes de IA en producción

    Tiempo estimado de lectura: 5 min

    Ideas clave

    • Instrumentación desde el día 0: traces y spans que representen sesiones completas y decisiones individuales.
    • Métricas triples: rendimiento (TTFT, percentiles), coste (tokens/coste por span/sesión) y calidad (feedback y señales automáticas).
    • Elegir plataforma según arquitectura: LangSmith para stacks centrados en LangChain; Langfuse (+ ClickHouse) para portabilidad y escala.
    • Cultura operacional: versionado de prompts, tests de regresión y despliegue progresivo son obligatorios.

    Cómo monitorear tus agentes de IA en producción debería ser la primera conversación del equipo antes de lanzar una beta. Si no instrumentas traces, spans, costes y calidad desde el día 0, tu siguiente sprint será apagar fuegos y explicar facturas inexplicables.

    Este artículo explica el diseño mínimo de observabilidad para agentes (LLM Observability), las métricas que importan y las decisiones tecnológicas prácticas entre plataformas como Langfuse y LangSmith. Incluye enlaces directos a recursos: Langfuse, LangSmith y ClickHouse.

    Resumen rápido (lectores con prisa)

    Qué es: Observabilidad para agentes de IA: traces distribuidos y spans que capturan prompts, llamadas a LLM, búsquedas vectoriales y tool calls.

    Cuándo usarlo: desde el día 0 en cualquier beta u ambiente productivo que use agentes/LLMs.

    Por qué importa: APMs tradicionales no detectan fallos semánticos ni picos de coste por tokens.

    Cómo funciona (resumen): instrumenta spans por acción, mide rendimiento/coste/calidad, y almacena traces para query analítica y alertas.

    Principio: los APM tradicionales no son suficientes

    APM como Datadog o Prometheus miden latencia HTTP, errores y consumo de CPU. Perfecto para servicios deterministas. Un agente de IA devuelve HTTP 200 y puede a la vez fabricar información falsa, ejecutar llamadas externas y disparar costes por token. En ese escenario, el APM dice “todo bien” mientras tu soporte recibe tickets.

    Necesitas telemetría diseñada para flujos probabilísticos: rastreo distribuido con traces que representen sesiones completas y spans que documenten cada decisión y llamada (LLM, búsqueda vectorial, tool calls, llamadas externas).

    Traces y spans: la unidad mínima de diagnóstico

    Diseña cada interacción como un trace. Cada acción —prompts, retrievals, llamadas a herramientas, transformaciones— es un span con metadata.

    Trace: session_42
    ├─ Span 1: receive_prompt (userId=42, promptHash=…)
    ├─ Span 2: vector_search (index=kb_v1, hits=3, latency=320ms)
    ├─ Span 3: LLM_call (model=gpt-4o, tokens_in=1800, tokens_out=120, cost=$0.012)
    └─ Span 4: synthesize_response (format=short-answer)

    Con esto puedes responder rápido: ¿por qué tardó 12s? ¿qué span generó el mayor coste? ¿qué prompts producen más fallos semánticos?

    Métricas imprescindibles (no negociables)

    Rendimiento

    • Time to First Token (TTFT): impacto directo en la UX.
    • Latencia por span y percentiles: p50 / p95 / p99 por tipo de span.

    Coste

    • Tokens y coste por span: calcular coste por span y por session/userId.
    • Coste acumulado por workflow: agente que llama al LLM varias veces debe sumar costes por workflow.
    • Alertas de coste: activar alertas cuando una sesión supera un umbral definido.

    Calidad

    • Feedback explícito: thumbs up/down ligado al trace.
    • Señales implícitas: tiempo de interacción, copias realizadas.
    • LLM-as-a-judge: usar un modelo más económico para evaluar respuestas automáticamente como señal de calidad (no como veredicto absoluto).

    Langfuse vs LangSmith: criterio técnico para elegir

    LangSmith es excelente si tu stack está centrado en LangChain/LangGraph: integración out-of-the-box, datasets de evaluación y UI lista para depurar agentes complejos. El coste es acoplamiento: extraer datos o migrar a otro sistema será costoso.

    Langfuse es agnóstico y open source; se integra con llamadas directas a APIs, Vercel AI SDK, n8n, etc. La reciente incorporación de ClickHouse al ecosistema refuerza su escalabilidad analítica: consultas sobre millones de traces con latencias bajas y análisis de coste en tiempo real. Si prevés escala o necesitas evitar vendor lock-in, Langfuse+ClickHouse es una apuesta sólida.

    Decisión práctica

    • Si dependes de LangChain → LangSmith.
    • Si buscas portabilidad, alto throughput analítico y autoalojamiento → Langfuse (+ ClickHouse).

    Implementación práctica: checklist mínimo viable

    1. Wrap de llamadas al LLM: envuelve cada llamada con un SDK de observabilidad (Langfuse/LangSmith) que capture prompt, model, tokens, cost y versión del prompt.
    2. Correlación: adjunta userId, sessionId y deployment/version tags a cada trace.
    3. Ignorar ruido: no envíes node_modules, logs grandes o secretos. Usa reglas de exclusión (.lfignore / .langsmith-ignore).
    4. Costeo por sesión: suma tokens y coste por sessionId y expón dashboards con coste por feature o cliente.
    5. Evaluación automatizada: configura un pipeline de “LLM-as-a-judge” para marcar respuestas sospechosas y crear datasets de retraining.
    6. Sandboxing y alertas: ejecuta tool calls en entornos aislados y genera alertas cuando spans ejecutan operaciones potencialmente destructivas.
    7. Auditoría y retenimiento: guarda prompts y respuestas (con enmascarado si hay datos sensibles) para reproducibilidad y cumplimiento.

    Operación y cultura: monitoreo como contrato

    No es sólo técnica: es proceso. Cada cambio en prompts o pipelines debe ir acompañado de: etiquetas de versión, tests de regresión en datasets de evaluación y despliegue progresivo (canary). Sin estos pasos, la observabilidad será un registro pasivo en lugar de un control activo.

    La regla final es simple: ningún agente a producción sin traces, coste por session y un mecanismo automático de evaluación. Si ignoras eso, no estás operando IA; estás apostando.

    Implementa observabilidad desde el primer sprint, usa Langfuse o LangSmith según tu arquitectura y organiza tus dashboards en rendimiento, coste y calidad. La visibilidad no es un lujo: es la única forma de mantener agentes de IA útiles, seguros y rentables en producción.

    Para equipos que construyen flujos, agentes o automatizaciones, una referencia práctica y recursos adicionales están disponibles en Dominicode Labs. Es una continuidad natural para explorar integración, pipelines de evaluación y despliegue controlado en proyectos de IA aplicada.

    FAQ

    ¿Por qué los APM tradicionales no detectan problemas de agentes de IA?

    Porque miden señales infraestructurales (HTTP, CPU, errores) pero no la veracidad semántica ni el consumo de tokens. Un agente puede devolver HTTP 200 y producir contenido incorrecto o costoso.

    ¿Qué debe contener un span para ser útil?

    Metadata mínima: tipo de acción (prompt, search, tool call), timestamps, latencia, modelo, tokens_in/tokens_out, coste estimado, userId/sessionId y versión del prompt.

    ¿Cómo calcular el coste por sesión?

    Suma los tokens y el coste asociado de todos los spans pertenecientes al mismo sessionId. Agrupa por workflow o por cliente para dashboards y alertas.

    ¿Cuándo elegir LangSmith sobre Langfuse?

    Elige LangSmith si tu stack está fuertemente integrado con LangChain/LangGraph y aprecias integración out-of-the-box. Evita si necesitas portabilidad o evitar vendor lock-in.

    ¿Qué es LLM-as-a-judge y para qué sirve?

    Es usar un modelo más económico para evaluar respuestas automáticamente como señal de calidad. Sirve para priorizar revisiones humanas y construir datasets de retraining, pero no debe ser el veredicto final.

    ¿Qué datos debo enmascarar al guardar prompts?

    Enmascara datos sensibles: PII, credenciales, secretos y cualquier información regulada. Guarda versiones y hashes cuando sea posible para reproducibilidad sin exposición directa.

  • Cómo estructurar patrones de indicaciones para Claude Code

    Cómo estructurar patrones de indicaciones para Claude Code

    Patrones de indicaciones, memoria, estructura del proyecto, subagentes, habilidades para Claude Code

    Tiempo estimado de lectura: 5 min

    • Ideas clave:
    • Claude Code necesita prompts estructurados y deterministas para operar de forma segura y efectiva.
    • Una memoria explícita (ej. CLAUDE.md) y una estructura de repo modular son indispensables.
    • Orquestar subagentes (p. ej. con n8n) reduce riesgo y carga cognitiva del agente principal.
    • Control estricto de habilidades (tool use) y entornos sandbox evita daños en producción.

    Introducción

    Patrones de indicaciones, memoria, estructura del proyecto, subagentes y habilidades para Claude Code son los cinco pilares que determinan si un agente CLI acelera tu ingeniería o genera deuda técnica silenciosa. Si no defines cómo hablarle, qué puede recordar, cómo está organizado el repo, cómo se subdividen las tareas y qué permisos tiene, Claude actúa a ciegas. Aquí tienes una guía práctica y accionable para poner orden.

    Resumen rápido (lectores con prisa)

    Claude Code es un operador que modifica código y ejecuta shells; requiere prompts deterministas, una memoria persistente en raíz (p. ej. CLAUDE.md), una estructura de repo modular, subagentes/orquestación para QA y control estricto de habilidades. Usa TDD y sandboxes antes de delegar cambios en producción.

    Claude Code como operador

    Claude Code no es un chatbot; es un operador que puede leer y modificar tu código, ejecutar shells y (en previews) automatizar UIs. La diferencia clave: requiere prompts estructurados, memoria explícita del proyecto, una arquitectura de repositorio que el agente pueda razonar, subagentes u orquestadores para tareas auxiliares y un control estricto de habilidades (tool use). Documentación útil: docs.anthropic — Claude Code y, para orquestación, n8n. Para novedades y previews (p. ej. Computer Use) revisa releasebot.dev.

    1) Patrones de indicaciones — cómo pedirle cosas a Claude Code

    No escribas prompts vagos. Usa plantillas deterministas:

    Patrón Contexto‑Restricción‑Acción

    Contexto: qué módulo, stack, rama. (“Servicio payments — Node.js/TS — branch feat/rate-limit”)

    Restricción: reglas innegociables. (“No tocar DB schema; no añadir deps externas”)

    Acción: objetivo con criterio verificable. (“Implementa rate limiting y añade tests que cubran 429; PR con test passing en CI es criterio de éxito”)

    Prompt de TDD (Test-Driven Prompting)

    – Paso 1: “Escribe el test que debería fallar”

    – Paso 2: pedir ejecución del test

    – Paso 3: solicitar la implementación hasta que los tests pasen

    Ejemplo de prompt (compacto):

    “Contexto: /services/payments, Node 18, TS. Restricción: no tocar migraciones. Acción: añade rate limiter en /api/charge; escribe tests unitarios y de integración; criterio: pipeline CI verde. Empieza por crear tests que fallen.”

    2) Memoria — cómo mantener contexto útil y persistente

    Claude Code construye su contexto leyendo el repo; no tiene intuición humana. Dos mecanismos clave:

    • Memoria de sesión (corto plazo): archivos abiertos y árbol activo. Evita saturarla con monorepos gigantes; abre solo lo necesario.
    • Memoria persistente (largo plazo): un archivo en la raíz que Claude lee siempre. Recomendación práctica:

    CLAUDE.md o .clauderc con:

    • Convenciones de estilo y nomenclatura
    • Comandos claves (tests, build, dev)
    • ADRs esenciales
    • Dependencias permitidas/prohibidas
    • Checklists de seguridad y compliance

    Este archivo convierte normas humanas en reglas ejecutables por el agente y reduce ambigüedad.

    3) Estructura del proyecto — diseño para agentes

    Diseña el repo pensando en unidades pequeñas y autocontenidas:

    • Modularidad: archivos <300 líneas, responsabilidades únicas.
    • Rutas semánticas: /auth/use-cases/login.ts en vez de /utils/helper9.ts.
    • Tipado estricto: TypeScript/Rust/Go ayudan al agente a validar cambios antes de ejecutarlos.
    • Tests como contrato: TDD + coverage mínimo hacen al agente predecible.

    Si el repo es un monolito acoplado, prioriza una fase de refactor (extract module) manual antes de delegar en agentes.

    4) Subagentes y orquestación — dividir para no perder contexto

    Claude Code aún no gestiona subagentes complejos de forma nativa. La práctica efectiva es orquestar subagentes externos:

    – Usa n8n o un orquestador propio para:

    • Ejecutar análisis estático en entornos aislados
    • Lanzar pipelines de seguridad y escaneo de dependencias
    • Devolver reportes al CLI para que Claude actúe sobre ellos

    Patrón típico:

    1. Claude genera un PR provisional.
    2. n8n ejecuta linters, SCA y tests en una VM sandbox.
    3. Resultado vuelve al CLI; Claude corrige y reitera.

    Así evitas que un único agente cargue demasiado contexto o tome decisiones incompletas.

    5) Habilidades (Tool Use) — permisos y límites

    Define explícitamente qué puede ejecutar el agente. Habilidades críticas:

    • Bash Execution: npm test, git, docker-compose — imprescindible para feedback real.
    • File System Access: lectura/escritura de archivos.
    • Semantic Search / Repo Index: para referencias cruzadas antes de modificar.
    • (Preview) Computer Use: interacción con UIs nativas — potente, frágil y debe usarse solo en sandboxes.

    Regla de oro: nunca habilites habilidades destructivas en máquinas con credenciales reales. Usa contenedores o VMs aisladas.

    Checklist mínimo de adopción antes de delegar tareas

    1. CLAUDE.md en raíz con políticas y comandos.
    2. Tests automatizados que sirvan de contrato.
    3. Entorno sandbox (Docker/VM) para ejecución.
    4. CI que valide PRs generados por el agente.
    5. Orquestador (n8n o similar) para subagentes de QA/security.
    6. Prompts basados en Contexto‑Restricción‑Acción y TDD.

    Conclusión

    Patrones de indicaciones, memoria, estructura del proyecto, subagentes y habilidades para Claude Code no son conceptos teóricos: son requisitos operativos. Implementados juntos, convierten a Claude en un multiplicador de capacidad. Si fallas en cualquiera, el agente acelera errores, no entrega. Empieza por documentar: CLAUDE.md, tests firmes y sandboxes. Luego automatiza, orquesta y vigila. Esto no acaba aquí: quien domine estas cinco piezas tendrá ventaja real al escalar agentes en ingeniería.

    Dominicode Labs

    Para equipos que integran automatización y orquestación de subagentes como parte de su plataforma de ingeniería, una continuación natural es explorar herramientas y patrones documentados en Dominicode Labs. La referencia ayuda a unir prácticas de prompts, memoria y sandboxes con flujos de trabajo reproducibles.

    FAQ

    ¿Qué es Claude Code y en qué se diferencia de un chatbot?

    Claude Code es un operador diseñado para leer y modificar repositorios, ejecutar comandos de shell y automatizar tareas. A diferencia de un chatbot, espera prompts estructurados y tiene habilidades (tool use) que deben definirse y limitarse explícitamente.

    ¿Qué debe contener un archivo CLAUDE.md?

    Debe incluir convenciones de estilo, comandos claves (tests/build/dev), ADRs importantes, dependencias permitidas/prohibidas y checklists de seguridad. Su propósito es convertir reglas humanas en referencia legible por el agente.

    ¿Cuándo debo usar subagentes u orquestadores?

    Úsalos cuando el pipeline requiera aislamiento (análisis estático, SCA, pruebas en sandbox) o cuando el agente principal necesite retroalimentación externa antes de cometer cambios. Orquestadores como n8n facilitan este patrón.

    ¿Qué habilidades del agente debo deshabilitar en producción?

    Deshabilita cualquier ejecución con acceso a credenciales reales o capacidad destructiva directa sobre entornos de producción. Mantén ejecución de bash y acceso a filesystem solo en contenedores/VMs aisladas.

    ¿Cómo aplicar TDD con Claude Code?

    Sigue el patrón: pide primero tests que fallen, ejecuta tests en sandbox, luego solicita la implementación hasta que los tests pasen. Define criterios de éxito claros (por ejemplo, pipeline CI verde) en el prompt.

    ¿Por qué modularizar archivos en <300 líneas?

    Archivos pequeños y responsabilidades únicas facilitan que el agente razone sobre cambios y reduzcan el riesgo de efectos colaterales imprevistos.

    ¿Qué papel juega CI en el flujo con agentes?

    CI actúa como guardián: valida PRs generados por el agente, ejecuta tests y linters y evita que cambios automatizados lleguen a producción sin verificación.

  • Implementando Claude Code para la automatización de desarrollo en Angular y NestJS

    Implementando Claude Code para la automatización de desarrollo en Angular y NestJS

    Claude Code como herramienta diaria de desarrollo

    Tiempo estimado de lectura: 5 min

    • Orquestación de tareas multi-archivo y ejecución de CLI para migraciones, generación de boilerplate y correcciones automáticas.
    • Requiere contexto persistente (ej. archivo CLAUDE.md) para evitar alucinaciones y errores arquitectónicos.
    • Útil para flujos repetibles y tests automatizados; no ideal para retoques UI o tareas atómicas simples.

    Resumen rápido (lectores con prisa)

    Claude Code es un agente orientado a orquestar tareas que implican múltiples archivos y ejecución de CLI. Úsalo cuando necesites migraciones, generación de boilerplate, tests y correcciones automáticas a partir de stack traces. No es la mejor opción para escribir una sola función o pulir UI.

    Por qué usar (o no) Claude Code en tu flujo diario

    Claude Code Claude Code está pensado para tareas que van más allá del autocompletado: migraciones, generación de boilerplate, tests y correcciones automáticas tras detectar fallos en la terminal. No es mejor que Copilot para escribir una función; es más útil cuando la tarea implica múltiples archivos y ejecución de CLI.

    Ventajas reales:

    • Orquestación multi-archivo y ejecución de comandos.
    • Correcciones automáticas tras leer stack traces.
    • Generación de tests y refactors repetibles.

    Limitaciones reales:

    • Consumo alto de contexto/token en sesiones largas.
    • Riesgo de sobreescritura si la instrucción es ambigua.
    • Posible bucle de corrección ante errores complejos.

    Decisión simple: úsalo para tareas de orquestación; no para retoques visuales ni diseño fino de UI.

    Preparación: cómo darle contexto al agente

    Sin contexto, el agente alucina. La práctica que funciona es tener un archivo de contexto que el agente lea antes de actuar. Crea CLAUDE.md en la raíz:

    # CLAUDE: reglas del repo
    Stack:
    - Backend: NestJS 10 (TypeScript estricto)  https://nestjs.com/
    - Frontend: Angular 17 (standalone components, Signals)  https://angular.io/
    
    Convenciones:
    - DTOs con class-validator
    - Servicios inyectados por constructor
    - Componentes standalone, sin NgModules
    - Commits en Conventional Commits
    

    Ese archivo actúa como prompt persistente. Reduce alucinaciones arquitectónicas y mejora resultados.

    Tutorial práctico: flujo real con NestJS y Angular

    Objetivo: crear recurso Products en backend (NestJS) y consumirlo desde Angular, con tests básicos.

    1) Generar recurso en NestJS

    En la carpeta del backend:

    # instrucción al agente
    claude "Lee CLAUDE.md. Genera recurso Products en NestJS: Controller, Service, DTO CreateProductDto con class-validator. Ejecuta npm run build y corrige errores."
    

    Qué hará:

    • Ejecutará nest g res products o creará manualmente los archivos.
    • Insertará DTOs con validaciones (@IsString, @IsNumber).
    • Ejecutará npm run build; si TypeScript falla, leerá el stack trace y aplicará correcciones iterativas.

    Ejemplo mínimo de DTO que el agente debe crear:

    // create-product.dto.ts
    import { IsString, IsNumber } from 'class-validator';
    export class CreateProductDto {
      @IsString()
      name: string;
    
      @IsNumber()
      price: number;
    }
    

    2) Consumir endpoint desde Angular

    En la carpeta del frontend:

    claude "Crea ProductService usando provideHttpClient y un componente ProductFormComponent standalone. Usa Signals para estado de formulario. Ejecuta ng build y corrige tipados."
    

    Qué esperar:

    • Creación de product.service.ts con funciones que llaman al endpoint.
    • ProductFormComponent standalone con Signals para isLoading y errors.
    • ng build que verifica tipado y dependencias; el agente corrige importaciones o tipos si hay fallos.

    Fragmento esperado en Angular:

    // product.service.ts (simplificado)
    import { inject } from '@angular/core';
    import { HttpClient } from '@angular/common/http';
    export const ProductService = () => {
      const http = inject(HttpClient);
      return {
        create: (payload: any) => http.post('/api/products', payload)
      };
    };
    

    3) Generar tests automatizados

    Comando recomendado:

    claude "Genera tests Jest para products.service.ts y products.controller.ts. Ejecuta npm run test y corrige mocks hasta que la suite pase."
    

    Valor: te ahorra el 70% del trabajo repetitivo de mocks y boilerplate.

    Riesgos y contramedidas operativas

    1. Trabaja siempre en una rama aislada:
      git checkout -b feat/claude-codex
      – Nunca en main o develop.
    2. Limita la ventana de contexto:
      – Corta sesiones largas. Ejecuta tareas atómicas y revisa resultados antes de continuar.
    3. Evita permisos globales de escritura en archivos sensibles:
      – Usa .claudeignore para bloquear rutas (si la herramienta lo soporta) o un wrapper que restrinja paths.
    4. Plan para fallos en node_modules:
      – Si entra en bucle, interrumpe y ejecuta npm ci o reinstala dependencias; luego reintenta con más contexto.

    Checklist para adopción en equipo

    • [ ] CLAUDE.md con convenciones del repo.
    • [ ] Branching obligatorio para sesiones de agente.
    • [ ] Scripts de CI que validen outputs generados por el agente.
    • [ ] Monitoreo de consumo de API/tokens.
    • [ ] Política interna para revisar commits automáticos antes de merge.

    Claude Code no es una varita mágica; es una herramienta poderosa si la gobiernas. Si empiezas documentando el proyecto y limitando sus permisos, te dará horas de productividad en tareas repetitivas y orquestación. Si no, corregirás borradores y rollbacks a mano. La diferencia está en las reglas y la disciplina.

    Relacionado: visita Dominicode Labs para ver experimentos y guías sobre agentes y automatización. Esta mención encaja como continuación lógica para equipos que exploran flujos de IA aplicada y agentes.

    FAQ

    ¿Qué es Claude Code y para qué sirve?

    Claude Code es un agente diseñado para orquestar tareas que implican múltiples archivos y comandos de terminal: migraciones, generación de boilerplate, tests y correcciones automáticas tras fallos. Es especialmente útil cuando la tarea requiere ejecutar CLI y aplicar cambios iterativos.

    ¿Cuándo debería usar Claude Code en lugar de Copilot?

    Usa Claude Code cuando la tarea sea multi-archivo, requiera ejecución de comandos o correcciones a partir de stack traces. Para pequeñas funciones o autocompletado local, Copilot suele ser más eficiente.

    ¿Cómo debo preparar mi repo antes de usar el agente?

    Crea un archivo de contexto persistente (por ejemplo CLAUDE.md) con stack, convenciones y reglas del repo. Trabaja en una rama aislada y asegúrate de tener scripts de CI que validen cambios automáticos.

    ¿Qué riesgos operativos debo mitigar?

    Principales riesgos: sobreescritura de archivos, consumo excesivo de tokens en sesiones largas y bucles de corrección. Mitígalo con ramas aisladas, límites de sesión y mecanismos para restringir paths sensibles (por ejemplo .claudeignore o wrappers).

    ¿Cómo integro tests automatizados en el flujo del agente?

    Pide al agente generar tests Jest para servicios y controladores, ejecutar npm run test y corregir mocks hasta que la suite pase. Complementa con scripts de CI que validen los cambios generados antes del merge.

    ¿Qué hacer si el agente entra en bucle de correcciones?

    Interrumpe la sesión, ejecuta npm ci o reinstala dependencias, revisa el contexto y reintenta con instrucciones más atómicas y detalladas. Limitar la ventana de contexto también ayuda a evitar bucles.

  • Cómo mejorar la calidad del código con Spec-Driven Development

    Cómo mejorar la calidad del código con Spec-Driven Development

    Spec-Driven Development en la práctica: del prompt al código mantenible — Un walkthrough real mostrando cómo una buena spec cambia la calidad del output de Claude Code o Cursor. Caso antes/después

    Tiempo estimado de lectura: 6 min

    • Ideas clave:
    • Una spec técnica reduce la ambigüedad en prompts y convierte salidas generativas en contratos verificables.
    • Sin spec, los LLMs tienden a producir código rápido pero frágil y con deuda técnica.
    • Una spec mínima (stack, artefactos, contratos, edge cases) es suficiente para outputs reproducibles y testeables.
    • Integra specs en CI/PR para automatizar comprobaciones y mantener control humano sobre arquitectura.

    Spec-Driven Development en la práctica: del prompt al código mantenible — esto no es una etiqueta elegante. Es la diferencia entre código que sobrevive y código que tendrás que reescribir dentro de tres sprints. Si usas Claude Code, Cursor o cualquier herramienta generativa, sin una spec clara estás empujando decisiones arquitectónicas a un modelo estadístico.

    En estas primeras líneas: definimos el problema, mostramos un caso antes/después y entregamos una receta práctica para que tu equipo obtenga salidas reproducibles y revisables por humanos.

    Resumen rápido (lectores con prisa)

    Qué es: Una spec técnica es un documento corto que define stack, artefactos, contratos de datos y criterios de aceptación.

    Cuándo usarla: Antes de pedirle a un LLM que genere código o acciones automáticas; imprescindible para features que afectan arquitectura o seguridad.

    Por qué importa: Reduce ambigüedad, limita el espacio de decisión del modelo y convierte output en un contrato auditables y testeable.

    Cómo funciona: Provee stack y contratos (ej. Zod schemas, tipos TS, API contracts) que el agente implementa exactamente, produciendo artefactos modulares y testeables.

    Por qué una spec cambia todo

    Los LLMs son excelentes en patrones, no en contexto de producto. Cuando reciben un prompt abierto, generan la solución más probable según su entrenamiento: ejemplos de tutoriales y antipatrón comunes. Esa es la razón por la que el output suele ser rápido pero frágil.

    Una especificación técnica (spec) reduce el “espacio de probabilidad” del modelo. Le das:

    • el stack exacto,
    • las restricciones arquitectónicas,
    • los contratos de datos,
    • y los criterios de aceptación/edge cases.

    Con esa entrada, herramientas como Cursor o Claude dejan de improvisar y comienzan a implementar un contrato.

    Walkthrough real: formulario de registro en Next.js

    Escenario: crear un registro de usuario con validación Zod y Server Actions (Next.js App Router). Te muestro el antes y el después, sin adornos.

    Antes — Prompt conversacional (vibe coding)

    Prompt enviado al modelo:

    “Crea un formulario de registro en Next.js con email, password y confirmación. Conéctalo a la API.”

    Salida típica:

    • Un solo archivo RegisterForm.tsx con JSX, estado useState y fetch mezclados.
    • Validación DIY con regex.
    • Manejo de errores = console.log.
    • Tipos débiles (any o sin tipos).
    • No hay tests ni contractos reutilizables.

    Resultado: funciona en local. Falla en producción. Es deuda técnica con firma.

    Después — Prompt con spec (Spec-Driven Development)

    Antes de preguntar al modelo, escribes spec-auth-register.md y lo adjuntas.

    Fragmento de spec:

    # Spec: Registro de usuario
    Stack: Next.js App Router, React Hook Form, Zod
    Outputs: 3 archivos
      - src/lib/validations/auth.ts (registerSchema)
      - src/actions/auth.actions.ts (Server Action) -> devuelve { success: boolean; error?: string }
      - src/components/auth/RegisterForm.tsx
    UI: usar useTransition para isPending; mostrar errores por campo; redirigir a /dashboard en éxito.
    Edge cases: handling de timeouts, duplicados, validación server-side.
    

    Prompt al modelo:

    “Lee @spec-auth-register.md e implementa exactamente los archivos descritos, respetando tipos y contratos.”

    Salida típica con spec:

    • registerSchema en auth.ts (Zod) reutilizable en cliente y servidor.
    • Server Action tipada que devuelve { success, error }.
    • Componente de presentación que usa React Hook Form y solo hace binding.
    • Estados de UI y manejo de errores explícito.
    • Código modular, testeable y legible.

    La diferencia es clara: la spec obliga al modelo a ceñirse a un contrato verificable. Lo que se genera se puede code-reviewar, testear e integrar.

    Plantilla mínima de spec que funciona

    No necesitas escribir una novela. Esta plantilla (portable en .specs/feature.md) es suficiente:

    1. Contexto de negocio (1-2 líneas).
    2. Stack y restricciones (libraries permitidas/prohibidas).
    3. Artefactos esperados (files + path).
    4. Contratos de datos (TS interfaces o Zod schemas).
    5. Estados UI y criterios de aceptación.
    6. Edge cases y métricas de éxito.

    Incluye URLs útiles en la spec para librerías: Zod, OWASP para seguridad, documentación de Cursor si lo usas.

    Integración práctica en el flujo de trabajo

    • Guarda specs en .specs/ y referencia el archivo en el prompt (Cursor soporta @Files).
    • Automatiza comprobaciones básicas con linters/CI: que exista un schema Zod, que acciones devuelvan un tipo estándar, que tests unitarios pasen.
    • Añade una regla en code review: si el cambio viene de un agente, el PR debe acompañar la spec original y un ADR si la modificación afecta arquitectura.
    • No olvides observabilidad y testing: cada tool o action generada debe tener tests unitarios independientes del LLM.

    Conclusión: la IA ejecuta, el ingeniero decide

    Spec-Driven Development no elimina la IA; la pone en su lugar. En lugar de confiar en la creatividad del modelo, confías en el criterio técnico del equipo para dirigirlo. Los equipos que adoptan specs claras convierten a Claude Code y Cursor en herramientas productivas en lugar de fuentes de deuda técnica. Implementar specs no es una carga extra: es la inversión que transforma prototipos de IA en software mantenible y auditable.

    La siguiente pieza en esta serie mostrará ejemplos de specs reales y scripts de CI que validan la conformidad automática entre spec y código.

    Para continuidad con iniciativas de automatización y prácticas de ingeniería aplicadas a IA, revisa recursos adicionales y experimentos en Dominicode Labs. Estos materiales complementan la adopción de specs y proporcionan plantillas y scripts para integrar comprobaciones automatizadas en CI/PR.

    FAQ

     

    ¿Qué es una spec técnica y cuánto debe medir?

    Una spec técnica es un documento conciso que define contexto, stack, artefactos requeridos, contratos de datos y criterios de aceptación. Suele medir entre 1 y 2 páginas; la clave es ser suficiente para convertir decisiones arquitectónicas en reglas ejecutables.

     

    ¿Qué diferencia hay entre una spec y una historia de usuario?

    Una historia de usuario describe el problema de negocio y la necesidad. La spec técnica traduce esa necesidad en artefactos técnicos concretos (files, tipos, contratos, edge cases) que un agente o desarrollador implementará.

     

    ¿Qué herramientas debo pedir en la spec para validación de datos?

    Especifica la librería (por ejemplo, Zod), el archivo donde residirá el schema y el contrato de retorno esperado para server actions. Indica validación client/server y casos límite relevantes.

     

    ¿Cómo integro specs en CI?

    Automatiza comprobaciones que verifiquen la presencia de schemas Zod, la firma de acciones y tests unitarios mínimos. Añade una regla en PRs que requiera la spec original cuando cambios provengan de un agente.

     

    ¿Qué hacer si el LLM ignora la spec?

    Ajusta el prompt para referenciar explícitamente la spec (ej. @spec-auth-register.md), valida output contra tests automatizados y rechaza cambios que no cumplan contratos en CI. Mantén revisión humana obligatoria para PRs generados por agentes.

  • Claude Opus 4.8: novedades para desarrolladores (Claude Code, Effort Control y más)

    Claude Opus 4.8: novedades para desarrolladores (Claude Code, Effort Control y más)

    Anthropic acaba de lanzar Claude Opus 4.8, y ellos mismos lo describen como una mejora “modesta” sobre Opus 4.7. Es una descripción honesta, pero engañosa: las mejoras de calidad de vida son justo las que más se notan cuando trabajas con esto todos los días.

    En este artículo voy directo a lo que importa si programas: qué cambia de verdad, qué es marketing, y cómo encaja en un flujo de trabajo serio.

    Qué es Opus 4.8 en una frase

    Opus 4.8 reemplaza a 4.7 dentro de la misma familia de modelos. Mismo precio, pero más fiable y con mejor criterio cuando trabaja en modo agente. El identificador del modelo en la API es claude-opus-4-8.

    La jugada interesante de este lanzamiento no es el modelo en solitario, sino lo que Anthropic construyó alrededor de él. Vamos por partes.

    1. Dynamic Workflows en Claude Code

    Esta es la novedad grande, y de momento está en research preview.

    Claude Code ahora puede planificar una tarea de gran tamaño, lanzar cientos de subagentes en paralelo dentro de una misma sesión, verificar sus propios resultados y recién entonces reportarte. El ejemplo que pone Anthropic es ambicioso: migraciones de código a escala de cientos de miles de líneas, desde el arranque hasta el merge, usando tu propia suite de tests como criterio de aceptación.

    El detalle a tener en cuenta: esta capacidad está disponible en los planes Enterprise, Team y Max. Si estás en otro plan, no la tendrás todavía.

    Para quien delega tareas largas, este es el cambio con más potencial a medio plazo.

    2. Effort Control: tú decides cuánto piensa

    Ahora puedes elegir el nivel de “esfuerzo” del modelo desde un control junto al selector de modelo.

    • Más esfuerzo: razona más profundo y entrega mejores respuestas.
    • Menos esfuerzo: responde más rápido y consume menos de tus límites de uso.

    Por defecto viene en high. Por encima tienes la opción “extra” —que en Claude Code corresponde a xhigh— y “max”. La recomendación oficial es usar “extra” para tareas difíciles y flujos asíncronos largos. A diferencia de Dynamic Workflows, Effort Control está disponible en todos los planes.

    3. Un modelo más honesto (menos bugs silenciosos)

    Esta es, para mí, la mejora que más se nota en el día a día del código.

    Anthropic entrenó el modelo para que no cante victoria sin evidencia. El dato concreto: Opus 4.8 tiene aproximadamente cuatro veces menos probabilidad que su predecesor de dejar pasar un fallo —en código que él mismo escribió— sin señalártelo.

    Traducido: menos “ya está listo” cuando en realidad no lo está. Si delegas tramos grandes de trabajo, esa honestidad te ahorra horas de revisión y depuración.

    Novedad para quien construye sobre la API

    Si desarrollas agentes sobre la API, hay un cambio silencioso pero práctico: la Messages API ahora acepta entradas de tipo system dentro del array de mensajes. Esto te permite actualizar las instrucciones de Claude a mitad de una tarea —permisos, presupuesto de tokens, contexto del entorno— sin romper el prompt cache ni tener que colarlo como un turno de usuario. Para harnesses de agentes que corren de forma autónoma, limpia bastante la arquitectura.

    Precios y velocidad

    Opus 4.8 mantiene el precio de 4.7:

    • Modo regular: 5 USD por millón de tokens de entrada, 25 USD por millón de salida.
    • Modo fast: 10 USD por millón de entrada, 50 USD por millón de salida, a 2,5× la velocidad. Anthropic indica que este modo fast es alrededor de tres veces más barato que en modelos anteriores.

    En resumen: mejor modelo, mismo costo. Difícil quejarse de eso.

    Mi opinión: no es un salto generacional, y está bien

    Seamos claros: Opus 4.8 no te va a volar la cabeza. Es una mejora de calidad de vida, no un cambio de generación. Pero precisamente por eso se siente: el mejor criterio agéntico y la honestidad encajan a la perfección con un flujo de Spec-Driven Development (SDD).

    Si el modelo respeta mejor el spec, se atreve a frenar cuando el plan no cuadra y no te miente con un “terminé” falso, entonces puedes delegar tramos más grandes con menos revisión manual. Esa es la dirección que importa: el desarrollador como director de la IA, no como su competidor.

    Conclusión

    Claude Opus 4.8 no es un titular espectacular, pero es una actualización sólida para quien vive dentro de Claude Code. Dynamic Workflows y la honestidad extra del modelo son lo que de verdad vale la pena, y el Effort Control le da un control fino que se agradece.

    Si trabajas con SDD y Claude Code, este lanzamiento te toca de lleno. En las próximas semanas haré un experimento práctico combinando Dynamic Workflows con specs bien definidas; lo compartiré por aquí.

    ¿Ya probaste Opus 4.8? ¿Qué tarea grande le tirarías primero a los Dynamic Workflows? Cuéntame en los comentarios.