Cómo convertir una nota de Obsidian en un brief que Claude Code sí entiende

La semana pasada dejé en Obsidian una nota de unas 2000 palabras y, al día siguiente, le pedí a Claude Code: “arregla ese botón del checkout”.

Lo que recibí fue el arreglo del botón, sí, pero también un ajuste del margen del header, un reordenamiento de los enlaces del footer y, de paso, un diff en tres archivos para “ordenar” la convención de nombres del CSS. No pedí nada de eso. ¿Por qué pasó? Porque pegué la nota entera. Hasta un comentario al aire de tres días antes (“esto también me chirría”) se leyó con el mismo peso que la tarea de hoy.

La nota no era el problema. El problema era yo, que creí que una nota se podía “entregar tal cual”. Una nota larga sirve para registrar, no para dar instrucciones. Hoy escribo el formato que cierra ese hueco: cómo convertir una nota de Obsidian en un brief corto que Claude Code sí puede ejecutar.

Puntos clave

Si pegas la nota completa, la IA no distingue un comentario viejo de la instrucción de hoy, y amplía el trabajo a cosas que nunca pediste.
Solo pasas cuatro cosas: “hechos confirmados”, “lo decidido”, “lo que aún no se sabe” y “el siguiente paso”. A eso le sumas “zonas que no se tocan” y “la prueba de que está terminado”.
Haz la condición de fin pequeña. Un archivo, una pantalla, un comando; revisa el build y el screenshot antes de pasar al siguiente.
Tienes una plantilla de prompt y un código corto que convierte la nota en brief, listos para copiar y pegar.
A la IA le delegas “escribir, buscar, arreglar”. La persona decide “alcance, prioridad y si se publica”. Mezclar esas dos columnas es lo que provoca accidentes.

Por qué pegar todo hace que el trabajo se desborde

Claude Code se mueve rápido. Justo por eso, si la primera entrada es amplia, corre a toda velocidad en esa amplitud.

Las notas tienen capas de tiempo. El hecho de hoy (“el botón hace salto de línea a 375px”) y una impresión de hace una semana (“ahora que lo pienso, los colores se ven anticuados”) conviven como dos viñetas iguales. Una persona las separa por fecha o contexto; la IA, al recibir el bloque pegado, no sabe cuál es una instrucción viva. Resultado: por amabilidad, mete mano en todas.

Hay algo más. En la nota se mezcla “lo decidido” con “lo que aún dudo”. Si la duda también se lee como instrucción, la IA decide por su cuenta hacia un lado y avanza. Eso es lo que más asusta. Por eso, antes de entregar, la persona tiene que clasificar una sola vez.

Solo pasas cuatro cosas

El criterio para clasificar es simple: repartes el contenido en estos cuatro cajones.

Hechos: lo que de verdad confirmaste. “A 375px de ancho el botón ocupa dos líneas”, “la URL pública es correcta”: cosas con las que cualquiera estaría de acuerdo al mirar.
Decisiones: lo ya decidido. “El PDF gratuito va antes que el material de pago”: una política ya discutida que no se mueve.
Dudas: lo que aún no se sabe. “No está claro qué componente controla el margen del botón”: huecos que no quieres que la IA rellene a su antojo.
Siguiente paso: la única cosa de esta ronda. Tan concreto como “localizar el componente, aplicar el cambio mínimo de CSS y verificar en ancho de móvil”.

A esto le sumas dos cosas. Zonas que no se tocan (ejemplo: los archivos de autenticación no se tocan esta vez) y la prueba de que está terminado (ejemplo: el build pasa, screenshot en ancho de móvil). Estos seis puntos son el cuerpo del brief.

Al clasificar, lo importante es no borrar las “dudas”. Si dejas con honestidad lo que no sabes, la IA te preguntará por ahí. Al revés, si borras la duda y la escribes como si fuera un hecho, avanzará a ciegas sobre una premisa equivocada.

Qué delegas a la IA y qué decides tú

Antes de nada, traza la línea entre lo que se puede delegar y lo que la persona debe sostener. Si esto queda difuso, por mucho brief que hagas, al final se tambalea.

Etapa	Lo delega la IA	Lo decide la persona
Alcance	-	A qué archivo o pantalla limitarse
Investigación	Buscar componentes y código	La prioridad de qué buscar
Implementación	Escribir el cambio mínimo	El tope de lo que se puede cambiar
Verificación	Correr build y tests	La decisión final de si se publica

