본문으로 건너뛰기

Frontend AI Ops · EP 02

프롬프트가 아니라 실행 환경이다 — 계약과 하네스로 생성 품질 고정하기

AI 에이전트의 출력이 매번 달라지는 건 모델 문제가 아니라 입력 문제다. Context Contract·Spec Contract·Task Contract 세 가지 계약과 하네스 4단계, 리뷰 가드레일 4계층을 실제로 돌아가는 시스템의 기록과 함께 정리했다.

· 9분 읽기

프롬프트가 아니라 실행 환경이다 — 계약과 하네스로 생성 품질 고정하기

3월에 프론트엔드 AI 실무 시리즈에서 PRD를 티켓으로 분해하는 글을 썼다. 이어서 Context Contract, PR 리뷰 에이전트 가드레일, 하네스 엔지니어링, 스펙 드리프트까지 두 달에 걸쳐 다섯 편을 썼다. 주제는 저마다 달라 보였는데, 돌아보면 같은 문장을 다섯 번 쓴 것이었다.

입력을 고정하지 않으면, 출력은 매번 다른 사람이 쓴 것처럼 나온다.

앞 편에서 다룬 검증 게이트가 “이미 나온 결과물을 증명하는 장치”라면, 이번 글은 결과물이 나오기 전에 품질을 고정하는 장치다. 이 글은 3월의 다섯 편을 한 편으로 합쳐 다시 쓴 것이다. 프레임은 남기고, 그 사이에 지금 실제로 돌아가는 시스템의 기록을 이식했다.

1. 첫 주 폭증, 셋째 주 붕괴

AI를 프로젝트에 처음 붙이면 거의 정해진 패턴으로 진행된다. 첫 주 생산성 폭증, 둘째 주 코드 스타일 붕괴, 셋째 주 회귀 버그와 리뷰 피로. 속도에 놀라 계속 밀어붙이다 보면, 어느 순간 리뷰가 초안 반려 처리로 변해 있는 자신을 발견한다.

원인은 모델이 똑똑하지 못한 게 아니다. 입력 기준이 불안정한 것이다. 매번 다른 맥락, 다른 규칙, 다른 완료 기준이 들어가면 출력도 매번 달라진다. 글쓰기도 똑같다. 이 블로그의 발행 파이프라인은 아이디어 → 명세 → 초안 → 편집 → 발행으로 나뉘는데 초안은 에이전트가 쓴다. 명세 단계를 건너뛰고 초안부터 돌리면 어떤 글이 나올지 아무도 모른다. 코드가 왜 다르겠는가.

해결은 단순하다. 에이전트에게 매번 전달되는 규칙을 문서로 고정한다. 그 문서를 나는 **계약(contract)**이라고 부른다. 계약이 고정하는 건 세 가지다.

  1. 기술적 경계 — 어떤 스택과 패턴을 허용할지
  2. 품질 기준 — lint·build·test의 통과 조건
  3. 산출물 형식 — PR 설명, 체크리스트, 로그의 포맷

2. 계약의 3종 — 무엇을 고정하느냐에 따라 달라진다

계약은 쓰이는 시점에 따라 세 종류다. 요구를 고정하는 Spec Contract, 작업을 고정하는 Task Contract, 실행 환경을 고정하는 Context Contract. 요구에서 실행으로 내려올수록 계약은 구체가 된다.

Spec Contract — 요구사항의 계약

“무엇을 했는지”가 아니라 무엇을 반드시 지켰는지를 먼저 선언한다. PR 본문 첫 줄에 박는다.

## Spec Contract
- 필수 시나리오: 로그인 사용자, 비로그인 사용자
- 예외 시나리오: API 4xx/5xx, 네트워크 타임아웃
- 제외 범위: 관리자 화면 확장

Task Contract — 작업 단위의 계약

작업 하나가 시작되기 전에 네 줄로 고정한다. 이건 템플릿이 아니라 이 블로그의 archive 검색 개선 작업에 실제로 썼던 계약이다.

## Task Contract

- Goal: archive page 검색 UX 개선
- Scope: app/archives, app/api/posts, app/lib/posts만 수정
- Non-goals: 디자인 시스템 전면 개편, 라우팅 구조 변경
- Verification: pnpm check, pnpm build

이 계약은 에이전트를 통제하는 문서이면서, 리뷰어에게는 “왜 이 파일만 바뀌었는지”에 대한 근거가 된다. AI-assisted PR 사례 정리에서 다룬 것처럼, Scope를 벗어난 diff는 리뷰어가 스타일보다 먼저 보게 되는 것이다.

