Comunicació, planificació i context

• Donar instruccions útils
  • En què és bona la IA
  • Apunta a exemples existents
  • Contractes formals
  • Evita la subespecificació
  • Força la consulta de fonts actuals
  • Demana crítica, no confirmació
  • Separar implementació i revisió
  • Un prompt, una responsabilitat
  • Acotar un refactor
  • Sessions, context i degradació
  • Què fer quan la IA falla
  • Patrons de referència
• Estructurar la feina
  • El pla com a artefacte durable
  • Spec-driven development
  • Tasques acotades i tasques transversals
• Enginyeria de context
  • Què no s’ha de documentar
  • Què val la pena documentar
  • Context persistent de projecte
  • Format per al consum de la IA
  • Skills, modularitat i progressive disclosure

Aquest capítol cobreix com redactar bons prompts, com estructurar la feina delegada i com preparar documentació i context reutilitzables per a sessions futures.

Comunicar-se bé amb la IA vol dir tres coses: donar instruccions útils, posar-li el context correcte i estructurar bé la feina delegada.

Donar instruccions útils

La primera palanca és la més visible: les instruccions. Si el prompt deixa espais buits, la IA els omplirà amb el que és estadísticament habitual, no amb el que necessita el teu projecte.

En què és bona la IA

Per usar-la bé, també convé saber en què acostuma a ser útil. En general, la IA rendeix bé quan la tasca té una especificació clara i molt judici mecànic:

• Boilerplate i codi repetitiu. Implementacions previsibles, adaptadors, serialització, mapping de dades.
• Resums i walkthroughs de codi existent. Especialment per orientar-te ràpid en un mòdul que encara no coneixes.
• Primers esborranys de tests. Sempre que l’especificació la posis tu i després els revisis.
• Generació d’alternatives. Comparar dos enfocaments, patrons o APIs abans de decidir.
• Ajuda en debugging. Si descrius bé el símptoma i el context, pot proposar causes plausibles amb rapidesa.
• Documentació mecànica. Signatures, exemples d’ús i esquelets que després completaràs amb el “per què”.

La regla pràctica: com més clar està què ha de sortir, més probable és que la IA sigui útil per produir-ho. Però la IA també és valuosa quan no saps què ha de sortir — per aprendre: demana explicacions, comparacions, walkthroughs. Un prompt bo per aprendre pot ser massa vague per producció, i això és correcte — no confongueu els dos modes.

Apunta a exemples existents

La forma més eficient d’especificar un patró és apuntar la IA a un exemple existent al codi. La IA és bona replicant; no és fiable inferint:

Contractes formals

Una interfície, una definició de tipus, o un esquema d’API és l’especificació de més alta fidelitat. No deixa quasi espai per a que la IA endevini què construir — la restringeix a omplir el com:

Perquè aquests contractes són llegibles per la màquina, la conformitat és verificable pel compilador o un test de contracte — sense dependre de la revisió humana per detectar desviacions. Per a com dissenyar bons contractes — precondicions, postcondicions, invariants — vegeu Disseny per contracte.

Evita la subespecificació

Cada terme vague en un prompt és una decisió que estàs delegant a la IA:

• “fes-ho net” — Què vol dir “net” en el teu projecte?
• “afegeix gestió d’errors adequada” — Quins errors? Quin format de resposta?
• “fes-ho millor” — Millor en quin sentit?

Si no pots definir què vols, la IA omplirà el buit amb el que és estadísticament comú a les seves dades d’entrenament — que pot no ser el que necessita el teu projecte. Això aplica quan el codi ha d’arribar a producció. Quan explores una idea, un prompt vague és legítim — el propòsit és veure què emergeix, no obtenir un resultat definitiu.

Força la consulta de fonts actuals

La data de tall fa que el model respongui amb intuïció desactualitzada sense avisar: contesta amb confiança sobre una versió antiga de la llibreria i no et dirà “no ho sé”. Quan treballes amb tecnologia recent — llibreries post-tall, APIs noves, frameworks en evolució ràpida — demana explícitament al prompt que consulti documentació actual (cerca web, WebFetch, documents de referència a la finestra de context) abans de generar codi. És especialment crític quan el model ja t’ha donat una resposta sospitosament confident sobre una cosa recent.

