개발자인데, 코드를 안 칩니다

마지막으로 코드를 직접 타이핑한 게 언제였는지 세어봤다. 6개월이 넘었다. 코드만이 아니다. IDE도 웬만해서는 열지 않게 됐다. 요즘 내 화면에 떠 있는 건 터미널과 개인 대시보드다. 코드를 아예 안 보는 건 아니다. 다만 파일을 열어 훑는 게 아니라 diff와 개발 환경에 반영된 결과만 확인한다. 그런데 처리하는 업무량은 오히려 늘었다.

지금 내 업무는 이렇게 돌아간다. 업무 요청이 들어오면 클로드 코드에 요청 내용을 넘긴다. 티켓 생성, 브랜치 생성, 구현, QA 문서와 증적 캡처, 테스트 서버 배포까지 전부 클로드 코드가 한다. 나는 결과물이 기획대로 구현됐는지 QA한다. 개발자라기보다 검수자에 가까워졌다.

이 워크플로우를 어떻게 만들었고, 실제로 어떤지 정리해본다.

핵심은 스킬

클로드 코드에는 스킬(skill)이라는 기능이 있다. 프로젝트의 .claude/skills/ 디렉토리에 마크다운으로 작업 절차를 정의해두면, 클로드가 해당 작업을 할 때 그 절차를 따른다. 쉽게 말해 팀 위키에 있던 “배포 절차”, “티켓 작성 규칙” 같은 문서를 AI가 실행 가능한 형태로 옮긴 것이다.

여기서 한 가지 짚을 게 있다. 클로드 코드에는 서브에이전트로 일을 떼어 맡기는 방법도 있는데, 왜 스킬이었나. 둘은 대체재가 아니다. 서브에이전트는 애매한 목표를 자율적으로, 병렬로 처리할 때 강하고, 스킬은 정해진 절차를 단계와 멈춤 지점까지 명시해 재현할 때 강하다. 내 업무는 티켓→구현→QA→배포로 모양이 고정된 절차라 후자에 가까웠다. 병렬성은 서브에이전트가 아니라 worktree와 세션 분리로 풀었고(따로 정리했다), 통제는 여러 개의 명시적 멈춤 지점으로 잡았다. 알아서 자율 실행하게 두는 것보다, 절차를 내가 읽을 수 있는 형태로 고정하고 되돌리기 어려운 자리에서 멈추게 하는 쪽이 이 일엔 맞았다.

.claude/skills/
├── _common/           # 공통 규칙 — 승인 원칙, 지라 포맷, API 호출 규칙
├── do/                # 오케스트레이터 — 입력을 분석해 유형 판별 후 위임
├── do-feature/        # 신규 작업·기존 티켓 구현
├── do-bugfix/         # Bug 티켓 자동 생성 + 수정
├── do-deploy/         # cherry-pick → 테스트/release 브랜치 배포
├── do-qa/             # QA 라우터
├── do-analysis/       # 코드 분석 · 팀 보고 · MR 생성
├── work/              # 신규 작업 계획 — 분석부터 티켓·브랜치 생성까지
├── qa/                # QA 문서 + 증적 캡처 → 컨플루언스 생성, 지라에 링크
├── figma/             # Figma-to-Code — 프로젝트 감지 후 전용 규칙 로드
├── figma-{프로젝트}/   # 프로젝트별 변환 규칙 (2개, 자동 로드 전용)
├── doc/               # 아키텍처 문서 생성 (시퀀스 다이어그램 포함)
├── gliffy/            # 컨플루언스 플로우차트 생성·갱신
├── vuln/              # 취약점 건별 분석 + 지라 댓글
├── vuln-sbom/         # 스캔 대기 프로젝트 일괄 수집 → 분석 → 코멘트
└── weekly-report/     # 브랜치 diff → 주간 보고 양식 → 컨플루언스 반영

한동안은 진입점인 /do만 커맨드로 따로 뒀다가 최근에 전부 스킬로 합쳤다. 나뉘어 있으면 이게 어디 있더라를 매번 생각해야 하는데, 프런트매터만으로 진입점과 위임 대상을 구분할 수 있게 되니 굳이 나눠 둘 이유가 없었다.

