AGENTS.md, {amiral} și programatorul asistat de AI

Introducere

Asistenții de codare AI devin o parte naturală a modului în care funcționează programatorii clinici R – funcții de completare automată, sugestie de cazuri de testare, redactare de derivări. Dar din cutie, acești agenți nu știu nimic despre convențiile ADaM, standardele CDISC sau despre cum se potrivește ecosistemul farmaceutic. Ei nu știu că analiza semnalează variabile precum ANL01FL de obicei ia "Y" sau NA si nu "N" Ei nu știu asta {pharmaversesdtm} este sursa canonică a datelor SDTM de testare sau asta {xportr} așteaptă în aval să vă transforme setul de date într-un fișier XPT gata de trimitere. AGENTS.md este un standard simplu, deschis, care schimbă asta – și {admiral} ecosistemul are acum infrastructură pentru a genera și menține automat aceste fișiere în fiecare pachet din familie.

Ce este AGENTS.md?

AGENTS.md este un fișier simplu de reducere pe care îl trimiteți în depozit, care oferă agenților de codare AI contextul de care au nevoie pentru a funcționa corect în proiectul dvs. Gândiți-vă la asta ca pe un README pentru agenți — în timp ce README.md spune unui nou dezvoltator care este proiectul, AGENTS.md îi spune unui asistent AI cum să lucreze corect în el.

De ce contează acest lucru pentru pharmaverse

Derivarile ADaM codifică zeci de ani de așteptări de reglementare CDISC care nu apar nicăieri în sintaxa R. Faptul că ANL01FL este un steag de analiză cu o logică specifică de derivare, care DTYPE = "LLOQ" înregistrările de imputare urmează reguli specifice – nimic din acestea nu este dedus numai din cod.

The {admiral} nici pachetul nu există izolat. Funcționează într-o conductă care curge din {pharmaversesdtm} date de testare prin derivații amirale, adesea ghidate de {metacore} specificații și, în cele din urmă, prin {xportr} la fișiere XPT gata de depunere. Un agent care scrie cod amiral fără acest context este ca un programator nou care știe doar funcția pe care o editează, nu sistemul căruia îi aparține.

Un AGENTS.md într-un depozit al familiei amiral poate comunica toate acestea înainte ca agentul să scrie o singură linie de cod.

Un prim pas în strategia pharmaverse AI

The {admiral} Echipa discută în mod activ cum să-și oficializeze abordarea cu privire la dezvoltarea asistată de AI – ce instrumente să încurajeze, ce balustrade să pună în aplicare și cum să documenteze rolul AI în strategia de programare. Acea conversație este încă devreme și în mod deliberat: consensul este de a câștiga experiență reală înainte de a bloca îndrumări oficiale.

Vestea bună este că experiența vine deja, repede.

7 martie 2026 — vine întrebarea. PR #2996 a aterizat de la un nou colaborator, maxthecat2024reparând mesajele de avertizare prost formatate în derive_param_computed(). PR a fost minuțios și bine structurat – exemple detaliate înainte/după, conversii de testare instantanee, o listă de verificare complet completată. A fost și genul de contribuție care a făcut echipa să se întrebe: a fost acesta un bot AI? Nu știm sigur și, în cele din urmă, nu a contat – codul a fost bun și a fost fuzionat. Dar întrebarea în sine era grăitoare.

Dar PR-ul a relevat și o limitare importantă. Mai degrabă decât să alerge devtools::document() pentru a regenera .Rd fișier, Copilot editat manual man/derive_vars_merged_summary.Rd direct – și propria sa descriere PR a recunoscut acest lucru: „Actualizat manual pentru a se potrivi roxygen2::roxygenize() ieșire.” Când un recenzent a subliniat acest lucru, Copilot a răspuns sincer: „R nu este disponibil în mediul meu sandbox, așa că nu pot executa devtools::document() direct. Pentru sesiunile viitoare, înțeleg fluxul de lucru corect.” Un recenzent uman a alergat devtools::document() în afara casetei de nisip și a împins generat corect .Rd fișier în commit c855860.

Aceasta este o nuanță importantă: problema nu era asta AGENTS.md era neclar – era că mediul de execuție al lui Copilot pur și simplu nu avea R disponibil. Nicio instrucțiune, oricât de bine scrisă, nu poate face un agent să execute o comandă pe care fizic nu o poate executa. AGENTS.md poate învăța un agent fluxul de lucru corect; asigurarea că mediul susține că fluxul de lucru este o responsabilitate separată, deținută de om. Această distincție contează pe măsură ce comunitatea își dezvoltă strategia AI.

Această fereastră de două săptămâni spune întreaga poveste. Contribuțiile asistate de IA sosesc deja în {admiral} repertoriu. AGENTS.md ajută deja agenții să înțeleagă convențiile specifice proiectului. Iar lacunele pe care le expune deja informează îmbunătățiri. Aceasta este bucla de feedback de care comunitatea are nevoie pentru a construi o strategie AI atentă – nu speculații, ci dovezi.

