API와 모노레포 이해하기

비개발자를 위한 쉬운 설명 - API가 무엇이고, 왜 약속이 필요하며, 모노레포가 AI 개발에 왜 유리한가

1. API란 무엇인가?

레스토랑에 비유하면

API를 이해하는 가장 쉬운 방법은 레스토랑에 비유하는 것입니다.

손님(앱/웹사이트): 서비스를 이용하려는 사용자
웨이터(API): 손님의 요청을 주방에 전달하고, 결과를 가져다주는 중개자
주방(서버/데이터베이스): 실제로 데이터를 저장하고 처리하는 곳

API의 정의

**API (Application Programming Interface)**는 두 시스템이 서로 대화하는 방법입니다.

실생활 예시	API 역할
카카오톡에서 "프로필 보기" 클릭	서버에서 프로필 정보를 가져오는 API 호출
배달앱에서 "주문하기" 클릭	주문 정보를 서버에 저장하는 API 호출
인스타그램 피드 스크롤	새 게시물 목록을 가져오는 API 호출

bkamp에서의 API 예시

bkamp 서비스에서 "쇼케이스 목록 보기"를 누르면:

1. 사용자가 앱 목록 페이지에 접속
2. 프론트엔드가 API 호출: GET /showcases/v1/showcases
3. 백엔드가 데이터베이스에서 앱 목록 조회
4. 백엔드가 JSON 형태로 응답 반환
5. 프론트엔드가 받은 데이터로 화면 구성

2. API 개발에 왜 '약속'이 필요한가?

소통의 혼란을 방지하기 위해

만약 레스토랑에서 메뉴판이 없다면 어떨까요?

손님: "뭔가 맛있는 거 주세요"
웨이터: "네? 무슨 말씀이신지..."
주방: "뭘 만들라는 거야?"

API 개발도 마찬가지입니다. 약속(규약)이 없으면 혼란이 생깁니다.

실제 혼란의 예시

❌ 약속이 없을 때

프론트엔드 개발자 A:  "사용자 정보 어떻게 가져와요?"
백엔드 개발자 B:     "GET /user 하면 돼요"
프론트엔드 개발자 C:  "저는 GET /users/{id} 쓰던데요?"
백엔드 개발자 D:     "아 그건 v2에서 바뀌었어요"

✅ 약속이 있을 때

문서: "사용자 정보 조회는 GET /users/v1/users/{id}를 사용합니다"
모든 개발자: "OK, 문서대로 하면 되겠네요"

bkamp API 규약의 핵심 약속들

1. URL 네이밍 규칙

모든 API 경로는 동일한 패턴을 따릅니다:

/{서비스}/{버전}/{리소스}

예시:
GET  /showcases/v1/showcases      → 앱 목록 조회
GET  /showcases/v1/showcases/123  → 앱 상세 조회
POST /showcases/v1/showcases      → 앱 생성

2. 응답 형식 통일

모든 API 응답은 같은 구조를 사용합니다:

json
{
  "success": true,
  "data": { ... 실제 데이터 ... },
  "error": null,
  "meta": { ... 추가 정보 (페이지네이션 등) ... }
}

3. 에러 코드 체계

에러도 일관된 규칙을 따릅니다:

{서비스}_{도메인}_{에러유형}

예시:
- AUTH_TOKEN_EXPIRED     → 인증 토큰 만료
- SHOWCASE_NOT_FOUND     → 앱을 찾을 수 없음
- RECIPE_STEP_REQUIRED   → 레시피 스텝 필요

4. 필드명 규칙

위치	규칙	예시
JSON (프론트엔드 ↔ API)	camelCase	`userId`, `createdAt`
Python 코드 (백엔드)	snake_case	`user_id`, `created_at`
DB 컬럼	snake_case	`user_id`, `created_at`

약속이 주는 효과

┌────────────────────────────────────────────────────────────────┐
│                     API 규약의 효과                              │
├────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ✅ 예측 가능성     → 새 API도 기존 패턴으로 쉽게 예측           │
│  ✅ 생산성 향상     → "이건 어떻게 하죠?" 질문 감소              │
│  ✅ 유지보수 용이   → 누가 작성해도 일관된 코드                  │
│  ✅ 협업 효율      → 프론트/백엔드 간 소통 비용 감소             │
│  ✅ 온보딩 단축    → 신규 개발자도 규칙만 알면 빠르게 적응        │
│                                                                 │
└────────────────────────────────────────────────────────────────┘

3. 모노레포란 무엇인가?

코드 저장 방식의 두 가지 선택

소프트웨어 개발에서 코드를 저장하는 방식은 크게 두 가지입니다:

멀티레포 (Multi-repo)

모노레포 (Mono-repo)

회사에 비유하면

방식	비유	특징
멀티레포	여러 건물에 나뉜 회사	팀별로 독립적, 소통 비용 높음
모노레포	한 건물에 모인 회사	빠른 소통, 공유 자원 활용

bkamp의 모노레포 구조

