제 9강. 코드 너머의 자동화 — Agent Operable System

꿀팁 — 이것만 알면 시킬 수 있다

코드만 에이전트가 다루면 끝이 아니다. 빌드, 배포, 모니터링까지 에이전트에게 맡기려면, 시스템 전체가 에이전트에게 읽히는 구조여야 한다. Docker 내부를 이해할 필요 없다. 에이전트가 전부 한다.

에이전트에게: “서버에 /health 엔드포인트를 추가해. DB 연결 상태, 에러 비율, 업타임을 JSON으로 반환하게 해.”

이 한 마디가 에이전트에게 시스템 상태를 읽을 수 있는 눈을 준다. /health가 있으면 에이전트가 “서버가 살아 있는가?“를 기계적으로 확인할 수 있다. 없으면 눈을 감고 수술하는 의사다.

에이전트에게: “이 프로젝트를 docker-compose.yml로 구성해. 앱 서버랑 DB가 포함되어야 해. docker compose up 하면 전부 뜨게 만들어.”

Docker가 뭔지 몰라도 된다. 앱을 상자에 담아서 어디서든 똑같이 실행되게 하는 도구라는 것만 알면 충분하다. 설치부터 설정까지 에이전트가 처리한다.

에이전트에게: “배포 실패 시 자동 롤백되도록 설정해. /health가 실패하면 이전 버전으로 되돌려.”

에이전트는 반드시 실수한다. 실수를 되돌릴 수 있어야 한다. 이 한 마디가 안전망이다.

세 마디. 서버에 눈을 달고, 시스템을 선언하고, 안전망을 깐다. 나머지는 에이전트가 한다.

찍먹 체험

1강에서 만든 앱(또는 아무 프로젝트)을 Claude Code로 열고:

“서버에 /health 엔드포인트를 추가해. DB 연결 상태, 에러 비율, 업타임을 JSON으로 반환하게 해. 기존 Hurl 테스트가 전부 통과해야 해.”

에이전트가 코드를 추가하면:

“/health가 200을 반환하는 Hurl 테스트를 만들어. JSON 응답에 db, status, uptime 필드가 있는지 확인하는 것도 추가해.”

이것이 Observability의 시작이다. 에이전트가 시스템 상태를 기계적으로 읽을 수 있게 된다.

왜 이렇게 시켜야 하는가

도입: 코드베이스 너머

8강에서 우리는 코드를 에이전트가 읽고 쓸 수 있는 구조로 만들었다. filefunc으로 파일을 쪼개고, tsma로 테스트를 확보하고, whyso로 변경 이력을 추적했다.

그런데 코드만 agent-operable이면 충분한가?

코드를 수정한 다음에는 빌드해야 한다. 빌드한 다음에는 배포해야 한다. 배포한 다음에는 모니터링해야 한다. 장애가 나면 롤백해야 한다. 이 과정 중 하나라도 사람이 수동으로 해야 한다면, 에이전트의 자율 범위는 “코드 편집"에서 끝난다.

바이브 코더의 현실을 떠올려보자. “기능 추가해"라고 시키면 코드가 나온다. 그 다음은? 터미널에서 빌드 명령어를 치고, AWS 콘솔에 들어가서 배포하고, 로그를 눈으로 훑고, 문제가 생기면 “되돌려"라고 다시 시킨다.

이 수동 과정 전체가 하나의 파이프라인으로 연결되어야 한다. 에이전트가 코드를 고치고, 테스트를 돌리고, 빌드하고, 배포하고, 모니터링까지 — 사람은 승인 버튼만 누르는 구조.

이것이 Agent Operable System이다.

코드베이스에서 시스템으로

코드베이스는 시스템의 한 부분이다. 시스템은 코드 + 인프라 + 배포 파이프라인 + 모니터링 + 운영 절차의 총합이다.

기능 요청
→ SSOT 편집 (yongol)
→ 코드 생성 (yongol generate)
→ 테스트 통과 (Hurl + go test)
→ 빌드 (Docker)
→ 배포 (CI/CD)
→ 모니터링 (헬스체크 + 로그)
→ 완료