Quan dubtis si cal forçar la consulta, hi ha tres moviments barats que redueixen el risc sense haver-ho de decidir a cegues:

• Pregunta-ho al mateix model. “Les teves dades d’entrenament són actuals per a aquesta llibreria/versió? Cal consultar la documentació?” — sovint el mateix model avisa del risc.
• Demana que citi l’API concreta. Si no pot anomenar la funció o el flag exacte, o si el nom no existeix quan el cerques al codi o a la documentació, és el senyal que està inventant.
• Fixa la versió al prompt. “utilitzant la llibreria X v5.2”. Força el model a comprometre’s amb una versió concreta o bé a reconèixer que no en té informació fiable.

Regla pràctica: el cost d’una consulta extra a documentació són segons; el cost de depurar crides a APIs al·lucinades són minuts o hores. En cas de dubte, consulta.

Demana crítica, no confirmació

La IA tendeix a dir-te que tens raó (sycophancy: biaix a confirmar el que dius, perquè va ser entrenada amb feedback que recompensava l’acord). Si preguntes “és correcte aquest disseny?”, quasi sempre produirà una confirmació amb arguments de suport. Pregunta millor:

• “Quins són els arguments més forts en contra d’aquest disseny?”
• “Quins casos límit no estic considerant?”
• “On podria fallar aquest enfocament?”

Separar implementació i revisió

Demanar a la IA que implementi codi i després el revisi a la mateixa sessió produeix autoavaluació esbiaixada — el model afavoreix la seva pròpia sortida. Implementació i revisió haurien de ser prompts separats, idealment en sessions separades. Quan revisis codi generat per IA, obre un context nou amb només el codi i l’especificació original, no la conversa que el va produir.

Un prompt, una responsabilitat

Els prompts compostos (“implementa la feature, escriu els tests i actualitza la documentació”) produeixen pitjors resultats en tots els aspectes. Seqüencia els passos i verifica cada un abans de continuar.

Per a decisions complexes (arquitectura, disseny de model de dades, anàlisi de trade-offs), demana una resposta estructurada: supòsits, alternatives, arguments en contra, riscos i conclusió. Això acostuma a produir millor judici que una resposta purament conclusiva. Per a implementació, un prompt, una responsabilitat.

Acotar un refactor

Els refactors grans donats a la IA com un sol prompt vague produeixen diffs grans i difícils de revisar que barrejaran canvis desitjats amb no desitjats.

En lloc de:

Refactoritza el mòdul d'usuaris per usar el patró repository

Escriu:

Extreu totes les queries de base de dades de UserService en una nova
classe UserRepository.
Segueix la mateixa estructura que ProductRepository a product/repository.py.
Manté les signatures dels mètodes públics de UserService sense canvis.
No modifiquis cap test encara — només el cablejat intern.

El segon prompt deixa l’arquitectura al desenvolupador (patró repository, seguint un exemple existent, interfície pública estable) i la implementació a la IA (l’extracció real, el cablejat i els canvis d’imports). El diff resultant cobreix una sola cosa i es pot revisar d’un cop.

Sessions, context i degradació

Un LLM no té memòria — ni entre sessions ni dins d’una mateixa sessió. Cada crida és independent: el model rep text i genera una resposta, sense recordar res de crides anteriors. La il·lusió de continuïtat dins d’una sessió la crea la capa d’orquestració (Claude.ai, ChatGPT, Cursor, Claude Code…), que acumula l’historial de la conversa i el torna a enviar al model a cada torn.

Tot aquest historial, juntament amb les instruccions de sistema, fitxers del projecte i el teu prompt, ha de cabre dins la finestra de context — el buffer de tokens que el model pot processar en una sola petició. A mesura que una sessió creix, les restriccions inicials reben menys atenció — els requeriments del principi queden efectivament enterrats.