bkamp-portal/
├── frontend/                    # 프론트엔드 (Next.js)
│   ├── apps/
│   │   ├── portal/             # 메인 포털
│   │   └── admin/              # 관리자 페이지
│   └── packages/               # 공유 패키지
│
├── services/                    # 백엔드 (FastAPI)
│   ├── auth/                   # 인증 서비스
│   ├── user/                   # 사용자 서비스
│   ├── project/                # 쇼케이스 서비스
│   ├── recipe/                 # 레시피 서비스
│   └── ...
│
├── shared/                      # 백엔드 공통 모듈
│   ├── schemas/                # 공통 스키마 (API 규약!)
│   ├── errors/                 # 공통 에러 코드
│   └── utils/                  # 공통 유틸리티
│
├── infrastructure/              # 인프라 설정
└── docs/                        # 문서

4. Claude Code와 모노레포의 시너지

AI가 코드를 이해하는 방식

Claude Code와 같은 AI 개발 도구는 코드를 읽고 이해한 후 작업을 수행합니다.

┌────────────────────────────────────────────────────────────────┐
│                  AI 개발 도구의 작업 흐름                         │
├────────────────────────────────────────────────────────────────┤
│                                                                 │
│   1. 코드 읽기 (Read)     → 기존 코드와 패턴 파악                │
│   2. 컨텍스트 이해        → 프로젝트 구조와 규칙 이해             │
│   3. 코드 작성 (Write)    → 기존 패턴에 맞춰 새 코드 생성         │
│   4. 일관성 유지          → 전체 프로젝트와 조화롭게 작성          │
│                                                                 │
└────────────────────────────────────────────────────────────────┘

모노레포가 AI 개발에 유리한 이유

이유 1: 전체 맥락을 한눈에

❌ 멀티레포 환경에서의 AI

"새 API를 만들어줘"
 → "음... 다른 API들은 어떻게 생겼죠? 다른 저장소를 봐야 하는데..."
 → 다른 서비스의 코드를 볼 수 없음
 → 패턴을 파악하기 어려움

✅ 모노레포 환경에서의 AI

"새 API를 만들어줘"
 → "기존 서비스들의 API 구조를 확인해볼게요"
 → GET /services/project/app/api/v1/endpoints/
 → "아하, 이런 패턴으로 작성하면 되겠군요!"
 → 일관된 코드 생성

이유 2: 공통 모듈 즉시 활용

python
# shared/ 폴더의 공통 모듈을 AI가 바로 찾아서 사용

# AI: "아, 이미 에러 코드가 정의되어 있네요. 그대로 사용할게요."
from shared.errors.codes import ErrorCode
from shared.schemas.response import CamelCaseModel

이유 3: 규약 문서와 코드가 함께

bkamp-portal/
├── docs/
│   └── 01-development/
│       └── 06_API_규약_설계서.md    ← AI가 규약 문서 참조
│
├── services/
│   └── project/
│       └── app/api/v1/              ← 규약을 따르는 실제 코드 참조

AI가 문서와 실제 코드를 동시에 참조할 수 있어, 규약에 맞는 코드를 정확하게 생성합니다.

실제 효과: bkamp 개발 사례

Before: 멀티레포 환경이었다면

1. "레시피 서비스 API 만들어줘"
2. AI: "다른 서비스 코드를 볼 수 없어서, 일반적인 방식으로 만들게요"
3. 결과: 기존 서비스와 다른 스타일의 API 생성
4. 개발자가 수동으로 일관성 맞춤 (시간 소모)

After: 모노레포 환경 (현재)

1. "레시피 서비스 API 만들어줘"
2. AI: "기존 project 서비스 구조를 참고할게요"
   - services/project/app/api/v1/endpoints/ 확인
   - shared/schemas/response.py 확인
   - docs/01-development/06_API_규약_설계서.md 확인
3. 결과: 기존 서비스와 동일한 스타일의 API 생성
4. 바로 사용 가능! (시간 절약)

핵심 시너지 정리

핵심 요약

개념	한 줄 설명	중요한 이유
API	시스템 간 대화 방법	프론트-백엔드 연결의 핵심
API 규약	API를 만드는 약속	일관성, 예측 가능성, 협업 효율
모노레포	하나의 저장소에 모든 코드	AI가 전체 맥락 파악 가능
시너지	규약 + 모노레포 + AI	빠르고 일관된 개발 가능

비개발자가 기억할 핵심

"API 규약이 있는 모노레포에서 AI 도구를 사용하면, AI가 기존 코드 패턴을 학습하여 일관된 코드를 자동으로 생성한다. 이것이 bkamp가 빠르게 개발될 수 있었던 핵심 비결이다."

문서 버전: 1.0 작성일: 2025-12-26 참고 문서: API 규약 설계서

API와 모노레포 이해하기

비개발자를 위한 쉬운 설명 - API가 무엇이고, 왜 약속이 필요하며, 모노레포가 AI 개발에 왜 유리한가

1. API란 무엇인가?

레스토랑에 비유하면

API를 이해하는 가장 쉬운 방법은 레스토랑에 비유하는 것입니다.

손님(앱/웹사이트): 서비스를 이용하려는 사용자
웨이터(API): 손님의 요청을 주방에 전달하고, 결과를 가져다주는 중개자
주방(서버/데이터베이스): 실제로 데이터를 저장하고 처리하는 곳

API의 정의

**API (Application Programming Interface)**는 두 시스템이 서로 대화하는 방법입니다.

