Planear, dar permisos y trabajar con Git

En el módulo 11 instalaste Claude Code y en el 12 le enseñaste tu proyecto. Ahora viene la pregunta de la segunda semana: ¿cómo dejo que un agente cambie cosas reales sin que un error termine en el sitio que ven mis clientes? La respuesta no es un truco de prompts. Es un proceso, el mismo que usan los equipos de software desde hace décadas, al que Claude Code agrega un modo para planear sin tocar nada y un sistema de permisos.

Lo que este módulo dice de Claude Code está verificado contra la documentación oficial a octubre de 2026; si algo no coincide, la documentación manda.

¿Por qué planear antes de que el agente toque nada?

Si le pides a un agente de código "agrega un formulario de contacto", empieza a editar archivos en segundos. A veces resuelve el problema equivocado: el que entendió, no el que tenías. La guía de buenas prácticas de Anthropic lo dice así: dejar que Claude salte directo a programar puede producir código que resuelve el problema equivocado. Por eso recomienda separar la investigación y la planeación de la ejecución.

La herramienta es el modo plan: Claude lee archivos, corre comandos para explorar y escribe un plan, pero no edita nada hasta que lo apruebes. Hay tres formas de entrar:

• Shift+Tab dentro de una sesión, varias veces si hace falta, hasta que la barra de estado muestre "⏸ plan mode on". El mismo atajo rota entre los modos de permisos de la siguiente sección.
• /plan al comienzo de un solo mensaje, para planear esa petición y nada más.
• claude --permission-mode plan al abrir la sesión desde la terminal.

El ciclo que propone la documentación tiene cuatro pasos: explorar (que lea las partes del proyecto que importan), planear (que liste qué archivos va a cambiar y en qué orden), implementar (apruebas el plan y lo dejas construir) y confirmar (pruebas, build y un commit con un mensaje claro). Cuando el plan está listo, Claude te da tres opciones: aprobar y seguir en modo automático (o aceptando ediciones, según tu sesión), aprobar revisando cada edición una por una, o "No, keep planning". Con Ctrl+G abres el plan en tu editor de texto y lo corriges a mano.

Ese momento, el plan en pantalla y nada tocado, es donde más vale tu criterio de negocio. Léelo como la propuesta de un contratista: ¿entendió lo que pedí? ¿Va a tocar algo que no debería? ¿Cómo va a comprobar que quedó bien? Corregir un plan cuesta un mensaje; una implementación, una tarde.

Quiero hacer este cambio: [DESCRIBE EL CAMBIO EN UNA O DOS FRASES, CON EL RESULTADO QUE ESPERAS VER].

Antes de editar nada:
1. Explora el proyecto y explícame en lenguaje simple cómo funciona hoy la parte que vamos a cambiar.
2. Lista cada archivo que vas a modificar o crear, y qué vas a cambiar en cada uno.
3. Dime qué podría romperse con este cambio y qué partes del proyecto NO vas a tocar.
4. Propón cómo vamos a comprobar que quedó bien: qué pruebas corres, qué comando de build, qué debo mirar yo en el navegador.
5. Si algo de lo que pedí es ambiguo, pregúntame antes de asumir.

No hagas ninguna edición hasta que yo apruebe el plan.

¿Qué permisos tiene Claude Code y cómo los controlo?

Cada acción que podría cambiar tu sistema pasa por un sistema de permisos que tú configuras y que aplica el programa, no el modelo: una instrucción en tu CLAUDE.md orienta lo que Claude intenta, pero no cambia lo que Claude Code le deja hacer. En el modo manual (el que la documentación llama default), leer y buscar dentro de la carpeta del proyecto no pregunta; editar archivos, correr comandos (salvo un conjunto fijo de solo lectura, como listar carpetas o las formas de solo lectura de git) y buscar en la web sí preguntan.

Cuando apruebas un comando con "Yes, and don't ask again", Claude Code guarda esa regla en un archivo del proyecto y no vuelve a preguntar por ese comando en ese repositorio. Encima hay modos que mueven la línea de lo que corre sin preguntar:

• Manual (default): solo lecturas sin preguntar. Para trabajo delicado.
• acceptEdits: además acepta ediciones de archivos y comandos comunes de carpetas (crear, mover, copiar).
• plan: el modo plan de la sección anterior.
• auto: un segundo modelo, un clasificador, revisa cada acción en lugar de ti y bloquea lo que parezca riesgoso: salirse del alcance de lo pedido, fusionar un pull request que ninguna persona aprobó, subir secretos a un repositorio público. Hoy es el modo con el que arrancan las sesiones de terminal. Si en la conversación dices "no hagas push hasta que yo revise", el clasificador lo trata como un límite.
• bypassPermissions: todo corre sin preguntar ni revisar. La documentación es tajante: solo en entornos aislados como contenedores o máquinas virtuales sin acceso a internet, donde Claude Code no pueda dañar tu equipo. En tu computador de trabajo, nunca.

Las reglas afinan cualquier modo. Se evalúan en este orden: deny (prohibido, en todos los modos, incluso bypassPermissions), ask (siempre pregunta) y allow (corre sin preguntar); una prohibición gana siempre sobre un permiso. Se escriben con la herramienta y un patrón: `Bash(npm run *)` permite cualquier script de npm, `Bash(git push *)` como ask obliga a preguntar antes de subir código, `Read(./.env)` como deny impide leer el archivo donde viven tus claves. Las ves y editas con /permissions, y viven en tres archivos:

• ~/.claude/settings.json: tú, en todos tus proyectos.
• .claude/settings.json dentro del proyecto: todos los que trabajen en esa carpeta. Se guarda en el repositorio para que el equipo reciba las mismas reglas y hooks.
• .claude/settings.local.json dentro del proyecto: solo tú, solo ahí. Es donde Claude Code guarda tus "don't ask again"; cuando él crea el archivo lo mantiene fuera de Git, y si lo creas a mano, agrégalo tú al .gitignore.

¿Qué es Git y por qué debes entenderlo aunque no programes?

Git lleva el historial de un proyecto. Según el libro oficial Pro Git, cada vez que guardas, Git toma una foto de cómo están todos los archivos en ese momento y conserva la serie de fotos. Es tu red de seguridad y tu registro de auditoría: ves qué cambió, vuelves a cualquier foto anterior y trabajas en un borrador sin tocar lo publicado. Seis palabras bastan, y la analogía de un contrato las aterriza:

• Repositorio. La carpeta del proyecto con todo su historial. El expediente del contrato: la versión vigente, cada versión anterior y quién cambió qué.
• Commit. Una foto guardada con un mensaje. "Versión 4: se ajustó la cláusula de pago al día 5". Un buen mensaje dice qué y por qué; el cómo ya está en los archivos.
• Rama. Una copia de trabajo donde cambias cosas sin tocar la versión vigente. La rama principal (suele llamarse main) es el contrato firmado; tu rama es el borrador con control de cambios.
• Pull request. La propuesta formal de incorporar tu rama a la principal. GitHub lo define como una propuesta para fusionar cambios en un proyecto, con espacio para discutirlos y revisarlos antes. Es la revisión antes de firmar: cada línea que cambia, a la vista de alguien distinto del autor.
• Merge. Incorporar los cambios aprobados a la rama principal. El borrador pasa a ser el contrato vigente. En muchos proyectos, incluido el nuestro, ese acto dispara la publicación.
• Revert. Deshacer un commit con un commit nuevo que lo invierte, sin borrar el historial. Como un otrosí que deja sin efecto una cláusula: el registro se conserva, que es lo que quieres cuando hay que explicar qué pasó.

No necesitas memorizar comandos: Claude Code los ejecuta, y con la herramienta gh de GitHub instalada sabe abrir pull requests y leer comentarios. Lo que necesitas es el idioma: "crea una rama para esto", "haz commit de lo que llevamos", "abre un pull request", y revisar lo que generó antes de enviarlo.

¿Cómo deshago algo que salió mal?

Tienes dos redes de seguridad. La primera vive dentro de Claude Code: los checkpoints. Cada mensaje tuyo que inicia un turno crea un punto de control con cómo estaban los archivos. Con /rewind, o pulsando Esc dos veces con el cuadro de texto vacío, abres un menú con tus mensajes de la sesión y eliges: restaurar código y conversación, solo la conversación o solo el código. Es ideal para "esa última idea no funcionó, volvamos atrás".

