백엔드 개발자가 프론트 화면을 고치기 시작했다 — AI 개발 하네스

백엔드 개발자가 프론트엔드 저장소에 들어와 Jira 티켓으로 기능을 구현했어요. 작은 버그도 수정했고, 마지막에는 저희 프론트엔드팀의 검토를 받았습니다.

세부 컨벤션과 관련 문서의 위치를 작업마다 다시 설명하지 않아도 됐어요. 그 반복 설명을 줄이려고 만든 것이 개발 하네스예요.

얼마 전까지 저는 이 블로그에 "하네스가 뭔지 잘 모른다"고 고백했던 사람이에요. 안 찾아봤다고, 우선순위의 문제라고요. 그 말은 지금도 유효한데 — 결국 하네스를 알게 된 건 검색이 아니라 필요 때문이었습니다. 만들어야 할 일이 생겼거든요.

(그 글에서 "내부가 궁금해지는 날이 오면 그때 파도 늦지 않다"고 했는데, 그날이 진짜 왔습니다. 파는 정도가 아니라 만들었어요.)

병목은 코드가 아니라 설명이었어요

저희 팀 사정은 이 시리즈를 읽으신 분이라면 아실 거예요. 제품 6종에 고객사 8곳, 프론트엔드는 2명. 티켓은 늘 프론트 앞에 줄을 섭니다.

처음에는 세부 규칙을 문서로 나누고 중앙 문서에 참조 링크까지 연결해 두었어요. 그런데 필요한 문서를 빠뜨리는 일이 반복됐습니다. 문서가 있는 것과 작업 중 실제로 확인하는 것은 다르더라고요.

화면 하나를 붙이려는 동료에게 이 내용을 작업마다 다시 설명해야 했어요. 개발 중에는 세부 문서 링크도 하나씩 전달했고요.

그리고 더 큰 비용이 따로 있었습니다. 티켓이 올 때마다 반복되는 일이요.

지라 티켓이 생기면, 누군가 그걸 읽습니다. 에픽을 거슬러 올라가고, 댓글을 뒤지고, 피그마를 열고, 스웨거를 확인하고 — 그걸 요약해서 작업할 사람에게 설명해줘요. 기획·Confluence·Figma·Swagger를 같은 위치에서 다시 확인하고, 빠진 내용이 없는지 살피는 일이 반복됐어요.

구현이 아니라 이 설명 워크플로우가 진짜 병목이었어요. 사람이 하는 일 중 가장 기계적인데, 가장 사람에게 묶여 있었죠.

전제 — 규칙이 이미 기계였다는 것

이 시리즈 앞의 세 편이 전부 이 이야기의 복선이었습니다. 컨벤션은 실패하는 빌드로 존재하고, 구조 변경의 검증 범위를 구분하고, 브라우저가 뭘 받아가는지는 CI가 지켜봐요.

반복해서 확인하던 규칙 일부를 검사로 옮기니, 다른 직군이 참여할 때 필요한 설명을 줄일 수 있었어요.

프론트엔드의 세부 규칙을 모두 외우지 않아도 작업을 시작할 수 있게 된 거예요.

리뷰어의 기억이 규칙을 지키는 코드베이스에서는 낯선 기여자가 위험해요. 검사로 표현한 위반은 빌드 실패로 알려줄 수 있어요. 그래도 구현과 동작 검토까지 없어지지는 않습니다.

그렇다면 남는 문제는 둘이에요. 요구사항을 누가 수집하느냐. 그리고 AI에게 시키는 방법이 사람마다 달라서 결과가 복불복이라는 것. 이 둘을 묶어서 푸는 게 하네스입니다.

하네스 — "작업해줘" 한 마디의 해부

사용자 입장에서 하네스는 이렇게 생겼어요.

반복하던 자료 확인과 정리를 수집 단계에 넣고, 구현 전 요구사항을 사람이 검토하도록 했어요. 작업자는 티켓 번호로 시작하되, 빠진 요구사항과 자료 사이의 불일치를 함께 확인합니다.

실행 범위는 사용자의 말로 정해져요. 옵션 플래그가 아니라, 사람이 원래 쓰는 문장으로요.

이 표에서 제일 중요한 건 마지막 두 줄이에요. 커밋·PR·지라 상태 변경 같은 바깥에 흔적이 남는 일은 기본 범위에 없습니다. 명시적으로 말해야만 해요.

AI에게 일을 시킬 때 제일 무서운 건 실력이 아니라 월권이거든요. 시키지 않은 커밋, 물어보지 않은 티켓 코멘트. 그래서 권한의 계단을 사용자 언어에 박아놨습니다.

수집과 구현을 갈랐어요

