웹·모바일·API를 위한 단일 AI 생성 코드베이스

단일 AI 생성 코드베이스가 의미하는 바

“하나의 코드베이스”가 거의 항상 모든 곳에서 동일한 UI가 실행된다는 의미는 아닙니다. 실무에서는 보통 하나의 저장소와 하나의 공유 규칙 집합을 뜻하며, 별도의 전달 표면(웹 앱, 모바일 앱, API)이 동일한 근본 비즈니스 결정을 공유합니다.

공유 로직 vs. 공유 UI

유용한 사고 모델은 절대적으로 달라져서는 안 되는 부분을 공유하는 것입니다:

• 도메인 규칙: 계산, 적격성 검사, 가격 책정, 워크플로우, 불변식.
• 유스케이스: “create order”, “cancel subscription”, “issue refund” 등.
• 데이터 계약: 요청/응답 형태, 검증 규칙, 오류 코드.

반면 UI 계층 전체를 공유하지 않는 경우가 일반적입니다. 웹과 모바일은 네비게이션 패턴, 접근성 기대치, 성능 제약, 플랫폼 기능이 다릅니다. 일부 경우 UI 공유가 도움이 될 수 있지만, 그것이 바로 “하나의 코드베이스”의 정의는 아닙니다.

AI가 바꾸는 것(그리고 바꾸지 않는 것)

AI로 크게 속도를 낼 수 있는 부분:

• 프로젝트 골격 생성(폴더, 빌드 스크립트, 기본 컴포넌트)
• CRUD 엔드포인트와 클라이언트 생성
• 예시에서 테스트와 픽스처 생성

그러나 AI가 자동으로 일관된 아키텍처를 만들어주지는 않습니다. 경계가 명확하지 않으면 로직 중복, 관심사 혼합(UI가 DB 코드를 직접 호출), 여러 곳에 거의 비슷한 검증이 생기는 경향이 있습니다. 레버리지는 구조를 먼저 정의한 다음 AI로 반복 작업을 채우는 데서 나옵니다.

달성해야 할 결과

AI 보조 단일 코드베이스는 다음을 제공할 때 성공적입니다:

• 일관성: 웹, 모바일, API가 동일한 규칙을 강제함.
• 속도: 새로운 기능을 한 번 구현하면 모든 표면에 노출됨.
• 유지보수성: 변경이 국소화되고, 리뷰되고, 테스트되고, 예측 가능하게 릴리스됨.

웹, 모바일, API 전달을 위한 목표와 제약

단일 코드베이스는 무엇을 달성해야 하는지—그리고 무엇을 표준화하지 말아야 하는지 명확할 때만 작동합니다. 웹, 모바일, API는 같은 비즈니스 규칙을 공유하더라도 서로 다른 사용자층과 사용 패턴을 가집니다.

누굴 대상으로 하는가(그리고 어떻게)

대부분 제품에는 최소 세 가지 “출입구”가 있습니다:

• 웹 앱 사용자(고객, 관리자, 서포트팀): 빠른 네비게이션, 접근성, 쉬운 업데이트를 기대합니다.
• 모바일 사용자: 네이티브 같은 상호작용, 간헐적 연결 지원, 효율적인 배터리/네트워크 사용을 기대합니다.
• 서드파티 통합(파트너, 내부 시스템, 자동화 도구): 안정적인 API, 명확한 계약, 예측 가능한 오류 처리를 필요로 합니다.

목표는 행동의 일관성(규칙, 권한, 계산)이지, 동일한 경험이 아닙니다.

비목표: 동일한 UX를 강제하지 말 것

흔한 실패 모드는 “단일 코드베이스”를 “모든 곳에서 하나의 UI”로 취급하는 것입니다. 이 경우 웹 같은 모바일 앱이나 모바일 같은 웹 앱이 생기며 둘 다 사용자에게 불편합니다.

대신 다음을 목표로 하세요:

• 공유 도메인 로직과 검증
• 공유 데이터 모델 및 API 계약
• 플랫폼별 표현 및 상호작용 설계

초기에 설계해야 할 주요 제약

오프라인 모드: 모바일은 종종 네트워크 없이도 읽기(때로는 쓰기)를 지원해야 합니다. 이는 로컬 저장소, 동기화 전략, 충돌 처리, 명확한 “진실의 원천” 규칙을 의미합니다.

