AI 드리븐

지도 위치 : 1일차 · 설계 마무리 · 구조를 정하고 이유를 파일로 남기는 자리 | 이전: 7차시 디자인 ② 검증 역할의 분리 | 다음: 9차시 서비스 뼈대 세우기 키워드 : 서비스 계층 구조, 구성 방식 선택과 결정 기록(ADR), 클라우드 개요

이 차시를 다 읽으면

1. 웹 서비스의 네 계층 을 말하고, 각 계층이 하지 않는 일 을 댈 수 있다.
2. 모놀리스 · 모노레포 · 관계형 DB · 트랜잭션을 정의하고, AI와 함께 개발할 때의 선택 기준(널리 쓰이는가, 내가 운영할 수 있는가)을 말할 수 있다.
3. 결정 기록(ADR) 을 유와 종차로 정의하고, 네 부분 중 "검토한 대안"이 왜 가장 쓸모 있는지 설명할 수 있다.
4. ADR과 아키텍처 문서를 "왜" ↔ "무엇이 어디에" 로 가르고, 이해 부채를 줄이는 습관을 말할 수 있다.
5. 클라우드 기본 용어(IaaS · PaaS · SaaS, 리전, 관리형 DB, 오브젝트 스토리지, CDN, 비밀값 관리 서비스)를 한 줄씩 말할 수 있다.

---

0. 이 차시의 판별 축

이 차시가 답하는 질문은 "서비스를 어떤 덩어리로 나누고, 그 결정의 이유를 어떻게 남기는가" 입니다. 앞에서 배운 대로 에이전트는 대화가 끝나면 잊습니다(2차시 2절, 디스크 ↔ 메모리). 규칙을 지침 파일에 남겼듯, 결정의 이유 도 파일에 남깁니다. 기록이 없으면 에이전트는 새 세션마다 "더 좋은 방법"을 제안하며 같은 논의를 반복하거나, 결정을 슬그머니 뒤집습니다. 이 차시로 1일차 "결정" 단계가 끝나고, 2일차의 모든 역할이 여기서 만든 문서를 맥락 (5차시 3.1의 두 번째 축)으로 씁니다.

---

1. ⭐ 서비스 계층 구조

1.1 정의

계층 구조 — [서비스 구성 방식]인데, [ 화면 · 서버 · 데이터 · 외부 서비스를 역할별 층으로 나누고 각 층이 자기 일만 하게 한다 ]는 점에서 한 덩어리 코드가 보여 주기 · 판정 · 저장을 모두 하는 방식과 구별된다.

┌─────────────────────────────┐
│ 화면 (프론트엔드)              │  보여 주고 입력받음. 판정하지 않음 (11차시)
└──────────────┬──────────────┘
               │ API (4차시의 약속)
┌──────────────▼──────────────┐
│ 서버 (백엔드)                  │  판정 · 검증 · 비즈니스 규칙 (10차시)
└───────┬──────────────┬──────┘
        │              │
┌───────▼──────┐ ┌─────▼───────────────┐
│ 데이터 (DB)   │ │ 외부 서비스           │
│ (12차시)      │ │ 결제(16), 이메일 등    │
└──────────────┘ └─────────────────────┘

🔍 읽는 포인트 : 상자 오른쪽의 한 줄 설명만 보면 됩니다. 특히 화면 상자의 "판정하지 않음" .

1.2 각 계층이 하지 않는 일

⚠️ 경계가 무너지는 전형: 화면이 금액을 계산하거나, 서버가 HTML 모양을 정하는 것입니다. 경계가 무너지면 역할을 나눈 에이전트들(5차시)이 서로의 일을 침범 합니다.

💡 비유는 마지막에 — 식당입니다. 홀 직원(화면)은 주문을 받고 음식을 내지만 가격을 정하지 않고, 주방(서버)은 조리하고 판단하며, 창고(데이터)는 보관하고, 배달 대행(외부 서비스)은 맡은 일만 합니다.

---

