Registra el dialecto local para que el código de IA se integre
¿Código de IA que se nota generado por IA? Te saltaste el paso de las convenciones. Cuando te incorporas a un repo, mapeas el stack y sigues una request real de punta a punta — pero lo que hace que el código nuevo se integre es el dialecto local: los nombres, patrones y reglas de la casa que tu codebase sigue y que ningún default genérico de un modelo seguirá jamás.
Por qué el dialecto importa más que el mapa
Un agente de código que conoce tu stack igual escribe en su estilo: su forma favorita de manejar errores, sus nombres por defecto, su idea de una línea de log. Cada uno de esos defaults que difiere de tu repo es un comentario de review esperando a ocurrir. PEP 8 lo dice sin rodeos: "Consistency within a project is more important" que la consistencia con cualquier guía externa — y la consistencia dentro de un módulo es la que más importa. Tus revisores lo sienten por instinto; por eso el código de IA "huele" a IA aunque funcione.
La solución son 15 minutos de registro, una sola vez por repo.
La checklist de 3 puntos del dialecto
Registra estas tres cosas en un archivo que el agente lea en cada sesión:
| # | Qué registrar | Dónde encontrarlo | Ejemplo de entrada |
|---|---|---|---|
| 1 | Nombres | Revisa 3–5 módulos centrales | "snake_case para funciones, PascalCase para clases, helpers _private" |
| 2 | Patrones | Una request real, de punta a punta | "Errores: lanzar subclases de AppError, nunca devolver códigos de error; log con structlog, un evento por línea" |
| 3 | Reglas de la casa | CONTRIBUTING, config del linter, .editorconfig | "Línea máx. 100 (anula el 88 de Black); sin barrel imports; los tests reflejan el layout de src/" |
El punto 3 es el que casi todos omiten. Las reglas de la casa son exactamente donde tu repo se desvía de los defaults del lenguaje — GitHub muestra el archivo CONTRIBUTING (raíz, docs/ o .github/) a cada contribuidor por esa razón, y el bloque rules de tu configuración de ESLint o tu .editorconfig es la mitad legible por máquina del mismo contrato. Esas desviaciones son invisibles para un modelo que solo vio defaults del lenguaje en su entrenamiento, así que escríbelas de forma explícita.
Dónde poner el registro
Pon la checklist donde tu agente la cargue automáticamente. En Claude Code eso es CLAUDE.md en la raíz del proyecto — se lee al inicio de cada sesión y está documentado como el lugar para "coding standards, workflows, project architecture". Otros agentes leen AGENTS.md o su equivalente; el principio es idéntico: las convenciones van en contexto persistente, no en un prompt que reescribes cada vez.
- Concreto le gana a vago. "Usa indentación de 2 espacios" funciona; "formatea bien el código" no. Escribe cada convención de modo que un revisor pueda verificarla mecánicamente.
- Registra las desviaciones, no los defaults. "Usamos snake_case en Python" desperdicia tokens — el modelo ya lo asume. "Usamos líneas de 100 caracteres, no 88" sí se gana su lugar.
Trucos de usuario avanzado
- Sigue una request real y cítala. No describas tu estilo de manejo de errores — pega un extracto de 10 líneas de un handler real en el archivo de convenciones como ejemplo canónico. Los modelos imitan ejemplos con más fiabilidad de la que siguen descripciones.
- Acota convenciones por rutas. Claude Code soporta reglas por ruta en
.claude/rules/con un globpaths:en el frontmatter, así tus reglas de nombres del frontend solo se cargan cuando el agente tocasrc/**/*.tsx. Los monorepos grandes con dos dialectos lo necesitan. - Apunta a la config del linter en vez de copiarla. Una línea como "las reglas de lint viven en
eslint.config.js; corre el linter antes de proponer código" sigue siendo cierta cuando la config cambia. Copia solo las 2–3 reglas que más sorprenden a los recién llegados. - Actualiza con la fricción del review. Cada vez que un revisor humano marca código de IA por estilo, esa es una entrada faltante de la checklist. Agrégala el mismo día — la heurística de la propia documentación es "Claude comete el mismo error una segunda vez".
- Roba estructura de guías de estilo publicadas. Las guías de estilo de Google muestran qué cubre un documento de convenciones completo por lenguaje; tú necesitas una fracción de eso, pero sus encabezados son una buena lista de escaneo de los temas donde tu repo podría tener opiniones.
Recursos
- PEP 8 — "Consistency within a project is more important"
- Setting guidelines for repository contributors (archivos CONTRIBUTING) — GitHub Docs
- Archivos de configuración de ESLint — donde viven las reglas de la casa
- EditorConfig — estilo legible por máquina entre editores
- How Claude remembers your project — CLAUDE.md y reglas por ruta
- Guías de estilo de Google — qué cubre un documento de convenciones completo
¿Construyendo una funcionalidad con IA? Yeda AI diseña, audita y entrega sistemas LLM de producción.