• Comença cada tasca discreta en una sessió nova amb un plantejament clar. Una sessió nova no és un cost — és un avantatge: menys context acumulat vol dir menys tokens processats per crida, respostes més precises i menys risc que el model ignori les teves restriccions. Arrossegar una sessió llarga és el que surt car — en qualitat i en consum de tokens.
• Si una sessió és llarga, repeteix les restriccions clau quan canviïs de subtasca. L’historial acumulat enterra les instruccions inicials; el model les “oblida” perquè estadísticament pesa més el context recent.
• No carreguis fitxers grans o context irrellevant. Cada token de context irrellevant dilueix el senyal útil — la informació que realment importa per a la tasca — i incrementa el cost de cada crida sense aportar res. Sigues selectiu: carrega només el que el model necessita per a la tasca concreta.
• L’historial de la conversa també és context. Cada torn anterior ocupa espai a la finestra de context i empeny les instruccions inicials cap avall, on reben menys atenció. Una sessió de 50 torns pot funcionar pitjor que una de 5 amb un bon prompt — no perquè el model sigui pitjor, sinó perquè el senyal útil queda enterrat.
• Reconeix els senyals de degradació. Quan el model comença a contradir decisions preses abans a la mateixa sessió, a “oblidar” restriccions que ja li has donat, o a entrar en bucles repetitius — la sessió està saturada. No insisteixis: obre’n una de nova amb un prompt net.

Amb bona documentació de context, les sessions curtes no són un problema — són la norma. Obrir una sessió nova és barat si el coneixement del projecte viu al repositori en lloc de dependre de la memòria d’una conversa — i a més, una sessió fresca amb context mínim i precís produeix millors resultats que una sessió llarga amb centenars de torns acumulats. Com capturar i carregar aquest coneixement es tracta a Enginyeria de context; com aprofitar sistemàticament aquesta propietat — repartint la feina entre sessions efímeres en lloc de confiar en la disciplina d’obrir-ne de noves manualment — es tracta a Estructurar la feina.

Què fer quan la IA falla

Quan la sortida no és bona, el pitjor reflex és insistir amb el mateix nivell de vaguetat. Millor aplicar aquestes correccions:

• Si la resposta és vaga, afegeix restriccions. Exemples, fitxers de referència, casos límit, formats de sortida.
• Si el codi és incorrecte, redueix l’abast. Demana una funció, un fitxer o un canvi concret en lloc d’una feature sencera.
• Si el resultat no millora, obre una sessió nova. El context acumulat d’intents fallits pot estar contaminant la resposta — un inici net amb un prompt més precís sovint funciona millor que un tercer intent a la mateixa conversa.
• Revisa el context que has donat. Abans de culpar la IA, comprova si li falta informació clau, si li has passat fitxers irrellevants que el distreuen, o si el teu prompt conté ambigüitats que no havies vist.

Patrons de referència

Les tècniques d’instrucció descrites en aquesta secció s’han formalitzat en un catàleg de patrons amb nom, descripció i exemples. Els més rellevants per al desenvolupament professional:

• Cadena de Pensament — demana al model que raoni pas a pas abans de concloure; útil per a debugging i decisions d’arquitectura on cal seguir el fil lògic
• Prompting amb Exemples — proporciona exemples del patró esperat en lloc de descriure’l amb paraules; el model replica millor del que infereix
• Prompting de Rol — especifica la perspectiva des de la qual ha de revisar (expert en seguretat, revisor de rendiment, arquitecte); evita feedback genèric
• Especificació de Restriccions — explicita el que no vols; cada terme vague és una decisió delegada al model
• Demanar Alternatives — demana dues o tres opcions amb els seus compromisos; especialment útil per a decisions d’arquitectura on no hi ha una resposta única
• Prompting de Verificació — en un torn separat, demana al model que trobi les debilitats del que acaba de generar; la revisió funciona millor amb context nou
• Planifica i Executa — demana un pla complet i espera la teva aprovació abans que el model escrigui cap codi; evita correccions costoses a mig camí
• Punts de Control Humans — el model hauria de pausar i demanar confirmació abans d’accions irreversibles (esborrar fitxers, executar migracions, modificar esquemes); complementari a l’execució aïllada, que limita el dany quan el punt de control falla
• Destil·lació de Prompt — al final d’una sessió de refinament, demana al model que escrigui el prompt únic que hauria produït el resultat directament; útil per construir plantilles reutilitzables per a tasques recurrents

