Com escriure un bon informe d’error (per a una IA o un desenvolupador)

Un bon informe d’error permet que una altra persona, un desenvolupador o una IA, vegi el mateix problema que has vist tu, sense haver de fer-te cap pregunta. Ha de tenir un títol específic, els passos exactes per reproduir-lo, el que esperaves, el que va passar realment, qualsevol missatge d’error copiat paraula per paraula, i on va passar: quina pàgina, navegador, dispositiu i usuari. Un error per informe, amb una captura de pantalla si ajuda.

La majoria dels errors triguen més a entendre’s que a corregir-se. Un informe clar elimina la part de la comprensió. Això importa encara més amb les eines d’IA: una IA no pot fer una pregunta de seguiment sobre què vols dir amb «el pagament és estrany», així que endevina, i una suposició errònia pot trencar alguna altra cosa.

La plantilla

Copia-la i omple-la:

Títol: [Què falla, i on] — p. ex. «El formulari de reserves rebutja hores després de les 18:00»

Passos per reproduir-ho:
1. ...
2. ...
3. ...

Esperat: [què hauria de passar]
Real: [què ha passat en lloc d’això]

Missatge d’error: [text exacte, si n’hi ha]
On: [pàgina/URL, navegador, dispositiu, amb quin usuari s’ha iniciat sessió]
Freqüència: [cada cop / a vegades / una vegada]
Captura de pantalla o gravació: [adjunta]

La resta d’aquesta guia explica cada part.

Pas 1: reprodueix-lo primer

Abans d’escriure, intenta que l’error torni a passar. Aprendràs quins passos són importants i si passa cada vegada.

• Comença des d’un estat net: actualitza, o tanca i torna a obrir la sessió.
• Anota cada clic i cada cosa que escrius.
• Intenta trobar el camí més curt que el provoca.
• Prova un segon navegador o un altre compte. Si només passa a un usuari, és una pista molt important.

Per aprofundir-hi, consulta com depurar una app creada amb IA.

Pas 2: escriu un títol específic

El títol ha de dir què falla i on, perquè algú que mira una llista sàpiga quin error és.

Pas 3: fes una llista de passos exactes

Numera-los. Sigues literal: quina pàgina, quin botó, què has escrit.

1. Inicia sessió com a client (compte de prova: customer@example.com).
2. Afegeix el «Kit d’inici» al carro.
3. Escriu el codi de descompte WELCOME10 i fes clic a Aplica.
4. Fes clic a Pagament.

«Prova de pagar amb un codi» deixa de banda els detalls que sovint importen: quin usuari, quin producte, quin codi, si s’ha aplicat abans.

Pas 4: esperat contra real

Aquest és el nucli de l’informe. Digues-ne tots dos, perquè la diferència és l’error.

• Esperat: la pàgina de pagament s’obre amb el 10 % de descompte al total.
• Real: el botó mostra un cercle de càrrega durant un segon, i després no passa res. Sense codi de descompte, el pagament funciona.

Sense «esperat», el lector potser no sap que el comportament és incorrecte. Sense «real», no sap què ha de buscar.

Pas 5: copia els errors exactament

Els missatges d’error són la ruta més ràpida fins a la causa. Copia’ls com a text, paraula per paraula; no els parafrasegis.

On trobar-los:

• A la pantalla: qualsevol missatge que mostri l’app.
• A la consola del navegador: obre les eines per a desenvolupadors (F12, o clic dret → Inspecciona) i mira la pestanya Console per veure les línies en vermell.
• Pestanya de xarxa: a les eines per a desenvolupadors, troba la petició que falla i anota’n la URL i el codi d’estat (per exemple POST /api/checkout → 500).
• Registres del servidor, si hi tens accés.

Una línia com TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48 sovint apunta directament al problema.

Pas 6: afegeix context

• On: la URL de la pàgina, l’entorn (vista prèvia, staging o producció).
• Qui: quin usuari o rol: administrador, membre, sense sessió iniciada.
• Dispositiu i navegador: «Safari a l’iPhone» versus «Chrome a Windows» pot importar.
• Dades: qualsevol cosa inusual del registre: text molt llarg, caràcters especials, un gran nombre d’elements.
• Quan va començar: «després del canvi d’ahir als codis de descompte» val molt.
• Freqüència: cada cop, o una vegada de cada deu.

Pas 7: mostra-ho

Una captura de pantalla amb el problema marcat, o una gravació de pantalla curta, elimina l’ambigüitat, especialment en els errors de disseny. Si la teva eina d’IA accepta imatges, adjunta-n’una. Retalla qualsevol cosa privada, incloses les claus i les dades d’altres persones.

Escriure informes d’error per a un constructor d’IA

La mateixa estructura funciona com a prompt. Hi ajuden dues addicions:

• Digues què no ha de canviar, perquè l’arranjament no provoqui un problema nou.
• Demana que verifiqui l’arranjament, no només que l’escrigui.

Amb sessió iniciada com a client, amb el «Kit d’inici» al carro i el codi WELCOME10 aplicat, fer clic a Pagament no fa res. Esperat: la pàgina de pagament s’obre amb un 10 % de descompte al total. Real: un cercle de càrrega breu i després res. La pestanya de xarxa mostra que POST /api/checkout ha retornat un 500. El pagament sense codi funciona. Troba la causa i arregla-la sense canviar com es calculen els preus de les comandes sense codi. Després comprova el pagament amb un codi de percentatge, un codi d’import fix i sense codi.

Si no estàs segur de la causa, demana primer un diagnòstic:

No canviïs el codi encara. Segons aquest informe, quines són les causes probables i què confirmaria cadascuna?

Errors habituals

• «Està trencat». Sense passos, sense resultat esperat, sense res en què actuar.
• Diversos errors en un sol informe. Alguns es corregeixen i d’altres es perden.
• Errors parafrasejats. «Una cosa undefined» amaga la part útil.
• Oblidar l’usuari o el rol. Molts errors només afecten administradors, o només usuaris nous.
• Descriure només l’arranjament que vols («afegeix una comprovació de null») en lloc del problema.
• Compartir secrets en captures de pantalla o registres enganxats.

Llista de comprovació

• He reproduït l’error i he trobat els passos més curts.
• El títol diu què falla i on.
• Els passos estan numerats i són literals.
• S’han indicat tant el resultat esperat com el real.
• Els missatges d’error s’han copiat exactament, amb la petició que falla i el codi d’estat.
• S’han inclòs la pàgina, l’entorn, l’usuari, el dispositiu i el navegador.
• He indicat amb quina freqüència passa i quan va començar.
• Hi ha una captura de pantalla o una gravació adjunta, amb les dades privades eliminades.
• Un error per informe.

Informar d’errors a l’agent de Mythex

Al projecte de Mythex, l’informe és el prompt. Algunes funcions ajuden:

• Adjunta una captura de pantalla de la vista prèvia o de la pantalla d’error: fins a 5 fitxers per missatge.
• /fix centra l’agent en arreglar un error, i el mode Pla li permet investigar abans d’editar.
• /test fa que l’agent reprodueixi els fluxos a la pròpia vista prèvia i t’informi del que veu.
• Torna a aquest punt desfà una correcció que ha empitjorat les coses.

La pàgina de la documentació sobre depurar amb prompts fa servir la mateixa estructura de passos, esperat i real. Per al cicle de correcció i comprovació que envolta això, consulta com iterar en una app creada amb IA.

Preguntes