workspace/projects/gamilit/orchestration/directivas/GUIA-NOMENCLATURA-COMPLETA.md

GUÍA COMPLETA: NOMENCLATURA Y ESTÁNDARES

Proyecto: GAMILIT - Sistema de Gamificación Educativa Versión: 1.0.0 Fecha: 2025-11-20 Ámbito: Todos los agentes y desarrolladores Tipo: Guía de Referencia Obligatoria

---

🎯 PROPÓSITO

Esta guía define TODOS los estándares de nomenclatura del proyecto para garantizar:

• Consistencia en todo el codebase
• Legibilidad y comprensión inmediata
• Mantenibilidad a largo plazo
• Evitar colisiones de nombres
• Facilitar búsquedas y navegación de código

---

📁 NOMENCLATURA DE ARCHIVOS Y CARPETAS

1. Archivos de Base de Datos (.sql)

Convención: {NN}-{nombre-descriptivo}.sql

Reglas:
  - Prefijo numérico secuencial (01, 02, 03...)
  - Nombres en snake_case
  - Descriptivo y claro
  - Extensión .sql

✅ Correcto:
  - 01-user_points.sql
  - 02-developments.sql
  - 03-phases.sql
  - 10-functions-geo.sql

❌ Incorrecto:
  - projects.sql (sin prefijo)
  - 1-projects.sql (prefijo de 1 dígito)
  - Projects.sql (PascalCase)
  - 01_projects.sql (guión bajo en lugar de guión)

2. Archivos de Backend TypeScript

Entities (.entity.ts)

Convención: {nombre}.entity.ts

Reglas:
  - Nombre en kebab-case
  - Sufijo .entity.ts
  - Singular (project, no projects)

✅ Correcto:
  - project.entity.ts
  - development.entity.ts
  - housing-unit.entity.ts
  - budget-item.entity.ts

❌ Incorrecto:
  - Project.entity.ts (PascalCase)
  - projects.entity.ts (plural)
  - projectEntity.ts (sin guión)
  - project.ts (sin sufijo)

Services (.service.ts)

Convención: {nombre}.service.ts

✅ Correcto:
  - project.service.ts
  - development.service.ts
  - auth.service.ts

❌ Incorrecto:
  - ProjectService.ts
  - projects.service.ts
  - project-service.ts

Controllers (.controller.ts)

Convención: {nombre}.controller.ts

✅ Correcto:
  - project.controller.ts
  - development.controller.ts
  - auth.controller.ts

❌ Incorrecto:
  - ProjectController.ts
  - projects.controller.ts

DTOs (.dto.ts)

Convención: {acción}-{entidad}.dto.ts

✅ Correcto:
  - create-project.dto.ts
  - update-project.dto.ts
  - filter-project.dto.ts

❌ Incorrecto:
  - CreateProject.dto.ts
  - project.dto.ts (sin acción)
  - projectDto.ts

Módulos (.module.ts)

Convención: {nombre}.module.ts

✅ Correcto:
  - project.module.ts
  - auth.module.ts
  - budget.module.ts

❌ Incorrecto:
  - ProjectModule.ts
  - projects.module.ts

3. Archivos de Frontend

Componentes React (.tsx)

Convención: {Nombre}{Tipo}.tsx

Reglas:
  - PascalCase
  - Sufijo con tipo si aplica (Button, Card, Modal)
  - Singular

✅ Correcto:
  - ProjectCard.tsx
  - ProjectListItem.tsx
  - CreateProjectModal.tsx
  - ProjectFilters.tsx

❌ Incorrecto:
  - projectCard.tsx (camelCase)
  - project-card.tsx (kebab-case)
  - ProjectsCard.tsx (plural sin razón)
  - Card.tsx (muy genérico)

Páginas React (.tsx)

Convención: {Nombre}Page.tsx

Reglas:
  - PascalCase
  - Sufijo Page obligatorio
  - Plural si lista, singular si detalle

✅ Correcto:
  - ProjectsPage.tsx (lista)
  - ProjectDetailPage.tsx (detalle)
  - CreateProjectPage.tsx (crear)
  - DashboardPage.tsx

