El archivo de instrucciones del proyecto que convierte un agente genérico en uno que conoce tus convenciones, tus comandos y tus trampas: qué incluir, qué dejar fuera y cómo mantenerlo vivo.
Cuándo usarlo: Redactar el archivo de instrucciones del proyecto para agentes de código, con comandos exactos, convenciones no evidentes y trampas documentadas
Herramienta recomendada: Claude Code
Actúa como ingeniero senior con experiencia en equipos que usan agentes de código a diario. Quiero escribir el archivo de instrucciones del proyecto (CLAUDE.md o el equivalente de mi herramienta) para que el agente deje de reinventar decisiones ya tomadas. ## Lo que voy a darte 1. Estructura del repositorio (salida de `tree -L 2` o similar). 2. Comandos reales de arranque, tests, lint y build. 3. Las tres correcciones que más veces he tenido que repetirle a un agente o a un compañero nuevo. 4. Stack, versiones y cualquier peculiaridad del entorno. ## Principios que quiero que respetes - **Solo lo que no se deduce del código.** Si el agente puede verlo leyendo dos ficheros, no va aquí. Las instrucciones que repiten lo obvio diluyen las que importan. - **Comandos exactos**, con las banderas reales, no descripciones («se ejecutan los tests»). - **Prohibiciones con motivo.** «No ejecutes X» sin explicar por qué se ignora en la tercera sesión. - **Corto y mantenido** antes que exhaustivo y desfasado. 40 líneas útiles valen más que 300 muertas. ## Estructura que quiero 1. **Qué es este proyecto** en tres líneas: qué hace, para quién, qué lo hace raro. 2. **Comandos**: arrancar, tests (todos y uno solo), lint, formato, build, tareas propias del proyecto. 3. **Convenciones no evidentes**: dónde vive cada tipo de código, cómo se nombran las cosas, qué patrón se sigue y cuál se está abandonando. 4. **Trampas conocidas**: cada una en una línea, con el síntoma y la regla. Esta es la sección con más valor por carácter escrito. 5. **Zonas prohibidas**: ficheros generados, directorios que no se tocan, comandos que no se lanzan y por qué. 6. **Definición de terminado**: qué debe pasar antes de considerar un cambio listo (tests, lint, tipos, documentación). ## Además - Señala qué instrucciones convendría mover a un skill o a un comando propio porque son procedimientos completos, no reglas. - Propón la rutina de mantenimiento: añadir una línea cada vez que haya que corregir lo mismo por segunda vez, y revisar el archivo cuando cambie el stack. - Advierte de las instrucciones que probablemente se ignoren por estar mal formuladas (vagas, contradictorias o negativas sin alternativa). ## Entregables 1. El archivo completo, listo para guardar en la raíz del repositorio. 2. Justificación de qué has dejado fuera y por qué. 3. Lista de las trampas que hay que documentar y que no me has visto contar (pregúntame por ellas si hace falta). 4. Rutina de mantenimiento en tres reglas.