Del prototip al traspàs: programari de recerca mantenible

El postdoc que va construir l'eina d'anàlisi es va graduar l'estiu passat. L'app Streamlit en què el consorci confiava per monitoritzar el reclutament multi-seu va caure al novembre quan va expirar la capa gratuïta del cloud. La pipeline que un altre equip fa servir per puntuar avaluacions de CV funciona al portàtil del postdoc i enlloc més, perquè les dependències mai es van anotar. El finançador preguntarà, a la propera revisió, què va passar amb les eines que el projecte va comprometre.

Aquest és el mode de fallada més comú al programari acadèmic de recerca: el prototip funciona, el desenvolupador se'n va, el programari mor. La solució no és més disciplina aplicada després. És un petit conjunt de pràctiques d'enginyeria aplicades a la fase de prototip — pràctiques que costen gairebé res si s'afegeixen aviat i li costen tot al projecte quan s'afegeixen tard o mai.

Aquest article és una guia pràctica per fer que el programari de recerca sigui mantenible: què el mata, què el salva, i el paquet mínim de traspàs que manté una eina viva més enllà del seu desenvolupador original.

Per què mor el programari de recerca

Després de treballar amb equips de recerca en salut, neurociència, polítiques públiques i ciències socials, els mateixos quatre patrons maten gairebé qualsevol peça de programari de recerca.

1. Mai es va capturar la fotografia de dependències

L'eina corre al portàtil del desenvolupador amb una versió específica de Python, un estat específic de virtualenv, un set específic de paquets R. Sis mesos després, al portàtil d'una altra persona, la meitat de les dependències ha canviat. L'eina deixa d'importar o comença a produir números diferents. Sense un manifest de dependències congelat (requirements.txt, Pipfile.lock, renv.lock, pyproject.toml), l'eina està implícitament lligada a una sola màquina.

2. El README era un placeholder

El repositori tenia README. El README deia "Eina d'anàlisi de recerca" i llistava els tres scripts. No deia com instal·lar dependències, com executar l'eina, quines entrades accepta o quines sortides produeix. Qui el va escriure sabia les respostes; ningú més. La documentació no és una tasca separada — és l'artefacte que fa l'eina llegible.

3. El desplegament era de capa gratuïta d'un sol ús

L'app Shiny a la capa gratuïta de shinyapps.io. L'app Streamlit a la capa gratuïta de Streamlit Cloud. El lloc estàtic a Netlify gratis. Les capes gratuïtes són bones per prototipar; no són infraestructura duradora per a programari lliurable a finançador. Quan canvia la facturació, s'arriba als límits d'ús o la plataforma pivota, les eines en capes gratuïtes desapareixen sense avisar.

4. El pla de manteniment era implícit

El pla, tal com era, era "el postdoc hi parararà esment". Quan el postdoc se'n va, el pla s'acaba. No hi ha ningú anomenat per escrit com a responsable durant els pròxims 24 mesos. La institució no sap que l'eina existeix al nivell necessari per assignar-la. Les eines de flux de treball de recerca sense un traspàs de manteniment per escrit són programari esperant morir.

Cada un és petit en el moment i devastador en conjunt. Cap requereix enginyeria sofisticada per arreglar-se.

Què salva el programari de recerca

Cinc pràctiques, aplicades durant la fase de prototip, canvien la taxa de supervivència dràsticament.

Pràctica 1: Fixa dependències al començament, no al final

El primer commit del prototip hauria d'incloure un manifest de dependències congelat. pip freeze > requirements.txt per a Python; renv::snapshot() per a R; lockfiles versionats per a qualsevol ecosistema que faci servir el projecte. Costa 30 segons al dia u i salva el projecte al dia 365.

Pràctica 2: Escriu el README com un test de màquina nova

El README ha de respondre quatre preguntes en ordre:

1. Què és això? — un paràgraf
2. Com l'instal·lo? — comandes exactes, copiables
3. Com l'executo? — comandes exactes, amb un exemple d'entrada
4. Què produeix? — estructura d'arxius de sortida, un exemple

Prova el README executant-lo en una altra màquina, o demana-li a un company que no hagi vist l'eina. Si no aconsegueix que funcioni en 15 minuts, el README és incomplet.

Pràctica 3: Tria una stack que la institució pugui mantenir

La stack correcta per a programari de recerca no és la més de moda. És la que la teva institució pot contractar o que el teu equip institucional de RSE ja suporta.

Per a projectes de recerca el 2026, les opcions duradores són:

• Python + stack científic estàndard (pandas, numpy, scipy, matplotlib) per a anàlisi
• R + tidyverse per a feina estadística on R és la lingua franca
• Node.js / TypeScript + un framework web mainstream (Next.js, FastAPI per al backend) per a eines
• Postgres per a qualsevol capa de dades persistent
• Desplegaments containeritzats (Docker) per a qualsevol cosa que hagi de córrer en servidor

Evita: frameworks de nínxol que depenen d'un únic mantenedor, llenguatges per als quals la teva institució no pot contractar, plataformes amb capes gratuïtes fràgils.

Pràctica 4: Desplega a infraestructura duradora des del principi

No prototipis a capes gratuïtes. Fes servir:

• L'allotjament de l'equip institucional de research-software-engineering (RSE) si està disponible
• Un servei gestionat de contenidors amb model de preus estable (Fly.io, Render, Railway, AWS App Runner) — entre 10 i 20 €/mes per a una eina de recerca de baix trànsit
• El cluster Kubernetes de la teva institució si n'hi ha i el teu projecte ho justifica

La diferència de cost entre gratis i durador acostuma a ser inferior a 300 €/any. La diferència de fiabilitat és la diferència entre "l'eina segueix viva" i "l'eina és morta".

Pràctica 5: Escriu el traspàs abans que el desenvolupador se'n vagi

El document de traspàs no és "tot el que sé sobre aquesta eina". És "el mínim que una altra persona necessita per mantenir l'eina funcionant". En concret:

• Un runbook per a tasques operatives comunes (desplegar, reiniciar, actualitzar dependències, investigar fallades)
• Un manual d'incidències per a modes de fallada coneguts (autenticació trencada, factura del cloud, canvis de format del dataset)
• Una llista de totes les credencials, comptes i dependències d'infraestructura, amb on es guarden
• Un successor amb nom — una persona concreta, amb vist-i-plau del seu responsable, que assumeix la responsabilitat durant els pròxims 24 mesos
• Un pla de retirada si no hi ha successor disponible — quan es retira l'eina i què la reemplaça

És incòmode escriure-ho perquè reconeix que l'eina sobreviurà a la implicació del desenvolupador original. Aquest reconeixement és la precondició per a la supervivència.

El paquet mínim viable de traspàs

Quan una eina de recerca passa de "desenvolupador-actiu" a "mantinguda per l'equip" — típicament quan el desenvolupador original es gradua, rota o canvia d'institució — els lliurables que el teu equip necessita són:

| Ítem | Què inclou | |---|---| | Repositori amb codi actual | Codi font complet, en una llar de llarg termini (GitLab institucional, GitHub Enterprise, Zenodo per a arxiu) | | Manifest de dependències congelat | requirements.txt / lockfile versionat | | README que passa el test de màquina nova | Instal·lar, executar, sortida esperada — verificat en una altra màquina | | Runbook | Procediments operatius: desplegar, actualitzar, reiniciar, recuperar | | Manual d'incidències | Modes de fallada coneguts + procediments de recuperació | | Traspàs de credencials | Accés a comptes, on es guarden, qui les pot rotar | | Contracte de manteniment | Successor amb nom, període de responsabilitat, ruta d'escalat | | Clàusula de retirada | Condicions sota les quals es decomissiona l'eina |

Vuit ítems. Cap és tècnicament difícil. Tots falten rutinàriament.

El test de màquina nova de 30 minuts

El diagnòstic de major palanca per a qualsevol eina de recerca: agafa algú que no l'hagi construïda, dóna-li una màquina nova, passa-li el README i observa-la intentant fer-la funcionar. Bloqueja 30 minuts.

Puntuació:

• L'ha fet funcionar en 15 minuts: nota A — l'eina està bé
• L'ha fet funcionar amb un o dos bloquejos menors: nota B — arregla'ls, gairebé hi ets
• L'ha fet funcionar en 30 minuts després de diversos bloquejos: nota C — el README necessita feina
• No l'ha fet funcionar: nota F — l'eina no sobreviurà al desenvolupador original

La majoria d'eines de recerca són C o F quan es proven amb honestedat. La majoria d'equips no ha fet mai el test, per això es sorprèn quan l'eina mor.

Quan incorporar ajuda externa

Un projecte de traspàs de programari de recerca és el moviment correcte quan:

• El desenvolupador original se'n va en menys de 3 mesos i no hi ha successor al seu lloc
• L'eina és operativament important (usuaris actius, flux de dades en marxa) però no està documentada
• El finançador espera que l'eina segueixi accessible durant un període declarat després del final del projecte
• L'equip no té plantilla per absorbir el manteniment i necessita un traspàs estructurat a l'equip intern o al grup institucional de RSE

El projecte MVP d'eina de recerca de Pragma cobreix la fase de construcció; també fem projectes de presa de relleu on l'objectiu és endurir un prototip existent fins a fer-lo mantenible. La sortida és el paquet de traspàs de 8 ítems anterior més la feina d'enginyeria necessària per fer cada ítem real (fixació de dependències, migració de desplegament, reescriptura del README, redacció del runbook).

Si tens un prototip que funciona però no és mantenible, aquest és el projecte.

Tres coses per fer aquesta setmana

1. Tria una eina prototip del teu projecte. Executa el test de màquina nova de 30 minuts. Sigues honest amb la nota.
2. Sigui quina sigui la nota, identifica la solució de menor cost que la mogui una lletra amunt. Sovint són 2 paràgrafs de README.
3. Si la nota és C o F i l'eina és operativament important, sol·licita una revisió de projecte. Definirem el paquet mínim de traspàs i el que costa entregar-lo.

El programari de recerca no ha de morir. La majoria de les pràctiques d'enginyeria que prevenen la seva mort no són sofisticades. La disciplina és fer-les al principi, quan costen gairebé res — en lloc d'al final, quan li costen tot al projecte.