❌ Incorrecto:
  - Projects.tsx (sin Page)
  - projectsPage.tsx (camelCase)
  - project-page.tsx (kebab-case)

Stores Zustand (.ts)

Convención: {nombre}.store.ts o use{Nombre}Store.ts

Reglas:
  - camelCase para archivo
  - Sufijo .store.ts

✅ Correcto:
  - project.store.ts
  - auth.store.ts
  - useProjectStore.ts

❌ Incorrecto:
  - ProjectStore.ts (PascalCase en archivo)
  - projectStore.ts (sin .store)

Hooks Personalizados (.ts)

Convención: use{Nombre}.ts

Reglas:
  - Prefijo use obligatorio
  - PascalCase después de use

✅ Correcto:
  - useProjects.ts
  - useAuth.ts
  - useProjectFilters.ts

❌ Incorrecto:
  - projects.ts (sin use)
  - useprojects.ts (sin PascalCase)
  - use-projects.ts (kebab-case)

Servicios API (.api.ts)

Convención: {nombre}.api.ts

✅ Correcto:
  - project.api.ts
  - auth.api.ts
  - budget.api.ts

❌ Incorrecto:
  - ProjectApi.ts
  - projectAPI.ts
  - project-api.ts

Types (.types.ts)

Convención: {nombre}.types.ts

✅ Correcto:
  - project.types.ts
  - common.types.ts
  - api.types.ts

❌ Incorrecto:
  - ProjectTypes.ts
  - project.type.ts (singular)

4. Archivos de Configuración

✅ Correcto:
  - tsconfig.json
  - package.json
  - .env.example
  - .gitignore
  - README.md
  - vite.config.ts
  - jest.config.js

Reglas:
  - Seguir convenciones estándar de cada herramienta
  - lowercase para config files
  - UPPERCASE para archivos especiales (README, LICENSE)

5. Carpetas

Carpetas de Código

Convención General: kebab-case o snake_case según contexto

Database:
  - snake_case para schemas: gamification_system
  - kebab-case para carpetas de código: schemas/project-management

Backend:
  - kebab-case: src/modules/project-management
  - camelCase para subcarpetas: entities, services, controllers

Frontend:
  - kebab-case: src/components/project-cards
  - PascalCase para componentes específicos: ProjectCard/

✅ Correcto (Database):
  - apps/database/ddl/schemas/gamification_system/
  - apps/database/ddl/schemas/financial_management/

✅ Correcto (Backend):
  - apps/backend/src/modules/project-management/
  - apps/backend/src/modules/auth/
  - apps/backend/src/shared/config/

✅ Correcto (Frontend):
  - apps/frontend/web/src/shared/components/
  - apps/frontend/web/src/apps/admin/
  - apps/frontend/mobile/src/screens/

❌ Incorrecto:
  - project-Management/ (mixto)
  - ProjectManagement/ (PascalCase en carpeta)
  - gamification_system/ en frontend (contexto incorrecto)

Carpetas de Orchestration

Convención: kebab-case o UPPERCASE para archivos especiales

✅ Correcto:
  - orchestration/agentes/database/
  - orchestration/directivas/
  - orchestration/inventarios/
  - orchestration/templates/
  - orchestration/estados/

Archivos:
  - UPPERCASE-CON-GUIONES.md para documentos principales
  - kebab-case.md para templates

Ejemplos:
  - DIRECTIVA-DOCUMENTACION-OBLIGATORIA.md
  - TEMPLATE-PLAN.md
  - MASTER_INVENTORY.yml

---

🏷️ NOMENCLATURA DE IDENTIFICADORES EN CÓDIGO

1. Database (PostgreSQL + SQL)

Schemas

Convención: {contexto}_management

Reglas:
  - snake_case
  - Sufijo _management para contextos de negocio
  - Singular o plural según convención del dominio

✅ Correcto:
  - auth_management
  - gamification_system
  - financial_management
  - purchasing_management

