¿Qué convenciones de directorios y estilos de código siguen bien Codex y Claude Code?

Codex y Claude Code no prefieren de forma inherente un lenguaje de programación, framework, ancho de sangría o estructura de carpetas en particular. Los entornos que pueden seguir con relativa fiabilidad son aquellos en los que las convenciones existentes del repositorio son coherentes, el alcance de las reglas necesarias está claro y los cambios se pueden validar automáticamente. Por tanto, el objetivo no es inventar una estructura que pueda gustarle a una IA, sino hacer que las convenciones del proyecto sean breves y verificables para que las entiendan las personas y los nuevos colaboradores. openai.com↗code.claude.com↗

Aquí, Codex y Claude Code se refieren a herramientas de agentes de programación que pueden leer archivos de un repositorio, consultar instrucciones, modificar código o ejecutar comandos. Estas herramientas obtienen muchas pistas del propio código, pero no siempre pueden inferir con precisión la terminología del dominio del producto, los cambios prohibidos, las comprobaciones previas al despliegue o las reglas de excepción para carpetas concretas. La estructura del repositorio, los archivos de instrucciones y los procedimientos de validación ejecutables cubren esa carencia. cdn.openai.com↗

¿Por qué es más importante la coherencia que la «estructura de carpetas correcta»?

Por ejemplo, un equipo puede organizar src/payments/ y src/users/ por funcionalidad, mientras que otro puede organizar src/controllers/, src/services/ y src/repositories/ por capas. No hay base para afirmar de forma concluyente que alguno de los dos enfoques sea automáticamente mejor para Codex o Claude Code. Lo importante es que las responsabilidades del mismo tipo tengan ubicaciones similares dentro de un repositorio, que los archivos nuevos se coloquen según los mismos criterios y que las pruebas y los estilos de importación sigan los patrones existentes.

Lo mismo se aplica cuando un agente añade una nueva funcionalidad de pagos. Si el módulo de pagos existente muestra cómo se organizan la validación de solicitudes, el manejo de errores, el acceso a datos y las pruebas, continuar ese patrón es más seguro. Por el contrario, si cada funcionalidad nueva introduce nombres de archivo y capas nuevos, o si una sola carpeta mezcla código de dominio con artefactos de compilación y archivos temporales, tanto los agentes como las personas tendrán dificultades para determinar dónde realizar cambios y qué afectan esos cambios.

Por tanto, las convenciones de directorios no son meramente reglas de apariencia. Son un sistema de navegación que revela dónde encontrar código, qué se debe cambiar conjuntamente y qué validación ejecutar. Cuanto más estables sean los nombres y los límites, menos necesario será repetir explicaciones extensas en los archivos de instrucciones.

¿Dónde debería residir la orientación básica del repositorio?

En Codex, AGENTS.md suele servir como archivo de instrucciones del proyecto. Las instrucciones de estilo de código, estructura, nomenclatura y pruebas contenidas en este archivo se aplican al directorio que lo contiene y a su subárbol, mientras que las instrucciones ubicadas en niveles más profundos pueden actuar como orientación más específica cuando surgen conflictos. También se admiten instrucciones para entornos personales y anulaciones mediante AGENTS.override.md. openai.com↗

En Claude Code, CLAUDE.md o .claude/CLAUDE.md pueden servir como centro de memoria y orientación del proyecto. Un archivo CLAUDE.md en una ruta principal puede proporcionarse como contexto al inicio, mientras que los archivos de subdirectorios se cargan según sea necesario al gestionar archivos en esas rutas. También puede utilizar CLAUDE.local.md para configuraciones por usuario y archivos en el nivel del directorio personal. code.claude.com↗

Aunque los dos archivos tienen nombres similares, su comportamiento de detección automática no es el mismo. En particular, no suponga que Claude Code lee automáticamente AGENTS.md como instrucciones compartidas. Si utiliza ambas herramientas, importe el archivo compartido en CLAUDE.md con @AGENTS.md, o defina explícitamente una conexión que se adapte al modelo operativo del equipo. code.claude.com↗

Es mejor que el archivo de orientación raíz se parezca más a un mapa de entrada que a una enciclopedia que describa extensamente todo el repositorio. Basta con mostrar los comandos que necesita primero un colaborador nuevo, la estructura de nivel superior, los invariantes clave y las ubicaciones de la documentación detallada. Un único archivo de instrucciones extenso consume contexto que debería usarse para el código real y los requisitos de la tarea, y puede dificultar advertir las restricciones críticas. Un ejemplo relacionado con OpenAI Codex también presenta una combinación de un archivo corto, similar a un mapa, de unas 100 líneas y documentación separada. openai.com↗