Estructurar la feina

Amb la infraestructura de context en marxa, queda la pregunta tàctica: com estructures la feina que delegues. El fil és el de sempre — decidir primer, executar després, separar fases perquè no es contaminin.

Cada vegada que arrenca una fase — una sessió nova, una subtasca, un subagent — el que li dones al principi és gairebé l’única palanca que tens: un cop ha començat a treballar, no pots corregir-la en temps real, i les suposicions que faci pel seu compte acaben dins del resultat. En diem briefing del paquet autoconclús d’instruccions i referències des del qual una sessió fresca pot arrencar sense demanar aclariments. Estructurar la feina és, en la pràctica, dissenyar la cadena de briefings que la travessa.

El pla com a artefacte durable

Un pla que només viu dins d’una sessió desapareix amb ella. Escriure’l com un document — un fitxer al repositori, el cos d’una issue, una ADR, un markdown breu — fa que la decisió de disseny sobrevisqui: es pot revisar pel seu compte abans que s’escrigui cap codi, es pot auditar després contra la implementació que ha produït, i cada fase d’execució posterior el pot carregar com a briefing ja escrit.

La idea ja apareix al document en dues formes més acotades: el mode Plan n’és la versió d’un sol torn, i el patró Planifica i Executa la versió de prompting. Promoure el pla a artefacte — committed, versionat, referenciable — afegeix tres propietats que cap de les dues dona per si sola:

• Revisió separada. El pla es revisa abans que el codi. Si és incorrecte, no has pagat cost d’implementació.
• Contracte reutilitzable. Cada execució posterior — pròpia o delegada a un subagent — el pot carregar sense dependre de la conversa que el va produir.
• Divergència detectable. Quan el codi s’aparta del pla, el pla és el punt de referència contra el qual la divergència es fa visible.

No cal un document pesat. Una llista de passos commitada, el cos d’una PR en draft, o un markdown d’una pantalla de llarg ja compleix la funció. El que importa no és el format — és que existeixi fora del context de la sessió que el va produir.

Spec-driven development

Darrere de cada briefing hi ha una especificació — més o menys explícita — de què ha de fer l’agent. El pla durable n’és una forma; els contractes formals i la documentació de context en són les altres dues. Tractar aquestes tres peces com a artefacte primari — del qual parteix i contra el qual es verifica el treball de l’agent — és el que la indústria anomena spec-driven development (SDD). Iniciatives com GitHub Spec Kit empaqueten aquest patró amb plantilles i convencions.

El vocabulari emergent distingeix tres graus de compromís amb l’especificació:

La majoria d’equips pragmàtics — i aquesta guia — aterren al tier del mig: l’spec informa i restringeix l’agent sense pretendre ser-ne la font única. Els contractes descriuen el què, els plans durables capturen la decisió, i l’enginyeria de context manté tots dos accessibles a cada sessió. Nomenar-ho spec-anchored dona vocabulari compartit amb l’ecosistema; l’enginyeria de fons és la que ja has fet.

La utilitat pràctica del framework és diagnòstica: abans d’arrencar una tasca, pregunta’t en quin tier et vols situar. Si la resposta és “cap” — ni contracte, ni pla, ni context escrit — l’agent treballarà des de l’aire, i el cost de rectificar es pagarà més tard.

Tasques acotades i tasques transversals

Amb la decisió escrita, l’atenció es desplaça a l’execució. Quan el codebase no hi cap al context — que és gairebé sempre — val la pena distingir dos tipus de tasca, perquè demanen estratègies diferents:

Tasques acotades: el canvi afecta un fitxer o un grapat de fitxers coneguts. El context es prepara fàcilment: apuntes la IA als fitxers rellevants, hi afegeixes la convenció aplicable, i demanes el canvi. El risc de perdre’s és baix.

Tasques transversals: el canvi pot tocar qualsevol lloc del codebase — renombrar un concepte, actualitzar una API interna, aplicar una nova convenció. Aquí la feina es parteix en dos passos: trobar on aplica i fer el canvi. El segon pas és mecànic; el primer és el que pot fallar silenciosament.