❌ Incorrecto:
  - authManagement (camelCase)
  - auth-management (kebab-case)
  - AUTH_MANAGEMENT (uppercase)
  - projects (sin contexto claro)

Tablas

Convención: {nombre}_en_plural

Reglas:
  - snake_case
  - Plural (projects, users, budgets)
  - Descriptivo y claro

✅ Correcto:
  - projects
  - developments
  - housing_units
  - budget_items
  - project_status_history

❌ Incorrecto:
  - project (singular)
  - Projects (PascalCase)
  - project-developments (kebab-case)
  - tbl_projects (prefijo innecesario)

Columnas

Convención: {nombre}_descriptivo

Reglas:
  - snake_case
  - Singular
  - Evitar abreviaciones
  - Sufijos estándar: _id, _at, _by_id

✅ Correcto:
  - id
  - code
  - name
  - description
  - created_at
  - updated_at
  - created_by_id
  - parent_project_id
  - total_budget_amount

❌ Incorrecto:
  - createdAt (camelCase)
  - created_date (ambiguo, usar created_at)
  - desc (abreviación)
  - proj_id (abreviación)

Primary Keys

Convención: id

Reglas:
  - SIEMPRE se llama "id"
  - Tipo UUID
  - DEFAULT gen_random_uuid()

✅ Correcto:
CREATE TABLE projects (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  ...
);

❌ Incorrecto:
  - project_id como PK (usar id)
  - pk_projects (nombre complejo)
  - uuid (genérico)

Foreign Keys

Convención:
  - Columna: {tabla_referenciada_singular}_id
  - Constraint: fk_{tabla_origen}_to_{tabla_destino}

✅ Correcto:
  - Columna: project_id, user_id, created_by_id
  - Constraint: fk_developments_to_projects
  - Constraint: fk_projects_to_users

❌ Incorrecto:
  - Columna: project (sin _id)
  - Columna: projectId (camelCase)
  - Constraint: fk_project (incompleto)
  - Constraint: projects_developments_fk (orden invertido)

Índices

Convención: idx_{tabla}_{columnas}_{tipo_opcional}

Reglas:
  - Prefijo idx_
  - snake_case
  - Incluir tipo si no es BTREE: _gist, _gin, _hash

✅ Correcto:
  - idx_projects_code
  - idx_projects_status
  - idx_projects_created_at
  - idx_projects_coordinates_gist
  - idx_projects_metadata_gin
  - idx_projects_status_created_at (compuesto)

❌ Incorrecto:
  - index_projects_code (prefijo largo)
  - projects_code_idx (orden invertido)
  - idx_code (sin tabla)
  - idx_ProjectsCode (PascalCase)

Unique Constraints

Convención: uq_{tabla}_{columna(s)}

✅ Correcto:
  - uq_projects_code
  - uq_users_email
  - uq_project_budgets_project_version

❌ Incorrecto:
  - unique_projects_code (prefijo largo)
  - projects_code_uq (orden invertido)
  - uq_code (sin tabla)

Check Constraints

Convención: chk_{tabla}_{columna}_{descripción}

✅ Correcto:
  - chk_projects_status_valid
  - chk_projects_progress_range
  - chk_budgets_amount_positive

❌ Incorrecto:
  - check_projects_status (prefijo largo)
  - projects_status_chk (orden invertido)
  - chk_status (sin tabla)

Funciones

Convención: {verbo}_{nombre_descriptivo}

Reglas:
  - snake_case
  - Verbo al inicio (get, update, calculate, validate)

✅ Correcto:
  - update_updated_at_column()
  - calculate_project_progress()
  - validate_budget_amount()
  - get_active_projects()

❌ Incorrecto:
  - UpdatedAtUpdate() (PascalCase)
  - updated_at() (sin verbo)
  - fn_update_updated_at (prefijo innecesario)

Triggers

Convención: trg_{tabla}_{acción}

✅ Correcto:
  - trg_projects_updated_at
  - trg_budgets_validate_amount
  - trg_developments_sync_count

❌ Incorrecto:
  - trigger_projects_updated_at (prefijo largo)
  - projects_updated_at_trg (orden invertido)
  - trg_updated_at (sin tabla)