¿Qué deberían incluir AGENTS.md y CLAUDE.md?

Las buenas instrucciones no duplican extensamente hechos que ya son evidentes en el código. En su lugar, priorizan la información que es difícil de aprender solo a partir del código o cuyo error de inferencia resulta costoso. Los materiales relacionados con Codex identifican las convenciones de nomenclatura, el lenguaje del dominio, las restricciones y dependencias conocidas, y los procedimientos de compilación y pruebas como información que vale la pena incluir en AGENTS.md. cdn.openai.com↗

Las instrucciones raíz pueden responder de forma concisa a preguntas como estas:

• ¿Qué comandos ejecutan el formateo, el análisis estático, la comprobación de tipos y las pruebas después de un cambio inicial?
• ¿Dónde se encuentran el código fuente, las pruebas, la documentación de diseño y la documentación operativa?
• ¿Qué convenciones de nomenclatura de archivos, importaciones, manejo de errores y pruebas se deben seguir al ampliar un módulo existente?
• ¿Se pueden modificar o incluir en el repositorio archivos generados, artefactos de compilación, archivos de bloqueo y secretos?
• ¿Las áreas de alto riesgo requieren un plan, revisión adicional o pruebas concretas?
• ¿Qué documentos contienen los procedimientos detallados de diseño y operación?

En cambio, afirmaciones amplias como «escriba código limpio», «priorice la seguridad» o «haga lo mejor posible» son difíciles de convertir en reglas ejecutables. Una afirmación como «utilice el módulo de validación existente para la entrada externa y añada la prueba de integración correspondiente para cada nueva ruta de API» es más útil porque puede observarse y verificarse. La orientación de Claude Code también enfatiza redactar concretamente las reglas específicas del proyecto, y revisar y organizar las instrucciones con regularidad a medida que crecen. code.claude.com↗

Las instrucciones deben ser un registro condensado de criterios de decisión, no un documento que dicte cada detalle de implementación. El conocimiento extenso y propenso a cambiar —como el uso de una biblioteca concreta, los contratos de API o el orden de respuesta ante incidentes— es más fácil de mantener cuando se traslada a un documento apropiado en docs/, mientras que las instrucciones raíz indican su ubicación y condiciones de uso.

¿Cuándo se necesitan reglas para subdirectorios individuales?

Las reglas de subdirectorios no son archivos que deban añadirse mecánicamente a cada carpeta. Cuando las reglas raíz compartidas son suficientes, los archivos separados pueden aumentar la sobrecarga de navegación y el potencial de conflictos. Es mejor reservarlos para límites que se apartan claramente de las reglas generales o donde los errores tengan consecuencias significativas.

Por ejemplo, src/payments/ puede documentar cómo deben expresarse los cálculos monetarios, cómo deben utilizarse los mocks de proveedores de pagos externos y qué comando específico de pruebas de integración debe ejecutarse. infra/ puede exigir un plan antes de los cambios, comprobaciones antes de aplicarlos y límites sobre qué archivos específicos de cada entorno pueden modificarse. generated/ puede indicar que se prohíben las ediciones directas e identificar la fuente y el comando de generación. El propósito de estas reglas no es hacer que la carpeta parezca especial, sino proporcionar con precisión las restricciones reales de esa área en el contexto de trabajo.

Para Codex, un AGENTS.md anidado se aplica por debajo de su directorio, y los archivos más profundos pueden proporcionar reglas más específicas. Claude Code también puede acumular varios archivos CLAUDE.md como contexto, por lo que es más seguro que los archivos anidados añadan condiciones concretas necesarias solo en esa área, en vez de hacer declaraciones ambiguas que anulen los archivos principales. openai.com↗code.claude.com↗

Por ejemplo, la raíz podría indicar: «Ejecute las pruebas del paquete que modificó», mientras que la carpeta de pagos indica: «Si cambia el contrato de pagos, ejecute tanto las pruebas unitarias como las de integración». En cambio, escribir «Las pruebas siempre deben ejecutarse» en la raíz y «No ejecute pruebas» en una subcarpeta deja sin saber qué regla seguir no solo a las herramientas, sino también a las personas.

¿Cómo se deben dividir las .claude/rules/ de Claude Code?

En Claude Code, puede colocar las reglas globales que siempre se necesitan en CLAUDE.md y dividir las reglas con temas distintos o comportamientos dependientes de la ruta en archivos pequeños dentro de .claude/rules/. Los archivos de reglas pueden organizarse recursivamente, y las condiciones de ruta pueden aplicar reglas solo a archivos o áreas concretas. code.claude.com↗

