Vibe 코드 정리 작업을 재사용 가능한 자산으로: AGENTS.md를 통한 엔지니어링 스타일 적용

배경: Cloud Cards 스토리

샌프란시스코 Ruby 컨퍼런스 홍보를 위해 ‘Cloud Cards’ 앱을 Ruby on Rails, Avo, RubyLLM 등으로 빠르게 개발했습니다. 배포 중 문제가 발생하여 동료 Vladimir Dementyev에게 검토를 요청했고, 그는 앱 전체를 처음부터 다시 작성하여 우아하고 명료한 코드를 선보였습니다.

문제점: 전문가 스타일의 부재

Vladimir와 같은 세계적인 엔지니어가 항상 ‘vibe 코딩’된 앱을 재작성해줄 수는 없습니다. 이에 우리는 원본과 Vladimir가 리팩토링한 두 가지 앱 버전을 활용하여, 모델이 Vladimir의 코딩 스타일을 모방하도록 학습시키는 방법을 모색했습니다.

3단계 AGENTS.md 생성 프로세스

1. 스타일 문서 생성: 사고 모델로 두 앱 버전의 차이점과 Vladimir의 스타일을 분석하여 style.md를 작성했습니다.

2. AGENTS.md 요약: style.md를 핵심 스타일 및 구조 결정을 규칙과 패턴으로 인코딩한 AGENTS.md로 요약했습니다.

3. 기술적 일관성 검토: 사고 모델과 수동 검토를 통해 AGENTS.md의 품질을 향상시켰습니다.

AGENTS.md의 효과와 핵심 규칙

새 프로젝트에 AGENTS.md를 적용한 결과, Vladimir는 코드를 버리지 않고 ‘작업할 수 있는 코드’라고 평가했습니다. 이는 코드 품질 개선의 중요한 진전을 의미합니다. AGENTS.md에는 다음과 같은 실용적인 규칙들이 포함되어 있습니다:

• 도메인 언어 사용: 일반 기술 용어 대신 자연어 사용 (예: User 대신 Participant).

• 상태 관리에 enum 활용: Ruby enum을 통해 predicate, bang 메서드, 스코프를 자동으로 얻습니다.

• Fat Model 방지: 모델은 데이터, 관계, 유효성 검사에 집중하고, 복잡한 로직은 네임스페이스 클래스(Cloud::CardGenerator 등)로 분리합니다. 15줄 이상 메서드, 외부 API 호출 등은 추출 대상입니다.

• Anyway::Config를 통한 타입-세이프 설정: Rails credentials나 ENV 대신 Anyway::Config를 사용하여 타입-세이프하고, 싱글톤 접근 및 환경별 설정이 용이한 설정을 관리합니다.

• 선호/지양 패턴: Form Object, Query Object, ViewComponent를 선호하고, Service Object, Result Object는 지양합니다.