#Backend

AI가 규칙을 "알잘딱" 지키는 백엔드 레포 만들기

Summary

AI에게 '부탁'하지 말고 '테스트'로 강제하세요: 채널톡의 AI 친화적 백엔드 구축기

말 안 듣는 AI 코딩 도구를 길들이는 비결은 자연어 프롬프트가 아닌 결정론적 아키텍처 테스트에 있습니다.

AI 코딩 도구가 확산되는 시대에 개발자의 역할은 AI가 안전하게 작업할 수 있는 '운동장'을 만드는 것으로 진화하고 있습니다. 본 아티클은 채널톡이 Go 언어 기반의 백엔드 환경에서 어떻게 DDD와 커스텀 정적 분석을 결합하여 AI의 실수 가능성을 차단했는지 상세히 설명합니다. 문서를 넘어 코드로 규칙을 정의함으로써 AI와 협업하는 차세대 개발 프로세스의 실질적인 이정표를 제시합니다.

01자연어 컨텍스트 파일(CLAUDE.md)의 낮은 규칙 준수율과 높은 추론 비용 문제 지적
02Go AST를 활용해 10만 라인 규모의 커스텀 아키텍처 테스트 슈트 구축
03도메인 간의 무분별한 참조를 막는 alias.go 진입점 패턴과 Saga 패턴의 도입
04Package Stutter 제거 등 AI의 예측 가능성을 극대화하는 대칭적 코드 구조 설계
05아키텍처 테스트 피드백 루프를 통해 Claude Code가 자율적으로 리팩토링을 완수한 사례 공유

RECOMMENDATION

AI 코딩 도구를 도입했음에도 코드 리뷰 단계에서 아키텍처 위반 사항이 빈번하게 발견되는 팀에게 강력히 추천합니다. 프롬프트 엔지니어링에 시간을 쏟기보다, 시스템적으로 위반을 차단하는 정적 분석 도구와 테스트 환경을 먼저 구축하십시오.

The Problem

Claude Code나 Cursor 같은 AI 도구를 사용할 때, CLAUDE.md와 같은 자연어 컨텍스트 파일에 명시된 아키텍처 규칙을 AI가 무시하거나 잘못 해석하는 현상이 발생했습니다. 특히 대규모 레포지토리에서 God Object와 복잡한 의존성 구조로 인해 AI가 일관된 패턴의 코드를 생성하지 못하고 영향 범위를 파악하는 데 한계를 보였습니다.

The Solution

자연어 지침 대신 Go AST(Abstract Syntax Tree)를 활용한 약 10만 라인의 커스텀 아키텍처 테스트 코드를 작성하여 프로젝트 규칙을 코드로 강제했습니다. DDD 기반의 리팩토링을 통해 도메인 간 경계를 명확히 하고, 모든 계층에 동일한 대칭적 코드 패턴과 alias.go를 통한 진입점 제한을 도입하여 결정론적 코드 제어 환경을 구축했습니다.

The Result

아키텍처 테스트 도입 후 모듈 간 결합도가 90% 감소하고 테스트용 Mock 개수가 70% 줄어드는 정량적 개선을 이루었습니다. 결과적으로 AI가 아키텍처 규칙을 위반할 경우 테스트 에러 메시지를 통해 스스로 코드를 수정할 수 있게 되어, 사람의 개입 없이도 AI가 자율적으로 대규모 리팩토링을 수행할 수 있는 수준에 도달했습니다.

Trade-off

기성 라이브러리가 지원하지 않는 세밀한 규칙을 위해 약 10만 라인에 달하는 방대한 양의 커스텀 분석 코드를 직접 유지보수해야 하는 비용이 발생합니다. 또한, 강력한 아키텍처 규칙을 적용하기 위해 기존의 복잡한 구조를 모두 리팩토링해야 하는 선행 작업이 필수적입니다.

Key Concepts

Concept · 01

결정론적 코드 제어

자연어 지침과 달리 테스트, 린터, 타입 시스템 등을 통해 규칙 위반 시 반드시 실패하도록 만드는 강제성 있는 제어 방식입니다.

CI/CD 파이프라인에서 아키텍처 규칙 위반 시 빌드를 차단하여 100% 감지를 보장합니다.
AI가 에러 메시지를 보고 스스로 코드를 수정할 수 있는 명확한 피드백 루프를 제공합니다.

Concept · 02

Package Stutter

Go 언어에서 패키지 이름과 해당 패키지 내의 타입/함수 이름이 중복되어 나타나는 현상을 의미합니다.

repo.AppRepo 대신 repo.App으로 네이밍을 단순화하여 AI의 명칭 예측 정확도를 높였습니다.
커스텀 네이밍 규칙을 통해 패키지명 중복 사용을 자동으로 검출하고 방지합니다.

Concept · 03

Saga 패턴

여러 마이크로서비스 또는 도메인 간의 데이터 일관성을 유지하기 위해 각 단계별 트랜잭션을 관리하고 실패 시 보상 트랜잭션을 실행하는 패턴입니다.

기존 God Object가 수행하던 도메인 간 조율 작업을 독립적인 Saga 레이어로 분리했습니다.
각 도메인의 내부 구현이 아닌 Public Service(alias)만 의존하도록 강제하여 결합도를 낮췄습니다.

Continue reading · same source

More from 채널 톡

View all posts from 채널 톡

AI가 규칙을 "알잘딱" 지키는 백엔드 레포 만들기

Summary