실생활 예시	API 역할
카카오톡에서 "프로필 보기" 클릭	서버에서 프로필 정보를 가져오는 API 호출
배달앱에서 "주문하기" 클릭	주문 정보를 서버에 저장하는 API 호출
인스타그램 피드 스크롤	새 게시물 목록을 가져오는 API 호출

bkamp에서의 API 예시

bkamp 서비스에서 "쇼케이스 목록 보기"를 누르면:

1. 사용자가 앱 목록 페이지에 접속
2. 프론트엔드가 API 호출: GET /showcases/v1/showcases
3. 백엔드가 데이터베이스에서 앱 목록 조회
4. 백엔드가 JSON 형태로 응답 반환
5. 프론트엔드가 받은 데이터로 화면 구성

2. API 개발에 왜 '약속'이 필요한가?

소통의 혼란을 방지하기 위해

만약 레스토랑에서 메뉴판이 없다면 어떨까요?

손님: "뭔가 맛있는 거 주세요"
웨이터: "네? 무슨 말씀이신지..."
주방: "뭘 만들라는 거야?"

API 개발도 마찬가지입니다. 약속(규약)이 없으면 혼란이 생깁니다.

실제 혼란의 예시

❌ 약속이 없을 때

프론트엔드 개발자 A:  "사용자 정보 어떻게 가져와요?"
백엔드 개발자 B:     "GET /user 하면 돼요"
프론트엔드 개발자 C:  "저는 GET /users/{id} 쓰던데요?"
백엔드 개발자 D:     "아 그건 v2에서 바뀌었어요"

✅ 약속이 있을 때

문서: "사용자 정보 조회는 GET /users/v1/users/{id}를 사용합니다"
모든 개발자: "OK, 문서대로 하면 되겠네요"

bkamp API 규약의 핵심 약속들

1. URL 네이밍 규칙

모든 API 경로는 동일한 패턴을 따릅니다:

/{서비스}/{버전}/{리소스}

예시:
GET  /showcases/v1/showcases      → 앱 목록 조회
GET  /showcases/v1/showcases/123  → 앱 상세 조회
POST /showcases/v1/showcases      → 앱 생성

2. 응답 형식 통일

모든 API 응답은 같은 구조를 사용합니다:

json
{
  "success": true,
  "data": { ... 실제 데이터 ... },
  "error": null,
  "meta": { ... 추가 정보 (페이지네이션 등) ... }
}

3. 에러 코드 체계

에러도 일관된 규칙을 따릅니다:

{서비스}_{도메인}_{에러유형}

예시:
- AUTH_TOKEN_EXPIRED     → 인증 토큰 만료
- SHOWCASE_NOT_FOUND     → 앱을 찾을 수 없음
- RECIPE_STEP_REQUIRED   → 레시피 스텝 필요

4. 필드명 규칙

위치	규칙	예시
JSON (프론트엔드 ↔ API)	camelCase	`userId`, `createdAt`
Python 코드 (백엔드)	snake_case	`user_id`, `created_at`
DB 컬럼	snake_case	`user_id`, `created_at`

약속이 주는 효과

┌────────────────────────────────────────────────────────────────┐
│                     API 규약의 효과                              │
├────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ✅ 예측 가능성     → 새 API도 기존 패턴으로 쉽게 예측           │
│  ✅ 생산성 향상     → "이건 어떻게 하죠?" 질문 감소              │
│  ✅ 유지보수 용이   → 누가 작성해도 일관된 코드                  │
│  ✅ 협업 효율      → 프론트/백엔드 간 소통 비용 감소             │
│  ✅ 온보딩 단축    → 신규 개발자도 규칙만 알면 빠르게 적응        │
│                                                                 │
└────────────────────────────────────────────────────────────────┘

3. 모노레포란 무엇인가?

코드 저장 방식의 두 가지 선택

소프트웨어 개발에서 코드를 저장하는 방식은 크게 두 가지입니다:

멀티레포 (Multi-repo)

모노레포 (Mono-repo)

회사에 비유하면

방식	비유	특징
멀티레포	여러 건물에 나뉜 회사	팀별로 독립적, 소통 비용 높음
모노레포	한 건물에 모인 회사	빠른 소통, 공유 자원 활용

bkamp의 모노레포 구조

bkamp-portal/
├── frontend/                    # 프론트엔드 (Next.js)
│   ├── apps/
│   │   ├── portal/             # 메인 포털
│   │   └── admin/              # 관리자 페이지
│   └── packages/               # 공유 패키지
│
├── services/                    # 백엔드 (FastAPI)
│   ├── auth/                   # 인증 서비스
│   ├── user/                   # 사용자 서비스
│   ├── project/                # 쇼케이스 서비스
│   ├── recipe/                 # 레시피 서비스
│   └── ...
│
├── shared/                      # 백엔드 공통 모듈
│   ├── schemas/                # 공통 스키마 (API 규약!)
│   ├── errors/                 # 공통 에러 코드
│   └── utils/                  # 공통 유틸리티
│
├── infrastructure/              # 인프라 설정
└── docs/                        # 문서

4. Claude Code와 모노레포의 시너지

AI가 코드를 이해하는 방식

Claude Code와 같은 AI 개발 도구는 코드를 읽고 이해한 후 작업을 수행합니다.

