Es importante que antes de iniciar con cualquier proyecto tenga muy bien definido cual es la arquitectura total, con ello estarás avanzando un 40% de lo que realmente el proyecto es.
#01 – Tecnología que uso con Claude Code
Para mi, en la mayoria de los proyectos usar este stack es mas se suficiente, ya que Laravel ya tiene todo un camino bastante avanzado a comparación de otros como React.js
Con Laravel ya tiene multitenat (que es la división de datos, ideal para una saas), autenticación de usuarios, manejo de colas de procesamiento y más…
Además Laravel ya tiene skills y un MCP que ayuda por mucho en el desarrollo con Claude Code.
- Lenguaje: PHP
- Framework Backend: Laravel
- Framework Frontend: Vue.js
- Librerías CSS: Tailwind, Shadcn
#02 – Creación de carpeta oculta .plan/ en Claude Code
En Claude Code, la debilidad mas grande no es la alucinación, sino la falta de memoria.
Es por ellos que con la carpeta .plan/ será posible tener la memoria de todo lo que va sucediendo, será nuestro guía, el plano de nuestro edificio.
### 1. Genera la carpeta `.plan/` como memoria viva del proyecto
El contexto del proyecto es:
[PEGA AQUÍ TU PLAN: nombre del producto, qué hace, para quién, stack técnico,
modelo de negocio, fases del roadmap con sus features, decisiones ya tomadas,
restricciones importantes]
Crea estos archivos con contenido REAL (no placeholders):
.plan/
README.md ← mapa de navegación: qué abrir según el dominio de la tarea
+ protocolo de lectura obligatoria antes de codear
+ protocolo de actualización obligatoria después de codear
01-vision.md ← producto, usuarios, diferenciadores, out-of-scope explícito
02-stack.md ← stack completo con versiones, servicios externos, dependencias
03-database.md ← convenciones del schema (PKs, soft-deletes, scoping, naming)
+ tablas iniciales si ya están definidas
04-architecture/
INDEX.md ← tabla de navegación a los slices de arquitectura
structure.md ← estructura de carpetas y capas del proyecto
[otros archivos por dominio según el stack: webhooks.md, jobs.md,
policies.md, broadcasts.md, etc. Solo los que aplican]
05-roadmap/
INDEX.md ← tabla de phases con status (pending/active/done) y links
phase-1-<slug>.md ← features de cada phase, criterios de done, status por feature
phase-2-<slug>.md
[una por phase]
06-progress-log/
INDEX.md ← tabla cronológica vacía (se llena cuando se completan features)
07-bugs/
INDEX.md ← catálogo vacío con el formato de entrada documentado
+ bugs conocidos del stack elegido que ya documentamos antes
[archivos por dominio: frontend.md, database.md, etc. — vacíos con formato]
08-decisions/
INDEX.md ← tabla de ADRs vacía con formato (contexto · decisión · consecuencia)
Reglas para estos archivos:
- Ningún slice excede 800 líneas. Si excedería, partir por sub-dominio y actualizar el INDEX
- Los INDEX son solo tablas de navegación — cero contenido sustantivo, máx 150 líneas
- El contenido debe ser accionable: un agente debe poder leer 2-3 archivos y saber exactamente qué hacer
- 06-progress-log/ empieza vacío
- 07-bugs/ empieza con bugs CONOCIDOS del stack elegido (patrones recurrentes documentados)
- 08-decisions/ empieza vacío#03 – Creación de CLAUDE.md en Claude Code
Muchos crean Claude.md al principio, pero lo ideal es hacerlo en este paso ya que con ello conectamos nuestro plan a las intrucciones generales.
### 2. Genera el archivo `CLAUDE.md` en la raíz
Debe contener estas secciones, adaptadas al proyecto:
**a) Producto** — 3-5 líneas: qué es, a quién va dirigido, qué es out-of-scope
**b) Source of truth: `.plan/`** — con estas instrucciones exactas para Claude:
Antes de codear (mandatory):
1. Leer `.plan/README.md`
2. Leer `.plan/07-bugs/INDEX.md` — aplicar preventions de bugs cuyo dominio matchea la tarea
3. Leer `.plan/05-roadmap/INDEX.md` — confirmar phase activa
4. Abrir los INDEX/slices del dominio de la tarea (tabla de mapeo abajo)
Tabla dominio → slice (adaptar al stack del proyecto):
| Dominio de la tarea | Slice(s) a abrir |
|---|---|
| DB · migración · modelo · query | `.plan/03-database.md` |
| Middlewares · jobs · webhooks · queues | `.plan/04-architecture/INDEX.md` → archivo correspondiente |
| Feature de una phase | `.plan/05-roadmap/phase-N-*.md` |
| Decisión arquitectónica no obvia | `.plan/08-decisions/INDEX.md` → ADR relevante |
| Dependencia o versión | `.plan/02-stack.md` |
| Producto / scope | `.plan/01-vision.md` |
Después de codear (mandatory, mismo turno):
| Cambio | Slice a actualizar |
|---|---|
| Migración / schema | `.plan/03-database.md` |
| Ruta · middleware · job · queue · webhook | `.plan/04-architecture/<dominio>.md` |
| Feature completada | `.plan/05-roadmap/phase-N-*.md` (status) + entry en `06-progress-log/` |
| Bug recurrente o costoso (>30 min) | `.plan/07-bugs/<dominio>.md` + fila en INDEX |
| Decisión no obvia | Nuevo `08-decisions/adr/ADR-NNN-<slug>.md` + fila en INDEX |
| Dependencia / versión | `.plan/02-stack.md` |
| Scope / producto | `.plan/01-vision.md` |
**c) Leyes inmutables del proyecto** — lista de las restricciones técnicas más importantes:
(ejemplos: tenancy model, roles, auth approach, schema rules, security requirements)
**d) Convenciones de código** — naming, layers, validation approach del stack elegido
**e) Skills y subagentes** — adaptar a los disponibles en este proyecto
**f) Reglas production-grade** — testing, security, observability, performance, error handling,
migration safety, git workflow (adaptar al stack)
**g) Ask vs proceed** — tabla de cuándo preguntar vs proceder directamente
IMPORTANTE para el CLAUDE.md:
- No duplicar información entre CLAUDE.md y .plan/
- CLAUDE.md = reglas inmutables; .plan/ = estado vivo que cambia
- El CLAUDE.md debe referenciar .plan/ constantemente, nunca copiar su contenido#4 – Creación de sub agentes en Claude Code.
Lee `.plan/README.md`, `.plan/01-vision.md`, `.plan/02-stack.md` y
`.plan/05-roadmap/INDEX.md`.
Basándote en el proyecto, dame una lista de subagentes que debería crear en Claude Code.
Para cada uno, dame exactamente estos tres campos listos para copiar y pegar en el
generador de subagentes:
---
**Nombre:** (kebab-case)
**Descripción:** (1-2 oraciones: qué hace, en qué es experto, qué NO hace)
**Cuándo activarlo:** (trigger preciso: "Usar cuando...", máx 2 líneas)
---
Agrupa los subagentes en:
- Constructores (escriben código)
- Revisores (solo leen y reportan, nunca modifican)
Si un dominio no justifica subagente propio, dilo en una línea y sugiere qué lo cubre.