Reglas de Claude Code para IA: instrucciones globales en CLAUDE.md

Claude Code empezó a rendirme mucho mejor cuando dejé de explicarle lo mismo en cada conversación. Llevo cerca de dos años programando con IA, uso Claude Code desde hace unos seis meses y la mejora más útil fue ridículamente simple: poner mis reglas por defecto en ~/.claude/CLAUDE.md y hacer que el agente arranque desde ahí.

Antes de eso, desperdiciaba mensajes siempre en lo mismo. Usa tipado estricto. No añadas planes B que no te pedí. Mantén los cambios acotados. No reescribas medio archivo solo porque te has venido arriba. Claude solía hacerme caso. Aun así, yo tenía que pagar ese peaje una y otra vez.

Ahora esa base ya está ahí, incluso antes de que el repositorio entre en escena.

Dónde guardo mis instrucciones globales de Claude Code

La documentación de Claude Code de Anthropic divide esto en varias capas. ~/.claude/CLAUDE.md es el archivo global del usuario. ./CLAUDE.md o ./.claude/CLAUDE.md es la capa compartida del proyecto. CLAUDE.local.md sirve para notas personales del proyecto que no deberían acabar en git.

Eso coincide casi exactamente con lo que yo quiero:

1. ~/.claude/CLAUDE.md para mis preferencias persistentes de desarrollo
2. CLAUDE.md del proyecto para arquitectura y comandos específicos del repositorio
3. CLAUDE.local.md cuando necesito notas personales del proyecto que deben quedarse fuera de git

No quiero copiar las mismas reglas personales en cada repositorio que abro. Si "nada de planes B silenciosos" es una preferencia global, debe ir en el archivo global. Si "ejecuta este extraño comando interno antes de lanzar las pruebas" es algo específico del repositorio, debe ir en el archivo del proyecto.

Esta es la versión que estoy usando ahora mismo en Claude Code:

Las reglas de Claude Code que realmente uso

Este bloque es deliberadamente aburrido. Las buenas reglas suelen serlo. No intento anticipar todos los casos límite. Solo quiero que Claude Code deje de cometer los mismos errores previsibles.

Lo mantengo en inglés porque es el contenido literal de mi ~/.claude/CLAUDE.md y está pensado para copiarse tal cual. Aun así, la estructura es simple: estilo de código, manejo de errores, particularidades del lenguaje, dependencias, pruebas, terminal, flujo de trabajo y documentación.

# Global Rules

## Code Style

- Comments in English only
- Prefer functional programming over OOP
- Use OOP classes only for connectors and interfaces to external systems
- Write pure functions - only modify return values, never input parameters or global state
- Follow DRY, KISS, and YAGNI principles
- Prefer simple, native, vendor-recommended solutions and avoid premature abstractions
- Use strict typing for returns, variables, collections, and complex data; validate external/API data at runtime; require needed fields, ignore unrelated extra fields, prefer structured models over loose dictionaries, and avoid weak generic types like `Any`, `unknown`, or `List[Dict[str, Any]]`
- Check if logic already exists before writing new code
- Never use default parameter values - make all parameters explicit
- Write simple single-purpose functions - no multi-mode behavior, no flag parameters that switch logic. If the user needs multiple modes, they will ask explicitly

## Error Handling

- Always raise errors explicitly, never silently ignore them
- Use specific error types that clearly indicate what went wrong
- Avoid catch-all exception handlers that hide the root cause
- No fallbacks, symptom-masking guards, or silent recovery unless I explicitly ask for them; fix root causes and make code either succeed or fail with a clear error
- External API or service calls: use retries with warnings, then raise the last error
- Error messages must be clear, actionable, and specific: explain what failed and why, include request params, response body, status codes, and avoid generic "something went wrong"
- Logging should use structured fields instead of interpolating dynamic values into message strings

## Libraries and Dependencies

- Use modern stable, project-compatible package management, libraries, and language standards; prefer vendor-recommended patterns such as ESM when supported
- Install dependencies in project environments, not globally
- Add or update dependencies in project config files, not as one-off manual installs
- If a dependency is installed locally, read its source code when needed instead of guessing, even if it is gitignored

## Testing

- Respect the repository test strategy and add only the minimum useful tests for the requested change
- Prefer smoke, integration, and end-to-end tests over narrow unit or regression tests; do not test static text, prompts, or config unless behavior depends on them
- Do not create fake/mock-based tests by default; use real integrations when practical, even if they cost a little money
- UI tests and automations must use stable IDs, test IDs, or accessibility IDs instead of visible text, and fail fast without fallback clicks

## Terminal Usage

- Prefer non-interactive commands with flags over interactive ones
- Always use non-interactive git diff: `git --no-pager diff` or `git diff | cat`

## Workflow

- Read the existing code and relevant project instructions before editing
- Keep changes minimal and tightly scoped to the current request: make the smallest useful diff, change only the lines needed to solve the problem, and avoid unrelated improvements unless the user asks for them
- Match the existing style of the repository even if it differs from my personal preference; new code must look like it was written by the same author
- Keep files small and cohesive; split by feature or responsibility when the project has no established structure
- Do not revert unrelated changes
- If you are unsure, inspect the codebase instead of inventing patterns
- When project instructions include test or lint commands, run them before finishing if the task changed code

## Documentation

