Context per a agents: coneixement declaratiu i procedimental
Per què l'AGENTS.md únic i gros falla sempre, i com repartir el que ha de saber un agent en dues capes que fallen de maneres diferents.
·8 min de lectura
Hi ha un moment previsible a tot projecte amb agents de codi. Comences amb un AGENTS.md de vint línies i va bé. Al cap d’un mes en té tres-centes, hi has abocat cada correcció que has hagut de fer, i l’agent ha començat a ignorar-lo. No la meitat: sencer.
OpenAI ho va descriure amb una frase que val el preu de l’article: «vam provar l’enfocament de l’AGENTS.md únic i gros. Va fallar de maneres previsibles… massa guia esdevé cap guia».
Aquest article és la primera dimensió del marc de harness engineering: el Context, el coneixement que informa l’agent abans que escrigui res.
Dues capes que fallen diferent
La distinció útil no és per format ni per fitxer. És per tipus de coneixement, i el criteri per separar-les és com es trenca cadascuna.
| Capa | Respon a | Exemples | Com falla |
|---|---|---|---|
| Declarativa | Què existeix | Esquema de la base de dades, API, estructura de carpetes, dependències | Errors factuals: importa mòduls que no hi són, crida endpoints eliminats |
| Procedimental | Com es decideix | Convencions de nom, direcció de dependències, criteri de tria de patró | Errors de criteri: codi correcte, però al lloc o amb la forma equivocats |
La diferència importa perquè el remei no és el mateix. Un error factual es corregeix donant-li el fet: l’esquema real, la llista de mòduls, la signatura de la funció. Un error de criteri no es corregeix amb més fets —n’hi pots donar mil— sinó amb una regla de decisió.
Si barreges les dues capes en un sol document, no pots diagnosticar. Veus que l’agent s’equivoca i no saps si li falta informació o li falta criteri, així que hi afegeixes text de tot tipus. I el document creix fins que deixa de fer efecte.
Context no és restricció
Un altre embolic freqüent, aquest més subtil. Context i restricció poden viure al mateix fitxer, i això fa pensar que són el mateix. No ho són, i la diferència és l’acte de parla:
- Context és descriptiu. «La nostra API és REST i retorna JSON.» Diu com són les coses.
- Restricció és prescriptiu. «Els noms de fitxer sempre en kebab-case.» Diu què s’ha de fer.
El mateix principi arquitectònic pot aparèixer a totes dues bandes: com a criteri procedimental al context, i com a regla verificable a la capa d’imposició. Això no és redundància, és governança per capes: el context informa la intenció de l’agent, la restricció verifica la seva sortida. Una sense l’altra deixa forats.
Per què el document gros deixa de funcionar
Tres mecanismes, i cap és culpa del model.
Dilució. El context és una finestra amb pressupost. Tres-centes línies de guia competeixen entre elles i amb el codi que l’agent ha de llegir per fer la feina. Quan tot és important, res destaca.
Irrellevància. El 90 % del document no té res a veure amb la tasca d’ara. L’agent que ha de tocar un endpoint no necessita les convencions de CSS, però se les llegeix igualment i li ocupen lloc.
Podridura. Un document llarg que ningú manté envelleix. Al cap de sis mesos, una part diu mentides. I aquí passa el pitjor que pot passar: un context que menteix és pitjor que no tenir-ne, perquè l’agent s’hi fia.
La forma que sí que aguanta
L’estructura que ha convergit a la pràctica —OpenAI, Thoughtworks i qualsevol que hi hagi estat prou temps hi arriben— és la mateixa: un fitxer d’entrada curt que apunta a documents específics.
AGENTS.md ← 40 línies. Principis i mapa. Res més.
docs/
├── arquitectura.md ← capes, direcció de dependències
├── dades.md ← esquema, invariants, migracions
├── api.md ← contractes, errors, versions
├── convencions.md ← noms, estructura de fitxers
└── decisions/
├── 001-per-que-no-orm.md
└── 002-cua-en-comptes-de-cron.mdL’AGENTS.md fa dues coses i prou: enuncia els principis innegociables i diu on és cada cosa. La resta es carrega quan cal.
Un AGENTS.md que funciona s’assembla a això:
# Context del projecte
API en Python + FastAPI, dades a Postgres, front en Astro.
## Innegociables
- Cap dependència nova sense justificar-ho al PR.
- Tot el que toqui diners porta proves.
- Les capes van cap avall: rutes → serveis → repositoris. Mai al revés.
## On mirar
- Arquitectura i capes → docs/arquitectura.md
- Esquema i migracions → docs/dades.md
- Contractes d'API → docs/api.md
- Per què alguna cosa és com és → docs/decisions/Quaranta línies. Es llegeixen senceres, no es dilueixen, i cada una es guanya el lloc.
El registre de decisions és la part que ningú fa
De tot el docs/, el directori que més rendeix és el de decisions, i és el que gairebé ningú manté. Un fitxer per decisió, amb tres apartats: què es va decidir, què es va descartar i per què.
El valor no és documental. És que evita el bucle més cansat que hi ha amb un agent: proposa una cosa raonable que ja vau descartar fa quatre mesos per un motiu concret, tu li dius que no, i tres sessions més tard la torna a proposar. Amb el registre escrit, no cal que t’hi barallis: el motiu és al repositori.
És exactament el mateix problema que el coneixement tàcit a qualsevol empresa. El que només és al cap d’algú no existeix per a ningú altre, i un agent és el «ningú altre» més literal que et trobaràs.
Context dinàmic: el que es carrega sol
L’evolució següent és no decidir tu què entra a la finestra. Tres mecanismes, de menys a més autònom:
| Mecanisme | Qui decideix què es carrega | Quan fer-ho servir |
|---|---|---|
| Fitxers d’instruccions | Tu, per endavant | Principis estables i curts |
| Skills i ordres pròpies | Tu, en invocar-les | Procediments repetitius amb passos fixos |
| Servidors MCP | L’agent, segons la tasca | Fets que canvien: esquemes vius, tiquets, documentació d’eines |
L’MCP —Model Context Protocol— és el que canvia més la capa declarativa. En comptes de mantenir un docs/dades.md que envelleix, l’agent consulta l’esquema real quan el necessita. El coneixement declaratiu deixa de ser una còpia i passa a ser una consulta, i el problema de la podridura desapareix per a aquesta capa.
El que no desapareix és la capa procedimental: cap servidor MCP et dirà per què vau triar cues en comptes de cron. Això s’escriu i es manté a mà.
Com saps si el teu context és bo
No et refiïs de la sensació. Hi ha dues proves barates.
La prova del company nou. Si el que has escrit no permetria a una persona que entra demà fer la feina sense preguntar-te res, tampoc en té prou un agent. És el mateix criteri que aplico a una especificació executable, i falla igual de sovint.
La prova de la correcció repetida. Porta un registre —tres línies en un fitxer— de cada cop que corregeixes l’agent. Al cap de dues setmanes, classifica: fet que li faltava o criteri que li faltava. Els primers van a la capa declarativa. Els segons, i això és el gir important, no van al context: van al linter. Si has hagut de corregir el mateix criteri tres vegades, l’has d’imposar, no explicar.
Què costa això
Manteniment real. Els documents envelleixen com el codi i amb menys senyals d’avís. La regla mínima: si un canvi de codi contradiu un document, el document es toca al mateix commit. Si no ho pots sostenir, escriu-ne menys.
La temptació de tornar-hi a abocar. Cada vegada que l’agent falli tindràs ganes d’afegir un paràgraf a l’AGENTS.md. Resisteix-t’hi. Pregunta’t primer si allò és un fet, un criteri o una regla, i posa-ho al lloc que toca.
Els projectes petits no ho necessiten. Per a un script de dues-centes línies, tot això és sobrecàrrega. El senyal per començar és quan la mateixa correcció apareix per tercera vegada.
El que t’has d’endur
- Separa fets de criteris. Fallen diferent i es corregeixen diferent.
- Un fitxer d’entrada curt amb principis i mapa; la resta a
docs/. - Escriu el que vau descartar i per què. És el que estalvia més converses.
- Els fets que canvien, consulta’ls (MCP) en comptes de copiar-los.
- El criteri que has hagut de corregir tres vegades no és context: és una regla, i el seu lloc és el linter.
El context és la meitat probabilística del harness: fa més probable que la sortida sigui correcta, però no ho garanteix mai. La garantia arriba a la dimensió següent.