/doctor prompt-audit de Claude Code es un comando que pide a Claude que lea tus archivos de instrucciones (CLAUDE.md, AGENTS.md, skills, comandos, etc.), busque las instrucciones que se han quedado obsoletas o que se contradicen entre sí y proponga cómo corregirlas. Lo único que recibes es un informe y unos diffs propuestos: tus archivos no cambian ni un carácter hasta que le pidas a Claude que aplique algo. Escribir /checkup prompt-audit ejecuta exactamente la misma revisión.
En este artículo explicamos qué revisa la auditoría de prompts, cómo ejecutarla y qué hacer con los resultados, a partir del texto original de la documentación oficial de Claude Code (la sección "Audit your instruction files" de How Claude remembers your project, además de Commands y Skills), del CHANGELOG y de la guía de auditoría que viene incluida en Claude Code. Todo lo relativo a la especificación se comprobó en esos originales a 3 de octubre de 2026. Las secciones 7 y 8 cuentan además qué pasó cuando la ejecutamos sobre los archivos de instrucciones de este sitio (9 hallazgos, 7 aplicados) y las precauciones que descubrimos por el camino.
La respuesta corta: /doctor prompt-audit de un vistazo
Fuente: documentación de Claude Code, "How Claude remembers your project" y "Commands" (consultada el 3 de octubre de 2026)
QUÉ HACE
Audita tus archivos de instrucciones
Busca redacciones pensadas para modelos antiguos, referencias a archivos o comandos que ya no existen e instrucciones contradictorias.
RESULTADO
Un informe y diffs propuestos
No cambia nada hasta que lo pidas. Tú decides, hallazgo por hallazgo, qué aplicar.
ALCANCE
CLAUDE.md, skills y más
También AGENTS.md, reglas, comandos y subagentes. Pasa una ruta para auditar un solo sitio.
VERSIÓN
v2.1.283 o posterior
Se ejecuta dentro de una sesión. No es lo mismo que claude doctor en la terminal.
Índice
- 1. ¿Qué es /doctor prompt-audit? Una auditoría de instrucciones obsoletas y contradictorias
- 2. Cómo usarlo: basta con escribirlo, y el alcance se acota con una ruta
- 3. Qué considera "obsoleto" la auditoría
- 4. Lo que no borra: no es una auditoría para "acortar"
- 5. Cómo leer los resultados: el informe y los diffs propuestos
- 6. En qué se diferencia de /doctor, /claude-api prompt-audit y claude doctor
- 7. Lo probamos: auditoría del CLAUDE.md y el AGENTS.md de este sitio
- 8. Inconvenientes y precauciones
- 9. Cuándo ejecutar una auditoría de prompts
- Preguntas frecuentes
1. ¿Qué es /doctor prompt-audit? Una auditoría de instrucciones obsoletas y contradictorias
Claude Code carga CLAUDE.md y tus demás archivos de instrucciones cada vez que arranca. Esos archivos crecen con el uso y van acumulando redacciones enfáticas escritas para modelos antiguos, nombres de archivos y comandos que ya no existen y reglas que contradicen a otro archivo. /doctor prompt-audit es el comando que pone a Claude a buscar justamente eso.
En resumen, según la documentación oficial:
- Qué busca: instrucciones escritas para modelos antiguos, referencias a archivos o comandos que no existen y archivos que se contradicen entre sí.
- Qué devuelve: un informe de los problemas encontrados y las correcciones propuestas en forma de diffs. Tus archivos no cambian hasta que le pidas a Claude que las aplique.
- Cómo funciona: a través de la skill
/claude-apique viene incluida en Claude Code. Si has desactivado esa skill en tu configuración (conskillOverrideso activandodisableBundledSkills), la auditoría no está disponible. - Versión: Claude Code v2.1.283 o posterior.
/checkup prompt-audites el mismo comando.
La entrada de v2.1.283 del CHANGELOG añade /doctor prompt-audit (y /checkup prompt-audit) para auditar CLAUDE.md, skills, agentes y comandos en busca de patrones de prompting escritos para modelos antiguos. En esa misma versión, la auditoría pasó también a poner al principio del informe las rutas obsoletas, los comandos obsoletos y los archivos de instrucciones en conflicto, y a conservar las palabras clave de profundidad de razonamiento, como "think", que Claude Code admite oficialmente.
¿Por qué importan las instrucciones obsoletas? La guía de auditoría incluida lo explica así: los modelos actuales siguen las instrucciones con más precisión y más al pie de la letra que los anteriores. Los "CRITICAL" y "MUST" acumulados para que los modelos antiguos no pasaran por alto una regla ahora pesan demasiado: la regla se aplica donde no hace falta y el modelo se vuelve rígido. La guía deja claro que el objetivo no es acortar las instrucciones, sino encontrar las que ya no encajan con el modelo actual, con el proyecto actual o con tus otras instrucciones.
2. Cómo usarlo: basta con escribirlo, y el alcance se acota con una ruta
Dentro de una sesión de Claude Code, basta con escribir:
/doctor prompt-auditSin argumentos, según la documentación oficial, audita estos archivos:
| Tipo | Qué incluye |
|---|---|
| Archivos de instrucciones | CLAUDE.md, CLAUDE.local.md, AGENTS.md |
Dentro de .claude/ y ~/.claude/ | Reglas, skills, comandos, subagentes, estilos de salida (output styles) |
Para auditar un solo archivo o carpeta, pasa una ruta. El ejemplo de la documentación oficial:
/doctor prompt-audit .claude/skills/deploySegún la guía incluida, la auditoría está pensada para llegar hasta el final sin pararse a hacer preguntas. Deduce el alcance y el modelo de referencia a partir de tu petición y de los propios archivos, y deja esas suposiciones por escrito al principio del informe. Si alguna es errónea, vuelve a ejecutarla con una ruta más acotada. Para los archivos de instrucciones, la referencia suele ser el modelo que ejecuta la auditoría (o, si una skill o un subagente fija su propio modelo, ese modelo).
La guía también indica que la auditoría no lee los archivos de configuración de Claude Code (.claude/settings*.json) ni la configuración de MCP (.mcp.json), porque pueden contener secretos. Los problemas de permisos o de hooks quedan fuera de esta auditoría; de eso se encarga el /doctor a secas (véase la sección 6).
3. Qué considera "obsoleto" la auditoría
Lo que revisa la auditoría está escrito en la guía incluida en Claude Code (las instrucciones de prompt-audit dentro de la skill /claude-api). Al leer los archivos incluidos en v2.1.286, vimos que las comprobaciones se agrupan en cuatro bloques. Para los archivos de instrucciones, los dos primeros hacen casi todo el trabajo.
| Grupo | Comprobaciones principales | Ejemplos |
|---|---|---|
| 1. Estilo de prompting desfasado | Redacción demasiado enfática, instrucciones de razonamiento que ya no hacen falta, pasos sobreespecificados, parches que quedaron de fallos de modelos antiguos | "CRITICAL: you MUST..." una y otra vez, "Piensa paso a paso", "PASO 1... PASO 2..." encorsetando un trabajo que requiere criterio |
| 2. Archivos de configuración frágiles | Rutas y comandos que no existen, archivos que se contradicen, historiales de incidentes escritos en el archivo, tropiezos puntuales convertidos en reglas permanentes, condiciones atadas a una fecha | El nombre de un script borrado, reglas opuestas en dos archivos, "Como esto falló el [fecha]..." |
| 3. Descripciones de herramientas | Las descripciones que escribes al definir herramientas en la API (las demasiado cortas se señalan para que tengan más detalle) | Descripciones de una línea, "usa siempre esta herramienta" dentro de una descripción |
| 4. Parámetros de las llamadas a la API | Parámetros que ahora dan error o están en desuso con los modelos actuales, órdenes que rompen la caché, etc. | Solo si hay código de aplicación (no aplica a un proyecto que solo tiene archivos de instrucciones) |
Dentro del grupo 2, las "rutas y comandos que no existen" reciben un trato especialmente estricto en la guía. Comprueba si cada ruta de tus archivos de instrucciones existe de verdad en el proyecto y si los comandos y las opciones están definidos en tus scripts o en tu configuración, leyendo archivos en lugar de ejecutar comandos. Todo lo que contradiga lo que realmente hay en el proyecto se convierte en un hallazgo de confianza alta.
Cuando dos archivos chocan, la auditoría usa git blame (el registro de quién escribió cada línea y cuándo) para decidir cuál es más reciente, y propone alinear el más antiguo. Pero si uno de los dos es una prohibición o una regla de seguridad que la corrección relajaría, o si el historial no permite saber cuál es más reciente, la guía indica no proponer ninguna corrección y limitarse a señalarlo como una decisión que corresponde al usuario.
4. Lo que no borra: no es una auditoría para "acortar"
Lo que más nos gustó de esta auditoría es que la guía detalla qué no se debe borrar. Advierte de que una auditoría que lo recorta todo perjudica precisamente a quienes escribieron instrucciones con cuidado, y establece que lo siguiente debe quedarse aunque su redacción coincida con algún patrón:
- Contexto que solo conoce el autor: datos sobre el público, el producto y el entorno, niveles de calidad, restricciones y las razones que hay detrás. La guía afirma sin rodeos que el contexto nunca sobra.
- La longitud en sí: nada se recorta solo por ser largo. Lo que hace daño son las instrucciones obsoletas, no el volumen.
- Pasos exactos para operaciones delicadas: el trabajo que solo tiene un procedimiento seguro, como los comandos de borrado o los flujos de autenticación, puede seguir totalmente especificado.
- Prohibiciones contra fallos que siguen ocurriendo: si el fallo todavía se reproduce con los modelos actuales, la regla se queda.
- Duplicación que funciona: tener el mismo contenido en dos sitios es una cuestión de gusto organizativo, no algo que auditar, mientras las copias no se contradigan.
También funciona en sentido contrario. Si a los modelos actuales les vendría bien una instrucción adicional, la propone. Y dice que, cuando no aparece nada, no cambiar nada es el resultado correcto.
5. Cómo leer los resultados: el informe y los diffs propuestos
Recibes dos cosas: un informe de auditoría y correcciones propuestas en forma de diffs. Cada hallazgo del informe tiene seis campos:
| Campo | Contenido |
|---|---|
| Ubicación | Nombre del archivo y número de línea |
| Evidencia | El texto problemático, citado literalmente |
| Patrón | Con qué patrón de la sección 3 coincide |
| Por qué está obsoleto | Con qué choca: el comportamiento del modelo actual o algo que existe realmente en el proyecto |
| Confianza | Alta (contradice la documentación oficial o el propio proyecto), media (comportamiento observado de forma generalizada), baja (deducido de la redacción) |
| Acción | Borrar, reescribir (con el texto nuevo), mover (con el destino), añadir o solo señalar |
Solo los hallazgos de confianza alta y media entran en los diffs propuestos. Los de confianza baja aparecen únicamente en el informe. Los diffs se dividen en un fragmento (hunk) por hallazgo, así que puedes elegir solo los que quieras.
Para aplicarlos, pídele a Claude algo como "aplica el 1, el 3 y el 4". La guía también indica que los conflictos entre archivos y las reescrituras de texto que no coincide con el proyecto no se aplican ante una petición general del tipo "límpialo todo". Cualquiera con permiso de escritura en el repositorio podría haber cambiado el texto más reciente o el propio proyecto, así que el diseño da por hecho que una persona revisa cada uno.
6. En qué se diferencia de /doctor, /claude-api prompt-audit y claude doctor
Hay cuatro cosas con nombres parecidos. Comparando lo que dicen la documentación oficial (Commands y Skills) y el CHANGELOG:
| Comando | Qué hace | ¿Cambia archivos? | Versión |
|---|---|---|---|
/doctor prompt-audit | Audita los archivos de instrucciones (CLAUDE.md, skills, etc.) en busca de instrucciones obsoletas y contradictorias | Solo informe y propuestas (las aplica si se lo pides) | v2.1.283 o posterior |
/doctor (alias /checkup) | Un chequeo de salud de tu entorno (instalaciones duplicadas, PATH, configuraciones rotas, skills y servidores MCP sin usar, hooks lentos, actualizaciones disponibles), además de propuestas para recortar de CLAUDE.md lo que el código ya deja claro y para mover instrucciones que se cargan siempre a skills o a archivos CLAUDE.md anidados | Primero informa y corrige tras tu confirmación | (propuestas para recortar CLAUDE.md: v2.1.206 o posterior) |
/claude-api prompt-audit | Audita los prompts y las descripciones de herramientas de aplicaciones creadas sobre la API de Claude en busca de patrones escritos para modelos antiguos | Propone diffs | v2.1.221 o posterior |
claude doctor (terminal) | Muestra el estado de tu instalación sin iniciar una sesión | No (solo lectura) | — |
Lo confuso es que /doctor también se ocupa de CLAUDE.md. La diferencia está en el objetivo. /doctor busca reducir lo que se carga siempre (eliminar duplicados, quitar lo que el código ya le dice a Claude, mover cosas a lugares que solo se cargan cuando hacen falta). /doctor prompt-audit comprueba si el contenido se ha quedado obsoleto o se contradice. El claude doctor de la terminal no ejecuta ninguna auditoría de prompts.
Si Claude no sigue tus instrucciones porque ni siquiera se están cargando, esta auditoría no lo arreglará. Explicamos cómo comprobar qué se carga en "Por qué la IA ignora las reglas: revisa CLAUDE.md, Cursor Rules y AGENTS.md", y cómo medir cuánto de tu contexto ocupan los archivos de instrucciones en "¿Qué se está comiendo el contexto de Claude Code?".
7. Lo probamos: auditoría del CLAUDE.md y el AGENTS.md de este sitio
El 3 de octubre de 2026 ejecutamos /doctor prompt-audit sobre los archivos de instrucciones que usamos para desarrollar este sitio. Lo hicimos en la aplicación de escritorio de Claude Code (con Claude Code 2.1.286 incluido y Opus 5.5 como modelo). Nuestros archivos de instrucciones son AGENTS.md (las reglas principales, compartidas entre Claude Code y Codex) y CLAUDE.md (que lo importa y añade notas específicas de Claude Code), con unos 10.700 caracteres entre los dos. No tenemos reglas, skills ni comandos dentro de .claude/.
Resultados de una ejecución
Fuente: prueba propia (3 de octubre de 2026, /doctor prompt-audit sobre CLAUDE.md y AGENTS.md)
Hallazgos
9
Revisados y aplicados
7
Descartados (confianza baja)
2
La primera sorpresa fue que apenas encontró prompting escrito para modelos antiguos. No había ni un solo "piensa paso a paso" ni ningún guion por pasos. La mayoría de los hallazgos pertenecían al grupo 2 de la sección 3 (archivos de configuración frágiles).
| Confianza | Cantidad | Qué encontró | Qué hicimos |
|---|---|---|---|
| Alta | 1 | Ese mismo día habíamos añadido dos herramientas de auditoría, pero una nota entre paréntesis seguía diciendo "ambas" y ya no cuadraba con las descripciones de las dos herramientas nuevas | Aplicado (reescribimos la nota para tratar por separado las herramientas añadidas) |
| Media | 5 | Registros de incidentes con fechas y cifras que seguían en los archivos de instrucciones (en contra de una regla del mismo archivo: no acumular registros de incidentes en los archivos de entrada) | Aplicado (pero los trasladamos a un archivo de registros aparte en vez de borrarlos) |
| Media | 1 | Un "(CRITICAL)" en un encabezado sin ninguna razón que lo justificara | Aplicado (lo quitamos) |
| Baja | 2 | Una lista de comandos que no funcionan en local y un encabezado con una fecha | Descartado (los dos están ahí por un motivo, y la guía también trata los de confianza baja como "solo señalar") |
El único hallazgo de confianza alta era un desfase real. Al añadir las herramientas de auditoría, pusimos sus nombres en la lista pero olvidamos reescribir la explicación de al lado. Cada vez que se cargaba el archivo, Claude podía malinterpretar a qué se refería "ambas", y a simple vista no nos habíamos dado cuenta.
El informe dejaba constancia además de que había confirmado que todas las rutas, nombres de herramientas y notas referenciadas en los archivos de instrucciones existen de verdad. Incluso cotejó la versión de PHP (coincidía con la configuración de Docker) y el número de pasos de un procedimiento (coincidía con una lista de otro archivo).
No aceptamos los diffs propuestos por Claude tal cual; los aplicamos solo después de contrastar cada uno con los archivos originales. Los cinco hallazgos de confianza media fueron los que más criterio exigieron. La propuesta era borrar los registros de incidentes, pero esos registros son la prueba que evita que se repitan los mismos errores, así que los trasladamos en lugar de borrarlos. Cuando las fechas y las cifras ya figuraban en otro archivo, simplemente las quitamos de los archivos de instrucciones; las dos que no estaban registradas en ningún otro sitio las copiamos al archivo de registros. Al final, los archivos de instrucciones pasaron de unos 10.700 caracteres a solo unos 40 caracteres menos. El tamaño apenas cambió; solo desaparecieron las contradicciones.
Ten en cuenta que se trata de una ejecución sobre un proyecto. La auditoría la redacta el modelo, así que volver a ejecutarla sobre los mismos archivos puede dar otro número de hallazgos u otra redacción. Un proyecto con muchas skills y comandos dentro de .claude/ probablemente obtenga hallazgos bastante distintos.
8. Inconvenientes y precauciones
Tras usarla y leer la documentación oficial y la guía, estas son cinco cosas que conviene tener presentes:
- Consume tu cuota de uso: Claude lee y audita tus archivos de instrucciones dentro de la sesión, así que cuenta para tu uso como cualquier otro trabajo. La documentación oficial no menciona ninguna tarifa aparte.
- No apliques los hallazgos a ciegas: puede que Claude no sepa por qué se escribió una regla. En nuestro caso, aceptar tal cual la propuesta de "borrar los registros de incidentes" habría tirado a la basura la prueba que evita repetir errores.
- Los resultados varían de una ejecución a otra: la auditoría la redacta un modelo, así que el número y la redacción pueden cambiar cada vez. No tomes una ejecución limpia como prueba de que un archivo no tiene problemas.
- No mira los archivos de configuración: no lee
settings.jsonni.mcp.json, así que los problemas de permisos, hooks y MCP no aparecerán. Para eso, usa/doctor. - No garantiza que tu contenido sea correcto: detecta rutas que faltan y contradicciones, pero no juzga si tu política es la acertada. Esa decisión es tuya.
La propia guía trata los borrados como hipótesis, no como conclusiones. Una vez que quitas una instrucción, se espera que compruebes en el trabajo real que no se ha roto el comportamiento que esa instrucción garantizaba.
9. Cuándo ejecutar una auditoría de prompts
La guía describe los prompts como productos de un modelo concreto, en los que las líneas que necesitaba una generación se convierten en lastre en la siguiente, y recomienda volver a auditar cada vez que sale un modelo nuevo. A nuestro juicio, estas tres situaciones son buenos momentos:
- Cuando pasas a una generación de modelos más reciente: para revisar la redacción enfática y los parches que quedaron de modelos antiguos
- Tras reescribir a fondo tus archivos de instrucciones: como en nuestra prueba, las reglas nuevas y las explicaciones antiguas tienden a desalinearse
- Cuando compartes archivos de instrucciones entre herramientas como Claude Code y Codex: facilita detectar contradicciones entre AGENTS.md y CLAUDE.md
En cambio, si tus archivos de instrucciones son cortos y rara vez cambian, no hay prisa. La guía también dice que no encontrar nada es un resultado correcto.
Resumen
/doctor prompt-audit es un comando que busca en tus archivos de instrucciones (CLAUDE.md, AGENTS.md, skills y más) redacciones escritas para modelos antiguos, rutas y comandos que no existen y reglas en conflicto, y después devuelve un informe y unos diffs propuestos. Está disponible en Claude Code v2.1.283 y posteriores, y no cambia nada hasta que lo pidas.
La guía de auditoría protege el contexto, las razones y las prohibiciones contra fallos que siguen ocurriendo como cosas que no se deben borrar, para que no se convierta en una auditoría para "acortar". Cuando la ejecutamos sobre los archivos de instrucciones de este sitio, casi no había prompting desfasado, pero sí encontró una explicación que olvidamos reescribir tras añadir una regla, un desfase real.
Lo más seguro es contrastar cada hallazgo con el archivo original y mover, en vez de borrar, el texto que existe por algún motivo. Ejecutarla una vez tras cambiar de modelo o reescribir tus archivos de instrucciones puede descubrir contradicciones que se te escaparon a simple vista.
Preguntas frecuentes
P. ¿/doctor prompt-audit reescribirá mi CLAUDE.md por su cuenta?
R. No. La documentación oficial dice que devuelve un informe y correcciones propuestas, y que tus archivos no cambian hasta que le pidas a Claude que las aplique. Incluso entonces, puedes elegir propuesta por propuesta.
P. ¿Qué diferencia hay entre /doctor prompt-audit y /checkup prompt-audit?
R. Ninguna. /checkup es un alias de /doctor, y la entrada de v2.1.283 del CHANGELOG menciona /doctor prompt-audit junto con /checkup prompt-audit.
P. ¿También audita el AGENTS.md de Codex?
R. Sí. La documentación oficial incluye AGENTS.md, junto a CLAUDE.md y CLAUDE.local.md, entre los archivos que se auditan cuando no pasas ningún argumento. Si compartes los dos archivos, también es útil para encontrar contradicciones entre ellos.
P. Lo escribí, pero la auditoría no arranca.
R. Primero comprueba tu versión: /doctor prompt-audit necesita v2.1.283 o posterior. Si tu versión es suficientemente reciente y aun así no se ejecuta, revisa si has desactivado la skill incluida /claude-api en tu configuración (skillOverrides o disableBundledSkills). Ten en cuenta también que claude doctor escrito en la terminal solo diagnostica tu instalación y no ejecuta esta auditoría.
P. ¿Puede auditar el prompt de sistema de una aplicación que he creado sobre la API?
R. Sí, pero para eso usa /claude-api prompt-audit (v2.1.221 o posterior). Audita tus prompts, las descripciones de herramientas y el código que llama a la API en busca de patrones escritos para modelos antiguos, y propone diffs.
Fuentes
- Documentación de Claude Code: How Claude remembers your project (sección "Audit your instruction files")
- Documentación de Claude Code: Commands (las filas de
/doctory/claude-api) - Documentación de Claude Code: Skills (subcomandos de la skill incluida
/claude-apiy versiones necesarias) - Claude Code: CHANGELOG (v2.1.283)
- La guía de prompt-audit de la skill
/claude-apiincluida en Claude Code v2.1.286 (consultada en nuestro propio equipo)
Todas las fuentes se consultaron en el original el 3 de octubre de 2026. La guía incluida se actualiza con cada versión de Claude Code, así que lo que revisa la auditoría puede cambiar de una versión a otra.
