Brand layer (capa de marca)
Brief del run (ejecución)
Output (resultado) consistente
01
Los tres tipos de archivo .md
Un archivo .md (Markdown) es un archivo de texto con formato ligero. La confusión viene
de que todos tienen la misma extensión. La diferencia no está en el formato, sino en quién los
lee y para qué. Hay tres usos completamente distintos y es crítico no mezclarlos.
Para humanos
README.md
El brochure del proyecto. Lo lee una persona cuando abre el repositorio
por primera vez. No lo lee la IA, no consume tokens. Existe para que
no tengas que explicar el proyecto desde cero cada vez que alguien
nuevo lo toca.
- Qué hace este proyecto y cuál es su objetivo
- Cómo se usa, qué va en cada carpeta
- Quién lo creó y cómo contribuir
Instrucciones para la IA
CLAUDE.md
El briefing del agente. Claude Code lo lee automáticamente al inicio
de cada sesión, sin que tengas que mencionarlo ni pegarlo. Si no existe,
Claude empieza a explorar el proyecto a ciegas sin contexto ni reglas.
- Reglas específicas de este proyecto
- Qué carpetas existen y para qué
- Orden en que debe cargar el contexto
- Lo que NO debe modificar jamás
Para lo que definas
mi-workflow.md
Un archivo .md con nombre libre. Su función depende de lo que pongas
ahí y de quién lo recibe. Puede ser contexto para la IA si lo adjuntas
al chat, o documentación interna si lo compartes con tu equipo.
- Guías de proceso o workflow (flujo de trabajo)
- Templates (plantillas) de contenido
- Contexto manual para la IA
- Notas de operación internas
La regla de oro
README.md y CLAUDE.md tienen nombres con convención fija.
Las herramientas los buscan por ese nombre exacto de forma automática.
Un archivo llamado brand-voice.md puede contener lo mismo que un CLAUDE.md
si lo adjuntas manualmente, pero no se cargará automático. El nombre importa.
CLAUDE.md como contexto persistente
En Claude Code, el CLAUDE.md funciona como memoria del proyecto entre sesiones.
Cada vez que abres el proyecto, Claude lo lee primero. Esto significa que no tienes
que re-explicar el contexto, las reglas ni la arquitectura en cada sesión. Es la diferencia
entre un colaborador que recuerda todo versus uno que empieza desde cero cada día.
02
Workflow (flujo de trabajo) vs Agent (agente)
Esta es la distinción que más confunde porque ambos hacen cosas con IA.
La diferencia fundamental es una sola pregunta: quién decide el siguiente paso.
La respuesta lo cambia todo en términos de control, previsibilidad y auditabilidad.
Workflow: tú defines el camino
Input (entrada)
Brief o contexto del run (ejecución)
↓
Paso 1: definido por ti
Prompt fijo, skill (habilidad) asignado
↓
Paso 2: definido por ti
Estructura determinada
↓
Paso 3: definido por ti
Output (resultado) esperado especificado
↓
Output (resultado)
Predecible entre runs (ejecuciones)
Quién decide los pasos: Tú, antes de correrlo.
La IA
ejecuta dentro de los carriles que trazaste.
Agent (agente): la IA decide el camino
Goal (objetivo)
Instrucción general del objetivo
↓
IA decide cómo abordar
Interpreta el goal (objetivo)
↓
IA ejecuta en loop (ciclo)
¿Qué herramienta uso ahora?
¿Qué hago con el resultado?
¿Necesito buscar más info?
↓
Output (resultado)
Variable entre runs (ejecuciones)
Quién decide los pasos: La IA, en tiempo real.
Ella
decide qué hacer, con qué tool (herramienta), si iterar.
Workflow: tú defines
Agent: la IA ejecuta
Qué es
Secuencia de pasos que diseñaste antes de correr. La IA ejecuta
instrucciones dentro de carriles fijos.
Le das un objetivo general. La IA decide qué herramientas usar, en qué
orden, y si necesita iterar.
Control
Defines cada nodo, cada prompt, cada transición. Nada ocurre sin que lo
hayas previsto.
La IA toma decisiones autónomamente en tiempo real. No ves el proceso
hasta que termina.
Previsibilidad
Alta. El run 1 y el run 47 producen la misma estructura de output.
Variable. Puede ser excelente o inconsistente según cómo interpretó el
goal (objetivo).
Cómo luce en Antigravity
Un archivo .md con pasos numerados, prerrequisitos y skills (habilidades) asignados. No
es un canvas visual: es texto estructurado que el agente lee y sigue.
Una sesión donde el agente reporta lo que va haciendo: "voy a leer este
archivo... encontré el problema... voy a corregirlo". Es un stream (flujo) de acciones.
Auditoría
Fácil. Cada nodo es inspeccionable, reproducible y modificable de forma
aislada.
Difícil. El razonamiento del agente no siempre es transparente ni
exactamente reproducible.
Fragilidad
Frágil ante lo inesperado. Si algo sale diferente a lo previsto, puede
romper el flujo.
Robusto ante variaciones. Se adapta a inputs (entradas) inesperados porque decide en
tiempo real.
.agent > workflows > ejemplo-workflow.md
# Workflow: [Nombre del entregable]
Descripción breve de lo que genera este workflow.
## Prerrequisitos
- Dato o contexto que necesita el agente antes de
empezar
- Objetivo principal del run (ejecución)
## Pasos
### 1. Nombre del primer paso
Usa el skill `nombre-del-skill` - sección "Nombre".
- Instrucción específica a ejecutar
- Pregunta o decisión que debe resolver
### 2. Nombre del segundo paso
Usa el skill `otro-skill`.
- Qué seleccionar o generar en este paso
- Criterio de decisión
## Output (resultado) esperado
- Formato: [descripción del formato final]
- Listo para: [uso final del entregable]
El workflow .md en Antigravity
El archivo .md del workflow es el guion. El agente en ejecución es quien lo
interpreta.
El workflow define qué pasos ejecutar y en qué orden, con qué skill (habilidad), y qué se espera al final.
El agente decide cómo ejecuta cada paso: qué busca, cómo interpreta el resultado, cuándo considera
que un paso está completo. El guion es tuyo. La interpretación es de la IA.
03
El espectro y el "hand-held agent" (agente guiado)
Workflow y Agent no son dos opciones binarias. Son los extremos de un espectro
con dos dimensiones independientes: quién define la secuencia de pasos
y quién elige las herramientas. Combinando esas dos dimensiones obtienes
cuatro posiciones en el espectro, desde control total hasta autonomía total.
Comprender / Definir
Ejecutar / Autonomía
Workflow puro
Tú defines la secuencia de pasos
y las herramientas disponibles.
Máxima previsibilidad.
Nada ocurre fuera de lo que definiste.
Agentic workflow (flujo agéntico)
Tú fijas la secuencia y las tools (herramientas) disponibles.
La IA decide cómo ejecuta cada paso
dentro del sandbox (entorno controlado) que construiste.
Punto óptimo para entregables
Balance entre control y flexibilidad
Tool freedom (libertad de herramientas)
Tú defines los pasos pero la IA
elige las herramientas para cada uno.
Raro en la práctica.
Agent (agente) puro
La IA decide todo: secuencia, herramientas,
criterio de éxito, cuándo detenerse.
Máxima autonomía, mínimo control.
Dimensión 1
Secuencia de pasos
Si tú defines la secuencia, sabes exactamente qué va a pasar y en qué orden.
Si la IA la define, ella decide qué hacer después de cada resultado,
con la flexibilidad de cambiar el camino según lo que encuentre.
Dimensión 2
Herramientas disponibles
Si tú defines el menú de tools (herramientas), la IA no puede improvisar ni usar
nada fuera de lo que habilitaste. Si la IA elige libremente,
puede adaptarse mejor pero también puede sorprenderte.
Qué es exactamente el "hand-held agent" (agente guiado)
Cuando defines el workflow y le indicas qué skills (habilidades) usar, estás en
agentic workflow (flujo agéntico). Los dos dials están fijados por ti:
la secuencia de pasos es tuya, y el menú de herramientas es tuyo.
La IA opera con agencia real pero dentro del sandbox (entorno controlado) que construiste.
Puede decidir cómo ejecuta, pero no puede improvisar herramientas
nuevas ni salirse del guion.
04
Output determinista
Cuando produces entregables de cliente, no hay opcionalidad. Una inconsistencia
en tono, formato o menciones tiene costo real: retrabajo, tiempo perdido y
percepción de falta de profesionalismo. El error común es pensar que el
problema es el prompt. El problema es dónde pones la responsabilidad
de la interpretación.
El problema raíz
Cuando le dices a la IA "escribe en tono profesional y menciona X", le estás
delegando la interpretación de esas instrucciones. Cada vez que corre,
interpreta distinto. Eso produce variación. Más instrucciones en el prompt no
equivalen a más determinismo: equivalen a más superficie para que la IA interprete
de formas distintas cada vez.
La solución es mover la responsabilidad de la IA a la estructura.
Hay tres mecanismos que, combinados, eliminan la variación.
Mecanismo 01
Template (plantilla) con slots (espacios)
En lugar de decirle cómo debe ser el output (resultado), dale el output con huecos.
La IA llena los slots, no inventa la estructura. El número de secciones,
el orden, el uso de negritas, si hay conclusión o no: ya está resuelto
antes de correr el workflow.
## [TÍTULO DEL ARTÍCULO]
**Categoría:** [Estrategia / Ops / Tech]
[Párrafo 1: contexto, 2-3 oraciones]
[Párrafo 2: insight principal]
**Conclusión:** [una oración con verbo]
Mecanismo 02
Constraints (restricciones) separados
Tono, menciones y límites van aparte del template, como checklist
explícito. Nunca mezclados en el prompt principal. La IA los procesa
diferente cuando están aislados como lista que cuando están enterrados
en un párrafo de instrucciones.
RESTRICCIONES (no negociables):
- Mencionar "mi-marca" en parrafo 1
- No usar "termino-prohibido"
- Tutear al lector
- Maximo 180 palabras totales
Mecanismo 03
Validation pass (paso de validación)
Un segundo llamado cuyo único trabajo es verificar el output (resultado) del primero
contra tus criterios, y devolver pass o fail (corrección) si falla.
No es retrabajo tuyo: es un nodo más en el workflow. Es el mecanismo que
más cambia el juego para entregables sin margen de error.
PASSMenciona
"mi-marca" en p1
PASSNo usa
"termino-prohibido"
FAILUsa "usted" en
parrafo 2
→ Corrigiendo parrafo 2...
Para entregables de cliente: los tres juntos
Cualquiera de los tres mecanismos solo no es suficiente. El template resuelve
estructura, los constraints (restricciones) resuelven tono y menciones, el validation pass
resuelve la variación residual. Una corrección típica cuesta
3 a 5 veces más tokens que el output original.
La estructura correcta es prevención, no corrección.
05
El mismo proceso: cómo luce en cada modo
El mismo objetivo: producir un entregable de cliente aplicando los tres mecanismos
de output determinista. La diferencia es arquitectural.
Azul = lineamientos que tú definiste.
Amarillo = decisión o punto de validación.
Rojo = ejecución de la IA.
Workflow: cada nodo lo defines tú
↓
Template (plantilla) con slots
Lineamientos: tú diseñaste la estructura
↓
Constraints (restricciones) como checklist
Lineamientos: tú escribiste las reglas
↓
Validación
Decisión: pass o fail según tus criterios
↓
Output (resultado)
Predecible, sin variación
El fail loop (ciclo de corrección): si la validación no pasa,
vuelve siempre al mismo punto fijo: el nodo de template. Determinista.
Siempre el mismo nodo, siempre los mismos criterios.
Cada nodo fue definido por ti antes de correr el workflow.
Agentic: cada nodo lo decide la IA
Input (entrada) + goal (objetivo)
Brief + instrucción general
↓
IA interpreta
Decide cómo abordar el problema
↓
IA genera
Ejecuta con su propia estructura
↓
IA auto-evalúa
Decide si el resultado es suficiente
↓
Output (resultado)
Variable entre runs (ejecuciones)
Sin punto fijo: si la IA decide reiterar,
ella decide también desde dónde y con qué criterio. No hay un nodo
invariante al que siempre volver.
Cada nodo fue decidido por la IA en tiempo real.
La distinción crítica
El workflow tiene un fail loop (ciclo de corrección) que siempre regresa al mismo punto.
El agente no tiene punto fijo al que volver: si reitera, decide también
desde dónde y con qué criterio. El template y los constraints en el workflow
no son pasos previos que la IA vio antes de empezar. Son las paredes dentro
de las cuales opera en todo momento.
La contención es la clave, no la secuencia.
06
El modelo de contención
Hay un error conceptual común al combinar workflow y agente: dibujar template
y constraints como pasos previos que ocurren antes de que la IA entre.
Eso implica que la IA podría ignorarlos una vez que empieza. El modelo correcto
es de contención: la IA opera dentro del sandbox (entorno controlado) que tú construiste.
Lectura incorrecta: secuencia lineal
Implica que template y constraints son pasos que ocurren antes de la IA.
Una vez que la IA pasa esos nodos, podría no respetarlos.
Lectura correcta: contención
Tu sandbox (entorno controlado)
Template + Constraints +
Validación
IA opera aquí dentro
Interpreta el brief
Llena los slots del template
Respeta los constraints
Pasa la validación
Por qué funciona: la IA no puede generar nada que no
quepa dentro del sandbox. Las paredes son permanentes, no un paso que ya pasó.
Cómo se implementa
El template y los constraints van dentro del prompt que recibe la IA, no antes de
él.
En cada paso del workflow, esos elementos están presentes en el contexto de ejecución.
La IA no los recuerda de antes: los tiene frente a ella en cada momento.
07
La jerarquía de contexto
Con múltiples formatos de contenido, cada uno con su template y constraints (restricciones), necesitas
una organización que cumpla dos objetivos simultáneos: maximizar la consistencia
de los elementos compartidos (tono, voz, restricciones globales) y
maximizar el uso de tokens cargando solo el contexto necesario por run (ejecución).
El principio que resuelve ambos: lo que es común sube, lo que es específico baja.
Capa 0 · Global · Siempre se carga
00-brand/
Son los lineamientos que gobiernan todo lo que produce la marca: contenido, web y app por igual.
Si un constraint aplica a más de un formato, vive aquí y nunca se duplica abajo.
Un botón de la app tiene el mismo tono que un post de LinkedIn.
brand-voice.md
product-guide.md
use-cases.md
global-constraints.md
glossary.md
▼ Ver ejemplo de estructura de carpetas
📁 00-brand/
📄 brand-voice.md
📄 product-guide.md
📄 use-cases.md
📄 global-constraints.md
📄 glossary.md
📄 visual-identity.md
Capa 1 · Por dominio · Solo el activo
01-content/ · 02-web/ ·
03-app/
En cualquier ejecución, solo se carga el dominio activo y dentro de ese dominio
solo el módulo o formato que se está trabajando. Si corres un newsletter,
no cargas el template de TikTok. Si trabajas en billing, no cargas auth ni dashboard.
newsletter.md
design-system.md
architecture.md
modules/billing.md
validation-rules.md
▼ Ver ejemplo de estructura de carpetas
📁 01-content/
📁 formats/
📄 newsletter.md
📄 linkedin-post.md
📄 blog-article.md
📄 tiktok-script.md
📄 validation-rules.md
📁 02-web/
📄 design-system.md
📄 seo-rules.md
📁 pages/
📄 home.md · landing-a.md
📁 03-app/
📄 architecture.md
📁 modules/
📄 auth.md · billing.md
📁 sprints/
📄 sprint-01.md
Capa 2 · Por ejecución · Solo las variables del run (ejecución)
04-runs/
Solo lo que cambia entre runs: tema de la semana, datos del cliente,
requerimiento específico del sprint (iteración). Todo lo invariante ya está resuelto arriba.
Un brief bien estructurado tiene pocas líneas.
brief-cliente-s12.md
brief-sprint-02.md
▼ Ver ejemplo de estructura de carpetas
📁 04-runs/
📁 content/
📄 brief-s12.md · brief-s13.md
📁 web/
📄 brief-landing-launch.md
📁 app/
📄 brief-sprint-01.md
Raíz del proyecto · Siempre presentes
CLAUDE.md + README.md
CLAUDE.md le dice al agente la lógica de carga según qué tipo de run (ejecución) se ejecuta.
README.md le dice a un humano cómo opera el sistema. Ambos en la raíz.
Sube si es compartido
Si un constraint aplica a más de un formato, vive en global-constraints.md. Duplicarlo abajo crea
divergencia silenciosa y acumulativa.
Baja si es específico
El template de newsletter, su largo, sus secciones: eso no contamina el brand layer. Cada capa
tiene su scope exacto.
El brief es mínimo
Solo las variables que cambian por run (ejecución). Todo lo invariante ya está resuelto arriba. El brief no
repite contexto que ya existe.
08
Optimización de tokens
La frustración con los límites de tokens no viene de los límites en sí mismos.
Viene de trabajar sin estructura. Sin estructura, cada sesión carga todo el
contexto desde cero, repite información que ya existía, y gasta presupuesto en
repetición en lugar de en trabajo nuevo. La jerarquía resuelve exactamente eso.
Sin estructura: sesión libre
Tokens en trabajo real
30%
Con estructura jerárquica
Tokens en trabajo real
75%
El system prompt (instrucción del sistema) no cuenta igual
El brand layer (capa de marca) en system prompt se carga una vez por sesión, no por mensaje.
En una sesión de 10 outputs, pagas ese contexto 1 vez, no 10.
La corrección es el mayor desperdicio
Una corrección típica cuesta entre 3 y 5 veces más tokens que el output original.
Estructura correcta es prevención pura.
Los sprints (iteraciones) como unidad de medida
El límite de tokens se convierte en una unidad de sprint. Diseñas el scope (alcance) para que quepa,
terminas con algo funcional y documentado.
09
Estructura completa: mi-marca
Content system + web/landing + web app. Tres ramas, una raíz compartida.
Cada rama tiene su propia capa de reglas de operación, pero todas heredan
del mismo brand system (sistema de marca).
📁 mi-marca/
│ 📄 CLAUDE.mdlee la IAmapa del proyecto + lógica de carga por tipo de run (ejecución)
│ 📄 README.mdlee humanoqué es, cómo se usa, qué hay en cada carpeta
│ 📁 00-brand/Capa 0 · global · siempre
│ │ brand-voice.mdtono, voz, personalidad de
marca
│ │ visual-identity.mdcolores, tipografía, uso de
logo
│ │ product-guide.mdqué ofrece la marca, qué no
│ │ global-constraints.mdlo que NUNCA se hace en ningún
formato
│ │ use-cases.md glossary.md
│ 📁 01-content/Capa 1 · content
│ │ formats/ → newsletter · linkedin · blog · tiktok-script · caso-exito ·
···
│ │ validation-rules.mdcriterios de QA por
formato
│ 📁 02-web/Capa 1 · web
│ │ design-system.md seo-rules.md copy-guidelines.md
│ │ pages/ → home · landing-a · landing-b · about · ···
│ 📁 03-app/Capa 1 · app
│ │ architecture.md ux-rules.md data-models.md
│ │ modules/ → auth · dashboard · billing · notifications · ···
│ │ sprints/ → sprint-01.md · sprint-02.md · ···
│ 📁 04-runs/Capa 2 · ejecución
│ │ content/ → brief-s12.md · brief-s13.md
│ │ web/ → brief-landing-launch.md · brief-redesign-hero.md
│ │ app/ → brief-sprint-01.md · brief-sprint-02.md
│ 📁 05-outputs/resultados por run
Lógica de carga en cada ejecución
Content run
00-brand/ completo
+ formats/newsletter.md
+ runs/content/brief.md
Los otros 9 formatos no existen en este contexto.
Web sprint
00-brand/ completo
+ 02-web/design-system.md
+ pages/landing-a.md
+ runs/web/brief.md
Las otras páginas no se cargan.
App sprint
00-brand/ completo
+ 03-app/architecture.md
+ modules/billing.md
+ runs/app/brief.md
auth y dashboard no se cargan.
Por qué 00-brand/ está en toda ejecución
El brand system (sistema de marca) no es solo para contenido: gobierna cualquier output que lleve
el nombre de la marca. Si vive separado por rama, cada rama empieza a interpretar
el tono de forma distinta. La divergencia entre ramas es silenciosa y acumulativa:
no la ves hasta que ya es un problema de percepción.
Lo que el CLAUDE.md de la raíz debe decir exactamente
No solo la descripción del proyecto. Debe incluir la lógica operativa de carga:
"antes de cualquier ejecución carga 00-brand/ completo. Luego carga solo el archivo de
formato que corresponda al run. Luego el brief. No cargues todos los formatos juntos.
Si el run es de app, carga architecture.md más solo el módulo activo."
Eso convierte la estructura de carpetas en instrucción operativa para el agente.
10
Conclusiones: por qué la estructura lo cambia todo
Cada sección de esta guía resuelve una pieza del mismo problema: cómo
hacer que la IA produzca resultados consistentes, auditables y eficientes.
No se trata de un solo truco ni de un prompt mágico. Se trata de un sistema
donde cada decisión arquitectural refuerza las demás.
🏗️
Estructura elimina ambigüedad
Sin estructura, cada sesión empieza desde cero.
Con jerarquía, el contexto ya existe antes de que la IA comience.
No interpretas tú. No interpreta la IA. La estructura habla por sí sola.
🔄
Consistencia entre ejecuciones
El run 1 y el run 47 producen la misma estructura.
Templates con slots fijan el formato. Constraints fijan el tono.
El validation pass atrapa lo que se escapa.
🛡️
Control y resiliencia
La contención no es un paso previo: es una pared permanente.
La IA opera dentro del sandbox que tú construiste.
El fail loop siempre regresa al mismo punto fijo.
⚡
Eficiencia de tokens
Sin estructura: 30% de tokens en trabajo real.
Con estructura jerárquica: 75%.
La diferencia no es teórica — es medible en cada sesión, en cada factura.
La IA no necesita mejores prompts.
Necesita mejor arquitectura alrededor.
Estructura primero. Instrucciones después. Resultados siempre.