El criterio de división no es el número de archivos, sino la cohesión de las reglas que cambian juntas. Por ejemplo, los comandos de prueba y los principios para los datos de prueba pueden ir en testing.md; las excepciones para importaciones, nomenclatura y formateo pueden ir en code-style.md; y las restricciones relacionadas con secretos, solicitudes externas y permisos pueden ir en security.md. Cada archivo debe abordar un solo tema y su título debe dejar claro cuándo es necesario leerlo.

La ventaja de este enfoque es que no es necesario leer siempre por completo instrucciones innecesarias. Por ejemplo, si las reglas completas de migración de bases de datos permanecen mezcladas con trabajo que solo edita documentación, pueden ocultar las instrucciones clave. Sin embargo, dividir las reglas de forma demasiado granular dificulta encontrar sus ubicaciones. Un enfoque equilibrado consiste en presentar brevemente los principales grupos de reglas y sus propósitos en el CLAUDE.md raíz, mientras se conserva el contenido real en archivos específicos por tema.

Después de separar las reglas, evite copiar la misma obligación en varios archivos. Las copias se desactualizan fácilmente con el tiempo. Mantener los principios compartidos en un solo lugar y registrar solo las excepciones y condiciones adicionales en archivos específicos por ruta reduce los conflictos.

¿Cómo se debe especificar el estilo de código?

El «estilo de código amigable para IA» no significa una elección universal, como tabulaciones frente a espacios o programación funcional frente a orientada a objetos. El criterio más importante es si se pueden reproducir las convenciones locales del repositorio. Las revisiones y el mantenimiento son más fáciles cuando un módulo nuevo sigue los patrones de nomenclatura de archivos, estilo de exportación, orden de importaciones, rutas de manejo de errores y estructura de pruebas de los módulos existentes.

Cualquier elección del proyecto que difiera de las convenciones comunes del lenguaje merece especialmente documentarse. La documentación de Claude Code utiliza como ejemplos el estilo de código específico del proyecto, como los módulos ES o la desestructuración de importaciones con nombre. En otras palabras, en lugar de reescribir cada regla predeterminada de un lenguaje, es más eficiente describir «lo que nuestro proyecto hace de forma distinta al valor predeterminado». code.claude.com↗

La siguiente tabla proporciona criterios sencillos para decidir sobre la orientación de estilo.

Los formateadores, linters y comprobadores de tipos hacen que el estilo sea verificable mecánicamente, en lugar de imponerlo mediante prosa. Por ello, es mejor que las instrucciones especifiquen los comandos reales que se deben ejecutar y el manejo esperado de los fallos, en vez de decir «formatee las cosas correctamente». Las prácticas recomendadas de Claude Code también recomiendan instrucciones claras para el proyecto y flujos de desarrollo verificables. code.claude.com↗

¿Con qué estructura de directorios puede empezar?

Lo siguiente es un ejemplo que puede utilizar al considerar Codex y Claude Code en conjunto. No es un estándar obligatorio, sino un posible punto de partida que separa las instrucciones compartidas, la documentación detallada y las excepciones específicas por área.

repo/
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── ARCHITECTURE.md
├── docs/
│   ├── design-docs/
│   ├── product-specs/
│   ├── runbooks/
│   └── generated/
├── src/
│   ├── feature-a/
│   └── feature-b/
├── tests/
└── .claude/
    ├── rules/
    │   ├── testing.md
    │   ├── code-style.md
    │   └── security.md
    └── settings.json

Aquí, README.md puede contener la información que necesitan las personas para empezar a trabajar con el repositorio, ARCHITECTURE.md puede describir los principales límites y la estructura del sistema, y docs/ puede albergar conocimiento extenso y detallado de diseño, producto y operaciones. La disposición real de src/ y tests/ debe seguir principalmente la estructura existente del proyecto. .claude/rules/ es una ubicación para reglas de Claude Code específicas por tema o ruta. code.claude.com↗

Si le preocupa tener muchos archivos en la raíz, la cuestión clave no es el número de nombres de archivo, sino la separación de responsabilidades. Si un archivo asume a la vez la introducción al proyecto, el diseño del sistema, la respuesta operativa, las convenciones detalladas de API y las reglas de estilo, se vuelve difícil saber qué información es esencial para la tarea actual. En cambio, una guía raíz breve que apunta a los documentos detallados necesarios permite a los colaboradores profundizar solo lo necesario.