┌────────────────────────────────────────────────────────────────┐
│                  AI 개발 도구의 작업 흐름                         │
├────────────────────────────────────────────────────────────────┤
│                                                                 │
│   1. 코드 읽기 (Read)     → 기존 코드와 패턴 파악                │
│   2. 컨텍스트 이해        → 프로젝트 구조와 규칙 이해             │
│   3. 코드 작성 (Write)    → 기존 패턴에 맞춰 새 코드 생성         │
│   4. 일관성 유지          → 전체 프로젝트와 조화롭게 작성          │
│                                                                 │
└────────────────────────────────────────────────────────────────┘

모노레포가 AI 개발에 유리한 이유

이유 1: 전체 맥락을 한눈에

❌ 멀티레포 환경에서의 AI

"새 API를 만들어줘"
 → "음... 다른 API들은 어떻게 생겼죠? 다른 저장소를 봐야 하는데..."
 → 다른 서비스의 코드를 볼 수 없음
 → 패턴을 파악하기 어려움

✅ 모노레포 환경에서의 AI

"새 API를 만들어줘"
 → "기존 서비스들의 API 구조를 확인해볼게요"
 → GET /services/project/app/api/v1/endpoints/
 → "아하, 이런 패턴으로 작성하면 되겠군요!"
 → 일관된 코드 생성

이유 2: 공통 모듈 즉시 활용

python
# shared/ 폴더의 공통 모듈을 AI가 바로 찾아서 사용

# AI: "아, 이미 에러 코드가 정의되어 있네요. 그대로 사용할게요."
from shared.errors.codes import ErrorCode
from shared.schemas.response import CamelCaseModel

이유 3: 규약 문서와 코드가 함께

bkamp-portal/
├── docs/
│   └── 01-development/
│       └── 06_API_규약_설계서.md    ← AI가 규약 문서 참조
│
├── services/
│   └── project/
│       └── app/api/v1/              ← 규약을 따르는 실제 코드 참조

AI가 문서와 실제 코드를 동시에 참조할 수 있어, 규약에 맞는 코드를 정확하게 생성합니다.

실제 효과: bkamp 개발 사례

Before: 멀티레포 환경이었다면

1. "레시피 서비스 API 만들어줘"
2. AI: "다른 서비스 코드를 볼 수 없어서, 일반적인 방식으로 만들게요"
3. 결과: 기존 서비스와 다른 스타일의 API 생성
4. 개발자가 수동으로 일관성 맞춤 (시간 소모)

After: 모노레포 환경 (현재)

1. "레시피 서비스 API 만들어줘"
2. AI: "기존 project 서비스 구조를 참고할게요"
   - services/project/app/api/v1/endpoints/ 확인
   - shared/schemas/response.py 확인
   - docs/01-development/06_API_규약_설계서.md 확인
3. 결과: 기존 서비스와 동일한 스타일의 API 생성
4. 바로 사용 가능! (시간 절약)

핵심 시너지 정리

핵심 요약

개념	한 줄 설명	중요한 이유
API	시스템 간 대화 방법	프론트-백엔드 연결의 핵심
API 규약	API를 만드는 약속	일관성, 예측 가능성, 협업 효율
모노레포	하나의 저장소에 모든 코드	AI가 전체 맥락 파악 가능
시너지	규약 + 모노레포 + AI	빠르고 일관된 개발 가능

비개발자가 기억할 핵심

"API 규약이 있는 모노레포에서 AI 도구를 사용하면, AI가 기존 코드 패턴을 학습하여 일관된 코드를 자동으로 생성한다. 이것이 bkamp가 빠르게 개발될 수 있었던 핵심 비결이다."

문서 버전: 1.0 작성일: 2025-12-26 참고 문서: API 규약 설계서

API와 모노레포 이해하기

비개발자를 위한 쉬운 설명 - API가 무엇이고, 왜 약속이 필요하며, 모노레포가 AI 개발에 왜 유리한가

1. API란 무엇인가?

레스토랑에 비유하면

API를 이해하는 가장 쉬운 방법은 레스토랑에 비유하는 것입니다.

손님(앱/웹사이트): 서비스를 이용하려는 사용자
웨이터(API): 손님의 요청을 주방에 전달하고, 결과를 가져다주는 중개자
주방(서버/데이터베이스): 실제로 데이터를 저장하고 처리하는 곳

API의 정의

**API (Application Programming Interface)**는 두 시스템이 서로 대화하는 방법입니다.

실생활 예시	API 역할
카카오톡에서 "프로필 보기" 클릭	서버에서 프로필 정보를 가져오는 API 호출
배달앱에서 "주문하기" 클릭	주문 정보를 서버에 저장하는 API 호출
인스타그램 피드 스크롤	새 게시물 목록을 가져오는 API 호출

bkamp에서의 API 예시

bkamp 서비스에서 "쇼케이스 목록 보기"를 누르면:

1. 사용자가 앱 목록 페이지에 접속
2. 프론트엔드가 API 호출: GET /showcases/v1/showcases
3. 백엔드가 데이터베이스에서 앱 목록 조회
4. 백엔드가 JSON 형태로 응답 반환
5. 프론트엔드가 받은 데이터로 화면 구성

2. API 개발에 왜 '약속'이 필요한가?

소통의 혼란을 방지하기 위해