Como muestra la tabla, “buscar, escribir, ejecutar” se le da bien a la IA. En cambio, “hasta dónde llegar” y “si se publica” los sostiene la persona. Si esa línea está escrita en el brief, cuando la IA intente ampliar el alcance, se frena sola.

Plantilla de prompt para copiar y pegar

Primero seleccionas la nota tal cual y la pegas debajo de este texto. La idea es que la propia tarea de clasificar la haga la IA.

Convierte la siguiente nota de Obsidian en un brief corto para Claude Code.
La salida debe tener solo los siguientes encabezados; descarta todo lo demás.

- Hechos: solo lo confirmado
- Decisiones: políticas que ya no se mueven
- Dudas: déjalas como "desconocido", no las rellenes por tu cuenta
- Siguiente paso: la única cosa de esta ronda, de forma concreta
- Zonas que no se tocan: archivos o funciones que no se modifican esta vez
- Prueba: cómo se sabe que está terminado (build, screenshot, etc.)

Las impresiones viejas y los comentarios al aire agrúpalos aparte como
"notas de referencia" y no los mezcles con las instrucciones.

Relees el brief que sale y solo compruebas dos cosas: que ninguna duda se haya convertido en hecho, y que el siguiente paso quede reducido a uno. Si está bien, pegas eso tal cual en tu CLAUDE.md o en el comentario del issue y pides la implementación. Cómo escribir el CLAUDE.md lo detallo en claude-md-best-practices.

Código de verificación que convierte la nota en brief

Antes del trabajo manual, dejo un código pequeño para que el cuerpo se aprenda la estructura. Corre en Node.js. Solo guarda la nota repartida en los seis puntos de arriba y la arma en un único brief para entregar a Claude Code.

// Guarda la nota repartida en "hechos, decisiones, dudas, siguiente paso"
const note = {
  title: "El botón del checkout salta de línea en móvil",
  facts: ["A 375px el botón ocupa dos líneas", "La URL pública es correcta"],
  decision: "El PDF gratuito va antes que el material de pago",
  unknowns: ["No está claro qué componente controla el margen del botón"],
  nextAction: "Localizar el componente, aplicar el CSS mínimo y verificar en ancho de móvil",
  doNotTouch: ["Los archivos de autenticación"],
  proof: ["El build pasa", "Screenshot a 375px de ancho"],
};

// Arma los seis puntos en un único texto de brief
function toBrief(item) {
  return [
    `Objetivo: ${item.nextAction}`,
    `Hechos: ${item.facts.join(" / ")}`,
    `Decisión: ${item.decision}`,
    `Dudas (no rellenar por tu cuenta): ${item.unknowns.join(" / ")}`,
    `Zonas que no se tocan: ${item.doNotTouch.join(" / ")}`,
    `Prueba: ${item.proof.join(" / ")}`,
  ].join("\n");
}

// Portero que revisa por máquina los huecos de la clasificación
function checkBrief(item) {
  const missing = [];
  if (item.facts.length === 0) missing.push("hechos");
  if (item.unknowns.length === 0) missing.push("dudas");
  if (!item.nextAction) missing.push("siguiente paso");
  if (missing.length) {
    throw new Error(`Falta clasificar: ${missing.join(", ")}`);
  }
  return true;
}

checkBrief(note);
console.log(toBrief(note));

checkBrief parece poca cosa, pero es la pieza clave. Si intentas sacar el brief con los hechos vacíos, las dudas vacías o el siguiente paso vacío, se detiene aquí. Prohibir el “lo pego y ya” desde el código reduce el accidente de que una nota descuidada llegue directa a la IA. Si pegas la salida en el comentario del issue o en una nota de handoff, podrás reutilizar el mismo criterio en la siguiente tarea. Cómo armar esa nota de handoff lo cuento en claude-code-session-handoff-template.

En qué situaciones funciona

1. Cuando pides mejorar un artículo Si sueltas “mejora este artículo”, la IA tiende a reescribir todo el cuerpo. La solución: en el brief escribe “te paso solo la intención de búsqueda y la política de CTA” y “prohibido reescribir el cuerpo entero”. Repartes así: hechos = los encabezados actuales, decisión = la política de los enlaces, dudas = el párrafo flojo, siguiente paso = arreglar solo un encabezado. El diff queda pequeño y revertir toma un instante. La configuración de la integración con Obsidian la resumí en claude-code-obsidian-integration.