열일곱 개로 늘었지만, 평소 진입점은 사실상 /do 하나다. 티켓 번호를 주든, 작업 설명을 주든, “배포”나 “mr” 같은 한 단어를 주든, /do가 입력을 분석해 어떤 유형의 일인지 판별하고 맞는 스킬로 위임하는 오케스트레이터 역할을 한다.

이 글에서 슬래시가 붙은 /do, /qa 같은 건 내가 직접 부르는 진입점이고, do-feature처럼 슬래시가 없는 건 위임으로만 실행되는 스킬이다. 표기만 다른 게 아니라 실제로 부를 수가 없는데, 뒤에서 다룰 프런트매터가 그걸 막는다.

여덟 개 유형이지만 위임 대상은 다섯 개다. 신규 작업과 기존 티켓은 티켓이 이미 있느냐만 다를 뿐 이후 절차가 같아서 do-feature 하나로 묶었고, 분석·보고·MR 생성은 셋 다 “코드를 읽고 결과를 정리해 어딘가에 내보낸다”는 모양이 같아서 do-analysis로 통합했다. 유형을 잘게 나누는 건 입력을 알아듣기 위해서지, 스킬을 그만큼 만들기 위해서가 아니다.

전체 호출 관계는 이렇다.

사용자 입력
├── /do  ── 오케스트레이터: 입력을 보고 유형을 판별해 위임
│   ├── do-feature   ← 신규 작업 / 기존 티켓
│   ├── do-bugfix    ← 버그 수정
│   ├── do-deploy    ← 배포만
│   ├── do-qa        ← QA 문서
│   └── do-analysis  ← 분석 / 팀 보고 / MR 생성
├── /work   ── 신규 작업 계획: 티켓·브랜치까지 만들고 do-feature로 인계
├── /figma  ── Figma-to-Code: 프로젝트 감지 후 전용 규칙 로드
│   └── figma-{프로젝트}   ← 자동 로드 전용
└── 독립 실행  ── /doc  /gliffy  /vuln  /vuln-sbom  /weekly-report

/work가 오케스트레이터를 거치지 않는 이유는 따로 있다. 신규 작업의 계획 단계는 판별할 유형이 없고 절차도 길어서 별도 진입점으로 두고, 티켓과 브랜치를 만든 뒤 do-feature에 인계한다. /figma, /doc, /gliffy, /vuln, /weekly-report는 티켓-배포 파이프라인 밖에 있는 것들이라 애초에 “무슨 일인지 판별”할 필요가 없다. 이름을 직접 부르는 게 더 빠르다.

do-feature와 do-bugfix는 구현이 끝나면 do-qa로 넘긴다. do-qa는 스스로 하는 일이 거의 없고 /qa를 부르는 라우터다. /do qa로 들어오든 구현 스킬이 넘기든 QA는 한 군데로 모이게 하려고 얇은 층을 하나 뒀다.

오케스트레이터 스킬 자체는 대략 이런 모양이다.

---
description: 작업 오케스트레이터. 유형별로 자동 분기하여 실행
arguments: 작업 내용. 지라 티켓 번호, 작업 설명, 또는 참조 티켓
argument-hint: PROJ-XXXX 또는 작업 설명
allowed-tools: [Bash, Read, Glob, Grep]
---

# 오케스트레이터

## 작업 내용: $ARGUMENTS

### 프로젝트 설정 (자동 로드)

!`cat config/repos.ts`

1. 입력에서 티켓 키 추출 (PROJ-1234 패턴)
2. 관련 파일 검색 + 컨텍스트 수집
3. 유형 분류 (신규 / 기존 티켓 / 버그 / 배포 / QA / 분석 / 보고 / MR)
4. 판별한 유형을 보여주고, 사용자 확인 후 해당 스킬 호출

포인트는 절차를 사람이 읽는 문서가 아니라 실행 단위로 쪼개서 쓰는 것이다. “티켓을 잘 만든다”가 아니라, 어떤 입력을 보고, 무엇과 대조하고, 어떤 형식으로 뽑는지를 명시한다. 모호하게 쓰면 결과물도 모호해진다.

