El 2026-01-02 Boris Cherny, creador de Claude Code, publicó en X un hilo de trece puntos sobre cómo usa la herramienta, abriendo con la observación de que su configuración es sorprendentemente sencilla. Cuando lo leímos el 2026-11-08, la primera publicación mostraba unas 8,2 millones de visualizaciones y el punto 13 unas 575 mil. Diez meses son mucho tiempo para Claude Code: cambiaron el modelo por defecto, el modo de permisos por defecto, la forma de organizar los comandos de barra y la forma de pasar sesiones entre terminal y nube. Por eso este artículo no repite el hilo, sino que coloca cada punto junto a la documentación tal como se leía ese día.
Boris Cherny: inicio del hilo (2026-01-02) · Boris Cherny: punto 13, el bucle de verificación
La vara de medir viene de la página oficial de best practices: toda instrucción es no determinista (escrita para el modelo, que decide si la sigue: el prompt, CLAUDE.md, una skill) o determinista (ejecutada por Claude Code, el harness, decida lo que decida el modelo: un hook, una regla deny, un ajuste gestionado). Algunos hábitos del hilo pertenecen al primer tipo y otros al segundo, y su fiabilidad difiere por completo. La afirmación más fuerte del hilo es el punto 13: dé a Claude una forma de verificar su trabajo y el resultado final mejora dos o tres veces. La estructura del artículo sigue ese bucle.
Boris Cherny: punto 13, el bucle de verificación · Documentación de Claude Code: Best practices
Primero los límites. No ejecutamos Claude Code, no activamos estos hooks en ningún repositorio real y comprobamos los bloques JSON, Markdown y shell solo sin conexión. Donde el hilo nombra un modelo, un comando o un plugin que la documentación actual ya no refleja, el texto lo indica (según describe el hilo) y remite a la página vigente. Las visualizaciones y los números de versión son lecturas del 2026-11-08 y pueden no mantenerse después.
1. Qué dice el hilo y qué comprobamos
Los trece puntos forman cuatro grupos. Orquestación de sesiones: cinco instancias locales de Claude en pestañas numeradas del terminal con notificaciones del sistema cuando una necesita entrada (punto 1); otras cinco a diez sesiones en claude.ai/code, con sesiones locales pasadas a la web mediante un ampersand y a veces recuperadas con --teleport (punto 2); Opus 4.5 con thinking para todo, más grande y lento que Sonnet pero con menos necesidad de corrección (punto 3). Captura de conocimiento: un único CLAUDE.md para el repositorio de Claude Code, versionado en git y editado por todo el equipo varias veces por semana, con una nota cada vez que Claude se equivoca (punto 4); mencionar a Claude en los PR de colegas para que la GitHub Action añada la lección a CLAUDE.md dentro del mismo PR, lo que el autor llama compounding engineering siguiendo a Dan Shipper (punto 5).
Proceso y permisos: la mayoría de sesiones empiezan en plan mode, se itera el plan y luego se pasa a aceptar ediciones automáticamente (punto 6); un comando de barra por cada flujo frecuente del bucle interno, versionado en .claude/commands/ (punto 7); unos pocos subagentes, code-simplifier para limpiar después de que Claude termina y verify-app con las instrucciones de prueba de extremo a extremo (punto 8); un hook PostToolUse que formatea el código y atrapa el diez por ciento aproximado que el modelo omite para que CI siga en verde (punto 9); nada de --dangerously-skip-permissions, sino /permissions para preaprobar comandos seguros guardados en un .claude/settings.json compartido (punto 10); Slack por MCP desde un .mcp.json compartido, BigQuery con la CLI bq, registros de Sentry (punto 11).
Y verificación: en tareas largas, pedir a Claude que verifique con un agente en segundo plano al terminar, usar un Stop hook para hacerlo de forma más determinista, o usar el plugin ralph-wiggum (punto 12); y el consejo final de que la verificación es probablemente lo más importante, con Claude probando cada cambio de claude.ai/code mediante la extensión de Chrome, abriendo un navegador, recorriendo la interfaz e iterando, mientras la comprobación adecuada depende del dominio: un comando bash, una suite de pruebas, un navegador o un simulador de teléfono (punto 13). Nuestro objeto de comparación es la documentación de code.claude.com del 2026-11-08; documentación actual, más abajo, significa siempre esa fecha.
Boris Cherny: punto 13, el bucle de verificación · Documentación de Claude Code: Best practices
2. Los 13 puntos frente a la documentación actual, tipo de mecanismo y archivo
Esta tabla es el índice del resto del artículo. La columna de mecanismo sigue la definición de best practices: lo decide el modelo significa que Claude lee la instrucción y elige; lo impone el harness significa que Claude Code la aplica en cualquier caso. El mismo objetivo suele existir en ambas formas. Pasar el typecheck antes de terminar puede ser una línea de CLAUDE.md (modelo) o un Stop hook (harness), y el consejo de la documentación es que una línea de CLAUDE.md que usted no para de subrayar pertenece a un hook.
| Punto | Hilo (2026-01) | Documentación actual (2026-11-08) | Mecanismo | Archivo o comando |
|---|---|---|---|---|
| 1 | 5 sesiones locales en paralelo, pestañas numeradas, notificaciones | Terminal config: Ghostty, Kitty e iTerm2 muestran notificaciones de escritorio; para trabajo paralelo, un worktree por sesión (claude -w) | Herramientas, no conducta del modelo | claude -w <name>; ajustes de notificación del terminal |
| 2 | 5–10 sesiones en la nube; traspaso con ampersand; --teleport de vuelta | Página de sesiones en la nube: --cloud crea una tarea nueva en la nube; --teleport trae una sesión de la nube al terminal; la CLI no puede enviar una sesión local existente a la nube (el traspaso con ampersand es solo del hilo) | Herramientas | claude --cloud ...; claude --teleport |
| 3 | Opus 4.5 con thinking para todo | Model config: Opus 5.5 con effort medium es el valor por defecto en la mayoría de planes; se ajusta con /effort, no con la redacción del prompt | Lo decide el modelo (effort fija cuánto piensa) | /model; /effort high |
| 4 | Un CLAUDE.md compartido en git, una nota por cada error | Memory: mantener CLAUDE.md por debajo de 200 líneas; escribir solo lo que el repositorio no muestra; /init, /doctor, /doctor prompt-audit | Lo decide el modelo | CLAUDE.md; .claude/rules/*.md |
| 5 | Mencionar a Claude en los PR para actualizar CLAUDE.md vía GitHub Action | GitHub Actions: /install-github-app instala la app y el workflow; mencionar @claude en un comentario de PR o issue (el hilo dice /install-github-action) | Lo decide el modelo (la Action corre de forma determinista, el texto lo escribe el modelo) | /install-github-app; .github/workflows/claude.yml |
| 6 | Empezar en plan mode (Shift+Tab dos veces), luego aceptar ediciones | Modos de permisos: las sesiones interactivas empiezan en auto; Shift+Tab recorre auto → default → acceptEdits → plan; o prefijar un prompt con /plan; al aprobar el plan se elige el modo siguiente | Plan decidido por el modelo; ediciones bloqueadas por el harness mientras se planifica | Shift+Tab; /plan; claude --permission-mode plan |
| 7 | Un comando de barra por flujo del bucle interno en .claude/commands/ | Skills: los comandos personalizados se fusionaron con las skills; .claude/commands/*.md sigue funcionando; forma nueva .claude/skills/<name>/SKILL.md con disable-model-invocation opcional | Lo decide el modelo (quién puede invocarlo es configurable) | .claude/skills/verify-app/SKILL.md |
| 8 | Subagentes code-simplifier y verify-app | Sub-agents: .claude/agents/<name>.md con name, description, tools, model y más; la lista tools la impone el harness | Mixto: la delegación la decide el modelo, el alcance de herramientas se impone | .claude/agents/code-simplifier.md |
| 9 | Un hook PostToolUse formatea el código | Páginas de hooks y best practices: matcher Edit|Write, el comando lee .tool_input.file_path; onFailure block opcional | Lo impone el harness | .claude/settings.json hooks.PostToolUse |
| 10 | Sin --dangerously-skip-permissions; /permissions preaprueba, settings.json compartido | Permissions: reglas allow, ask y deny; deny rige en todos los modos; las allow del archivo compartido esperan al diálogo de confianza de cada miembro | Lo impone el harness | .claude/settings.json permissions |
| 11 | MCP de Slack en .mcp.json; CLI bq; Sentry | Best practices: preferir una CLI cuando existe; si no, claude mcp add --transport http; desactivar servidores sin uso en /mcp | Herramientas | claude mcp add ...; .mcp.json |
| 12 | Tareas largas: agente en segundo plano, Stop hook o plugin ralph-wiggum | Hooks: un Stop hook sale con 2 para devolver a Claude al trabajo, tope de 8 bloqueos consecutivos, CLAUDE_CODE_STOP_HOOK_BLOCK_CAP ajustable; /goal es la alternativa integrada; el plugin ralph-wiggum no apareció en la ruta del repositorio que revisamos | Stop hook impuesto; /goal lo juzga un modelo | hooks.Stop; /goal <condición> |
| 13 | Dar a Claude una forma de verificar; calidad ×2–3; la extensión de Chrome prueba la interfaz | Best practices: dar algo que devuelva pass o fail; pedir evidencia (comando y salida, o captura); Chrome: claude --chrome, requiere un plan directo Pro, Max, Ultra, Team o Enterprise con sesión iniciada por /login | La comprobación es determinista; que Claude la acepte lo decide el modelo; un Stop hook puede imponerla | scripts/verify.sh; claude --chrome; /verify |
Documentación de Claude Code: Best practices · Documentación de Claude Code: referencia de Hooks · Documentación de Claude Code: subagentes · Documentación de Claude Code: Memory y CLAUDE.md · Documentación de Claude Code: Skills (slash-commands redirige aquí) · Documentación de Claude Code: integración con Chrome · Documentación de Claude Code: modos de permisos · Documentación de Claude Code: reglas de permisos · Documentación de Claude Code: sesiones en la nube (--cloud y --teleport) · Documentación de Claude Code: GitHub Actions · Documentación de Claude Code: configuración del terminal y notificaciones · Documentación de Claude Code: /goal · Documentación de Claude Code: configuración del modelo
Tres filas discrepan del hilo y conviene recordarlas. Primera: el comando es ahora /install-github-app, no /install-github-action. Segunda: el traspaso con ampersand de una sesión local a la web no tiene equivalente en la página de sesiones en la nube, que afirma que el traspaso desde la CLI es unidireccional: --teleport trae una sesión de la nube al terminal, --cloud crea una tarea nueva en la nube y solo la aplicación de escritorio puede enviar una sesión local a la nube. Tercera: el directorio plugins de anthropics/claude-code contenía solo un README cuando lo miramos, así que la ubicación del plugin ralph-wiggum no está confirmada; el artículo lo menciona tal como lo describe el hilo y no da pasos de instalación.
Documentación de Claude Code: sesiones en la nube (--cloud y --teleport) · Documentación de Claude Code: GitHub Actions
3. El bucle de verificación: planificar, implementar, verificar, evidencia, revisión
Una los puntos 6, 9, 12 y 13 y obtiene un solo bucle. Plan mode fija qué construir y qué cuenta como terminado. Tras la aprobación Claude implementa en modo acceptEdits o auto. Cada edición la formatea el hook PostToolUse. Cuando Claude intenta terminar, el Stop hook ejecuta el typecheck o las pruebas y, si fallan, le devuelve la salida del compilador para que siga trabajando. Cuando pasan, Claude presenta evidencia: los comandos ejecutados, sus códigos de salida y su salida, o una captura del navegador. Por último revisa alguien que no escribió el código, sea un subagente nuevo iniciado por /code-review u otro miembro del equipo.
¿Qué pasos son deterministas? El hook de formato y el Stop hook los ejecuta el harness; los resultados de pruebas y typecheck los dan el compilador y el ejecutor de pruebas, no la memoria del modelo; y la negativa de plan mode a editar fuentes también la impone el harness. Si el plan es sólido, si la evidencia basta y si se aceptan los hallazgos de la revisión siguen siendo juicios del modelo o de un humano. Al diseñar el bucle, ponga en el lado determinista los pocos pasos que nunca pueden saltarse y deje el resto al modelo.
La página de best practices es directa sobre la evidencia: la frase todas las pruebas pasan casi no aporta información; lea el comando y su salida, y en una sesión que usted no vigiló es la única evidencia que tiene. El script verify.sh de la sección 8 existe para este paso: escribe el código de salida, la duración y la ruta del log de cada comprobación en un archivo Markdown con marca de tiempo, de modo que Claude, el Stop hook y quien revisa citan el mismo documento.
- Plan mode: leer el código, proponer, acordar la definición de terminado (Shift+Tab o /plan)
- Aprobar el plan → pasar a acceptEdits o auto; Claude implementa
- Tras cada Edit/Write el hook PostToolUse formatea el archivo (impuesto por el harness)
- Claude ejecuta el comando de comprobación de CLAUDE.md, lee la salida y corrige hasta que pasa
- Claude intenta parar → el Stop hook ejecuta tsc o verify.sh; salida 2 lo devuelve al trabajo (impuesto por el harness, tope de 8 consecutivos)
- Pasa → evidencia: comandos, códigos de salida, rutas de logs, capturas (scripts/verify.sh escribe .claude/evidence/)
- Revisión independiente: un subagente nuevo de /code-review u otro miembro del equipo coteja la evidencia con el plan
- Un humano aprueba la fusión; la protección de rama es la última barrera determinista
Documentación de Claude Code: Best practices · Documentación de Claude Code: referencia de Hooks · Documentación de Claude Code: modos de permisos
4. CLAUDE.md: compartido, crecido a partir de errores, breve
El punto 4 sobrevive en las páginas de memory y best practices con dos límites. Longitud: memory fija como objetivo menos de 200 líneas por archivo CLAUDE.md, porque los archivos largos consumen contexto y reducen el cumplimiento; las reglas que solo importan en una parte del árbol van a archivos de .claude/rules/ con un front matter paths: para cargarse solo cuando Claude toca archivos coincidentes. Contenido: escriba solo lo que Claude no puede leer del repositorio, como una decisión tomada en una reunión, un proceso de despliegue que vive en una sola cabeza, la variable de entorno que necesitan las pruebas de integración y todo lo que ya ha corregido dos veces. La arquitectura y la estructura de directorios no van ahí; Claude lee el repositorio por sí mismo.
Documentación de Claude Code: Best practices · Documentación de Claude Code: Memory y CLAUDE.md
Añadir una línea cada vez que Claude falla sigue funcionando, pero la documentación es clara sobre su techo: CLAUDE.md es no determinista y, por fuerte que sea la redacción, seguirla sigue siendo decisión de Claude. Si una regla se sigue omitiendo tras negritas e IMPORTANT, o el archivo es tan largo que la entierra o la regla no admite excepciones, y entonces pertenece a un hook o a una regla deny. El ejemplo de abajo respeta esas reglas. Su último bloque, la definición de terminado, sirve al requisito de evidencia de la sección 3: eleva la probabilidad de que Claude muestre evidencia, mientras la imposición vive en el Stop hook.
# Commands
- Install: pnpm install
- Typecheck: pnpm tsc --noEmit
- Run one test file: pnpm vitest run path/to/file.test.ts
- Full verification with evidence file: bash scripts/verify.sh
# Conventions
- Use the error helpers in src/lib/errors.ts; never throw raw strings
- src/legacy/ is still live, but do not copy its patterns into new code
# Gotchas
- Integration tests need DATABASE_URL set, see .env.example
- src/gen/ is generated (2026-10-30: edited by hand once); run pnpm gen instead
# Definition of done
- Before saying a task is complete, show the command you ran and its output,
or the screenshot. "Tests pass" without output does not count.Tres comandos lo mantienen. /init redacta un borrador a partir del código y sugiere mejoras en vez de sobrescribir uno existente; /doctor propone recortar lo que Claude puede deducir del código; /doctor prompt-audit señala instrucciones escritas para modelos antiguos, que apuntan a archivos inexistentes o que se contradicen. En una sesión, /context all confirma que el archivo se cargó. El punto 5, dejar que Claude enmiende CLAUDE.md durante la revisión de un PR, depende de la GitHub Action: el comando de instalación actual es /install-github-app, que instala la GitHub App, guarda el secreto de autenticación, sube una rama con los archivos del workflow y abre un pull request; una vez fusionado, mencionar @claude en un comentario de issue o PR lo dispara. El resultado de ese paso es texto escrito por el modelo, así que si entra o no en CLAUDE.md sigue siendo una decisión de revisión humana.
Documentación de Claude Code: Best practices · Documentación de Claude Code: Memory y CLAUDE.md · Documentación de Claude Code: GitHub Actions
5. Plan mode, reglas de permisos y dos hooks en un solo settings.json
El punto 6 dice Shift+Tab dos veces para plan mode, que era el recuento desde el modo manual por defecto de enero de 2026. La página de modos de permisos indica ahora que desde Claude Code v2.1.283 las sesiones interactivas de terminal y VS Code empiezan en auto mode, donde un modelo clasificador revisa las acciones arriesgadas en su lugar; desde auto, Shift+Tab pasa a default (manual), luego acceptEdits y luego plan. Prefijar un prompt con /plan o arrancar con claude --permission-mode plan es más rápido. En plan mode Claude lee archivos, ejecuta comandos exploratorios y escribe un plan, pero no puede editar fuentes, y eso lo garantiza el harness; al aprobar el plan usted elige el modo siguiente, que es el paso a aceptar ediciones del hilo.
El punto 10 está intacto en la página de permissions: las reglas allow preaprueban, las ask fuerzan una pregunta y las deny rigen en todos los modos, incluidos auto y bypassPermissions. Importan dos bordes. Un deny sobre Read(./.env) también detiene cat .env, porque Claude Code reconoce los comandos habituales de lectura, pero no un script que abra el archivo; y un deny de dominio para WebFetch no hace nada contra curl salvo que el sandbox esté activo. Best practices añade que el clasificador de auto mode es un juicio, no una regla dura, así que sus reglas de nunca van en deny o en hooks. La renuncia del hilo a --dangerously-skip-permissions coincide con la documentación actual, que reserva bypassPermissions para contenedores desechables.
Documentación de Claude Code: Best practices · Documentación de Claude Code: reglas de permisos · Documentación de Claude Code: modos de permisos
{
"permissions": {
"allow": [
"Bash(pnpm tsc --noEmit)",
"Bash(pnpm vitest run *)",
"Bash(bash scripts/verify.sh)",
"Bash(git status *)",
"Bash(git diff *)"
],
"ask": ["Bash(git push *)"],
"deny": ["Read(./.env)", "Read(./.env.local)", "Read(./secrets/**)"]
},
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "npx prettier --write --ignore-unknown \"$(jq -r '.tool_input.file_path')\""
}
]
}
],
"Stop": [
{
"hooks": [
{ "type": "command", "command": "pnpm tsc --noEmit 1>&2 || exit 2" }
]
}
]
}
}Los dos hooks son los puntos 9 y 12. El matcher de PostToolUse es Edit|Write y el comando extrae .tool_input.file_path del JSON de stdin con jq y se lo pasa a Prettier; la documentación advierte que un archivo reescrito por un comando Bash o un proceso externo no dispara este hook, para eso existe el evento FileChanged. El contrato del Stop hook es código de salida 2 para bloquear la parada, con stderr devuelto a Claude como la razón por la que no puede terminar, y por eso el ejemplo redirige allí la salida del compilador. La página de hooks añade dos válvulas: tras ocho bloqueos de Stop consecutivos sin ninguna llamada a herramienta entre medias, Claude Code anula el siguiente bloqueo y termina el turno (CLAUDE_CODE_STOP_HOOK_BLOCK_CAP sube el tope), y el campo de entrada stop_hook_active es true cuando el turno ya es una continuación por hook, así que los scripts deben leerlo para no girar sobre una condición imposible.
Documentación de Claude Code: referencia de Hooks · Documentación de Claude Code: Best practices
¿Y si se rompe el propio hook? Por defecto un hook que falla o agota el tiempo deja pasar la acción y registra un aviso de error. Para un hook de seguridad puede fijar onFailure: block, de modo que un hook que ni siquiera arranca bloquee igualmente la acción; pero la página de hooks advierte que en eventos Stop un bloqueo devuelve a Claude al trabajo y Claude no puede reparar un hook que no corre, así que el ejemplo no lo pone en el Stop hook. Recuerde también el aviso de best practices: el conjunto impuesto debe ser pequeño y, con cuarenta reglas, la mayoría serán preferencias que el modelo podría haber sopesado solo.
Documentación de Claude Code: referencia de Hooks · Documentación de Claude Code: Best practices
| Archivo o ubicación | Aplica a | Qué poner | Nota |
|---|---|---|---|
| ~/.claude/settings.json | Usted, en todos los proyectos de esta máquina | Tema, modelo por defecto, reglas allow personales, configuración autoMode | El bloque autoMode solo funciona aquí; el clasificador lo ignora en ajustes de proyecto |
| .claude/settings.local.json | Usted, solo en este proyecto | Anulaciones personales; donde se guarda Sí, y no volver a preguntar | Claude Code lo añade a las exclusiones de git al crearlo; si lo crea a mano, añádalo a .gitignore |
| .claude/settings.json | Todo el que trabaje en la carpeta | allow/ask/deny del equipo, hooks, plugins, variables de entorno | Deny aplica de inmediato; allow y hooks esperan al diálogo de confianza de cada miembro |
| Ajustes gestionados (managed-settings.json y otros) | Todo el que la organización despliegue | Política de seguridad, cumplimiento | Ningún archivo personal lo anula; el único lugar para la política del equipo de seguridad |
| CLAUDE.md | Todo el que trabaje en la carpeta | Comandos, convenciones, trampas, decisiones del equipo | No determinista; menos de 200 líneas |
| CLAUDE.local.md | Usted, solo en este proyecto | Preferencias, URL locales, datos de prueba | En .gitignore; se carga junto a CLAUDE.md |
| .claude/rules/*.md | Todos, pero solo en rutas coincidentes | Reglas de un directorio o tipo de archivo | El front matter paths: controla la carga |
| .claude/skills/, .claude/agents/ | Todos | Procedimientos de varios pasos, definiciones de subagentes | Una skill puede fijar disable-model-invocation; la lista tools de un subagente la impone el harness |
Documentación de Claude Code: archivos de ajustes y precedencia · Documentación de Claude Code: Best practices · Documentación de Claude Code: Memory y CLAUDE.md · Documentación de Claude Code: subagentes · Documentación de Claude Code: Skills (slash-commands redirige aquí)
6. Los comandos de barra pasaron a ser skills; los subagentes ganaron front matter
El punto 7 guarda los comandos en .claude/commands/. El 2026-11-08 la URL de documentación de slash-commands resuelve a la página de skills, que abre diciendo que los comandos personalizados se fusionaron con las skills: .claude/commands/deploy.md y .claude/skills/deploy/SKILL.md crean ambos /deploy, los archivos antiguos siguen funcionando y la forma nueva añade un directorio para archivos de apoyo, front matter y control sobre quién invoca. Para un flujo del bucle interno con efectos secundarios o larga duración, la documentación sugiere disable-model-invocation: true, de modo que solo corra cuando usted escribe /verify-app y Claude no pueda iniciarlo por su cuenta. $ARGUMENTS se sustituye por lo que escriba tras el comando.
Documentación de Claude Code: Skills (slash-commands redirige aquí)
El verify-app de abajo corresponde al subagente del punto 8 que guardaba las instrucciones de prueba de extremo a extremo, pero lo escribimos como skill y no como subagente porque necesita manejar el navegador en la sesión actual y devolver la evidencia. allowed-tools solo aplica al turno que lo invoca y preaprueba verify.sh y la lectura del archivo de evidencia. El contenido pide a Claude anotar en cada paso qué hizo, qué esperaba y qué vio, y prohíbe decir funciona sin evidencia. Tenga en cuenta que la página de skills lista un /verify integrado que compila y ejecuta la aplicación para confirmar un cambio; cuando no hay receta grabada escribe los pasos que funcionaron en .claude/skills/verify/SKILL.md, y una skill grabada en la raíz del repositorio sustituye a la integrada, así que evite el nombre verify a secas para su propia skill.
Documentación de Claude Code: Skills (slash-commands redirige aquí)
---
name: verify-app
description: End-to-end check of the web app after a change. Runs the evidence script, drives the changed flow in the browser and reports what was seen. Use before opening a PR.
disable-model-invocation: true
argument-hint: [flow-name]
allowed-tools: Bash(bash scripts/verify.sh) Read
---
1. Run `bash scripts/verify.sh`, then read .claude/evidence/latest.md.
If any step shows a non-zero exit code, stop and report it.
2. Start the app with the command from CLAUDE.md and open it in the
connected browser (http://localhost:3000).
3. Exercise the flow named in $ARGUMENTS: the happy path, one invalid
input, one empty state.
4. For each step write down what you did, what you expected, what you saw.
Take a screenshot of the final state.
5. Report: commands with exit codes, the evidence file path, screenshot
paths, and every mismatch against the plan. Never write "works" without
attaching the evidence.Los subagentes son un archivo Markdown cada uno bajo .claude/agents/ para el proyecto (versionado) o ~/.claude/agents/ para uso personal. La página actual de sub-agents lista el front matter: name y description son obligatorios; tools, disallowedTools, model, permissionMode, maxTurns, skills, memory, isolation y otros son opcionales. El campo tools es determinista: un subagente con Read, Grep, Glob es un revisor que no puede editar, y Claude Code impone ese límite en vez de pedirlo un prompt. El code-simplifier del hilo necesita cambiar archivos y ejecutar comprobaciones, así que el ejemplo concede Edit y Bash; model: inherit conserva el modelo de la sesión principal. Si la sesión principal le delega lo decide Claude a partir de la description, y también puede nombrarlo en un prompt.
---
name: code-simplifier
description: Simplifies code that was just written without changing behaviour. Use after the implementation passes its tests and before review.
tools: Read, Grep, Glob, Edit, Bash
model: inherit
---
You are cleaning up a diff you did not write. Work only on files changed
since the base branch: `git diff --name-only main...HEAD`.
- Remove dead code, duplicated helpers and abstraction layers used once.
- Keep public interfaces and observable behaviour identical. Add no features.
- After each file, run `pnpm tsc --noEmit` and the test file for that module.
- Finish with a table: file, lines before, lines after, commands run and
their exit codes. If a check fails, revert that file and say so.Una nota de coste de la página de best practices: cada petición de un subagente cuenta en su uso, y un subagente nuevo primero reúne el contexto que su conversación ya tenía, así que puede ser más lento; pasar la misma tarea a un subagente no produce una respuesta más inteligente, solo paralelismo, salida larga fuera de la conversación principal y unos ojos que no vieron el razonamiento. Fije model: haiku para trabajos simples y consulte /usage para ver lo que cuesta cada tipo de subagente.
Documentación de Claude Code: Best practices · Documentación de Claude Code: subagentes
7. La verificación cambia por dominio: qué comprobación, qué evidencia, quién impone
El núcleo del punto 13 no es la extensión de Chrome, sino dar a Claude algo que devuelva pass o fail. La página de best practices enumera archivos de prueba, el código de salida de una compilación, un linter, un script que compara la salida con un fixture y una captura del navegador junto al diseño, y dice que si el repositorio ya tiene uno de ellos, la línea más útil de CLAUDE.md es el comando que lo ejecuta. La rigurosidad tiene cuatro niveles: en el prompt (Claude decide cuándo está satisfecho), como /goal (otro modelo comprueba la condición tras cada turno, útil en ejecuciones largas en segundo plano), como Stop hook (impuesto por el harness hasta pasar o llegar al tope) y por alguien que no escribió el código (/code-review en un subagente nuevo).
Documentación de Claude Code: Best practices · Documentación de Claude Code: /goal
| Dominio | Comprobación | Evidencia | Quién impone |
|---|---|---|---|
| Biblioteca / lógica pura | Pruebas unitarias, typecheck, lint | Comando, código de salida, nombres de casos fallidos | Juzga la cadena de herramientas; el Stop hook garantiza la ejecución |
| Herramienta CLI | Un comando bash contra la salida esperada; diff de un fixture | Comando y extracto de stdout/stderr | Código de salida del script; Stop hook |
| Interfaz web | La integración de Chrome abre la página local, rellena formularios, lee la consola; /verify compila y ejecuta | Capturas, lista de errores de consola, notas por paso | El modelo maneja el navegador; un humano lee las capturas |
| Aplicación móvil | Ejecutar en un simulador, según describe el hilo; no hallamos página de documentación específica | Capturas, log de compilación | Lo decide el modelo; depende de su cadena de herramientas |
| Datos / scripts | Repetir con entrada fija, comparar hash de salida o número de filas | Hash de salida, filas, diff | Juzga el script; puede vivir en verify.sh |
| Ejecución larga sin supervisión | Condición /goal más Stop hook más --max-turns | Archivo de evidencia más descripción del PR | /goal lo juzga un modelo; hook y tope de turnos, el harness |
Documentación de Claude Code: Best practices · Documentación de Claude Code: integración con Chrome · Documentación de Claude Code: Skills (slash-commands redirige aquí) · Documentación de Claude Code: /goal
Chrome merece su propia comprobación de requisitos. La página actual de Chrome exige Chrome, Edge u otro navegador Chromium con la extensión Claude in Chrome 1.0.36 o posterior; un plan directo de Anthropic Pro, Max, Ultra, Team o Enterprise con sesión iniciada por /login, porque con una clave de API o un token de larga duración la integración permanece apagada; sin proveedores de nube de terceros; y sin WSL. Se arranca con claude --chrome o activando Enabled by default en /chrome, con la advertencia de que las herramientas de navegador siempre activas aumentan el uso de contexto. Claude se detiene ante páginas de inicio de sesión y CAPTCHA y le pide que los resuelva. Del hábito del hilo de probar cada cambio de claude.ai/code, lo que puede copiar es que Claude abra la página en localhost, recorra el flujo cambiado, lea los errores de consola y tome capturas; lo que no puede copiar es el contenido de las pruebas del otro equipo.
En todos los niveles, pida evidencia. La página de best practices dice, en esencia, que todas las pruebas pasan dice muy poco, que leer la salida es más rápido que repetir la comprobación y que en una sesión no vigilada es la única evidencia que tiene. Añade un consejo de revisión contraintuitivo: diga al revisor que omita el estilo, porque un revisor al que se le pide encontrar problemas siempre encuentra algo, y corregir cada hallazgo acumula capas de abstracción y pruebas de casos imposibles.
8. El script de evidencia: un archivo para Claude, el Stop hook y quien revisa
El verify.sh de abajo es el ejemplo propio de este artículo; pasó bash -n sin conexión y no se ejecutó en un proyecto real. Ejecuta por turno el typecheck, las pruebas y la compilación, escribe el código de salida, la duración y la ruta del log de cada paso en .claude/evidence/ bajo un nombre .md con marca de tiempo, apunta latest.md al archivo más reciente y, al final, imprime todo el archivo en stderr, de modo que usado como Stop hook (bash scripts/verify.sh || exit 2) la razón que ve Claude para no poder terminar es la evidencia misma. El ejemplo de CLAUDE.md y la skill verify-app referencian el mismo comando, así que los tres citan una sola salida.
Documentación de Claude Code: Best practices · Documentación de Claude Code: referencia de Hooks
#!/usr/bin/env bash
# scripts/verify.sh - run the project's checks and write an evidence file
# that Claude, a Stop hook and a human reviewer can all quote.
set -u
OUT_DIR=".claude/evidence"; mkdir -p "$OUT_DIR"
STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
OUT="$OUT_DIR/$STAMP.md"
status=0
run() { # run <label> <command...>
local label="$1"; shift
local start; start=$(date +%s)
local rc=0
"$@" >"$OUT_DIR/$label.log" 2>&1 || rc=$?
printf -- '- %s: exit %s, %ss, log %s/%s.log\n' \
"$label" "$rc" "$(( $(date +%s) - start ))" "$OUT_DIR" "$label" >>"$OUT"
[ "$rc" -ne 0 ] && status=1
return 0
}
{
echo "# Verification evidence $STAMP"
echo "- commit: $(git rev-parse --short HEAD 2>/dev/null || echo none)"
echo "- changed files: $(git diff --name-only HEAD 2>/dev/null | wc -l | tr -d ' ')"
} >"$OUT"
run typecheck pnpm tsc --noEmit
run tests pnpm vitest run
run build pnpm build
echo "- overall: $([ "$status" -eq 0 ] && echo PASS || echo FAIL)" >>"$OUT"
ln -sfn "$STAMP.md" "$OUT_DIR/latest.md"
cat "$OUT" >&2 # stderr, so "bash scripts/verify.sh || exit 2" works as a Stop hook
exit "$status"Tres decisiones. Si colgar el script entero en Stop: ejecutar todas las pruebas y la compilación cada vez que Claude quiere terminar puede ser lento, así que el settings.json de la sección 5 ejecuta solo tsc en Stop y deja el script completo a la skill o al prompt; si su suite tarda uno o dos minutos, colgarlo todo está bien. El script ignora a propósito stop_hook_active porque lo recalcula todo y no tiene ninguna condición imposible; si su comprobación depende de un servicio externo, lea el JSON de stdin al principio y salga con 0 cuando stop_hook_active sea true y el fallo se repita, devolviendo el problema a un humano. Y si versionar el directorio de evidencia: añádalo a .gitignore y pegue latest.md en la descripción del PR, o cada ejecución se convertirá en ruido de commits.
Mantenga separados los papeles al combinar el script con CLAUDE.md. CLAUDE.md le dice a Claude que el comando existe, y Claude suele ejecutarlo al terminar; el Stop hook garantiza que corrió y pasó al menos una vez antes de que acabe el turno; el archivo de evidencia permite a un revisor humano comprobar sin repetir. Por eso best practices deja la línea de typecheck de CLAUDE.md en solo el comando: el comando es para el modelo, la imposición es para el hook.
9. Qué cambió entre enero y noviembre
Los puntos 1, 2, 3 y 11 son sobre todo elecciones de entorno y herramientas, y hay que actualizarlos antes de copiarlos. Opus 4.5 con thinking fue la elección del autor en ese momento; la página de model config lista ahora Opus 5.5 con effort medium como valor por defecto en la mayoría de planes y proveedores, y best practices hace de effort el control principal de cuánto piensa Claude, siendo frases como think hard texto normal del prompt. El razonamiento del hilo, que un modelo mayor que necesita menos corrección acaba siendo más rápido, sigue en pie; el nombre del modelo debe salir de /model. Para sesiones paralelas la documentación recomienda ahora un worktree por sesión (claude -w feature-x) para que las ediciones no choquen, y la página de terminal config dice que Ghostty, Kitty e iTerm2 muestran notificaciones de escritorio, con iTerm2 necesitando activar antes sus ajustes de alertas.
Documentación de Claude Code: configuración del modelo · Documentación de Claude Code: Best practices · Documentación de Claude Code: configuración del terminal y notificaciones
| Hilo (2026-01) | Documentación 2026-11-08 | Qué significa para un equipo |
|---|---|---|
| Opus 4.5 con thinking | Por defecto Opus 5.5 con effort medium; /effort ajusta | No fije un nombre de modelo en CLAUDE.md; use /effort, no la redacción del prompt |
| Shift+Tab dos veces para plan mode | Las sesiones empiezan en auto; tres pulsaciones desde auto, o /plan | Escriba /plan en su documentación |
| El ampersand pasa una sesión local a la web | El traspaso desde la CLI es unidireccional: --cloud crea, --teleport trae de vuelta; la aplicación de escritorio puede enviar una sesión local | El traspaso con ampersand es solo del hilo; documente los comandos actuales |
| .claude/commands/ para comandos de barra | Fusionados con las skills; los archivos antiguos funcionan; la forma nueva es SKILL.md | Escriba los flujos nuevos como skills y controle quién los invoca |
| /install-github-action | /install-github-app | Comando renombrado |
| Sin --dangerously-skip-permissions | Sigue existiendo; la documentación lo limita a contenedores desechables | Misma postura; las reglas deny siguen aplicando en ese modo |
| Plugin ralph-wiggum | No hallado en la ruta del repositorio que revisamos | No lo instale a partir del hilo; confirme antes la fuente |
| Un agente en segundo plano verifica tareas largas | Los subagentes corren en segundo plano por defecto; /goal es la alternativa integrada | Prefiera /goal o un Stop hook para tareas largas |
Documentación de Claude Code: configuración del modelo · Documentación de Claude Code: modos de permisos · Documentación de Claude Code: sesiones en la nube (--cloud y --teleport) · Documentación de Claude Code: Skills (slash-commands redirige aquí) · Documentación de Claude Code: GitHub Actions · Documentación de Claude Code: referencia de Hooks · Documentación de Claude Code: subagentes · Documentación de Claude Code: /goal
El principio del punto 11 no cambió: prefiera una CLI cuando exista, pues con gh instalado y autenticado Claude abre pull requests y lee revisiones sin explicaciones; para sistemas sin CLI use MCP con claude mcp add --transport http seguido de un nombre y la URL del servidor, tras lo cual el servidor aparece en /mcp. Best practices añade una nota de coste: los servidores conectados añaden los nombres e instrucciones de sus herramientas al contexto aunque no se usen, así que apague los que no necesite. Compartir la configuración de Slack mediante .mcp.json como hace el hilo es coherente con esto; mantenga las credenciales en variables de entorno y no en el archivo.
10. Reproducirlo en un equipo en una semana: orden y aceptación
Ordene el trabajo por dependencias y empiece por lo que las pruebas pueden confirmar. La secuencia supone que el repositorio ya tiene un comando de pruebas o typecheck; si no, añada primero un comando que devuelva pass o fail, porque todos los pasos siguientes dependen de él. Cada paso indica cómo confirmar que surtió efecto, y cada método de confirmación procede de la documentación actual.
- Día 1: escribir CLAUDE.md con la plantilla de la sección 4, solo comandos, convenciones, trampas y definición de terminado; dejar que /init lo redacte y recortar a menos de 200 líneas; confirmar con /context all y leer las sugerencias de /doctor.
- Día 2: versionar la parte permissions de .claude/settings.json; que cada miembro acepte el diálogo de confianza de la carpeta, o las reglas allow quedan inertes; inspeccionar las reglas efectivas con /permissions y pedir a Claude que lea .env para confirmar la negativa.
- Día 3: añadir el hook de formato PostToolUse; pedir a Claude que añada una línea mal indentada a un archivo que Prettier procesa y confirmar que el archivo guardado vuelve corregido; listar los hooks registrados con /hooks.
- Día 4: añadir scripts/verify.sh y el Stop hook (al principio solo tsc); pedir a Claude un cambio que rompa un tipo y confirmar que recibe los errores del compilador y sigue trabajando en vez de parar; si aparece el tope de ocho bloqueos, la condición misma está mal.
- Día 5: añadir la skill verify-app y el subagente code-simplifier; ejecutar /verify-app <flow> una vez y revisar el archivo de evidencia y las capturas; pedir a Claude que llame a code-simplifier e inspeccionar los códigos de salida que informa.
- Cada semana: pasar las correcciones repetidas de la revisión a CLAUDE.md (o dejar que lo haga la GitHub Action); ejecutar /doctor prompt-audit cada mes; cuando el conjunto impuesto supere una docena de reglas, preguntar cuáles son en realidad preferencias.
Documentación de Claude Code: Best practices · Documentación de Claude Code: referencia de Hooks · Documentación de Claude Code: Memory y CLAUDE.md · Documentación de Claude Code: Skills (slash-commands redirige aquí) · Documentación de Claude Code: reglas de permisos
Basta un criterio de aceptación: para cualquier cambio completado por Claude, quien revisa puede ver en la descripción del PR o en el archivo de evidencia qué se ejecutó, con qué códigos de salida y qué capturas, sin repetir ningún comando. Cuando se cumple, el bucle del punto 13 existe. La afirmación de calidad dos o tres veces mayor es la experiencia del autor; no teníamos forma de reproducir el factor y no lo intentamos.
Lo que no verificamos: no ejecutamos Claude Code, así que no observamos el tope de ocho bloqueos de Stop, el momento de disparo de PostToolUse ni la integración de Chrome en la práctica; no confirmamos la ubicación actual del plugin ralph-wiggum; el traspaso con ampersand de una sesión local a la web no tiene equivalente en la documentación actual y no podemos decir si sigue funcionando; las visualizaciones son lecturas del 2026-11-08; la mejora de calidad de dos a tres veces es experiencia personal del autor y no fue reproducida. Este artículo analiza la documentación pública de Anthropic y el hilo público de un ingeniero; este sitio no está afiliado a Anthropic. Los artículos relacionados de abajo cubren los límites de ejecuciones sin supervisión, el incidente del correo de cuenta en User-Agent y el informe sobre uso por investigadores.