From d066fe217c9dbc0743fe03d1a24991a0e223eb5a Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sat, 13 Dec 2025 21:16:48 +0000 Subject: [PATCH] =?UTF-8?q?feat:=20Establecer=20la=20estructura=20de=20orq?= =?UTF-8?q?uestaci=C3=B3n=20de=20agentes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Define la estructura de directorios y la documentación inicial para orquestar el trabajo de los agentes de IA. - Crea los directorios `src` y `docs/agents`. - Genera archivos de bitácora individuales para cada uno de los 13 agentes definidos. - Introduce `docs/CONVENTIONS.md` para establecer las reglas de nomenclatura, estilo de código y contratos de API. - Actualiza el `README.md` principal con una sección que detalla el nuevo flujo de trabajo basado en agentes, explicando cómo deben operar y documentar su progreso. Este cambio sienta las bases para un desarrollo estructurado, trazable y coherente, de acuerdo con el rol del Agente 0 (Arquitectura y Orquestación). --- README.md | 24 ++++- docs/CONVENTIONS.md | 120 ++++++++++++++++++++++++ docs/agents/agent-00-architecture.md | 18 ++++ docs/agents/agent-01-infraestructura.md | 18 ++++ docs/agents/agent-02-backend.md | 18 ++++ docs/agents/agent-03-base.md | 18 ++++ docs/agents/agent-04-importación.md | 18 ++++ docs/agents/agent-05-gestión.md | 18 ++++ docs/agents/agent-06-vacaciones.md | 18 ++++ docs/agents/agent-07-permisos.md | 18 ++++ docs/agents/agent-08-webhooks.md | 18 ++++ docs/agents/agent-09-seguridad.md | 18 ++++ docs/agents/agent-10-frontend.md | 18 ++++ docs/agents/agent-11-testing.md | 18 ++++ docs/agents/agent-12-observabilidad.md | 18 ++++ 15 files changed, 377 insertions(+), 1 deletion(-) create mode 100644 docs/CONVENTIONS.md create mode 100644 docs/agents/agent-00-architecture.md create mode 100644 docs/agents/agent-01-infraestructura.md create mode 100644 docs/agents/agent-02-backend.md create mode 100644 docs/agents/agent-03-base.md create mode 100644 docs/agents/agent-04-importación.md create mode 100644 docs/agents/agent-05-gestión.md create mode 100644 docs/agents/agent-06-vacaciones.md create mode 100644 docs/agents/agent-07-permisos.md create mode 100644 docs/agents/agent-08-webhooks.md create mode 100644 docs/agents/agent-09-seguridad.md create mode 100644 docs/agents/agent-10-frontend.md create mode 100644 docs/agents/agent-11-testing.md create mode 100644 docs/agents/agent-12-observabilidad.md diff --git a/README.md b/README.md index 27f555f..872e812 100644 --- a/README.md +++ b/README.md @@ -254,7 +254,29 @@ No definen reglas nuevas. --- -## 14. Nota final +## 14. Flujo de Trabajo Basado en Agentes + +Este proyecto se desarrolla siguiendo una metodología de **agentes especializados**, donde cada agente (ya sea humano o IA) tiene un conjunto de responsabilidades bien definidas. + +### 14.1 Documentos Clave + +* **`TASKS.md`**: Define el rol y las tareas de cada agente. Este es el punto de partida para cualquier contribución. +* **`docs/CONVENTIONS.md`**: Establece las reglas técnicas y de estilo que todos los agentes deben seguir. La consistencia es fundamental. +* **`docs/agents/`**: Contiene las bitácoras individuales de cada agente. Es **obligatorio** que cada agente documente sus decisiones, progreso y bloqueos en su archivo correspondiente. + +### 14.2 Proceso de Trabajo + +1. **Consultar `TASKS.md`**: Identifica tu rol de agente y las tareas asignadas. +2. **Revisar `docs/CONVENTIONS.md`**: Asegúrate de que tu trabajo se alinee con las convenciones del proyecto. +3. **Ejecutar Tareas**: Implementa la funcionalidad o realiza la tarea asignada. +4. **Actualizar Bitácora**: Documenta lo que hiciste, por qué y cuál fue el resultado en tu archivo de bitácora en `docs/agents/`. +5. **Enviar Cambios**: Sigue las convenciones de nomenclatura de ramas y mensajes de commit. + +Este proceso estructurado garantiza la trazabilidad, facilita la colaboración y permite la orquestación eficiente del trabajo. + +--- + +## 15. Nota final Este README es el **contrato técnico y funcional** del sistema. diff --git a/docs/CONVENTIONS.md b/docs/CONVENTIONS.md new file mode 100644 index 0000000..6d29fb2 --- /dev/null +++ b/docs/CONVENTIONS.md @@ -0,0 +1,120 @@ +# Convenciones del Proyecto – HR Platform + +Este documento define las **convenciones técnicas y de estilo** que deben seguir todos los agentes que contribuyan al proyecto. + +Su objetivo es asegurar la **consistencia, legibilidad y mantenibilidad** del código y la documentación. + +--- + +## 1. Nomenclatura (Naming Conventions) + +### 1.1 General + +* **Idioma:** Inglés para todo el código (variables, funciones, clases). Español para documentación y comentarios si es necesario aclarar un término de negocio específico de la región. +* **Claridad sobre brevedad:** `calculateAnnualLeave` es mejor que `calcLev`. + +### 1.2 Variables y Funciones + +* **Estilo:** `camelCase`. + * Ejemplo: `const currentUser = ...;` + * Ejemplo: `function calculateSalary(...)` + +### 1.3 Clases y Tipos + +* **Estilo:** `PascalCase` (o `UpperCamelCase`). + * Ejemplo: `class EmployeeService { ... }` + * Ejemplo: `interface UserProfile { ... }` + +### 1.4 Constantes + +* **Estilo:** `UPPER_CASE` con guiones bajos. + * Ejemplo: `const MAX_LOGIN_ATTEMPTS = 5;` + +### 1.5 Archivos + +* **Componentes/Módulos:** `PascalCase.js` (ej. `EmployeeCard.js`) +* **Servicios/Rutas/Config:** `kebab-case.js` (ej. `user-routes.js`, `database-config.js`) + +--- + +## 2. Estilo de Código (Code Style) + +### 2.1 JavaScript/Node.js + +* **Formateador:** Prettier con la configuración por defecto. +* **Linter:** ESLint con un conjunto de reglas estándar (ej. `eslint:recommended`). +* **Módulos:** Usar `import`/`export` (ES Modules) en lugar de `require`/`module.exports` (CommonJS) siempre que sea posible. +* **Punto y coma:** Obligatorio. + +### 2.2 Comentarios + +* **Cuándo:** Comentar lógica de negocio compleja, no código obvio. +* **Cómo:** Usar JSDoc para funciones y módulos para describir propósito, parámetros y valores de retorno. + +--- + +## 3. Contratos de API (API Contracts) + +### 3.1 Endpoints + +* **Formato:** RESTful. Usar sustantivos en plural para las colecciones. + * `GET /api/v1/employees` (Obtener todos los empleados) + * `GET /api/v1/employees/{id}` (Obtener un empleado) + * `POST /api/v1/employees` (Crear un empleado) + * `PUT /api/v1/employees/{id}` (Actualizar un empleado) + * `DELETE /api/v1/employees/{id}` (Eliminar un empleado) + +### 3.2 Versionado + +* Incluir el número de versión en la URL: `/api/v1/...` + +### 3.3 Payloads (Request/Response) + +* **Formato:** JSON. +* **Estilo de claves:** `camelCase`. +* **Respuestas de error:** Usar una estructura consistente. + ```json + { + "error": { + "code": "VALIDATION_ERROR", + "message": "El campo 'email' es inválido.", + "details": [ + { "field": "email", "issue": "Formato incorrecto" } + ] + } + } + ``` + +--- + +## 4. Commits en Git + +### 4.1 Mensajes de Commit + +* **Formato:** Conventional Commits. + * `feat: Implementar login de usuarios` + * `fix: Corregir cálculo de vacaciones en años bisiestos` + * `docs: Actualizar README con instrucciones de despliegue` + * `style: Formatear código con Prettier` + * `refactor: Mover lógica de negocio a capa de servicio` + * `test: Añadir pruebas unitarias para el módulo de permisos` + * `chore: Actualizar dependencias de npm` + +### 4.2 Ramas + +* `main`: Rama principal, representa el estado de producción. +* `develop`: Rama de integración para el trabajo en curso. +* `test`: Rama de pruebas. +* **Ramas de feature:** `feature/nombre-corto-del-feature` (ej. `feature/user-auth`) +* **Ramas de bugfix:** `fix/descripcion-corta-del-bug` (ej. `fix/login-error`) + +--- + +## 5. Documentación + +* **Bitácoras de Agente:** Cada agente debe registrar sus decisiones y progreso en su archivo correspondiente en `docs/agents/`. +* **READMEs:** Cualquier nuevo módulo complejo debe tener su propio `README.md` explicando su propósito y uso. + +--- + +Este documento es una guía viva y puede ser actualizado por el **Agente 0 (Arquitectura)** según las necesidades del proyecto. diff --git a/docs/agents/agent-00-architecture.md b/docs/agents/agent-00-architecture.md new file mode 100644 index 0000000..7e1ead6 --- /dev/null +++ b/docs/agents/agent-00-architecture.md @@ -0,0 +1,18 @@ +# Bitácora del Agente 0 – Arquitectura & Orquestación + +Este documento registra las decisiones, cambios y observaciones del **Agente 0**. + +Su propósito es mantener un historial claro y auditable de las directrices arquitectónicas que gobiernan el proyecto. + +--- + +## Entradas de Bitácora + +### [Fecha] - Decisión/Observación + +* **Contexto:** [Descripción del problema o situación] +* **Decisión/Acción:** [Qué se decidió o qué acción se tomó] +* **Justificación:** [Por qué se tomó esa decisión] +* **Impacto:** [Sistemas o agentes afectados] + +--- diff --git a/docs/agents/agent-01-infraestructura.md b/docs/agents/agent-01-infraestructura.md new file mode 100644 index 0000000..3578677 --- /dev/null +++ b/docs/agents/agent-01-infraestructura.md @@ -0,0 +1,18 @@ +# Bitácora del Agente 1 – Infraestructura & DevOps + +Este documento registra las decisiones, cambios y observaciones del **Agente 1**. + +Su propósito es mantener un historial claro y auditable de las tareas y soluciones implementadas. + +--- + +## Entradas de Bitácora + +### [Fecha] - Tarea/Decisión + +* **Contexto:** [Descripción del requerimiento o problema] +* **Acción/Implementación:** [Qué se hizo o cómo se implementó] +* **Resultado:** [Cuál fue el resultado, ej. endpoint creado, test pasado] +* **Observaciones:** [Notas adicionales, dependencias, problemas encontrados] + +--- diff --git a/docs/agents/agent-02-backend.md b/docs/agents/agent-02-backend.md new file mode 100644 index 0000000..ab058a6 --- /dev/null +++ b/docs/agents/agent-02-backend.md @@ -0,0 +1,18 @@ +# Bitácora del Agente 2 – Backend Core (Node.js) + +Este documento registra las decisiones, cambios y observaciones del **Agente 2**. + +Su propósito es mantener un historial claro y auditable de las tareas y soluciones implementadas. + +--- + +## Entradas de Bitácora + +### [Fecha] - Tarea/Decisión + +* **Contexto:** [Descripción del requerimiento o problema] +* **Acción/Implementación:** [Qué se hizo o cómo se implementó] +* **Resultado:** [Cuál fue el resultado, ej. endpoint creado, test pasado] +* **Observaciones:** [Notas adicionales, dependencias, problemas encontrados] + +--- diff --git a/docs/agents/agent-03-base.md b/docs/agents/agent-03-base.md new file mode 100644 index 0000000..e36c9f4 --- /dev/null +++ b/docs/agents/agent-03-base.md @@ -0,0 +1,18 @@ +# Bitácora del Agente 3 – Base de Datos & Modelado + +Este documento registra las decisiones, cambios y observaciones del **Agente 3**. + +Su propósito es mantener un historial claro y auditable de las tareas y soluciones implementadas. + +--- + +## Entradas de Bitácora + +### [Fecha] - Tarea/Decisión + +* **Contexto:** [Descripción del requerimiento o problema] +* **Acción/Implementación:** [Qué se hizo o cómo se implementó] +* **Resultado:** [Cuál fue el resultado, ej. endpoint creado, test pasado] +* **Observaciones:** [Notas adicionales, dependencias, problemas encontrados] + +--- diff --git a/docs/agents/agent-04-importación.md b/docs/agents/agent-04-importación.md new file mode 100644 index 0000000..bcbc961 --- /dev/null +++ b/docs/agents/agent-04-importación.md @@ -0,0 +1,18 @@ +# Bitácora del Agente 4 – Importación Google Sheets + +Este documento registra las decisiones, cambios y observaciones del **Agente 4**. + +Su propósito es mantener un historial claro y auditable de las tareas y soluciones implementadas. + +--- + +## Entradas de Bitácora + +### [Fecha] - Tarea/Decisión + +* **Contexto:** [Descripción del requerimiento o problema] +* **Acción/Implementación:** [Qué se hizo o cómo se implementó] +* **Resultado:** [Cuál fue el resultado, ej. endpoint creado, test pasado] +* **Observaciones:** [Notas adicionales, dependencias, problemas encontrados] + +--- diff --git a/docs/agents/agent-05-gestión.md b/docs/agents/agent-05-gestión.md new file mode 100644 index 0000000..94ca64b --- /dev/null +++ b/docs/agents/agent-05-gestión.md @@ -0,0 +1,18 @@ +# Bitácora del Agente 5 – Gestión de Socias + +Este documento registra las decisiones, cambios y observaciones del **Agente 5**. + +Su propósito es mantener un historial claro y auditable de las tareas y soluciones implementadas. + +--- + +## Entradas de Bitácora + +### [Fecha] - Tarea/Decisión + +* **Contexto:** [Descripción del requerimiento o problema] +* **Acción/Implementación:** [Qué se hizo o cómo se implementó] +* **Resultado:** [Cuál fue el resultado, ej. endpoint creado, test pasado] +* **Observaciones:** [Notas adicionales, dependencias, problemas encontrados] + +--- diff --git a/docs/agents/agent-06-vacaciones.md b/docs/agents/agent-06-vacaciones.md new file mode 100644 index 0000000..6ede962 --- /dev/null +++ b/docs/agents/agent-06-vacaciones.md @@ -0,0 +1,18 @@ +# Bitácora del Agente 6 – Vacaciones (Reglas de Negocio) + +Este documento registra las decisiones, cambios y observaciones del **Agente 6**. + +Su propósito es mantener un historial claro y auditable de las tareas y soluciones implementadas. + +--- + +## Entradas de Bitácora + +### [Fecha] - Tarea/Decisión + +* **Contexto:** [Descripción del requerimiento o problema] +* **Acción/Implementación:** [Qué se hizo o cómo se implementó] +* **Resultado:** [Cuál fue el resultado, ej. endpoint creado, test pasado] +* **Observaciones:** [Notas adicionales, dependencias, problemas encontrados] + +--- diff --git a/docs/agents/agent-07-permisos.md b/docs/agents/agent-07-permisos.md new file mode 100644 index 0000000..2604861 --- /dev/null +++ b/docs/agents/agent-07-permisos.md @@ -0,0 +1,18 @@ +# Bitácora del Agente 7 – Permisos + +Este documento registra las decisiones, cambios y observaciones del **Agente 7**. + +Su propósito es mantener un historial claro y auditable de las tareas y soluciones implementadas. + +--- + +## Entradas de Bitácora + +### [Fecha] - Tarea/Decisión + +* **Contexto:** [Descripción del requerimiento o problema] +* **Acción/Implementación:** [Qué se hizo o cómo se implementó] +* **Resultado:** [Cuál fue el resultado, ej. endpoint creado, test pasado] +* **Observaciones:** [Notas adicionales, dependencias, problemas encontrados] + +--- diff --git a/docs/agents/agent-08-webhooks.md b/docs/agents/agent-08-webhooks.md new file mode 100644 index 0000000..8e30d4e --- /dev/null +++ b/docs/agents/agent-08-webhooks.md @@ -0,0 +1,18 @@ +# Bitácora del Agente 8 – Webhooks & Eventos + +Este documento registra las decisiones, cambios y observaciones del **Agente 8**. + +Su propósito es mantener un historial claro y auditable de las tareas y soluciones implementadas. + +--- + +## Entradas de Bitácora + +### [Fecha] - Tarea/Decisión + +* **Contexto:** [Descripción del requerimiento o problema] +* **Acción/Implementación:** [Qué se hizo o cómo se implementó] +* **Resultado:** [Cuál fue el resultado, ej. endpoint creado, test pasado] +* **Observaciones:** [Notas adicionales, dependencias, problemas encontrados] + +--- diff --git a/docs/agents/agent-09-seguridad.md b/docs/agents/agent-09-seguridad.md new file mode 100644 index 0000000..4f80915 --- /dev/null +++ b/docs/agents/agent-09-seguridad.md @@ -0,0 +1,18 @@ +# Bitácora del Agente 9 – Seguridad & Autorización + +Este documento registra las decisiones, cambios y observaciones del **Agente 9**. + +Su propósito es mantener un historial claro y auditable de las tareas y soluciones implementadas. + +--- + +## Entradas de Bitácora + +### [Fecha] - Tarea/Decisión + +* **Contexto:** [Descripción del requerimiento o problema] +* **Acción/Implementación:** [Qué se hizo o cómo se implementó] +* **Resultado:** [Cuál fue el resultado, ej. endpoint creado, test pasado] +* **Observaciones:** [Notas adicionales, dependencias, problemas encontrados] + +--- diff --git a/docs/agents/agent-10-frontend.md b/docs/agents/agent-10-frontend.md new file mode 100644 index 0000000..e730d8b --- /dev/null +++ b/docs/agents/agent-10-frontend.md @@ -0,0 +1,18 @@ +# Bitácora del Agente 10 – Frontend (Staging) + +Este documento registra las decisiones, cambios y observaciones del **Agente 10**. + +Su propósito es mantener un historial claro y auditable de las tareas y soluciones implementadas. + +--- + +## Entradas de Bitácora + +### [Fecha] - Tarea/Decisión + +* **Contexto:** [Descripción del requerimiento o problema] +* **Acción/Implementación:** [Qué se hizo o cómo se implementó] +* **Resultado:** [Cuál fue el resultado, ej. endpoint creado, test pasado] +* **Observaciones:** [Notas adicionales, dependencias, problemas encontrados] + +--- diff --git a/docs/agents/agent-11-testing.md b/docs/agents/agent-11-testing.md new file mode 100644 index 0000000..d1921b0 --- /dev/null +++ b/docs/agents/agent-11-testing.md @@ -0,0 +1,18 @@ +# Bitácora del Agente 11 – Testing & QA + +Este documento registra las decisiones, cambios y observaciones del **Agente 11**. + +Su propósito es mantener un historial claro y auditable de las tareas y soluciones implementadas. + +--- + +## Entradas de Bitácora + +### [Fecha] - Tarea/Decisión + +* **Contexto:** [Descripción del requerimiento o problema] +* **Acción/Implementación:** [Qué se hizo o cómo se implementó] +* **Resultado:** [Cuál fue el resultado, ej. endpoint creado, test pasado] +* **Observaciones:** [Notas adicionales, dependencias, problemas encontrados] + +--- diff --git a/docs/agents/agent-12-observabilidad.md b/docs/agents/agent-12-observabilidad.md new file mode 100644 index 0000000..17b45aa --- /dev/null +++ b/docs/agents/agent-12-observabilidad.md @@ -0,0 +1,18 @@ +# Bitácora del Agente 12 – Observabilidad & Calidad + +Este documento registra las decisiones, cambios y observaciones del **Agente 12**. + +Su propósito es mantener un historial claro y auditable de las tareas y soluciones implementadas. + +--- + +## Entradas de Bitácora + +### [Fecha] - Tarea/Decisión + +* **Contexto:** [Descripción del requerimiento o problema] +* **Acción/Implementación:** [Qué se hizo o cómo se implementó] +* **Resultado:** [Cuál fue el resultado, ej. endpoint creado, test pasado] +* **Observaciones:** [Notas adicionales, dependencias, problemas encontrados] + +---