전부 새로 짠 것도 아니다. 클로드 코드가 기본으로 제공하는 스킬들 — 계획 세우기(plan), 수정된 코드를 확인하는 diff 같은 것들 — 도 다시 만들지 않고 각 스킬 절차 안에 그대로 끌어다 녹였다. 이미 있는 건 다시 만들 이유가 없다. 내가 더한 건 그 위에 얹은, 우리 조직의 시스템(지라·깃랩·컨플루언스)과 티켓·배포 규칙에 맞춘 절차층에 가깝다.

프런트매터가 정책이 된다

처음엔 “이 스킬은 오케스트레이터만 부른다” 같은 규칙을 본문에 글로 적어뒀는데, 글로 적힌 규칙은 지켜질 때도 있고 아닐 때도 있었다. 지금은 프런트매터로 못을 박아둔다.

앞의 두 줄은 서로 반대쪽을 막는다. user-invocable: false가 막는 건 사람의 손이고, disable-model-invocation: true가 막는 건 모델의 손이다. do-* 스킬들은 오케스트레이터를 거치지 않으면 실행될 수 없고, /work는 반대로 모델이 “이건 신규 작업 같으니 계획부터 세워야지” 하면서 혼자 티켓을 만들러 가지 못한다. 지라에 글을 쓰는 스킬이라 시작하는 결정만큼은 내 손에 두고 싶었다.

allowed-tools는 스킬별 최소 권한이다. 실제로 이렇게 갈린다.

뒤에서 개입 지점을 되돌리기 비용이 있는 자리에 뒀다고 쓸 텐데, 이건 그보다 한 층 위에 있는 얘기다. 개입 지점은 실행 중에 멈춰 서서 묻는 장치인 반면 프런트매터는 애초에 할 수 없게 만들어두는 장치라, 매번 묻는 것보다 비용이 덜 든다.

물어보게 하지 말고 미리 쥐여준다

최근에 넣은 것 중에 효과가 제일 확실했던 건 동적 컨텍스트 주입이다. 스킬 본문에 셸 명령을 적어두면 스킬이 실행될 때 그 결과가 프롬프트에 실려 들어온다.

### 프로젝트 설정 (자동 로드)

!`cat config/repos.ts`

### 이번 주 브랜치 목록 (자동 로드)

!`git log --since="last monday" --all --format="%D" | ... | grep 'origin/feature/'`

전에는 스킬이 “프로젝트 설정을 읽어라”라고 지시하면 클로드가 파일을 찾고, 읽고, 필요하면 한 번 더 찾았다. 지금은 스킬이 시작되는 시점에 이미 손에 들려 있다. /do와 /work는 저장소 설정을, /weekly-report는 이번 주 브랜치 목록을 그렇게 받는다.

뒤에서 QA 증적 캡처를 Node 스크립트로 옮긴 얘기가 나오는데 원리가 같다. cat config/repos.ts의 결과는 누가 실행하든 같으니, 결과가 정해져 있는 일은 에이전트에게 시키는 대신 미리 해서 넘기는 게 낫다. 탐색하게 두면 왕복만 늘어난다.

같이 넣은 게 하나 더 있는데, /weekly-report의 “이번 주”를 월요일 00:00부터 일요일 23:59까지 KST 기준으로 못 박은 것이다. 사소해 보이지만 이걸 안 정해두니 금요일에 돌릴 때마다 범위가 흔들려서 결과가 매번 달랐다. 프롬프트에 남겨둔 모호함은 결국 결과의 모호함으로 돌아온다.

어디서 멈출지를 먼저 정한다

그리고 스킬마다 수동 개입 지점을 명시적으로 설계해뒀다. 티켓 내용 검토, 구현 방식 선택, 배포 여부, MR 생성 실행 같은 지점에서는 반드시 멈추고 내 확인을 받게 되어 있다. 유형 판별부터가 그렇다 — /do가 “이건 버그 수정으로 보인다”라고 판별해도 확정은 내가 한다. 나머지 단계가 전부 자동이어도, 방향을 정하는 판단과 되돌리기 어려운 실행은 사람 손을 거치게 하는 것. 이 장치 덕분에 자동화를 넓혀도 통제감을 잃지 않았다.