El mismo principio se aplica al colocar archivos de instrucciones en carpetas específicas por funcionalidad. No añada uno a menos que la funcionalidad tenga reglas dedicadas; añádalo solo cuando haya una razón clara, como el manejo de datos sensibles o un proceso de generación automatizado. La proliferación frecuente de archivos de reglas puede complicar la propia estructura en vez de explicarla.

¿Cómo puede reducir las reglas duplicadas al utilizar ambas herramientas?

Una opción es conservar las convenciones de desarrollo compartidas y canónicas en AGENTS.md, importarlo desde el CLAUDE.md raíz y añadir después solo el contenido que necesita Claude Code. Por ejemplo:

@AGENTS.md

## Solo para Claude Code
- Presente un plan antes de cambiar `src/payments/`.
- Siga las reglas específicas por ruta de `.claude/rules/`.

Esta configuración reduce la necesidad de mantener repetidamente en ambos archivos los comandos de prueba, las reglas de nomenclatura comunes y los principios sobre archivos generados. Al mismo tiempo, conserva las reglas específicas de Claude Code y una configuración basada en .claude/rules/. Sin embargo, como se indicó antes, Claude Code no lee automáticamente AGENTS.md como instrucciones compartidas, por lo que debe configurar realmente una importación o conexión equivalente. code.claude.com↗

La ubicación del archivo compartido puede depender del uso relativo que haga el equipo de las herramientas y de las convenciones existentes del repositorio. Si Codex se utiliza con mayor frecuencia, AGENTS.md es una fuente canónica sencilla; si las operaciones se centran en el sistema de reglas de Claude Code, CLAUDE.md puede ser la fuente canónica en su lugar. Independientemente de la elección, la clave es designar un original autoritativo para cada regla y dejar solo referencias o adiciones específicas de la herramienta en el otro archivo.

Es mejor separar las preferencias individuales de las convenciones del equipo. Los alias de comandos en un entorno personal, las elecciones de herramientas locales y los hábitos personales de trabajo pueden pertenecer a archivos de anulación personales. En cambio, los procedimientos de prueba, las restricciones de seguridad y la estructura de código que debe conocer cualquier persona que clone el repositorio deben permanecer en las instrucciones del proyecto bajo control de versiones. Tanto Codex como Claude Code admiten configuraciones de instrucciones a nivel de proyecto y a nivel personal. openai.com↗code.claude.com↗

¿Por qué los comandos de validación deben ser centrales en las instrucciones?

Las propuestas o cambios de un agente de programación pueden parecer plausibles, pero no garantizan automáticamente la corrección, la compatibilidad ni la seguridad. La orientación relacionada con Codex también explica que sigue siendo necesaria la revisión humana y la validación de los resultados. openai.com↗

Por esa razón, las buenas instrucciones de repositorio explican no solo «cómo programar», sino también «cómo comprobar». Cuando sea posible, enumere los comandos de formateo, linting, comprobación de tipos, pruebas unitarias, pruebas de integración y compilación en formas que realmente puedan ejecutarse. Para repositorios grandes en los que exigir una validación completa para cada tarea no es práctico, puede distinguir la validación mínima por ubicación del cambio de las condiciones que requieren validación completa.

Por ejemplo, las actualizaciones de documentación pueden requerir solo comprobación de enlaces o una compilación de documentación, mientras que los cambios en un contrato de API público pueden requerir tanto pruebas unitarias como de integración. Los cambios difíciles de revertir, como los esquemas de bases de datos o la configuración de infraestructura, pueden requerir una fase adicional de revisión. Lo importante no es esperar que la herramienta evalúe el riesgo de forma mágica, sino registrar explícitamente en el repositorio las rutas de validación que el equipo ya conoce.

El código generado y los artefactos de compilación también deben distinguirse claramente desde la perspectiva de la validación. Si los archivos no deben editarse directamente, documente la ubicación de su fuente y el procedimiento de generación; si se permite editar un artefacto, indique qué comando lo actualiza. También es más seguro dejar claro el principio de que los secretos y las configuraciones personales específicas del entorno no pertenecen al repositorio, la ubicación de los archivos de ejemplo y los pasos de validación necesarios.

¿Cuáles son las ideas equivocadas y los patrones de fallo más comunes?

La primera idea equivocada es que «más instrucciones producen mejor cumplimiento». En la práctica, los documentos extensos pueden ocultar las reglas más importantes. Si las instrucciones han crecido demasiado, elimine las explicaciones duplicadas, las reglas que ya están automatizadas y las excepciones que ya no son válidas, y traslade el conocimiento detallado a documentos separados. code.claude.com↗openai.com↗