AGENTS.md reprezintă prima infrastructură tangibilă care iese din această gândire. Indiferent dacă un colaborator este un om care folosește un asistent AI, un agent autonom sau ceva între ele, codul trebuie să respecte convențiile ADaM și standardele pharmaverse. AGENTS.md ajută la asigurarea faptului că o face.

Dacă aveți gânduri despre cum ar trebui să arate strategia mai largă, discuția este deschisă – alăturați-vă conversației de la numărul 547 de Amiraldev. Comunitatea științifică open-source mai largă lucrează la întrebări similare: rOpenSci a publicat recent o politică de inteligență artificială care merită citită ca punct de referință pentru modul în care se formează aceste norme. În special, politica rOpenSci solicită agents.md direct în șablonul de trimitere a revizuirii software-ului:

„Dacă depozitul dvs. include un fișier „agents.md” sau echivalent, vă rugăm să furnizați un link și să descrieți modul în care acesta a fost utilizat în dezvoltarea pachetului dumneavoastră.”

Asta o cere deja comunitatea științifică open-source mai largă AGENTS.md ca parte a evaluării inter pares este un semnal că această normă se instalează rapid.

Implementarea ecosistemului Amiral

Mai degrabă decât fiecare pachet să-și mențină propriul fișier manual, logica de generare este centralizată în {admiralci} și oferă un fișier consistent și actualizat fiecărui pachet care se înscrie. Fluxul de lucru reunește conținut din mai multe surse:

• Strategia de programare și ghidurile de testare unitară din {admiraldev}
• Context specific pachetului dintr-un fișier YAML din fiecare depozit (zonă terapeutică, pachete aferente, IG-uri CDISC relevante)
• Contextul ecosistemului descriind modul în care pachetele familiei amiral se încadrează în conducta mai largă pharmaverse
• Fundamentele ADaM care acoperă convențiile variabile-cheie și modelele terminologice controlate

The {admiral} AGENTS.md este substanțială — peste 1.300 de linii de context autogenerat extrase direct din {admiraldev} strategia de programare, utilizarea git și viniete de verificare R CMD. Include chiar și un mecanism de verificare încorporat: agenții sunt instruiți să adauge comentariul # admiral guidelines loaded la prima linie a fiecărui fișier R nou pe care îl creează, confirmând că liniile directoare au fost de fapt citite. Este un mod mic, dar inteligent de a face observabilă conformitatea agentului în timpul revizuirii codului.

Iată o ilustrare simplificată a tipului de conținut pe care îl conține fișierul:

# AGENTS.md — admiral

## Package Overview
{admiral} provides a toolbox for ADaM dataset construction in R,
following CDISC ADaM standards and pharmaverse conventions.

## ADaM Conventions
- Flag variables (ANL01FL, SAFFL, etc.) take values "Y" or NA
- PARAM/PARAMCD pairs must align with CDISC controlled terminology
- ASEQ must be derived as the last step before dataset finalization

## Ecosystem Context
- Test SDTM data: use {pharmaversesdtm} (CDISC pilot data)
- Downstream: datasets consumed by {xportr} for XPT transport files
- Metadata: {metacore}/{metatools} provide spec-driven variable control

## Unit Testing
- Use {testthat} with expect_dfs_equal() for dataset comparisons
- Every new function requires tests for typical use, edge cases, and errors

## Documentation
- Run devtools::document() to regenerate .Rd files — never edit man/ directly
- Update NEWS.md for any user-facing function changes

O notă practică: AGENTS.md la rădăcina depozitului declanșează o NOTĂ în verificarea R CMD, astfel încât fișierul este adăugat la .Rbuildignore. Trăiește și în tests/testthat/ unde îndrumările specifice testării sunt cel mai aproape de locul în care este nevoie. Pachete de extensie ca {admiralonco}, {admiralvaccine}și {admiralpeds} își pot suprapune propriul context, adăugând convenții specifice zonei terapeutice fără a duplica conținutul infrastructurii partajate.

Cum să adoptați acest lucru în pachetul dvs

Dacă mențineți un pachet amiral-familie, adopția este în trei pași:

1. Adăugați un fișier de configurare YAML în depozitul dvs. cu context specific pachetului (zonă terapeutică, pachete aferente, IG CDISC relevante)
2. Faceți referire la fluxul de lucru reutilizabil de la {admiralci} în dumneavoastră .github/workflows/ director
3. Adăuga ^AGENTS.md$ la dvs .Rbuildignore

Fluxul de lucru rulează apoi conform unui program, extragând cel mai recent conținut din {admiraldev} și pachetul dvs. YAML și comiterea unei actualizări AGENTS.md automat.

Resurse