이 체인에서 어느 한 고리가 에이전트에게 불투명하면, 그 이후는 전부 사람의 몫이 된다. 하나의 끊어진 고리가 전체 자동화를 무너뜨린다.

Agent Operable System의 4가지 조건

시스템이 에이전트에 의해 운영 가능하려면 네 가지 조건을 만족해야 한다.

조건 1. Observability — 모든 상태가 기계적으로 관측 가능하다

에이전트는 눈이 없다. 화면을 보지 못한다. 대시보드를 읽지 못한다. 에이전트가 시스템의 상태를 알려면, 그 상태가 텍스트로 출력되어야 한다.

# 사람의 관측
AWS 콘솔에 로그인 → CloudWatch 대시보드 → 그래프를 눈으로 확인
→ "어, CPU가 높네" → 판단

# 에이전트의 관측
$ curl -s localhost:8080/health | jq .
{
  "status": "ok",
  "db": "connected",
  "uptime": "3h42m",
  "error_rate_5m": 0.02
}
→ error_rate > 0.05? → 알림

관측 가능성의 핵심: 사람이 보는 것이 아니라, 기계가 파싱할 수 있는 것.

Observability를 갖추지 않은 시스템에서 에이전트는 눈을 감고 수술하는 의사다.

조건 2. Declarative — 모든 행동이 선언적으로 정의되어 있다

에이전트에게 “배포해"라고 시키면 뭘 하는가?

선언적 시스템이 아니면: 에이전트가 “보통 이렇게 하지 않나?” 하고 추측한다. SSH로 서버에 접속하고, git pull을 치고, 프로세스를 재시작하고… 그리고 뭔가 빠뜨린다.

선언적 시스템이면: 모든 것이 파일에 적혀 있다.

# docker-compose.yml — 서비스가 뭘 실행하는지
services:
  app:
    build: .
    ports: ["8080:8080"]
    environment:
      DATABASE_URL: ${DATABASE_URL}

# Makefile — 어떤 명령어로 무엇을 하는지
deploy:
    docker compose up -d
    curl -sf localhost:8080/health || (docker compose logs && exit 1)

# .github/workflows/deploy.yml — 언제 자동으로 실행되는지
on:
  push:
    branches: [main]
jobs:
  deploy:
    steps:
      - run: make build
      - run: make deploy

선언적 시스템에서 에이전트가 할 일은 명확하다:

1. 파일을 읽는다 (docker-compose.yml, Makefile, workflow)
2. 파일에 적힌 대로 실행한다
3. 결과를 확인한다

추측이 없다. 파일이 진실이다.

4강에서 배운 yongol의 SSOT 원칙이 여기서도 동일하게 적용된다. 코드에서 결정과 구현을 분리했듯이, 시스템에서도 “무엇을 해야 하는가”(선언)와 “어떻게 하는가”(실행)를 분리한다.

Docker는 앱을 상자에 담아서 어디서든 똑같이 실행되게 하는 도구다. 이사할 때 짐을 박스에 넣듯, 앱과 필요한 모든 것을 하나의 상자에 넣는다. 상자만 옮기면 어디서든 똑같이 돌아간다. Terraform은 서버를 코드 파일로 관리하는 도구다.

Docker와 Terraform의 내부를 이해할 필요는 없다. “앱을 상자에 담는 것"이라는 한 줄만 알면 충분하다. 나머지는 에이전트가 한다. docker-compose.yml 파일의 문법을 공부하지 마라. 에이전트에게 시키면 알아서 만든다. 당신은 결과만 확인한다 — “앱이 뜨는가? /health가 200을 반환하는가?”

조건 3. Reversible — 모든 변경이 검증 가능하고 되돌릴 수 있다

에이전트가 배포했는데 서비스가 죽었다. 이 상황에서 두 가지가 필요하다:

1. 무엇이 틀렸는지 알 수 있어야 한다 (검증 가능)
2. 이전 상태로 되돌릴 수 있어야 한다 (가역적)

# 되돌릴 수 없는 배포 (공포)
파일을 서버에 직접 올리고 덮어쓰는 방식.
→ 문제 발생 → 이전 버전이 어디에? → 기억 안 남 → 패닉

# 되돌릴 수 있는 배포 (안심)
git revert HEAD && make deploy
→ 문제 발생 → 이전 커밋으로 롤백 → 1분 안에 복구

3강에서 배운 Git의 핵심이 여기서 다시 등장한다. 코드의 되돌림은 Git이 담당한다. 인프라의 되돌림은 Terraform이 담당한다. DB의 되돌림은 마이그레이션의 down 파일이 담당한다.

되돌릴 수 없는 변경은 에이전트에게 시킬 수 없다. 에이전트가 실수하면 — 그리고 반드시 실수한다 — 되돌릴 수 있어야 한다.

조건 4. Human-in-the-loop — 승인 게이트가 명시적이다

네 조건 중 가장 중요한 것이 이것이다.

에이전트가 판단하고 사람이 승인하는 구조. “사람이 지시하고 에이전트가 실행"이 아니라, “에이전트가 제안하고 사람이 승인"이다. 방향이 반대다.

# 기존: 사람이 지시한다
"이 버그 고쳐" → 에이전트가 코드를 수정 → 사람이 결과를 확인

# Agent Operable: 에이전트가 제안한다
에이전트: "error_rate이 5%를 넘었습니다. 
  원인: 최근 배포의 DB 커넥션 풀 설정 누락.
  수정안: docker-compose.yml의 DB_MAX_CONNECTIONS를 20에서 50으로 변경.
  롤백 계획: 실패 시 이전 이미지로 자동 롤백."
사람: "승인"

핵심은 승인 게이트가 명시적이고, 자동으로 건너뛸 수 없다는 것이다.

되돌릴 수 있는 작업은 자동으로 실행해도 된다. 되돌리기 어렵거나 영향이 큰 작업은 반드시 승인을 거친다. 이 경계를 미리 선언해두는 것이 Human-in-the-loop 설계다.

에이전트의 병목은 지능이 아니라 컨텍스트다

8강에서 filefunc가 코드의 컨텍스트 오염을 제거했다. 이 원리는 시스템 전체로 확장된다.

코드를 구조화하면 같은 에이전트가 10배 넓은 범위를 다룬다.

코드만이 아니다. 시스템의 모든 레이어를 구조화하면 에이전트의 탐색 범위가 극적으로 넓어진다:

코드   → filefunc로 구조화
설정   → docker-compose.yml, Makefile로 선언적 정의
명세   → yongol SSOT로 교차 검증
인프라  → Terraform state로 영속
모니터링 → /health + 구조화 로그로 기계 판독 가능

에이전트의 병목은 지능이 아니다. 더 똑똑한 모델을 쓰는 것보다, 에이전트에게 구조화된 정보를 주는 것이 10배 효과적이다. 8강에서 filefunc로 코드를 구조화한 것처럼, 9강에서는 시스템 전체를 구조화한다.

80/20 — 사람이 진짜 신경 써야 하는 것

Agent Operable System이 완성되면, 명세에서 코드의 80~90%가 자동 생성된다. 당신이 신경 쓸 것은 나머지 10~20%뿐이다.

그 10~20%는 무엇인가? 비즈니스 규칙(가격 정책, 워크플로우), 도메인 로직(법적/정책 계산), 외부 API 연동 같은 것들이다. 이것만 filefunc으로 구조화하고 tsma로 테스트를 확보하면 된다.

이것이 비-SWE가 100+ 엔드포인트를 유지할 수 있는 구조다.

결정은 사람이 한다. 구현과 검증은 기계가 한다. 사람은 “무엇을 만들 것인가"만 결정하면 된다. “어떻게 만들 것인가"는 명세가 정의하고 에이전트가 실행한다.