전체 스킬을 통틀어 이런 지점이 스물여섯 개다. 어떤 단계를 밟고 어디서 멈추는지 정리하면 이렇다.

표를 놓고 보면 규칙이 하나 보인다. 멈추는 지점은 전부 되돌리기 비용이 있는 자리다. 티켓 생성, 브랜치 push, MR 생성, 컨플루언스와 지라에 글을 남기는 순간. 반대로 코드를 읽고 분석하고 초안을 만드는 단계에는 개입 지점이 하나도 없다. do-qa처럼 다른 스킬을 부르기만 하는 라우터도 멈출 이유가 없다.

/figma만 예외처럼 보인다. 세 번 멈추는데 그중 둘은 외부 시스템을 건드리지 않는 자리로, 구현 위치와 컴포넌트 트리를 확인받는 지점이다. 다만 이것도 기준이 다른 게 아니다. 트리 구조를 잘못 잡으면 그 아래 구현이 통째로 날아가니까. 되돌리기 비용은 외부 시스템에만 생기는 게 아니라 잘못된 전제 위에 쌓아올린 작업량에도 생긴다.

처음부터 이렇게 설계한 건 아니다. 초반엔 중요해 보이는 곳마다 확인을 넣었는데, 확인이 너무 잦으면 결국 다 엔터만 치게 된다. 그렇게 형식이 되어버린 확인은 안전장치가 아니라 장식에 가깝다. 그래서 기준을 중요한가에서 틀렸을 때 되돌릴 수 있는가로 바꿨다. 스킬이 늘면서 개수는 다시 스물여섯으로 올라갔지만 스킬당 두 개꼴이라는 밀도는 그대로다.

승인이 먼저였다

여기까지 오면 드러나지만, 이 워크플로우는 사내 시스템에 실제로 쓰기를 하는 구조다. 지라에 티켓을 만들고 깃랩에 브랜치를 올린다. 그래서 도구를 고르는 것보다 먼저 한 일이 사내 승인을 받는 것이었다. 클로드 코드는 승인된 도구로 사용 중이고, 그 위에서 스킬을 얹었다.

순서를 뒤집으면 나중에 되돌릴 수 없다. 이미 반년치 티켓과 커밋이 그 도구를 거쳐 나간 뒤에 “그거 승인된 거였나요”를 듣는 상황은 만들지 않는 게 낫다. 개인 생산성 도구라면 혼자 판단해도 되지만, 사내 시스템에 자격증명을 물리는 순간부터는 성격이 달라진다.

토큰은 환경변수로

스킬들이 지라, 컨플루언스, 깃랩 API를 호출하니까 인증 토큰이 필요하다. 각 서비스에서 개인 토큰을 발급받아 컴퓨터의 환경변수로 저장했고, 스킬에서는 환경변수 이름만 참조한다.

# ~/.zshrc — 토큰은 여기에만 존재
export JIRA_API_TOKEN="..."
export GITLAB_TOKEN="..."

이렇게 하면 토큰 값 자체가 클로드 코드에 노출되지 않는다. 스킬 파일에도, 대화 프롬프트에도, 저장소 어디에도 키가 등장하지 않는다. AI에게 업무 시스템 접근 권한을 주는 순간 자격증명 관리가 가장 먼저 정리해야 할 문제였다.

이건 어디까지나 키가 새지 않게 하는 장치다. 도구가 무엇을 읽고 어디까지 접근하느냐는 별개의 문제고, 그건 환경변수가 아니라 앞의 승인 절차에서 정리할 일이다. 둘을 같은 것으로 묶어두면 나중에 곤란해진다.

업무 하나가 흘러가는 과정

실제 업무 요청 하나가 들어왔을 때의 흐름이다.

