코드 컨벤션을 템플릿과 하네스로 연결한다

바이브 코딩으로 코드를 만드는 속도는 빨라졌다. 하지만 생성된 코드가 매번 다른 구조를 따른다면, 변경 사항을 이해하고 유지보수하는 비용도 함께 커진다.

같은 기능이어도 어떤 작업에서는 Controller에 처리가 들어가고, 다른 작업에서는 Service에 들어갈 수 있다. 테스트 위치와 응답 처리 방식까지 달라지면, 코드를 생성한 뒤 구조부터 다시 확인해야 한다.

나는 코드 컨벤션을 템플릿으로 구조화하고, 하네스가 그 템플릿을 선택해 사용하도록 구성했다. AI가 구현하더라도 일관된 규칙 안에서 코드가 만들어지고, 변경이 어느 위치에서 어떤 책임으로 이루어졌는지 파악할 수 있게 하려는 것이다.

컨벤션을 실제 구현 형태로 만든다

문서에 규칙을 적는 것만으로는 구현 결과가 일정해지지 않는다. 같은 설명도 AI가 다르게 해석할 수 있기 때문이다.

그래서 반복해서 사용하는 구조를 코드 템플릿으로 만들었다. 템플릿에는 파일 배치, 계층별 책임, 메서드 형태와 테스트 구성을 함께 담는다.

구성	담는 내용
코드 컨벤션	일관되게 지킬 작성·구현 규칙
템플릿	규칙을 적용한 구체적인 코드 구조
하네스	작업에 필요한 템플릿과 실행 절차를 선택하는 기준
테스트와 E2E	생성된 결과가 요구사항과 계약을 충족하는지 확인하는 수단

컨벤션이 기준이라면, 템플릿은 그 기준의 구현 예제이고 하네스는 이를 실제 작업에 적용하는 연결 장치다.

구조가 일정하면 요구사항을 받았을 때 어느 부분을 확인해야 하는지 예상할 수 있다.

내 구조에서는 HTTP 요청과 응답 처리는 Controller, 비즈니스 로직의 조합은 Facade 계층, 데이터 처리는 Service의 책임을 기준으로 살펴본다. 테스트 역시 대응하는 책임에 맞춰 배치한다.

이렇게 책임과 위치가 유지되면 변경 내용을 볼 때 확인 범위를 좁힐 수 있다.

구조만으로 모든 변경의 정확성을 보장할 수는 없다. 다만 코드를 어디서부터 읽어야 하는지, 변경이 정해진 책임 안에서 이루어졌는지 판단하기 쉬워진다.

반복되는 API 개발은 구현부터 테스트와 Controller API E2E까지 하나의 원셋으로 구성한다.

작업 요청
   ↓
저장소 규칙과 기존 패턴 확인
   ↓
적용할 원셋 선택
   ↓
구현·테스트·E2E 템플릿 복사
   ↓
도메인명·필드·계약 등 차이 반영
   ↓
실행과 검증

Implementer가 매번 구조를 새로 설계하기보다, 준비된 파일을 복사하고 이번 작업에서 달라지는 부분만 채우도록 하는 방식이다.

대상 저장소의 규칙과 기존 패턴이 우선한다. 삭제 방식이나 없는 자원의 응답처럼 프로젝트마다 달라지는 정책은 확장 지점으로 남긴다.

이 방식은 AI가 반복해서 수행하던 탐색과 설계, 코드 재생성을 줄이려는 목적도 있다. 파일 복사와 치환으로 해결할 수 있는 작업을 매번 새로 생성할 필요는 없다.

하네스의 원칙은 요구사항과 저장소 규칙, 필요한 검증을 충족하는 방법 중 토큰 소비가 가장 적은 실행 경로를 선택하는 것이다.

간단한 수정은 관련 파일만 확인한다. 원셋 작업은 필요한 템플릿을 재사용한다. 추가 판단이나 별도 에이전트는 필요한 경우에만 사용한다.

대신 토큰 절약을 이유로 테스트를 생략하거나 기대 결과를 낮추지는 않는다. 줄이려는 것은 반복 판단과 불필요한 생성 비용이며, 결과를 확인하는 책임은 유지한다.

작업하면서 발견한 개선점을 모두 자동으로 규칙에 반영하지는 않는다. 특정 상황에서 필요했던 수정이 다른 작업에도 적합한 기준이라는 보장은 없기 때문이다.

AI는 반복 문제와 개선안을 제안하고, 나는 적용 범위와 근거를 확인한 뒤 공통 컨벤션과 템플릿에 반영한다.

이 구조를 통해 바이브 코딩의 속도를 활용하면서도, 내가 이해하고 관리할 수 있는 코드의 형태를 유지하려고 한다. 코드를 빠르게 생성하는 것과 함께, 생성된 변경을 빠르게 읽고 검토할 수 있는 구조를 만드는 것이 목표다.