English

Dile a tu agente que anote, no que arregle, los problemas fuera de alcance

La limpieza servicial de tu IA está saboteando tu pull request. Le pides que arregle un bug y regresa habiendo también renombrado tres variables, modernizado un import que solo leyó y reformateado un archivo que abrió de paso. El bug queda arreglado — pero ahora el diff tiene 400 líneas en nueve archivos, y quien revisa no puede distinguir la corrección de una línea del ruido a su alrededor.

El instinto detrás de esto es bueno. El agente ve código muerto, un patrón viejo, un error en un comentario, y quiere dejar el campamento más limpio de como lo encontró. El problema es cuándo. Cada mejora no relacionada que se cuela en una tarea mezcla responsabilidades e infla el cambio bajo revisión.

Por qué gana la disciplina de alcance

La guía de prácticas de ingeniería de Google es directa: un buen changelist "hace un cambio mínimo que aborda una sola cosa". Los diffs pequeños y de un solo propósito se revisan más rápido, se revisan más a fondo, tienen menos probabilidad de esconder un bug y son mucho más fáciles de fusionar y de revertir. La misma guía dice sin rodeos que "suele ser mejor hacer las refactorizaciones en un CL separado de los cambios de funcionalidad o de las correcciones de bugs" — mover una clase y arreglar un bug en esa clase son dos revisiones, no una.

Un diff inflado roba en silencio todos esos beneficios. Quien revisa ahora tiene que deducir la intención: ¿cuáles líneas son la corrección y cuáles son el agente improvisando? Esa es exactamente la carga cognitiva que los diffs pequeños existen para eliminar.

La única regla

Dale a tu agente una sola instrucción y ponla donde la lea en cada sesión — para Claude Code, eso es CLAUDE.md:

## Scope discipline
- Touch only what the task requires. Do not clean up, reformat, or
  modernize code that is adjacent to — or merely read by — the task.
- If you notice something worth improving that is out of scope, NOTE it,
  do not fix it. Add it to a "Things I didn't touch" list at the end of
  your summary and offer it as a follow-up.

Ahora el instinto de limpieza del agente tiene a dónde ir que no es tu diff. Sigue sacando a la luz el código muerto y el patrón obsoleto — como una lista de seguimientos que puedes priorizar — mientras el pull request se mantiene como un solo cambio lógico.

Anotar vs. arreglar: una regla rápida

El límite es simple: arregla solo lo que la tarea no puede completarse sin ello. Todo lo demás es una nota.

Movidas de usuario avanzado

• Haz de la lista de seguimientos un entregable. Pide un FOLLOWUPS.md o un bloque con viñetas de "Things I didn't touch" en cada resumen. Esas notas se convierten en un backlog listo de PRs de limpieza pequeños y acotados — los del buen tipo.
• Mantén la regla corta y arriba en CLAUDE.md. La propia guía de Anthropic recomienda mantener estos archivos concisos; los modelos frontera siguen de forma confiable solo un par de cientos de instrucciones, así que una regla de alcance enterrada bajo 300 líneas se ignora. Un párrafo breve cerca del inicio le gana a un párrafo en la página tres.
• Divide cuando el agente ya se excedió. Si un diff volvió demasiado grande, pídele al agente que mueva los cambios incidentales a un segundo commit o a una rama separada — un PR por cambio lógico, tal como prescriben las guías de revisión de código.
• Nombra el alcance también en la tarea. "Arregla el null check en auth.ts; no cambies nada más" refuerza la regla permanente al momento de pedir y le da al modelo un límite concreto que respetar.

Recursos

• Small CLs — Google Engineering Practices
• Writing good CL descriptions — Google Engineering Practices
• Best practices for Claude Code — Anthropic