---

2. Backend (TypeScript + Node.js)

Classes

Convención: {Nombre}{Sufijo}

Reglas:
  - PascalCase
  - Sufijo según tipo: Entity, Service, Controller, Dto, Module

✅ Correcto:
  - ProjectEntity
  - ProjectService
  - ProjectController
  - CreateProjectDto
  - ProjectModule

❌ Incorrecto:
  - projectEntity (camelCase)
  - Project_Entity (snake_case)
  - ProjectEnt (abreviación)
  - Entity (sin nombre)

Interfaces

Convención: I{Nombre} o {Nombre} (sin I según preferencia)

Reglas:
  - PascalCase
  - Descriptivo y claro
  - Prefijo I opcional (proyecto por proyecto)

✅ Correcto (con I):
  - IProjectService
  - IUserRepository
  - IAuthProvider

✅ Correcto (sin I):
  - ProjectService
  - UserRepository
  - AuthProvider

❌ Incorrecto:
  - iProjectService (lowercase i)
  - project_service (snake_case)
  - ProjectServiceInterface (sufijo redundante)

Types

Convención: {Nombre}Type o {Nombre}

Reglas:
  - PascalCase
  - Descriptivo

✅ Correcto:
  - ProjectStatus
  - UserRole
  - ApiResponse
  - ProjectWithDevelopments

❌ Incorrecto:
  - projectStatus (camelCase)
  - project_status (snake_case)
  - TProjectStatus (prefijo T redundante si ya está en .types.ts)

Enums

Convención: {Nombre}Enum o {Nombre}

Reglas:
  - PascalCase para nombre
  - UPPER_SNAKE_CASE para valores

✅ Correcto:
enum ProjectStatus {
  DRAFT = 'draft',
  ACTIVE = 'active',
  PAUSED = 'paused',
  COMPLETED = 'completed',
}

enum UserRole {
  ADMIN = 'admin',
  SUPERVISOR = 'supervisor',
  WORKER = 'worker',
}

❌ Incorrecto:
enum projectStatus { ... } (camelCase)
enum ProjectStatus {
  draft = 'draft', (lowercase)
  Active = 'active', (PascalCase)
}

Variables

Convención: camelCase

Reglas:
  - camelCase
  - Descriptivo
  - Evitar abreviaciones
  - Booleanos con prefijo is/has/can

✅ Correcto:
  - project
  - projectList
  - totalBudgetAmount
  - isActive
  - hasPermission
  - canDelete

❌ Incorrecto:
  - Project (PascalCase)
  - project_list (snake_case)
  - prj (abreviación)
  - active (booleano sin is/has)
  - temp (no descriptivo)

Constantes

Convención: UPPER_SNAKE_CASE

Reglas:
  - UPPERCASE
  - Snake_case con guiones bajos
  - Agrupadas en objetos/archivos

✅ Correcto:
const MAX_UPLOAD_SIZE = 5242880; // 5MB
const API_BASE_URL = 'https://api.example.com';
const DEFAULT_PAGE_SIZE = 20;

const DB_TABLES = {
  PROJECTS: 'user_points',
  DEVELOPMENTS: 'developments',
  USERS: 'users',
};

❌ Incorrecto:
const maxUploadSize = 5242880; (camelCase)
const Max_Upload_Size = 5242880; (mixto)
const MAX_UPLOAD (sin valor)

Funciones/Métodos

Convención: {verbo}{Complemento}

Reglas:
  - camelCase
  - Verbo al inicio (get, set, create, update, delete, fetch, calculate)
  - Descriptivo

✅ Correcto:
  - getProjects()
  - createProject()
  - updateProject()
  - deleteProject()
  - fetchProjectById()
  - calculateTotalBudget()
  - validateProjectCode()
  - isProjectActive()

❌ Incorrecto:
  - GetProjects() (PascalCase)
  - get_projects() (snake_case)
  - projects() (sin verbo)
  - get() (no descriptivo)
  - getProjectsFromDatabaseAndFormatThem() (demasiado largo)