만약 레스토랑에서 메뉴판이 없다면 어떨까요?

손님: "뭔가 맛있는 거 주세요"
웨이터: "네? 무슨 말씀이신지..."
주방: "뭘 만들라는 거야?"

API 개발도 마찬가지입니다. 약속(규약)이 없으면 혼란이 생깁니다.

실제 혼란의 예시

❌ 약속이 없을 때

프론트엔드 개발자 A:  "사용자 정보 어떻게 가져와요?"
백엔드 개발자 B:     "GET /user 하면 돼요"
프론트엔드 개발자 C:  "저는 GET /users/{id} 쓰던데요?"
백엔드 개발자 D:     "아 그건 v2에서 바뀌었어요"

✅ 약속이 있을 때

문서: "사용자 정보 조회는 GET /users/v1/users/{id}를 사용합니다"
모든 개발자: "OK, 문서대로 하면 되겠네요"

bkamp API 규약의 핵심 약속들

1. URL 네이밍 규칙

모든 API 경로는 동일한 패턴을 따릅니다:

/{서비스}/{버전}/{리소스}

예시:
GET  /showcases/v1/showcases      → 앱 목록 조회
GET  /showcases/v1/showcases/123  → 앱 상세 조회
POST /showcases/v1/showcases      → 앱 생성

2. 응답 형식 통일

모든 API 응답은 같은 구조를 사용합니다:

json
{
  "success": true,
  "data": { ... 실제 데이터 ... },
  "error": null,
  "meta": { ... 추가 정보 (페이지네이션 등) ... }
}

3. 에러 코드 체계

에러도 일관된 규칙을 따릅니다:

{서비스}_{도메인}_{에러유형}

예시:
- AUTH_TOKEN_EXPIRED     → 인증 토큰 만료
- SHOWCASE_NOT_FOUND     → 앱을 찾을 수 없음
- RECIPE_STEP_REQUIRED   → 레시피 스텝 필요

4. 필드명 규칙

위치	규칙	예시
JSON (프론트엔드 ↔ API)	camelCase	`userId`, `createdAt`
Python 코드 (백엔드)	snake_case	`user_id`, `created_at`
DB 컬럼	snake_case	`user_id`, `created_at`

약속이 주는 효과

┌────────────────────────────────────────────────────────────────┐
│                     API 규약의 효과                              │
├────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ✅ 예측 가능성     → 새 API도 기존 패턴으로 쉽게 예측           │
│  ✅ 생산성 향상     → "이건 어떻게 하죠?" 질문 감소              │
│  ✅ 유지보수 용이   → 누가 작성해도 일관된 코드                  │
│  ✅ 협업 효율      → 프론트/백엔드 간 소통 비용 감소             │
│  ✅ 온보딩 단축    → 신규 개발자도 규칙만 알면 빠르게 적응        │
│                                                                 │
└────────────────────────────────────────────────────────────────┘

3. 모노레포란 무엇인가?

코드 저장 방식의 두 가지 선택

소프트웨어 개발에서 코드를 저장하는 방식은 크게 두 가지입니다:

멀티레포 (Multi-repo)

모노레포 (Mono-repo)

회사에 비유하면

방식	비유	특징
멀티레포	여러 건물에 나뉜 회사	팀별로 독립적, 소통 비용 높음
모노레포	한 건물에 모인 회사	빠른 소통, 공유 자원 활용

bkamp의 모노레포 구조

bkamp-portal/
├── frontend/                    # 프론트엔드 (Next.js)
│   ├── apps/
│   │   ├── portal/             # 메인 포털
│   │   └── admin/              # 관리자 페이지
│   └── packages/               # 공유 패키지
│
├── services/                    # 백엔드 (FastAPI)
│   ├── auth/                   # 인증 서비스
│   ├── user/                   # 사용자 서비스
│   ├── project/                # 쇼케이스 서비스
│   ├── recipe/                 # 레시피 서비스
│   └── ...
│
├── shared/                      # 백엔드 공통 모듈
│   ├── schemas/                # 공통 스키마 (API 규약!)
│   ├── errors/                 # 공통 에러 코드
│   └── utils/                  # 공통 유틸리티
│
├── infrastructure/              # 인프라 설정
└── docs/                        # 문서

4. Claude Code와 모노레포의 시너지

AI가 코드를 이해하는 방식

Claude Code와 같은 AI 개발 도구는 코드를 읽고 이해한 후 작업을 수행합니다.

┌────────────────────────────────────────────────────────────────┐
│                  AI 개발 도구의 작업 흐름                         │
├────────────────────────────────────────────────────────────────┤
│                                                                 │
│   1. 코드 읽기 (Read)     → 기존 코드와 패턴 파악                │
│   2. 컨텍스트 이해        → 프로젝트 구조와 규칙 이해             │
│   3. 코드 작성 (Write)    → 기존 패턴에 맞춰 새 코드 생성         │
│   4. 일관성 유지          → 전체 프로젝트와 조화롭게 작성          │
│                                                                 │
└────────────────────────────────────────────────────────────────┘

모노레포가 AI 개발에 유리한 이유

이유 1: 전체 맥락을 한눈에

❌ 멀티레포 환경에서의 AI

