Agenții IA pot accelera dezvoltarea software, dar eficiența lor în proiecte reale depinde mai mult de calitatea contextului în care aceștia operează. În dezvoltarea aplicațiilor mobile, acest lucru devine esențial: o interfață aparent simplă depinde de arhitectură, state management, navigație, lifecycle, servicii, repository-uri, localizare, accesibilitate, testare, design system și constrângeri de platformă.
Acest white paper propune un model practic de Context Engineering pentru dezvoltarea aplicațiilor mobile cu agenți IA. Modelul limitează accesul agentului la zonele de interes ale taskului vizat, printr-un set controlat de informații relevante: reguli arhitecturale, taskuri structurate, context de design, politici de securitate, fișiere de memorie ale proiectului, teste automate, checklisturi de testare manuală și puncte clare de intervenție umană.
Lucrarea descrie un workflow agentic complet, de la definirea unui task precum Project-001: Initial app setup, până la implementarea de UI, review, testare, actualizare de memorie a agentului și documentație. Procesul include separarea clară între View, ViewModel, Services, Repositories, AppState, AppRouter și AppEnvironment, precum și introducerea unei strategii de testare printr-un task ulterior specializat.
Concluzia este că programarea agentică presupune proiectarea unui mediu de lucru în care agentul primește contextul potrivit, produce schimbări mici și verificabile, se oprește în fața deciziilor arhitecturale și rămâne sub controlul explicit al programatorului. Viitorul dezvoltării asistate de IA va aparține sistemelor în care contextul devine infrastructură: agentul lucrează cu direcție, schimbările rămân verificabile, iar dezvoltatorul păstrează controlul arhitectural.
Agenții IA sunt tot mai prezenți în dezvoltarea software. Pe măsură ce utilizarea lor trece de la experimente izolate la fluxuri zilnice de dezvoltare, consumul de tokeni devine o problemă economică directă pentru echipe și organizații. Un agent folosit necalibrat poate consuma context, poate produce schimbări greșite și poate genera iterații suplimentare. Un agent folosit într-un mediu proiectat explicit poate reduce timpul de implementare, crește consistența codului și poate limita risipa operațională.
În lipsa unor limite clare, agenții IA construiesc module duplicate, introduc componente care există deja, modifică soluții validate și deviază de la arhitectura proiectului din cauza unor instrucțiuni incomplete sau ambigue. Rezultatul poate părea corect la prima vedere, dar devine costisitor în review: mai multe fișiere modificate, mai mult context consumat, mai multă muncă manuală și mai multe iterații pentru a readuce implementarea în direcția corectă.
Dezvoltarea aplicațiilor mobile amplifică această problemă. Un ecran aparent simplu depinde de mai multe straturi: View, ViewModel, Services, Repositories, AppState, AppRouter, AppEnvironment, design system, localizare, accesibilitate, testare, configurație și lifecycle. Agentul trebuie să cunoască aceste relații înainte să modifice codul.
Acest articol propune o abordare practică de Context Engineering pentru aplicații mobile. Abordarea descrie cum poate fi proiectat, structurat și livrat contextul relevant către un agent IA care lucrează într-un codebase real. Modelul urmărește obținerea unor schimbări mici, verificabile și consistente arhitectural, cu programatorul păstrat explicit în bucla de decizie.
Lucrarea se concentrează pe calibrarea contextului pentru un singur agent executant. Orchestrarea unui sistem multi-agent presupune alte mecanisme de coordonare, alte tipuri de memorie și alte puncte de sincronizare. Acest subiect rămâne în afara scopului lucrării.
Scenariul este familiar. Dezvoltatorul îi cere agentului: "implementează acest ecran". Agentul generează codul, aplicația rulează, iar vizual pare acceptabil. Apoi apare review-ul de diff: arhitectura proiectului a fost ignorată, logica de business a fost duplicată, localizarea este inconsistentă, state-ul este gestionat într-un loc greșit și au apărut componente UI care existau deja în design system.
Agenții IA sunt generatoare de tipare extrem de capabile, care operează în interiorul unei ferestre de context. Ei nu înțeleg implicit produsul, istoria arhitecturală, deciziile echipei sau compromisurile din cod. Calitatea rezultatului depinde direct de calitatea contextului în care agentul lucrează.
În programarea tradițională, un dezvoltator nou citește proiectul, învață arhitectura, pune întrebări, înțelege convențiile de cod, primește feedback la code review și se normalizează treptat în fluxul echipei. În programarea agentică, aceste informații trebuie externalizate către agent sub formă de context structurat.
Context Engineering este procesul de a selecta, structura, menține și livra informația potrivită către un agent IA, astfel încât acesta să poată duce la bun sfârșit un task de software engineering într-un anumit produs, proiect, codebase, arhitectură și workflow de echipă.
Diferența față de Prompt Engineering este prezentată în Tabelul 1.
| Prompt Engineering | Context Engineering |
|---|---|
| Se concentrează pe o instrucțiune punctuală. | Se concentrează pe mediul informațional în care operează agentul. |
| Este de obicei ad-hoc. | Este repetabil, versionat și întreținut în repository. |
| Utilizatorul explică manual contextul taskului. | Proiectul oferă un context pack reutilizabil și actualizabil. |
| Este potrivit pentru taskuri mici și izolate. | Este necesar pentru codebase-uri complexe și reale. |
Tabelul 1: Prompt Engineering vs Context Engineering
O parte importantă din eșecuri și din consumul risipitor de tokeni apare deoarece modelul primește prea puțin context, prea mult context irelevant și depășit, instrucțiuni ambigue, reguli arhitecturale incomplete, acceptance criteria neclare, lipsa unui feedback loop sau/și documentație incompletă sau neactualizată.
Contextul unui agent trebuie proiectat. În cazul unei aplicații mobile, această proiectare ia forma unui harness contextual dedicat.
În echipele umane, când un membru nou se alătură unui proiect, primește informații contextuale despre produs, documente arhitecturale, explicații de domeniu, exemple, feedback la code review și taskuri mici pentru acomodare. Agenții IA au nevoie de o disciplină similară.
Figura 1. : Initial Setup pentru o aplicație mobilă
În Figura 1 este prezentat un harness contextual pentru o aplicație mobilă. Acesta definește modul în care agentul operează în proiect și îi oferă acces controlat la informațiile necesare pentru implementarea taskurilor.
Harnessul funcționează ca infrastructură de lucru pentru dezvoltare asistată de IA. Fișierele sale sunt păstrate în repository pentru a putea fi versionate, revizuite și îmbunătățite în timp.
Fișierul AGENTS.md descrie regulile generale de funcționare ale agentului. El stabilește:
ce fișiere trebuie citite înainte de implementare;
ce zone sunt protejate;
când agentul trebuie să ceară aprobare;
cum trebuie raportate riscurile și presupunerile;
cum trebuie tratate testele;
cum trebuie propuse update-urile de memorie;
Acest fișier funcționează ca un contract operațional. Agentul primește un set de reguli persistente, versionate împreună cu proiectul.
Directorul ai-context/ conține contextul stabil al proiectului. Aici sunt descrise produsul, arhitectura, modelele de date, strategia de state management, navigația, networkingul, localizarea,
accesibilitatea, testarea, design systemul, configurările de securitate și harta repository-ului. Aceste fișiere răspund la întrebări precum:
Ce construim?
Cum este organizat proiectul?
Unde locuiește state-ul?
Cum se face navigația?
Cum sunt accesate datele?
Cum se testează task-urile?
Ce reguli de localizare și accesibilitate trebuie respectate?
Directorul ai-tasks/ conține taskurile concrete care urmează să fie implementate de agent. Fiecare task definește scopul, acceptance criteria, fișierele de context relevante, fișierele protejate și cerințele de testare. După finalizare, taskurile pot fi mutate în DONE/ pentru a păstra istoricul.
Un task bine scris reduce ambiguitatea. Agentul pornește de la o descriere structurată a muncii care trebuie făcută, cu limite și criterii de verificare.
Directorul ai-design/ conține contextul de design: sursele Figma, mappingul dintre componentele din design și componentele din cod, template-uri de Design Extraction Report și checklisturi de Visual QA.
Pentru aplicațiile mobile, designul este important deoarece un ecran conține stări, componente, reguli de spacing, typography, culori, dark mode, large text și constrângeri de accesibilitate.
Directorul ai-memory/ reprezintă memoria proiectului. Aici sunt păstrate deciziile recurente, patternurile validate, riscurile cunoscute și vocabularul comun al echipei. Această memorie reduce nevoia ca agentul să redescopere aceleași reguli la fiecare task.
Memoria proiectului trebuie actualizată cu grijă. Agentul poate propune update-uri, iar dezvoltatorul decide ce merită păstrat.
Directorul ai-decisions/ păstrează deciziile importante sub formă de Architecture Decision Records. Acestea sunt utile atunci când un task introduce o schimbare arhitecturală sau când echipa trebuie să documenteze un compromis tehnic.
Directorul ai-workflows/ conține prompturi și template-uri reutilizabile pentru planificare, implementare, self-review, update de memorie, testare manuală și Pull Request. Scopul său este să standardizeze interacțiunea cu agentul.
Directorul ai-safety/ descrie zonele protejate, politica de secrete și regulile de sandboxing. Acest director reduce riscul ca agentul să modifice configurații sensibile sau să acceseze fișiere care nu sunt necesare pentru taskul curent.
O structură generică pentru un proiect mobile poate arăta astfel:
MobileApp/
AGENTS.md
ai-context/
product.md
architecture.md
domain-model.md
state-management.md
navigation.md
networking.md
localization.md
accessibility.md
testing.md
design-system.md
security-configuration.md
repo-map.md
ai-tasks/
Project-001-initial-app-setup.md
Project-002-design-system.md
Project-003-navigation.md
DONE/
ai-design/
design-sources.md
component-mapping.md
design-extraction-template.md
visual-qa-template.md
ai-memory/
architecture-decisions.md recurring-patterns.md
known-risks.md glossary.md
ai-decisions/
Project-003-navigation-through-router.md
Project-004-viewmodels-own-presentation-state.md
ai-workflows/
agent-planning-prompt.md
agent-implementation-prompt.md
agent-self-review-prompt.md
memory-update-prompt.md
manual-qa-template.md pr-template.md
ai-safety/
protected-files.md
secrets-policy.md
App/
Features/
Services/
Repositories/
DesignSystem/
Tests/Această structură separă codul aplicației de infrastructura de lucru a agentului. Directoarele App/, Features/, Services/, Repositories/, DesignSystem/ și Tests/ aparțin aplicației. Directoarele care încep cu ai- descriu contextul, memoria, regulile și workflow-ul agentului.
Un context bun pentru agent trebuie să fie relevant, actualizat, comprimat, specific per task, structurat, explicit și testabil. În oglindă, un context deficitar este prea mare, outdated, contradictoriu, implicit, împrăștiat sau/și plin de fișiere irelevante.
După ce acest harness există în repository, fluxul de lucru al dezvoltatorului devine mai predictibil.
Pentru a începe implementarea unui task, dezvoltatorul pornește prin scrierea unui fișier în ai-tasks/. Acest fișier descrie cerințele taskului, acceptance criteria, linkurile de design, linkul către Ticket și fișierele de context relevante.
Apoi dezvoltatorul cere agentului un plan. Agentul citește doar fișierele relevante, produce un plan, enumeră fișierele pe care se așteaptă să le modifice, listează riscurile și marchează eventualele puncte de decizie. Dezvoltatorul aprobă, respinge sau rafinează planul.
După aprobarea planului, agentul execută implementarea, scrie sau actualizează testele automate, produce checklisturi de testare manuală și își face un self-review. La final, dezvoltatorul verifică implementarea, rulează testele necesare, inspectează git difful și decide dacă schimbarea este acceptabilă.
În Figura 2 este afișat procesul complet de execuție.
Figura 2: Procesul de dezvoltare cu Context Engineering
Procesul poate fi rezumat astfel:
Dezvoltatorul creează sau rafinează taskul în ai-tasks/.
Taskul referențiază linkul de Ticket, linkul de design și fișierele de context relevante.
Dezvoltatorul cere agentului un plan în mod read-only.
Agentul produce planul, riscurile, presupunerile și strategia de testare.
Dezvoltatorul aprobă sau modifică planul.
Agentul implementează în mod workspace-write.
Agentul scrie sau actualizează testele automate.
Agentul produce Manual QA și Visual QA checklist.
Agentul își face self-review pe baza contextului proiectului.
Dezvoltatorul face review la git diff și testează manual flow-ul.
Dacă există conflict arhitectural, agentul se oprește și propune decision branches.
Dacă implementarea este acceptată, agentul propune update-uri pentru ai-memory/ sau ai-decisions/.
Dezvoltatorul aprobă update-urile de memorie.
Schimbarea este committed, se creează un Pull Request și se face merge-ul feature-ului.
Această buclă obligă agentul să lucreze în limite clare. Agentul pornește de la task și de la contextul explicit selectat pentru acel task. Repository-ul complet rămâne disponibil acolo unde este necesar și justificat.
Un task este contractul dintre dezvoltator, agent, design, ticket și repository. El trebuie să fie suficient de clar încât agentul să poată planifica și suficient de limitat încât schimbarea să rămână verificabilă.
Un task poate avea următoarea structură:
# Project-001: Initial app setup
## Source
Ticket:
Design:
Type:
Priority:
## Problem
Describe the current problem.
## Goal
Describe the desired outcome.
## Acceptance criteria
- [ ] ...
- [ ] ...
- [ ] ...
## Relevant context files
Read only:
- ai-context/architecture.md
- ai-context/state-management.md
- ai-context/navigation.md
- ai-context/testing.md
- ai-context/security-configuration.md
- ai-context/repo-map.md
## Protected areas Do not modify:
- production configuration
- secrets
- signing
- CI/CD
- payment
- authentication
## Expected agent output before editing
- implementation plan
- expected files to modify
- assumptions
- risks
- decision points
- automated test plan
- manual test plan
## Expected agent output after editing
- files changed
- acceptance criteria coverage
- tests added or updated
- tests run
- tests not run and why
- manual QA checklist
- memory or documentation updates proposedPrin această structură, taskul devine un mecanism de control. Agentul primește scop, limite, context și criterii de verificare.
Partea a II-a a acestui articol va fi publicată în următorul număr al revistei.
de Vlad Petrean
