published: false
description: "멈추지 않는 AI 기반 TDD 루프를 설계하는 방법 — GitHub Issues를 메모리로, Playwright를 테스트로, Vercel을 스테이징으로, 그리고 Telegram을 원탭 인간 승인 도구로 활용합니다."
tags: aiagents, tdd, devops, llmops

cover_image: https://images.unsplash.com/photo-1555949963-ff9fe0c870eb?w=1000

요약 (tl;dr) — AI 에이전트에게 GitHub Issue를 지정하면, 에이전트가 실패하는 E2E 테스트를 작성하고, 수정 사항을 구현하며, 전체 출처 메타데이터(provenance metadata)와 함께 커밋하고, 스테이징(staging)에 배포한 뒤, Telegram으로 사용자에게 알림을 보냅니다. 사용자는 한 번의 탭으로 승인하기만 하면 됩니다. 바로 배포(Ship)하세요.

오늘날 AI 지원 개발의 문제점

AI 코딩 어시스턴트를 사용하는 대부분의 팀은 동일한 벽에 부딪힙니다:

• 에이전트의 정체 (Agents stall): IDE에서 인간의 응답을 기다리며 멈춰버립니다.
• 컨텍스트 윈도우 (Context windows) 만료: 작업 중간에 컨텍스트가 만료되어 모든 진행 상황을 잃어버립니다.
• 감사 추적 (Audit trail) 부재: 어떤 모델이 무엇을 작성했는지, 얼마나 걸렸는지, 토큰 비용이 얼마나 들었는지 알 수 없습니다.
• 테스트가 뒷전임: AI는 코드를 먼저 작성하고, 테스트는 때때로 아예 작성되지 않습니다.
• 스테이징 리뷰를 위해 노트북이 필요함: 비동기(async) 워크플로우를 저해합니다.

이 포스트는 이 다섯 가지 문제를 모두 해결하는 체계적인 아키텍처를 설명합니다.

핵심 아이디어: AI의 작업 메모리로서의 GitHub Issues

기초는 간단합니다: GitHub Issue는 모든 작업 단위에 대한 단일 진실 공급원 (Single source of truth)입니다.

각 Issue에는 다음 내용이 포함됩니다:

• 관련 PRD(제품 요구 사항 문서) 섹스에 대한 참조
• 평문 단언(plain-language assertions)으로 작성된 수락 기준 (Acceptance criteria)
• 마지막 반복 스냅샷 (수행된 작업, 실패한 작업, 다음 단계)
• 테스트 산출물(test artefacts) 링크 (비디오, 트레이스, HTML 보고서)
• 모든 AI 세션의 토큰/시간 메타데이터

AI 에이전트가 작업을 시작할 때 Issue를 읽습니다. 작업이 완료되거나 토큰이 소진되어 종료될 때, 에이전트는 다시 Issue에 내용을 기록합니다. 다음 에이전트(또는 새로운 세션의 동일한 에이전트)는 정확히 중단된 지점부터 작업을 이어받습니다.

왜 파일이 아닌 Issue인가요? Issue는 브랜치 전환(branch switches) 시에도 유지되며, 모든 팀원에게 가시적이고, 댓글(comments)과 라벨(labels)을 지원하며, CI/CD 트리거와 네이티브하게 통합됩니다.

6단계 TDD 루프

┌──────────────────────────────────────────┐
│         📋  GITHUB ISSUE                 │
│  PRD ref · Acceptance Criteria · State   │
...

단 하나의 불변 법칙: 코드를 작성하기 전에 반드시 테스트가 **실패(fail)**해야 합니다. 이는 수락 기준(acceptance criteria)을 정밀하게 만들도록 강제하며, 테스트가 올바른 동작을 수행하는지 보장하고, 구현이 완료되었을 때 명확한 신호를 제공합니다.

단계별 상세 분석

1단계 — Issue 컨텍스트 읽기 (Read Issue Context)

issue-knowledge-manager 에이전트가 현재 Issue를 읽고, PRD 참조를 추출하며, 수락 기준(acceptance criteria)을 파싱하고, 마지막 반복(iteration)의 스냅샷을 로드합니다. 이 과정은 약 500 토큰을 소모하며 10초 미만이 소요됩니다. 루프 내의 모든 후속 에이전트는 이 공유된 컨텍스트에서 시작합니다.

2단계 — RED (실패하는 테스트 작성)

qa-test-engineer 에이전트가 수락 기준으로부터 E2E 명세(spec)를 작성합니다. 작업을 넘기기 전에 테스트 스위트(test suite)를 실행하여 새로운 테스트가 실패함을 확인합니다. 테스트가 즉시 통과된다면 이는 기준이 이미 충족되었거나 테스트가 잘못되었다는 것을 의미합니다. 어느 쪽이든, 중단하고 조사해야 합니다.

3단계 — GREEN (구현)

frontend-dev 또는 backend-dev 에이전트가 최소한의 코드 변경 사항을 구현합니다. 그 후 guardian 에이전트가 차이점(diff)을 검토합니다: 새로운 any 타입이 없는지, 중복된 로직은 없는지, 패턴이 코드베이스와 일치하는지 확인합니다. 승인된 후에만 루프는 재실행을 위해 2단계로 돌아갑니다.

4단계 — 출처를 포함한 커밋 (Commit with Provenance)

테스트가 통과되면 release-automation 에이전트가 구조화된 메타데이터와 함께 커밋합니다:

[vscode/claude-sonnet-4] fix: table sort order matches canvas view

Issue: #32
...

