ff3038f183
Sistema completo de gestión de tokens para subagentes NEXUS v4.0: Nuevas directivas SIMCO: - SIMCO-SUBAGENTE.md: Protocolo para agentes en modo subagente - SIMCO-CCA-SUBAGENTE.md: CCA ligero para subagentes (~1,500 tokens) - SIMCO-CONTROL-TOKENS.md: Gestión de límites de tokens - SIMCO-DELEGACION-PARALELA.md: Delegación paralela Perfiles compact (~250 tokens cada uno): - PERFIL-BACKEND-COMPACT.md - PERFIL-FRONTEND-COMPACT.md - PERFIL-DATABASE-COMPACT.md - PERFIL-DEVOPS-COMPACT.md - PERFIL-ML-COMPACT.md - PERFIL-GENERIC-SUBAGENT.md Templates de delegación escalonados: - TEMPLATE-DELEGACION-MINIMA.md (~250 tokens) - TEMPLATE-DELEGACION-ESTANDAR.md (~600 tokens) - TEMPLATE-DELEGACION-COMPLETA.md (~1,800 tokens) Nuevos perfiles especializados: - PERFIL-MCP-ARCHITECT.md - PERFIL-MCP-DEVELOPER.md - PERFIL-RAG-ENGINEER.md - PERFIL-CICD-SPECIALIST.md - PERFIL-PRODUCTION-MANAGER.md - PERFIL-MONITORING-AGENT.md - PERFIL-SECRETS-MANAGER.md - PERFIL-PROPAGATION-TRACKER.md Checklists y documentación: - CHECKLIST-PRE-DELEGACION.md - Análisis y planes de implementación Métricas de mejora: - ~59% reducción de tokens por delegación - Perfiles compact: 69% más ligeros - CCA subagente: 85% más ligero 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
361 lines
10 KiB
Markdown
361 lines
10 KiB
Markdown
# SIMCO: MODULOS COMPARTIDOS
|
|
|
|
**Version:** 1.0.0
|
|
**Fecha:** 2026-01-03
|
|
**Aplica a:** Todos los agentes de desarrollo
|
|
**Prioridad:** OBLIGATORIA - Consultar antes de implementar funcionalidad comun
|
|
**Relacionado:** SIMCO-ESTRUCTURA-REPOS.md, PRINCIPIO-ANTI-DUPLICACION.md
|
|
|
|
---
|
|
|
|
## RESUMEN EJECUTIVO
|
|
|
|
> **El workspace NEXUS tiene DOS sistemas de codigo compartido: catalog/ y modules/**
|
|
> Consultar AMBOS antes de implementar funcionalidad que pueda existir.
|
|
> Duplicar codigo existente = deuda tecnica y mantenimiento multiplicado.
|
|
|
|
---
|
|
|
|
## DIFERENCIA: catalog/ vs modules/
|
|
|
|
### Tabla Comparativa
|
|
|
|
| Aspecto | shared/catalog/ | shared/modules/ |
|
|
|---------|---------------|---------------|
|
|
| **Proposito** | Documentacion + codigo de referencia | Codigo TypeScript listo para importar |
|
|
| **Contenido** | README, guias, templates, ejemplos | Archivos .ts exportables |
|
|
| **Uso** | Copiar y adaptar al proyecto | Importar directamente (@shared/modules/*) |
|
|
| **Funcionalidades** | auth, payments, notifications, etc. | utils, tipos comunes, helpers |
|
|
| **Mantenimiento** | Cada proyecto mantiene su copia | Central, actualizaciones afectan a todos |
|
|
| **Cuando usar** | Funcionalidad compleja que requiere adaptacion | Utilidades genericas sin logica de negocio |
|
|
|
|
### shared/catalog/ - Catalogo de Funcionalidades
|
|
|
|
```yaml
|
|
Ubicacion: /home/isem/workspace-v1/shared/catalog/
|
|
|
|
Proposito: Documentar funcionalidades complejas con codigo de referencia
|
|
|
|
Estructura por funcionalidad:
|
|
shared/catalog/{funcionalidad}/
|
|
+-- README.md # Descripcion y trade-offs
|
|
+-- IMPLEMENTATION.md # Pasos de implementacion
|
|
+-- _reference/ # Codigo de referencia para copiar
|
|
| +-- backend/
|
|
| +-- frontend/
|
|
| +-- database/
|
|
+-- orchestration/
|
|
+-- CONSUMIDORES.yml # Proyectos que lo usan
|
|
|
|
Funcionalidades disponibles (11):
|
|
- auth # Login, registro, JWT, OAuth
|
|
- session-management # Sesiones concurrentes
|
|
- rate-limiting # Throttle, 429
|
|
- notifications # Email, push, in-app
|
|
- websocket # Tiempo real, streaming
|
|
- multi-tenancy # Tenant, RLS
|
|
- feature-flags # Toggles dinamicos
|
|
- payments # Stripe, suscripciones
|
|
- template-saas # Template SaaS completo
|
|
- portales # Dashboards, widgets
|
|
- audit-logs # Auditoria, compliance
|
|
|
|
Como usar:
|
|
1. Buscar: grep -i "{keyword}" shared/catalog/CATALOG-INDEX.yml
|
|
2. Leer: shared/catalog/{funcionalidad}/README.md
|
|
3. Copiar: _reference/ al proyecto
|
|
4. Adaptar: configuracion al contexto actual
|
|
5. Validar: ejecutar tests
|
|
```
|
|
|
|
### shared/modules/ - Modulos TypeScript
|
|
|
|
```yaml
|
|
Ubicacion: /home/isem/workspace-v1/shared/modules/
|
|
|
|
Proposito: Codigo TypeScript compartido para importar directamente
|
|
|
|
Estructura:
|
|
shared/modules/
|
|
+-- package.json # Configuracion del monorepo
|
|
+-- utils/ # Utilidades genericas
|
|
| +-- index.ts
|
|
| +-- date.util.ts
|
|
| +-- string.util.ts
|
|
| +-- validation.util.ts
|
|
+-- auth/ # Modulo de autenticacion (en desarrollo)
|
|
+-- notifications/ # Sistema de notificaciones
|
|
+-- payments/ # Integracion de pagos
|
|
+-- billing/ # Facturacion
|
|
+-- multitenant/ # Multi-tenancy
|
|
|
|
Modulos disponibles (6):
|
|
- utils # Helpers de fecha, string, validacion
|
|
- auth # Guards, decorators, JWT
|
|
- notifications # Servicio de notificaciones
|
|
- payments # Integracion Stripe
|
|
- billing # Logica de facturacion
|
|
- multitenant # Tenant context, RLS
|
|
|
|
Como usar:
|
|
1. Importar: import { funcion } from '@shared/modules/utils';
|
|
2. Usar directamente en el codigo
|
|
3. NO copiar, solo importar
|
|
```
|
|
|
|
---
|
|
|
|
## FLUJO DE DECISION
|
|
|
|
### ¿Necesito funcionalidad compartida?
|
|
|
|
```
|
|
INICIO: Voy a implementar funcionalidad
|
|
|
|
|
v
|
|
¿Es funcionalidad comun (auth, payments, notifications)?
|
|
|
|
|
+-- SI --> Buscar en @CATALOG_INDEX
|
|
| |
|
|
| +-- Encontrado --> Seguir IMPLEMENTATION.md, copiar y adaptar
|
|
| |
|
|
| +-- No encontrado --> ¿Es utilidad generica?
|
|
| |
|
|
| +-- SI --> Ver shared/modules/
|
|
| |
|
|
| +-- NO --> Implementar nuevo
|
|
|
|
|
+-- NO --> ¿Es utilidad generica (fecha, string, validacion)?
|
|
|
|
|
+-- SI --> import from '@shared/modules/utils'
|
|
|
|
|
+-- NO --> Implementar en el proyecto
|
|
```
|
|
|
|
### ¿Catalog o Modules?
|
|
|
|
```yaml
|
|
Usar CATALOG cuando:
|
|
- Es funcionalidad completa (auth, payments, notifications)
|
|
- Requiere adaptacion al proyecto
|
|
- Tiene logica de negocio que varia
|
|
- Incluye DDL, backend, frontend
|
|
- Cada proyecto puede tener variaciones
|
|
|
|
Usar MODULES cuando:
|
|
- Es utilidad generica sin logica de negocio
|
|
- NO requiere adaptacion
|
|
- Es identico en todos los proyectos
|
|
- Son helpers puros (fecha, string, validacion)
|
|
- Cambios deben propagarse a todos los consumidores
|
|
```
|
|
|
|
---
|
|
|
|
## COMO IMPORTAR MODULOS
|
|
|
|
### Configuracion en tsconfig.json
|
|
|
|
```json
|
|
{
|
|
"compilerOptions": {
|
|
"paths": {
|
|
"@shared/modules/*": ["../../shared/modules/*"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Ejemplos de Importacion
|
|
|
|
```typescript
|
|
// Importar utilidades
|
|
import { formatDate, parseDate } from '@shared/modules/utils';
|
|
import { slugify, capitalize } from '@shared/modules/utils/string.util';
|
|
import { isValidEmail, isValidPhone } from '@shared/modules/utils/validation.util';
|
|
|
|
// Importar modulos completos
|
|
import { TenantService } from '@shared/modules/multitenant';
|
|
import { NotificationService } from '@shared/modules/notifications';
|
|
import { StripeService } from '@shared/modules/payments';
|
|
```
|
|
|
|
### Estructura de Exportaciones
|
|
|
|
```typescript
|
|
// shared/modules/utils/index.ts
|
|
export * from './date.util';
|
|
export * from './string.util';
|
|
export * from './validation.util';
|
|
```
|
|
|
|
---
|
|
|
|
## CUANDO CREAR MODULO NUEVO
|
|
|
|
### Criterios para Promocion a shared/modules/
|
|
|
|
```yaml
|
|
Crear modulo nuevo SI:
|
|
- Es usado por 3+ proyectos
|
|
- Es utilidad generica (NO logica de negocio)
|
|
- NO requiere adaptacion por proyecto
|
|
- Tiene tests unitarios
|
|
- Tiene documentacion (README.md)
|
|
- Sigue patrones de los modulos existentes
|
|
|
|
NO crear modulo SI:
|
|
- Es especifico de un proyecto
|
|
- Contiene logica de negocio variable
|
|
- Requiere configuracion diferente por proyecto
|
|
- Es prototipo no probado
|
|
```
|
|
|
|
### Proceso de Promocion
|
|
|
|
```yaml
|
|
PASO_1_IDENTIFICAR:
|
|
- Codigo duplicado en 2+ proyectos
|
|
- Utilidad generica sin dependencia de negocio
|
|
|
|
PASO_2_EXTRAER:
|
|
- Crear carpeta en shared/modules/{modulo}/
|
|
- Mover codigo a archivos .ts
|
|
- Crear index.ts con exports
|
|
|
|
PASO_3_DOCUMENTAR:
|
|
- Crear README.md siguiendo TEMPLATE-MODULO-COMPARTIDO.md
|
|
- Documentar API publica
|
|
- Agregar ejemplos de uso
|
|
|
|
PASO_4_CONFIGURAR:
|
|
- Actualizar shared/modules/package.json
|
|
- Verificar paths en consumidores
|
|
|
|
PASO_5_VALIDAR:
|
|
- npm run build en shared/modules
|
|
- npm run test (si hay tests)
|
|
- Verificar importacion desde proyecto de prueba
|
|
|
|
PASO_6_ACTUALIZAR_CONSUMIDORES:
|
|
- Reemplazar codigo duplicado por imports
|
|
- Actualizar inventarios
|
|
```
|
|
|
|
---
|
|
|
|
## ESTRUCTURA DE MODULO
|
|
|
|
### Template de Modulo
|
|
|
|
```
|
|
shared/modules/{modulo}/
|
|
+-- README.md # Documentacion del modulo
|
|
+-- package.json # (opcional) dependencias propias
|
|
+-- index.ts # Punto de entrada, exports
|
|
+-- {funcion}.ts # Archivos de funcionalidad
|
|
+-- {funcion}.spec.ts # Tests unitarios
|
|
+-- types.ts # (opcional) tipos TypeScript
|
|
```
|
|
|
|
### Ejemplo: Modulo utils
|
|
|
|
```
|
|
shared/modules/utils/
|
|
+-- README.md
|
|
+-- index.ts # export * from './date.util'; ...
|
|
+-- date.util.ts # formatDate, parseDate, addDays...
|
|
+-- date.util.spec.ts # Tests de fecha
|
|
+-- string.util.ts # slugify, capitalize, truncate...
|
|
+-- string.util.spec.ts # Tests de string
|
|
+-- validation.util.ts # isValidEmail, isValidPhone...
|
|
+-- validation.util.spec.ts # Tests de validacion
|
|
```
|
|
|
|
---
|
|
|
|
## CHECKLIST DE DOCUMENTACION
|
|
|
|
### Al Crear Modulo Nuevo
|
|
|
|
```markdown
|
|
- [ ] README.md creado con:
|
|
- [ ] Descripcion del modulo
|
|
- [ ] Instalacion/configuracion
|
|
- [ ] API publica documentada
|
|
- [ ] Ejemplos de uso
|
|
- [ ] Dependencias listadas
|
|
- [ ] index.ts con exports
|
|
- [ ] Tests unitarios
|
|
- [ ] Agregar a shared/modules/package.json
|
|
- [ ] Verificar paths de importacion
|
|
```
|
|
|
|
### Al Usar Modulo Existente
|
|
|
|
```markdown
|
|
- [ ] Verificar version compatible
|
|
- [ ] Configurar paths en tsconfig.json
|
|
- [ ] Importar correctamente
|
|
- [ ] NO copiar codigo (solo importar)
|
|
- [ ] Reportar bugs/mejoras al owner del modulo
|
|
```
|
|
|
|
---
|
|
|
|
## MANTENIMIENTO
|
|
|
|
### Responsabilidades
|
|
|
|
```yaml
|
|
Owner del modulo:
|
|
- Mantener documentacion actualizada
|
|
- Revisar PRs de contribuciones
|
|
- Versionar cambios breaking
|
|
- Notificar a consumidores de cambios
|
|
|
|
Consumidores:
|
|
- Importar, NO copiar
|
|
- Reportar bugs al owner
|
|
- Contribuir mejoras via PR
|
|
- Actualizar cuando hay cambios
|
|
```
|
|
|
|
### Versionado
|
|
|
|
```yaml
|
|
Reglas de versionado:
|
|
- Patch (1.0.X): Bugfixes, no rompe nada
|
|
- Minor (1.X.0): Nueva funcionalidad, retrocompatible
|
|
- Major (X.0.0): Breaking changes, requiere actualizacion
|
|
|
|
Comunicacion:
|
|
- Cambios breaking se anuncian en CHANGELOG.md
|
|
- Consumidores actualizan antes de deadline
|
|
```
|
|
|
|
---
|
|
|
|
## ERRORES COMUNES
|
|
|
|
| Error | Causa | Solucion |
|
|
|-------|-------|----------|
|
|
| Modulo no encontrado | Paths mal configurados | Verificar tsconfig.json |
|
|
| Codigo duplicado | No consulto modules/ | Refactorizar a import |
|
|
| Breaking changes | Actualizo modulo sin avisar | Versionar correctamente |
|
|
| Funcionalidad en modules que deberia estar en catalog | Tiene logica de negocio | Mover a catalog/ |
|
|
| Tests fallan despues de import | Modulo incompatible | Verificar version y deps |
|
|
|
|
---
|
|
|
|
## REFERENCIAS
|
|
|
|
- **Estructura:** `SIMCO-ESTRUCTURA-REPOS.md`
|
|
- **Anti-duplicacion:** `PRINCIPIO-ANTI-DUPLICACION.md`
|
|
- **Catalogo:** `shared/catalog/CATALOG-INDEX.yml`
|
|
- **Template modulo:** `TEMPLATE-MODULO-COMPARTIDO.md`
|
|
|
|
---
|
|
|
|
**Version:** 1.0.0 | **Sistema:** SIMCO | **Tipo:** Directiva de Modulos
|