El risc d’una tasca transversal no és la finestra de context — és la cobertura de la cerca. Si la cerca no troba una ocurrència, el canvi queda incomplet i ningú se n’adona fins que alguna cosa es trenca en producció. La capa d’orquestració executa el que li demanes; no garanteix que hagis demanat prou.

Què fer:

1. Separa descoberta i acció. Primer una passada només de cerca (“llista tots els llocs on passa X, no toquis res”). Revisa la llista. Llavors encomana l’edició. Així pots auditar la cobertura abans que cap línia es mogui.
2. Triangula la cerca. Una sola cerca per nom de símbol perd renames, wrappers, dispatch dinàmic, strings, configuració, tests, documentació. Demana cerques per senyals diferents — símbol, patró de crida, tipus relacionats, missatges d’error — i comprova que convergeixen.
3. Ancora en estructura, no en text. Signatures de tipus, implementadors d’una interfície, grafs d’imports i “callers of” són més fiables que un grep. Usa eines d’AST o LSP quan existeixin.
4. Força una passa de “què hem pogut perdre”. Demana a l’agent que argumenti contra la seva pròpia llista: quins patrons escaparien d’aquesta cerca? Llavors executa aquelles cerques.
5. Fes el radi d’impacte observable. Un diff en sec, o un pilot sobre un sol fitxer, fa que una ocurrència perduda aparegui com a inconsistència en lloc de podrir-se silenciosament.

La capa d’orquestració s’encarrega de la mecànica, però l’estratègia de cerca, els criteris d’acceptació i la verificació són feina del desenvolupador. La IA és un junior ràpid amb memòria perfecta del que li poses al davant — i memòria zero del que no.

Quan l’eina fusiona descoberta i acció. Sovint els agents més autònoms executen els dos passos seguits sense aturar-se — i perds justament el moment on podries auditar la cobertura. Tens tres palanques:

1. Forçar el checkpoint al prompt. “Primer llista totes les ocurrències i espera confirmació abans de tocar res.” Els models acostumen a respectar-ho, però no sempre — depèn del mode.
2. Triar el mode adequat. Per tasques transversals, baixa un nivell: mode plan o chat primer (vegeu Control i autonomia), i només passes a edició quan tens la llista revisada.
3. Revisar a posteriori si no hi ha checkpoint. Si el mode no admet pausa, el checkpoint es desplaça al final: diff complet abans de commit, i una cerca independent teva que validi que no s’ha perdut res. És pitjor que aturar al mig — ja has pagat el cost del canvi — però és la xarxa de seguretat quan l’agent no en posa cap.

El patró general: com més autònoma és l’eina, més carrega sobre tu la responsabilitat de dissenyar els punts de verificació — abans, durant o després.

Algunes eines permeten delegar peces acotades a subagents efímers — sessions fresques que arrenquen amb un briefing autoconclús, executen una feina delimitada i retornen un resum. Això aïlla el context, separa fases i permet revisió independent sense biaix. El principi és el mateix: com més autònoma és l’eina, més importa dissenyar els punts de verificació.

Enginyeria de context

L’enginyeria de context tracta de decidir quin coneixement ha de veure la IA, en quina forma i amb quina persistència. El coneixement que només viu al cap d’algú o en una finestra de xat és fràgil — per a l’equip i per a la IA. Quan una sessió produeix quelcom durable — un walkthrough del codi, una decisió de refactoring i la seva justificació, una convenció de noms — fes commit al repositori com a fitxer markdown. Això serveix primer l’equip (nous desenvolupadors el poden llegir, les revisions el poden referenciar) i com a conseqüència serveix la IA (es pot carregar com a context en sessions futures).

Ara bé, crear el document és només la meitat. L’enginyeria de context — decidir què carregar, en quina forma, i quan — s’està convertint en l’habilitat central del treball amb IA, per davant fins i tot del prompt engineering. La raó és directa: un bon prompt en una sessió amb context pobre produeix resultats pobres; un prompt mediocre en una sessió amb context ric produeix resultats útils.

