Recent, Anthropic a lansat certificarea Claude Certified Architect – Foundations, structurată pe patru mari zone. E genul de lansare la care o primă reacție ar fi: "Ah, încă un curs teoretic și o insignă de pus pe LinkedIn". Dar a apărut un thread foarte interesant pe X de la @hooeem care demontează rapid ideea asta. Curriculumul din spate este, de fapt, o hartă extrem de clară pentru cum ar trebui să construim agenți AI care chiar funcționează. Nu la nivel de demo-uri fragile pe care să le arăți la o conferință, ci la nivel de arhitectură de producție.
Ce scoate în evidență thread-ul este foarte pragmatic. Examenul nu testează (doar) teorii abstracte, ci te forțează să înțelegi unde greșesc, de fapt, majoritatea dezvoltatorilor când „se joacă” cu Anthropic MCP (Model Context Protocol), Claude Code și agenți autonomi.
Am citit argumentele și le-am transpus într-un limbaj simplu, extrăgând esențialul din acest „ghid ascuns”. Fără jargon inutil, doar pașii critici dacă vrei ca aplicația ta cu AI să nu o ia razna la o simplă excepție.
1. Tool Design & MCP: Descrierile sunt inima agentului
Prima capcană în care picăm cu toții este să credem că LLM-ul este suficient de inteligent ca să „intuiască” ce face un program sau o funcție din proiect. În programa Anthropic, Tool Design & MCP acoperă aproximativ 18% din examen. Iar aici apare observația critică a lui @hooeem:
„Descrierile tool-urilor (tool descriptions) sunt cel mai neglijat element din orice sistem de agenți. Modelul alege tool-urile DOAR pe baza description-ului. Descrierile vagi duc la misrouting.”
Modelul nu îți citește logica internă a tool-ului. Nu are o intuiție profundă legată de ce poate să facă funcția aia denumită sumar fetchData(). El vede un nume, citește textul tău explicativ și decide. Ai făcut o descriere ambiguă sau leneșă? Așteaptă-te ca agentul să selecteze tool-ul complet greșit sau să refuze să îl folosească.
Nu rezolvi problema asta inventând un sistem complex de dirijare, cu vreun classifier super complicat sau cu zeci de exemple few-shot. Rezolvarea e simplă și de bun simț: trebuie să scrii descrieri clare, cu intenții, input-uri și output-uri bine explicate.
Nu-i da prea multe tool-uri deodată
O altă regulă de bază din thread: nu lăsa 18 tool-uri pe mâna unui singur agent. Când ai un spațiu de posibilități atât de mare, modelele se încurcă în selecție. Soluția sănătoasă? Creează sub-agenți specializați. Unul cu 3-4 tool-uri pentru extragerea de date, altul cu 3-4 tool-uri pentru redactare. Totul supervizat de o parte logică de orchestrare, care pasează execuția cui trebuie.
2. Capcana CLAUDE.md: De ce nu merge AI-ul tău și la alții în echipă
La capitolul Claude Code Configuration (în jur de 20% din certificare), s-a atins un subiect pe care multe echipe îl tratează superficial: ierarhia de fișiere CLAUDE.md.
Ai trei niveluri la care poți furniza instrucțiunile, de la general la specific:
- User-level: Fișierul este pe mașina ta locală (ex: în folderul tău home).
- Project-level: În repository, vizibil pentru toate componentele acelei soluții.
- Directory-level: Specific pentru un context clar, de la foldere precum
docs/,front-end/până la module punctuale.
Unde apar cele mai mari probleme? Ați ghicit, la instalările pur locale. Dezvoltatorul își configurează agentul pe laptopul propiu cu instrucțiuni perfecte (la nivel user). Agentul îi livrează zilnic cod excepțional. Dar când un coleg trage proiectul din git, asistentul lui este un dezastru. De ce? Fiindcă regulile critice nu erau salvate în version control. Pentru un flux de lucru previzibil, regulile aplicației trebuie să stea neapărat în repository-ul organizației.
3. Schemele JSON îți garantează structura, nu adevărul
Toată industria iubește Structured Outputs. Este foarte satisfăcător să definești un JSON Schema strict, să-l arunci spre model și să primești date gata formatate, ușor de parsat. Doar că, exact cum ne atrage atenția și acest curriculum:
„Tool_use cu JSON schemas elimină erorile de sintaxă, dar nu și erorile semantice.”
Pe românește, LLM-ul va formata perfect cele mai gogonate minciuni. Va asocia greșit date sau va trage concluzii eronate, dar va respecta tipul de date ca un elev obedient. E frumos ambalat, se citește cu succes într-o funcție, dar conține o iluzie. Soluția pe care toți trebuie s-o adoptăm este integrarea obligatorie a unur teste automate și a unor validări de business pe fiecare output valoros scos de LLM. Schema garantează parse-ul, nu business logica.
4. Nu lăsa AI-ul să inventeze: Folosește câmpuri Nullable
E un detaliu fin, dar esențial. Imaginează-ți că agentul trebuie să extragă un număr de înmatriculare dintr-un buletin rutier. Dacă în schema JSON declari câmpul ca fiind un format obligatoriu de tip string, LLM-ul simte presiunea necesității acelei valori. Și, dacă n-o găsește în text... ei bine, va inventa el ceva. Apare dintr-odată pe un borderou o plăcuță pe care el consideră că ar fi nimerit să o folosească. Ai halucinație pură de tip structural.
Modul în care oprești acest instinct narativ? Marchezi câmpurile respective ca nullable. Dacă modelul învață că este permis să întoarcă un null cinstit și curat când nu are dovada în text, te scutește de un dezastru logic, decizional sau chiar financiar, mai încolo. Fără frică de null. Asta e frumusețea unui control mai bun peste context.
Exercițiul suprem: Primul domeniu în practică
Thread-ul ne oferă și o scurtătură practică. Ca să internalizezi tot ce contează pentru Agentic Architecture, încearcă să construiești un agent mic care dispune de:
- 3-4 tool-uri MCP funcționale și cu descrieri ireproșabile.
- Stop Reason Handling: Agentul să poată justifica programatic de ce s-a oprit – a finalizat un proces, a fost oprit de limita maximă de reîncercări sau nu i-au ajuns tokenzii?
- Un PostToolUse Hook: Un pas simplu automat de a normaliza / procesa formatele de date instant după ce o acțiune este finalizată, înainte de runda următoare de raționament.
- Un Policy Interception Hook: Un gardian care se uită peste conținutul returnat sau procesat și este gata să dea deny operațiunii direct, dacă este încălcată vreo politică de etică ori securitate.
Pare copleșitor la început, dar fix aceste concepte separă niște if-else-uri cu OpenAI sau Claude API în spatele lor de o adevărată arhitectură pe care o poți escala alături de clienți.
Checklist pentru non-tehnici: Întrebări vitale pentru noile tale proiecte AI
Chiar dacă rolul tău este mai mult de produs sau de coordonare, ghidul ăsta din spatele validării pentru Claude se simte foarte la un loc într-o negociere sau revizuire tehnică cu o echipă proaspătă:
- Câte acțiuni (tool-uri) directe poate folosi agentul ăsta? Răspunsul sănătos este maxim 4-5. Dacă se prezintă „Agentul Suprem cu 24 de tool-uri gata de apelat”, e de oprit procesul pe loc.
- Cum ne asigurăm cu schemele astea JSON că datele nu sunt halucinate? Răspuns corect: Avem logici de validare și fallback și definim unde se poate câmpul cu parametrul „nullable” când AI-ul e nesigur.
- În ce stadiu prindem erorile ca să nu facă sistemul o acțiune complet iremediabilă? Nu treceti de pasul în care echipa tehnică trebuie să implementeze hook-uri de interception policy, pe baza unor reguli foarte detaliate.
Revenind la certificarea Anthropic, ea se simte, din tot ce vedem public, ca un proces complet de igienizare și maturizare a industriei. Mai puține demouri care fac lucruri fanteziste, mai multă stabilitate, claritate și fiabilitate într-un set de reguli și principii arhitecturale pe care le putem aplica cu toții.
Surse și Resurse Utile
- Thread original X (Twitter): @hooeem despre Claude Architect
- Oficial Anthropic: anthropic.com