작업을 시작하는 내 순서도 정해져 있다. 에이전트에게 시키기 전에 spec.md를 먼저 쓰고, 요구사항·경계 조건·하지 말아야 할 것을 적은 다음, 에이전트에게 역질문을 반복시켜 빠진 조각을 채운다. Osmani의 표현을 빌리면 “waterfall in 15 minutes” — 워터폴의 장점인 명세를 15분 안에만 하는 것이다. 이렇게 작업하는 법을 정리하면서 실감한 건, 계약 단계에서 발견하는 위반 유형(타입 누수, 서버/클라이언트 경계 오용, 접근성 속성 누락)이 리뷰 단계에서 발견하는 같은 위반보다 훨씬 싸다는 당연한 사실이었다.

Context Contract — 실행 환경의 계약

에이전트가 돌아가는 환경 자체의 규칙이다. 최소 형태는 이 정도다.

# Context Contract v1

## Stack
- Next.js App Router + TypeScript
- 스타일: Tailwind 우선
- 상태관리: 서버 상태는 React Query, 전역 상태 최소화

## Rules
- any 금지, 타입 단언 최소화
- 비즈니스 로직은 UI 컴포넌트 밖으로 분리
- 접근성: 버튼/링크 role, label 누락 금지

## Done Criteria
- pnpm lint 통과
- pnpm build 통과
- 핵심 E2E smoke 3개 통과

## Output Format
- 변경 요약 5줄 이내
- 리스크/롤백 포인트 1개 이상
- 테스트 로그 링크 첨부

포인트는 완벽함이 아니라 일관성이다. 규칙 50개짜리 문서보다, 10개 규칙을 모든 작업에 일관되게 적용하는 문서가 강하다. 그리고 Context Contract는 팀 규칙의 압축본이지 개인 취향의 목록이 아니다. 취향이 섞이는 순간 계약이 아니라 선호장이 된다.

3. 하네스 — 나쁜 답이 들어와도 품질을 지키는 시스템

프롬프트 엔지니어링이 “좋은 답을 요청하는 기술”이라면, 하네스 엔지니어링은 “나쁜 답이 들어와도 품질을 지키는 시스템”이다. 계약이 문서라면 하네스는 그 문서를 집행하는 기계다. 최소 구성은 4단계다.

1) 입력 경계. 에이전트가 수정할 수 있는 파일 범위, 금지 영역(인증·결제·공통 유틸), 완료 기준을 미리 선언한다. “그럴듯하지만 위험한 수정”은 이 단계에서 잘린다.

2) 자동 검증 체인. lint/typecheck → 핵심 플로우 테스트 → build. 중요한 건 “많이 검사”가 아니라 항상 같은 순서로 검사하는 것이다. 순서가 흔들리면 결과를 비교할 수 없다.

3) 사람 리뷰 체크리스트. AI 코드의 첫 번째 위험은 동작 실패보다 설계 일관성 붕괴다. 사람은 세 가지만 본다 — 기존 아키텍처 경계를 깨지 않았는가, 에러/로딩/빈 상태 처리가 누락되지 않았는가, 비즈니스 규칙이 하드코딩되지 않았는가.

4) PR 템플릿. 본문 형식을 고정하면 검증이 서사가 된다.

## 변경 요약
- 무엇을 바꿨는지
- 왜 바꿨는지

## AI 사용 범위
- 초안 생성:
- 사람이 직접 수정:
- 반려한 제안:

## 검증 결과
- lint/typecheck:
- test:
- build:

## 리스크와 후속 작업
- 남은 리스크:
- 다음 액션:

하네스의 리뷰 단계에서 내가 쓰는 방법은 에이전트를 분리하는 것이다. 구현은 컨텍스트를 쌓아둔 주력 에이전트(Claude Code)에게, 리뷰는 성격이 다른 에이전트(Codex)에게. 코드를 쓴 모델은 자기 코드를 못 본다. 다른 모델의 눈이 필요하고, 둘의 의견이 갈리는 지점이 진짜 설계 결정이 필요한 곳이어서 사람이 판단한다. 이 운용의 디테일 — 긴 세션은 컨텍스트 60%쯤에서 compaction 타이밍을 관리한다든지 — 은 듀얼 에이전트 실전 비교에 따로 정리했다.

이 구조의 전제는 세션 관리다. 두 에이전트의 히스토리가 각자 흩어지면 “지난번에 뭐라고 리뷰받았더라”부터 무너진다. 그래서 나는 에이전트 CLI 9개의 세션과 권한을 하나로 묶는 데몬을 직접 만들어 쓰고 있다. 하네스를 문서가 아니라 돌아가는 시스템으로 옮긴 셈이다. 검증 체인이 배포 단계까지 커지면 검증 게이트가 되는데, 그 이야기는 앞 편에서 했다.

