실전 유즈케이스 2 — 풀스택: 프로덕션 품질의 아티팩트와 테스트로 '자신 있게' 배포하기
풀스택 작업은 "프론트가 보인다/백이 동작한다"만으로 끝나지 않습니다. 배포 순간에 필요한 질문이 늘 따라붙습니다. "요구사항은 정확히 무엇이었나?", "테스트는 어디까지 자동화됐나?", "실패하면 어떻게 되돌리나?", "운영에서 문제를 어떻게 발견하고 추적하나?"
이 챕터의 목표는 기능 추가를 요구사항 정리 → 구현 → 테스트/검증 산출물(Artifacts) → 배포 준비까지 한 태스크로 묶어, '돌아감'이 아니라 '배포 가능'에 도달하는 흐름을 만드는 것입니다. 핵심은 Antigravity에게 일을 시키는 방식이 아니라, 결과를 통과시키는 방식을 먼저 고정하는 데 있습니다.
'배포 가능'의 정의를 먼저 고정한다
프로덕션 품질은 감각이 아니라 게이트(통과 조건)로 만들어야 합니다. 이때 게이트는 "테스트가 녹색이다" 같은 단일 조건이 아니라, 배포 리스크를 줄이는 여러 조건의 묶음입니다.
풀스택 태스크에서 최소한 다음이 충족돼야 '배포 가능'이라고 말할 수 있습니다.
첫째, 요구사항이 테스트로 내려와야 합니다. 요구사항 기반 테스트는 요구사항에서 테스트 목표/조건을 도출해 케이스를 설계하고, 요구사항과 테스트를 추적 가능하게 연결하는 것을 전제로 합니다.5
둘째, 변화가 작은 단위로 쪼개져야 합니다. 장시간 에이전트 작업에서 가장 흔한 실패는 "한 번에 너무 많이 하다가 맥락이 끊기거나", "중간 상태로 남긴 채 다음 세션에 떠넘기는 것"입니다. 이를 막기 위해 진행 로그(예: progress 파일)와 깃 커밋을 남기며, 한 세션에서 한 기능을 '머지 가능한 상태'로 마무리하는 방식이 효과적입니다.1
셋째, 배포 실패를 전제로 설계해야 합니다. 프로덕션에서도 자동 테스트로 변경 결과를 검증하고, 사전에 정의한 조건에서 자동 롤백이 가능해야 배포 속도와 안정성을 함께 가져갈 수 있습니다.3
넷째, 운영에서 "원인을 찾을 수 있는 형태"로 내보내야 합니다. 관측성은 대시보드가 아니라 상관관계입니다. trace_id/request_id 같은 컨텍스트가 서비스 경계를 넘어 전파되고, 로그·트레이스·메트릭이 한 워크플로로 연결될 때 실제로 MTTR이 줄어듭니다.6
이 네 가지를 한 문장으로 요약하면 이렇습니다.
배포 가능 = 요구사항 추적(Traceability) + 작은 변경 단위 + 자동화된 검증/롤백 + 운영에서의 추적 가능성
"한 태스크"를 위한 제출물(Artifacts) 체크리스트
앞서 다룬 Artifact Pack 개념을 풀스택 배포 맥락으로 가져오면, "무조건 있어야 하는 제출물"을 태스크 출력물로 고정하는 일이 됩니다. 이 출력물이 모이면, Antigravity가 어떤 방식으로 일했든 리뷰와 승인이 쉬워집니다.
권장하는 풀스택 배포 태스크 출력물은 다음 7개입니다.
요구사항 요약 + 수용 기준(AC): 기능/비기능(성능·보안·제한사항) 포함
테스트 매트릭스(요구사항 ↔ 테스트 연결표): 어떤 AC가 어떤 테스트로 커버되는지
구현 계획(Plan) + 결정 로그(Decision log): 왜 이렇게 설계했는지까지 남김
변경 목록(디프 요약) + 마이그레이션/호환성 메모: 스키마, API 계약, 프론트 영향
CI 결과 링크 + 핵심 테스트 증거: 유닛/통합/E2E, 필요 시 스크린샷/리포트
배포 전략 + 롤백 런북: feature flag, canary, 롤백 트리거
운영 관측성 변경 요약: 로그 필드, trace 전파, 알람/SLO 변화
여기서 중요한 포인트는 "문서가 많아야 한다"가 아니라, 배포에 필요한 질문이 이 7개로 모두 답이 나야 한다는 점입니다. 계획을 1급 아티팩트로 두고(작업 규모에 따라 가볍게/무겁게), 진행과 결정을 리포지토리에 남기는 방식은 에이전트 중심 개발에서도 반복적으로 권장됩니다.2
실전 시나리오: '프로필 이미지 업로드' 기능을 배포 가능한 수준으로
예시로 "사용자가 프로필 이미지를 업로드하고, 프로필 화면에 즉시 반영된다"를 추가한다고 가정해보겠습니다. 풀스택이기 때문에 프론트(UI), 백엔드(API), 저장소(S3 등), DB(메타데이터), 권한(인가), 운영(로그/모니터링)까지 모두 걸립니다.
1) 요구사항을 '테스트 가능한 문장'으로 바꾼다
Antigravity에게 바로 구현을 시키기 전에, 먼저 AC를 테스트 가능한 형태로 정리합니다.
예를 들면 다음과 같습니다.
사용자는 JPG/PNG 이미지를 업로드할 수 있다.
5MB를 초과하면 업로드가 거절되고, UI에 에러 메시지가 표시된다.
업로드 성공 시 프로필 화면에 새 이미지가 즉시 표시된다(캐시 고려).
업로드는 로그인 사용자만 가능하고, 타인의 프로필은 수정할 수 없다.
업로드 요청/응답은 trace_id로 추적 가능해야 한다.
그리고 이 AC들을 테스트 매트릭스로 바로 연결합니다. 요구사항 기반 테스트의 핵심은 "요구사항에서 테스트 목표/조건을 도출하고", 요구사항과 테스트의 링크를 유지하는 것입니다.5
2) 계획(Plan)을 '구현 순서'가 아니라 '통과 조건' 중심으로 쓴다
계획은 "무엇을 만들지"보다 "어떻게 통과시킬지"가 중심이어야 합니다.
예시 계획 구조는 다음처럼 잡습니다.
API 계약 확정(요청 스키마/응답 스키마, 에러 코드)
저장소 업로드 방식 결정(직접 업로드 vs 서버 프록시, 서명 URL 등)
백엔드 구현 + 유닛 테스트
통합 테스트(스토리지 연동 또는 대체 전략)
프론트 구현 + E2E 경로(업로드→반영) 테스트
관측성(로그 필드/trace 전파) 추가
배포 전략(Feature flag + canary)과 롤백 트리거 정의
여기서 '결정 로그'를 붙입니다. 예컨대 "직접 업로드를 선택한 이유", "파일 검증을 서버에서 한 이유", "이미지 리사이즈를 어디서 하는지" 같은 결정을 남겨야 다음 변경에서 흔들리지 않습니다. 계획과 결정 로그를 리포지토리에 남기는 습관은 에이전트 작업에서도 품질을 지탱하는 기둥으로 다뤄집니다.2
3) 구현은 '세션/커밋 단위로 머지 가능'하게 쪼갠다
풀스택 기능은 한 번에 끝내려 하면 중간 상태가 남기 쉽습니다. 장시간 에이전트 작업에서 검증 가능한 진전을 만들기 위해서는, 진행 파일(예: progress)과 깃 커밋으로 "다음 세션이 바로 이어받을 수 있는 상태"를 만드는 것이 효과적입니다.1
이 시나리오에서는 보통 다음 순서가 안전합니다.
1커밋: API 스켈레톤 + 에러 규약 + 최소 유닛 테스트
2커밋: 업로드 검증(파일 타입/크기) + 권한 체크 + 유닛 테스트 보강
3커밋: 스토리지 연동 + 통합 테스트(또는 테스트 더블)
4커밋: 프론트 업로드 UI + 성공/실패 상태 처리
5커밋: E2E(업로드→반영) + 관측성 + 문서/런북
각 커밋은 "돌아가는 중간 결과"가 아니라, 메인 브랜치에 합쳐도 괜찮은 상태를 목표로 합니다. 그래야 '진짜로' 다음 단계(테스트/릴리즈)가 빨라집니다.1
4) 테스트는 피라미드로 설계하고, 파이프라인에 넣는다
지속 배포에 가까워질수록 테스트는 사실상 유일한 자동 게이트가 됩니다. 그래서 테스트는 빠른 것부터(유닛) 넓게 깔고, 중요한 통합 경로를 덮고, 꼭 필요한 사용자 여정만 E2E로 얇게 올리는 피라미드 형태가 안정적입니다.4
이 기능에서 추천하는 자동 테스트는 다음 조합입니다.
유닛: 파일 검증 로직, 권한 체크, 메타데이터 저장 로직
통합: 업로드 요청→스토리지 저장→DB 반영(테스트 환경에서 재현)
E2E: 로그인→프로필로 이동→업로드→새 이미지 표시(핵심 1~2개 경로만)
풀스택 CI/CD는 프론트와 백을 분리한 채로가 아니라, 하나의 파이프라인 관점에서 속도·품질·보안·신뢰성을 함께 다루는 것이 출시를 빠르게 만듭니다.7
5) 배포 전략(Feature flag / Canary)과 자동 롤백 조건을 '태스크 안'에 넣는다
배포를 운영팀의 일로 남기면, 결국 "돌아감"에서 멈춥니다. 반대로 배포 전략과 롤백 기준을 태스크 산출물로 포함하면, 리뷰가 끝나는 순간 배포 준비도 끝납니다.
권장 흐름은 이렇습니다.
Feature flag로 기능을 기본 OFF로 배포한다.
내부 사용자/스태프만 ON → 문제 없으면 점진 확대
Canary로 일부 트래픽에만 노출하고 지표를 본다.4
아래 조건 중 하나라도 만족하면 자동 롤백되게 설계한다: 자동화된 프로덕션 테스트 실패, 에러율/지연시간이 성공 기준을 벗어남, 헬스체크 실패 등.3
AWS Well-Architected에서도 프로덕션 배포 시 자동 테스트로 변경을 검증하고, 사전 정의한 조건에서 자동 롤백이 가능해야 배포 신뢰도가 올라간다고 명확히 권장합니다.3
6) 운영 관측성(Observability)을 "나중에"가 아니라 "이번 태스크의 일부"로 만든다
업로드 기능은 운영에서 이슈가 자주 납니다. 파일이 커서 실패하거나, 특정 브라우저에서만 깨지거나, 캐시로 인해 "반영이 안 됐다"는 문의가 나오기도 합니다.
그래서 이번 태스크에서 관측성 변경을 명시합니다.
모든 업로드 요청에 trace_id/request_id를 붙이고, 로그·트레이스·에러 리포트에서 동일 키로 찾을 수 있게 한다.6
multi-tenant 또는 조직 단위가 있다면 tenant_id 같은 컨텍스트도 함께 남긴다.6
민감정보(이미지 원본, 개인정보)는 로그/텔레메트리 단계에서 마스킹/차단한다.6
관측성은 "알람이 많다/대시보드가 많다"가 아니라, 장애 시점에 원인을 빠르게 좁힐 수 있는 상관관계를 제공할 때 의미가 있습니다.6
Antigravity 태스크 프롬프트(템플릿)
아래는 이 챕터의 흐름을 한 태스크로 묶기 위한 프롬프트 예시입니다. 여러분의 스택에 맞게 파일명과 도구만 바꾸면 됩니다.
목표: 프로필 이미지 업로드 기능을 '배포 가능' 상태로 완료한다.
산출물(반드시 제출):
requirements.md (AC 포함)
test-matrix.md (AC↔테스트 연결)
plan.md + decisions.md
ci-proof.md (CI 링크, 핵심 테스트 결과)
deploy.md (feature flag/canary/rollback 조건)
observability.md (로그 필드/trace 전파/알람)
작업 규칙:
한 번에 하나의 기능 단위로 진행하고, 매 단계는 머지 가능한 상태로 끝낸다.
테스트를 삭제/완화해 통과시키지 말 것. 부족하면 테스트를 추가한다.
프로덕션 롤백 기준을 수치/조건으로 명확히 정의한다.
모든 변경은 커밋 단위로 남기고 progress 파일에 요약한다.
이 템플릿의 의도는 단순합니다. "구현"을 요청하는 것이 아니라 배포에 필요한 증거 묶음을 요청하는 것입니다.
요약: '기능 개발'이 아니라 '배포 가능한 변경'을 생산하는 루틴
풀스택에서 자신 있게 배포하려면, Antigravity가 코드를 잘 짜는 것만으로는 부족합니다. 요구사항을 테스트로 연결하고,5 계획과 결정을 아티팩트로 남기며,2 작은 단위로 머지 가능한 상태를 유지하고,1 자동 테스트·점진 배포·자동 롤백을 배포 파이프라인의 일부로 설계해야 합니다.34 여기에 운영 관측성까지 태스크 안에 포함하면, 배포 이후의 불확실성도 줄어듭니다.6
다음으로는 이 흐름이 팀 단위로 커졌을 때, 여러 워크스페이스를 운영하며 일관된 품질 게이트를 유지하는 방법을 살펴보겠습니다.
참고
1Effective harnesses for long-running agents
2Harness engineering: leveraging Codex in an agent-first world
3OPS06-BP04 Automate testing and rollback (AWS Well-Architected Framework)
4Continuous Deployment Best Practices for DevOps Teams in 2025
5Requirements-based testing (IBM Docs)
6Observability Tooling: How to Build a Production-Grade Stack That Actually Reduces Incidents
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.