Project Forge

Template para proyectos multiplataforma diseñado para desarrollo asistido por IA con Claude Code.

Qué es esto

Un repositorio que se clona como punto de partida para cualquier proyecto que necesite backend, web, Android y/o iOS. El stack tecnológico se decide al inicializar cada proyecto mediante un wizard guiado por el agente de IA.

Filosofía

Basado en principios de ingeniería agéntica:

• CLAUDE.md como router — El agente lee un directorio lógico de contexto, no un documento masivo
• Separación investigación/implementación — Investigar primero, codear después, en contextos separados
• Contratos de tarea — Cada tarea tiene criterios de finalización deterministas con tests
• Contexto mínimo — El agente lee solo lo que necesita para su tarea actual
• Rules y Skills — Comportamiento consistente codificado en archivos reutilizables

Cómo empezar

1. Clona el template

git clone https://github.com/{tu-usuario}/project-forge.git mi-nuevo-proyecto
cd mi-nuevo-proyecto
rm -rf .git
git init

2. Abre Claude Code

claude

3. Ejecuta el wizard

El agente detectará que el proyecto no está inicializado y ejecutará el wizard, o puedes lanzarlo manualmente:

/init

El wizard te guiará por:

1. Definición del dominio y usuarios
2. Selección de plataformas (cualquier combinación de backend, web, Android, iOS)
3. Decisión del stack de cada plataforma (el agente recomienda según tus requisitos)
4. Generación de documentación, estructura y reglas adaptadas
5. Limpieza de plataformas no activas
6. Configuración de infraestructura

4. Empieza a desarrollar

Usa los comandos del agente:

• /feature — Implementar una nueva funcionalidad
• /contract — Crear un contrato de tarea
• /status — Ver el estado del proyecto

Estructura del repositorio

project-forge/
├── CLAUDE.md                    # Punto de entrada del agente (routing)
├── .claude/
│   ├── rules/                   # Reglas de comportamiento
│   │   ├── general.md           # Código limpio, naming, estructura
│   │   ├── git.md               # Commits, branches, workflow
│   │   ├── testing.md           # Qué y cómo testear
│   │   ├── code-review.md       # Checklist de auto-revisión
│   │   └── platform/            # Reglas por plataforma
│   ├── skills/                  # Recetas de "cómo hacer X"
│   │   ├── init-wizard.md       # Wizard de inicialización
│   │   ├── new-feature.md       # Proceso de nueva feature
│   │   ├── new-endpoint.md      # Añadir endpoint API
│   │   ├── new-screen.md        # Añadir pantalla
│   │   ├── new-module.md        # Crear módulo reutilizable
│   │   ├── debugging.md         # Proceso de debugging
│   │   └── deploy.md            # Proceso de despliegue
│   └── commands/                # Comandos slash
├── docs/                        # Documentación del proyecto
│   ├── PROJECT_BRIEF.md         # Contexto del proyecto
│   ├── ARCHITECTURE.md          # Arquitectura del sistema
│   ├── TECH_STACK.md            # Stack tecnológico
│   ├── API_CONTRACT.md          # Especificación de la API
│   ├── DATA_MODEL.md            # Modelo de datos
│   ├── GLOSSARY.md              # Glosario del dominio
│   ├── specs/                   # Specs de features
│   └── adr/                     # Architecture Decision Records
├── contracts/                   # Contratos de tarea (Definition of Done)
│   ├── active/                  # En curso
│   └── completed/               # Historial
├── plans/                       # Planes de implementación
├── platforms/                   # Código fuente por plataforma
│   ├── backend/
│   ├── web/
│   ├── web-admin/               # Backoffice (si activo)
│   ├── android/
│   └── ios/
├── shared/                      # Definiciones compartidas
├── infrastructure/              # Docker, CI/CD, deploy
└── scripts/                     # Scripts de utilidad

Flujo de trabajo con el agente

1. Usuario describe lo que quiere
        ↓
2. Agente investiga (contexto separado)
        ↓
3. Se crea una Spec (docs/specs/)
        ↓
4. Se crea un Plan (plans/)
        ↓
5. Se crean Contratos con tests (contracts/active/)
        ↓
6. Agente implementa (contexto limpio)
        ↓
7. Tests pasan + auto-review
        ↓
8. Contrato completado → contracts/completed/

Plataformas (todas configurables en /init)

Cualquier combinación es válida — desde un proyecto solo Android hasta las 4 plataformas:

• Backend: Ktor, Spring Boot, NestJS, FastAPI, Go, etc.
• Web: Next.js, Nuxt, SvelteKit, Remix, etc.
• Web Admin / Backoffice: Panel de administración independiente (mismo framework que web o diferente: React Admin, custom, etc.)
• Android: Kotlin + Jetpack Compose (DI, networking y DB se eligen en init)
• iOS: SwiftUI nativo (networking, DI y DB se eligen en init)
• Base de datos: PostgreSQL, MongoDB, MySQL, SQLite, etc.

Mantenimiento del template

Conforme uses el template en proyectos reales, mejora las rules y skills con lo que aprendas. Trata el template como un producto vivo que evoluciona con tu experiencia.