1. 기획 정리와 티켓 생성. 우리 조직은 기획자가 따로 없어서 요청이 한두 문장짜리로 러프하게 온다. 이걸 그대로 티켓으로 만들면 구현 중에 모호한 지점마다 AI가 임의로 결정해버린다. 그래서 티켓을 만들기 전에 요청을 스펙으로 다듬는다. 목적과 요구사항, 완료 조건을 정의하고, 무엇보다 선택이 필요한 문제들(엣지 케이스 처리, 정책적 판단, 기존 동작과의 충돌)을 미리 골라내서 답을 정해둔다. 정리가 끝나면 /work를 실행한다. 작업 분석과 영향도 파악, 티켓 초안 작성까지 진행되고, 초안을 내가 검토·확정하면 지라에 티켓이 등록되고 브랜치와 worktree까지 만들어진다.

2. 구현과 자동 검증. /work가 넘긴 지점부터 do-feature 스킬이 이어받아 컨텍스트를 수집하고 구현을 진행한다. 구현이 끝나면 사람 손으로 넘어가기 전에 자동 검증이 한 벌 돈다 — 단위·통합 테스트로 동작을 확인하고, 타입체크·린트·빌드로 코드 자체를 검증하고, 정적 보안 분석(SAST)과 시크릿 스캔으로 취약한 패턴이나 실수로 커밋된 키가 없는지 본다. 여기서 하나라도 깨지면 배포로 넘어가지 않고 수정 루프를 돈다. 의존성 취약점은 결이 달라서 뒤의 /vuln이 따로 맡는다. 이미 티켓이 있는 작업이라면 처음부터 /do PROJ-1234 한 줄이면 된다. 나는 이 시점에 다른 업무 요청을 처리하거나 앞선 작업의 QA를 한다. 구현이 도는 동안 기다리지 않는 게 이 방식의 핵심이다.

3. QA 문서. 구현이 끝나면 /qa가 지라 티켓과 git diff를 대조해 테스트 시나리오와 체크리스트를 뽑고, 컨플루언스에 QA 문서로 생성한 뒤 지라 티켓에 링크 코멘트까지 단다. 이 문서가 중요한 이유는 내 QA의 기준이 되기 때문이다. “잘 되겠지”가 아니라 항목 단위로 확인한다.

증적 캡처는 처음에 Playwright MCP로 붙였다. 클로드가 브라우저를 직접 조종하면서 시나리오를 따라가고 단계별 스크린샷을 남기는 방식이다. 되긴 됐다. 문제는 토큰이었다. 클릭 한 번, 입력 한 번이 전부 툴 호출이라 왕복이 계속 쌓이고, 매 스텝의 화면과 DOM이 컨텍스트로 들어간다. QA 한 건 돌리는 비용이 구현 비용에 맞먹는 수준이었다.

한동안은 이걸 브라우저 자동화는 비싸다로 정리해뒀는데, 진단이 틀렸다. 비싼 건 브라우저 자동화가 아니라 에이전트가 브라우저를 한 스텝씩 조종하는 구조였다. 캡처 자체는 원래 싼 일이고, 스무 번 캡처하려고 툴 호출을 스무 번 하는 게 문제였다.

그래서 호출 구조를 바꿨다. 클로드가 브라우저를 직접 몰지 않고, 시나리오대로 화면을 순회하며 캡처하는 Node 스크립트를 짜서 Bash 한 번으로 실행한다. Playwright 패키지를 코드에서 직접 쓰는 방식이다. 이러면 컨텍스트에 들어오는 건 스크립트와 실행 결과뿐이고 중간 화면은 들어오지 않는다. 스무 번의 왕복이 한 번으로 줄었다.

Playwright Test도 후보였는데 과잉이라 접었다. 그쪽은 테스트 러너 체계를 통째로 들여오는 일인데, 지금 필요한 건 증적 캡처지 테스트 스위트가 아니다. config와 spec을 관리하는 부담이 얻는 것보다 크다.

여기서 얻은 건 도구 선택보다 기준 쪽이었다. 판단이 필요한 일은 에이전트가 하고, 절차가 정해져 있는 일은 코드로 짜서 한 번에 돌린다. 같은 동작을 반복하는데 매번 에이전트를 태우고 있다면 그건 자동화라기보다 낭비에 가깝다.