"새 API를 만들어줘"
 → "음... 다른 API들은 어떻게 생겼죠? 다른 저장소를 봐야 하는데..."
 → 다른 서비스의 코드를 볼 수 없음
 → 패턴을 파악하기 어려움

✅ 모노레포 환경에서의 AI

"새 API를 만들어줘"
 → "기존 서비스들의 API 구조를 확인해볼게요"
 → GET /services/project/app/api/v1/endpoints/
 → "아하, 이런 패턴으로 작성하면 되겠군요!"
 → 일관된 코드 생성

이유 2: 공통 모듈 즉시 활용

python
# shared/ 폴더의 공통 모듈을 AI가 바로 찾아서 사용

# AI: "아, 이미 에러 코드가 정의되어 있네요. 그대로 사용할게요."
from shared.errors.codes import ErrorCode
from shared.schemas.response import CamelCaseModel

이유 3: 규약 문서와 코드가 함께

bkamp-portal/
├── docs/
│   └── 01-development/
│       └── 06_API_규약_설계서.md    ← AI가 규약 문서 참조
│
├── services/
│   └── project/
│       └── app/api/v1/              ← 규약을 따르는 실제 코드 참조

AI가 문서와 실제 코드를 동시에 참조할 수 있어, 규약에 맞는 코드를 정확하게 생성합니다.

실제 효과: bkamp 개발 사례

Before: 멀티레포 환경이었다면

1. "레시피 서비스 API 만들어줘"
2. AI: "다른 서비스 코드를 볼 수 없어서, 일반적인 방식으로 만들게요"
3. 결과: 기존 서비스와 다른 스타일의 API 생성
4. 개발자가 수동으로 일관성 맞춤 (시간 소모)

After: 모노레포 환경 (현재)

1. "레시피 서비스 API 만들어줘"
2. AI: "기존 project 서비스 구조를 참고할게요"
   - services/project/app/api/v1/endpoints/ 확인
   - shared/schemas/response.py 확인
   - docs/01-development/06_API_규약_설계서.md 확인
3. 결과: 기존 서비스와 동일한 스타일의 API 생성
4. 바로 사용 가능! (시간 절약)

핵심 시너지 정리

핵심 요약

개념	한 줄 설명	중요한 이유
API	시스템 간 대화 방법	프론트-백엔드 연결의 핵심
API 규약	API를 만드는 약속	일관성, 예측 가능성, 협업 효율
모노레포	하나의 저장소에 모든 코드	AI가 전체 맥락 파악 가능
시너지	규약 + 모노레포 + AI	빠르고 일관된 개발 가능

비개발자가 기억할 핵심

"API 규약이 있는 모노레포에서 AI 도구를 사용하면, AI가 기존 코드 패턴을 학습하여 일관된 코드를 자동으로 생성한다. 이것이 bkamp가 빠르게 개발될 수 있었던 핵심 비결이다."

문서 버전: 1.0 작성일: 2025-12-26 참고 문서: API 규약 설계서

API와 모노레포 이해하기

비개발자를 위한 쉬운 설명 - API가 무엇이고, 왜 약속이 필요하며, 모노레포가 AI 개발에 왜 유리한가

1. API란 무엇인가?

레스토랑에 비유하면

API를 이해하는 가장 쉬운 방법은 레스토랑에 비유하는 것입니다.

손님(앱/웹사이트): 서비스를 이용하려는 사용자
웨이터(API): 손님의 요청을 주방에 전달하고, 결과를 가져다주는 중개자
주방(서버/데이터베이스): 실제로 데이터를 저장하고 처리하는 곳

API의 정의

**API (Application Programming Interface)**는 두 시스템이 서로 대화하는 방법입니다.

실생활 예시	API 역할
카카오톡에서 "프로필 보기" 클릭	서버에서 프로필 정보를 가져오는 API 호출
배달앱에서 "주문하기" 클릭	주문 정보를 서버에 저장하는 API 호출
인스타그램 피드 스크롤	새 게시물 목록을 가져오는 API 호출

bkamp에서의 API 예시

bkamp 서비스에서 "쇼케이스 목록 보기"를 누르면:

1. 사용자가 앱 목록 페이지에 접속
2. 프론트엔드가 API 호출: GET /showcases/v1/showcases
3. 백엔드가 데이터베이스에서 앱 목록 조회
4. 백엔드가 JSON 형태로 응답 반환
5. 프론트엔드가 받은 데이터로 화면 구성

2. API 개발에 왜 '약속'이 필요한가?

소통의 혼란을 방지하기 위해

만약 레스토랑에서 메뉴판이 없다면 어떨까요?

손님: "뭔가 맛있는 거 주세요"
웨이터: "네? 무슨 말씀이신지..."
주방: "뭘 만들라는 거야?"

API 개발도 마찬가지입니다. 약속(규약)이 없으면 혼란이 생깁니다.

실제 혼란의 예시

❌ 약속이 없을 때

프론트엔드 개발자 A:  "사용자 정보 어떻게 가져와요?"
백엔드 개발자 B:     "GET /user 하면 돼요"
프론트엔드 개발자 C:  "저는 GET /users/{id} 쓰던데요?"
백엔드 개발자 D:     "아 그건 v2에서 바뀌었어요"

✅ 약속이 있을 때