El model només pot treballar amb el que té al context efectivament carregat. Si el patró rellevant no hi és, la IA en substituirà un de les seves dades d’entrenament. Si una restricció no s’estableix, serà ignorada. Si una regla de domini no es proporciona, serà inferida — o silenciosament descartada.

Això vol dir que la feina més rendible no és aprendre a formular prompts millors — és construir i mantenir la infraestructura de context del projecte: fitxers de convencions, ADRs, exemples canònics, restriccions de domini. Equips que inverteixen en aquesta infraestructura reporten menys intervencions correctores per tasca, perquè cada sessió arrenca amb les decisions ja codificades en lloc d’haver de redescobrir-les.

Què no s’ha de documentar

No documentes com funciona el codi — el codi és sempre la font més precisa i actualitzada d’aquesta informació. Una descripció com “UserService crida el repository, que consulta la base de dades” queda obsoleta en el moment que algú refactoritza el codi, i la documentació obsoleta enganya activament la IA. El test és senzill: si un document podria quedar malament quan algú canvia codi sense tocar el document, és una descripció d’implementació — no hi pertany.

Què val la pena documentar

El que sí pertany al context és el que el codi no pot dir de si mateix — allò que el desenvolupador tenia al cap però que el codi no expressa — i que la IA necessita per no contradir o desfer decisions sense adonar-se’n:

• Per què una estructura va ser triada — les decisions de disseny i les seves justificacions. Les ADRs (Architecture Decision Records) encaixen bé: situació, decisió, conseqüències; la IA redacta l’estructura, tu escrius la justificació.
• Quin patró seguir i on trobar l’exemple canònic al projecte (“per a nous repositoris, segueix l’estructura de UserRepository”)
• Invariants i restriccions que no estan expressats en els tipus ni en els tests
• Desviacions intencionals de les convencions del framework — la IA les sobreescriurà silenciosament si no s’especifiquen

Context persistent de projecte

Per carregar aquesta informació a una sessió: apunta la IA als exemples rellevants, proporciona les restriccions i la documentació escrita. Per a convencions que s’han d’aplicar sempre, usa un fitxer de context a nivell de projecte — moltes eines suporten un fitxer d’instruccions que es carrega automàticament sense repetir-ho cada cop. Tracta’l com codi: revisa’l periòdicament, elimina regles duplicades, resol contradiccions. Un fitxer de context que només creix acaba degradant-se — cada línia irrellevant dilueix les instruccions que importen, incrementa el consum de tokens a cada crida, i empitjora la qualitat de les respostes. Menys context, però més precís, sempre guanya.

Format per al consum de la IA

La documentació de context no només ha de tenir el contingut correcte — ha d’estar en una forma que la IA pugui consumir eficientment. Les pràctiques que funcionen bé per a lectors humans (navegació visual, progressive disclosure interactiu, exemples desplegables) són irrellevants o contraproduents per a un model que llegeix en una sola petició i té un pressupost de tokens limitat.

• Mida controlada. Un document que supera el pressupost de context pràctic esdevé invisible: o es trunca o s’abandona. Dividir documentació extensa en fitxers temàtics amb referències creuades és millor que un sol fitxer monolític.
• Markdown net i estructura consistent. Encapçalaments regulars, codi immediatament després de la descripció que il·lustra, menys decoració visual. El que facilita l’escaneig humà també facilita que l’agent trobi el fragment rellevant sense carregar-ho tot.

Skills, modularitat i progressive disclosure

Un patró que s’ha consolidat és el de les skills modulars: un fitxer amb una capçalera declarativa (name, description) i un cos amb instruccions detallades. El mecanisme clau és el progressive disclosure: a l’arrencada, l’agent només carrega les capçaleres de totes les skills — una taula de continguts compacta. Només quan una tasca fa rellevant una skill, l’agent llegeix el cos complet. Això permet exposar desenes de capacitats sense saturar el pressupost de tokens.

La distinció amb els fitxers d’instruccions globals del projecte és neta: aquests són instruccions sempre al context; les skills són capacitats modulars que l’agent carrega només quan encaixen amb la tasca. És la mateixa lògica dels contractes formals aplicada a la documentació — una capçalera declarativa permet decidir si val la pena carregar abans de fer-ho.