2. 구성 방식 선택

2.1 먼저 용어

⚠️ 모놀리스( 실행 · 배포 단위)와 모노레포( 저장소 단위)는 다른 축입니다. 화면과 서버를 따로 배포하면서 저장소는 하나로 둘 수 있습니다.

2.2 결정 항목

2.3 AI와 함께 개발할 때 추가 기준

⭐ 마지막 기준에서 코드를 읽지 않는 사람에게 유리한 선택이 나옵니다.

• 서버를 직접 관리하는 방식보다 관리형 서비스 · PaaS (백업 · 보안 패치 · 재시작을 플랫폼이 대신 함, 0절 축 4)
• 대시보드에서 로그와 상태를 눈으로 볼 수 있고, 되돌리기(롤백) 버튼이 있는 플랫폼
• AI가 잘 다루는 널리 쓰이는 기술

2.4 반례 — 지금 고르면 안 되는 구성

---

3. ⭐ 결정 기록 — ADR

3.1 정의

결정 기록 (ADR, Architecture Decision Record) — [설계 문서]인데, [ 결정 하나를 맥락 · 결정 · 검토한 대안 · 결과로 짧게 남겨 "왜 그렇게 정했는가"를 보존한다 ]는 점에서 지금 구조가 어떻게 생겼는지만 보여 주는 아키텍처 문서와 구별된다.

결정 하나에 파일 하나, 짧게 씁니다.

# docs/adr/0002-database.md
# ADR-0002: 데이터베이스로 PostgreSQL을 쓴다

- 상태: 확정 (2026-10-20)

## 맥락
예약과 결제는 "남은 자리 감소"와 "예약 생성"이 함께 성공하거나 함께 실패해야 한다.
동시 예약이 발생할 수 있다.

## 결정
관계형 DB인 PostgreSQL을 쓴다. 클라우드의 관리형 DB를 사용한다.

## 검토한 대안
- 문서형 DB: 트랜잭션 · 제약조건 활용이 상대적으로 불편해서 기각
- SQLite: 로컬 개발은 편하지만 배포 환경의 동시 접속에 부적합해서 기각

## 결과
- 트랜잭션과 잠금(한 예약이 처리되는 동안 같은 자리를 다른 요청이 못 건드리게 함)으로 동시 예약 문제를 처리할 수 있다 (13차시)
- 관리형 DB 비용이 발생한다
- 운영 시 내가 할 수 있는 일: 대시보드에서 백업 복원, 접속 수 확인 / 없는 일: 느린 질의 원인 분석

🔍 읽는 포인트 : ## 검토한 대안과 ## 결과의 마지막 줄만 보면 됩니다.

지침 파일에 한 줄 추가합니다.

기술 선택을 바꾸자고 제안하기 전에 docs/adr/를 먼저 읽는다.

🔍 읽는 포인트 : "제안하기 전에 "입니다. 기록이 있어도 에이전트가 읽지 않으면 소용이 없으므로, 읽는 시점을 규칙으로 정합니다.

3.2 ADR과 아키텍처 문서

⭐ 코드를 읽지 않으면 AI가 구현하면서 구조를 조금씩 바꾸는 것 을 알아채기 어렵습니다. 코드는 늘어나는데 이해하는 사람이 아무도 없는 상태가 쌓이는 것을 이해 부채 라고 부릅니다. 장애가 났을 때(23차시) 가장 크게 드러납니다. 아키텍처 문서는 이 부채를 줄이는 가장 쉬운 장치입니다.

docs/architecture.md를 만들어줘. 계층별로 어떤 기능이 어느 폴더에 있는지, 화면 → 서버 → DB 흐름을
글자 그림으로. 구조를 바꾸는 작업을 할 때마다 이 문서도 갱신하는 규칙을 CLAUDE.md에 추가해줘.

🔍 읽는 포인트 : 두 번째 문장 "갱신하는 규칙을 CLAUDE.md에"입니다. 문서를 한 번 만드는 것보다 계속 맞춰 두는 규칙 이 중요합니다.