문서: "사용자 정보 조회는 GET /users/v1/users/{id}를 사용합니다"
모든 개발자: "OK, 문서대로 하면 되겠네요"

bkamp API 규약의 핵심 약속들

1. URL 네이밍 규칙

모든 API 경로는 동일한 패턴을 따릅니다:

/{서비스}/{버전}/{리소스}

예시:
GET  /showcases/v1/showcases      → 앱 목록 조회
GET  /showcases/v1/showcases/123  → 앱 상세 조회
POST /showcases/v1/showcases      → 앱 생성

2. 응답 형식 통일

모든 API 응답은 같은 구조를 사용합니다:

json
{
  "success": true,
  "data": { ... 실제 데이터 ... },
  "error": null,
  "meta": { ... 추가 정보 (페이지네이션 등) ... }
}

3. 에러 코드 체계

에러도 일관된 규칙을 따릅니다:

{서비스}_{도메인}_{에러유형}

예시:
- AUTH_TOKEN_EXPIRED     → 인증 토큰 만료
- SHOWCASE_NOT_FOUND     → 앱을 찾을 수 없음
- RECIPE_STEP_REQUIRED   → 레시피 스텝 필요

4. 필드명 규칙

위치	규칙	예시
JSON (프론트엔드 ↔ API)	camelCase	`userId`, `createdAt`
Python 코드 (백엔드)	snake_case	`user_id`, `created_at`
DB 컬럼	snake_case	`user_id`, `created_at`

약속이 주는 효과

┌────────────────────────────────────────────────────────────────┐
│                     API 규약의 효과                              │
├────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ✅ 예측 가능성     → 새 API도 기존 패턴으로 쉽게 예측           │
│  ✅ 생산성 향상     → "이건 어떻게 하죠?" 질문 감소              │
│  ✅ 유지보수 용이   → 누가 작성해도 일관된 코드                  │
│  ✅ 협업 효율      → 프론트/백엔드 간 소통 비용 감소             │
│  ✅ 온보딩 단축    → 신규 개발자도 규칙만 알면 빠르게 적응        │
│                                                                 │
└────────────────────────────────────────────────────────────────┘

3. 모노레포란 무엇인가?

코드 저장 방식의 두 가지 선택

소프트웨어 개발에서 코드를 저장하는 방식은 크게 두 가지입니다:

멀티레포 (Multi-repo)

모노레포 (Mono-repo)

회사에 비유하면

방식	비유	특징
멀티레포	여러 건물에 나뉜 회사	팀별로 독립적, 소통 비용 높음
모노레포	한 건물에 모인 회사	빠른 소통, 공유 자원 활용

bkamp의 모노레포 구조

bkamp-portal/
├── frontend/                    # 프론트엔드 (Next.js)
│   ├── apps/
│   │   ├── portal/             # 메인 포털
│   │   └── admin/              # 관리자 페이지
│   └── packages/               # 공유 패키지
│
├── services/                    # 백엔드 (FastAPI)
│   ├── auth/                   # 인증 서비스
│   ├── user/                   # 사용자 서비스
│   ├── project/                # 쇼케이스 서비스
│   ├── recipe/                 # 레시피 서비스
│   └── ...
│
├── shared/                      # 백엔드 공통 모듈
│   ├── schemas/                # 공통 스키마 (API 규약!)
│   ├── errors/                 # 공통 에러 코드
│   └── utils/                  # 공통 유틸리티
│
├── infrastructure/              # 인프라 설정
└── docs/                        # 문서

4. Claude Code와 모노레포의 시너지

AI가 코드를 이해하는 방식

Claude Code와 같은 AI 개발 도구는 코드를 읽고 이해한 후 작업을 수행합니다.

┌────────────────────────────────────────────────────────────────┐
│                  AI 개발 도구의 작업 흐름                         │
├────────────────────────────────────────────────────────────────┤
│                                                                 │
│   1. 코드 읽기 (Read)     → 기존 코드와 패턴 파악                │
│   2. 컨텍스트 이해        → 프로젝트 구조와 규칙 이해             │
│   3. 코드 작성 (Write)    → 기존 패턴에 맞춰 새 코드 생성         │
│   4. 일관성 유지          → 전체 프로젝트와 조화롭게 작성          │
│                                                                 │
└────────────────────────────────────────────────────────────────┘

모노레포가 AI 개발에 유리한 이유

이유 1: 전체 맥락을 한눈에

❌ 멀티레포 환경에서의 AI

"새 API를 만들어줘"
 → "음... 다른 API들은 어떻게 생겼죠? 다른 저장소를 봐야 하는데..."
 → 다른 서비스의 코드를 볼 수 없음
 → 패턴을 파악하기 어려움

✅ 모노레포 환경에서의 AI

"새 API를 만들어줘"
 → "기존 서비스들의 API 구조를 확인해볼게요"
 → GET /services/project/app/api/v1/endpoints/
 → "아하, 이런 패턴으로 작성하면 되겠군요!"
 → 일관된 코드 생성

이유 2: 공통 모듈 즉시 활용

python
# shared/ 폴더의 공통 모듈을 AI가 바로 찾아서 사용

# AI: "아, 이미 에러 코드가 정의되어 있네요. 그대로 사용할게요."
from shared.errors.codes import ErrorCode
from shared.schemas.response import CamelCaseModel