왜 빅테크는 이걸 안 만드는가

“이렇게 좋은 건데 왜 Anthropic이나 OpenAI가 안 하는가?”

모델은 범용이지만 검증 도구는 언어와 프레임워크에 특화되어야 한다. Go 테스트 도구는 Go에만 적용되고, Python 도구는 Python에만 적용된다. 빅테크의 ROI에 맞지 않는다. 그래서 이 자리가 비어 있다.

기차(모델)가 빨라질수록 선로(검증 도구)가 더 중요해진다. 이 강의를 듣는 당신이 깔 수 있는 선로다.

전체 파이프라인: “기능 추가해” 한 마디에서 배포까지

Agent Operable System이 갖춰진 프로젝트에서 “주문 내역 조회 기능 추가해"라고 하면:

1. SSOT 편집
   에이전트: features.yaml에 ListOrders 추가
   에이전트: OpenAPI에 GET /orders 정의
   에이전트: DDL에 orders 테이블 정의
   에이전트: SSaC에 서비스 흐름 선언
   에이전트: Hurl에 테스트 시나리오 작성

2. 정합성 검증
   에이전트: yongol validate → 0 errors

3. 코드 생성
   에이전트: yongol generate → Go 핸들러, sqlc 쿼리, React 컴포넌트

4. 테스트 통과
   에이전트: go test → PASS
   에이전트: Hurl 테스트 → PASS

5. 빌드
   에이전트: docker build → 성공

6. 배포 (승인 게이트)
   에이전트: "모든 검증 통과. staging 배포 승인 요청합니다."
   사람: "승인"
   에이전트: staging 배포 → /health 확인 → 정상

7. 프로덕션 배포 (승인 게이트)
   에이전트: "staging에서 30분간 에러 없음. 프로덕션 배포 승인 요청합니다."
   사람: "승인"
   에이전트: 프로덕션 배포 → /health 확인 → 정상

8. 완료
   에이전트: "ListOrders 기능 배포 완료. 
   모니터링 중. 이상 발생 시 자동 롤백합니다."

사람이 한 일: “주문 내역 조회 기능 추가해” + “승인” 두 번. 에이전트가 한 일: 나머지 전부.

이것이 바이브 코딩 스케일업의 완성형이다.

레거시에서 Agent Operable System으로

“우리 프로젝트는 이미 만들어져 있는데 어떻게 전환하나?”

한 번에 전부 바꿀 필요 없다. 단계별로 갈 수 있다.

1단계 — Observability 확보 (1일)

• /health 엔드포인트 추가
• 로그를 구조화 JSON으로 변경
• 기본 모니터링 설정

2단계 — 선언적 시스템 전환 (2-3일)

• Docker Compose로 서비스 구성 정의
• Makefile로 빌드/배포/테스트 명령어 통합
• CI/CD 파이프라인 구축

3단계 — 가역성 확보 (1-2일)

• DB 마이그레이션 시스템 도입
• 롤백 절차 문서화 및 자동화
• 배포 시 헬스체크 + 자동 롤백

4단계 — 승인 게이트 정의 (1일)

• 자동 실행 가능한 작업 목록 정리
• 승인이 필요한 작업 목록 정리
• CI/CD에 승인 단계 추가

각 단계가 독립적이다. 1단계만 해도 에이전트가 시스템 상태를 파악할 수 있다. 2단계까지 하면 에이전트가 배포를 실행할 수 있다. 3단계까지 하면 실수를 되돌릴 수 있다. 4단계까지 하면 안전하게 자율 운영할 수 있다.

비전 — 바이브 코딩 스케일업의 끝

1강에서 시작한 “말로 시키면 만들어준다"가 어디까지 왔는가.

1강: "할 일 목록 앱 만들어"
  → 코드가 나온다. 3개 기능까지 작동한다.

8강: "filefunc validate 돌려서 위반 0으로 만들어"
  → 코드베이스가 에이전트 친화적으로 바뀐다.

