> For the complete documentation index, see [llms.txt](https://rws.gitbook.io/rws/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rws.gitbook.io/rws/estructura-repositorio-agentico-v2-es.md). # Estructura de Repositorio Co-Existente para Humanos y Agentes de IA (V2) > \[!NOTE] **BLUF (Bottom-Line Up Front)**: La estructuración de un repositorio como espacio de trabajo único y co-existente para humanos y agentes de IA —gobernado por un acoplamiento bidireccional estricto (Código-Prueba-Especificación) y un Lenguaje Ubicuo vivo— elimina la entropía de contexto, reduciendo los bucles de alucinación de IA y acelerando la entrega continua de software con trazabilidad total. ## Introducción Estructurada (SCQA) * **Situación**: Los equipos de ingeniería de software utilizan repositorios Git para almacenar código fuente y asistentes cognitivos de IA para acelerar vertiginosamente la escritura y refactorización de programas. * **Complicación**: El principal cuello de botella en el desarrollo asistido por IA se ha convertido en la desalineación y la entropía de contexto en el repositorio. La documentación estática que queda obsoleta ("especificación ficción") genera alucinaciones de términos, variables redundantes y bucles infinitos de "vibe coding". * **Pregunta**: *¿Cómo estructurar y gobernar la topología de carpetas del repositorio para que funcione como un entorno operativo co-existente y fuente única de verdad viva para Product Managers, Desarrolladores Humanos y Agentes de IA?* * **Respuesta**: Implementar el blueprint de repositorio co-existente, que unifica Domain-Driven Design (DDD), Pensamento Sistémico y Especificación Ejecutiva acoplada a pruebas de aceptación automatizadas, estableciendo reglas claras de consumo por perfil y ciclo de vida mediante metadatos de estado. *** ## 1. El Blueprint de la Estructura de Repositorio El repositorio a continuación está estructurado para reflejar las definiciones del dominio de negocio directamente en la arquitectura física de carpetas, garantizando trazabilidad absoluta entre producto, documentación e implementación: ``` my-project/ ├── .agents/ # Configuraciones y reglas locales de IA │ ├── rules/ # Regras específicas por dominio/squad (AGENTS.md locales) │ └── skills/ # Habilidades y scripts personalizados de los agentes ├── docs/ # Documentación viva y especificaciones de producto │ ├── adr/ # Architectural Decision Records (Registros de Decisiones de Diseño) │ ├── proposals/ # Propuestas colaborativas (RFCs) en debate (Bottom-Up) │ │ └── RFC-XXXX-slug.md # Metadatos de estado (draft/accepted) y propuesta detallada │ ├── context/ # Contextos Delimitados (Bounded Contexts) │ │ ├── CONTEXT-MAP.md # Mapa de relaciones e interfaces de dominio │ │ ├── domain-a/ │ │ │ ├── CONTEXT.md # Glosario (Lenguaje Ubicuo) con metadatos de estado (stable/exploration/deprecated) │ │ │ └── specs/ # Especificaciones de comportamiento (Markdown / EARS) │ │ ├── domain-b/ │ │ │ ├── CONTEXT.md │ │ │ └── specs/ │ │ └── shared/ # Contextos transversales / inter-dominio (Shared Kernel) │ │ ├── CONTEXT.md # Glosario común con metadados de estado │ │ └── specs/ # Especificaciones de comportamiento de servicios comunes │ ├── product-artifacts/ # Artefactos Lógicos de Producto (Espacio de Trabajo PM/UX) │ │ ├── okrs/ # Objetivos y Resultados Clave corporativos y de dominio (Padre de las Iniciativas) │ │ ├── initiatives/ # Iniciativas de valor (Hijas de los OKRs; vinculan los PR-FAQs y PRDs) │ │ ├── pr-faqs/ # Press Releases & FAQs (Visión de éxito de cliente; vinculados a las Iniciativas) │ │ ├── prds/ # Product Requirement Documents (Outcomes y criterios; vinculados a las Iniciativas) │ │ ├── roadmaps/ # Hitos temporales y cronogramas de apuestas (Bets) │ │ └── story-maps/ # Desglose táctico y releases (MVP, R2, R3 en Mermaid) │ ├── raw-data/ # Datos Brutos de Entrada (Bandeja de Entrada de Ingestión e Insumos) │ │ └── raw-notes.md # Notas brutas de reuniones, transcripciones y benchmarks externos │ └── architecture/ # Visiones globales de sistema (System Thinking) │ └── system-architecture.md# Mapeo de bucles de retroalimentación, límites y flujos ├── src/ # Código fuente (Estructurado según dominios de DDD) │ ├── domain-a/ │ │ ├── application/ # Casos de uso y orquestación │ │ ├── domain/ # Entidades, agregados y reglas de dominio puras │ │ ├── infrastructure/ # Base de datos, adaptadores y APIs externas │ │ └── test/ # Pruebas que validam docs/context/domain-a/specs/ │ ├── domain-b/ │ └── shared/ # Código transversal común (Shared Kernel e Infraestructura) │ ├── domain/ # Entidades y Value Objects globales (ej: CustomerId) │ ├── infrastructure/ # Conectores de base de datos, logs y middlewares comunes │ └── test/ # Pruebas que validam docs/context/shared/specs/ ├── AGENTS.md # Punto de entrada (README) para los Agentes de IA └── README.md # Punto de entrada (README) para Desarrolladores Humanos ``` *** ## 2. Uso de la Estructura por Perfil (PM, Desarrollador e IA) Cada miembro del equipo interactúa con el repositorio a través de lentes distintas, alimentando y consumiendo el contexto según sus responsabilidades operativas: ### A. El Product Manager (PM) * **Dónde trabaja**: Opera en las carpetas `docs/product-artifacts/`, `docs/raw-data/` y `docs/proposals/`. * **Cómo consume**: * Deposita en la carpeta `raw-data/` los insumos brutos externos de discovery (como transcripciones de entrevistas con usuarios, informes de mercado o correos de reclamos). * Define las metas estratégicas en `okrs/`, que actúan como "padres" orientadores de las iniciativas. * Estructura las `initiatives/` (hijas directas de los OKRs), que centralizan el contexto de negocio. * Vincula en las iniciativas los artefactos de discovery (`pr-faqs/` bajo el estándar Amazon) y los documentos de requisitos de producto (`prds/`). * Mapea el cronograma macro en `roadmaps/` y diseña el desglose táctico en `story-maps/` utilizando diagramas de flujo Mermaid colapsables. * Controla el ciclo de vida de los archivos en `docs/product-artifacts/` (OKRs, Iniciativas, PRDs, PR-FAQs, Roadmaps, Story Maps) y `docs/proposals/` utilizando metadatos de estado en sus encabezados YAML frontmatter (ej: `status: draft`, `status: active`/`accepted`, `status: deprecated`). * Revisa propuestas en `docs/proposals/` y altera el metadato `status` a `accepted` para aprobar nuevas ideas. * **Valor**: El PM utiliza el repositorio como el espacio de trabajo inicial de diseño de producto. La carpeta `raw-data/` sirve como la "bandeja de entrada de ingestión" para que la IA consuma información de la vida real, generando especificaciones basadas en evidencias concretas en lugar de premisas inventadas. ### B. El Desarrollador Humano * **Dónde trabaja**: Opera principalmente en `src/`, `docs/adr/` y `docs/proposals/`. * **Cómo consume**: * Lee los artefactos de producto en `docs/product-artifacts/` para comprender la visión, dependencias temporales y alcance de las entregas (*releases*). * Implementa el código bajo la organización de Bounded Contexts en `src/`. * Escribe registros de decisión en `docs/adr/` para documentar trade-offs arquitectónicos difíciles de revertir o que serían sorprendentes en el futuro, reduciendo la carga cognitiva de reuniones de alineación técnica. * Propone mejoras de producto o simplificaciones conceptuales creando RFCs en `docs/proposals/` con `status: draft`. ### C. El Agente de IA (AI Coding Assistant) * **Dónde trabaja**: Consume todo el repositorio, pero es guiado por `AGENTS.md` y `.agents/`. * **Cómo consume**: * Lee el archivo `AGENTS.md` al inicio de la sesión para absorber las directrices operativas del proyecto (estilo de commits, comandos de build y enrutamiento de pruebas). * Consume el glosario local `docs/context//CONTEXT.md` para descubrir la nomenclatura exacta de la **Lenguaje Ubicuo** (evitando generar variables homónimas o sinónimos confusos en la base de datos), respetando y validando el ciclo de vida/estado del contexto. * Aplica las reglas específicas contenidas en `.agents/rules/` aplicadas a subcarpetas de squads. * Escanea `docs/proposals/` y, al detectar propuestas con `status: accepted`, sincroniza y propaga las alteraciones en los archivos de especificación y glosario de dominio. *** ## 3. Manteniendo la Base Viva: Conexión Código-Prueba-Especificación El mayor riesgo de cualquier base de conocimiento es su degradación cronológica. Para impedir que la documentación se convierta en una "especificación ficción", el modelo utiliza la metodología de **Especificación Ejecutiva**: ```mermaid graph TD %% Clases de Estilo Neutras e IDE-Safe classDef entryExit fill:#0f172a,stroke:#10b981,stroke-width:2px,color:#e2e8f0; classDef doc fill:#0f172a,stroke:#3b82f6,stroke-width:1px,color:#e2e8f0; classDef test fill:#18181b,stroke:#a1a1aa,stroke-width:1px,color:#e2e8f0; classDef fail fill:#31101b,stroke:#f43f5e,stroke-width:1.5px,color:#fecdd3; Start([Alteración de Requisito]):::entryExit --> EditSpec[docs/context/domain/specs/specs.md]:::doc EditSpec --> RunTest[Ejecutar Prueba de Aceptación en src/domain/test/]:::test RunTest --> Check{¿Pruebas Coinciden?}:::cond Check -->|No| Fail[Código y Spec Desalineados - Build Se Quiebra]:::error Check -->|Sí| Save[Código Actualizado y Living Doc Sincronizada]:::entryExit Fail --> Fix[Ingeniero/IA Corrige el Código o Actualiza la Spec]:::action Fix --> RunTest ``` * **Acoplamiento Bidireccional**: Las especificaciones de comportamiento en la carpeta `docs/context/domain/specs/` (escritas en formato Markdown simplificado usando EARS y Tablas de Decisión) están vinculadas directamente a las pruebas de aceptación en `src/domain/test/`. Si el desarrollador humano o la IA alteran el comportamiento del código físico sin actualizar las especificaciones correspondientes, **el pipeline de Integración Continua (CI/CD) se rompe**. * **El Bucle de Interrogatorio (Sabatina)**: Siempre que se diseñe una nueva lógica en la conversación, el desarrollador humano ejecuta la sabatina `/grill-with-docs` para que el agente de IA reevalúe las definiciones de `CONTEXT.md` antes de generar código físico, garantizando que el glosario se expanda de forma viva y bajo demanda. ### El Flujo Bottom-Up y Ciclo de Vida de RFCs Cuando un desarrollador identifica una oportunidad de mejora en el producto o simplificación de dominio a partir de la lectura del código o de las especificaciones: ```mermaid graph TD %% Clases de Estilo Neutras e IDE-Safe classDef start fill:#0f172a,stroke:#10b981,stroke-width:2px,color:#e2e8f0; classDef doc fill:#0f172a,stroke:#3b82f6,stroke-width:1px,color:#e2e8f0; classDef review fill:#18181b,stroke:#eab308,stroke-width:1.5px,color:#fef9c3; classDef sync fill:#1e1b4b,stroke:#818cf8,stroke-width:1.5px,color:#e0e7ff; Start([Dev lee specs/código y propone mejora]):::start --> Draft[IA auxilia al Dev a redactar RFC en docs/proposals/ con status: draft]:::doc Draft --> Review[PM revisa RFC física o vía Pull Request]:::review Review --> Choice{¿PM Acepta?} Choice -->|No| Archive[RFC Archivada o Ajustada]:::doc Choice -->|Sí| Accept[Estado alterado a status: accepted o PR fusionado]:::start Accept --> SyncDocs[Agente de IA propaga specs, CONTEXT.md y PRDs]:::sync SyncDocs --> Implement[Dev/IA codifican y prueban la nueva Spec]:::start ``` * **Independencia de Git**: El ciclo de vida de la propuesta (`draft` -> `under-review` -> `accepted`) se controla directamente mediante metadatos (frontmatter YAML) en la parte superior del archivo de propuesta. Esto permite que los equipos usen Git (vía Pull Requests) o carpetas compartidas sincronizadas (donde el PM solo cambia el estado en el archivo de texto). *** ## 4. Directrices de Gobernanza para Agentes de IA Para garantizar que la IA actúe como una mantenedora activa de la base de conocimiento (y no como una generadora de basura y contaminación de archivos), las siguientes reglas deben inyectarse como instrucciones obligatorias del sistema o configurarse en el archivo `.agents/rules/`: ### 1. **Prioridad de Lectura de Contexto (Read First)** * La IA **nunca** debe escribir código ni proponer modificaciones de arquitectura antes de escanear y analizar `AGENTS.md`, los glosarios de `CONTEXT.md` correspondientes al dominio de la tarea y los últimos 5 ADRs en `docs/adr/`. ### 2. **Alineación Terminológica Estricta** * La IA tiene prohibido introducir nuevos términos de variables, tablas o entidades de base de datos que difieran del glosario oficial del contexto. * *Ejemplo*: Si el glosario define **`PO` (Purchase Order)** y condena explícitamente el sinónimo `PedidoDeCompra` o `PurchaseOrder` en la sección de alias a evitar, la IA debe utilizar estrictamente el término `po` en todas las clases, métodos y tablas de base de datos generadas. * **Respeto al Ciclo de Vida del Contexto**: La IA debe monitorear el metadato `status` en el encabezado YAML frontmatter de cada `CONTEXT.md`: * `status: stable`: El modelo de lenguaje ubicuo está consolidado. La IA debe seguirlo al pie de la letra y evitar proponer nuevos alias o variaciones. * `status: exploration`: El contexto está siendo mapeado o refinado activamente. La IA tiene flexibilidad para sugerir términos y estructurar nuevas entidades usando el bucle `/grill-with-docs`. * `status: deprecated`: El contexto o conceptos cayeron en desuso. La IA debe negarse a codificar nuevas lógicas dependientes de esos archivos y alertar al desarrollador sobre la depreciación. ### 3. **Actualización Co-Existente de Documentación (No Ghost Features)** * Cualquier Pull Request de funcionalidad generado por la IA **debe contener obligatoriamente** la actualización correspondiente en los archivos del dominio. Si se agrega un nuevo parámetro de comportamiento a la regla de negocio, la especificación correspondiente en `docs/context//specs/` debe editarse en el mismo PR. ### 4. **Creación Vaga de ADRs (Lazy ADRs)** * Al proponer desviaciones de diseño o elecciones con alto lock-in tecnológico, la IA debe generar un borrador de ADR en `docs/adr/` solo si la decisión satisface simultáneamente las 3 premisas: ser difícil de revertir, ser sorprendente para futuros ingenieros sin contexto y ser fruto de un trade-off legítimo entre alternativas viables. ### 5. **Barrera de Alcance Basada en Releases y Estado (Scope Guard)** * Al implementar nuevas funciones, la IA debe consultar activamente el estado de los artefactos de producto en `docs/product-artifacts/` (PRDs, Story Maps, etc.). Está instruida para codificar y generar comportamientos basados únicamente en artefactos de producto marcados como `status: active` o `status: approved`. * La IA debe consultar el roadmap y el desglose de releases en `docs/product-artifacts/story-maps/` del respectivo dominio. Si el usuario solicita la codificación de una funcionalidad descrita en un artefacto en `status: draft`, o mapeada para una versión futura (ej: Release 2) mientras el ciclo actual está bloqueado en otra iteración (ej: MVP), la IA debe emitir una alerta de alcance y opcionalmente simular stubs/mocks en lugar de codificar la lógica real de forma precipitada (*gold plating*). ### 6. **Escaneo y Sincronización de Propuestas (RFC Auto-Sync)** * La IA debe monitorear la carpeta `docs/proposals/` al inicio de cada tarea. Si encuentra una propuesta con `status: accepted` cuyas especificaciones correspondientes en `docs/context//specs/` o glosarios en `docs/context//CONTEXT.md` aún no hayan sido actualizados, la IA debe actualizar dichos artefactos de documentación antes de generar o modificar el código fuente. ### 7. **Protección de Kernel Compartido (Shared Kernel Guard)** * La IA tiene prohibido alterar de forma autónoma archivos bajo `docs/context/shared/` o `src/shared/` sin antes validar el impacto multidominio descrito en `docs/context/CONTEXT-MAP.md`. En caso de proponer una alteración en entidades o contratos transversales (como esquemas comunes, tipos globales o eventos consumidos por múltiples dominios), la IA debe obligatoriamente describir los dominios afectados en el chat y proponer la creación de un ADR o de una RFC de impacto global. *** ## 5. Ecosistema Operativo: Agentes y Habilidades (Skills) Para garantizar que la gobernanza de código y documentación ocurra sin fricciones y con alta fidelidad, el repositorio se opera mediante una clara división entre **Quién Ejecuta (Agentes/Personas)** y **Cómo Ejecuta (Skills/Herramientas)**. Las Skills residen en `.agents/skills/` y los Agentes son roles cognitivos orientados por directrices específicas. ### A. El Portafolio de Skills (Herramientas y Procedimientos) Las Skills son scripts deterministas, utilidades locales o prompts estructurados paso a paso: * **`grill-with-docs` (Refinador de Contexto)**: Protocolo de interrogatorio interactivo que lee glosarios y especificaciones para identificar ambigüedades, forzando la alineación terminológica y guardando los términos resueltos directamente en los archivos físicos de documentación. * **`compile-product-artifact` (Compilador de Requisitos)**: Motor que consume archivos PRD o RFC marcados como `status: active` o `status: accepted` y extrae automáticamente los términos al `CONTEXT.md` y reglas funcionales al `specs/specs.md` en estándar EARS. * **`specs-to-test-boilerplate` (Plantillas de Prueba)**: Utilidad que lee las especificaciones escritas en EARS y genera el esqueleto (*stub*) de los archivos de pruebas técnicas en `src//test/`, manteniendo la trazabilidad 1 a 1. * **`context-map-linter` (Validador de Fronteras)**: Script ejecutado localmente o en el CI/CD que analiza los `imports` del código físico para impedir violaciones de acoplamiento no declaradas en `docs/context/CONTEXT-MAP.md`. * **`adr-wizard` (Asistente de Decisiones)**: Asistente interactivo que valida las 3 condiciones obligatorias para la creación de un ADR y genera el esqueleto estandarizado en `docs/adr/`. ### B. Agentes Especializados (Roles Cognitivos) Los Agentes asumen "lentes" de visualización distintas y consumen las Skills anteriores para interactuar con el equipo: * **`ProductRefiner` (PM Digital)**: Enfocado en outcomes de negocio, OKRs y desglose táctico. Opera en `docs/raw-data/` y `docs/product-artifacts/`. * **`DomainArchitect` (Guardián del DDD)**: Enfocado en la integridad conceptual, nomenclatura del lenguaje ubicuo y límites transaccionales. Opera en `docs/context/` y `docs/adr/`. * **`SpecVerifier` (Garantía de Calidad/QA)**: Enfocado en la capacidad de prueba, cobertura y alineación del código con la especificación funcional. Opera en `specs/` y `src//test/`. ### C. Aceleración del Proceso de Product Management (El Bucle del PM) El PM logra reducir el ciclo de escritura de PRDs y alineación técnica usando el agente `ProductRefiner` equipado con la skill `grill-with-docs`. El flujo ocurre de la siguiente manera: ```mermaid graph TD %% Clases de Estilo Neutras e IDE-Safe classDef pm fill:#0f172a,stroke:#3b82f6,stroke-width:1.5px,color:#e2e8f0; classDef ai fill:#1e1b4b,stroke:#818cf8,stroke-width:1.5px,color:#e0e7ff; classDef dev fill:#0f172a,stroke:#10b981,stroke-width:2px,color:#e2e8f0; Ingest[1. Ingestión: PM inserta ideas brutas en docs/raw-data/raw-notes.md]:::pm --> DraftPRD[2. Borrador: ProductRefiner lee las notas y genera PRD/PR-FAQ con status: draft]:::ai DraftPRD --> Grill[3. Sabatina: PM activa la skill grill-with-docs en el PRD draft]:::pm Grill --> Ask{4. ¿IA detecta vacíos conceptuales, conflictos o faltas de errores?}:::ai Ask -->|Sí| Answers[5. PM responde las preguntas de la IA en el chat]:::pm Answers --> Grill Ask -->|No| Active[6. Aprobación: PM cambia el PRD a status: active]:::pm Active --> Compile[7. Compilación: Se ejecuta la skill compile-product-artifact]:::ai Compile --> Sync[8. Sincronización: CONTEXT.md y specs/specs.md generados automáticamente]:::ai Sync --> DevReady([9. Listo para Dev: IA y Desarrolladores implementan en src/]):::dev ``` * **Ventaja Competitiva:** El PM no necesita dedicar días a detallar escenarios de error ni a traducir reglas de negocio complejas. La IA asume la carga cognitiva de encontrar brechas de lógica y redactar el documento técnico final, mientras que el PM actúa únicamente como el validador estratégico de las decisiones. *** \[\[index]] --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://rws.gitbook.io/rws/estructura-repositorio-agentico-v2-es.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.