better

# Eines IA per al desenvolupament

Guia sobre eines IA per al desenvolupament de programari: fonaments, criteri d'ús, context, automatització i pràctiques de treball amb agents.

Guia sobre eines IA per al desenvolupament de programari: fonaments, criteri d'ús, vocabulari compartit, context, automatització i pràctiques de treball amb agents.

1. [Fonaments de programació amb IA](./aitools/01_fonaments.md)

2. [Control i autonomia](./aitools/02_control_i_autonomia.md)

Llegeix en ordre: 1 → 2 → 3. Els tres primers capítols construeixen el marc conceptual: com funciona un agent, quan cedir-li control, i com triar el nivell adequat per a cada tasca.

**Vull millorar com treballo dia a dia amb l'agent**

Comença per 3 (triar el nivell), continua amb 4 (comunicació i context) i 7 (pràctiques). Són els capítols més operatius.

Comença per 3 (triar el nivell), continua amb 4 (comunicació, context i vocabulari compartit) i 7 (pràctiques). Són els capítols més operatius.

**Vull fer el meu projecte més compatible amb eines IA**

Capítol 5 directament — inclou ara guia pràctica sobre com evolucionar el fitxer d'instruccions, com construir l'arnès i com calibrar-lo. Si vols el "per què" primer, llegeix abans el 3.

Capítol 5 directament — inclou ara guia pràctica sobre com evolucionar el fitxer d'instruccions, com construir l'arnès, com calibrar-lo i com convertir el vocabulari del domini en context reutilitzable. Si vols el "per què" primer, llegeix abans el 3.

**Sóc tècnic i avaluo integrar IA en un equip**

2 (control i autonomia) + 5 (projecte automatitzable) + 6 (tipus de projecte). El 8 tanca amb reflexions útils per a decisions d'equip.

2. **Saps descriure el resultat esperat amb precisió** perquè la IA no hagi d'omplir buits d'especificació — si no pots, la tasca encara requereix decisions que no has pres

3. **La verificació del resultat és senzilla** — idealment automatitzada (tests, linting) que detectarà errors sense intervenció

Si, a més, el projecte ja fa servir un vocabulari de domini estable i compartit, l'autonomia és més segura: l'agent té menys marge per inventar noms, conceptes o abstraccions que no pertanyen al problema.

Si falta alguna, baixa el mode — o executa l'agent en un entorn aïllat on els errors quedin continguts (vegeu [Execució aïllada (sandboxing)](./07_practiques_i_tancament.md#execució-aïllada-sandboxing)).

Les tasques tedioses o senzilles són el punt de partida natural per delegar: si la feina és tediosa, normalment és perquè les decisions de disseny ja estan preses (condició 1) i el resultat esperat és prou clar per descriure'l sense ambigüitat (condició 2); i com que saps exactament què ha de sortir, verificar-ho és directe (condició 3).

- **Ambigüitat real (cal judici).** El problema depèn del context i no té una única resposta correcta. *"Refactoritza aquest mòdul perquè respecti el patró de `UserService`"*, *"per què falla aquest test inestable?"*, *"és segur aquest canvi de schema?"*. Codificar totes les heurístiques explícitament és inviable o es desactualitza ràpid. **És el cas legítim per a un agent.**

- **Desconeixement temporal del domini.** Les regles existeixen, però *encara no les coneixes*. És el cas més perillós: l'agent produeix sortida raonable, i això elimina la pressió per entendre-ho. La trampa: usar l'agent per *evitar pensar*, no per *raonar millor*. L'estratègia correcta és inversa — **explora el problema amb l'agent, entén-lo, i un cop el tens clar formalitza-ho en codi**.

### Vocabulari del domini

Un senyal útil que el problema s'està aclarint és quan el vocabulari del domini es torna estable. Si tots a l'equip anomeneu les mateixes coses amb els mateixos termes, el problema és més fàcil de descriure, de verificar i de delegar. Si un mateix concepte oscil·la entre sinònims, el model de la tasca encara és difús.

Per això el llenguatge del projecte no és un detall de redacció: és part del model del problema. Quan el vocabulari ja és compartit, sovint la feina deixa de semblar difícil d'entendre i passa a ser més fàcil de formalitzar.

## Eines deterministes de precisió

Abans de delegar al segon o tercer nivell, val la pena conèixer les eines del primer nivell que fan operacions que semblen intel·ligents però que en realitat són completament deterministes:

- **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](./07_practiques_i_tancament.md#execució-aïllada-sandboxing), 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

### Vocabulari compartit del domini

Quan el projecte té un vocabulari estable del domini, la IA té menys coses a endevinar. Els noms de classes, els límits entre mòduls i els termes del domini no són detalls cosmètics: són part del context que el model llegeix per entendre què està construint. En termes de Fowler, això és el vocabulari compartit que defineix un context local.

- **Si el prompt és vague, el model omple buits amb vocabulari genèric.** Aleshores sembla que ha entès la tasca, però en realitat ha triat un model de domini per defecte.

- **Si el codi usa noms inconsistents, el model perd senyal.** Un mateix concepte amb tres noms diferents és una invitació a generar tres interpretacions diferents.

- **Si el vocabulari és precís, el model pot mapar millor la intenció al codi.** La claredat del llenguatge no és només bona comunicació humana; és context executable per a la IA.

La conclusió pràctica és simple: abans de demanar més precisió al model, revisa si el projecte ja parla amb precisió. La qualitat del prompt i la qualitat del vocabulari del codi es reforcen mútuament, i el mateix passa amb el context del domini.

## 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.

**El criteri pràctic: si la violació del contracte produeix un error de compilació o de validació sense que ningú hagi de llegir el codi, el contracte existeix realment.**

### El codi com a context

Quan el projecte té una estructura estable i un vocabulari limitat, el mateix codi ja fa de context i d'arnès per a l'agent. Les abstraccions bones no només executen bé: també li diuen al model quins conceptes existeixen, com es relacionen i quines decisions no hauria de reinventar.

- **Abstraccions estables redueixen la dependència del prompt.** Si el model troba límits clars entre mòduls, li cal menys instrucció extra per mantenir-se dins del patró.

- **Els tests i els tipus no només detecten errors.** També delimiten què vol dir una implementació acceptable, i això fa que la IA generi menys variants plausibles però incorrectes.

- **Un codi ben estructurat és un context reutilitzable.** Quan el vocabulari del projecte és consistent i acotat, canvia menys la manera com el model interpreta cada tasca.

Per això, millorar l'arquitectura no és només una decisió per a humans. També és la manera més fiable de fer que la IA rendeixi millor sense haver de compensar-la amb prompts cada vegada més llargs.

## Tests i CI/CD

La verificació ha de ser simple i fiable. Això depèn de dues peces que es reforcen mútuament: una suite de tests sòlida i una CI/CD que l'executi automàticament a cada canvi.