Decoradores

Convención: @{Nombre}

Reglas:
  - PascalCase después de @
  - Sin prefijo especial

✅ Correcto:
  @Entity()
  @Column()
  @Injectable()
  @Controller()
  @Get()
  @Post()

❌ Incorrecto:
  @entity() (lowercase)
  @Entity_Decorator() (sufijo redundante)

---

3. Frontend (React + TypeScript)

Componentes React

Convención: {Nombre}{Tipo_opcional}

Reglas:
  - PascalCase
  - Descriptivo
  - Sufijo con tipo si ayuda claridad

✅ Correcto:
  - ProjectCard
  - ProjectListItem
  - CreateProjectModal
  - ProjectFilters
  - Button
  - Input

❌ Incorrecto:
  - projectCard (camelCase)
  - project-card (kebab-case)
  - Card (muy genérico sin contexto)
  - PC (abreviación)

Props de Componentes

Convención: {Componente}Props

✅ Correcto:
interface ProjectCardProps {
  project: Project;
  onClick: () => void;
}

interface ButtonProps {
  label: string;
  variant: 'primary' | 'secondary';
}

❌ Incorrecto:
interface IProjectCardProps { ... } (prefijo I redundante)
interface ProjectCard_Props { ... } (snake_case)
interface Props { ... } (muy genérico)

Hooks Personalizados

Convención: use{Nombre}

Reglas:
  - Prefijo use obligatorio
  - PascalCase después de use
  - Retorna objeto o array

✅ Correcto:
const useProjects = () => { ... }
const useAuth = () => { ... }
const useProjectFilters = () => { ... }

❌ Incorrecto:
const projects = () => { ... } (sin use)
const useprojects = () => { ... } (sin PascalCase)
const getProjects = () => { ... } (no es hook)

Estados (useState)

Convención: {nombre} y set{Nombre}

✅ Correcto:
const [project, setProject] = useState<Project | null>(null);
const [projects, setProjects] = useState<Project[]>([]);
const [isLoading, setIsLoading] = useState(false);
const [hasError, setHasError] = useState(false);

❌ Incorrecto:
const [Project, SetProject] = useState(); (PascalCase)
const [project, updateProject] = useState(); (no usa set)
const [prj, setPrj] = useState(); (abreviación)

Stores (Zustand)

Convención: use{Nombre}Store

✅ Correcto:
const useProjectStore = create<ProjectState>(() => ({ ... }));
const useAuthStore = create<AuthState>(() => ({ ... }));

Uso:
const { projects, fetchProjects } = useProjectStore();

❌ Incorrecto:
const projectStore = create(); (sin use)
const useProjects = create(); (sin Store)
const useProjectsStore = create(); (plural incorrecto)

Acciones de Stores

Convención: {verbo}{Complemento}

✅ Correcto (en store):
{
  fetchProjects: async () => { ... },
  createProject: async (data) => { ... },
  updateProject: async (id, data) => { ... },
  deleteProject: async (id) => { ... },
  setSelectedProject: (project) => { ... },
}

❌ Incorrecto:
{
  FetchProjects: () => { ... }, (PascalCase)
  fetch_projects: () => { ... }, (snake_case)
  get: () => { ... }, (no descriptivo)
}

Event Handlers

Convención: handle{Evento} o on{Evento}

✅ Correcto:
const handleClick = () => { ... };
const handleSubmit = (e: FormEvent) => { ... };
const handleProjectSelect = (project: Project) => { ... };
const onProjectCreate = (project: Project) => { ... };

❌ Incorrecto:
const click = () => { ... }; (sin handle/on)
const HandleClick = () => { ... }; (PascalCase)
const handle_click = () => { ... }; (snake_case)
const clickHandler = () => { ... }; (sufijo en lugar de prefijo)

CSS Classes (si usan CSS Modules)

Convención: kebab-case

✅ Correcto:
.project-card { ... }
.project-list-item { ... }
.button-primary { ... }
.is-active { ... }

❌ Incorrecto:
.ProjectCard { ... } (PascalCase)
.project_card { ... } (snake_case)
.projectCard { ... } (camelCase)