성능: 웹은 번들 크기와 인터랙티브까지의 시간을 신경 쓰며; 모바일은 시작 시간과 네트워크 효율을, API는 지연과 처리량을 신경 씁니다. 공유 코드는 모든 클라이언트에 불필요한 모듈을 배송하지 않도록 해야 합니다.

보안 및 규정 준수: 인증, 인가, 감사 기록, 암호화, 데이터 보존은 모든 표면에서 일관되어야 합니다. 규제가 있는 영역에서 운영한다면 로깅, 동의, 최소 권한 접근 같은 요구사항을 처음부터 반영하세요.

레퍼런스 아키텍처: 레이어와 책임

단일 코드베이스는 명확한 레이어와 엄격한 책임 분리가 있을 때 가장 잘 작동합니다. 이런 구조는 AI 생성 코드를 검토, 테스트, 교체하기 쉽게 만듭니다.

상위 흐름

다음은 대부분 팀이 수렴하는 기본 형태입니다:

Clients (Web / Mobile / Partners)
          ↓
     API Layer
          ↓
    Domain Layer
          ↓
 Data Sources (DB / Cache / External APIs)

핵심 아이디어: 사용자 인터페이스와 전송 세부 사항은 가장자리에 있고, 비즈니스 규칙은 중앙에 위치합니다.

무엇을 공유하는가

“공유 가능한 핵심”은 어디에서든 동일하게 동작해야 하는 모든 것입니다:

• 도메인(비즈니스 로직): 가격 규칙, 적격성 검사, 주문 상태 전환 등.
• 검증: 입력 규칙과 오류 메시지를 일관된 오류 코드로 매핑.
• 네트워킹 + 스키마: API 요청/응답 타입, 직렬화, 계약 테스트.

AI가 새로운 기능을 생성할 때 최상의 결과는: 도메인 규칙을 한 번 업데이트하면 모든 클라이언트가 자동으로 혜택을 받는 것입니다.

무엇을 다르게 유지해야 하는가

일부 코드는 공유 추상화로 강제하기에 비용이 크거나 위험합니다:

• UI 컴포넌트: 웹 디자인 시스템 vs 네이티브 컨트롤.
• 내비게이션과 사용자 흐름: 브라우저 라우팅 vs 모바일 스택.
• 디바이스 기능: 푸시 알림, 생체인증, 카메라, 오프라인 저장.

실용적인 규칙: 사용자가 "볼 수 있는" 것이나 OS가 "깨뜨릴" 수 있는 것은 앱별로 유지하세요. 비즈니스 결정이라면 도메인에 두세요.

레이어별 책임

• API 레이어: 인증, 속도 제한, HTTP/GraphQL을 도메인 커맨드로 매핑.
• 도메인 레이어: 순수 규칙과 유스케이스, 최소한의 의존성.
• 데이터 소스: 데이터베이스와 서드파티 서비스를 인터페이스 뒤에 두어 구현을 바꿔도 비즈니스 로직을 재작성하지 않도록 함.

공유 도메인 레이어(비즈니스 로직)

공유 도메인 레이어는 ‘지루한’ 것이 좋은 부분이어야 합니다: 예측 가능하고, 테스트 가능하며, 어디서나 재사용할 수 있는 부분. AI가 시스템 생성에 도움을 준다면 이 레이어가 프로젝트의 의미를 고정하는 곳입니다—그래서 웹 화면, 모바일 플로우, API 엔드포인트가 동일한 규칙을 반영합니다.

명사와 동사로 시작하세요

제품의 핵심 개념을 엔티티(시간에 따른 아이덴티티가 있는 것, 예: Account, Order, Subscription)와 값 객체(값으로 정의되는 것, 예: Money, EmailAddress, DateRange)로 정의하세요. 그런 다음 행동을 유스케이스(또는 애플리케이션 서비스)로 캡처하세요: “Create order”, “Cancel subscription”, “Change email”.

이 구조는 도메인을 비전문가가 이해하기 쉽게 만듭니다: 명사는 존재하는 것을 설명하고, 동사는 시스템이 하는 일을 설명합니다.

비즈니스 규칙을 UI에 무관하게 유지하세요

비즈니스 로직은 버튼 탭, 웹 폼 제출, API 요청 중 무엇에 의해 트리거되는지 알 필요가 없어야 합니다. 실무적으로는:

• 프레임워크 임포트 금지(도메인 코드에 웹 컨트롤러, 모바일 뷰, ORM 어노테이션 금지)
• UI 문자열 금지(오류 코드는 메시지 대신 키/코드 사용 권장)
• 네트워크 가정 금지(도메인이 “API를 호출”하면 안 되고 규칙을 표현해야 함)

AI가 코드를 생성할 때 이 분리가 쉽게 사라집니다—그럴 때는 리팩터 대상으로 삼으세요.

모든 곳에서 하나의 검증 규칙 집합

검증은 제품이 자주 흩어지는 지점입니다: 웹은 허용하지만 API가 거부하거나 모바일이 다르게 검증하는 경우. 검증을 도메인 레이어(또는 공유 검증 모듈)에 두어 모든 표면이 동일한 규칙을 강제하게 하세요.

예시:

• EmailAddress는 한 번만 포맷을 검증하고 웹/모바일/API에서 재사용
• Money는 음수 합계를 방지(값이 어디서 왔든 상관 없음)
• 유스케이스는 교차 필드 규칙을 강제(예: “종료일은 시작일 이후여야 함”)

이렇게 하면 API 레이어는 번역기가 되고, 웹/모바일은 프리젠터가 되며 도메인 레이어가 단일 진실의 원천으로 남습니다.

API 레이어: 다른 모든 것을 이끄는 계약

API 레이어는 시스템의 “공개 얼굴”이며, 단일 AI 생성 코드베이스에서는 다른 모든 것을 고정하는 부분이어야 합니다. 계약이 명확하면 웹 앱, 모바일 앱, 내부 서비스까지 같은 진실을 기준으로 생성 및 검증할 수 있습니다.

API 우선 계약에서 시작하세요

핸들러나 UI 와이어링을 생성하기 전에 계약을 정의하세요:

• 엔드포인트와 리소스: 일관된 명사(예: /users, /orders/{id}), 예측 가능한 필터링과 정렬
• 오류: 안정적인 오류 형식(code, message, details)과 문서화된 HTTP 상태 사용법
• 페이징: 하나의 접근법을 선택(진화에 유리한 커서 기반 추천)하고 응답 필드 표준화
• 버전 관리: 초기 결정(path /v1/... 또는 헤더 기반)과 사용 중단 규칙 문서화

하나의 스키마에서 타입과 클라이언트 생성

OpenAPI(또는 GraphQL SDL)를 정식 아티팩트로 사용하고 여기서부터 생성하세요:

• 서버 스텁(라우트, 검증 스캐폴딩)
• 웹/모바일용 타입화된 클라이언트
• 드리프트를 줄이는 공유 요청/응답 모델

AI 생성 코드가 빨라도 스키마가 있으면 정렬 상태를 유지할 수 있습니다.

미묘한 파손을 방지하는 일관성 규칙

몇 가지 비협상 규칙을 정하세요:

• 네이밍: snake_case 또는 camelCase 중 하나로 통일; JSON과 생성 타입 간 일치
• 상태 코드: 성공은 200/201/204, 검증은 400, 인증은 401/403, 충돌은 409
• 아이덴포턴시: 결제나 주문 생성 같은 리스크 작업에는 Idempotency-Key 요구 및 재시도 정책 정의

API 계약을 제품처럼 다루세요. 계약이 안정되면 다른 모든 것은 생성, 테스트, 배포하기 쉬워집니다.

웹 앱: 공유 로직 통합 vs. 결합 피하기

웹 앱은 공유 비즈니스 로직으로 큰 이점을 얻고, 그 로직이 UI와 뒤엉키면 큰 피해를 봅니다. 핵심은 공유 도메인 레이어를 “헤드리스” 엔진으로 취급하는 것입니다: 규칙, 검증, 워크플로를 알지만 컴포넌트, 라우트, 브라우저 API는 모릅니다.

렌더링 선택: SSR vs CSR(그리고 중요한 이유)

**SSR(서버 사이드 렌더링)**을 사용하면 공유 코드는 서버에서 안전하게 실행되어야 합니다: 직접적인 window, document, 브라우저 저장소 호출 금지. 이는 좋은 강제 장치입니다: 브라우저 의존 동작은 얇은 웹 어댑터 레이어에 둡니다.

**CSR(클라이언트 사이드 렌더링)**에서는 더 자유롭지만 동일한 규율이 필요합니다. CSR 전용 프로젝트는 모든 것이 브라우저에서 실행되므로 도메인 모듈에 UI 코드를 실수로 임포트하는 일이 잦고, 이후 SSR이나 엣지 렌더링을 추가할 때 문제가 됩니다.

