Angular Feature Architecture

⚠️ Skill personal, no genérica de Angular. No aplicar a proyectos que no sigan este estilo.

Basada en un frontend Angular real, revisado a fondo el 2026-07-18 leyendo directamente el código fuente (no la documentación interna del proyecto, que en varios puntos describe patrones aspiracionales no implementados). Ante conflicto entre esta skill y tu código real, gana el código real.

Motor

• Angular (última mayor estable), 100% standalone — cero NgModule.
• Arquitectura feature-based: core/ (transversal, eager) + features/ (por dominio de negocio, lazy) + shared/ (reutilizable, eager).
• Sin ORM ni Data Access propio — consume una API vía HttpClient envuelto en un ApiService único (ver references/service-and-http-patterns.md).
• Entidades agrupadas por carpeta de negocio — ver skill business-domain-grouping para el mapeo esquema↔carpeta, aplicado aquí a features/{core}/.

Decisiones persistentes entre sesiones

Antes de "Antes de crear", verifica si existe .claude/skill-decisions.md en el proyecto:

• Sección ## Transversal → si ya tiene "Idioma de nomenclatura", no la vuelvas a preguntar (es compartida con sql-database-patterns y dotnet-clean-architecture — la fija la primera skill que se use en el proyecto).
• Sección ## angular-feature-architecture → si existe, léela y aplica esas decisiones (versión, prefijo, librería UI, librería de iconos) directamente.
• Si ninguna existe todavía, es la primera vez en este proyecto: haz las preguntas obligatorias de abajo y crea/completa ambas secciones.

Es un archivo del proyecto que usa la skill (no de la skill en sí), para que una sesión nueva (otra terminal, otro IDE) continúe sobre lo ya decidido en vez de volver a preguntar todo como si fuera la primera vez. Formato:

## Transversal

- Idioma de nomenclatura: {español|inglés}

## angular-feature-architecture

- Versión de Angular: {versión}
- Prefijo/nombre del proyecto: {prefijo}
- Librería UI: {PrimeNG|otra}
- Librería de iconos: {Boxicons|otra} — versión: {versión}

### Excepciones por entidad
- {Entidad}: {excepción puntual}

Append-only: una excepción nueva se agrega a la lista, nunca se reescribe una decisión ya tomada salvo que el usuario pida explícitamente cambiarla.

Antes de crear (obligatorio)

Antes de generar un workspace nuevo, pregunta siempre las 5 — nunca asumas ninguna, son obligatorias antes de crear cualquier archivo:

1. Versión de Angular — sugiere por defecto la última estable, pero pregunta si el usuario quiere esa u otra.
2. Prefijo/nombre del proyecto (para selectores de componente y el workspace, ej. tu-app).
3. Librería de widgets UI — sugiere PrimeNG (última estable compatible con la versión de Angular elegida) por defecto, pero confirma siempre; si el usuario prefiere otra, úsala.
4. Librería de iconos — sugiere Boxicons por defecto, confirma siempre; si confirma Boxicons, pregunta también qué versión usar; si prefiere otra librería, úsala.
5. ¿Idioma de nomenclatura? (si no está ya fijado en ## Transversal) Español (default) o inglés — aplica a las propiedades de los modelos TypeScript (producto_id→product_id, estado→status, etc., mismo snake_case, solo cambia la palabra — ver equivalencias en sql-database-patterns) y a los comentarios de código. No afecta el texto de la UI (labels, botones, notificaciones) — eso es un idioma de producto/UX aparte, no una decisión de esta skill.

Antes de un CRUD nuevo (obligatorio)

Antes de construir el CRUD de una entidad, pregunta siempre: ¿modal o vista independiente? Puedes sugerir un default según el volumen/ complejidad de los datos (ej. una entidad con muchos campos o sub-secciones sugiere vista independiente), pero nunca lo asumas sin preguntar — ver references/component-patterns.md.

Workflow

1. ¿Workspace nuevo desde cero? → references/project-structure.md (estructura de carpetas, environments, angular.json).
2. ¿Feature/entidad nueva? → sigue el checklist de abajo, un archivo por responsabilidad: references/service-and-http-patterns.md, references/component-patterns.md, references/forms-and-validation.md, references/routing-and-lazy-loading.md. Usa business-domain-grouping para decidir la carpeta {Core}.
3. ¿Auth, guards, o JWT? → references/auth-and-security.md.
4. ¿Estilos, tema PrimeNG, o componentes compartidos? → references/styling-and-shared-ui.md.
5. ¿Vas a instalar un paquete npm (nuevo, o un bump de versión mayor de uno existente)? → skill package-security-vetting antes de npm install — obligatorio, salvo que ya sea uno de los defaults ya confirmados (PrimeNG, Boxicons, Chart.js/ng2-charts).
6. Siempre → nomenclatura de references/project-structure.md.
7. Siempre, al terminar una feature → sus pruebas: references/testing.md (en un workspace nuevo, configurar Jest antes de la primera feature). La feature no está terminada hasta que npm test está en verde.
8. Siempre, al terminar una feature → verificación de atomicidad (references/component-patterns.md, "Atomicidad obligatoria"): ningún <{prefijo}-modal> fuera del componente de su modal, ningún .html con más de un título de sección (cada sección en su componente) y ningún .html de más de 300 líneas. Si el comando lista algo, la feature no está terminada: se parte en componentes y se vuelve a correr.

Reglas duras

• Sin NgModules. Todo componente/directiva/pipe es standalone.
• Signals para estado local (signal()/computed()) — nunca BehaviorSubject para estado de UI. RxJS se reserva para el flujo async/HTTP (Observable, finalize, forkJoin, catchError).
• inject() en vez de constructor DI, en todos los componentes, servicios, guards e interceptors.
• OnPush en todo componente.
• Control flow nuevo (@if/@for/@else/@switch) — nunca *ngIf/*ngFor.
• Un servicio por entidad, inyectando siempre ApiService — nunca HttpClient directo en un componente ni en un servicio de feature.
• Reactive Forms únicamente para captura de datos (FormBuilder, FormGroup, Validators). [(ngModel)] solo se acepta para estado de UI suelto (ej. un input de búsqueda), nunca para un formulario de alta/edición.
• Todo input de formulario usa un componente/directiva de la librería UI elegida (PrimeNG por defecto: pInputText, p-select, p-datepicker, etc.) — nunca un <input>/<select> nativo; la librería pierde su estilo de error en inválido si no.
• Guards e interceptors son funcionales (CanActivateFn, HttpInterceptorFn) — nunca basados en clase.
• Sin barrel files (index.ts) en ningún nivel — imports directos por ruta relativa al archivo.
• IDs como string opaco en todo modelo TypeScript — el frontend nunca encripta/desencripta nada; ese es un límite exclusivo del backend (ver references/auth-and-security.md).
• Tailwind CSS, sin SCSS — cero archivos .scss en el proyecto. Un CSS por componente solo se acepta como excepción real y puntual (ej. una transición de grid-template-rows que Tailwind no expresa bien) — no es el patrón por defecto.
• Sufijo .component.ts en todo componente de feature, co-ubicado con su .html en su propia carpeta.

• Atomicidad obligatoria — violarla es un error FATAL, sin excepción. Cada pieza de UI con responsabilidad propia es su propio componente:

  1. Un modal es siempre su propio componente (components/.../{x}-form/, envuelto en <{prefijo}-modal>). El <{prefijo}-modal> solo aparece en el .html de ese componente: nunca dentro del html de una página (pages/), de un -overview, de un -list ni de otro formulario. Quien lo abre solo pone la etiqueta del componente del modal (<{prefijo}-{x}-form ... />).
  2. Un detalle / sub-CRUD dentro de un formulario (direcciones, contactos, cuentas, documentos…) se parte siempre en su carpeta components/{seccion}/ con dos componentes: {seccion}-list (título de la sección, tabla, estado vacío, abrir/quitar) y {seccion}-form (el modal de registrar/editar). La página padre solo pone <{prefijo}-{seccion}-list ... />; nada de la tabla ni del modal queda en su html ni en su ts.
  3. Un formulario seccionado se compone de secciones: si un formulario (página o modal) agrupa sus campos en secciones con título (Identificación, Contacto, Datos comerciales, Tributario…), cada sección es su componente components/{entidad}-{seccion}/ y el formulario solo las renderiza, en orden: <{prefijo}-{entidad}-identificacion [form]="form" />, <{prefijo}-{entidad}-tributario [form]="form" />… El html del formulario no contiene ningún campo de una sección ni su título.
  4. Un html no se desborda: si el .html de un componente pasa de 300 líneas, se parte en componentes antes de entregarlo.

  Ejemplos deterministas (NO / SÍ) y el comando que lo verifica: references/component-patterns.md, "Atomicidad obligatoria". La verificación se ejecuta al terminar cada feature (Workflow, paso 8).

• Reutilización obligatoria e inquebrantable. Antes de crear cualquier componente, servicio, pipe o bloque de estilo, revisa si ya existe algo reutilizable. Se promueve a shared/ en cuanto 2+ puntos de la app lo necesitan — un componente, un servicio, un pipe, o incluso un bloque de estilo Tailwind que se repite. Cero duplicación de código como regla, no como aspiración.
• Prohibido el hardcode. Ni una lista estática va inline en un componente — toda lista/constante de negocio vive centralizada en un servicio de shared/.
• Create y edit son siempre el mismo componente (modal o página) cuando sea técnicamente posible — nunca un diálogo separado para crear y otro para editar.
• environments/ con 3 entornos: environment.ts (dev), environment.qa.ts, environment.prod.ts.
• Pruebas obligatorias con Jest (references/testing.md): cada feature se entrega con sus *.spec.ts junto a lo que prueban. Cada validación del formulario y cada mensaje de rechazo del backend/BD que nombra la especificación se provoca desde la pantalla (la API se simula con el texto exacto del SP) y se verifica lo que ve el usuario. Nada se da por terminado ni se sube con una prueba en rojo; se corrige el código, no la prueba.

Checklist: agregar una feature/entidad nueva

{Core} = carpeta de negocio (ver skill business-domain-grouping).

1. features/{core}/{entidad}/models/{entidad}.model.ts — Entidad, EntidadInsDto, EntidadUpdDto — references/service-and-http-patterns.md.
2. features/{core}/{entidad}/services/{entidad}.service.ts — references/service-and-http-patterns.md.
3. features/{core}/{entidad}/pages/{entidad}-overview/ + components/{entidad}-list/ o pages/{entidad}-form/ (según la variante que corresponda). El listado usa siempre el componente compartido shared/ui/tabla-listado (columnas + plantillas de celda) — references/component-patterns.md, "Listado reutilizable".
4. features/{core}/{entidad}/components/{entidad}-fields/ (formulario) — references/forms-and-validation.md. Si es un modal, va envuelto en el armazón compartido <{prefijo}-modal> — references/component-patterns.md, "Modal reutilizable". 4a. Si el formulario tiene secciones con título: un componente por sección, components/{entidad}-{seccion}/ — obligatorio, references/component-patterns.md, "Atomicidad obligatoria" (punto 3). 4b. Por cada detalle/sub-CRUD del formulario (direcciones, contactos…): components/{seccion}/{seccion}-list/ + components/{seccion}/{seccion}-form/ (modal) — obligatorio, references/component-patterns.md, "Atomicidad obligatoria".
5. features/{core}/{entidad}/{entidad}.routes.ts ({ENTIDAD}_ROUTES) — references/routing-and-lazy-loading.md.
6. Registrar la ruta en features/{core}/{core}.routes.ts (loadChildren) — references/routing-and-lazy-loading.md.
7. Si la feature es nueva a nivel de dominio, registrar también en app.routes.ts — references/routing-and-lazy-loading.md.
8. Pruebas: {entidad}-form.component.spec.ts (validaciones, mensajes de rechazo del backend, camino feliz), del listado y del servicio, y una spec por cada {seccion}-list / {seccion}-form; npm test en verde — references/testing.md.
9. Verificación de atomicidad (Workflow, paso 8) sin salida.

Referencias

• references/project-structure.md — core/features/shared, environments, convenciones de nombres.
• references/routing-and-lazy-loading.md — lazy loading multi-nivel, guards funcionales, rutas.
• references/component-patterns.md — atomicidad obligatoria (un modal = un componente; detalle = -list + -form; una sección = un componente; html ≤ 300 líneas), standalone/OnPush/Signals, variantes de split overview/list/fields, listado reutilizable shared/ui/tabla-listado, modal reutilizable shared/ui/modal, cascada de ubigeo shared/ui/ubigeo-cascada (ControlValueAccessor con NgControl).
• references/forms-and-validation.md — Reactive Forms, helpers de validación, PrimeNG, campos de fecha.
• references/service-and-http-patterns.md — ApiService, servicio por entidad, ApiResponse, modelos/DTOs, catálogos con cache.
• references/auth-and-security.md — JWT, login multi-tenant en 2 fases, guards, IDs opacos.
• references/styling-and-shared-ui.md — Tailwind, tema PrimeNG, shared/ui, iconos.
• references/testing.md — Jest + jest-preset-angular zoneless, qué se prueba por feature, cómo simular la API con los mensajes del backend, trazabilidad.
• Skill business-domain-grouping — mapeo esquema↔carpeta de negocio ({Core}), aplicado a features/.
• Skill angular-design-system — todo lo visual: colores, tipografía, dark mode, botones/cards/alerts/modales, grillas, notificaciones, KPIs y charts.
• Skill package-security-vetting — chequeo de seguridad obligatorio antes de instalar cualquier paquete npm fuera de los defaults ya confirmados.