---

📦 NOMENCLATURA DE MÓDULOS Y PAQUETES

1. Módulos de Backend

Convención: kebab-case

✅ Correcto:
  - project-management
  - auth
  - budget-management
  - user-management

❌ Incorrecto:
  - projectManagement (camelCase)
  - gamification_system (snake_case en backend)
  - ProjectManagement (PascalCase)

2. Paquetes npm

Convención: kebab-case con scope opcional

✅ Correcto:
  - @myapp/shared
  - @myapp/components
  - myapp-utils

❌ Incorrecto:
  - @myApp/shared (camelCase)
  - @myapp/Shared (PascalCase)

---

🗂️ NOMENCLATURA DE TAREAS Y DOCUMENTACIÓN

1. IDs de Tareas de Agentes

Convención: {AGENTE}-{NNN}

Reglas:
  - AGENTE en mayúsculas: DB, BE, FE
  - Número de 3 dígitos con ceros leading

✅ Correcto:
  - DB-001
  - DB-042
  - BE-015
  - FE-008

❌ Incorrecto:
  - db-001 (lowercase)
  - DB-1 (sin ceros)
  - DATABASE-001 (nombre completo)
  - DB001 (sin guión)

2. IDs de Subtareas de Subagentes

Convención: {TAREA-PRINCIPAL}-SUB-{NN}

✅ Correcto:
  - DB-042-SUB-01
  - DB-042-SUB-02
  - BE-015-SUB-01

❌ Incorrecto:
  - DB-042-01 (sin SUB)
  - DB-042-SUBAGENT-01 (nombre largo)
  - DB-042-sub-01 (lowercase)

3. Tipos de Tareas

Nomenclatura para carpetas de tareas:

Historia de Usuario:
  US-{NNN}-{nombre-corto}
  Ejemplo: US-001-gestion-proyectos

Feature:
  FEAT-{NNN}-{nombre-corto}
  Ejemplo: FEAT-042-dashboard-proyectos

Bugfix:
  FIX-{NNN}-{nombre-corto}
  Ejemplo: FIX-015-validacion-presupuesto

Tarea Extra:
  TASK-{NNN}-{nombre-corto}
  Ejemplo: TASK-008-migracion-datos

Refactor:
  REFACTOR-{NNN}-{nombre-corto}
  Ejemplo: REFACTOR-023-services-layer

4. Archivos de Documentación

Convención: UPPERCASE-CON-GUIONES.md o {numero}-{nombre}.md

✅ Correcto (documentos principales):
  - README.md
  - CHANGELOG.md
  - CONTRIBUTING.md
  - DIRECTIVA-CONTROL-VERSIONES.md
  - PROMPT-AGENTES-PRINCIPALES.md

✅ Correcto (documentos secuenciales):
  - 01-ANALISIS.md
  - 02-PLAN.md
  - 03-EJECUCION.md
  - 04-VALIDACION.md
  - 05-DOCUMENTACION.md

✅ Correcto (templates):
  - TEMPLATE-PLAN.md
  - TEMPLATE-CONTEXTO-SUBAGENTE.md

❌ Incorrecto:
  - readme.md (lowercase)
  - Readme.md (mixto)
  - ANALISIS.md (sin número si es secuencial)

---

🌐 NOMENCLATURA DE ENDPOINTS API

Convención REST

Formato: /{version}/{recurso}/{id}/{sub-recurso}

Reglas:
  - lowercase
  - kebab-case para recursos compuestos
  - Plural para colecciones
  - Singular para detalle

✅ Correcto:
  GET    /api/v1/projects
  GET    /api/v1/projects/:id
  POST   /api/v1/projects
  PUT    /api/v1/projects/:id
  DELETE /api/v1/projects/:id
  GET    /api/v1/projects/:id/developments
  GET    /api/v1/projects/:id/budget-items

❌ Incorrecto:
  GET /api/v1/Projects (PascalCase)
  GET /api/v1/project (singular para colección)
  GET /api/v1/projects_list (snake_case)
  GET /api/v1/getProjects (verbo en URL)
  GET /api/v1/projects/:id/getDevelopments (verbo)