실용적 규칙: 공유 모듈은 결정적이고 환경 무관적이어야 합니다; 쿠키, localStorage, URL을 건드리는 것은 웹 앱 레이어에 둡니다.

상태 경계: 도메인 상태 vs UI 상태

공유 로직은 평범한 객체와 순수 함수로 도메인 상태(예: 주문 총액, 적격성, 유도된 플래그)를 노출할 수 있습니다. 웹 앱은 UI 상태(로딩 스피너, 폼 포커스, 낙관적 애니메이션, 모달 가시성)를 소유해야 합니다.

이렇게 하면 React/Vue 상태 관리 라이브러리를 바꿔도 비즈니스 규칙을 다시 쓰지 않아도 됩니다.

분리해야 할 웹 전용 관심사

웹 레이어는 다음을 처리해야 합니다:

• 접근성(시맨틱 마크업, 키보드 네비게이션, ARIA)
• 라우팅(URL 구조, 딥 링크, 서버 리다이렉트)
• 브라우저 저장소(쿠키/세션, localStorage, 캐싱)

웹 앱을 사용자 상호작용을 도메인 커맨드로 번역하고, 도메인 결과를 접근 가능한 화면으로 번역하는 어댑터로 생각하세요.

모바일 앱: 네이티브 기능을 살린 공유 로직

모바일 앱은 공유 도메인 레이어에서 가장 큰 혜택을 얻습니다: 가격, 적격성, 검증, 워크플로 규칙이 웹 및 API와 동일하게 동작해야 합니다. 모바일 UI는 그 공유 로직을 감싸는 “셸”이 되어 터치, 간헐적 연결, 디바이스 기능에 최적화됩니다.

설계해야 할 플랫폼 패턴

공유 비즈니스 로직이 있더라도 모바일에는 거의 1:1로 웹과 매핑되지 않는 패턴이 있습니다:

• 내비게이션: 화면, 탭, 모달을 앱 레이어에서 모델링하고 도메인 결정(예: “체크아웃 전에 이메일 확인 필요”)은 공유 코드에 둡니다.
• 백그라운드 작업: 동기화, 업로드, 새로고침을 명시적 작업으로 처리하며 시간 제한과 재개 가능성을 고려합니다.
• 푸시 알림: 알림 페이로드를 앱 레이어에서 파싱한 뒤 공유 로직에 핸드오프하여 다음 행동 결정.
• 딥 링크: 앱 레이어에서 라우트 처리하되 권한 검증과 필요한 데이터 페칭은 공유 코드로 수행.

오프라인 우선: 캐시, 동기화, 충돌 전략

실제 모바일 사용을 예상한다면 오프라인을 전제로 하세요:

• 읽기 모델을 로컬에 캐시(key-value 또는 SQLite)하고 명확한 신선도 정책 적용
• 쓰기는 의도/이벤트로 큐잉(예: “create order draft”)하고 온라인 시 동기화
• 충돌 규칙을 사전에 정의(최종 쓰기 우선, 서버 권위 병합, 사용자 해결)
• 재시도는 백오프와 아이덴포턴시 키로 구현하여 API가 중복 수신을 안전하게 처리하도록 함

모바일 전용 고려사항

• 앱 크기: 공유 레이어를 모듈화해 앱이 필요한 것만 포함하도록 유지
• 배터리/데이터: 네트워크 호출을 묶고 과도한 폴링을 피함
• 권한: 필요한 순간에만 요청(카메라, 위치, 연락처)하고 권한 검사는 도메인 코드가 아닌 앱 레이어에 두어 플랫폼별 정책을 유연하게 함

모든 표면의 데이터 모델, 인증, 권한

웹, 모바일, API가 각자 데이터 형태와 보안 규칙을 발명하면 단일 코드베이스는 곧 실패합니다. 모델, 인증, 인가를 제품 결정으로 취급하고 한 번만 인코딩하세요.

데이터 모델의 단일 진실의 원천

모델이 위치한 한 곳을 정하고 다른 모든 것은 거기서 파생되게 하세요. 일반 옵션:

• 스키마 우선: OpenAPI/JSON Schema 같은 스키마 파일에 엔티티와 검증 규칙을 정의하고 타입을 생성
• 공유 모듈: 모델 타입과 검증기를 공유 패키지(보통 ‘도메인’ 패키지)에 두어 모든 앱이 임포트
• 하이브리드: 외부 계약은 스키마 파일, 내부 도메인 규칙은 공유 모듈