2. Cuando arreglas un bug El truco es separar el hecho reproducido de la causa que aún no conoces. “A 375px el botón salta de línea” es un hecho; “qué componente controla el margen” es una duda. Si los mezclas y escribes “seguro la causa está en el CSS”, la IA empieza a arreglar con una corazonada equivocada. Si entregas la duda como duda, la IA investigará eso primero.

3. Cuando te consultan sobre una implementación Las notas de negocio del cliente no se las muestras tal cual: las repartes en “lo que se toca esta vez”, “lo que jamás se toca” y “lo que se confirma la próxima vez”. No dejes que toque por su cuenta datos de producción o cobros sin verificar. Con solo escribir esa línea en el brief, puedes compartir pantalla con tranquilidad durante la consulta.

Fallos típicos y cómo corregirlos

Mis primeras metidas de pata caben casi todas en estos tres.

La primera fue pegar el vault entero. Decisiones viejas y restricciones actuales se mezclaron, y la IA dejó de saber a cuál creer. La corrección es simple: antes de pegar, clasifica en los seis puntos de arriba. La impresión de hace tres días se aísla en “notas de referencia”.

La segunda fue pasar solo la decisión. Escribí únicamente “el PDF va delante”, y la IA, al no saber por qué, hizo lo contrario en otra parte. Si dejas el hecho y la razón juntos, la decisión se puede aplicar a otros casos.

La tercera fue hacer la condición de fin demasiado grande. Si pides “deja todo ordenado”, la IA amplía el alcance por amabilidad. Limítate a un archivo, una pantalla, un comando, y mira el build y el screenshot antes de seguir. Solo con eso reduces el tiempo de revertir sin perder velocidad. Para afinar el prompt, mira también claude-code-prompt-engineering-advanced.

Preguntas frecuentes

P. ¿No es más trabajo hacer un brief que pegar la nota completa? Las primeras veces lo sientes así. Pero el tiempo de releer y revertir un diff que se desbordó por soltarlo todo pesa más a la larga. Clasificar, con práctica, te toma un minuto.

P. ¿Puedo dejar que la IA también haga la clasificación? Sí. La plantilla de prompt de arriba es justo ese uso. Eso sí, el brief que salga lo lee una persona una vez, solo para comprobar que ninguna duda se haya convertido en hecho.

P. ¿En qué se diferencian CLAUDE.md y el brief? CLAUDE.md es el lugar para reglas que no cambian en todo el proyecto; el brief es el encargo de una sola ronda de trabajo. Si una misma “decisión” del brief aparece una y otra vez, esa es la señal para ascenderla a CLAUDE.md.

P. ¿Sirve aunque no use Obsidian? Sí. Funciona con Notion o con una nota de texto plano. Lo importante no es la herramienta, sino la forma de pensar: separar hechos, decisiones, dudas y siguiente paso.

P. ¿Hasta dónde delego a la IA y desde dónde decido yo? “Buscar, escribir, ejecutar” lo puedes delegar tranquilo. “Hasta dónde ampliar el alcance” y “si se publica” los sostiene la persona. El truco es dejar esa línea escrita en el brief. Las bases de cómo delegar a la IA las explico en claude-code-for-non-engineers.

Lo que comprobé al probarlo de verdad

Después del “accidente de los tres archivos que no pedí” del principio, me obligué a clasificar siempre en los seis puntos antes de pegar la nota.

Probé de nuevo el mismo arreglo del botón del checkout, esta vez en forma de brief. El diff fue un archivo, unas pocas líneas de CSS. Ni el header ni el footer: nada de lo que no pedí se tocó. Que checkBrief me detuviera una vez por intentar sacar el brief con las dudas vacías también ayudó: añadí “qué componente controla el margen” antes de entregar, y la IA buscó ese componente primero.

Comprobé dos cosas. Que “si dejas las dudas, la IA no las rellena por su cuenta sino que las investiga”. Y que “si reduces el siguiente paso a uno, el diff queda pequeño y es fácil revertir”. Mi sensación actual es que, más que buscar el prompt perfecto, el minuto de clasificación antes de entregar es, al final, lo más rápido.

Cuando ya domines la clasificación de notas y quieras hacer girar el mismo formato en todo el equipo, tengo preparada una formación y consultoría donde diseñamos juntos la manera de implementarlo.

Las condiciones previas oficiales las puedes confirmar en Anthropic Claude Code getting started.