4. 리뷰 에이전트에는 가드레일이 필요하다

리뷰를 에이전트에게 맡기면 먼저 만나는 건 개선이 아니라 실패 목록이다. 과잉 경고 — 중요하지 않은 스타일 코멘트가 쏟아져 신뢰가 떨어진다. 허위 지적 — 문제 없는 코드를 잘못 지적한다. 중요 이슈 누락 — 접근성·보안·성능을 놓친다. 규칙 불일치 — 팀 컨벤션과 다른 기준으로 말한다. 그래서 모델을 고르기 전에 가드레일을 설계한다. 4계층이다.

1) 입력 계층. 에이전트가 읽는 정보를 고정한다 — 변경 파일 목록, PR 설명(목표/범위/비범위), 팀 리뷰 규칙, 도메인 경계. 컨텍스트가 흔들리면 출력도 흔들린다.

2) 분석 계층. 코멘트를 위험도로 분리한다. P0 보안/데이터 손상, P1 사용자 영향이 큰 버그 가능성, P2 유지보수성·성능 제안, P3 스타일·선호. 분류가 없으면 리뷰어의 집중이 분산된다.

3) 출력 계층. 모든 코멘트에 근거 3요소를 강제한다 — 문제 위치(파일/라인), 위험 근거, 재현 또는 검증 방법. 하나라도 없으면 ‘제안’ 등급으로 강등한다. 이 규칙 하나가 허위 지적을 크게 줄인다.

4) 결정 계층. AI 코멘트가 곧 머지 차단 조건이 되면 팀이 지친다. P0/P1만 차단 후보이고, 최종 머지 권한은 사람 리뷰어에게 남는다.

요약하면 AI는 증폭기이고, 사람은 승인자다.

이 원칙을 나는 리뷰 이전의 영역에 먼저 시스템으로 만들어뒀다. 파일 쓰기, 커밋, 네트워크 같은 파괴적 행위는 에이전트가 임의로 실행하지 못하고, 승인 요청이 내가 보는 채널(웹 UI, CLI, 텔레그램 버튼)로 릴레이된다. “이 커밋 날려도 될까요?”가 오면 확인하고 버튼 하나로 승인한다. LLM을 “과신하고 실수에 취약한 주니어 개발자처럼 대하라”는 조언에 한 걸음 더 나아가, 그 주니어에게 프로덕션 키를 주지 않는 구조를 코드로 만든 것이다. 리뷰 가드레일의 결정 계층과 완전히 같은 모양이다.

5. 스펙 드리프트 — 기능은 도는데 요구사항에서 벗어난다

계약과 하네스를 갖춰도 남는 실패가 있다. 기능은 돌아가는데 요구사항의 핵심에서 살짝씩 벗어나는 스펙 드리프트다. 원인을 모아 보니 네 패턴으로 수렴했다.

패턴증상원인
상태 누락형데모에서는 잘 되는데 빈/에러/권한 거부 상태가 없다비정상 시나리오가 입력에 명시되지 않음
경계 침범형서버 로직이 클라이언트로 밀린다, 번들이 부풀어 있다서버/클라이언트 경계를 못 박지 않음
UX 단축형동작은 하는데 키보드 탐색·에러 복구가 약하다”동작 구현” 중심 지시, UX 제약 누락
측정 실종형머지는 됐는데 추적 로그와 지표가 없다관측 항목이 PR 정의에 없음

대응은 세 가지다. 첫째, §2의 Spec Contract를 PR 첫 줄에 고정한다. 둘째, 프롬프트에 금지사항을 명시한다. “이렇게 하라”만 있으면 경계가 흔들린다.

Do Not:
- 서버 컴포넌트를 클라이언트로 강제 전환하지 말 것
- 기존 API 스키마를 임의 변경하지 말 것
- 접근성 속성(role/aria-label) 삭제하지 말 것

셋째, 리뷰의 질문을 바꾼다. “어떤 게 바뀌었나”가 아니라 — 이 변경이 요구사항 계약에서 벗어난 부분은 없는가, 테스트가 기능 성공이 아니라 요구사항 충족을 증명하는가, 문서와 로그가 다음 작업자에게 재현 가능한가.

그리고 이탈 기록을 지우지 않는다. 위반을 카테고리(타입/상태/네트워크/접근성)로 나눠 쌓아두면 감이 패턴이 된다. 내 경우 그 패턴은 세션 로그에 남는데, 3개월 전에 정리해둔 실패 케이스가 검색어 하나로 회수된다 — 세션 히스토리 이야기에서 다룬 그 기록이다. 스펙 드리프트는 반복되는 실패라는 점에서 기억장치가 곧 가드레일이 된다.