커밋 전에 롤백 태그(rollback tag)가 생성됩니다: test-pass/32/2026-03-31. 다른 어떤 AI 환경에서도 단 하나의 명령으로 이 정확한 상태로 롤백할 수 있습니다.

5단계 — 스테이징 배포 (Deploy to Staging)

devops-engineer 에이전트는 모든 tdd/* 브랜치가 자동 스테이징 배포 (staging deploy)를 트리거하도록 보장합니다. 프리뷰 URL (preview URL)은 GitHub Issue에 게시되고 메시징 게이트웨이를 통해 전송됩니다.

6단계 — 모바일에서의 휴먼 리뷰 (Human Review on Your Phone)

오케스트레이터 (orchestrator)는 다음 내용을 포함하는 알림을 보냅니다:

• Playwright 비디오 녹화본 링크
• HTML 테스트 보고서 (HTML test report)
• 스테이징 프리뷰 URL (staging preview URL)
• 합격/불합격 (pass/fail) 상태가 포함된 수락 기준 (acceptance criteria) 체크리스트

당신은 단 한 단어로 답장합니다: APPROVE, CHANGE, 또는 ESCALATE. 나머지는 에이전트가 처리합니다.

안전성: Zero-Stall 보장

AI 에이전트의 가장 큰 실질적인 실패 모드 (failure mode)는 멈춰버리는 것입니다. 여기 전체 안전망이 있습니다:

트리거 (Trigger)                        →   에이전트 응답 (Agent Response)
─────────────────────────────────────────────────────────────────────
토큰 수 (Token count) > 80k (soft)       →   Issue에 스냅샷 저장 · 계속 진행
...

종료 계약 (The exit contract): 깔끔하게 종료되는 에이전트는 항상 이슈 (issue)에 스냅샷을 먼저 작성합니다. 무엇이 완료되었는지, 무엇이 진행 중인지, 작업 중인 정확한 파일과 라인(line)을 기록합니다. 이 스냅샷을 읽는 에이전트는 어떤 환경에서든 정확히 그 지점부터 작업을 계속할 수 있습니다.

에이전트 위임 지도 (Agent Delegation Map)

📋 GITHUB ISSUE  (Source of Truth)
         │
         ▼
...

각 계층은 독립적으로 교체 가능합니다. Playwright를 Cypress로 교체할 수 있습니다. Telegram을 Slack으로 교체할 수 있습니다. 오케스트레이션 계약 (orchestration contract)은 동일하게 유지됩니다.

타임캡슐로서의 커밋 (The Commit as a Time Capsule)

이 시스템의 모든 커밋은 자기 기술적 (self-describing)입니다. 6개월 후에 누군가(또는 다른 AI)가 git 로그를 읽더라도 다음 내용을 정확히 재구성할 수 있습니다:

필드 (Field)	알려주는 내용
커밋 메시지 (Commit message)	무엇이 변경되었는지
...

이것은 오버헤드 (overhead)가 아닙니다. 이것은 **신뢰할 수 있는 AI 지원 개발 (trustworthy AI-assisted development)**의 토대입니다.

반복 스냅샷 형식 (Iteration Snapshot Format)

에이전트가 이슈에 다시 기록할 때마다, 다음과 같은 구조화된 템플릿을 사용합니다:

## Iteration Snapshot — 2026-03-31 14:22

**상태 (Status):** PASS
...

이것이 가능하게 하는 것

이전 (Before)	이후 (After)
IDE 응답을 기다리며 에이전트가 멈춤 (stalls)	타임아웃 발생, 상태 저장, 종료, 사용자에게 알림 (ping)
...

시작하기 체크리스트 (Getting Started Checklist)

• GitHub Issues에 수락 기준 (acceptance criteria) 정의 (단순한 작업 설명이 아님)
• video: 'on' 및 trace: 'on' 설정을 포함한 E2E 테스트 (Playwright) 구축
• 브랜치 기반 스테이징 배포 (Vercel, Netlify 또는 유사 서비스) 구성
• Human-in-the-loop 알림을 위한 메시징 게이트웨이 설정 (Telegram 봇이 가장 쉬움)
• 각 역할별(orchestrator, qa, dev, release, devops) 에이전트 정의 파일 작성
• 커밋 메타데이터 컨벤션 (commit metadata convention) 수립 — 첫날부터 강제 적용
• 토큰 예산 임계값 (token budget thresholds) 설정 — 80k 소프트 제한, 95k 하드 제한을 견고한 기준점으로 삼을 것
• 모든 에이전트가 일관된 상태를 기록할 수 있도록 이슈 스냅샷 템플릿 생성

결론 (Conclusion)

목표는 소프트웨어 개발에서 인간을 제거하는 것이 아닙니다. 테스트 실행, 보일러플레이트 (boilerplate) 작성, 프리뷰 배포, API 키 교체와 같이 인간의 판단이 필요하지 않은 부분에서 인간을 제외하고, 판단이 필요한 부분만을 여러분이 실제로 손에 들고 있는 기기 위로 깔끔하게 드러내는 것입니다.

명확한 수락 기준이 담긴 GitHub Issue, 먼저 실패하는 E2E 테스트, 자신의 출처(provenance)를 스스로 기록하는 커밋, 그리고 휴대폰에서의 원터치 결정 — 이것이 바로 팀이 신뢰하고, 감사(audit)하며, 확장할 수 있는 워크플로우입니다.

AI는 완벽할 필요가 없습니다. 책임감(accountable)이 있어야 합니다.

Tags: #aiagents #tdd #devops #llmops #playwright #vercel #gitops