1. AI 코딩의 한계와 코드베이스의 역할
AI는 영화 ‘메멘토’의 주인공처럼 매 세션마다 기억이 초기화된 상태로 깨어납니다. AI는 지난 세션에서 발생한 오류나 잘못된 메서드 생성을 기억하지 못하며, 오직 현재 컨텍스트에 로드된 규칙만을 신뢰합니다. 반면, 코드베이스는 과거의 모든 나쁜 습관, 리팩토링되지 않은 모델, 임시방편으로 작성된 SQL 쿼리 등을 고스란히 기억하고 있습니다. AI는 이러한 레거시 패턴을 현재의 정답으로 오해하고 복제하기 때문에, 개발자는 AI가 신뢰할 수 있는 패턴을 구별해주는 ‘컨벤션(Conventions)’이라는 필터를 반드시 설정해야 합니다.
2. 핵심적인 Rails ‘문신(Tattoos)’: 모델 설계 원칙
AI에게 가장 먼저 주입해야 할 규칙은 비즈니스 로직의 위치입니다. 모델은 단순한 데이터베이스 테이블의 투영이 아니라, 도메인 로직의 소유자여야 합니다. - 비즈니스 로직의 집중: 모든 도메인 로직은 컨트롤러나 뷰가 아닌 모델 내부에 위치해야 합니다. 이를 통해 로직이 파편화되는 것을 방지합니다. - 캡슐화와 메시지 전달: 객체의 내부 구현(연관 관계 등)에 직접 접근하여 쿼리를 날리는 대신, 객체에게 필요한 동작을 요청(Ask)하는 메서드를 호출해야 합니다. - 도메인 객체 전달: 메서드 시그니처는 ID와 같은 원시 값 대신 도메인 객체를 직접 전달받도록 설계하여 코드의 가독성과 타입 안정성을 높입니다.
3. 지루하지만 강력한 컨트롤러 컨벤션
컨트롤러가 ‘흥미로워지는’ 순간, 애플리케이션의 유지보수는 어려워집니다. AI가 일관된 코드를 작성하게 하려면 컨트롤러를 최대한 단순하게 유지해야 합니다.
- Thin Controller: 컨트롤러는 비즈니스 로직을 직접 처리하지 않고 모델에 위임합니다. 파라미터 처리, 응답 형식 관리, 흐름 제어에만 집중합니다.
- RESTful 리소스 준수: 표준 7가지 액션을 따르고 리소스당 하나의 컨트롤러를 유지합니다. 커스텀 액션을 남발하면 AI는 어떤 패턴을 따를지 혼란을 겪게 됩니다.
- 강제적인 권한 부여(Authorization): 모든 액션에서 authorize 호출을 의무화합니다. 이는 보안을 강화할 뿐만 아니라 AI가 권한 체크를 누락하는 실수를 방지합니다.
4. 뷰의 복잡성 제어와 ViewComponent
뷰 템플릿(ERB)에 로직이 섞이기 시작하면 테스트와 유지보수가 불가능해집니다. AI와의 협업에서는 특히 뷰 로직의 격리가 중요합니다. - Hotwire 및 Turbo 활용: 복잡한 JSON API와 수동 DOM 조작(JavaScript) 대신 Turbo 프레임을 사용하여 서버 지향적인 동적 업데이트를 구현합니다. - ViewComponent 도입: Rails의 기본 헬퍼(Helper)는 전역 네임스페이스 오염과 테스트의 어려움을 야기합니다. 대신 독립적이고 테스트 가능한 ViewComponent를 사용하여 프레젠테이션 로직을 캡슐화합니다. - Dumb Views: ERB 템플릿은 컴포넌트를 호출하는 ‘접착제’ 역할만 수행해야 하며, 복잡한 조건문이나 데이터 가공 로직을 포함해서는 안 됩니다.
5. 기술 부채의 격리와 관리
AI가 코드를 작성할 때 기술 부채는 필연적으로 발생합니다. 하지만 ViewComponent와 같이 명확하게 명명되고 격리된 구조 내에 부채가 쌓인다면, 이는 관리 가능한 수준이 됩니다. 개발자는 나중에 AI 에이전트에게 “이 컴포넌트들을 정리해줘”라고 요청할 수 있으며, AI는 필요한 모든 컨텍스트가 한곳에 모여 있는 컴포넌트 구조 덕분에 효율적으로 리팩토링을 수행할 수 있습니다. 결국 잘 정의된 컨벤션은 AI가 작성한 코드의 품질을 보장하고, 개발자가 전체 시스템의 아키텍처를 통제할 수 있게 돕는 핵심 도구입니다.