9강: "기능 추가해" + "승인"
  → 코드 생성 → 테스트 통과 → 빌드 → 배포 → 모니터링.
  → 전체 파이프라인이 에이전트 주도로 돌아간다.

비-SWE가 100+ 엔드포인트를 유지하고, 배포하고, 운영할 수 있는 구조.

SWE 없이 스케일업이 가능한 이유: 결정은 사람이, 구현과 검증은 기계가.

그런데 아직 빠진 것이 하나 있다. 코드를 구조화했고, 시스템을 구조화했다. 하지만 데이터는?

10강에서 마지막 퍼즐을 맞춘다.

실습

필수 실습 (비전공자)

목표: /health 엔드포인트를 추가하고 Hurl로 검증한다.

단계 1 — Observability 확보

에이전트에게: "서버에 /health 엔드포인트를 추가해. 
DB 연결 상태, 에러 비율, 업타임을 JSON으로 반환하게 해. 
기존 Hurl 테스트가 전부 통과해야 해."

단계 2 — Hurl 테스트 작성

에이전트에게: "/health가 200을 반환하는 Hurl 테스트를 만들어.
JSON 응답에 db, status, uptime 필드가 있는지 확인하는 것도 추가해."

확인할 것:

• /health가 200을 반환하는가?
• Hurl 테스트가 통과하는가?

도전 실습 (선택)

Docker를 직접 설치하거나 설정 파일을 이해할 필요 없다. 전부 에이전트에게 시킨다.

단계 1 — Docker Compose

에이전트에게: "Docker가 설치 안 되어 있으면 설치해줘.
이 프로젝트를 docker-compose.yml로 구성해.
앱 서버와 PostgreSQL이 포함되어야 해.
docker compose up 하면 전부 뜨게 만들어.
Makefile에 build, deploy, test 명령어를 추가해."

에이전트가 Docker 설치부터 설정 파일 생성, 실행 확인까지 전부 처리한다. 당신은 마지막에 “앱이 뜨는가?“만 확인한다. 에러가 나면 Claude Code가 자동으로 감지하고 수정을 시도한다.

단계 2 — CI/CD 파이프라인

에이전트에게: "GitHub Actions workflow를 만들어.
main 브랜치에 push하면:
1. go test 실행
2. Hurl 테스트 실행
3. Docker build
4. 전부 통과하면 staging 배포
단, production 배포는 수동 승인 필요."

단계 3 — 통합 시연

에이전트에게 기능 하나를 추가 요청한다. SSOT 편집부터 staging 배포까지 에이전트가 수행하고, production 배포만 수동 승인하는 전체 파이프라인을 시연한다.

확인할 것:

• “기능 추가해” 한 마디에서 staging 배포까지 사람의 개입이 몇 번이었는가?
• 에이전트가 실패했을 때 되돌리기까지 몇 분 걸렸는가?
• 에이전트가 /health 결과를 읽고 상태를 파악할 수 있었는가?

연관 글

• Reins Engineering — 고삐 있는 AI
• yongol — AI 코딩 SaaS의 용골

Reins Engineering 전체 강의

근거 자료 출처

• 8강 참조: Stanford “Lost in the Middle” (2024), Amazon “Context Length Alone Hurts LLM Performance” (2025) — 불필요한 컨텍스트가 에이전트 성능을 30~85% 저하
• Observability 원칙 — 기계가 파싱 가능한 구조화 출력(/health 엔드포인트, JSON 로그)이 에이전트 운영의 전제 조건
• Docker Compose — 선언적 서비스 구성으로 에이전트가 추측 없이 시스템을 읽고 실행
• Terraform — Infrastructure as Code, 인프라 상태의 선언적 정의와 가역적 변경
• CI/CD (GitHub Actions) — 빌드-테스트-배포 파이프라인의 선언적 자동화
• Human-in-the-loop 설계 — 되돌릴 수 있는 작업은 자동, 영향이 큰 작업은 승인 게이트 필수