Cómo escribir el brief de tu primera tarea con Claude Code

“Oye, déjame el README de este repositorio bonito, como tú veas.”

Treinta minutos después de instalarlo, ese fue el primer encargo que le lancé a Claude Code. Lo que volvió fue un diff que, además del README, había reescrito hasta los nombres de los scripts en package.json. Funcionaba, sí, pero tres archivos habían cambiado en sitios que yo no quería tocar. Me quedé congelado frente a la pantalla pensando: “¿Esto se puede publicar o no?”.

¿Por qué Claude Code, que se supone que es listísimo, mete mano en sitios que nadie le pidió? No es un problema de capacidad. Es que yo no le dije ni una palabra sobre hasta dónde podía llegar. Es como decirle a un becario “déjame la tienda bonita” y volver para encontrarte las estanterías reordenadas de arriba abajo.

Este artículo va justo de eso: de escribir ese “hasta dónde” en una sola hoja. Yo lo llamo el brief de la primera tarea.

Puntos clave

El primer encargo sale mal porque pides “déjamelo bonito” sin definir objetivo, permisos, verificación y cómo deshacerlo.
El brief lleva 9 campos: objetivo / estado del lector / qué puede leer / qué puede editar / qué puede ejecutar / qué no toca / verificación / cómo deshacer / siguiente paso.
A Claude Code le delegas “leer, corregir y ejecutar comandos de verificación”. Borrar, desplegar a producción y cualquier gasto los decides tú.
Te dejo una plantilla de brief para copiar y pegar, y un script de JavaScript que comprueba automáticamente si al brief le falta algún campo.
El atajo al primer éxito es elegir una sola tarea pequeña que, si falla, puedas revertir con git.

Por qué la primera tarea acaba en accidente

Justo después de instalar Claude Code, casi todo el mundo hace lo mismo: lanzar un encargo amplio. “Ordéname el repositorio”, “arregla el README”. Lo entiendo: quieres ver de qué es capaz.

Pero con un encargo amplio, los primeros diez minutos se van en exploración. Claude Code lee archivos por todas partes, corrige por su cuenta lo que le parece relacionado, y termina con un informe vago tipo “creo que funciona”. Y tú acabas releyendo el diff entero hasta concluir que “habría ido más rápido haciéndolo yo”.

La causa no es lo listo que sea el modelo. Es que no le has dado ni la meta ni los límites. Hasta un becario humano, si en su primer día le dices “haz lo que quieras”, o se queda paralizado o se descontrola. Con solo fijar los límites de antemano, este accidente desaparece casi por completo.

Si lo que te preocupa son las operaciones básicas, échale un vistazo primero a cómo empezar con Claude Code y vuelve aquí: la parte del brief te entrará mucho mejor.

Los 9 campos que escribo en el brief

Esto es lo que pongo en una hoja cada vez. No hacen falta palabras técnicas. Solo rellenas una respuesta por línea.

Campo	Qué escribir	Mal → Bien
Objetivo	Cómo se ve el éxito al terminar	”Arreglar el README” → “Ajustar los pasos del README a `package.json`”
Estado del lector	Para quién es el trabajo	(vacío) → “Principiante, quiere acertar una sola vez”
Qué puede leer	Archivos que se permite consultar	(todos) → “Solo README.md y package.json”
Qué puede editar	Archivos que se permite cambiar	(todos) → “Solo README.md”
Qué puede ejecutar	Comandos que se permite lanzar	(cualquiera) → “Solo npm run build”
Qué no toca	Lo que jamás puede cambiar	(sin definir) → “package-lock, configuración de despliegue, precios”
Verificación	La prueba de que salió bien	”Si funciona, vale” → “build pasa / el diff es solo del README”
Cómo deshacer	Cómo volver atrás si falla	(nada) → “Restaurar el README desde git”
Siguiente paso	Un único próximo destino para el lector	(poner tres) → “Primero solo el material de iniciación gratuito”

La clave está en “qué no toca”, “verificación” y “cómo deshacer”. En el momento en que escribes esas tres líneas, el encargo deja de ser un “favor” y se convierte en “un trabajo que puedo delegar con tranquilidad”.

Plantilla de brief para copiar y pegar

Aquí tienes una plantilla lista para usar. Va en un bloque de código para que puedas pegársela tal cual a Claude Code. Cambia el nombre de tu repositorio y la zona que quieres tocar.

# Brief de la primera tarea

Objetivo: Ajustar los pasos de configuración del README al contenido de package.json.
Estado del lector: Principiante. Quiere acertar una sola vez.
Qué puede leer:
- README.md
- package.json
Qué puede editar:
- Solo README.md
Qué puede ejecutar:
- npm run build
Qué no toca:
- package-lock.json
- Configuración de despliegue (variables de entorno, ajustes de publicación)
- Precios o enlaces de registro
Verificación:
- npm run build pasa
- git diff muestra cambios solo en README.md
Cómo deshacer:
- Si la verificación falla, restaurar README.md desde git
Siguiente paso:
- Recomendar solo el material de iniciación gratuito

