Cómo trabajamos con Claude Code en un proyecto Laravel

Los tres archivos que deciden si Claude Code te ayuda o te estorba: CLAUDE.md, los permisos en settings.json y un subagente que revisa antes del commit.

JZ Jorge Zamarrón 10 nov. 2026 5 min de lectura
Cómo trabajamos con Claude Code en un proyecto Laravel

El sitio que estás leyendo está hecho en Laravel 11 con Filament y Tailwind, y buena parte del trabajo de este año lo hicimos con Claude Code en la terminal: las páginas de servicios, industrias y ciudades, las versiones en inglés, el llms.txt y el schema. Te cuento cómo lo configuro, porque la diferencia entre que Claude Code te ayude o te estorbe está casi toda en tres archivos.

1. CLAUDE.md: lo que un programador nuevo necesitaría saber

Claude Code lee el archivo CLAUDE.md de la raíz del proyecto al iniciar cada sesión. Yo lo escribo como si fuera la nota de bienvenida para alguien que entra el lunes al equipo: cómo se corre el proyecto, dónde vive cada cosa y qué no se toca.

# Sitio Zygnus

## Cómo se corre
- `php artisan serve --port=8088`
- Assets: `npx vite build` (local; el servidor no compila)
- Pruebas: `php artisan test`

## Dónde vive el contenido
- Páginas de servicio, industria y ciudad: resources/content/landings.php (ES)
  y landings.en.php (EN), mismas llaves.
- Portafolio y blog: base de datos (Filament en /admin).
- Textos de interfaz: lang/es y lang/en.

## Reglas
- No inventar cifras, clientes ni testimonios. Si falta un dato, preguntar.
- Toda página nueva va en español e inglés.
- No editar .env ni nada en storage/.
- Las ciudades solo tienen página propia si hay oficina o un caso real.

La regla de no inventar cifras parece obvia. La puse porque un modelo que redacta copy de ventas tiende a rellenar con números redondos que suenan bien, y en un sitio que vende confianza eso es lo último que quieres.

2. Permisos en .claude/settings.json

El segundo archivo define qué puede hacer Claude Code sin preguntarte. Conviene guardarlo en el repositorio para que todo el equipo trabaje con las mismas reglas. Un ejemplo para Laravel:

{
  "permissions": {
    "allow": [
      "Bash(php artisan test:*)",
      "Bash(php artisan route:list:*)",
      "Bash(npx vite build)",
      "Bash(git status)",
      "Bash(git diff:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Bash(rsync:*)",
      "Bash(php artisan migrate:fresh:*)"
    ]
  }
}

Lo que va en allow son comandos que corro veinte veces al día y que no rompen nada. Lo que va en deny es lo que no quiero que pase nunca desde una sesión de Claude: leer credenciales, desplegar o borrar la base. El despliegue lo hago yo, a propósito.

3. Un subagente para revisar antes del commit

Los subagentes viven en .claude/agents/. Cada uno tiene su propio contexto, sus herramientas y sus instrucciones, así que no ensucian la conversación principal. Este es un revisor para cambios en Blade y controladores que puedes copiar y ajustar:

---
name: revisor-laravel
description: Revisa cambios en controladores, rutas y vistas Blade antes de un commit. Úsalo cuando termines una edición.
tools: Read, Grep, Glob, Bash
---
Revisa el diff actual (git diff) y busca:
- Rutas nuevas sin nombre o sin su versión en el otro idioma.
- Textos escritos directo en Blade que deberían estar en lang/.
- Consultas dentro de un @foreach (N+1).
- Variables sin escapar con {!! !!} que vengan del usuario.
Reporta archivo y línea. No edites nada.

La última línea importa. Un revisor que también corrige se convierte en otro autor, y entonces ya nadie revisó.

Cómo es una sesión normal

Empiezo pidiendo un plan antes de cualquier edición, sobre todo cuando el cambio toca varias capas. Para las páginas bilingües, por ejemplo, el plan dejó claro que el contenido iba en un archivo PHP por idioma con las mismas llaves, que una clase Landings lo cargaba y que las rutas en inglés redirigían con 301 si alguien entraba con el slug en español. Discutir eso en texto me ahorró deshacer código.

Después lo dejo editar, corro las pruebas y reviso el diff yo mismo. Claude Code escribe rápido; la responsabilidad de lo que llega a producción sigue siendo mía, y por eso el despliegue no está en su lista de permisos.

Lo que reviso yo siempre

Hay tres cosas que no delego. La primera son las cifras: los números que aparecen en este sitio salen de consultas a las bases de producción, y cuando Claude Code propone un texto con un dato, lo comparo contra esa consulta antes de aceptarlo. La segunda son las rutas públicas, porque un slug que cambia sin redirección 301 puede tirar posiciones en Google que costó trabajo ganar. La tercera es el despliegue, por lo que ya conté arriba.

También aprendí a pedir cambios chicos. Una instrucción como "haz las páginas de ciudades" produce mucho código de golpe y es difícil de revisar con calma. "Agrega la página de Chihuahua con estas secciones y no toques las demás" produce un diff que puedo leer completo antes de aceptarlo.

Si ya usas Claude Code en un proyecto Laravel, me interesa saber qué tienes en tu CLAUDE.md que yo no tenga. Siempre encuentro una regla que me faltaba.

JZ

Escrito por

Jorge Zamarrón · Fundador y CEO

Fundó Zygnus y lleva quince años haciendo software y consultoría de procesos para empresas. Es consejero de Alcis Corp, un holding de más de diez empresas con ventas conjuntas de más de 12 mil millones de pesos al año, y director de Innovación y Desarrollo de J. García López.

Boletín

Un correo cuando publiquemos algo nuevo

Sin promociones. Solo los artículos.