도구가 핵심이 아니라 일관성이 핵심입니다. OrderStatus가 한 클라이언트에서 다섯 값이고 다른 곳에서 여섯 값이면 AI가 기꺼이 컴파일시키고 버그를 배포할 것입니다.

인증: 세션, 토큰, 안전한 저장

인증은 사용자에게 일관되게 느껴지되 표면별 구현은 달라야 합니다:

• 웹은 쿠키 기반 세션을 선호하는 경우가 많음(좋은 CSRF 보호, 브라우저에 단순함)
• 모바일과 타사 클라이언트는 액세스/리프레시 토큰이 필요함

단일 흐름을 설계하세요: 로그인 → 단기 액세스 → 필요 시 리프레시 → 서버 측 상태 무효화로 로그아웃. 모바일에서는 비밀을 Keychain/Keystore에 저장하고, 웹에서는 httpOnly 쿠키를 선호하세요.

권한 부여: 중앙 규칙, API에서 강제

권한은 한 번 정의하고 어디서나 적용하세요. 이상적으로 비즈니스 규칙 근처에 정의한 뒤 모든 곳에서 사용합니다.

• 도메인 레이어에서 검사 중앙화(예: canApproveInvoice(user, invoice))
• 보안 확보를 위해 API에서 강제
• UI는 동작 숨기기/비활성화 목적으로만 반영

이렇게 하면 “모바일에서는 되는데 웹에서는 안 됨” 같은 드리프트를 방지하고 AI 코드 생성에 명확하고 테스트 가능한 계약을 제공합니다.

빌드, 릴리스, 배포 전략

코드베이스를 통일 상태로 유지하려면 빌드와 릴리스가 예측 가능해야 합니다. 목표는 팀이 API, 웹 앱, 모바일 앱을 독립적으로 배포할 수 있게 하되 로직을 포크하거나 환경별 특수 처리를 하지 않도록 하는 것입니다.

모노레포 vs 멀티레포

단일 코드베이스에는 모노레포(하나의 레포, 다중 패키지/앱)가 잘 맞습니다. 공유 도메인 로직, API 계약, UI 클라이언트가 함께 진화하기 쉽고 원자적 변경(한 PR로 계약과 모든 소비자 업데이트)을 할 수 있으며 리팩터가 단순합니다.

멀티레포도 통합할 수는 있지만 조정 비용이 듭니다: 공유 패키지 버저닝, 아티팩트 퍼블리시, 파괴적 변경 동기화. 조직 경계, 보안 규칙, 스케일 때문에 멀티레포를 선택하는 경우를 제외하고는 모노레포가 더 실용적입니다.

빌드 타깃과 아티팩트

각 표면을 공유 패키지를 소비하는 별도 빌드 타깃으로 취급하세요:

• API 서비스 아티팩트: 컨테이너 이미지 또는 서버리스 번들
• 웹 번들: 정적 자산 + 서버 런타임(SSR인 경우)
• 모바일 빌드: Android(AAB/APK), iOS(IPA) — 네이티브 파이프라인에서 공유 로직을 의존성으로 가져감

빌드 출력은 명시적이고 재현 가능하게(락파일, 고정 툴체인, 결정적 빌드) 유지하세요.

CI/CD 파이프라인과 환경 분리

전형적인 파이프라인: lint → typecheck → 단위 테스트 → 계약 테스트 → 빌드 → 보안 스캔 → 배포.

구성은 코드와 분리하세요: 환경 변수와 시크릿은 CI/CD와 시크릿 매니저에 두고 레포에는 두지 마세요. 환경별 오버레이(dev/stage/prod)를 사용해 동일한 아티팩트를 다시 빌드하지 않고 환경 간 승격할 수 있게 하세요—특히 API와 웹 런타임에 유용합니다.

공유 코드에 대한 테스트와 품질 게이트

웹, 모바일, API가 같은 코드베이스에서 배포될 때 테스트는 단순한 체크리스트가 아니라 작은 변경이 세 제품을 동시에 깨뜨리는 것을 막는 메커니즘이 됩니다. 목표는 문제를 가장 저렴하게 고칠 수 있는 곳에서 감지하고 사용자에게 도달하기 전에 위험한 변경을 차단하는 것입니다.

실용적인 테스트 피라미드