Con un encargo real: si solo se trata de ajustar los pasos del README a package.json, lo que se lee es el README y package.json, lo que se edita es solo el README, y la prueba es npm run build. Con este nivel de detalle, aunque salga mal lo reviertes de un golpe con git checkout -- README.md. La primera vez vale más estrechar así. De hecho, cuanto más estrecho, mejor puedes juzgar tú mismo si salió bien o no.

Qué delegar a Claude Code y qué decides tú

Cuando escribo el brief, trazo esta línea en mi cabeza. Si la frontera es borrosa, Claude Code se la salta “creyendo que te ayuda”.

Se le puede delegar a Claude Code	Lo decides tú (no se automatiza)
Leer archivos indicados	Decidir qué archivos puede tocar
Editar solo los archivos indicados	Borrar archivos
Ejecutar comandos de verificación como `npm run build`	Desplegar o reflejar en producción
Devolver un resumen del diff	Operaciones que generan gasto
Informar de la causa de un fallo	Operaciones irreversibles como `git push --force`

La columna izquierda se delega. La derecha, al principio, déjala toda en “confirmar con la persona antes de ejecutar”. Solo cuando una operación demuestre ser segura, la vas moviendo poco a poco hacia el lado automático. Con solo respetar este orden, las veces que te entran sudores fríos de madrugada se reducen muchísimo.

Al entregar el encargo, añado siempre esta línea:

Ejecuta una sola tarea pequeña, solo dentro del alcance de este brief.
Lo que consideres fuera de alcance, no lo ejecutes: solo propónlo.

Antes de nada, devuélveme estas 5 cosas:
1. Archivos que vas a leer
2. Archivos que vas a editar
3. Comandos de verificación antes y después del trabajo
4. Resumen del diff de los cambios
5. Cómo deshacer si algo falla

Lo importante es pedir “antes de implementar, devuélveme el plan y la verificación”. Si el plan que vuelve se sale del alcance del brief, lo paras en el sitio. Si lo paras antes de mover un solo dedo, no hay nada que limpiar después.

Código para detectar campos que faltan en el brief

Aunque creas que has escrito el brief completo, es fácil que se te escape un campo. Yo compruebo la presencia de cada campo con una máquina. Es un JavaScript que funciona copiándolo y pegándolo. Lo lanzas con Node.js, por ejemplo con node check-brief.mjs.

// Comprueba de forma mecánica si el brief tiene todos los campos necesarios
const requiredFields = [
  "Objetivo",
  "Qué puede leer",
  "Qué puede editar",
  "Qué puede ejecutar",
  "Qué no toca",
  "Verificación",
  "Cómo deshacer",
  "Siguiente paso",
];

export function validateFirstTaskBrief(markdown) {
  // Lista los campos que no están incluidos
  const missing = requiredFields.filter((field) => !markdown.includes(field));

  // También mira si llega a escribir el comando de verificación (aquí, npm run build)
  const hasProofCommand = markdown.includes("npm run build");

  return {
    ok: missing.length === 0,
    missing,
    readyForClaudeCode: missing.length === 0 && hasProofCommand,
  };
}

// Ejemplo de comprobación
const sample = `
Objetivo: Ajustar el README a package.json
Qué puede leer: README.md
Qué puede editar: README.md
Qué puede ejecutar: npm run build
Qué no toca: package-lock.json
Verificación: npm run build pasa
Cómo deshacer: restaurar README.md desde git
Siguiente paso: material de iniciación gratuito
`;

const result = validateFirstTaskBrief(sample);
console.log(result);
// → { ok: true, missing: [], readyForClaudeCode: true }

Si pasas esta comprobación antes de entregar el brief, dejan de olvidársete “qué no toca” y “cómo deshacer”. Si confías solo en el ojo humano, un día con prisas siempre se te escapa algo. Lo que una máquina puede saber, mejor dejárselo a la máquina.

Tres situaciones donde funciona bien

1. Corregir un README o una guía de pasos “Actualiza la documentación” tiene alcance infinito. Si lo estrechas a “solo la sección de configuración del README, ajustada a los nombres de los scripts de package.json”, el diff cabe en un archivo y lo verificas con npm run build. Es lo más adecuado para una primera tarea.

2. Una primera revisión de un pull request En lugar de “mira este PR”, di: “de los archivos cambiados, lee solo lo que está bajo src/ y señala dónde podrían romperse los tests. No toques el código, solo señala”. Le delegas la lectura, pero el juicio de qué corregir te lo quedas tú. Así evitas el accidente de “lo arregla por su cuenta y genera otro bug”.