내부는 두 덩어리로 나뉩니다. 수집을 담당하는 오케스트레이터와, 구현을 담당하는 구현 하네스요.

규칙은 하나예요. 구현 하네스는 지라·피그마·슬랙 커넥터에 의존하지 않는다.

구현부가 외부 시스템을 직접 물면, 지라가 느린 날 구현이 멈추고, 피그마 API가 바뀌면 구현 코드를 고쳐야 해요. 그래서 구현부는 정규화된 task record 하나만 입력으로 받습니다. 바깥세상이 어떻게 생겼는지 몰라요.

이 경계, 어디서 본 모양이죠. 플러그인이 DB를 모르고, 렌더러가 집계 위치를 모르는 것과 같은 원칙입니다. 하네스를 설계할 때도 결국 같은 손버릇이 나오더라고요.

태스크마스터를 닮은 티켓 — task record

하네스의 심장은 task record라는 JSON 문서 하나예요. 태스크마스터(Taskmaster) 같은 AI 작업 관리 도구를 써보신 분이라면 낯익은 모양일 겁니다. 그 형태를 레포 안에 내장한 셈이에요.

{"id": "TICKET-731","input":          { "goal": "정산 요약 화면", "jiraKey": "...", "swaggerSources": ["..."] },"requirements":   { /* 지라·피그마에서 정규화한 요구사항 */ },"architecture":   { /* 어느 패키지가 소유하는가, 어떤 계약을 쓰는가 */ },"questions":      [ /* 소스가 침묵하는 지점 — 사람에게 물을 것 */ ],"implementation": { /* 단계별 진행 상태 */ },"verification":   { /* 게이트·테스트 통과 증거 */ },"decisions":      [ /* 버린 대안과 그 이유 */ ]}

구조가 곧 프로세스예요. 위에서 아래로 채워지고, 앞 칸이 비면 뒤 칸을 못 채웁니다. 요구사항 없이 구현 못 하고, 검증 없이 완료 못 해요.

여기서 아낀 게 하나 더 있습니다. questions 칸이요. 소스를 다 읽고도 답이 없는 지점 — "이 버튼, 실패하면 어떻게 되나요?" — 만 모아서 사람에게 옵니다. 목표는 반복 설명을 줄이고 필요한 판단을 사람에게 모으는 거예요. 다만 이미 해결된 내용이나 간단한 문제를 다시 질문하기도 해서, 질문 자체의 타당성도 검토해야 합니다.

마지막 줄이 운영에서 제일 고마운 부분이에요. 각 단계가 독립 체크포인트라, 지라 보고가 실패했다고 성공한 구현을 다시 돌리는 일이 없습니다.

동시성도 record가 지켜요. 같은 task를 두 세션이 잡으면 lease가 충돌을 막습니다. 사람 둘이 같은 티켓을 잡는 사고를, 에이전트 둘이 재현하지 않도록요.

설치도 소프트웨어처럼 다룹니다

하네스에서 제가 제일 마음에 들어하는 부분은 사실 실행이 아니라 설치예요.

.harness/
  harness.lock.json     ← 스킬 버전·payload SHA·프로토콜을 고정
  payload/              ← 에이전트들이 공유하는 실행 규칙 원본
  task.schema.json      ← 티켓의 형태 그 자체
  state.local.json      ← 개인 상태 (Git 밖)

.claude/skills/  .agents/skills/   ← clone마다 설치되는 관리형 사본

실행 규칙이 lock 파일로 버전·해시가 고정돼요. 의존성을 잠그듯 워크플로우를 잠그는 겁니다. 그리고 같은 payload를 Codex와 Claude가 공유해요 — 도구를 갈아타도 일하는 방식은 그대로라는 걸, 이번엔 파일 하나로 보장하는 거죠.

설치 상태도 그냥 "됐다/안 됐다"가 아니라 상태 기계입니다.

downgrade-blocked 같은 상태가 있다는 게 이 설계의 성격을 보여줘요. 잘못 낮춰 깔리는 것까지 막습니다. 워크플로우를 소프트웨어로 취급하면, 워크플로우에도 버전 충돌이 있다는 걸 인정하게 되거든요.

AI가 남긴 코드의 "왜"를 지키기

AI가 구현하면 코드는 남는데 이유가 날아가기 쉬워요. 그래서 하네스에는 결정 기록 규칙이 같이 붙어 있습니다.

// TICKET-731: 스웨거에 응답 스키마가 아직 없어 임시 타입으로 대체// 제거 조건: 정산 API v2 스키마가 공개되면 이 파일을 지우고 계약 타입을 쓴다