Pero tiene límites que la documentación deja claros: solo registra ediciones hechas con las herramientas de archivos de Claude, no lo que cambió un comando de terminal (un rm, un mv); normalmente no restaura lo que editó un subagente; y los respaldos se borran al cabo de un tiempo. No reemplaza el control de versiones. La regla práctica: dentro de una sesión, rewind; entre sesiones o para cualquier cosa ya publicada, Git (una rama que se descarta, un revert, volver a un commit).

¿Cuál es el flujo seguro de principio a fin?

Esto es lo que vas a repetir cada vez que un agente cambie algo real; con práctica son veinte minutos.

1. 1Rama nueva. "Crea una rama llamada formulario-contacto". Desde aquí, nada toca la versión publicada.
2. 2Plan. Modo plan con el prompt de arriba. Lees el plan como una propuesta, lo corriges, lo apruebas.
3. 3Implementar. Sales del modo plan y lo dejas construir. Si ves algo raro, Esc y redirige.
4. 4Pruebas y build. "Corre las pruebas y el build, y muéstrame la salida". La guía insiste en darle a Claude una comprobación que pueda ejecutar: pruebas, un build que falla o pasa, una captura para comparar. Si no puedes verificarlo, no lo publiques.
5. 5Revisar el diff. /diff te muestra todo lo que cambió sin salir de la sesión. Léelo con el prompt de revisión de abajo, o pídele a un subagente que lo revise en un contexto limpio: quien no escribió el código lo juzga con más frialdad.
6. 6Commit. Un mensaje que explique qué y por qué. Claude lo escribe; tú lo lees.
7. 7Pull request. "Abre un pull request" con qué cambia, cómo se probó y qué debería mirar quien revisa.
8. 8Revisión. Alguien distinto del autor aprueba. Si trabajas solo, es tú al día siguiente o un segundo agente con instrucciones de revisor; el humano en el ciclo del módulo 9 aquí tiene nombre.
9. 9Merge y despliegue. Al fusionar a la rama principal, se publica. Si el despliegue es automático, el merge es el botón de "enviar al cliente".

Quién revisa qué: el agente revisa consistencia, errores de código y que las pruebas pasen; tú revisas que el cambio sea el que pediste, que no tocó lo que no debía y que lo que ven los clientes diga lo correcto. Esa mitad no se delega, porque es Diligencia: quien fusiona responde por lo publicado. Y todo el flujo depende de lo bien que describiste la tarea; el módulo 17 convierte esa descripción en una especificación con criterios de aceptación y pruebas como contrato.

Revisa el diff actual de este proyecto como un revisor exigente que no escribió el código. El objetivo del cambio era: [OBJETIVO EN UNA FRASE].

Responde punto por punto:
1. ¿El cambio hace exactamente lo pedido, ni más ni menos? Lista cualquier archivo o función modificada que no sea necesaria para el objetivo.
2. ¿Qué podría romperse? Casos límite, datos vacíos, textos en los dos idiomas, pantallas pequeñas.
3. ¿Hay algo que un cliente vería mal: textos, precios, enlaces, errores de ortografía?
4. ¿Hay datos sensibles, claves o rutas de mi computador que no deberían estar en el código?
5. ¿Las pruebas cubren el cambio? Si no, qué prueba agregarías.

Reporta solo hallazgos que afecten la corrección o el objetivo; no sugerencias de estilo. Para cada uno: archivo, línea y qué harías.

Prepara el commit y el pull request para el cambio actual.

Mensaje del commit: una primera línea de máximo 70 caracteres que diga qué cambió, en [IDIOMA], y debajo dos o tres frases con el porqué. No describas cómo (eso está en el código).

Descripción del pull request, con estos apartados:
- Qué cambia y por qué (para alguien que no vio la conversación).
- Cómo se probó: comandos que corriste y su resultado, y qué revisé yo a mano.
- Qué debería mirar quien revisa, en orden de riesgo.
- Qué NO cambia, para acotar la revisión.

Muéstrame los dos textos antes de ejecutar nada. No hagas push hasta que yo lo diga.

El siguiente módulo, "Skills, comandos, hooks y subagentes", vuelve repetible lo que acabas de hacer a mano: el prompt de revisión como un comando propio, las pruebas antes de cada commit como un hook que no se puede saltar, y un subagente revisor con sus propias instrucciones.