그리고 주기적으로 "docs/architecture.md와 실제 코드 구조가 다른 곳이 있는지 점검해줘" 라고 시킵니다.

3.3 반례 — 이건 결정 기록이 아닙니다

---

4. 클라우드 기본 용어

4.1 정의와 용어표

클라우드 — [인프라 이용 방식]인데, [ 남의 데이터센터에 있는 컴퓨터 · 저장소를 인터넷 너머로 빌려 쓰고 쓴 만큼 낸다 ]는 점에서 내 건물에 장비를 두고 직접 운영하는 방식과 구별된다(0절 축 3).

🔍 읽는 포인트 : IaaS → PaaS → SaaS로 갈수록 클라우드가 관리하는 범위가 넓어지고 내가 손댈 범위가 줄어듭니다 (0절 축 4). 코드를 읽지 않는 사람에게는 대체로 오른쪽이 유리합니다(2.3).

앞으로 다시 만납니다 — 15차시에서 이 구성을 설정 파일(코드) 로 적어 되돌릴 수 있게 만들고, 21 · 22차시에서 서버와 화면을 실제로 인터넷에 공개합니다.

---

5. 클래스온 — 1일차 산출물 묶음

docs/
├── requirements.md      # 3차시 — 무엇이 맞는 상태인가
├── scope.md             # 4차시 — Must / Should / Could / Won't
├── api.md               # 4차시 — 화면 ↔ 서버의 약속
├── design.md            # 6차시 — 디자인 토큰 · 상태 규칙
├── architecture.md      # 8차시 — 무엇이 어디에
└── adr/                 # 8차시 — 왜
    ├── 0001-monorepo.md
    ├── 0002-database.md
    └── 0003-hosting.md

🔍 읽는 포인트 : 오른쪽 주석의 차시 번호만 보면 1일차 전체가 한눈에 들어옵니다.

⭐ 이 문서들이 2일차 모든 에이전트의 맥락 이 됩니다. 1일차는 코드를 한 줄도 쓰지 않았지만, 2일차에 AI가 빠르게 코드를 만들 때 무엇이 맞는지 판정할 기준 을 전부 여기서 만들었습니다(README 4장: 결정이 구현보다 먼저 온다).

---

6. 실습 — 맡기고 검수하기

이 차시는 내가 결정권을 쥐는 곳 입니다(README 9.2: 아키텍처 결정 승인). AI는 선택지와 근거를 정리하고, 결정은 내가 합니다.

지시

architect 역할로 클래스온의 서버 실행 방식(hosting)에 대한 ADR 초안을 써줘.
- 대안 최소 3개(예: PaaS, 서버리스 함수, 직접 관리하는 가상 서버)를 [대안 | 장점 | 단점 | 월 예상 비용 범위 | 운영 시 내가 할 수 있는 일 / 없는 일] 표로 비교
- 비용 · 기능은 각 서비스의 공식 문서 주소를 근거로 쓰고, 확인 못 한 칸은 "확인 필요"로 남길 것. 추측으로 채우지 마
- 결정 칸은 비워 두고 "사람 결정 필요"라고 쓸 것
- docs/adr/0003-hosting.md로 저장하고 원문을 보고에 붙여줘

받을 증거

• ADR 초안 원문
• 비교표의 각 칸에 붙은 공식 문서 주소

내가 직접 확인할 것

---

부록 A. 스스로 확인하기

부록 B. 자주 하는 실수

부록 C. NotebookLM 복습 프롬프트

이 8차시 노트만 근거로 6문제를 내줘. 코드를 모르는 사람 기준으로.
"네 계층과 하지 않는 일", "모놀리스와 모노레포", "ADR의 네 부분과 검토한 대안", "ADR과 아키텍처 문서", "IaaS · PaaS · SaaS"는 반드시 포함해줘.
답은 내가 답한 다음에 채점하고, 틀린 이유를 노트의 절 번호를 근거로 설명해줘.