Implementarea Claude Code: ghid pentru producție

Implementarea Claude Code devine fiabilă numai atunci când agentul poate face diferența între „cererea a fost acceptată” și „producția este sănătoasă”. Dockup oferă acest nivel de deployment printr-un CLI conceput pentru apeluri automate: JSON structurat, coduri reale de ieșire ale procesului și un mod --wait care rămâne conectat până când un deployment ajunge într-o stare terminală.

Acest ghid duce un repository de la lucrul local la o versiune de producție verificată. De asemenea, definește permisiunile pe care ar trebui să le primească Claude Code, dovezile pe care ar trebui să le returneze și momentul în care un om trebuie să aprobe o acțiune distructivă.

De ce are nevoie implementarea Claude Code înainte de producție?

Un coding agent nu ar trebui să înceapă prin a ghici numele unui serviciu sau prin a naviga într-un dashboard. Oferă-i un contract operațional restrâns: să identifice ținta exactă, să efectueze o singură modificare intenționată, să aștepte rezultatul și să raporteze dovezi într-un format ușor de procesat automat.

Cerințele de bază sunt simple:

Cerință	De ce contează	Verificare
Node.js 18 sau o versiune mai nouă	Necesar pentru pachetul Dockup CLI	node --version
Cont Dockup	Deține workspace-urile, serviciile și bazele de date	Autentifică-te la app.dockup.ai
Repository Git	Sursa pentru build-ul serviciului	Confirmă URL-ul remote și branch-ul
Token API	Autentificare non-interactivă	dockup whoami --json
Endpoint de health check sau port de ascultare	Controlează comutarea blue-green	dockup health ... --json

Stabilește limita producției înainte ca agentul să acționeze. Claude Code poate crea un serviciu, seta configurații care nu conțin secrete, declanșa un deploy, inspecta logurile și propune un rollback. Nu ar trebui să șteargă un serviciu, să elimine o bază de date sau să curețe configurația fără aprobarea explicită a unui om.

Dockup consolidează această limită. Comenzile distructive refuză să continue fără --yes și returnează o eroare structurată needs_confirm, în loc să trateze lipsa confirmării ca pe o invitație la improvizație. Pentru o politică mai amplă, consultă măsurile de protecție pentru agenții AI în producție.

Cum instalezi skill-ul Claude Code și te autentifici în siguranță?

Instalează CLI-ul, instalează skill-ul inclus și verifică dacă skill-ul corespunde binarului instalat:

npm install -g dockup-cli
dockup skill install
dockup skill status --json

Programul de instalare scrie skill-ul canonical în ~/.agents/skills/dockup/ și îl leagă în directorul de skill-uri al Claude Code. Deoarece skill-ul este livrat în același pachet npm ca CLI-ul, dockup update le actualizează pe ambele. Claude Code nu trebuie să se bazeze pe o referință copiată de comenzi care poate descrie flag-uri pe care binarul local nu le acceptă.

Folosește un token din environment pentru sesiunile autonome:

export DOCKUP_TOKEN="<TOKEN>"
dockup whoami --json

Un răspuns reușit identifică acel cont și raportează tokenSource ca env. Nu introduce tokenul într-un prompt, nu îl salva în repository și nu îl afișa într-un log CI. Valorile secrete stocate în Dockup sunt mascate atunci când configurația este citită.

Referința completă pentru Dockup CLI este interfața de comenzi oficială. Cu 135 de comenzi, Claude Code ar trebui să consulte referința actuală și skill-ul inclus, nu să se bazeze pe flag-uri reținute din memorie.

Deoarece skill-ul este inclus în pachetul CLI, dockup update actualizează împreună executabilul și instrucțiunile acestuia. Această aliniere a versiunilor este mai sigură decât copierea unei liste de comenzi într-un prompt utilizat pe termen lung.

Cum creează Dockup CLI un serviciu pornind de la Git?

Mai întâi, cere agentului să identifice workspace-ul și evită construirea slug-urilor din numele afișate. Țintele existente sunt returnate de:

dockup services --json

Pentru un repository care nu a fost implementat niciodată, o singură tranzacție poate crea serviciul, îl poate implementa, poate aștepta finalizarea și poate lega directorul curent:

dockup create my-api \
  --repo https://github.com/acme/my-api \
  --project production \
  --deploy \
  --wait \
  --link \
  --json