6. PRD에서 티켓까지 — 요구 단계의 계약

흐름의 가장 위, 요구 단계로 돌아가자. PRD를 에이전트가 읽고 티켓을 뽑게 할 때는 한 번에 티켓을 만들지 않는다. 2단계로 나눈다.

1단계, 정규화. PRD에서 사용자 시나리오, 수용 기준, 비기능 요구사항(성능/접근성/보안), 의존성만 추출한다. 결과물은 티켓이 아니라 구조화된 JSON 요약이다. 2단계, 티켓 생성. 이 요약을 입력받아 Epic(기능 단위) → Story(사용자 가치 단위) → Sub-task(구현 단위)와 DoD를 만든다. 목표는 완벽한 티켓이 아니라 사람이 검수할 수 있는 초안이다.

AI가 뽑은 티켓이 실무에서 깨지는 지점도 세 곳으로 수렴한다 — UI 상태 전이 누락(로딩/빈/오류/성공의 분리, 낙관적 업데이트 실패 시 롤백), 접근성 조건 누락(키보드 내비게이션, 스크린리더 라벨), 측정 지표 누락(클릭/전환/이탈 이벤트 정의). 이 세 가지는 시스템 프롬프트에 강제한다.

{
  "title": "[FE] 회원가입 폼 검증 UX 개선",
  "type": "story",
  "priority": "P1",
  "acceptanceCriteria": [
    "이메일 형식 오류 시 즉시 인라인 에러를 노출한다",
    "비밀번호 규칙(8자 이상, 특수문자 포함)을 실시간 안내한다",
    "모든 에러 메시지는 스크린리더로 읽힌다"
  ],
  "frontendTasks": [
    "폼 상태 머신 정의 (idle/loading/error/success)",
    "검증 로직 유닛 테스트 추가",
    "Playwright E2E: 잘못된 입력/정상 입력 케이스 추가"
  ],
  "dependencies": ["Auth API v2", "디자인 시스템 TextField 컴포넌트"],
  "definitionOfDone": [
    "E2E 통과",
    "접근성 점검 통과",
    "분석 이벤트 대시보드에서 수집 확인"
  ]
}

이제 다섯 편이 왜 한 편이었는지가 보인다. 요구(PRD·Spec Contract) → 작업(Task Contract) → 실행(Context Contract) → 검증(하네스 체인) → 리뷰(가드레일). 계약이 요구에서 리뷰까지 하나의 파이프라인으로 내려오는 것이었고, 3월의 글들은 그 파이프라인의 각 기역마다를 따로 찍어놓은 사진이었다.

시작 체크리스트

내일 작업 하나에 붙여본다면, 이 순서다.

  1. 프로젝트 규칙을 10줄 Context Contract로 고정한다
  2. 작업 시작 전 Task Contract 네 줄(Goal/Scope/Non-goals/Verification)을 먼저 쓴다
  3. lint → 테스트 → build를 항상 같은 순서로 돌린다
  4. 리뷰 코멘트에는 근거 3요소(위치·근거·재현 방법)를 강제한다
  5. PR 본문 첫 줄에 Spec Contract, 끝에 검증 로그를 남긴다

남는 것

3월의 다섯 편에 나눠 쓴 결론을 한 문장으로 줄이면 이렇다. 생성 품질은 모델이 아니라 환경이 결정한다. 모델은 몇 달마다 바뀌지만 계약과 하네스는 저장소에 남는다. 도구가 바뀌어도 워크플로 자산이 따라간다는 것은, 두 에이전트를 함께 쓰면서 이미 확인했다.

“AI를 잘 쓰는 사람이 아니라, 품질을 통제하는 사람” — 이 시리즈를 다시 쓰는 이유도 결국 이 문장 하나다.

계약과 하네스로도 못 막는 게 하나 남는다. 장애다. 장애가 터졌을 때의 시스템과 큰 변경을 안전하게 겪는 법은 이어지는 글에서 다룬다.

Related

· 17 min read Build Logs

spec-studio 구축기 — 화면설계서의 번호를 객체로 옮기고, SQLite 한 파일을 정본으로 두기

기획 올인원 툴을 버리고 그린필드로 다시 세운 spec-studio. 화면 위 번호 핀을 불변 객체로 만들고, 로컬 SQLite 한 파일을 정본으로 두고, Confluence에는 단방향 사본만 보냅니다. 6타입·7링크 추적 그래프, L0→L1→L2, 제안→결정→되돌리기, LLM 제안과 한국어 골든셋 30건 eval까지 — 커밋 16개, 테스트 157개, mock 기준 스키마 100%·타입 93%·링크 92%의 기록입니다.

프론트엔드AI
→