바이브 코딩, 시작 전에 반드시 설계해야 할 것들 — 하네스 코딩·컨텍스트 관리·토큰 비용 절감 실전 가이드
바이브 코딩을 시작할 때 가장 먼저 해야 할 일은 코드를 작성하는 것이 아니다. 나중에 바뀔 요구사항을 예측하고, AI가 수정할 수 있는 경계를 설계하는 일이다. 작은 기능 하나를 추가했는데 수십 개 화면을 고쳐야 한다면, 그 비용은 코드 작성 시간뿐 아니라 AI 컨텍스트와 토큰, 테스트와 디버깅 비용으로 돌아온다.
1. 색상 테마 버튼 하나가 왜 대규모 수정이 되었을까?
최근 앱 개발 중 화면 테마를 세 가지로 제공하자는 요구가 생겼다. ① 네온(기본): 짙은 검정 우주 배경과 흰색·네온 색상 ② 화이트: 흰 배경과 진한 회색 글씨 ③ 크게 보기: 아이보리·흰색 배경, 큰 검정 글씨와 기본 시스템 글꼴. 상단의 ‘Aa’ 버튼을 누르면 테마가 순환하고 선택값도 기억하도록 하는 기능이다.
기능 정의만 보면 단순한 버튼이다. 그러나 개발 중간에 추가하자 약 330곳에 흩어진 고정 색상, 화면마다 다른 글꼴 및 크기, 개별 컴포넌트의 스타일을 찾아 바꿔야 했다. 화면별 세 가지 조합을 검토해야 하므로 수정은 곧 테스트 범위의 폭증으로 이어진다. 이 사례에서 중요한 것은 ‘테마 버튼을 나중에 넣으면 안 된다’가 아니다. 테마가 앞으로 바뀔 수 있는 제품이라면 색상과 타이포그래피를 처음부터 개별 화면이 아닌 공통 토큰으로 관리해야 한다는 점이다.
예를 들어 화면에서 직접 #07060E와 #FFFFFF를 쓰는 대신 theme.colors.background와 theme.colors.text를 참조하게 만들면, 테마 추가 시 수정 범위를 중앙 설정과 일부 예외 컴포넌트로 줄일 수 있다. 글자 크기와 간격도 마찬가지다. ‘크게 보기’는 색상만의 문제가 아니다. 글자 확대에 따른 줄바꿈, 버튼 높이, 접근성, 레이아웃 밀림, 플랫폼별 글꼴 제공까지 확인해야 한다.
2. 바이브 코딩과 하네스 코딩은 어떻게 다른가?
바이브 코딩은 자연어로 원하는 결과를 설명하며 AI의 코드 생성 능력을 활용하는 개발 방식이다. 초기 시제품을 빠르게 만드는 데 강점이 있다. 하지만 작업을 반복할수록 ‘이전에 무엇을 결정했는가’, ‘어디까지 수정해도 되는가’, ‘무엇으로 성공을 판정하는가’가 중요해진다.
하네스 엔지니어링(Harness Engineering)은 AI 코딩 에이전트가 일할 수 있도록 둘러싼 실행 환경을 설계하는 것이다. 저장소 문서, 코드 탐색 방식, 작업 지시, 허용된 도구, 권한, 검증 스크립트, 테스트, 로그 수집, 변경 리뷰와 실패 복구까지 포함한다. 단지 에이전트에게 긴 지침서를 주는 것이 아니다. AI가 잘못된 수정을 하기 어렵게 만들고, 잘못한 경우 빠르게 발견하도록 만드는 구조가 핵심이다.
즉 ‘AI에게 전체 코드를 수정해 달라’는 요청에서 ‘수정 범위를 제한하고, 테스트로 통과 여부를 확인하며, 실패 요약만 다시 전달하는 작업 루프’로 옮겨가는 것이다. OpenAI의 하네스 엔지니어링 사례 역시 명확한 아키텍처 경계, 저장소 안의 지식, 자동 검사, 에이전트가 읽을 수 있는 피드백을 강조한다.
3. 프로젝트 생성 전에 확정할 설계 항목
3-1. 기능보다 먼저 변경 가능성을 분류한다
모든 기능을 처음부터 다 구현할 필요는 없다. 대신 나중에 바뀔 가능성이 높고, 바뀌면 전 화면에 영향을 주는 항목은 초기에 결정해야 한다. 대표적으로 디자인 테마·글꼴·언어·시간대·권한·인증·결제·알림·데이터 저장 방식·API 버전·환경 설정·접근성이 있다.
첫 기획 문서에는 기능 목록과 별개로 ‘변경 영향도가 큰 공통 정책’ 표를 만든다. 예: 테마(전체 UI), 인증(모든 보호된 API), 날짜/시간(조회·통계·알림), 유료화(권한·서버 검증·UI), 데이터 모델(저장·마이그레이션·API). 당장 구현하지 않더라도 변경 경로는 확보한다.
3-2. 공통 설정을 화면과 분리한다
테마 토큰은 배경·표면·본문·보조 글씨·강조·경고·구분선 등 의미 중심으로 정의한다. 글꼴은 제목·본문·캡션의 타입 스케일로 정의하고, 여백·모서리 반경·아이콘 크기도 공통 기준을 둔다. 화면은 구체적인 색상값이 아니라 의미 있는 토큰만 참조한다. 이렇게 해두면 네온에서 화이트로 바꾸더라도 화면 로직과 디자인 정책이 뒤섞이지 않는다.
3-3. 도메인과 계층의 책임을 구분한다
소규모 앱에서도 최소한 features/ (기능), shared/ui/ (공통 UI), theme/ (스타일 토큰), services/ (외부 API), data/ (저장소), config/ (환경 설정), tests/ (검증)을 구분할 가치가 있다. 파일 이름만 예쁘게 나누는 것으로 끝나서는 안 된다. 예컨대 UI 컴포넌트가 데이터베이스에 직접 접근하지 않는다는 의존성 규칙이 필요하다. 작은 프로젝트라면 이 구조를 더 단순하게 시작해도 된다.
3-4. 비기능 요구사항을 반드시 정의한다
화면이 정상적으로 보이는 것만으로 제품이 완성되는 것은 아니다. 개인정보·보안·오프라인 처리·백업·복구·응답속도·동시 사용자·접근성·배포 경로·운영 로그·오류 알림·구독 결제 검증을 초기에 점검해야 한다. 나중에 추가할수록 수정 범위가 커질 수 있는 내용들이다.
4. 컨텍스트가 커질수록 왜 작업 결과가 나빠질 수 있을까?
AI 모델에는 한 번에 처리할 수 있는 컨텍스트 창이 있다. 이 안에는 개발 지시문뿐 아니라 이전 대화, 읽어온 파일, 명령 실행 결과, 빌드 로그, 오류 출력이 쌓인다. 컨텍스트 용량이 늘어난다고 매번 정확도가 반드시 하락하는 것은 아니다. 그러나 쓸모없는 내용이 너무 많아지면 관련 근거가 묻히고, 오래된 설계와 최신 설계가 충돌하며, 비용과 지연이 늘어날 수 있다. 긴 컨텍스트에서 중요한 정보를 찾아내는 능력이 악화되는 현상을 ‘컨텍스트 로트(context rot)’라고 부르기도 한다.
특히 하나의 채팅에서 요구사항 정의, 기능 구현, 오류 수정, 빌드 결과, 서버 로그, UI 재디자인을 모두 처리하면 무엇이 현재 목표인지 불명확해진다. 긴 작업 내역을 무조건 보존하기보다 결정 사항은 파일에 보존하고, 현재 작업에 필요한 자료만 AI에게 다시 제공하는 편이 효율적인 경우가 많다.
4-1. 프로젝트 메모리와 채팅 기록을 구분한다
README.md에는 실행 방법, ARCHITECTURE.md에는 경계와 데이터 흐름, DECISIONS.md에는 바뀌지 않는 의사결정, AGENTS.md 또는 도구별 에이전트 지침 파일에는 수정 금지 영역·테스트 명령·완료 기준을 기록한다. 각 파일은 간결하게 유지하고 실제 코드와 맞지 않는 문서는 갱신한다. 에이전트가 자동으로 읽는 파일명과 범위는 사용 중인 도구별로 확인해야 한다.
4-2. 컨텍스트를 압축하되 중요한 상태는 잃지 않는다
세션이 길어지면 목표, 완료된 작업, 핵심 파일, 설계 결정, 남은 오류, 다음 확인 명령만 요약해 새 작업으로 넘긴다. 원본 로그와 대용량 출력은 파일로 보존하고 필요할 때 다시 읽는다. 무작정 요약하면 미해결 예외나 복구 조건이 빠질 수 있으므로 변경된 파일·테스트 결과·환경 정보 같은 핵심 사실을 함께 기록해야 한다.
5. 개발과 디버깅을 왜 분리해야 할까?
기능 개발과 디버깅은 목적부터 다르다. 개발 단계에서는 요구사항을 구현하고, 디버깅 단계에서는 재현 조건을 좁혀 원인을 찾아야 한다. 두 작업을 한 세션에서 무제한 반복하면 AI가 원인을 확정하지 못한 채 관련 없는 파일까지 수정하거나, 정상 동작하던 기능에 회귀 오류를 만들 수 있다.
권장 흐름은 ① 기능 정의 → ② 영향도 분석 → ③ 제한된 구현 → ④ 자동 테스트 → ⑤ 오류 요약 → ⑥ 별도 디버깅 작업 → ⑦ 회귀 테스트다. 새로운 오류를 해결할 때는 재현 절차, 기대 결과, 실제 결과, 최초 실패 시점, 변경 이력과 관련 로그만 전달한다. 수정 후에는 오류가 발생한 경로뿐 아니라 인접 기능의 테스트도 실행한다.
여기서 ‘분리’는 개발자나 AI가 서로 말하지 않아야 한다는 뜻이 아니다. 목표와 작업 컨텍스트를 구분하고 결과를 검증 가능한 형태로 주고받자는 뜻이다. 단순 버그라면 같은 세션에서 해결해도 되며, 로그가 크거나 반복 실패가 발생할 때 분리 효과가 커진다.
6. 로그를 통째로 넣지 말고 증거를 추출하라
수천 줄의 서버 로그나 빌드 출력을 그대로 붙이는 일은 대개 비효율적이다. 같은 경고가 반복되고, 정상 로그가 실패 메시지를 압도하며, 토큰을 소비한다. 로그를 숨기라는 뜻은 아니다. 원본은 파일로 보존하고 AI에는 분석에 필요한 증거만 전달하자는 것이다.
예를 들어 빌드 실패라면 사용 명령, 종료 코드, 최초 핵심 오류 1~3개, 해당 오류 전후의 제한된 로그, 관련 파일 경로, 실행 환경 버전만 전달한다. 실행 오류라면 요청 ID와 타임스탬프 기준으로 실패 요청을 추적하고, 전체 스택 트레이스는 필요한 범위만 선택한다. 비밀번호·토큰·개인정보는 반드시 마스킹한다.
CI나 스크립트에서 성공 여부와 검사 결과를 구조화해 반환하면 AI가 장황한 로그 대신 ‘어떤 검사가 왜 실패했는가’에 집중할 수 있다. 다만 원인이 불명확할 때는 더 넓은 로그나 전체 스택이 반드시 필요할 수 있다. 토큰 절약을 이유로 증거를 지나치게 잘라내는 것도 위험하다.
7. 토큰과 비용을 줄이는 실전 작업 방식
7-1. 수정 전 영향도 분석을 별도 단계로 둔다
첫 요청은 ‘바로 코드 수정’이 아니라 ‘요구사항에 영향을 받는 파일, 호출 관계, 공통화 가능 영역, 위험도, 테스트 범위를 찾아 계획만 제시하라’로 시작한다. 분석 결과에 따라 작게 변경할 수 있는지, 선행 리팩터링이 필요한지 판단한다. 분석이 부실하면 작은 기능도 전체 코드 재작성으로 번질 수 있다.
7-2. 관련 파일만 읽고 변경한다
프로젝트 전체를 매번 읽는 대신 먼저 디렉터리 구조, 검색 결과, 인터페이스와 테스트를 확인한다. 그런 뒤 수정 파일의 실제 내용을 확인한다. 사용하지 않는 소스, 외부 패키지, 대형 JSON, 자동 생성 결과, 빌드 산출물은 기본 컨텍스트에서 제외한다. 무턱대고 전체 파일을 줄이는 대신 문제에 필요한 파일을 단계적으로 탐색하는 것이 핵심이다.
7-3. 한 번에 한 가지 검증 가능한 변경을 한다
‘테마 변경 + 로그인 개선 + 결제 추가 + 전체 화면 디자인 수정’과 같은 묶음 요청은 원인 분석과 복구를 어렵게 만든다. 우선 토큰 정의, 그다음 공통 UI, 대표 화면 1개, 나머지 화면 순으로 확장한다. 각 단계에 완료 기준을 둬서 실패 시 되돌릴 수 있게 한다. 변경 전 Git 커밋과 브랜치를 준비하는 것도 중요하다.
7-4. 비싼 추론은 설계와 고난도 오류에 집중한다
모든 작업에 가장 강력한 모델과 최대 추론량이 필요한 것은 아니다. 파일 이름 정리·반복 패턴 변환·간단한 테스트 추가에는 더 가벼운 모델이나 자동화 스크립트가 적합할 수 있다. 보안·아키텍처·동시성·데이터 손실 위험이 있는 작업은 검토를 강화한다. 모델별 토큰 단가뿐 아니라 실패 후 재작업 비용까지 함께 계산해야 한다.
7-5. 재사용 가능한 검증 명령을 준비한다
사람이 매번 화면을 눌러 확인하는 대신 타입 검사, 정적 분석, 단위 테스트, UI 스냅샷, API 계약 테스트, 주요 사용자 흐름의 E2E 테스트를 단계적으로 구축한다. 물론 테스트도 유지비가 있으므로 핵심 사용 흐름부터 우선한다. 자동 검증이 정확할수록 AI에게 매번 긴 설명을 반복할 필요가 줄어든다.
8. AI에게 이렇게 요청하면 좋다
예시 A: 구현 전 영향도 조사
목표: 앱에 네온/화이트/크게 보기 테마를 추가한다.
지금은 코드를 수정하지 말고 다음만 수행하라.
1. 하드코딩된 색상·글꼴·크기 사용처를 검색한다.
2. 공통 디자인 토큰 적용 가능 영역을 구분한다.
3. 변경 대상 파일과 연관 기능, 위험도를 제시한다.
4. 가장 작은 변경 단위의 구현 순서를 작성한다.
5. 각 단계의 테스트·롤백 방법을 설명한다.
추정과 확인된 사실을 구분하고 불필요한 파일은 읽지 마라.예시 B: 제한된 범위로 구현
승인된 1단계만 구현하라.
범위: 테마 토큰 정의 및 테마 상태 저장 인터페이스.
기존 화면의 시각 디자인은 변경하지 마라.
작업 후 변경 파일 목록, 테스트 명령, 결과,
알려진 미완료 항목을 요약하라.
테스트 실패 시 무관한 파일을 수정하지 마라.예시 C: 별도 디버깅 작업
기능 추가는 중단하고 아래 재현 오류만 진단하라.
기대 결과 / 실제 결과 / 재현 단계 / 최근 변경사항:
[내용 입력]
첨부 로그의 첫 실패 원인과 관련 스택만 분석하라.
원인 가설을 우선순위로 제시하고 확인 명령을 제안하라.
근거가 확인되기 전에는 대규모 리팩터링을 하지 마라.9. 프로젝트 시작 시 점검할 체크리스트
- 핵심 기능 외에 테마·권한·유료화·언어·접근성 등 변경 가능성 큰 정책을 정리했는가?
- 화면과 API, 데이터 저장소 사이에 책임 경계가 있는가?
- 색상·글꼴·간격·상태 표시를 공통 토큰과 컴포넌트로 관리하는가?
- 환경변수와 비밀정보가 소스코드 및 로그에서 분리되어 있는가?
- 아키텍처와 의사결정을 저장소에 문서로 남겼는가?
- AI가 수정할 수 있는 범위와 수정하지 말아야 할 범위를 지정했는가?
- 기능 개발과 오류 재현·진단의 작업 컨텍스트를 구분하는가?
- 전체 로그가 아니라 실패를 설명하는 최소 충분한 증거를 제공하는가?
- 코드 변경 전에 영향도와 검증 범위를 분석하는가?
- 자동 테스트·빌드·롤백 방법이 준비되어 있는가?
- 장기 세션의 결정 사항을 요약하고 낡은 컨텍스트를 정리하는가?
- 토큰 비용뿐 아니라 실패율·재작업 시간·검증 비용까지 관찰하는가?
10. 결론: 바이브 코딩의 속도는 프롬프트가 아니라 구조에서 오래 유지된다
바이브 코딩은 처음 몇 개 화면을 만드는 데 놀라울 정도로 빠르다. 하지만 서비스가 커질수록 빠르게 만드는 능력보다 안전하게 바꾸는 능력이 중요해진다. 테마 버튼 하나가 전체 화면 수정으로 번진 사례는 AI의 한계라기보다 공통 정책과 변경 경계를 초기에 설계하지 않았을 때 나타나는 전형적인 비용이다.
초기 요구사항 정리, 영향도 분석, 공통 구조, 하네스 설계, 컨텍스트 관리, 개발·디버깅 분리, 필요한 로그만 전달하는 습관은 모두 같은 목적을 가진다. AI가 더 적은 정보로 정확하게 일하고, 사람이 결과를 검증할 수 있도록 만드는 것. 개발 속도를 높이는 가장 좋은 방법은 AI에게 더 많은 코드를 한꺼번에 쓰게 하는 것이 아니라, 변경이 작고 명확하며 테스트 가능한 프로젝트를 만들어 주는 것이다.
참고 자료
OpenAI — Harness engineering: leveraging Codex in an agent-first world (2026)
OpenAI Developers — Codex as a platform (2026)
Anthropic — Effective context engineering for AI agents
Anthropic — Context engineering: memory, compaction, and tool clearing (2026)