Când repository-ul conține un Dockerfile, Dockup îl folosește. În lipsa acestuia, Dockup apelează Nixpacks pentru detectarea automată a build-ului. Alegerea este explicată în Nixpacks comparat cu Dockerfile, inclusiv situațiile în care instrucțiunile explicite de build justifică efortul de mentenanță.

Înainte de a reîncerca crearea după o sesiune întreruptă, rulează din nou dockup services --json și inspectează ținta exactă. Dacă serviciul există deja, continuă de la starea sa în loc să emiți o altă cerere de creare.

După ce este legat, comenzile din acel repository pot identifica ținta din .dockup, însă runbook-urile de producție ar trebui să înregistreze în continuare valoarea completă project/service. Descoperirea este limita sigură dintre o acțiune anterioară incertă și o nouă modificare în producție.

Cum trebuie pregătite variabilele de mediu, bazele de date și health check-urile?

Păstrează configurația obișnuită separată de secrete. Claude Code poate seta o valoare publică pentru runtime și un secret mascat, fără să afișeze ulterior valorile secrete stocate:

dockup env set NODE_ENV=production \
  -s production/my-api \
  --json

dockup env set API_KEY="$API_KEY" \
  --secret \
  -s production/my-api \
  --json

Modificările de environment se aplică la următorul deployment. Acest lucru este intenționat: un container care rulează își păstrează environment-ul procesului curent până când este înlocuit. Fluxul complet de operare este prezentat în variabile de mediu și secrete.

Dacă aplicația are nevoie de o bază de date PostgreSQL gestionată, creeaz-o în workspace-ul selectat și citește-i detaliile prin comenzile documentate pentru baze de date:

dockup db create --name main-db --type postgresql --json
dockup db list --json

Rețeaua privată poate oferi ulterior serviciilor și bazelor de date hostname-uri stabile de forma <slug>.internal în cadrul aceluiași proiect. Nu lăsa agentul să inventeze un URL pentru baza de date; folosește informațiile de conectare returnate de Dockup și stochează-le ca secret.

Configurează un readiness gate înainte de prima versiune importantă în producție:

dockup health production/my-api \
  --path /healthz \
  --interval 5 \
  --retries 5 \
  --json

Dockup efectuează deployment blue-green fără downtime și direcționează traficul către noua versiune numai după trecerea health gate-ului. Arhitectura este analizată în deployment-uri fără downtime.

Cum implementează Claude Code și demonstrează că operațiunea a reușit?

Folosește --wait; nu lăsa agentul să interpreteze „deployment pus în coadă” ca „aplicația rulează”:

dockup deploy production/my-api --wait --json

Timeout-ul implicit pentru așteptare este de 900 de secunde. La succes, comanda se încheie cu 0 și returnează starea terminală, durata, ID-ul deployment-ului și URL-ul. Dacă build-ul eșuează, comanda se încheie cu o valoare nenulă și code:"deploy_failed". Dacă operațiunea încă rulează la expirarea timeout-ului, comanda se încheie cu o valoare nenulă și code:"deploy_timeout".

O instrucțiune utilă pentru Claude Code este: „Consideră codul de ieșire al procesului rezultatul principal; apoi rezumă câmpurile JSON.” Astfel sunt evitate formulările optimiste atunci când platforma a returnat deja o eroare.

După succes, colectează trei semnale independente:

dockup status production/my-api --json
dockup uptime production/my-api --hours 24 --json
dockup security production/my-api --json

status confirmă starea serviciului și a celui mai recent deployment. uptime returnează statistici de monitorizare minut cu minut, inclusiv timpul mediu de răspuns și p95. security afișează cea mai recentă scanare CVE a imaginii și scanarea configurației. Aceste verificări completează practicile de securitate la nivelul aplicației; nu înlocuiesc testele aplicației.

Ce ar trebui să facă Claude Code când producția eșuează?

Separă eșecul de build de eșecul la runtime. Un build eșuat necesită cel mai recent log de build:

dockup logs production/my-api --build --json

Un container care a fost construit, dar se închide după pornire, necesită output-ul de runtime:

dockup logs production/my-api --json

Pentru a urmări un build păstrând în același timp loturi ușor de procesat automat, folosește modul NDJSON follow:

dockup logs production/my-api --build -f --json

Comanda se oprește când deployment-ul ajunge într-o stare terminală și se încheie cu o valoare nenulă dacă acesta a eșuat. Claude Code poate transmite progresul fără să inventeze o buclă de polling.

