에이전트가 만든 코드를 손으로 고치다가 같은 오류를 다시 만난 적이 많다. 첫 수정은 빠르다. 두 번째 수정부터는 작업 방식에 결함이 있다는 신호다. 나는 반복 오류를 타입과 검사 명령, 권한 설정으로 옮긴다.
이 글에서 말하는 하네스는 에이전트가 일하는 실행 환경 전체다. 저장소 규칙은 읽어야 할 맥락을 정한다. 도구 권한은 할 수 있는 행동을 제한한다. 테스트와 로그는 결과를 판정하고, 승인 지점은 외부 배포를 멈춰 세운다. 모델은 이 경계 안에서 코드를 작성한다.
DORA의 2025년 연구는 AI가 조직의 기존 강점과 약점을 확대한다고 설명했다. Anthropic도 장시간 실행하는 코딩 에이전트 실험에서 초기 환경, 기능 목록, 진행 기록, Git 이력을 사용했다. 모델에게 큰 요청 하나를 주는 것보다 다음 세션이 상태를 이어받을 구조를 만드는 데 초점을 맞췄다.
대화가 끝나도 남는 규칙을 만든다
“기존 코드를 존중해 달라”는 문장은 행동을 판정하지 못한다. 에이전트마다 존중의 뜻을 다르게 해석한다. 나는 같은 요구를 저장소 안의 파일과 명령으로 옮긴다.
| 장치 | 에이전트가 얻는 정보 | 사람이 확인할 내용 |
|---|---|---|
AGENTS.md | 수정 범위와 금지된 행동 | 이번 작업에도 규칙이 맞는가 |
| schema와 types | 허용된 데이터 상태 | 잘못된 상태를 표현할 수 있는가 |
| tests와 audit | 성공과 실패의 예시 | 요구사항을 빠뜨리지 않았는가 |
| Git diff | 세션이 바꾼 파일 | 범위를 넘은 수정이 있는가 |
| 진행 기록 | 이전 세션의 결과와 남은 일 | 새 세션이 추측 없이 시작하는가 |
규칙은 짧고 실행 가능해야 한다. “품질 좋은 코드를 작성한다”는 문장은 검사할 수 없다. “primary 글은 reviewed_at을 가져야 한다”, “삭제 명령은 대상 경로를 먼저 출력한다”처럼 성공 조건과 실패 조건을 적는다.
저장소 규칙도 계속 다듬는다. 에이전트가 파일 경로를 반복해서 잘못 찾으면 주요 디렉터리를 문서에 적는다. 같은 명령에서 비밀 값이 출력되면 출력 방식을 고친다. 규칙을 추가한 이유와 막으려는 실패를 함께 남기면 나중에 불필요한 제약을 지울 수 있다.
반복 오류를 하네스 변경으로 바꾸는 법
오류를 고친 뒤 다음 세션이 같은 실수를 할 수 있는지 묻는다. 가능하다면 수정이 끝나지 않은 셈이다. 나는 실패 종류에 맞춰 장치를 고른다.
| 반복되는 실패 | 하네스에 남길 변경 |
|---|---|
| 상태값을 다르게 해석함 | enum 타입과 데이터베이스 제약 조건 |
| 필수 출처를 빼먹음 | frontmatter 검사와 실패 메시지 |
| 관련 없는 파일까지 정리함 | 허용 경로와 diff 검토 단계 |
| 테스트를 고쳐서 통과시킴 | 테스트 파일 수정 금지 규칙과 별도 리뷰 |
| 배포 전 초안을 공개함 | 안전한 발행 기본값과 사람 승인 |
| 긴 작업에서 진행 상황을 잃음 | 구조화된 체크리스트와 세션별 인수인계 |
예를 들어 글에 출처 URL을 넣어 달라고 매번 요청하면 누락을 늦게 발견한다. 콘텐츠 감사 스크립트가 primary 글의 source.url을 검사하게 만들면 발행 전에 명령이 실패한다. 실패 메시지에 파일명과 빠진 필드를 넣으면 에이전트가 수정할 위치도 안다.
이 방식은 프롬프트 길이를 줄인다. 모델에게 과거의 모든 실수를 설명할 필요가 없다. 저장소가 현재 규칙을 보여 주고 검사 명령이 위반 지점을 출력한다.
작업 시작 15분에 범위를 고정한다
에이전트가 코드를 쓰기 전에 현재 상태를 읽게 한다. 나는 다음 순서를 사용한다.
- 관련 파일과 저장소 규칙을 찾는다.
- Git 상태에서 기존 사용자 변경을 구분한다.
- 수정할 파일과 건드리지 않을 영역을 계획에 적는다.
- 변경 전 실행 가능한 검사를 돌려 기준점을 만든다.
- 데이터나 배포 설정을 바꾸면 복구 방법부터 준비한다.
기준점이 없으면 변경 후 생긴 오류와 원래 있던 오류를 구분하기 어렵다. dirty worktree에서는 이 문제가 더 커진다. 에이전트가 다른 사람이 만든 untracked 파일을 정리 대상으로 판단할 수 있으므로, 백업과 Git 상태 기록을 먼저 남긴다.
외부 데이터는 별도 경계를 둔다. Supabase 마이그레이션을 작성하는 작업과 실제 데이터베이스에 적용하는 작업을 나누고, 첫 단계에서는 dry-run과 행 개수를 확인한다. Vercel 배포도 로컬 빌드가 통과한 뒤 진행한다. 코드를 수정할 권한이 외부 시스템을 변경할 권한까지 포함한다고 보지 않는다.
다시 만들 때 필요한 조건
초안 전체를 다시 만드는 편이 수정 비용보다 낮을 때가 있다. 나는 입력 스펙과 샘플 데이터가 고정돼 있고, 자동 검사가 결과를 판정하며, 별도 worktree나 복구 가능한 백업이 준비된 경우에 재생성을 선택한다.
조건을 갖추지 않은 재생성은 이전 오류를 다른 위치로 옮긴다. 화면은 달라져도 누락된 요구사항을 찾을 기준이 없다. 코드가 많아지면 검토 시간도 늘어난다. 작은 단위로 바꾸고 검사한 기록이 있으면 실패한 지점까지만 되돌릴 수 있다.
재생성 범위도 명시한다. 콘텐츠 원고를 다시 쓰는 작업에서 이미지와 slug까지 함께 바꾸지 않는다. 라우팅 구조를 고치는 작업에서 데이터베이스 원본을 삭제하지 않는다. 한 번에 한 종류의 위험만 다루면 검토자가 원인을 찾기 쉽다.
구현과 검토의 입력을 다르게 준다
한 세션에 구현과 검토를 모두 맡기면 검토 단계가 구현자의 설명을 따라간다. 배포나 데이터 변경을 포함한 작업에서는 역할마다 입력을 다르게 준다.
구현자: 요구사항, 현재 코드, 허용 범위를 읽고 최소 변경을 만든다.
검토자: 요구사항, diff, 검사 결과를 읽고 빠진 조건과 회귀를 찾는다.
승인자: 사용자 가치, 운영 위험, 배포 시점을 결정한다.
같은 모델을 사용해도 새 컨텍스트에서 검토를 시작할 수 있다. 검토자에게 구현 과정의 변명을 전달하지 않고 산출물과 증거를 준다. 구현자가 테스트를 추가했다면 검토자는 그 테스트가 요구사항을 충분히 표현하는지 살핀다. 빌드 성공은 타입과 번들 문제를 확인할 뿐, 잘못된 제품 판단까지 증명하지 않는다.
검토 의견도 하네스로 환류한다. “다음에는 조심”으로 끝내지 않고 재현 가능한 실패를 테스트나 감사 규칙으로 옮긴다. 사람의 가치 판단이 필요한 항목은 체크리스트와 승인 단계에 남긴다.
긴 작업은 다음 세션을 독자로 삼는다
에이전트가 여러 컨텍스트에 걸쳐 일하면 새 세션은 이전 대화를 온전히 기억하지 못한다. Anthropic의 장시간 에이전트 실험은 기능 목록과 진행 파일, Git 이력을 다음 세션의 입력으로 사용했다. 나도 긴 작업에 다음 내용을 남긴다.
완료한 항목과 검사 결과
수정한 파일과 선택한 이유
남은 항목과 시작할 위치
확인하지 못한 가정
외부 시스템에 적용하지 않은 변경
복구 경로
“거의 완료” 같은 평가는 쓰지 않는다. content:audit: 20 files, 0 errors처럼 다음 세션이 확인할 수 있는 결과를 기록한다. 실행하지 않은 배포와 데이터베이스 변경도 분리해서 적는다. 기록이 구체적이면 새 에이전트가 완료된 작업을 다시 만들거나 적용하지 않은 변경을 적용됐다고 오해할 가능성이 줄어든다.
블로그 발행 파이프라인에 적용한 구조
이 블로그 자동화는 주제를 받아 원고를 만드는 데서 시작했다. 지금은 자료 확인, 초안 작성, 문체 검수, 사람 승인, 게시를 별도 단계로 다룬다. 새 원고는 draft + archive로 저장한다. 검토자가 출처와 내용을 확인하고 published + primary를 선택해야 글 목록, sitemap, 광고 범위에 들어간다.
primary 글에는 다음 검사를 실행한다.
npm run content:audit
npm run content:links
npm run typecheck
npm run build
콘텐츠 감사는 선정한 slug 목록과 frontmatter를 비교한다. 링크 검사는 본문과 출처 URL을 요청한다. 타입 검사와 빌드는 페이지 코드와 라우팅을 확인한다. archive, diary, vocabulary에는 noindex가 있는지 HTML에서도 확인한다. 광고 스크립트가 primary 글에서만 로드되는지도 대표 URL로 점검한다.
사람은 검사 명령이 판단할 수 없는 부분을 맡는다. 출처를 과장하지 않았는지, 개인 경험처럼 쓴 문장이 사실인지, 글이 독자에게 새로운 판단 기준을 주는지 읽는다. 문체 검수도 금지 표현만 찾지 않고 짧아진 문장을 구체적인 사례와 절차로 보충한다.
하네스는 에이전트의 능력을 과장하지 않는다. 모델이 흔들리는 순간에도 원본 데이터와 공개 페이지를 보호할 장치를 제공한다. 나는 모델 비교보다 실패가 어디에서 멈췄는지 기록하고, 다음 실행에서 같은 실패를 더 일찍 잡는 데 시간을 쓴다. 그 기록이 쌓일수록 바이브코딩 결과의 편차가 줄어든다.