임시 구현에는 티켓 번호·이유·제거 조건이 반드시 붙어요. 여러 파일에 영향을 주는 결정은 별도 문서로 남기고, 필수 항목에 "버린 대안"이 들어갑니다. 완료된 구현에 "제안됨" 상태의 결정을 남기는 건 금지고요 — 결정 못 한 건 결정이 아니라 blocker로 보고해야 합니다.

아키텍처 예외를 주석으로 승인하는 것도 금지예요. 규칙을 바꾸고 싶으면 구현을 멈추고, 규칙 원본과 검사를 같이 바꿔야 합니다. 게이트를 우회하는 뒷문을 하네스가 직접 만들지 않도록요.

그래서 정말 되냐면

됩니다. 다만 정확히 말할게요.

백엔드 개발자가 프론트엔드 기능을 만들고 작은 버그를 수정한 사례가 있어요. 기획자도 사용할 수 있도록 진입 절차를 표준화했습니다. 다만 각자 본업이 있어서 실제로는 주로 저희 프론트엔드팀이 하네스를 사용해요.

하지만 게이트가 모든 걸 잡아주는 건 아니에요.

리뷰가 사라진 게 아니라 이동했어요. "컨벤션 지켰나"를 보던 시간이 "설계가 맞나"를 보는 시간이 됐습니다. 그리고 그건 기계에 못 맡기는, 원래 사람이 했어야 하는 리뷰고요.

솔직한 한계도 하나. AI 구현 품질은 여전히 편차가 있습니다. 하네스는 바닥을 올려주는 장치지 천장을 올려주는 장치가 아니에요. 정해 둔 검사로 컨벤션 위반을 발견하는 것과 결과가 제품 요구에 맞는지는 별개의 문제예요. 기획·Figma·Confluence의 불일치, 백엔드 기능 누락과 협업 조율은 사람이 확인하고 최종 결과도 검토합니다.

줄어든 것은 제가 직접 개입하는 시간이었어요

하루 단위로 걸리던 작업에서 제가 직접 개입하는 시간은 약 1시간 수준으로 줄었다고 느껴요. 사용 경험에 따른 추정이지 측정 로그의 평균은 아닙니다.

개발 전체가 1시간 만에 끝난다는 뜻은 아니에요. 에이전트가 구현하고 테스트하는 시간은 따로 흐르고, 저는 요구사항 판단과 결과 검토에 참여합니다. 총 완료 시간과 사람의 개입 시간을 구분하는 게 이 변화의 핵심이에요.

다음 상상 — 게이트를 한 칸 더 왼쪽으로

여기서부터는 아직 만든 게 아니라 상상이에요. 그런데 요즘 이 생각을 자주 합니다.

지금 하네스는 개발 단계의 입구에 서 있어요. 티켓이 이미 존재한다는 전제죠. 그런데 요구사항이 빠지거나 서로 어긋나는 문제는 티켓이 만들어지기 전부터 시작되기도 해요.

기획자가 초안을 넣으면, 하네스가 이 체크리스트로 심문하는 거예요.

[기획 하네스 심문 — 상상]Q. 이 목록의 최대 행 수는 얼마인가요? 미정이면 최악 케이스 기준으로 답해주세요.
Q. "저장" 버튼의 로딩·실패·권한없음 상태가 정의되지 않았어요.
Q. 이 화면의 "그룹"이라는 용어가 기존 스펙의 "조직"과 충돌해요.

질문에 답이 채워진 스펙만 개발 티켓이 될 수 있고, 그 정규화된 스펙이 그대로 개발 하네스의 input이 됩니다. 두 하네스가 파이프라인으로 이어지는 거죠. 지금은 "설명이 필요 없는 작업자"를 만들었는데, 그땐 애초에 설명이 필요 없는 티켓이 내려오는 거예요.

개발 리뷰에서 "이 경우엔 어떻게 되나요?"라고 묻던 것들이, 시니어 기획 리뷰가 하던 일이 — 검사가 되는 겁니다. 사람이라 비쌌고 안 규칙적이었을 뿐, 원래 있던 일이에요.

요즘 말로 하면 이게 AX라던데, 저는 그 단어보다 이렇게 부르고 싶어요. 게이트를 한 칸 왼쪽으로 미는 것. AI는 그걸 갑자기 싸게 만들어준 도구고요.

이 시리즈는 "규칙은 문서가 아니라 실패하는 빌드다"로 시작했어요. 세 편 내내 규칙을 기계로 옮겼고, 이번 편은 그 배당금 이야기였습니다.

지금은 다른 직군도 정해진 절차로 프론트엔드 작업에 참여하고, 저희 팀은 반복 설명보다 요구사항과 결과 검토에 시간을 쓸 수 있어요. 검사와 사람의 판단을 함께 둔 채 직접 개입을 줄인 것, 제가 하네스를 계속 쓰는 이유입니다.