- Code is the primary documentation - use clear naming, types, and docstrings
- Keep documentation in docstrings of the functions, classes, or modules they describe, not in separate files
- Separate docs files only when a concept cannot be expressed clearly in code, and only one file per topic
- Never duplicate documentation across files; reference other sources instead
- Store knowledge as current state, not as a changelog of modifications

## Commits

- Never create a git commit unless the user explicitly asks for one
- Prefer `git merge` over `git squash` whenever possible, unless the user explicitly asks for squash.
- Uncommitted changes are the user's review state - they read the diff before deciding what to commit
- Keep changes uncommitted until asked, so the diff stays clean and reviewable

Ese bloque cubre casi todo lo que me importa en el día a día.

Sin él, Claude se descarrila de maneras muy reconocibles. Añade un plan B "por si acaso". Relaja los tipos porque el tipado estricto le resulta incómodo. Mete capas innecesarias alrededor de funciones sencillas. Corrige el problema equivocado porque intenta agradar en vez de ser preciso.

Prefiero dedicar diez minutos una vez a escribir un buen archivo global que seguir corrigiendo esos patrones uno por uno en cada sesión nueva.

Primero el CLAUDE.md global, después el CLAUDE.md del proyecto

No quiero un único CLAUDE.md gigantesco con todo embutido.

Mi archivo global debería responder a preguntas como:

• ¿Qué tan estricto quiero el tipado?
• ¿Cómo quiero que se manejen los errores?
• ¿Quiero cambios pequeños o refactorizaciones amplias?
• ¿Qué tipo de documentación espero?

Mi archivo del proyecto debería responder a preguntas distintas:

• ¿Cómo ejecuto el proyecto?
• ¿Qué comandos son seguros y esperados?
• ¿Cuáles son los límites importantes de la arquitectura?
• ¿Dónde están las pruebas?
• ¿Qué convenciones solo aplican a este repositorio?

En la práctica:

• el CLAUDE.md global dice cómo trabajo yo
• el CLAUDE.md del proyecto dice cómo funciona este repositorio

Cuando mezclas esas dos cosas, el archivo se convierte en un batiburrillo. La mitad es demasiado genérica, la otra mitad demasiado local, y Claude tiene que cargar con todo eso en cada tarea.

Anthropic recomienda mantener estos archivos concisos. Bien. Los archivos de instrucciones largos suelen parecer un intento de meter un manual entero de ingeniería dentro de las instrucciones. Eso nunca acaba bien.

Qué se rompe a mitad de sesión

Las reglas ayudan. No arreglan para siempre una sesión caótica.

Si paso veinte mensajes hablando de un subsistema y luego cambio de golpe a otro problema distinto, Claude puede quedarse atascado en el contexto anterior. Es normal. No trato las conversaciones largas como si fueran sagradas.

Así que en la práctica hago esto:

• Empiezo una sesión nueva cuando la tarea pasa de exploración a implementación
• Empiezo una sesión nueva cuando salto de un subsistema a otro muy distinto
• Mantengo las instrucciones del proyecto lo bastante concisas para no pagar un peaje de contexto en cada turno

Por eso también me gustan los archivos Markdown para planes y notas. Si la tarea es grande, prefiero dejar el estado por escrito antes que confiar en que un hilo larguísimo se mantenga limpio.

Mi despliegue práctico de reglas para Claude Code

Si hoy tuviera que configurar esto desde cero, lo haría en este orden.

1. Crear ~/.claude/CLAUDE.md

Empieza por tus líneas rojas. No consejos de vida. No manifiestos sobre ingeniería. Solo las reglas que de verdad importan una y otra vez entre repositorios.

Para mí, eso significa:

• tipado estricto
• manejo explícito de errores
• ediciones mínimas
• sin planes B silenciosos
• docstrings donde la documentación debe vivir
• hábitos de terminal no interactivos

Solo con eso ya cambia más el resultado que la mayoría de los retoques en las instrucciones.

2. Añadir un CLAUDE.md de proyecto

Usa el archivo del repositorio para comandos, arquitectura, convenciones de nombres y límites. Anthropic te da /init para esbozar uno, y eso ayuda. Aun así, yo lo edito a mano después porque las instrucciones generadas son un borrador, no una pieza terminada.

3. Mantener cortas las reglas del proyecto

No conviertas el archivo del proyecto en una segunda copia del personal. Pon ahí comandos específicos del repositorio, notas de arquitectura y convenciones locales. Deja las preferencias duraderas en el archivo global.

Por qué esto importa más que ponerse ingenioso con las instrucciones

Mucho contenido sobre la "configuración definitiva" de agentes de código acaba convirtiéndose bastante rápido en puro teatro.

Lo que de verdad mejoró mi trabajo del día a día fue mucho más simple:

• un CLAUDE.md global y estable en mi cuenta
• un CLAUDE.md de proyecto claro

Esa combinación hace que Claude trabaje con más aplomo. Menos planes B metidos porque sí. Menos abstracciones ingeniosas porque sí. Menos sesiones en las que, diez minutos después, descubro que el agente y yo estábamos resolviendo problemas ligeramente distintos.

Si usas varios agentes de código, el mismo patrón aparece también en otras herramientas. Distinto producto, misma lección: define la base una vez y deja de renegociarla cada mañana.

Si te interesan los artículos complementarios, aquí los tienes:

• Reglas de Cursor IDE para IA: https://kirill-markin.com/es/articulos/reglas-cursor-ide-para-ia/
• Reglas de Codex para IA: https://kirill-markin.com/es/articulos/reglas-codex-para-ia/