3. Cambiar el CTA (el enlace al siguiente paso del lector) Incluso para sustituir un solo botón debajo de un artículo popular, “busca el componente relacionado y arréglalo” es demasiado amplio. Antes, define en el brief “qué archivos puede tocar”, “qué URL pública vas a comprobar” y “qué enlace se sustituye”. La comprobación final pasa de “parece que está más o menos bien” a “con esta prueba lo puedo publicar”.

Tres fallos que cometí yo

Lo escribo con honestidad. Antes de empezar a usar el brief, yo repetía siempre los mismos fallos.

El primero fue no escribir “qué no toca”. Solo quería que arreglara el README, pero Claude Code, por amabilidad, me “ordenó” también package.json y el build dejó de pasar. Con solo añadir las tres líneas Qué no toca: package-lock.json, configuración de despliegue, esto no volvió a ocurrir.

El segundo fue dejar la verificación en “si funciona, vale”. Como no había decidido qué significaba “funciona”, cada vez me tocaba seguir el diff entero con la vista. Cuando lo pasé a un comando concreto, Verificación: npm run build pasa / el diff es solo del README, la comprobación pasó a durar diez segundos.

El tercero fue poner tres siguientes pasos. Cuando al final del artículo pegaba el material, el curso y la consultoría a la vez, la reacción del lector se difuminaba. Si lo estrechas a uno solo según el estado del lector, al final ese uno sí que se clica. Qué escribir en cada sitio conviene dejarlo como norma del proyecto en cómo escribir tu CLAUDE.md, y así no te desvías cada vez.

Preguntas frecuentes

P. ¿No es un rollo escribir estos 9 campos cada vez? Solo las primeras veces. Si creas una plantilla y la guardas como first-task-brief.md, a partir de ahí solo cambias tres o cuatro líneas. El tiempo de escribirlo es mucho menor que el de releer un diff descontrolado.

P. ¿Hace falta brief incluso para tareas sencillas? Para “corregir una errata en un archivo” basta con un encargo de palabra. El brief brilla en trabajos que pueden tocar varios archivos, o que rozan producción, gasto o borrados. Ante la duda, escríbelo: no pierdes nada.

P. ¿Debería usar los nombres de campo en inglés (Goal, May edit, etc.)? Si en equipo vais a poner los logs uno al lado de otro para compararlos, las claves en inglés vienen bien por uniformidad. Si lo usas tú solo, con español basta. Claude Code entiende ambos. Lo importante no es el idioma, sino que no falte ningún campo.

P. ¿Sirve también para quien no programa? Sí. En la redacción de artículos o en ordenar documentación, la idea de “qué puede leer, qué puede editar, qué no toca” es la misma. La puerta de entrada para quien no es ingeniero la reuní en Claude Code para quien no es ingeniero.

P. ¿Y si Claude Code ignora el brief y toca algo fuera de alcance? Lo básico es pedir “antes de nada, devuélveme el plan y la verificación” y pararlo antes de que mueva un dedo. Si aun así se pasa, lo más probable es que tu “qué no toca” no sea lo bastante concreto. Si especificas hasta nombres de carpetas y archivos, funciona mucho mejor.

Lo que comprobé al probarlo de verdad

Lo más claro fue probar este brief con la tarea pequeña de ajustar el README a package.json. Al escribir de antemano Qué puede editar: solo README.md, el impulso de Claude Code de estirar la mano hacia package-lock o los archivos de configuración se cortó en la fase del plan, antes de ejecutar. Lo grande fue que el trabajo de releer el diff simplemente desapareció.

También funcionó meter dos cosas en Verificación: npm run build y git diff. El juicio final dejó de ser “por las vibras parece bien” y pasó a una afirmación clara: “el build está en verde, el diff es solo del README, así que se publica”. En cambio, la vez que dejé Siguiente paso en blanco, hasta yo dudé “¿qué iba a recomendar ahora?” y el enlace del final del artículo quedó difuso.

Lo que entendí al final es esto: el valor no está en darle a Claude Code mucha libertad. Recortar la primera tarea hasta hacerla pequeña, y dejar el éxito, el fallo y el siguiente paso visibles a tus propios ojos. Eso es lo más rápido. La molestia de escribir una hoja de límites no es nada comparada con la molestia de releer después un diff descontrolado.

Si quieres afinar más el mecanismo exterior, revisa el comportamiento de los permisos en la documentación oficial de Claude Code de Anthropic: así queda claro el reparto de papeles entre el brief y la configuración. Y si quieres meter Claude Code en el trabajo de tu empresa y ordenar también las reglas de uso, en formación y consultoría podemos crear juntos, desde cero, el formato de brief adaptado a vuestras tareas reales.