No és només format

Quan sents parlar de Markdown, el més habitual és pensar en documentació de GitHub, fitxers README o textos a Discord. Una cosa tècnica, pròpia de desenvolupadors.

Per a mi, ha acabat sent una altra cosa: la manera com em comunico amb els meus agents d’IA cada dia.

No parlo d’escriure documentació bonica. Parlo d’utilitzar Markdown com un llenguatge per explicar a un agent què vull que faci, amb quin context, en quin ordre i amb quins límits.

Per què Markdown i no text pla

Pots escriure a un agent d’IA en text pla. Funciona per a coses senzilles. Però quan la tasca té diverses parts —context, instruccions, exemples, restriccions— el text pla es torna difícil de seguir.

Un missatge llarg sense estructura és complicat de llegir per a una persona i també ho és per a una IA. Els models no processen de la mateixa manera un bloc de text que un document amb seccions, llistes i jerarquia.

Markdown aporta estructura sense complicacions. Un encapçalament marca una secció. Una llista ordena els passos. Un bloc de codi separa un exemple de la resta. I tot això ajuda el model a entendre què és context, què és una instrucció i què és un límit.

El que utilitzo cada dia

Els meus agents es guien per documents en Markdown. Els skills són fitxers .md amb una estructura fixa: què són, quan s’utilitzen, quins passos cal seguir i quins errors s’han d’evitar. Els templates són Markdown amb variables. Les instruccions recurrents les guardo com a notes en Markdown.

No ho vaig fer per disseny, sinó per necessitat. Quan vaig començar a delegar tasques als agents, les instruccions en text pla generaven més errors, més anades i tornades i més correccions. Quan vaig passar aquestes mateixes instruccions a Markdown, el resultat va millorar notablement.

Llistes, blocs i ordre

Quan dono instruccions a un agent, les escric en llistes numerades. No perquè m’agradi el format, sinó perquè una llista imposa un ordre. El pas 1 va abans que el pas 2. Si l’agent segueix aquesta llista, no es deixa res pel camí. Els blocs de codi serveixen per donar exemples concrets. Si vull que un agent actualitzi un projecte a través de l’API, li escric exactament el curl que ha d’executar, dins d’un bloc de codi i com a part de la instrucció. No li dic «fes un curl a aquest endpoint»; li escric el curl complet. La diferència en el resultat és clara.

I els encapçalaments separen seccions: context, instruccions, restriccions. Si tot està en un sol paràgraf, el model pot barrejar les instruccions amb el context. Si cada cosa té la seva secció, les manté separades.

El frontmatter com a context

Una cosa que he après treballant amb Astro i amb el portfolio és que el frontmatter d’un fitxer Markdown —aquella capçalera entre guions amb parelles clau-valor— és una manera molt eficient de proporcionar context. Un fitxer Markdown amb frontmatter no és només text. És text amb metadades: idioma, data, categoria, estat. I aquestes metadades indiquen a l’agent, abans de llegir res, què té entre mans.

És com la capçalera d’un correu: abans de llegir el missatge ja saps de qui ve, quan ha arribat i de quin assumpte tracta. Quan un agent llegeix el frontmatter d’un document, ja té context abans de començar.

El que no és

Escriure en Markdown per a agents d’IA no és el mateix que documentar codi. No busca ser bonic ni exhaustiu. Busca ser clar i funcional.

No cal explicar-ho tot. Cal donar la informació suficient perquè l’agent sàpiga què ha de fer, sense informació innecessària. Un document de 200 línies que repeteix el mateix en tres llocs és pitjor que un de 50 línies que va directe al gra.

Quan n’hi ha prou amb text pla

No tot necessita Markdown. Si la tasca és senzilla —«revisa aquest text i digues-me què et sembla» o «comprova que aquest servidor respon»—, un missatge clar en text pla funciona bé.

El problema apareix quan la complexitat creix i continuo escrivint de la mateixa manera. Si la tasca té diverses parts, depèn d’un context específic o té restriccions importants, el text pla es queda curt. És aquí on l’estructura de Markdown marca la diferència.

No es tracta d’utilitzar Markdown sempre. Es tracta de saber quan el text pla ja no és suficient.

El que m’ha ensenyat

Aprendre a escriure en Markdown m’ha ensenyat a pensar d’una manera més estructurada. Quan separes el context de les instruccions, ordenes els passos i distingeixes el que és important del que és accessori, no només ho fas millor per a la IA: també ho fas millor per a tu.

Ara, quan escric un correu, una instrucció per a un company o un document tècnic, penso en seccions, ordre i claredat. No perquè Markdown m’ho imposi, sinó perquè he comprovat que, quan una cosa està ben estructurada, tothom l’entén millor.