이유 3: 규약 문서와 코드가 함께

bkamp-portal/
├── docs/
│   └── 01-development/
│       └── 06_API_규약_설계서.md    ← AI가 규약 문서 참조
│
├── services/
│   └── project/
│       └── app/api/v1/              ← 규약을 따르는 실제 코드 참조

AI가 문서와 실제 코드를 동시에 참조할 수 있어, 규약에 맞는 코드를 정확하게 생성합니다.

실제 효과: bkamp 개발 사례

Before: 멀티레포 환경이었다면

1. "레시피 서비스 API 만들어줘"
2. AI: "다른 서비스 코드를 볼 수 없어서, 일반적인 방식으로 만들게요"
3. 결과: 기존 서비스와 다른 스타일의 API 생성
4. 개발자가 수동으로 일관성 맞춤 (시간 소모)

After: 모노레포 환경 (현재)

1. "레시피 서비스 API 만들어줘"
2. AI: "기존 project 서비스 구조를 참고할게요"
   - services/project/app/api/v1/endpoints/ 확인
   - shared/schemas/response.py 확인
   - docs/01-development/06_API_규약_설계서.md 확인
3. 결과: 기존 서비스와 동일한 스타일의 API 생성
4. 바로 사용 가능! (시간 절약)

핵심 시너지 정리

핵심 요약

개념	한 줄 설명	중요한 이유
API	시스템 간 대화 방법	프론트-백엔드 연결의 핵심
API 규약	API를 만드는 약속	일관성, 예측 가능성, 협업 효율
모노레포	하나의 저장소에 모든 코드	AI가 전체 맥락 파악 가능
시너지	규약 + 모노레포 + AI	빠르고 일관된 개발 가능

비개발자가 기억할 핵심

"API 규약이 있는 모노레포에서 AI 도구를 사용하면, AI가 기존 코드 패턴을 학습하여 일관된 코드를 자동으로 생성한다. 이것이 bkamp가 빠르게 개발될 수 있었던 핵심 비결이다."

문서 버전: 1.0 작성일: 2025-12-26 참고 문서: API 규약 설계서

비개발자를 위한 쉬운 설명 - API가 무엇이고, 왜 약속이 필요하며, 모노레포가 AI 개발에 왜 유리한가

API와 모노레포 이해하기

목차

1. API란 무엇인가?

레스토랑에 비유하면

API의 정의

bkamp에서의 API 예시

2. API 개발에 왜 '약속'이 필요한가?

소통의 혼란을 방지하기 위해

실제 혼란의 예시

bkamp API 규약의 핵심 약속들

1. URL 네이밍 규칙

2. 응답 형식 통일

3. 에러 코드 체계

4. 필드명 규칙

약속이 주는 효과

3. 모노레포란 무엇인가?

코드 저장 방식의 두 가지 선택

멀티레포 (Multi-repo)

모노레포 (Mono-repo)

회사에 비유하면

bkamp의 모노레포 구조

4. Claude Code와 모노레포의 시너지

AI가 코드를 이해하는 방식

모노레포가 AI 개발에 유리한 이유

이유 1: 전체 맥락을 한눈에

이유 2: 공통 모듈 즉시 활용

이유 3: 규약 문서와 코드가 함께

실제 효과: bkamp 개발 사례

Before: 멀티레포 환경이었다면

After: 모노레포 환경 (현재)

핵심 시너지 정리

핵심 요약

비개발자가 기억할 핵심

답변 1개

비개발자를 위한 쉬운 설명 - API가 무엇이고, 왜 약속이 필요하며, 모노레포가 AI 개발에 왜 유리한가

API와 모노레포 이해하기

목차

1. API란 무엇인가?

레스토랑에 비유하면

API의 정의

bkamp에서의 API 예시

2. API 개발에 왜 '약속'이 필요한가?

소통의 혼란을 방지하기 위해

실제 혼란의 예시

bkamp API 규약의 핵심 약속들

1. URL 네이밍 규칙

2. 응답 형식 통일

3. 에러 코드 체계

4. 필드명 규칙

약속이 주는 효과

3. 모노레포란 무엇인가?

코드 저장 방식의 두 가지 선택

멀티레포 (Multi-repo)

모노레포 (Mono-repo)

회사에 비유하면

bkamp의 모노레포 구조

4. Claude Code와 모노레포의 시너지

AI가 코드를 이해하는 방식

모노레포가 AI 개발에 유리한 이유

이유 1: 전체 맥락을 한눈에

이유 2: 공통 모듈 즉시 활용

이유 3: 규약 문서와 코드가 함께

실제 효과: bkamp 개발 사례

Before: 멀티레포 환경이었다면

After: 모노레포 환경 (현재)

핵심 시너지 정리

핵심 요약

비개발자가 기억할 핵심

답변 1개

비개발자를 위한 쉬운 설명 - API가 무엇이고, 왜 약속이 필요하며, 모노레포가 AI 개발에 왜 유리한가

API와 모노레포 이해하기

목차

1. API란 무엇인가?

레스토랑에 비유하면

API의 정의

bkamp에서의 API 예시

2. API 개발에 왜 '약속'이 필요한가?

소통의 혼란을 방지하기 위해

실제 혼란의 예시