공유 도메인(비즈니스 로직)부터 시작하세요. 이 부분은 가장 많이 재사용되고 느린 인프라 없이 테스트하기 쉽습니다.

• 단위 테스트(도메인 레이어): 가격, 적격성, 권한 결정, 상태 전환, 엣지 케이스 검증. 빠르게 실행되며 테스트 스위트의 대부분이 되어야 합니다.
• 통합 테스트(API 레이어): 직렬화, 검증, 인증, 데이터 접근과 함께 API가 엔드투엔드로 동작함을 증명. 모든 코너 케이스 대신 핵심 흐름에 집중하세요.
• UI 테스트(클라이언트별): 로그인, 체크아웃, 폼 제출 같은 주요 여정을 확인하는 소수의 가치 있는 체크. 느리므로 ‘스모크 알람’으로 취급하세요.

이 구조는 대부분의 신뢰를 공유 로직에서 확보하면서 레이어 간의 연결 문제를 잡아줍니다.

클라이언트와 API 정렬을 유지하는 계약 테스트

모노레포에서도 API가 컴파일되지만 사용자 경험을 깨뜨리는 방식으로 변경되는 건 쉽습니다. 계약 테스트는 조용한 드리프트를 방지합니다.

• API↔클라이언트 계약: 요청/응답 형태, 오류 포맷, 상태 코드를 고정. API가 새로운 필드를 필수로 추가하거나 enum을 바꾸면 계약 테스트가 병합 전에 실패합니다.
• 게이트로서의 스키마: OpenAPI/GraphQL 스키마를 공개하면 스키마 변경을 리뷰 가능한 아티팩트로 다루세요. 파괴적 변경은 명시적 승인과 마이그레이션 계획 필요.

릴리스를 보호하는 품질 게이트

테스트도 중요하지만 테스트를 둘러싼 규칙도 중요합니다.

• 풀 리퀘스트 게이트: 도메인 단위 테스트 + 통합 테스트 통과, 린트/포맷, 도메인 레이어의 최소 커버리지 요구
• 기능 플래그: 완성되지 않은 동작은 플래그 뒤에 숨겨 환경별/사용자 그룹별 활성화
• 단계적 롤아웃: 내부 사용자 → 소수의 프로덕션 트래픽 → 전체 사용자
• 롤백 계획: 롤백을 1차적 결과로 다룸—버전된 릴리스, 롤백 가능한 DB 마이그레이션(또는 안전한 순방향 마이그레이션), 명확한 “중단 기준” 준비

이런 게이트가 있으면 AI 보조 변경도 빈번하면서도 취약하지 않게 될 수 있습니다.

아키텍처를 잃지 않고 AI 사용하기

AI는 단일 코드베이스를 가속화할 수 있지만 항상 빠른 주니어 엔지니어처럼 다뤄야 합니다: 초안 작성에 능하지만 리뷰가 필요합니다. 목표는 AI로 속도를 내되 아키텍처, 계약, 장기 일관성에 대해 사람 책임을 유지하는 것입니다.

AI가 가장 도움이 되고 위험이 낮은 곳

AI는 기계적으로 작성하던 초안들을 생성하는 데 유용합니다:

• 프로젝트 스캐폴드(폴더, 보일러플레이트 모듈, 기능 골격)
• 기존 계약 기반의 API 문서 및 예시
• 테스트 스위트(도메인 규칙 단위 테스트, 엔드포인트 계약 테스트)
• 마이그레이션 및 시드 데이터 스크립트
• 계획을 정의한 후의 반복적 리팩터(필드명 변경, 모듈 분리)

규칙: AI가 생성한 코드는 읽거나 테스트로 검증하기 쉬워야 하며, 비즈니스 의미를 은밀히 바꾸어서는 안 됩니다.

아키텍처를 보호하는 가드레일

AI 출력은 명시적 규칙으로 제한되어야 합니다:

• 코딩 표준: 린터/포매터, 네이밍 규칙, “UI에서 직접 DB 접근 금지” 같은 스타일 제약
• 아키텍처 규칙: 의존성 경계(도메인이 API/웹/모바일을 임포트할 수 없음), 빌드 체크나 도구로 강제
• PR 체크리스트: “계약 변경? OpenAPI + 클라이언트 타입 + 테스트 업데이트 필요.” “새 도메인 규칙? 도메인 테스트 추가.”

AI가 경계를 위반하는 지름길을 제안하면, 컴파일되더라도 허용하지 마세요.