그래도 QA 전 구간을 무인으로 돌리지는 않는다. 시나리오를 만들고 화면을 순회하며 단계별 증적을 캡처해 문서에 붙이는 데까지가 스킬의 몫이고, 그 화면이 기획대로인지 판단하는 건 내 몫이다. 스크린샷이 열 장 붙어 있어도 그게 맞는 화면인지는 기획을 아는 사람만 알 수 있으니, 캡처가 대조를 대신해주지는 못한다.

캡처가 싸지면서 오히려 이 구분이 더 중요해졌다. 왕복 비용이 사라져서 증적은 얼마든지 늘릴 수 있는데, 늘어난 만큼 이만큼 붙어 있으니 됐겠지 하고 넘어갈 유혹도 같이 커진다. 자동화가 가능하다는 것과 자동화가 합리적이라는 건 별개다.

4. 테스트 서버 배포. /do release를 실행하면 cherry-pick 대상 커밋을 나에게 확인받고 테스트 브랜치로 push한다. 이후는 파이프라인이 테스트 서버까지 올린다.

5. 내 차례. 여기서부터가 내 일이다. 먼저 /diff로 작성된 단위 테스트와 실제 변경 내용을 코드 수준에서 훑고, 그다음 QA 문서의 시나리오와 붙어 있는 증적을 따라 테스트 서버에서 기획과 대조하며 확인한다. 캡처가 있다고 통과가 아니라, 그 화면이 기획대로인지를 내가 본다. 어긋난 게 있으면 어떤 항목이 어떻게 다른지 티켓에 코멘트로 남기고 다시 클로드 코드에 넘긴다. QA를 통과하면 /do mr로 push와 release 대상 MR 생성까지 마무리한다.

티켓에서 배포까지의 파이프라인 밖에 있는 일들도 스킬로 돌린다. /doc은 기능이나 흐름 단위의 아키텍처 문서를 시퀀스 다이어그램과 함께 생성한다. /vuln은 티켓으로 내려온 SBOM 취약점을 건별로 파고든다 — 의존성 경로를 추적하고, 취약한 함수가 실제로 호출되는지 코드 패턴과 정적 분석으로 확인해서 영향없음·제한적·있음 중 하나로 판정하고 근거와 함께 지라에 댓글을 단다. 판정 자체보다 근거를 남기는 쪽이 중요하다. “영향없음”이라고만 적힌 댓글은 나중에 아무도 신뢰하지 않는다.

/weekly-report는 주간 보고를 쓴다. 이번 주에 작업한 feature 브랜치를 모아 브랜치별 diff를 실제로 읽고, 브랜치당 4~5개 항목으로 정리한 뒤 팀 주간 보고 양식에 맞춰 컨플루언스에 반영한다. 커밋 메시지를 나열하지 않고 코드를 읽게 한 데는 이유가 있다. 커밋 메시지는 내가, 정확히는 클로드가 쓴 요약이라 이미 한 번 손실이 일어난 정보다. 주간 보고에서 그걸 다시 요약하면 요약의 요약이 되어 무엇을 했는지만 남고 무엇이 달라졌는지가 사라진다. diff에서 출발하면 커밋 메시지에 안 적힌 변경까지 잡힌다.

이 스킬에는 조건이 하나 더 붙어 있는데, 읽는 사람이 상위 보고 라인이라는 점이다. 개발자끼리 쓰는 보고라면 “훅 로직 리팩터링”으로 충분하지만 여기서는 그 문장이 아무것도 전달하지 못한다. 그래서 브랜치명이나 파일명, 함수명 같은 구현 어휘를 걷어내고 무엇이 달라졌는지와 그게 왜 필요했는지로 다시 쓰라는 규칙을 스킬에 넣었다. diff까지 읽게 만드는 이유가 여기서 한 번 더 살아난다. 코드가 뭘 바꿨는지 알아야 그 변경을 업무 언어로 옮길 수 있고, 커밋 메시지만 봐서는 번역할 원문 자체가 없다.

코드 조사가 필요하면 /do 분석, 상황 공유가 필요하면 /do 보고로 현상·원인·조치 3줄 요약을 뽑는다. 반복되는 업무의 모양이 보일 때마다 스킬이 하나씩 늘어난 결과다.