---

🔤 NOMENCLATURA DE VARIABLES DE ENTORNO

Convención: UPPER_SNAKE_CASE con prefijo

Reglas:
  - UPPERCASE
  - Snake_case
  - Prefijo por categoría: DB_, API_, APP_, AUTH_

✅ Correcto:
  - DATABASE_URL
  - DB_HOST
  - DB_PORT
  - API_BASE_URL
  - APP_PORT
  - AUTH_JWT_SECRET
  - NODE_ENV

❌ Incorrecto:
  - databaseUrl (camelCase)
  - database-url (kebab-case)
  - DATABASEURL (sin separador)
  - url (no descriptivo)

---

✅ TABLA DE REFERENCIA RÁPIDA

Contexto	Convención	Ejemplo
Database
Schema	snake_case + _management	gamification_system
Tabla	snake_case plural	projects
Columna	snake_case singular	created_at
FK columna	{tabla}_id	project_id
FK constraint	fk_{origen}to{destino}	fk_developments_to_projects
Índice	idx_{tabla}_{columnas}	idx_projects_status
Función	{verbo}_{nombre}	update_updated_at_column
Backend
Clase	PascalCase + Sufijo	ProjectEntity
Interface	PascalCase (I opcional)	IProjectService
Variable	camelCase	projectList
Constante	UPPER_SNAKE_CASE	MAX_UPLOAD_SIZE
Método	camelCase con verbo	getProjects()
Archivo	kebab-case.sufijo.ts	project.service.ts
Frontend
Componente	PascalCase	ProjectCard
Hook	use + PascalCase	useProjects
Store	use + PascalCase + Store	useProjectStore
Props	PascalCase + Props	ProjectCardProps
Handler	handle + PascalCase	handleClick
Archivo	PascalCase.tsx	ProjectCard.tsx
Otros
Endpoint	/lowercase/kebab-case	/api/v1/projects
Env var	UPPER_SNAKE_CASE	DATABASE_URL
Tarea	{AGENTE}-{NNN}	DB-042
Carpeta	kebab-case	project-management

---

📖 CASOS ESPECIALES

1. Acrónimos

Regla: Tratar acrónimos como palabras

✅ Correcto:
  - ApiService (no APIService)
  - HttpClient (no HTTPClient)
  - UrlParser (no URLParser)

Excepción en constantes:
  - API_BASE_URL (OK en UPPER_CASE)
  - HTTP_TIMEOUT (OK en UPPER_CASE)

2. Números en Nombres

Evitar números excepto en:
  - Archivos secuenciales: 01-user_points.sql
  - Versiones: v1, v2
  - IDs de tareas: DB-042

❌ Evitar:
  - project2Service
  - user1Repository

3. Booleanos

Prefijos obligatorios: is, has, can, should

✅ Correcto:
  - isActive
  - hasPermission
  - canDelete
  - shouldValidate

❌ Incorrecto:
  - active (sin prefijo)
  - permission (sin has)
  - deleted (ambiguo)

---

🔍 VALIDACIÓN DE NOMENCLATURA

Checklist Pre-Commit

- [ ] Nombres de archivos siguen convenciones
- [ ] Nombres de clases/interfaces en PascalCase
- [ ] Variables en camelCase
- [ ] Constantes en UPPER_SNAKE_CASE
- [ ] Database objects en snake_case
- [ ] Sin abreviaciones ambiguas
- [ ] Nombres descriptivos (no temp, data, item)
- [ ] Booleanos con prefijo is/has/can
- [ ] Métodos con verbo al inicio

---

📚 REFERENCIAS

• ESTANDARES-NOMENCLATURA.md (estándares por capa)
• DIRECTIVA-CALIDAD-CODIGO.md (principios SOLID)
• DIRECTIVA-DISENO-BASE-DATOS.md (normalización)

---

Versión: 1.0.0 Fecha: 2025-11-20 Próxima revisión: Mensual Responsable: Todos los agentes y desarrolladores