Brief productivo para Claude Code: qué debe dar primero un principiante

Por qué importa este flujo

Los principiantes no suelen fallar por escribir prompts poco elegantes. Fallan porque faltan objetivo, archivos protegidos, enlaces de ingresos y criterio de terminado. Un brief corto reduce suposiciones y mantiene pequeño el primer cambio.

Conviene leerlo junto con: runbook de primera tarea, mantenimiento de prompts, plantilla CLAUDE.md.

Flujo práctico

Escribe el objetivo en una frase, luego archivo objetivo, lector y razón de negocio. Añade lo que no se toca, qué enlaces Gumroad deben seguir vivos y el comando de prueba.

Kit mínimo para copiar y pegar

# Claude Code task brief

## Goal
Change one clear thing:

## Context
- user or reader:
- current file/page:
- business reason:

## Constraints
- do not touch:
- keep these links working:
- proof command:

## Definition of done
- small diff
- public URL checked
- CTA path still works
- handoff note written

Use this brief before editing.
Ask up to three clarifying questions only if the goal, protected files, or proof command is missing.
Then propose the smallest safe patch and the verification receipt.

rg --files | Select-Object -First 80
git diff --name-only
cd site
npm.cmd run build

Ejemplo de un buen brief de petición

Un buen brief no solo dice qué cambiar. También explica por qué se cambia y qué superficie debe quedar intacta. Para editar un artículo, una petición útil sería:

Mejora solo la introducción y la zona de CTA de site/src/content/blog-es/claude-code-productive-prompt-brief.mdx. El lector es un desarrollador independiente que está probando Claude Code por primera vez. El objetivo es que entienda cuándo le basta el PDF gratuito y cuándo tiene sentido pasar a Prompt Templates, Setup Guide o una consultoría. No cambies frontmatter, slug, enlaces Gumroad existentes, enlaces internos ni bloques de código. Después ejecuta node scripts/check-updated-article-quality.mjs y confirma que no quedan errores de este slug.

Funciona porque limita el trabajo. “Solo la introducción y la zona de CTA” evita que Claude Code reescriba todo el artículo. El lector y el objetivo de negocio orientan el tono: no se trata de adornar frases, sino de ayudar a una persona concreta a elegir el siguiente paso.

También protege elementos críticos. El frontmatter controla fecha, categoría y heroImage; los enlaces Gumroad sostienen la ruta de ingresos; los enlaces internos mantienen la navegación; los bloques de código son material que el lector copia. Si esos límites están escritos desde el inicio, la revisión posterior es mucho más simple.

Ejemplo de una mala petición

Una mala petición suele sonar razonable, pero deja demasiado abierto:

Mejora este artículo para SEO y conversión.

SEO puede significar título, keywords, enlaces internos, description o expansión del cuerpo. Conversión puede significar un CTA más fuerte, más enlaces a Gumroad, una comparación o una nota de experiencia personal. Si no hay límites, Claude Code puede generar un diff grande que cuesta revisar y que quizá toca zonas que no debían cambiar.

Otro caso débil es:

Hazlo más fácil para principiantes y dime cuando termines.

La intención es buena, pero no hay forma clara de validar el resultado. Una versión mejor pediría incluir un buen brief, una mala petición, una plantilla para principiantes y una ruta natural hacia PDF gratuito, materiales de Gumroad y consultoría. Además, debería nombrar el comando de prueba que cerrará el trabajo.

Plantilla inicial para principiantes

No hace falta escribir el prompt perfecto. Empieza con cinco líneas sencillas:

Cambio: una sola cosa que quieres modificar
Objetivo: archivo, URL, comando o pantalla afectada
Lector o usuario: quién se beneficia del cambio
Protecciones: archivos, enlaces, comportamientos o reglas que no se tocan
Prueba: comando o resultado que confirma que está terminado

Si quieres mejorar el CTA de una página de producto, el cambio debe ser el texto y la posición del CTA, no toda la página. El objetivo es el archivo MDX de esa página. El lector es alguien que ya entendió el PDF gratuito pero aún no sabe si necesita plantillas o ayuda de setup. Las protecciones son los enlaces a PDF gratuito, Prompt Templates y Setup Guide. La prueba es el build, la URL pública y el clic en los enlaces.

La plantilla es pequeña a propósito. Su función es hacer que el primer patch sea revisable, reversible y conectado a un resultado. Cuando el equipo madura, se pueden añadir reglas como mantener todas las traducciones sincronizadas, no cambiar precios sin aprobación o conservar capturas y ejemplos existentes.

Ruta natural hacia materiales y consultoría

El brief también debe ordenar la siguiente acción del lector. Si todavía duda con comandos básicos, el PDF gratuito es suficiente. Si repite el mismo tipo de petición, Prompt Templates le ahorra tiempo. Si hay despliegue de equipo, permisos, revisión editorial o enlaces de ingresos, una consultoría puede costar menos que aprender rompiendo producción.

Este orden evita que el artículo parezca una venta forzada. Primero entrega algo útil hoy. Luego ofrece material reutilizable cuando la repetición duele. Por último, abre la puerta a consultoría para escenarios donde los ejemplos generales no alcanzan. La ruta comercial sigue el nivel real de riesgo del lector.

Tres casos reales de uso

Si solo mejoras un CTA, prohíbe reescritura completa y exige verificación de URL pública.
Al editar CLAUDE.md, entrega comandos prohibidos y comando de build primero.
Al actualizar productos, protege PDF gratis, Prompt Templates y Setup Guide.

Fallos comunes y cómo evitarlos

Pedir ‘mejóralo’. Normalmente genera un diff demasiado amplio.
Omitir enlaces protegidos. La ruta de ingresos puede desaparecer sin verse mal.
No definir terminado. Claude Code puede quedarse en investigación.

Ruta hacia PDF gratis, Gumroad y consultoría

Usa el PDF gratuito antes de escribir briefs. Usa Prompt Templates para peticiones reutilizables. Usa Setup Guide si necesitas estabilizar CLAUDE.md, hooks y supuestos del proyecto.

Empieza con el PDF gratuito para dominar comandos y hábitos seguros. Pasa a Gumroad cuando el flujo se repita, y reserva consultoría cuando el despliegue, el equipo o los ingresos no se deban improvisar.

Qué verifiqué para este artículo

Separé plantilla Markdown, instrucción corta y comando de prueba. La meta es un cambio, una prueba y una revisión de la ruta de ingresos.