늘기만 한 건 아니다. 만들어놓고 결국 지운 스킬도 있다. 쓸 것 같아서 만들었는데 몇 번 돌려보고 손이 안 가면, 그건 실제 업무의 모양이 아니라 내가 상상한 업무의 모양이었던 셈이다. 스킬은 파일이라 지우는 비용이 거의 없는 반면 남겨두는 비용은 은근히 있다. /do가 위임할 후보가 하나 늘고, 목록을 볼 때마다 눈에 걸리고, 나중에 이게 뭐 하는 거였는지 다시 읽어야 한다. 안 쓰는 절차는 문서로 남겨두느니 지우는 편이 낫다고 보고, 지금은 한동안 안 부른 스킬이 보이면 그냥 지운다.

기획은 따로 정리했다

1단계에서 “요청이 러프하게 온다”고 했는데, 이 앞단만 떼면 그 자체로 한 편이다. 전담 기획자가 없는 조직에서 요청을 스펙으로 다듬는 과정, 그리고 요즘은 타팀이 바이브 코딩으로 만든 화면을 들고 오기 시작해서 그 코드에서 요구사항을 역산하게 된 얘기 — 기획서 대신 화면이 온다에 정리해뒀다.

여기서는 한 줄만 남긴다. AI에게 구현을 맡기는 워크플로우에서는 앞단 검토가 특히 중요하다. 모호한 요구사항은 AI의 임의 결정이 되어 QA에서야 발견되니까, 기획 취합 단계의 왕복이 뒤 단계의 왕복을 줄여준다.

동시에 여러 작업 굴리기

이 흐름이 업무 하나면 단순한데, 실제로는 같은 프로젝트에서 여러 작업이 동시에 돈다. 평소에는 4~5개, 많을 때는 12개를 한꺼번에 돌린 적도 있다. 구현이 각자의 worktree에서 알아서 돌고 나는 상태만 관리하니까 가능했다.

이 규모가 되면 스킬만으로는 안 된다. 작업 공간 분리, 히스토리 기록, 전체를 조망하는 화면이 같이 있어야 한다. 셋을 어떻게 붙였는지는 혼자서 열두 개 작업 굴리기에 따로 썼다.

6개월 해보고 느낀 것

좋아진 것

반복 업무가 사라졌다. 티켓 양식 맞추기, 브랜치 이름 규칙, QA 문서 템플릿 채우기, 배포 커맨드 순서 외우기. 이런 것들은 원래도 머리를 쓰는 일이 아니라 절차를 기억하는 일이었다. 절차는 스킬에 있고, 나는 기억할 필요가 없다.

병렬 처리가 된다. 예전엔 업무 하나를 잡으면 구현이 끝날 때까지 그 일에 묶였다. 지금은 구현이 도는 동안 다른 요청을 티켓으로 만들고, 끝난 작업을 QA한다. 업무량이 늘었는데 야근이 줄어든 이유다.

달라진 것

내 역할의 무게중심이 구현에서 양끝으로 옮겨갔다. 앞쪽은 기획, 뒤쪽은 검증이다. 처음엔 이게 어색했다. 개발자인데 코드를 안 짜니까. 근데 곰곰이 생각해보면 원래도 가치는 “코드를 친다”가 아니라 “의도한 대로 동작하는 제품을 내보낸다”에 있었다. 타이핑은 그 수단이었을 뿐이다.

특히 기획의 비중이 커졌다. 구현이 사람 손을 떠나면서, 품질을 결정하는 지점이 코드가 아니라 스펙으로 이동했다. 사람이 구현할 때는 모호한 기획도 어떻게든 굴러간다. 구현하다 애매하면 그 자리에서 판단하거나 물어보면 되니까. AI 구현에서는 그 임기응변이 사라진다. 모호한 요구사항을 주면 그럴듯한 쪽으로 조용히 결정해버리고, 그 결정이 틀렸다는 건 QA에서야 발견된다. 그래서 기획 단계에서 선택해야 할 문제를 미리 파악하고 정의하는 것이 내 업무 중 가장 중요한 부분이 됐다. 잘 정의된 티켓은 한 번에 통과하고, 러프하게 넘긴 티켓은 반드시 반려 루프를 돈다.