Dacă versiunea curentă nu este sănătoasă și trebuie rerulată o versiune anterioară cunoscută, listează istoricul și folosește ID-ul exact:

dockup deployments production/my-api -n 20 --json
dockup rollback <deploymentId> production/my-api --json

Agentul ar trebui să raporteze ce deployment ID a selectat și de ce. Rollback-ul este o decizie operațională, nu un substitut pentru înțelegerea problemei. Păstrează logul de build, logul de runtime, codul de ieșire și înregistrarea de audit, astfel încât incidentul să poată fi reconstituit.

Un raport final de deployment Claude Code ar trebui să includă ținta, commit-ul sau branch-ul, deployment ID-ul, starea terminală, URL-ul, timpul scurs, rezultatul verificării de health și orice risc care necesită acțiuni ulterioare. Aceste dovezi transformă o acțiune autonomă într-o modificare de producție care poate fi analizată.

Definește un contract de finalizare pentru producție

Înainte de a începe, include în task contractul de finalizare așteptat. O solicitare utilă este: implementează repository-ul legat în production/my-api; așteaptă un rezultat terminal; nu șterge, nu curăța și nu transfera nimic; în caz de eșec, returnează codul erorii și ultimele 60 de linii relevante din logul de build; la succes, returnează statusul, URL-ul, deployment ID-ul, durata și dovezile de health.

Această formulare îi oferă lui Claude Code un obiectiv delimitat și o schemă de raportare. De asemenea, împiedică agentul să modifice „în mod util” infrastructură fără legătură atunci când versiunea eșuează. Agentul poate propune o remediere separată, dar acțiunea de producție rămâne atribuită unei singure solicitări.

Pentru versiuni repetate, păstrează un mic registru al release-urilor în repository sau în sistemul de change management. Înregistrează ținta, branch-ul sursă, calea de health așteptată, timeout-ul normal și acțiunea de recuperare aprobată. O implementare Claude Code este mai sigură atunci când următoarea sesiune nu trebuie să reconstruiască aceste informații din istoricul conversației.

Verifică limita contului înainte de prima scriere

Workspace-urile sunt limite de proprietate și facturare. Cere-i lui Claude Code să afișeze whoami, să listeze serviciile și să precizeze workspace-ul selectat înainte de a modifica ceva. Planul Pro costă 20 USD pe lună și include un credit de utilizare de 20 USD; este planul plătit recomandat. Toate planurile plătite permit workspace-uri, baze de date și deployment-uri nelimitate, în timp ce utilizarea CPU, RAM și a discului este măsurată pe minut și scăzută din soldul planului.

Acest model de tarifare nu schimbă regula de siguranță: un agent ar trebui să verifice utilizarea și aria țintei înainte de a scala sau de a crea resurse suplimentare. Raportul de producție ar trebui să distingă planul de abonament de consumul efectiv măsurat.

Pune fluxul de lucru în producție

Instalează skill-ul în același mediu în care va rula Claude Code, verifică autentificarea și începe cu un serviciu cu risc redus, al cărui endpoint de health este deja cunoscut.

npm install -g dockup-cli
dockup skill install

Prima comandă instalează CLI-ul. A doua instalează skill-ul Dockup compatibil pentru Claude Code și Codex. Începe gratuit la app.dockup.ai.

Întrebări frecvente

Poate Claude Code să facă deploy direct în producție cu Dockup?

Da. Instalează skill-ul Dockup, furnizează un DOCKUP_TOKEN cu scop limitat, identifică ținta exactă project/service și rulează comanda de deploy cu --wait și --json.

De ce ar trebui Claude Code să folosească --wait?

Fără --wait, un răspuns reușit înseamnă doar că deployment-ul a fost pus în coadă. Cu --wait, Dockup se încheie cu 0 numai după succes și returnează în caz contrar erori structurate deploy_failed sau deploy_timeout.

Vede Claude Code valorile secrete stocate?

Dockup maschează valorile secrete în output. Agentul poate seta sau înlocui un secret, însă citirea configurației de environment nu returnează valoarea secretă stocată.

Ce se întâmplă când un repository nu are Dockerfile?

Dockup folosește Nixpacks pentru a detecta și construi automat aplicația. Un Dockerfile din repository are prioritate atunci când este prezent.

Cum poate Claude Code să recupereze după o versiune problematică?

Ar trebui să inspecteze logurile de build și runtime, să listeze istoricul deployment-urilor și să reruleze un deployment anterior cunoscut cu dockup rollback, folosind deployment ID-ul exact.