La segunda es que «cada carpeta necesita un archivo de instrucciones». Las instrucciones anidadas son útiles solo cuando existen restricciones especiales. Un archivo anidado sin especificidad simplemente añade otro archivo que leer y puede hacer poco clara su relación con las reglas principales.

La tercera es que «basta con cumplir las reglas de estilo». Incluso si el formateo es coherente, un cambio no es necesariamente bueno si no se ejecutaron pruebas, se infringieron reglas de dominio o se editaron directamente archivos generados. La automatización de estilo, y los procedimientos de pruebas y revisión, no son sustitutos: son salvaguardas que trabajan juntas.

La cuarta es que «la herramienta resolverá por sí sola las contradicciones en la documentación». Cuando las instrucciones de nivel principal y secundario, o las instrucciones compartidas y específicas de la herramienta, entran en conflicto, el resultado se vuelve difícil de predecir. Mantenga la misma regla en un solo lugar y haga claros el alcance y las condiciones adicionales de las reglas secundarias. Dado que la configuración de memoria de Claude Code también gestiona instrucciones jerárquicas, es importante diseñar reglas que eviten conflictos. code.claude.com↗

Por último, evite tratar un archivo de instrucciones como una garantía de calidad. Las instrucciones proporcionan contexto que respalda el juicio de agentes y personas; no son mecanismos que garanticen la corrección, la seguridad o que el código generado supere las pruebas. Revisar los cambios y realizar la validación necesaria sigue siendo esencial. openai.com↗

¿Qué deberíamos aplicar primero en nuestro repositorio?

No necesita rediseñar toda la estructura de carpetas desde el principio. Es más realista comenzar con pequeñas mejoras basadas en confusiones recurrentes en el repositorio actual. Por ejemplo, si los nuevos colaboradores no pueden encontrar el comando de prueba, añádalo a las instrucciones raíz. Si los mismos errores se producen repetidamente en el módulo de pagos, añada reglas específicas solo para esa ruta. Si los documentos de diseño están mezclados con código y es difícil navegar por ellos, primero distinga los tipos de documentos dentro de docs/.

Puede utilizar una secuencia de evaluación como esta:

1. Identifique las convenciones de ubicación de archivos, nomenclatura y pruebas que realmente se repiten en el código base actual.
2. Organice los comandos y las condiciones de fallo de los formateadores, linters, comprobaciones de tipos y pruebas.
3. Identifique las restricciones de dominio, las áreas que no deben editarse y los procedimientos de generación que son difíciles de comprender únicamente a partir del código.
4. Escriba de forma concisa solo el contenido más importante en el AGENTS.md o CLAUDE.md raíz.
5. Añada instrucciones anidadas o reglas específicas por ruta solo en áreas sensibles que las reglas generales no puedan explicar.
6. Designe una fuente original para las reglas compartidas y deje solo referencias y reglas específicas de cada herramienta en los archivos de la otra herramienta.
7. Revise periódicamente si las instrucciones resultaron útiles en el trabajo real y si contienen afirmaciones innecesarias o contradictorias.

En este proceso, no tiene que tratar «fácil de entender para las herramientas» y «fácil de mantener para las personas» como objetivos opuestos. La documentación breve y precisa, los límites de módulos predecibles y la validación ejecutable automáticamente ayudan a ambos. Por el contrario, intentar compensar mediante archivos de instrucciones una estructura difícil de explicar incluso para las personas probablemente hará que la documentación sea inmanejable.

Conclusión: ¿qué convenciones debería elegir?

La clave de las convenciones de directorios y los estilos de código adecuados para Codex y Claude Code no es adoptar una estructura particular de moda. Un enfoque práctico es mantener de manera coherente las convenciones del código base existente, conservar una guía breve en la raíz, separar el conocimiento detallado en documentos apropiados y añadir reglas de alcance limitado solo donde sean necesarias.

Para Codex, puede utilizar AGENTS.md; para Claude Code, CLAUDE.md y, cuando sea necesario, .claude/rules/. Si utiliza ambas herramientas, designe una única fuente para las reglas compartidas y conecte explícitamente el archivo compartido en Claude Code para reducir la duplicación. Sobre todo, combine las instrucciones con formateadores, linters, comprobaciones de tipos, pruebas y revisión humana. Dado que la interpretación de instrucciones específicas del producto puede cambiar según la versión, es recomendable mantener las reglas pequeñas y claras mientras consulta la documentación oficial de las herramientas que realmente utiliza. openai.com↗code.claude.com↗