검증 능력도 마찬가지로 중요해졌다. 구현 속도가 병목이 아니게 되면서, 이제 병목은 내가 얼마나 빠르고 정확하게 정의하고 검수하느냐다. 요구사항에서 빠진 결정을 찾아내는 능력, 엣지 케이스를 떠올리는 능력, diff에서 위험한 변경을 골라내는 눈. 아이러니하게도 코드를 안 치게 되면서 코드를 읽는 시간은 더 늘었다.

불안한 것

솔직히 불안한 지점도 있다. 코드 감각이 무뎌지는 것 아닌가 하는 걱정. 6개월간 직접 안 쳤으니 지금 화이트보드 코딩 면접을 보면 예전만 못할 것이다. 다만 설계를 판단하는 감각과 잘못된 코드를 알아보는 감각은 오히려 유지되거나 늘었다. 매일 남이 짠(정확히는 AI가 짠) 코드를 읽고 평가하는 게 일이니까.

책임 문제도 있다. 구현을 AI가 했어도 배포된 코드의 책임은 나에게 있다. 그래서 QA를 형식적으로 넘길 수가 없다. 검수가 뚫리면 그게 곧 장애다. 역설적으로, 코드를 직접 안 짜게 되면서 검증에는 예전보다 훨씬 진지해졌다.

이 방식이 맞는 사람

권하기 전에 하나 분명히 해둘 게 있다. 지금까지 쓴 건 전부 내 워크플로우다. 팀에 전파해서 쓰는 단계가 아니라 내가 편하자고 만들어 혼자 쓰는 수준이다. 클로드 코드 자체는 사내 승인을 받고 쓰지만 이 스킬 뭉치는 공식적으로 도입된 게 아니라서, 앞에 적은 효과는 전부 한 사람 기준으로 읽어야 한다.

혼자 쓰는 도구는 내가 납득하면 그만이지만 여럿이 쓰는 도구는 남이 읽고 고치고 믿을 수 있어야 한다. 요구되는 게 다른데 나는 아직 뒤쪽을 해보지 않았다. 그래서 아래는 이렇게 하면 팀이 좋아진다는 얘기가 아니라 혼자 해보니 이런 조건에서 굴러가더라에 가깝다.

모두에게 권할 방식도 아니다. 내 경우엔 절차가 정형화된 업무가 많고, 티켓·배포 같은 주변 시스템이 API로 접근 가능하다는 조건이 맞았다. 이 조건이 안 되면 스킬로 만들 절차 자체가 없다.

반면 기획 문서가 명확하게 나오는 조직일 필요는 없었다. 우리도 기획자가 따로 없다. 기획을 정리하는 게 개발자의 일이라서 하는 것도 아니다. 기획자가 없는 조직에서 기획은 누구의 일도 아니고, 아무도 자기 일이라고 생각하지 않는다. 그리고 아무도 안 하면 일이 진행이 안 된다. 그래서 그냥 한다. 거창한 역할 재정의가 아니라, 일이 굴러가게 하려다 보니 자연스럽게 맡게 된 것에 가깝다. 다만 AI 워크플로우에서는 이 공백을 방치한 대가가 명확하다. 러프한 요청을 그대로 AI에 넘기면 모호함이 코드가 되어 QA에서 터진다. 누가 하든, 누군가는 메워야 하는 공백이다.

그리고 순서가 중요하다. 나도 처음부터 전부 맡긴 게 아니다. 티켓 생성처럼 실패해도 타격 없는 것부터 스킬로 만들었고, 결과물이 안정적으로 나오는 걸 확인한 다음에 구현과 배포로 넓혔다. 신뢰는 단계적으로 쌓는 것이지 선언하는 게 아니다.

6개월 전의 나에게 “곧 코드를 한 줄도 직접 안 치게 될 거야”라고 하면 안 믿었을 것이다. 지금은 반대로, 다시 모든 걸 직접 타이핑하던 방식으로 돌아가라고 하면 그게 더 상상이 안 된다.