거버넌스: AI 작업을 감사 가능하게 만들기

위험은 나쁜 코드뿐 아니라 추적되지 않는 결정입니다. 감사 로그를 유지하세요:

• 주요 프롬프트와 응답을 작업 항목(티켓 ID, PR 링크)과 함께 저장
• 계약 변경, 인증 모델 전환, 새로운 도메인 개념에 대한 아키텍처 결정(ADR)을 기록
• API 변경은 명시적이어야 함: 버전 관리, 문서화, 계약 테스트 포함

AI는 재현 가능할 때 가장 가치가 있습니다: 팀이 왜 생성했는지 보고 검증하고 요구사항 변경 시 안전하게 재생성할 수 있어야 합니다.

도구 참고: 경계를 존중하는 AI

시스템 수준에서 AI 보조 개발을 도입할 때 가장 중요한 기능은 원시 생성 속도가 아니라 산출물이 계약과 레이어링에 맞춰 유지되는 능력입니다.

예: Koder.ai는 채팅 인터페이스로 웹, 서버, 모바일 애플리케이션을 돕는 비브 코딩 플랫폼입니다—실제 내보낼 수 있는 소스 코드를 생성하면서도 워크플로를 지원합니다. 이 기사의 워크플로에 유용한 이유: API 계약과 도메인 규칙을 정의한 후 React 기반 웹, Go+Postgres 백엔드, Flutter 모바일 앱을 빠르게 반복하면서도 아키텍처 경계를 검토, 테스트, 강제할 수 있습니다. 플래닝 모드, 스냅샷, 롤백 같은 기능은 단일 코드베이스에서의 “생성 → 검증 → 승격” 릴리스 규율과 잘 맞습니다.

단일 코드베이스를 사용하지 말아야 할 때(대안)

단일 코드베이스는 중복을 줄일 수 있지만 기본적으로 항상 최선은 아닙니다. 공유 코드가 어색한 UX를 강요하거나 릴리스를 늦추거나 플랫폼 차이를 숨기기 시작하면 아키텍처 협상에 더 많은 시간을 쓰게 됩니다.

별도 코드베이스가 더 나은 경우

별도 코드베이스(또는 최소한 별도 UI 레이어)가 정당화되는 경우:

• UI가 제품의 핵심인 경우. 웹과 모바일이 근본적으로 다른 상호작용 모델(제스처, 오프라인 우선 화면, 카메라 중심 흐름, 복잡한 애니메이션)을 필요로 하면 공유 UI는 타협이 됩니다.
• 엄격한 플랫폼 제약이 있는 경우. 앱스토어 심사 규칙, 디바이스 권한, 백그라운드 실행 제한, 접근성 요구가 플랫폼별 구현을 요구할 수 있습니다.
• 릴리스 주기가 다른 경우. 모바일이 월 단위로 배포되고 웹이 일 단위로 배포된다면 강하게 결합된 모노레포는 모든 변경을 조정 이벤트로 만들 수 있습니다.

흔한 실패 모드

• UI 과도 공유: “하나의 UI로 모두 제어”하면 최저공통분모 경험이 됨.
• 누수하는 추상화: “공유” 모듈이 여전히 웹/모바일 세부사항(라우팅, 저장, 인증 토큰)을 노출해 소비자가 취약해짐.
• 버전 드리프트: 팀이 속도를 위해 공유 코드를 복붙하고 수정은 한 곳에만 반영됨.

결정 체크리스트(그리고 대신 할 일)

단일 코드베이스를 고수하기 전에 다음을 물어보세요:

• 도메인 로직을 네이티브 UX를 유지하면서 깔끔하게 공유할 수 있는가?
• 플랫폼 팀들이 도구, 릴리스 타이밍, 실험에서 자율성을 가져야 하는가?
• API가 충분히 안정적이어서 클라이언트가 독립적으로 진화할 수 있는가?

경고 신호가 보이면 실용적 대안은 공유 도메인 + API 계약을 유지하되 웹과 모바일은 별도 앱으로 두는 것입니다. 공유 코드는 비즈니스 규칙과 검증에만 집중시키고 각 클라이언트는 UX와 플랫폼 통합을 소유하게 하세요.

원하는 경우 경로 선택을 도와드릴 수 있습니다—/pricing에서 옵션을 비교하거나 /blog에서 관련 아키텍처 패턴을 둘러보세요.