허접 웹프로그래머의 자료 모음

AI 크롤러는 당신의 사이트를 정말 읽을 수 있나요?

은둔한량 — Tue, 21 Jul 2026 11:31:50 +0900

SSR 없이 렌더링된 페이지, 막혀 있는 GPTBot, 빠진 JSON-LD. 눈에는 안 보이지만 AI 답변에서 당신을 사라지게 만드는 것들입니다

$ segeo scan https://your-site.com

→ fetching raw HTML (no JS execution) ...
✓ SEO   crawl · index · meta ····· 82
! GEO   ai-crawler · schema ······ 41   # GPTBot disallowed, no JSON-LD
◆ TOTAL weighted score ·········· 63

# 77 checks · 8 categories · report saved

사람들은 이제 구글에 검색하는 만큼 ChatGPT와 Perplexity에게 묻습니다. 문제는, AI가 답변을 만들 때 참조하는 파이프라인이 우리가 최적화해 온 검색 파이프라인과 다르다는 것입니다.

구글 순위는 잘 나오는데 ChatGPT에 브랜드를 물어보면 전혀 안 나오는 경험, 개발하다 보면 한 번쯤 겪습니다. 버그가 아니라 구조의 문제입니다. 검색엔진 봇과 AI 크롤러는 같은 URL을 열어도 서로 다른 것을 본다는 전제에서 출발해야 합니다.

01. AI 크롤러는 자바스크립트를 실행하지 않는다

가장 먼저 걸리는 지점입니다. Googlebot은 렌더링 큐를 거쳐 JS를 실행하지만, 대부분의 AI 크롤러는 원시 HTML만 가져갑니다. 클라이언트에서 fetch 후 마운트되는 콘텐츠는 AI 입장에서 존재하지 않는 셈입니다.

	Googlebot	GPTBot · ClaudeBot · PerplexityBot
처리 방식	크롤 → 렌더 큐 → JS 실행 → 인덱싱	원시 HTML만 파싱 (JS 미실행)
CSR 콘텐츠	지연은 있지만 결국 읽힘	루트 `div`만 보이면 빈 페이지로 처리

처방 — SPA라면 SSR·SSG·프리렌더를 도입하세요. Next.js는 App Router의 서버 컴포넌트, 그 외 프레임워크는 프리렌더링 미들웨어로 최소한 핵심 콘텐츠·메타·JSON-LD를 원시 HTML에 실어 보내야 합니다.

02. robots.txt / llms.txt — 접근을 명시적으로 허용하기

AI 크롤러 상당수는 차단돼 있으면 그냥 지나갑니다. 기본값으로 막혀 있거나, 와일드카드 Disallow에 함께 걸려버린 경우가 흔하죠. 노출을 원한다면 명시적으로 허용해야 합니다.

# --- AI 크롤러 (허용 시 AI 답변 인용 후보) ---
User-agent: GPTBot          # ChatGPT / OpenAI
User-agent: ClaudeBot       # Claude / Anthropic
User-agent: PerplexityBot   # Perplexity
User-agent: Google-Extended # Gemini 학습·그라운딩 토큰
Allow: /

# --- ChatGPT·Copilot은 Bing 인덱스를 사용 ---
User-agent: Bingbot
Allow: /

# --- 네이버 AI 브리핑 (국내 트래픽의 절반) ---
User-agent: Yeti
Allow: /

Sitemap: https://your-site.com/sitemap.xml

여기에 더해 /llms.txt를 두면, AI가 사이트의 핵심 문서를 빠르게 파악하도록 지도를 쥐여줄 수 있습니다. 마크다운 한 장이면 됩니다.

# Your Company

> 한 줄 소개 — 무엇을 하는 회사이고 누구를 위한 서비스인지.

## 핵심 문서
- [제품 소개](https://your-site.com/about): 기능 요약
- [자주 묻는 질문](https://your-site.com/faq): 대표 Q&A
- [문의](https://your-site.com/contact): 연락 경로

03. 메타 · 스니펫 제어 — nosnippet 한 줄의 무게

구글 AI Overviews는 별도 크롤러가 아니라 일반 Googlebot 색인을 씁니다. 그래서 스니펫 지시자 하나가 AI 노출 여부를 가릅니다. nosnippet이 걸려 있으면 순위와 무관하게 AI 개요에서 즉시 제외됩니다.

<!-- 정규 URL 고정: 중복·파라미터 흡수 -->
<link rel="canonical" href="https://your-site.com/page" />

<!-- 스니펫 충분히 허용 (AI 인용 후보로 노출) -->
<meta name="robots"
      content="index,follow,max-snippet:-1,max-image-preview:large" />

<!-- 특정 페이지만 AI/스니펫 제외하고 싶을 때 -->
<meta name="robots" content="nosnippet" />

04. 구조화 데이터 — AI에게 "엔티티"로 인식되기

AI가 브랜드를 하나의 엔티티(entity) 로 이해하게 만드는 핵심 신호가 JSON-LD입니다. Organization + sameAs로 정체성을 묶고, 콘텐츠는 Article·FAQPage로, 지역 비즈니스라면 LocalBusiness로 명세하세요.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Your Company",
  "url": "https://your-site.com",
  "logo": "https://your-site.com/logo.png",
  "sameAs": [
    "https://www.instagram.com/your",
    "https://blog.naver.com/your",
    "https://www.linkedin.com/company/your"
  ]
}
</script>

05. 인용 가능성 — AI가 복붙할 수 있는 문장 구조

기술 설정을 다 맞춰도, 문장 구조가 인용에 부적합하면 소용없습니다. AI는 두괄식 답변, 정의형 문장, 명확한 시맨틱 마크업을 선호합니다. 질문에 대한 결론을 첫 문장에 두고, <h2>에 실제 질문을, 그 아래 답을 배치하는 구조가 인용률을 높입니다.

<h2>GEO란 무엇인가요?</h2>
<p>GEO는 생성형 AI 검색이 답변을 만들 때 내 사이트를
   출처로 인용하도록 콘텐츠·구조를 최적화하는 작업이다.</p>
<!-- ↑ 정의를 첫 문장에. AI가 그대로 인용 가능 -->

06. URL 하나로 8개 카테고리 77개 항목 자동 점검

위 항목들을 페이지마다 손으로 확인하기는 번거롭습니다. 세지오(SEGEO) 는 주소만 넣으면 검색엔진 기준과 AI 기준을 동시에 훑고, 무엇이 막혀 있는지 리포트로 돌려줍니다.

	카테고리	점검 내용
A	AI 크롤러 접근성	GPTBot·ClaudeBot·PerplexityBot·Google-Extended·Yeti의 robots.txt·llms.txt 정책
B	크롤링 · 인덱싱	상태 코드, 리다이렉트 체인, canonical, sitemap, 도메인 정규화
C	메타 · 스니펫 제어	nosnippet·max-snippet 등 AI 개요 노출을 좌우하는 메타 지시자
D	구조화 데이터	Organization·sameAs·Article·FAQ JSON-LD 유효성과 엔티티 신호
E	콘텐츠 인용 가능성	두괄식·정의형 문장, 통계 밀도, 신선도(freshness)
F	E-E-A-T · 신뢰	저자, 발행일, 출처 링크, 소개·연락처 등 신뢰 근거
H	성능 · 렌더링	JS 없이 원시 HTML만으로 콘텐츠가 읽히는지 검증
I	보안 · 정책	HTTPS, 혼합 콘텐츠, 보안 헤더, HTTP/2

결과는 뭉뚱그린 하나가 아니라 세 축으로 분해됩니다. 77개 항목마다 영향 축이 태그돼 있어, 지금 SEO가 약한지 GEO가 약한지 바로 구분됩니다.

SEO 점수 — 크롤링·인덱싱·메타 등 전통 검색 노출 요인
GEO 점수 — AI 크롤러·구조화·인용 가능성 요인
통합 점수 — 8개 카테고리 가중치 종합 판정

진단 근거 — 구글 검색센터 공식 문서, llms.txt 표준 스펙, 주요 AI 크롤러의 공개 정책을 기반으로 77개 항목과 가중치를 설계했고, 실제 운영 사이트 실측으로 외부 진단 도구와 교차 검증했습니다. 리포트는 링크로 저장돼 팀·개발자에게 그대로 공유할 수 있습니다.

지금 사이트가 어디서 막혀 있는지 확인하세요

$ segeo scan https://segeo.kr

URL 하나로 무료 진단하기

비로그인 1회/일 · 카카오·구글 로그인 시 무제한 · 카드 불필요

SEGEO — 검색엔진과 AI, 두 파이프라인에서 발견되게.

http://segeo.kr 쎄지오

DDD (Domain-Driven Design) 완벽 가이드

은둔한량 — Thu, 26 Mar 2026 20:21:39 +0900

DDD (Domain-Driven Design) 완벽 가이드

1. DDD란 무엇인가?

DDD(Domain-Driven Design, 도메인 주도 설계)는 복잡한 소프트웨어를 도메인(비즈니스 영역)의 본질에 집중하여 설계하는 방법론이다. 2003년 Eric Evans가 저서 *"Domain-Driven Design: Tackling Complexity in the Heart of Software"*에서 처음 체계화하였다.

핵심 철학은 단순하다. 소프트웨어의 복잡성은 기술이 아니라 비즈니스 자체에서 온다. 따라서 개발자와 도메인 전문가가 공통의 언어로 소통하고, 그 언어가 코드에 그대로 반영되어야 한다.

2. DDD의 핵심 원칙

2.1 유비쿼터스 언어 (Ubiquitous Language)

개발팀과 비즈니스 전문가가 동일한 용어를 사용하여 소통하는 것이다. 이 언어는 코드, 문서, 대화 모든 곳에서 일관되게 사용된다.

잘못된 예	올바른 예
`UserData` 클래스	`Customer` 클래스
`processItem()` 메서드	`placeOrder()` 메서드
`flag` 필드	`isApproved` 필드

2.2 모델 주도 설계 (Model-Driven Design)

도메인 모델이 설계와 구현의 중심이 된다. 모델은 단순한 다이어그램이 아니라 코드로 직접 표현되는 살아있는 설계이다.

2.3 지식 탐구 (Knowledge Crunching)

개발자와 도메인 전문가가 반복적인 대화와 협업을 통해 도메인 지식을 정제하고, 이를 모델에 반영하는 과정이다.

3. 전략적 설계 (Strategic Design)

전략적 설계는 큰 그림을 다룬다. 시스템 전체를 어떻게 분리하고 조직할 것인지를 결정한다.

3.1 바운디드 컨텍스트 (Bounded Context)

DDD에서 가장 중요한 개념 중 하나이다. 하나의 모델이 유효한 명확한 경계를 정의한다.

예시: 전자상거래 시스템

┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│   주문 컨텍스트   │  │  배송 컨텍스트    │  │  결제 컨텍스트    │
│                 │  │                 │  │                 │
│  - Order        │  │  - Shipment     │  │  - Payment      │
│  - OrderItem    │  │  - Delivery     │  │  - Transaction  │
│  - Customer     │  │  - Address      │  │  - Invoice      │
│   (주문자 정보)  │  │  - Customer     │  │  - Customer     │
│                 │  │   (수령인 정보)  │  │   (결제자 정보)  │
└─────────────────┘  └─────────────────┘  └─────────────────┘

같은 Customer라는 용어도 컨텍스트마다 다른 의미와 속성을 갖는다. 이것이 바운디드 컨텍스트의 핵심이다.

3.2 컨텍스트 맵 (Context Map)

바운디드 컨텍스트 간의 관계를 시각화한 것이다. 주요 관계 패턴은 다음과 같다.

패턴	설명	사용 상황
Shared Kernel	두 컨텍스트가 공통 모델을 공유	밀접하게 협력하는 팀
Customer-Supplier	상류(Supplier)가 하류(Customer)에 데이터 제공	팀 간 의존 관계가 명확할 때
Conformist	하류가 상류 모델을 그대로 수용	외부 시스템에 종속될 때
Anti-Corruption Layer	외부 모델을 내부 모델로 변환하는 계층	레거시 시스템 통합 시
Open Host Service	공개 프로토콜/API로 서비스 제공	다수의 소비자가 있을 때
Published Language	문서화된 공유 언어(JSON Schema 등)	표준화된 통신이 필요할 때
Separate Ways	관계를 끊고 독립적으로 운영	통합 비용 > 이익일 때

3.3 서브도메인 (Subdomain)

비즈니스 영역을 분류하여 투자 우선순위를 결정한다.

Core Domain (핵심 도메인): 비즈니스의 핵심 경쟁력. 최고의 개발자를 투입하고 DDD를 적극 적용한다.
Supporting Subdomain (지원 도메인): 핵심은 아니지만 비즈니스에 필요한 영역. 적절한 수준으로 개발한다.
Generic Subdomain (일반 도메인): 범용적인 기능. 기존 솔루션이나 외부 서비스를 활용한다.

4. 전술적 설계 (Tactical Design)

전술적 설계는 하나의 바운디드 컨텍스트 내부를 어떻게 구현할 것인지를 다룬다.

4.1 엔티티 (Entity)

고유한 식별자(ID)를 가지며, 시간이 지나도 동일성(identity)이 유지되는 객체이다.

public class Order {
    private OrderId id;          // 고유 식별자
    private CustomerId customer;
    private List<OrderLine> lines;
    private OrderStatus status;

    public void addItem(Product product, int quantity) {
        // 비즈니스 규칙 검증 후 항목 추가
        if (status != OrderStatus.DRAFT) {
            throw new IllegalStateException("확정된 주문에는 상품을 추가할 수 없습니다.");
        }
        lines.add(new OrderLine(product.getId(), quantity, product.getPrice()));
    }

    public Money calculateTotal() {
        return lines.stream()
            .map(OrderLine::subtotal)
            .reduce(Money.ZERO, Money::add);
    }
}

4.2 값 객체 (Value Object)

식별자가 없으며, 속성의 조합으로 동등성이 결정되는 불변 객체이다.

public record Money(BigDecimal amount, Currency currency) {

    public Money add(Money other) {
        if (!this.currency.equals(other.currency)) {
            throw new IllegalArgumentException("통화가 다른 금액은 합산할 수 없습니다.");
        }
        return new Money(this.amount.add(other.amount), this.currency);
    }

    public Money multiply(int quantity) {
        return new Money(this.amount.multiply(BigDecimal.valueOf(quantity)), this.currency);
    }
}

public record Address(String city, String street, String zipCode) {
    // 불변이며 값으로 비교된다
    // new Address("서울", "강남대로", "06000").equals(new Address("서울", "강남대로", "06000")) → true
}

4.3 애그리거트 (Aggregate)

관련된 엔티티와 값 객체를 하나의 트랜잭션 경계로 묶은 것이다. 하나의 애그리거트 루트(Aggregate Root)를 통해서만 내부 객체에 접근할 수 있다.

┌─── Aggregate: Order ────────────────────────────┐
│                                                  │
│   ┌──────────────┐                               │
│   │  Order (Root) │ ← 외부에서 접근하는 유일한 진입점  │
│   └──────┬───────┘                               │
│          │                                       │
│   ┌──────┴───────┐  ┌─────────────┐             │
│   │  OrderLine   │  │  OrderLine  │  (내부 엔티티) │
│   └──────────────┘  └─────────────┘             │
│                                                  │
│   ┌──────────────┐                               │
│   │  Money (VO)  │  (값 객체)                     │
│   └──────────────┘                               │
└──────────────────────────────────────────────────┘

애그리거트 설계 규칙:

애그리거트 루트를 통해서만 내부 상태를 변경한다.
하나의 트랜잭션에서 하나의 애그리거트만 수정한다.
다른 애그리거트는 ID로만 참조한다 (직접 객체 참조 금지).
애그리거트는 가능한 작게 유지한다.

4.4 도메인 이벤트 (Domain Event)

도메인에서 발생한 의미 있는 사건을 표현하는 객체이다. 과거형으로 명명한다.

public record OrderPlacedEvent(
    OrderId orderId,
    CustomerId customerId,
    Money totalAmount,
    LocalDateTime occurredAt
) implements DomainEvent {}

// 사용 예
public class Order {
    public void place() {
        this.status = OrderStatus.PLACED;
        registerEvent(new OrderPlacedEvent(
            this.id, this.customer, calculateTotal(), LocalDateTime.now()
        ));
    }
}

도메인 이벤트는 바운디드 컨텍스트 간의 느슨한 결합(loose coupling)을 실현하는 핵심 도구이다.

4.5 리포지토리 (Repository)

애그리거트의 영속성(저장과 조회)을 담당하는 인터페이스이다. 도메인 계층에서는 인터페이스만 정의하고, 구현은 인프라 계층에서 한다.

// 도메인 계층 - 인터페이스
public interface OrderRepository {
    Order findById(OrderId id);
    void save(Order order);
    List<Order> findByCustomer(CustomerId customerId);
}

// 인프라 계층 - 구현
public class JpaOrderRepository implements OrderRepository {
    @Override
    public Order findById(OrderId id) {
        // JPA를 사용한 구현
    }
}

4.6 도메인 서비스 (Domain Service)

특정 엔티티에 속하지 않는 도메인 로직을 담당한다. 상태를 갖지 않는(Stateless) 객체이다.

public class PricingService {

    public Money calculateDiscountedPrice(Order order, Customer customer) {
        Money total = order.calculateTotal();
        DiscountPolicy policy = resolvePolicy(customer.getGrade());
        return policy.apply(total);
    }
}

4.7 팩토리 (Factory)

복잡한 객체 생성 로직을 캡슐화한다.

public class OrderFactory {

    public Order createOrder(CustomerId customerId, List<CartItem> cartItems) {
        // 재고 확인, 가격 검증 등 복잡한 생성 로직
        Order order = new Order(OrderId.generate(), customerId);
        for (CartItem item : cartItems) {
            order.addItem(item.getProduct(), item.getQuantity());
        }
        return order;
    }
}

5. 아키텍처 패턴

DDD는 특정 아키텍처를 강제하지 않지만, 아래 패턴들과 잘 어울린다.

5.1 계층형 아키텍처 (Layered Architecture)

┌─────────────────────────────────┐
│     Presentation Layer          │  ← UI, API Controller
├─────────────────────────────────┤
│     Application Layer           │  ← 유스케이스 조율, 트랜잭션 관리
├─────────────────────────────────┤
│     Domain Layer                │  ← 엔티티, 값 객체, 도메인 서비스
├─────────────────────────────────┤
│     Infrastructure Layer        │  ← DB, 메시징, 외부 API
└─────────────────────────────────┘

5.2 헥사고날 아키텍처 (Hexagonal / Ports & Adapters)

도메인을 중심에 두고, 외부 의존성을 포트(인터페이스)와 어댑터(구현)로 분리한다.

                    ┌─── Driving Adapter ───┐
                    │   REST Controller     │
                    │   CLI                 │
                    └───────────┬───────────┘
                                │
                    ┌───────────▼───────────┐
                    │     Input Port        │
                    │  (Use Case Interface) │
                    ├───────────────────────┤
                    │                       │
                    │    Domain Model       │  ← 핵심 비즈니스 로직
                    │                       │
                    ├───────────────────────┤
                    │    Output Port        │
                    │  (Repository 등)      │
                    └───────────┬───────────┘
                                │
                    ┌───────────▼───────────┐
                    │  Driven Adapter       │
                    │  JPA, Kafka, Redis    │
                    └───────────────────────┘

5.3 CQRS (Command Query Responsibility Segregation)

명령(쓰기)과 조회(읽기) 모델을 분리한다.

Command 모델: 도메인 모델을 통해 상태 변경 처리
Query 모델: 조회에 최적화된 별도의 읽기 모델 사용

5.4 이벤트 소싱 (Event Sourcing)

상태를 직접 저장하는 대신, 발생한 이벤트의 시퀀스를 저장한다. 현재 상태는 이벤트를 순서대로 재생하여 복원한다.

Event Store:
  1. OrderCreated { orderId: "001", customer: "홍길동" }
  2. ItemAdded { orderId: "001", product: "노트북", qty: 1 }
  3. ItemAdded { orderId: "001", product: "마우스", qty: 2 }
  4. OrderPlaced { orderId: "001", total: 1,520,000원 }

→ 현재 상태 복원: 이벤트 1~4를 순서대로 적용

6. DDD의 사용 범위

6.1 DDD가 적합한 경우

상황	이유
복잡한 비즈니스 로직이 있는 시스템	DDD의 핵심 가치가 발휘됨
도메인 전문가와 긴밀한 협업이 가능한 환경	유비쿼터스 언어의 효과를 극대화
장기적으로 진화해야 하는 시스템	바운디드 컨텍스트로 유연한 변경 가능
마이크로서비스 아키텍처	서비스 경계를 바운디드 컨텍스트로 정의
레거시 시스템 현대화	ACL 패턴으로 점진적 마이그레이션

6.2 DDD가 과도한 경우

상황	대안
단순 CRUD 애플리케이션	Active Record 패턴, 트랜잭션 스크립트
기술 중심 시스템 (파일 변환, ETL 등)	파이프라인 패턴
프로토타입 또는 MVP	빠른 개발 우선, 필요 시 리팩토링
소규모 팀/단기 프로젝트	오버엔지니어링의 위험
도메인 전문가 접근이 불가능한 경우	DDD의 핵심 전제가 성립하지 않음

6.3 산업별 적용 사례

금융: 거래 처리, 리스크 관리, 보험 계약
이커머스: 주문 관리, 재고, 가격 정책
의료: 환자 기록, 진료 워크플로우
물류: 배송 추적, 경로 최적화
SaaS: 멀티테넌트 관리, 구독/과금

7. 실전 적용 가이드

7.1 이벤트 스토밍 (Event Storming)

DDD 모델을 도출하는 가장 효과적인 워크숍 기법이다.

진행 순서:

도메인 이벤트 도출 — 비즈니스에서 일어나는 사건을 주황색 포스트잇에 적는다.
커맨드 식별 — 이벤트를 발생시키는 행위를 파란색 포스트잇에 적는다.
애그리거트 식별 — 커맨드를 처리하고 이벤트를 발생시키는 주체를 노란색 포스트잇에 적는다.
바운디드 컨텍스트 도출 — 관련 요소들을 묶어 경계를 설정한다.
정책 식별 — 이벤트에 반응하여 자동으로 실행되는 규칙을 라일락색 포스트잇에 적는다.

7.2 점진적 도입 전략

DDD를 한 번에 전체 시스템에 적용하는 것은 위험하다. 아래 단계를 따른다.

1단계: 유비쿼터스 언어 수립

도메인 전문가와 용어 사전 작성
코드의 클래스명, 메서드명에 반영

2단계: 바운디드 컨텍스트 식별

기존 시스템의 경계를 분석
핵심 도메인을 우선 식별

3단계: 핵심 도메인에 전술적 패턴 적용

애그리거트, 엔티티, 값 객체 설계
리포지토리 패턴 도입

4단계: 컨텍스트 간 통합 패턴 적용

도메인 이벤트 도입
ACL 등 통합 패턴 구현

7.3 흔한 실수와 주의사항

실수	올바른 접근
기술 패턴에만 집중	도메인 이해가 최우선
모든 곳에 DDD 적용	핵심 도메인에 집중
애그리거트를 너무 크게 설계	작은 애그리거트, ID 참조
빈혈 도메인 모델 (Anemic Domain Model)	엔티티에 비즈니스 로직 포함
유비쿼터스 언어 무시	코드와 대화에서 동일 용어 사용
바운디드 컨텍스트 없이 단일 모델 고집	컨텍스트별 독립 모델 유지

8. DDD와 관련 기술/방법론

기술/방법론	DDD와의 관계
마이크로서비스	바운디드 컨텍스트 = 서비스 경계의 근거
클린 아키텍처	도메인 중심 의존성 방향과 일치
TDD	도메인 모델의 행위를 테스트로 검증
BDD	유비쿼터스 언어로 시나리오 작성
Event-Driven Architecture	도메인 이벤트 기반 비동기 통합
Kafka / RabbitMQ	도메인 이벤트 전달 인프라
Spring Boot	DDD 구현에 널리 사용되는 프레임워크

9. 추천 학습 자료

필수 도서

Eric Evans — Domain-Driven Design: Tackling Complexity in the Heart of Software (2003)
Vaughn Vernon — Implementing Domain-Driven Design (2013)
Vaughn Vernon — Domain-Driven Design Distilled (2016, 입문용)

심화 도서

Scott Millett & Nick Tune — Patterns, Principles, and Practices of Domain-Driven Design (2015)
Alberto Brandolini — Introducing EventStorming (이벤트 스토밍 기법)

10. 요약

DDD는 단순히 코드 패턴의 집합이 아니라 비즈니스 문제를 소프트웨어로 해결하는 사고 방식이다.

핵심을 세 줄로 정리하면 다음과 같다.

전략적 설계: 바운디드 컨텍스트로 시스템을 나누고, 유비쿼터스 언어로 소통한다.
전술적 설계: 엔티티, 값 객체, 애그리거트 등의 빌딩 블록으로 도메인 모델을 구현한다.
지속적 정제: 도메인 전문가와의 협업을 통해 모델을 끊임없이 발전시킨다.

"소프트웨어의 심장부에 있는 복잡성에 맞서라." — Eric Evans

DDD (Domain-Driven Design) — 초보자를 위한 완벽 가이드

은둔한량 — Thu, 26 Mar 2026 20:20:05 +0900

Part 1. DDD가 뭔데?

1.1 한 줄 정의

DDD(Domain-Driven Design, 도메인 주도 설계)는 "비즈니스를 이해하고, 그 이해를 코드에 그대로 녹여내는 소프트웨어 설계 방법"이다.

1.2 "도메인"이 뭔가요?

"도메인(Domain)"은 우리가 만드는 소프트웨어가 해결하려는 현실 세계의 문제 영역이다.

쉽게 말하면 이렇다.

쿠팡을 만든다면 → 도메인은 "온라인 쇼핑"
토스를 만든다면 → 도메인은 "금융/송금"
배달의민족을 만든다면 → 도메인은 "음식 배달"
병원 시스템을 만든다면 → 도메인은 "의료/진료"

도메인에는 그 분야만의 규칙, 용어, 프로세스가 있다. 예를 들어 "음식 배달" 도메인에는 "주문", "배달료", "배달원 배정", "예상 도착 시간" 같은 개념이 있고, 이런 것들이 어떻게 작동하는지에 대한 규칙이 있다.

DDD는 이런 도메인의 규칙과 개념을 코드의 중심에 놓자는 것이다.

1.3 왜 이름이 "Domain-Driven"인가?

보통 개발을 하면 기술 중심으로 생각하기 쉽다.

"DB 테이블을 어떻게 설계하지?"
"API를 RESTful하게 만들어야 하나?"
"Spring을 쓸까, Express를 쓸까?"

DDD는 이런 기술적 고민보다 도메인(비즈니스)을 먼저 생각하라고 말한다.

"고객이 주문을 취소하면 어떤 일이 벌어져야 하지?"
"환불 정책은 뭐지?"
"부분 취소가 가능한가?"

기술이 아니라 비즈니스가 설계를 이끈다(drive) — 그래서 "Domain-Driven"이다.

Part 2. 왜 DDD를 써야 하는가?

2.1 DDD 없이 개발하면 생기는 문제들

많은 프로젝트가 이런 과정을 겪는다.

초기 (1~3개월):
코드가 단순하고, 기능 추가가 빠르다. 모든 게 잘 돌아가는 것 같다.

중기 (6개월~1년):
기능이 늘어나면서 코드가 점점 복잡해진다. "이 코드 왜 이렇게 됐지?" 하는 부분이 생긴다. 하나를 고치면 다른 데가 깨진다.

후기 (1년 이후):
새 기능 하나 추가하는 데 일주일이 걸린다. 아무도 전체 코드를 이해하지 못한다. "처음부터 다시 만들자"는 이야기가 나온다.

이것을 Big Ball of Mud(거대한 진흙 덩어리)라고 부른다. 왜 이렇게 되는 걸까?

2.2 근본적인 원인: 비즈니스와 코드의 괴리

가장 큰 원인은 비즈니스 로직이 코드 여기저기에 흩어져 있기 때문이다.

아래는 DDD 없이 흔히 볼 수 있는 코드이다.

// ❌ 흔한 안 좋은 코드 — 비즈니스 로직이 Controller에 섞여 있다
@PostMapping("/orders/{id}/cancel")
public Response cancelOrder(@PathVariable Long id) {
    Order order = orderRepository.findById(id);

    // 취소 가능한지 확인 — 이게 비즈니스 규칙인데 Controller에 있다
    if (order.getStatus().equals("SHIPPED")) {
        return Response.error("이미 배송된 주문은 취소할 수 없습니다");
    }

    // 환불 금액 계산 — 이것도 비즈니스 규칙이다
    long refundAmount = order.getTotalPrice();
    if (order.getStatus().equals("PREPARING")) {
        refundAmount = (long)(order.getTotalPrice() * 0.9); // 준비중이면 90% 환불
    }

    order.setStatus("CANCELLED");              // 단순 setter 호출
    order.setRefundAmount(refundAmount);
    orderRepository.save(order);

    paymentService.refund(order.getPaymentId(), refundAmount);
    notificationService.sendCancelNotification(order.getUserId());

    return Response.ok();
}

이 코드의 문제점은 다음과 같다.

문제 1: 비즈니스 규칙이 숨어 있다.
"배송 후에는 취소 불가", "준비중이면 90% 환불" 같은 중요한 규칙이 Controller 코드 사이에 묻혀 있다. 기획자가 "환불 정책이 어떻게 되어 있지?"라고 물으면, 코드를 뒤져야 한다.

문제 2: 같은 규칙이 여러 곳에 복사된다.
관리자 페이지에서도 주문 취소를 할 수 있다면? 같은 로직을 복사해서 붙여넣는다. 나중에 환불 정책이 바뀌면 두 곳을 다 찾아서 고쳐야 한다. 한 곳을 빼먹으면 버그가 된다.

문제 3: 테스트하기 어렵다.
이 로직을 테스트하려면 HTTP 요청을 만들어야 한다. 순수한 비즈니스 규칙만 테스트할 수가 없다.

2.3 DDD가 이 문제를 어떻게 해결하는가

DDD를 적용하면 같은 기능이 이렇게 바뀐다.

// ✅ DDD를 적용한 코드 — 비즈니스 규칙이 Order 안에 있다

// 도메인 모델 — Order 클래스
public class Order {
    private OrderId id;
    private OrderStatus status;
    private Money totalPrice;

    public void cancel() {
        // 비즈니스 규칙이 Order 안에 명확하게 표현된다
        if (this.status == OrderStatus.SHIPPED) {
            throw new OrderAlreadyShippedException("이미 배송된 주문은 취소할 수 없습니다");
        }

        this.status = OrderStatus.CANCELLED;
    }

    public Money calculateRefundAmount() {
        if (this.status == OrderStatus.PREPARING) {
            return this.totalPrice.multiply(0.9);   // 준비중: 90% 환불
        }
        return this.totalPrice;                      // 그 외: 전액 환불
    }
}

// Controller — 얇고 단순하다
@PostMapping("/orders/{id}/cancel")
public Response cancelOrder(@PathVariable Long id) {
    orderCancelService.cancel(OrderId.of(id));   // 유스케이스 호출만
    return Response.ok();
}

// Application Service — 흐름만 조율한다
public class OrderCancelService {
    public void cancel(OrderId orderId) {
        Order order = orderRepository.findById(orderId);

        order.cancel();                                          // 도메인 모델에게 위임
        Money refund = order.calculateRefundAmount();            // 도메인 모델에게 위임

        orderRepository.save(order);
        paymentService.refund(order.getPaymentId(), refund);
        eventPublisher.publish(new OrderCancelledEvent(order));
    }
}

무엇이 달라졌는가?

달라진 점 1: 비즈니스 규칙이 한 곳에 모여 있다.
"취소 가능 여부"와 "환불 금액 계산"이라는 규칙이 Order 클래스 안에 있다. 기획자가 "환불 정책이 뭐지?"라고 물으면, Order.calculateRefundAmount()를 보면 된다.

달라진 점 2: 어디서든 같은 규칙이 적용된다.
사용자가 취소하든, 관리자가 취소하든, 배치 작업이 취소하든, 항상 order.cancel()을 호출한다. 규칙이 중복되지 않는다.

달라진 점 3: 비즈니스 규칙만 따로 테스트할 수 있다.

@Test
void 배송된_주문은_취소할_수_없다() {
    Order order = createOrder(OrderStatus.SHIPPED);
    assertThrows(OrderAlreadyShippedException.class, () -> order.cancel());
}

@Test
void 준비중인_주문은_90퍼센트_환불한다() {
    Order order = createOrder(OrderStatus.PREPARING);
    Money refund = order.calculateRefundAmount();
    assertEquals(Money.of(9000), refund);  // 10,000원의 90%
}

HTTP, DB, 프레임워크 없이 순수하게 비즈니스 규칙만 테스트할 수 있다.

2.4 한 마디로 정리하는 DDD의 가치

문제	DDD의 해결책
비즈니스 규칙이 코드 여기저기 흩어져 있다	도메인 모델에 규칙을 집중시킨다
개발자와 기획자가 서로 다른 언어를 쓴다	유비쿼터스 언어로 통일한다
시스템이 커질수록 변경이 어렵다	바운디드 컨텍스트로 경계를 나눈다
새 팀원이 코드를 이해하기 어렵다	코드가 비즈니스를 직접 설명한다

Part 3. DDD의 핵심 개념 — 쉽게 풀어쓰기

DDD에는 크게 두 가지 영역이 있다. 전략적 설계(큰 그림)와 전술적 설계(세부 구현)이다. 레스토랑에 비유하면, 전략적 설계는 "주방, 홀, 창고를 어떻게 배치할까"이고, 전술적 설계는 "각 구역 안의 도구와 작업 방식을 어떻게 정할까"이다.

3.1 전략적 설계 — 큰 그림 그리기

3.1.1 유비쿼터스 언어 (Ubiquitous Language)

한 줄 설명: 개발팀과 비즈니스팀이 똑같은 단어를 쓰는 것이다.

왜 필요한가?

실제로 흔히 일어나는 상황을 보자.

기획자: "고객이 장바구니에서 결제하면 주문이 생성되잖아요."
개발자: "아, 네. User가 Cart의 Item들을 Payment 처리하면 OrderData가 INSERT 되는 거죠."
기획자: "...네?"

같은 이야기를 하고 있는데 용어가 다르다. 이런 상황이 반복되면 커뮤니케이션 비용이 기하급수적으로 늘어난다.

DDD에서는 이렇게 한다.

기획자: "고객(Customer)이 주문(Order)을 생성(placeOrder)하면..."
개발자: "네, Customer 객체의 placeOrder 메서드를 호출하면..."

코드에서도, 회의에서도, 문서에서도 같은 단어를 쓴다. 코드가 곧 비즈니스 문서가 된다.

실천 방법:

프로젝트 초기에 팀원들과 용어 사전을 만든다.
코드의 클래스명, 메서드명, 변수명에 이 용어를 사용한다.
기술 용어를 비즈니스 용어로 치환한다.

잘못된 예                    올바른 예
────────────────────────    ────────────────────────
UserData                 →  Customer
processItem()            →  placeOrder()
updateFlag()             →  approvePayment()
data1, data2             →  shippingAddress, billingAddress
handleStuff()            →  calculateDeliveryFee()

3.1.2 바운디드 컨텍스트 (Bounded Context)

한 줄 설명: "이 용어와 규칙이 통하는 범위"의 경계선이다.

왜 필요한가?

현실에서 같은 단어가 상황에 따라 다른 뜻을 갖는 것처럼, 소프트웨어에서도 마찬가지다.

"상품(Product)"이라는 단어를 생각해 보자.

상품 카탈로그팀: 이름, 설명, 이미지, 카테고리가 중요하다.
재고 관리팀: 수량, 창고 위치, 입출고 이력이 중요하다.
주문팀: 가격, 할인, 주문 수량이 중요하다.
배송팀: 무게, 크기, 포장 방법이 중요하다.

이 네 팀이 하나의 Product 클래스를 공유하면 어떻게 될까?

// ❌ 모든 팀이 하나의 Product를 공유한 결과
public class Product {
    private String name;          // 카탈로그팀이 씀
    private String description;   // 카탈로그팀이 씀
    private String imageUrl;      // 카탈로그팀이 씀
    private int stockQuantity;    // 재고팀이 씀
    private String warehouseCode; // 재고팀이 씀
    private BigDecimal price;     // 주문팀이 씀
    private BigDecimal discount;  // 주문팀이 씀
    private double weight;        // 배송팀이 씀
    private String packagingType; // 배송팀이 씀
    // ... 필드가 끝없이 늘어난다
}

이 클래스는 모든 팀의 요구사항을 담다 보니 비대해지고, 한 팀의 변경이 다른 팀에 영향을 준다. 재고팀이 stockQuantity 관련 로직을 수정했는데, 주문팀 코드가 깨지는 일이 생긴다.

DDD에서는 바운디드 컨텍스트로 경계를 나눈다.

┌── 카탈로그 컨텍스트 ──┐  ┌── 재고 컨텍스트 ──────┐
│                       │  │                       │
│  Product              │  │  StockItem             │
│  ├ name               │  │  ├ productId (ID만!)   │
│  ├ description         │  │  ├ quantity            │
│  ├ imageUrl           │  │  ├ warehouseCode       │
│  └ category           │  │  └ lastRestockedAt     │
│                       │  │                       │
└───────────────────────┘  └───────────────────────┘

┌── 주문 컨텍스트 ──────┐  ┌── 배송 컨텍스트 ──────┐
│                       │  │                       │
│  OrderItem            │  │  Parcel               │
│  ├ productId (ID만!)  │  │  ├ productId (ID만!)  │
│  ├ unitPrice          │  │  ├ weight              │
│  ├ quantity           │  │  ├ dimensions          │
│  └ discount           │  │  └ packagingType       │
│                       │  │                       │
└───────────────────────┘  └───────────────────────┘

각 컨텍스트는 자기에게 필요한 속성만 가진다. 다른 컨텍스트의 객체는 ID로만 참조한다. 이렇게 하면 각 컨텍스트가 독립적으로 변경될 수 있다.

비유: 바운디드 컨텍스트는 나라의 국경과 같다. 같은 "football"이라는 단어도 미국에서는 미식축구, 영국에서는 축구를 의미한다. 각 나라(컨텍스트) 안에서는 혼동이 없다. 국경(경계)이 있기 때문이다.

3.1.3 컨텍스트 맵 (Context Map)

한 줄 설명: 바운디드 컨텍스트들이 서로 어떤 관계인지 그린 지도이다.

바운디드 컨텍스트들은 완전히 고립되지 않는다. 서로 데이터를 주고받아야 한다. 이 관계를 정리한 것이 컨텍스트 맵이다.

주요 관계 패턴을 일상 비유로 설명하면 이렇다.

Shared Kernel (공유 커널):
두 팀이 공통으로 쓰는 코드가 있다. 마치 두 가게가 하나의 주차장을 공유하는 것과 같다. 편리하지만 한쪽이 주차장을 바꾸면 다른 쪽도 영향을 받는다.

Customer-Supplier (고객-공급자):
한 팀(공급자)이 다른 팀(고객)에게 데이터를 제공한다. 식당(고객)과 식재료 납품업체(공급자)의 관계와 같다. 식당이 필요한 것을 요청하고, 납품업체가 맞춰준다.

Anti-Corruption Layer (부패 방지 계층):
외부 시스템의 복잡하고 지저분한 데이터를 우리 시스템에 맞게 변환하는 계층이다. 해외여행 시 환전하는 것과 같다. 외국 화폐(외부 모델)를 우리나라 화폐(내부 모델)로 바꿔서 사용한다.

// Anti-Corruption Layer 예시
// 외부 결제 시스템의 응답을 우리 도메인 모델로 변환한다
public class PaymentGatewayAdapter {

    private final ExternalPaymentAPI externalApi;

    public PaymentResult processPayment(Order order) {
        // 외부 API는 우리와 다른 용어, 다른 구조를 사용한다
        ExternalPaymentResponse response = externalApi.charge(
            order.getTotalPrice().toDouble(),      // 외부: double 사용
            order.getCustomer().getId().toString()  // 외부: String ID
        );

        // 외부 응답을 우리 도메인 모델로 "번역"한다
        return new PaymentResult(
            PaymentId.of(response.getTransactionRef()),
            response.getResultCode().equals("00") 
                ? PaymentStatus.APPROVED 
                : PaymentStatus.DECLINED,
            Money.of(response.getChargedAmt())
        );
    }
}

3.1.4 서브도메인 (Subdomain) — 모든 곳에 DDD를 쓸 필요는 없다

한 줄 설명: 비즈니스 영역을 중요도에 따라 분류하는 것이다.

이것은 매우 실용적인 개념이다. 모든 코드에 DDD를 적용할 필요가 없다. 중요한 곳에만 집중하면 된다.

Core Domain (핵심 도메인) — 우리 서비스의 경쟁력

배달의민족이라면: "배달원 배정 알고리즘", "예상 도착 시간 계산"
넷플릭스라면: "콘텐츠 추천 알고리즘"
여기에 최고의 개발자를 투입하고, DDD를 적극 적용한다.

Supporting Subdomain (지원 도메인) — 핵심은 아니지만 필요한 것

배달의민족이라면: "가게 등록/관리", "메뉴 관리"
중요하지만 경쟁력의 원천은 아니다. 적절한 수준으로 개발한다.

Generic Subdomain (일반 도메인) — 누구나 필요한 것

"로그인/회원가입", "알림 발송", "파일 업로드"
이건 직접 만들 필요 없다. 기존 라이브러리나 SaaS를 쓴다.

투자 우선순위:

┌─────────────────────────────────────────────┐
│            Core Domain                       │
│     (DDD 전력 투입, 최고 인력 배치)            │
│     배달원 매칭, 추천 알고리즘 등               │
├─────────────────────────────────────────────┤
│         Supporting Subdomain                 │
│     (적절한 수준의 설계)                       │
│     가게 관리, 메뉴 관리, 리뷰 등              │
├─────────────────────────────────────────────┤
│          Generic Subdomain                   │
│     (구매/외부 서비스 활용)                     │
│     인증, 알림, 결제 연동 등                   │
└─────────────────────────────────────────────┘

3.2 전술적 설계 — 실제로 코드를 어떻게 짜는가

전략적 설계로 큰 그림을 그렸다면, 이제 각 바운디드 컨텍스트 안에서 어떤 구조로 코드를 짤 것인지를 정한다.

3.2.1 엔티티 (Entity)

한 줄 설명: 고유한 ID가 있어서, 속성이 바뀌어도 같은 것으로 식별되는 객체이다.

비유: 사람은 이름을 바꿔도, 머리를 잘라도, 옷을 바꿔도 같은 사람이다. 주민등록번호(ID)로 식별하기 때문이다.

public class Customer {
    private final CustomerId id;   // 이것으로 식별된다
    private String name;            // 바뀔 수 있다
    private String email;           // 바뀔 수 있다
    private Address address;        // 바뀔 수 있다

    // name이 바뀌어도 같은 Customer이다
    // id가 같으면 동일한 Customer이다
}

엔티티의 핵심 규칙:

반드시 고유한 식별자(ID)를 가진다.
라이프사이클이 있다 (생성 → 변경 → 삭제).
속성이 달라져도 ID가 같으면 같은 객체이다.
자신의 비즈니스 규칙을 스스로 관리한다 (이것이 핵심이다).

// ❌ 나쁜 예: 빈혈 모델 (Anemic Model) — 엔티티에 로직이 없다
public class Order {
    private Long id;
    private String status;
    private BigDecimal totalPrice;

    // getter, setter만 있다
    public String getStatus() { return status; }
    public void setStatus(String status) { this.status = status; }
}

// 비즈니스 로직이 Service에 흩어져 있다
public class OrderService {
    public void cancelOrder(Long orderId) {
        Order order = repository.findById(orderId);
        if (order.getStatus().equals("SHIPPED")) {     // 규칙이 여기에 있다
            throw new RuntimeException("취소 불가");
        }
        order.setStatus("CANCELLED");                   // 아무나 상태를 바꿀 수 있다
    }
}

// ✅ 좋은 예: 풍부한 모델 (Rich Model) — 엔티티가 자기 규칙을 안다
public class Order {
    private final OrderId id;
    private OrderStatus status;
    private Money totalPrice;

    // setter가 없다! 상태 변경은 비즈니스 의미가 있는 메서드로만 가능하다
    public void cancel() {
        if (this.status == OrderStatus.SHIPPED) {
            throw new OrderAlreadyShippedException();
        }
        if (this.status == OrderStatus.CANCELLED) {
            throw new OrderAlreadyCancelledException();
        }
        this.status = OrderStatus.CANCELLED;
    }

    public void ship() {
        if (this.status != OrderStatus.PAID) {
            throw new OrderNotPaidException();
        }
        this.status = OrderStatus.SHIPPED;
    }
}

setStatus("CANCELLED") 대신 cancel()이라는 비즈니스 의미가 있는 메서드를 사용한다. 이 안에 "취소할 수 있는 조건"이라는 비즈니스 규칙이 들어 있다. 이것이 DDD에서 말하는 풍부한 도메인 모델(Rich Domain Model)이다.

3.2.2 값 객체 (Value Object)

한 줄 설명: ID가 없고, 값 자체가 의미인 객체이다. 불변(immutable)이다.

비유: 만원짜리 지폐를 생각해 보자. 내가 가진 만원과 친구가 가진 만원은 "구별"할 필요 없이 같은 가치이다. 우리는 지폐의 일련번호(ID)로 돈을 구분하지 않는다. 금액이라는 값 자체가 중요하다.

// 값 객체 예시 1: 돈
public record Money(BigDecimal amount, String currency) {

    // 불변이다 — 새 객체를 반환한다
    public Money add(Money other) {
        if (!this.currency.equals(other.currency)) {
            throw new CurrencyMismatchException();
        }
        return new Money(this.amount.add(other.amount), this.currency);
    }
}

// 값 객체 예시 2: 주소
public record Address(String city, String district, String detail, String zipCode) {
    // 서울 강남구의 이 주소와 저 주소가 "같은 곳"이면 같은 Address이다
    // ID로 구분하지 않고, 값으로 비교한다
}

// 값 객체 예시 3: 기간
public record DateRange(LocalDate start, LocalDate end) {
    public DateRange {
        if (end.isBefore(start)) {
            throw new IllegalArgumentException("종료일이 시작일보다 앞설 수 없습니다");
        }
    }

    public boolean contains(LocalDate date) {
        return !date.isBefore(start) && !date.isAfter(end);
    }
}

"왜 그냥 String이나 int를 쓰면 안 되나요?"

// ❌ 원시 타입 사용 — 의미가 불명확하고 실수하기 쉽다
public void createOrder(String customerId, int amount, String currency) {
    // customerId 자리에 실수로 상품명을 넣어도 컴파일러가 잡지 못한다!
}
createOrder("맥북 프로", 1000, "KRW");  // 버그! 그런데 컴파일은 된다

// ✅ 값 객체 사용 — 타입으로 실수를 방지한다
public void createOrder(CustomerId customerId, Money price) {
    // CustomerId 자리에 String을 넣으면 컴파일 에러!
}
createOrder(new CustomerId("C001"), new Money(1000, "KRW"));  // 명확하다

값 객체를 사용하면 타입 시스템이 실수를 잡아준다. 이것을 "Primitive Obsession(원시 타입 집착)을 피한다"고 한다.

3.2.3 애그리거트 (Aggregate)

한 줄 설명: 항상 함께 변경되어야 하는 객체들을 하나로 묶은 단위이다.

이것은 DDD에서 가장 어렵지만 가장 중요한 개념이다.

비유: 주문서를 생각해 보자. 주문서에는 주문 항목들이 있다. "주문 항목 #3"을 따로 다른 주문서로 옮기는 건 말이 안 된다. 주문서와 주문 항목은 항상 함께 존재하고, 함께 변경되어야 한다. 이 "주문서 + 주문 항목들"이 하나의 애그리거트이다.

// Order 애그리거트
// Order가 Aggregate Root (유일한 진입점)
public class Order {
    private final OrderId id;
    private final CustomerId customerId;        // 다른 애그리거트는 ID로만 참조!
    private final List<OrderLine> orderLines;   // 내부 객체
    private OrderStatus status;
    private Money totalPrice;

    // 외부에서는 반드시 Order(Root)를 통해서만 OrderLine을 조작한다
    public void addItem(ProductId productId, int quantity, Money unitPrice) {
        if (this.status != OrderStatus.DRAFT) {
            throw new OrderNotModifiableException();
        }
        this.orderLines.add(new OrderLine(productId, quantity, unitPrice));
        recalculateTotal();
    }

    public void removeItem(ProductId productId) {
        this.orderLines.removeIf(line -> line.getProductId().equals(productId));
        recalculateTotal();
    }

    private void recalculateTotal() {
        this.totalPrice = orderLines.stream()
            .map(OrderLine::subtotal)
            .reduce(Money.ZERO, Money::add);
    }
}

// OrderLine은 Order 없이는 존재할 수 없다
public class OrderLine {
    private final ProductId productId;
    private int quantity;
    private Money unitPrice;

    public Money subtotal() {
        return unitPrice.multiply(quantity);
    }
}

왜 애그리거트가 필요한가?

데이터 일관성 보장: 주문 항목이 변경되면 총액도 함께 바뀌어야 한다. 애그리거트 안에서 이걸 보장한다.
동시성 제어: 애그리거트 단위로 락(lock)을 잡으면 된다. 두 사람이 동시에 같은 주문을 수정하는 것을 방지할 수 있다.
트랜잭션 경계: 하나의 트랜잭션 = 하나의 애그리거트. 명확하고 단순하다.

초보자가 자주 하는 실수: 애그리거트를 너무 크게 만드는 것

// ❌ 너무 큰 애그리거트 — Customer 안에 모든 것을 넣었다
public class Customer {
    private CustomerId id;
    private List<Order> orders;           // 주문 수백 개를 다 로딩?
    private List<Review> reviews;          // 리뷰도?
    private List<Address> addresses;       // 배송지도?
    private ShoppingCart cart;              // 장바구니도?
}
// Customer를 불러올 때마다 수백 개의 주문을 다 읽어야 한다. 성능 재앙!

// ✅ 적절한 크기 — 각각 독립적인 애그리거트로 분리한다
public class Customer {
    private CustomerId id;
    private String name;
    private String email;
}

public class Order {
    private OrderId id;
    private CustomerId customerId;  // Customer를 ID로만 참조한다!
    private List<OrderLine> lines;
}

public class ShoppingCart {
    private CartId id;
    private CustomerId customerId;  // Customer를 ID로만 참조한다!
    private List<CartItem> items;
}

규칙: 다른 애그리거트는 반드시 ID로만 참조한다. 객체를 직접 포함하지 않는다.

3.2.4 도메인 이벤트 (Domain Event)

한 줄 설명: "이런 일이 일어났어요"를 알리는 메시지이다.

비유: 회사에서 "김대리가 퇴사했습니다"라는 공지가 나면, 인사팀은 급여를 정리하고, IT팀은 계정을 삭제하고, 총무팀은 장비를 회수한다. 각 팀은 자기 할 일을 알아서 한다. 공지를 보낸 사람이 각 팀에 일일이 지시하지 않는다.

// 이벤트 정의 — 과거형으로 이름 짓는다 ("이런 일이 일어났다")
public record OrderPlacedEvent(OrderId orderId, CustomerId customerId, Money total) {}
public record OrderCancelledEvent(OrderId orderId, Money refundAmount) {}
public record PaymentCompletedEvent(PaymentId paymentId, OrderId orderId) {}

// 이벤트 발행
public class Order {
    public void place() {
        this.status = OrderStatus.PLACED;
        Events.publish(new OrderPlacedEvent(this.id, this.customerId, this.totalPrice));
    }
}

// 이벤트 처리 — 각자 자기 할 일을 한다
// 재고 서비스
@EventListener
public void on(OrderPlacedEvent event) {
    stockService.reserve(event.orderId());  // 재고 차감
}

// 알림 서비스
@EventListener  
public void on(OrderPlacedEvent event) {
    notificationService.sendOrderConfirmation(event.customerId());  // 주문 확인 알림
}

// 포인트 서비스
@EventListener
public void on(OrderPlacedEvent event) {
    pointService.earnPoints(event.customerId(), event.total());  // 포인트 적립
}

왜 이벤트를 쓰는가?

이벤트 없이 직접 호출하면 이렇게 된다.

// ❌ 이벤트 없이 — Order가 모든 후속 작업을 직접 알아야 한다
public class OrderService {
    public void placeOrder(Order order) {
        orderRepository.save(order);
        stockService.reserve(order);                    // 재고
        notificationService.sendConfirmation(order);    // 알림
        pointService.earnPoints(order);                 // 포인트
        analyticsService.trackOrder(order);             // 분석
        // 새로운 후속 작업이 추가될 때마다 여기를 수정해야 한다!
    }
}

이러면 주문 서비스가 재고, 알림, 포인트, 분석 서비스를 모두 알아야 한다. 결합도가 높아진다. 새로운 후속 작업(예: 쿠폰 발행)이 추가되면 이 코드를 수정해야 한다.

이벤트를 사용하면 Order는 "주문이 완료되었다"는 사실만 알리고, 나머지는 각 서비스가 알아서 처리한다. 느슨한 결합(Loose Coupling)이 실현된다.

3.2.5 리포지토리 (Repository)

한 줄 설명: 애그리거트를 저장하고 꺼내오는 창구이다.

비유: 도서관의 사서와 같다. 우리는 "이 책 좀 찾아주세요"라고 하면 사서가 서가에서 찾아다 준다. 책이 서가의 어디에 있는지(DB 테이블, SQL 쿼리) 우리가 알 필요 없다.

// 도메인 계층 — "무엇을" 할 수 있는지만 정의한다 (인터페이스)
public interface OrderRepository {
    Order findById(OrderId id);
    void save(Order order);
    List<Order> findByCustomer(CustomerId customerId);
}

// 인프라 계층 — "어떻게" 하는지를 구현한다
public class JpaOrderRepository implements OrderRepository {

    @Override
    public Order findById(OrderId id) {
        // JPA, MyBatis, 순수 JDBC 등 무엇이든 가능
        // 도메인 코드는 이 구현을 모른다!
        OrderEntity entity = em.find(OrderEntity.class, id.getValue());
        return entity.toDomain();
    }
}

왜 인터페이스와 구현을 나누는가?

도메인 모델이 DB 기술에 의존하지 않게 하기 위해서이다. JPA를 MyBatis로 바꾸거나, MySQL을 MongoDB로 바꿔도 도메인 코드는 전혀 수정할 필요 없다.

3.2.6 도메인 서비스 (Domain Service)

한 줄 설명: 하나의 엔티티에 넣기 애매한 비즈니스 로직을 담는 곳이다.

// "할인 금액 계산"은 Order에 넣을까, Customer에 넣을까?
// 둘 다 참여하는 로직이므로 도메인 서비스에 둔다.
public class DiscountCalculator {

    public Money calculateDiscount(Order order, Customer customer) {
        Money discount = Money.ZERO;

        // VIP 고객 할인
        if (customer.getGrade() == Grade.VIP) {
            discount = discount.add(order.getTotal().multiply(0.05));
        }

        // 대량 주문 할인
        if (order.getItemCount() >= 10) {
            discount = discount.add(order.getTotal().multiply(0.03));
        }

        return discount;
    }
}

주의: 도메인 서비스를 남용하면 엔티티가 비어버린다(빈혈 모델). 가능하면 엔티티 안에 로직을 넣고, 정말로 여러 엔티티에 걸친 로직만 도메인 서비스로 뺀다.

3.2.7 애플리케이션 서비스 (Application Service)

한 줄 설명: 유스케이스의 흐름을 조율하는 지휘자이다. 비즈니스 로직은 없다.

비유: 오케스트라의 지휘자와 같다. 지휘자는 악기를 직접 연주하지 않는다(비즈니스 로직을 직접 수행하지 않는다). 각 연주자(도메인 객체)에게 "자, 이제 당신 차례"라고 신호를 보내고, 전체 흐름을 조율한다.

// Application Service — 흐름만 조율한다 (비즈니스 로직 없음!)
public class PlaceOrderUseCase {

    private final OrderRepository orderRepository;
    private final CustomerRepository customerRepository;
    private final DiscountCalculator discountCalculator;
    private final EventPublisher eventPublisher;

    @Transactional  // 트랜잭션 관리는 여기서
    public OrderId execute(PlaceOrderCommand command) {
        // 1. 필요한 도메인 객체를 가져온다
        Customer customer = customerRepository.findById(command.customerId());

        // 2. 도메인 객체에게 일을 시킨다
        Order order = Order.create(customer.getId(), command.items());
        Money discount = discountCalculator.calculateDiscount(order, customer);
        order.applyDiscount(discount);
        order.place();

        // 3. 결과를 저장한다
        orderRepository.save(order);

        // 4. 이벤트를 발행한다
        eventPublisher.publish(new OrderPlacedEvent(order.getId()));

        return order.getId();
    }
}

이 코드를 읽으면 비즈니스 프로세스가 한눈에 보인다: 고객을 찾고 → 주문을 만들고 → 할인을 적용하고 → 주문을 확정하고 → 저장하고 → 알린다.

Part 4. 어디에 쓰는가? — 사용 범위

4.1 DDD를 써야 하는 상황

"이럴 때 DDD가 빛난다"

상황 1: 비즈니스 규칙이 복잡하다

보험 가입 심사, 대출 승인, 가격 정책 등
if-else가 수십 개 중첩되기 시작하면 DDD를 고려한다

상황 2: 여러 팀이 하나의 시스템을 만든다

바운디드 컨텍스트로 팀별 경계를 나누면 독립적으로 개발할 수 있다

상황 3: 시스템이 오래 유지보수될 예정이다

3~5년 이상 운영될 시스템이라면 초기 투자 가치가 있다

상황 4: 마이크로서비스로 가려고 한다

바운디드 컨텍스트가 마이크로서비스의 경계가 된다
DDD 없이 마이크로서비스를 나누면 "분산된 모놀리스"라는 최악의 결과가 나올 수 있다

상황 5: 도메인 전문가(기획자, 현업)와 협업할 수 있다

DDD의 핵심은 도메인 전문가와의 소통이다
이 전제가 성립하지 않으면 DDD의 효과가 크게 줄어든다

4.2 DDD를 쓰지 않아도 되는 상황

"이럴 때는 과도하다"

상황 1: 단순 CRUD 앱

게시판, 관리자 페이지처럼 데이터를 넣고 빼는 게 전부라면 DDD는 오버엔지니어링이다
그냥 Controller → Service → Repository 구조로 충분하다

상황 2: 프로토타입 / MVP

빨리 만들어서 시장 반응을 봐야 하는 단계라면 DDD는 속도를 늦춘다
먼저 만들고, 성공하면 나중에 리팩토링한다

상황 3: 기술 중심 시스템

로그 수집, ETL 파이프라인, 파일 변환 도구 등
비즈니스 규칙보다 기술적 처리가 핵심인 시스템에는 맞지 않는다

상황 4: 혼자 또는 소규모 팀의 단기 프로젝트

3개월 안에 끝나는 1~2명의 프로젝트라면 간단한 구조가 낫다

4.3 판단 기준 체크리스트

아래 질문에 "예"가 3개 이상이면 DDD를 진지하게 고려해볼 만하다.

□ 비즈니스 규칙이 자주 바뀌거나 복잡한가?
□ 도메인 전문가(기획자, 현업)가 프로젝트에 참여하는가?
□ 시스템을 2년 이상 유지보수할 예정인가?
□ 3명 이상의 개발자가 같은 코드베이스에서 일하는가?
□ "이 코드 왜 이렇게 됐지?" 하는 상황이 자주 발생하는가?
□ 새로운 기능을 추가할 때 기존 코드를 많이 수정해야 하는가?
□ 마이크로서비스 아키텍처를 계획하고 있는가?

Part 5. 아키텍처 — DDD 코드를 어떤 구조로 정리하는가

5.1 계층형 아키텍처 (Layered Architecture)

가장 기본적인 구조이다. 각 계층은 아래 계층만 사용할 수 있다.

  com.example.order
├──   presentation          ← 1. 사용자 인터페이스 계층
│   ├── OrderController.java       사용자 요청을 받고 응답을 돌려준다
│   └── OrderResponse.java         응답 형태를 정의한다
│
├──   application            ← 2. 응용 계층 (유스케이스)
│   ├── PlaceOrderUseCase.java     흐름을 조율한다 (비즈니스 로직 없음)
│   └── PlaceOrderCommand.java     입력 데이터를 담는다
│
├──   domain                 ← 3. 도메인 계층 (핵심!)
│   ├── Order.java                 엔티티 + 비즈니스 규칙
│   ├── OrderLine.java             내부 엔티티
│   ├── Money.java                 값 객체
│   ├── OrderStatus.java           값 객체 (Enum)
│   ├── OrderRepository.java       리포지토리 인터페이스
│   └── DiscountCalculator.java    도메인 서비스
│
└──   infrastructure         ← 4. 인프라 계층
    ├── JpaOrderRepository.java    리포지토리 구현
    ├── OrderJpaEntity.java        DB 매핑용 엔티티
    └── KafkaEventPublisher.java   이벤트 발행 구현

핵심은 의존성 방향이다. 도메인 계층은 다른 어떤 계층에도 의존하지 않는다. 인프라 계층이 도메인 계층에 의존한다 (화살표가 안쪽을 향한다).

5.2 헥사고날 아키텍처 (Hexagonal Architecture)

계층형보다 한 단계 진화한 구조이다. 도메인을 중심에 놓고, 외부와의 연결을 "포트"와 "어댑터"로 분리한다.

           외부 세계 (들어오는 쪽)
    ┌─────────────────────────────┐
    │  REST API   │  GraphQL  │  CLI │     ← Driving Adapters
    └──────┬──────┴─────┬─────┴──┬──┘        (입력을 받는 것들)
           │            │        │
    ═══════╪════════════╪════════╪═══════
           ▼            ▼        ▼
    ┌─────────────────────────────────┐
    │        Input Ports               │     ← 유스케이스 인터페이스
    │  (PlaceOrderUseCase 등)         │
    ├─────────────────────────────────┤
    │                                 │
    │         Domain Model            │     ← 핵심 비즈니스 로직
    │    (Order, Customer, Money)      │        (프레임워크 의존성 없음!)
    │                                 │
    ├─────────────────────────────────┤
    │        Output Ports              │     ← 리포지토리 인터페이스
    │  (OrderRepository 등)           │
    └──────┬──────┬─────────┬─────────┘
           │      │         │
    ═══════╪══════╪═════════╪════════════
           ▼      ▼         ▼
    ┌──────┴──────┴─────────┴─────────┐
    │  JPA  │  Kafka  │  외부 API      │     ← Driven Adapters
    └─────────────────────────────────┘        (외부 시스템 연결)
           외부 세계 (나가는 쪽)

장점: 도메인 모델에 Spring, JPA 같은 프레임워크 의존성이 전혀 없다. 도메인 모델만 따로 테스트할 수 있고, 기술을 바꿔도 도메인은 건드리지 않는다.

5.3 CQRS — 읽기와 쓰기를 분리한다

왜 분리하는가?

쓰기(명령)와 읽기(조회)는 요구사항이 완전히 다르다.

쓰기: 비즈니스 규칙 검증이 중요하다. 도메인 모델을 거쳐야 한다.
읽기: 빠르게 화면에 뿌릴 데이터를 가져오는 게 중요하다. 도메인 모델을 거칠 필요가 없다.

┌─────────────────────────────────────────────────┐
│                    Client                        │
└────────┬────────────────────────────┬────────────┘
         │                            │
    ┌────▼─────┐                 ┌────▼─────┐
    │ Command  │                 │  Query   │
    │  Side    │                 │  Side    │
    ├──────────┤                 ├──────────┤
    │ 도메인    │   이벤트로      │ 읽기     │
    │ 모델을   │ ──동기화──▶     │ 전용     │
    │ 통과     │                 │ 모델     │
    ├──────────┤                 ├──────────┤
    │ 정규화된 │                 │ 비정규화  │
    │ DB       │                 │ DB/캐시  │
    └──────────┘                 └──────────┘

    "주문 생성"                   "내 주문 목록 조회"
    "주문 취소"                   "주문 상세 보기"

Part 6. 실전에서 시작하는 방법

6.1 이벤트 스토밍 (Event Storming) — DDD의 시작점

이벤트 스토밍은 포스트잇을 사용한 워크숍으로, 개발자와 기획자가 함께 도메인을 탐색하는 방법이다.

준비물: 넓은 벽, 여러 색상의 포스트잇, 마커

진행 방법을 음식 배달 서비스로 예시를 들면 이렇다.

1단계: 도메인 이벤트 나열하기 (주황색 포스트잇)

"무엇이 일어났는가?"를 과거형으로 적는다

[고객이 회원가입했다]  [메뉴를 검색했다]  [장바구니에 담았다]
[주문이 접수되었다]  [가게가 주문을 확인했다]  [조리가 시작되었다]
[조리가 완료되었다]  [배달원이 배정되었다]  [배달이 시작되었다]
[배달이 완료되었다]  [고객이 리뷰를 작성했다]  [환불이 처리되었다]

2단계: 커맨드 식별 (파란색 포스트잇)

이벤트를 발생시킨 행위를 적는다

[주문하기] → [주문이 접수되었다]
[주문 확인하기] → [가게가 주문을 확인했다]
[배달원 배정하기] → [배달원이 배정되었다]

3단계: 애그리거트 식별 (노란색 포스트잇)

커맨드를 처리하는 주체를 적는다

           Order             Delivery          Restaurant
            │                  │                  │
    [주문하기]──▶[주문접수됨]    │                  │
            │          [배달원배정]──▶[배달원배정됨]  │
            │                  │      [주문확인]──▶[주문확인됨]

4단계: 바운디드 컨텍스트 도출

관련된 것들을 묶어서 경계를 긋는다

┌── 주문 컨텍스트 ──┐  ┌── 배달 컨텍스트 ──┐  ┌── 가게 컨텍스트 ──┐
│ Order            │  │ Delivery          │  │ Restaurant        │
│ OrderItem        │  │ DeliveryDriver    │  │ Menu              │
│ Payment          │  │ Route             │  │ OperatingHours    │
└──────────────────┘  └───────────────────┘  └───────────────────┘

6.2 점진적 도입 — 한 번에 다 하려고 하지 말 것

DDD를 처음부터 완벽하게 적용하려고 하면 실패한다. 단계적으로 도입한다.

1주차: 유비쿼터스 언어만 도입한다

코드의 클래스명, 메서드명을 비즈니스 용어로 바꾼다
processData() → calculateDeliveryFee()
이것만으로도 코드 가독성이 크게 좋아진다

2~4주차: 값 객체를 도입한다

String email → Email email
int price → Money price
기존 코드를 크게 바꾸지 않아도 적용할 수 있다

1~2개월차: 핵심 엔티티에 비즈니스 로직을 넣는다

가장 중요한 도메인 객체부터 시작한다
Service에 있던 로직을 Entity로 옮긴다

3개월 이후: 바운디드 컨텍스트를 나눈다

시스템의 경계를 식별하고 분리한다

6.3 초보자가 가장 많이 하는 실수 TOP 5

실수 1: 패턴에 집착한다

"이 클래스는 Value Object인가 Entity인가?" 같은 분류에 시간을 쏟는다
중요한 건 분류가 아니라 비즈니스를 이해하는 것이다

실수 2: 모든 곳에 DDD를 적용한다

회원가입 페이지에 Aggregate, Domain Event를 적용할 필요 없다
복잡한 비즈니스 로직이 있는 핵심 도메인에만 적용한다

실수 3: 빈혈 모델을 만든다 (Anemic Domain Model)

Entity에 getter/setter만 있고, 로직은 전부 Service에 있다
이러면 DDD를 적용했다고 볼 수 없다

실수 4: 기술부터 고민한다

"Kafka를 쓸까, RabbitMQ를 쓸까?"보다
"주문 취소 시 재고는 어떻게 되지?"가 먼저이다

실수 5: 애그리거트를 너무 크게 만든다

하나의 애그리거트에 관련된 모든 것을 넣는다
애그리거트는 작게, 다른 애그리거트는 ID로만 참조한다

Part 7. 현실 세계 예시 — 배달 앱 만들기

지금까지 배운 개념을 종합해서, 간단한 배달 앱의 DDD 설계를 해보자.

7.1 서브도메인 분류

Core Domain (핵심):
  - 주문 관리: 주문 생성, 상태 관리, 취소/환불
  - 배달원 매칭: 최적의 배달원 배정 알고리즘

Supporting Subdomain (지원):
  - 가게 관리: 가게 등록, 메뉴 관리
  - 리뷰: 평점, 리뷰 작성

Generic Subdomain (일반):
  - 인증: 로그인/회원가입 → Firebase Auth 사용
  - 결제: PG사 연동 → 토스페이먼츠 사용
  - 알림: 푸시 알림 → FCM 사용

7.2 바운디드 컨텍스트와 도메인 모델

// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
// 주문 컨텍스트 (Core Domain — DDD 적극 적용)
// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

// 값 객체
public record OrderId(String value) {}
public record Money(int amount) {
    public Money add(Money other) { return new Money(this.amount + other.amount); }
    public Money multiply(int qty) { return new Money(this.amount * qty); }
}
public record DeliveryAddress(String city, String detail, double lat, double lng) {}

// 엔티티 + 애그리거트 루트
public class Order {
    private final OrderId id;
    private final String customerId;
    private final String restaurantId;
    private final List<OrderItem> items;
    private final DeliveryAddress deliveryAddress;
    private OrderStatus status;
    private Money totalPrice;

    // 주문 생성
    public static Order create(String customerId, String restaurantId,
                               List<OrderItem> items, DeliveryAddress address) {
        if (items.isEmpty()) {
            throw new EmptyOrderException("주문 항목이 비어 있습니다");
        }
        Order order = new Order(OrderId.generate(), customerId, restaurantId,
                                items, address, OrderStatus.CREATED);
        order.calculateTotal();
        return order;
    }

    // 주문 접수
    public void accept() {
        if (this.status != OrderStatus.CREATED) {
            throw new InvalidOrderStateException("접수 대기 상태가 아닙니다");
        }
        this.status = OrderStatus.ACCEPTED;
    }

    // 주문 취소
    public void cancel(String reason) {
        if (this.status.isAfter(OrderStatus.PREPARING)) {
            throw new OrderCannotBeCancelledException("조리 시작 후에는 취소할 수 없습니다");
        }
        this.status = OrderStatus.CANCELLED;
    }

    // 환불 금액 계산 — 비즈니스 규칙이 여기에 있다
    public Money calculateRefundAmount() {
        return switch (this.status) {
            case CREATED, ACCEPTED -> this.totalPrice;                         // 전액 환불
            case PREPARING -> new Money((int)(this.totalPrice.amount() * 0.9)); // 90% 환불
            default -> throw new RefundNotAvailableException();
        };
    }

    private void calculateTotal() {
        this.totalPrice = items.stream()
            .map(item -> item.getPrice().multiply(item.getQuantity()))
            .reduce(Money.ZERO, Money::add);
    }
}

// 도메인 이벤트
public record OrderAcceptedEvent(OrderId orderId, String restaurantId) {}
public record OrderCancelledEvent(OrderId orderId, Money refundAmount) {}

// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
// 가게 컨텍스트 (Supporting — 적절한 수준의 설계)
// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

// 여기서는 DDD를 적극적으로 쓰지 않아도 된다
// 간단한 CRUD에 가까우므로 일반적인 구조로 충분하다
public class Restaurant {
    private String id;
    private String name;
    private List<MenuItem> menu;
    private OperatingHours operatingHours;

    public boolean isOpen() {
        return operatingHours.includes(LocalTime.now());
    }
}

7.3 컨텍스트 간 통신

┌── 주문 컨텍스트 ──┐          ┌── 배달 컨텍스트 ──┐
│                   │          │                   │
│  Order.accept()   │          │                   │
│       │           │          │                   │
│  OrderAccepted  ──┼── 이벤트 ──▶ DeliveryService │
│    Event          │          │   .assignDriver() │
│                   │          │                   │
└───────────────────┘          └───────────────────┘

┌── 주문 컨텍스트 ──┐          ┌── 결제 컨텍스트 ──┐
│                   │          │                   │
│  Order.cancel()   │          │                   │
│       │           │          │                   │
│  OrderCancelled ──┼── 이벤트 ──▶ PaymentService  │
│    Event          │          │   .refund()       │
│                   │          │                   │
└───────────────────┘          └───────────────────┘

각 컨텍스트는 이벤트를 통해 느슨하게 연결된다. 주문 컨텍스트는 배달이 어떻게 이루어지는지 모르고, 배달 컨텍스트는 주문이 어떻게 만들어지는지 모른다. 각자 자기 일에만 집중한다.

Part 8. 자주 묻는 질문 (FAQ)

Q: DDD를 배우려면 얼마나 걸리나요?
기본 개념은 1

~~2주면 이해할 수 있다. 하지만 실전에서 능숙하게 적용하려면 6개월~~

1년의 경험이 필요하다. 핵심은 "도메인을 이해하려는 태도"이지 "패턴을 외우는 것"이 아니다.

Q: DDD와 마이크로서비스는 같은 건가요?
아니다. DDD는 설계 방법론이고, 마이크로서비스는 아키텍처 스타일이다. 다만 DDD의 바운디드 컨텍스트가 마이크로서비스의 경계를 정하는 데 매우 유용하다.

Q: 작은 프로젝트에서도 DDD를 써야 하나요?
전부 적용할 필요는 없다. 유비쿼터스 언어, 값 객체, 풍부한 도메인 모델 정도만 적용해도 코드 품질이 크게 좋아진다. 이것들은 프로젝트 규모와 관계없이 유용하다.

Q: DDD를 쓰면 코드가 더 많아지지 않나요?
맞다. 초기 코드량은 늘어난다. 하지만 시간이 지날수록 변경이 쉽고, 버그가 줄어들며, 새 팀원의 온보딩이 빨라진다. 장기적으로는 총 비용이 줄어든다.

Q: 기존 프로젝트에 DDD를 적용할 수 있나요?
가능하다. "Strangler Fig Pattern"을 사용하여 기존 시스템을 감싸면서 점진적으로 DDD를 적용할 수 있다. 한꺼번에 바꾸려 하지 말고, 가장 복잡하고 자주 변경되는 부분부터 시작한다.

Q: Spring/JPA 없이도 DDD를 할 수 있나요?
당연하다. DDD는 특정 프레임워크에 종속되지 않는다. Python, TypeScript, Go, 어떤 언어/프레임워크에서도 적용할 수 있다. 오히려 프레임워크 없이 순수한 도메인 모델을 만드는 것이 DDD의 이상에 더 가깝다.

마무리: DDD의 본질

DDD의 본질은 패턴이나 아키텍처가 아니다. 본질은 이것이다.

"소프트웨어가 해결하려는 문제를 깊이 이해하고, 그 이해를 코드에 그대로 반영하는 것"

기술은 변한다. Spring이 사라질 수도, JPA 대신 다른 것이 나올 수도 있다. 하지만 비즈니스를 코드로 표현하는 능력은 어떤 기술 스택에서든 가치 있다.

DDD를 처음 배울 때는 어렵게 느껴질 수 있다. 하지만 핵심은 단순하다.

비즈니스를 이해하라.
비즈니스 용어를 코드에 그대로 사용하라.
비즈니스 규칙을 도메인 객체에 넣어라.
경계를 나누어 복잡성을 관리하라.

이 네 가지만 기억하면 DDD의 80%를 이해한 것이다.

Get Shit Done (GSD) 완전 가이드

은둔한량 — Thu, 26 Mar 2026 09:56:58 +0900

GSD는 Claude Code 위에서 동작하는 프로젝트 관리 + 자동 실행 워크플로우 시스템입니다.

GSD란 무엇인가?
설치하기
핵심 개념 이해하기
프로젝트 시작하기
전체 워크플로우 흐름
명령어 상세 가이드
설정 및 커스터마이징
실전 시나리오별 사용법
파일 구조 이해하기
모델 프로필 시스템
Git 통합
트러블슈팅 & FAQ
전체 명령어 요약표

1. GSD란 무엇인가?

GitHub 저장소: https://github.com/glittercowboy/get-shit-done

배경

Claude Code는 강력한 AI 코딩 도구이지만, 복잡한 프로젝트를 진행할 때는 몇 가지 한계가 있습니다:

대화 컨텍스트가 길어지면 앞부분을 잊어버림
여러 단계의 작업을 체계적으로 추적하기 어려움
작업 중간에 세션이 끊기면 맥락을 잃음
큰 작업을 어떻게 나눌지 판단이 어려움

GSD(Get Shit Done)는 이 문제들을 해결합니다.

GSD가 하는 일

GSD는 마치 프로젝트 매니저처럼 동작합니다:

프로젝트를 분석하고 요구사항을 정리합니다
작업을 마일스톤 → 페이즈 → 플랜 → 태스크 단위로 쪼갭니다
각 단계를 전문 AI 에이전트에게 위임하여 실행합니다
완료된 작업을 검증합니다
모든 진행상황을 .planning/ 폴더에 파일로 기록하여 세션이 끊겨도 이어갈 수 있습니다

비유로 이해하기

일반 Claude Code 사용:
  "이 기능 만들어줘" → Claude가 직접 코딩 → 끝

GSD 사용:
  "이 기능 만들어줘"
  → PM(GSD)이 요구사항 분석
  → 리서처가 기술 조사
  → 플래너가 실행 계획 작성
  → 체커가 계획 검토
  → 실행자가 코드 작성
  → 검증자가 결과 확인
  → 완료 보고

2. 설치하기

2.1. 사전 요구사항

GSD를 설치하기 전에 다음이 필요합니다:

요구사항	설명
Claude Code	Anthropic의 공식 CLI 도구 (터미널에서 `claude` 명령어로 실행)
Node.js	v18 이상 권장 (`node -v`로 확인)
npm / npx	Node.js와 함께 설치됨 (`npx -v`로 확인)
Git	버전 관리 (`git --version`으로 확인)

Claude Code가 아직 없다면?
npm install -g @anthropic-ai/claude-code
설치 후 claude 명령어로 실행할 수 있습니다.

2.2. GSD 설치

방법 1: 글로벌 설치 (추천)

모든 프로젝트에서 GSD를 사용하고 싶다면:

npx -y get-shit-done-cc@latest --claude --global

이 명령은 ~/.claude/ 폴더에 GSD를 설치합니다. 어떤 프로젝트에서든 /gsd:* 명령을 사용할 수 있습니다.

방법 2: 로컬(프로젝트별) 설치

특정 프로젝트에서만 GSD를 사용하고 싶다면:

npx -y get-shit-done-cc@latest --claude --local

현재 디렉토리의 .claude/ 폴더에 설치됩니다.

방법 3: npm 글로벌 설치

npm install -g get-shit-done-cc

2.3. 설치 확인

설치가 완료되면 Claude Code를 실행하고 다음을 입력해봅니다:

/gsd:help

명령어 목록이 표시되면 설치 성공입니다.

2.4. 설치되는 것들

설치 시 다음 파일/폴더가 생성됩니다:

~/.claude/                         ← (글로벌 설치 기준)
├── get-shit-done/                 ← GSD 코어 파일
│   ├── bin/                       ← 실행 스크립트 & 라이브러리
│   ├── commands/                  ← CLI 명령어 정의
│   ├── workflows/                 ← 워크플로우 정의 (60+개)
│   ├── references/                ← 참조 문서 (17개)
│   ├── templates/                 ← 프로젝트 템플릿 (26개)
│   └── VERSION                    ← 현재 버전 파일
│
├── agents/                        ← GSD 전문 에이전트 (18개)
│   ├── gsd-planner.md
│   ├── gsd-executor.md
│   ├── gsd-verifier.md
│   └── ... (15개 더)
│
├── hooks/                         ← 자동 실행 훅
│   ├── gsd-check-update.js        ← 세션 시작 시 업데이트 확인
│   ├── gsd-context-monitor.js     ← 컨텍스트 사용량 모니터링
│   ├── gsd-prompt-guard.js        ← 프롬프트 가드
│   └── gsd-statusline.js          ← 상태 표시줄
│
├── gsd-file-manifest.json         ← 파일 무결성 검증용 매니페스트
└── settings.json                  ← (기존 파일에 훅 설정 추가)

2.5. 훅(Hook) 자동 설정

설치 시 ~/.claude/settings.json에 다음 훅들이 자동으로 등록됩니다:

훅	트리거 시점	역할
`gsd-check-update.js`	세션 시작	새 버전이 있는지 확인
`gsd-context-monitor.js`	도구 사용 후	토큰 사용량 추적, 컨텍스트 부족 경고
`gsd-prompt-guard.js`	파일 쓰기 전	안전성 검증
`gsd-statusline.js`	상시	현재 상태 표시

2.6. 업데이트

GSD를 최신 버전으로 업데이트하려면 Claude Code 안에서:

/gsd:update

또는 터미널에서 직접:

npx -y get-shit-done-cc@latest --claude --global

업데이트 시 보존되는 것들:

사용자가 만든 커스텀 명령어/에이전트 (gsd- 접두사가 아닌 것)

커스텀 훅

CLAUDE.md 파일

로컬에서 수정한 GSD 파일 (gsd-local-patches/에 백업됨)

2.7. 다른 AI CLI에서도 사용 가능

GSD는 Claude Code 외에도 여러 AI CLI 도구를 지원합니다:

런타임	설치 플래그	설정 디렉토리
Claude Code	`--claude`	`~/.claude/`
OpenCode	`--opencode`	`~/.config/opencode/`
Gemini CLI	`--gemini`	`~/.gemini/`
Codex	`--codex`	`$CODEX_HOME/`

환경변수로 커스텀 경로도 지정 가능합니다:

CLAUDE_CONFIG_DIR=/custom/path npx -y get-shit-done-cc@latest --claude --global

3. 핵심 개념 이해하기

계층 구조

GSD는 작업을 4단계 계층으로 관리합니다:

프로젝트 (Project)
  └── 마일스톤 (Milestone) — v1.0, v2.0 같은 큰 릴리즈 단위
        └── 페이즈 (Phase) — 마일스톤을 이루는 각 단계 (Phase 1, 2, 3...)
              └── 플랜 (Plan) — 페이즈 안의 구체적 실행 계획
                    └── 태스크 (Task) — 플랜 안의 개별 작업 항목

예시:

프로젝트: 온라인 쇼핑몰
  └── 마일스톤 v1.0: MVP 출시
        ├── Phase 1: 사용자 인증 시스템
        │     ├── Plan 1: 데이터베이스 스키마 설계
        │     └── Plan 2: 로그인/회원가입 API 구현
        ├── Phase 2: 상품 관리 기능
        │     ├── Plan 1: 상품 CRUD API
        │     └── Plan 2: 상품 이미지 업로드
        └── Phase 3: 주문/결제 시스템
              └── ...

주요 문서 파일들

GSD는 .planning/ 폴더에 여러 문서를 생성합니다:

파일	역할
`PROJECT.md`	프로젝트 전체 개요, 목표, 제약조건
`REQUIREMENTS.md`	상세 요구사항 목록
`ROADMAP.md`	마일스톤별 페이즈 목록과 진행상태
`STATE.md`	현재 진행 상태 추적 (어디까지 했는지)
`CONTEXT.md`	페이즈별 설계 결정사항 기록
`PLAN.md`	각 페이즈의 구체적 실행 계획
`SUMMARY.md`	실행 완료 후 결과 요약
`UAT.md`	사용자 수용 테스트 체크리스트
`config.json`	GSD 설정값

전문 에이전트들

GSD는 작업 종류에 따라 전문화된 AI 에이전트를 사용합니다:

에이전트	역할	비유
gsd-project-researcher	프로젝트 초기 조사	시장조사 담당자
gsd-phase-researcher	페이즈별 기술 조사	기술 리서처
gsd-planner	실행 계획 작성	프로젝트 매니저
gsd-plan-checker	계획 품질 검토	QA 리뷰어
gsd-executor	실제 코드 작성/실행	개발자
gsd-verifier	완료된 작업 검증	QA 테스터
gsd-debugger	버그 조사 및 수정	디버거
gsd-codebase-mapper	기존 코드 분석	코드 아키텍트

4. 프로젝트 시작하기

4.1. 새 프로젝트 초기화

기존 코드베이스에서 GSD를 처음 사용한다면:

/gsd:new-project

이 명령을 실행하면 GSD가 다음을 수행합니다:

프로젝트에 대해 질문합니다 (목표, 범위, 제약조건 등)
4개의 리서처 에이전트가 병렬로 코드베이스를 분석합니다
분석 결과를 종합하여 PROJECT.md를 생성합니다
요구사항을 정리하여 REQUIREMENTS.md를 생성합니다
로드맵을 만들어 ROADMAP.md를 생성합니다
.planning/ 폴더 전체 구조를 세팅합니다

결과물:

.planning/
  ├── config.json          ← GSD 설정
  ├── PROJECT.md           ← 프로젝트 개요
  ├── REQUIREMENTS.md      ← 요구사항
  ├── ROADMAP.md           ← 로드맵 (페이즈 목록)
  ├── STATE.md             ← 진행 상태
  └── research/            ← 리서치 결과물
        ├── ARCHITECTURE.md
        ├── FEATURES.md
        ├── PITFALLS.md
        ├── STACK.md
        └── SUMMARY.md

4.2. 기존 코드베이스 분석만 하기

프로젝트를 시작하지 않고 코드 구조만 파악하고 싶다면:

/gsd:map-codebase

4개의 전문 에이전트가 병렬로 코드를 분석하여 다음을 생성합니다:

기술 스택 분석 (stack.md)
아키텍처 분석 (architecture.md)
코드 품질 분석 (concerns.md)
코딩 컨벤션 분석 (conventions.md)

5. 전체 워크플로우 흐름

표준 워크플로우 (처음부터 끝까지)

┌─────────────────────────────────────────────────────┐
│  1. /gsd:new-project        프로젝트 초기화           │
│         ↓                                            │
│  2. /gsd:discuss-phase 1    Phase 1 설계 논의         │
│         ↓                                            │
│  3. /gsd:plan-phase 1       Phase 1 실행 계획 작성    │
│         ↓                                            │
│  4. /gsd:execute-phase 1    Phase 1 실행 (코드 작성)  │
│         ↓                                            │
│  5. /gsd:verify-work 1      Phase 1 결과 검증         │
│         ↓                                            │
│  6. (Phase 2, 3... 반복)                             │
│         ↓                                            │ 
│  7. /gsd:complete-milestone  마일스톤 완료           │
└─────────────────────────────────────────────────────┘

간단한 흐름 (자동 라우팅)

매번 다음 단계를 기억할 필요 없이:

/gsd:progress    ← 현재 상태를 보여주고, 다음에 할 일을 알려줌
/gsd:next        ← 자동으로 다음 단계를 실행

자율 실행 (완전 자동)

모든 페이즈를 한번에 자동 실행하고 싶다면:

/gsd:autonomous

이 명령은 남은 모든 페이즈에 대해 discuss → plan → execute를 자동으로 반복합니다.

6. 명령어 상세 가이드

6.1. `/gsd:new-project` — 프로젝트 초기화

언제 사용하나요?

GSD를 처음 사용할 때
새로운 프로젝트를 시작할 때

동작 과정:

프로젝트에 대해 질문 (목표, 기술 스택, 제약조건)
4개 리서처가 병렬로 조사 (기술, 아키텍처, 주의사항, 기능)
리서치 결과 종합
PROJECT.md, REQUIREMENTS.md, ROADMAP.md 생성

팁:

질문에 최대한 구체적으로 답변하면 더 좋은 계획이 나옵니다
이미 .planning/ 폴더가 있으면 기존 프로젝트로 인식합니다

6.2. `/gsd:discuss-phase [N]` — 페이즈 설계 논의

언제 사용하나요?

페이즈를 시작하기 전에 설계 방향을 정하고 싶을 때
"어떻게 구현할지" 아직 결정하지 못한 부분이 있을 때

사용법:

/gsd:discuss-phase 1           ← Phase 1에 대해 논의
/gsd:discuss-phase 1 --auto    ← 질문 없이 Claude가 알아서 결정

동작 과정:

해당 페이즈의 목표와 요구사항을 확인
"회색 영역" (아직 결정되지 않은 부분)을 찾아냄
각 영역에 대해 질문하고 사용자의 결정을 기록
모든 결정사항을 CONTEXT.md에 저장

예시 질문들:

"인증은 JWT와 세션 중 어느 것을 사용할까요?"
"파일 업로드는 로컬 저장소와 S3 중 어디를 사용할까요?"
"API 응답 형식은 어떻게 할까요?"

--auto 플래그:
질문에 답하기 귀찮을 때 사용합니다. Claude가 추천 옵션으로 자동 결정합니다.

6.3. `/gsd:plan-phase [N]` — 실행 계획 작성

언제 사용하나요?

페이즈 설계가 확정된 후 (discuss 이후)
구체적인 실행 계획이 필요할 때

사용법:

/gsd:plan-phase 1                ← Phase 1 계획 작성
/gsd:plan-phase 1 --research     ← 리서치를 먼저 한 후 계획 작성
/gsd:plan-phase 1 --skip-verify  ← 계획 검증 건너뛰기
/gsd:plan-phase 1 --gaps         ← UAT에서 발견된 갭만 보완
/gsd:plan-phase 1 --prd file.md  ← PRD 파일로부터 직접 계획 작성

동작 과정:

리서치 (선택) — 기술적 조사가 필요하면 리서처 에이전트가 조사
계획 작성 — 플래너 에이전트가 PLAN.md 파일 생성
계획 검증 — 체커 에이전트가 계획의 완성도를 검토
수정 루프 — 문제가 있으면 최대 3번까지 수정

결과물 예시: .planning/phases/1/PLAN-1.md

---
phase: 1
plan: 1
title: "데이터베이스 스키마 설계"
wave: 1
depends_on: []
files_modified: ["migrations/001_create_users.php"]
---

## Goal
사용자 테이블과 인증 관련 스키마를 설계한다.

## Tasks
- [ ] users 테이블 마이그레이션 생성
- [ ] roles 테이블 마이그레이션 생성
- [ ] 시드 데이터 작성

## Verification
- 마이그레이션이 정상 실행되는지 확인
- 롤백이 정상 동작하는지 확인

6.4. `/gsd:execute-phase [N]` — 페이즈 실행

언제 사용하나요?

계획(PLAN.md)이 완성된 후 실제 코드를 작성할 때

사용법:

/gsd:execute-phase 1               ← Phase 1의 모든 플랜 실행
/gsd:execute-phase 1 --interactive ← 메인 대화에서 직접 실행 (서브에이전트 없이)
/gsd:execute-phase 1 --wave 2     ← 특정 웨이브만 실행
/gsd:execute-phase 1 --auto       ← 확인 없이 자동 진행

동작 과정:

PLAN.md 파일들을 발견하고 웨이브별로 그룹화
같은 웨이브의 플랜들은 병렬 실행 (독립적인 작업)
각 플랜마다 gsd-executor 에이전트가 코드를 작성
각 태스크 완료 시 atomic commit (개별 커밋)
모든 플랜 완료 후 결과 검증
SUMMARY.md 생성

웨이브(Wave) 시스템:

Wave 1: [Plan A, Plan B]  ← 동시에 실행 (서로 의존성 없음)
         ↓
Wave 2: [Plan C]           ← Wave 1 완료 후 실행 (Plan A, B에 의존)
         ↓
Wave 3: [Plan D, Plan E]  ← 동시에 실행

--interactive 플래그:
서브에이전트 대신 현재 대화에서 직접 실행합니다. 작은 페이즈나 실행 과정을 직접 보고 싶을 때 유용합니다.

6.5. `/gsd:verify-work [N]` — 작업 검증 (UAT)

언제 사용하나요?

페이즈 실행 완료 후 결과를 테스트할 때

사용법:

/gsd:verify-work 1    ← Phase 1 결과를 검증

동작 과정:

SUMMARY.md에서 테스트 항목을 추출
UAT.md 파일 생성 (테스트 체크리스트)
테스트를 하나씩 보여주며 결과를 물어봄
통과/실패/차단 등으로 결과 기록
실패한 항목은 자동으로 수정 계획 수립

대화 예시:

GSD: "테스트 1: 로그인 페이지가 정상적으로 표시되는지 확인하세요."
     "브라우저에서 /login에 접속하면 로그인 폼이 보이나요?"

사용자: "네, 잘 보입니다"

GSD: ✅ 통과! 다음 테스트...
     "테스트 2: 잘못된 비밀번호로 로그인 시 에러 메시지가 표시되나요?"

사용자: "에러 메시지가 안 나옵니다"

GSD: ❌ 이슈 발견! 수정 계획을 작성합니다...

6.6. `/gsd:quick` — 빠른 작업 실행

언제 사용하나요?

새 프로젝트가 아닌 작은 단일 작업을 할 때
전체 페이즈 워크플로우까지는 필요 없는 경우

사용법:

/gsd:quick "로그인 페이지에 비밀번호 재설정 링크 추가"
/gsd:quick "API 응답에 페이지네이션 추가" --full
/gsd:quick "검색 기능 개선" --discuss --research

플래그 옵션:
| 플래그 | 효과 |
|--------|------|
| (없음) | 계획 → 실행 |
| --discuss | 논의 → 계획 → 실행 |
| --research | 리서치 → 계획 → 실행 |
| --full | 계획 → 검증 → 실행 → 검증 |
| --discuss --research --full | 전체 파이프라인 |

quick vs fast vs 일반 실행:

/gsd:fast     → 3개 이하 파일 수정, 1분 이내 작업 (계획 없음)
/gsd:quick    → 중간 규모 작업 (간단한 계획 + 실행)
/gsd:plan-phase + /gsd:execute-phase → 큰 작업 (전체 워크플로우)

6.7. `/gsd:fast` — 초간단 즉시 실행

언제 사용하나요?

아주 사소한 수정 (오타 수정, 변수명 변경 등)
3개 이하 파일만 수정하는 작업
계획이 필요 없을 만큼 명확한 작업

사용법:

/gsd:fast "버튼 색상을 파란색에서 초록색으로 변경"
/gsd:fast "console.log 디버그 코드 제거"

특징:

서브에이전트를 사용하지 않음 (현재 대화에서 바로 실행)
PLAN.md를 생성하지 않음
리서치/검증 과정 없음
가장 빠르고 가벼운 실행 방식

6.8. `/gsd:do` — 자연어 라우터

언제 사용하나요?

어떤 GSD 명령어를 써야 할지 모를 때
자연스러운 문장으로 작업을 설명하고 싶을 때

사용법:

/gsd:do "로그인이 안 되는 버그 수정해줘"         → /gsd:debug로 라우팅
/gsd:do "새 프로젝트 시작하자"                    → /gsd:new-project로 라우팅
/gsd:do "사용자 프로필 페이지 만들어줘"           → /gsd:quick 또는 /gsd:add-phase로 라우팅
/gsd:do "지금 어디까지 했지?"                     → /gsd:progress로 라우팅

라우팅 규칙:
| 키워드 | 라우팅 대상 |
|--------|------------|
| 셋업, 시작, 초기화 | /gsd:new-project |
| 버그, 에러, 크래시 | /gsd:debug |
| 조사, 리서치 | /gsd:research-phase |
| 논의, 브레인스토밍 | /gsd:discuss-phase |
| 복잡한 기능 | /gsd:add-phase |
| 작은 작업 | /gsd:quick |
| 리뷰, 품질 | /gsd:verify-work |
| 상태, 진행 | /gsd:progress |
| 테스트 | /gsd:add-tests |
| 완료, 배포 | /gsd:complete-milestone |

6.9. `/gsd:progress` — 진행 상태 확인

언제 사용하나요?

프로젝트 진행 상태를 확인하고 싶을 때
다음에 뭘 해야 할지 모를 때

사용법:

/gsd:progress

표시 정보:

현재 마일스톤/페이즈 진행률
각 페이즈의 상태 (계획됨/실행중/완료)
미결 이슈나 검증 부채
다음 행동 추천 (자동으로 적절한 명령어를 제안)

6.10. `/gsd:debug` — 체계적 디버깅

언제 사용하나요?

버그를 조사하고 수정할 때
에러의 근본 원인을 찾고 싶을 때

사용법:

/gsd:debug "로그인 시 500 에러 발생"
/gsd:debug "파일 업로드 후 썸네일이 생성되지 않음"

특징:

과학적 방법론 (가설 → 검증 → 결론) 사용
디버그 상태가 파일로 저장되어 세션이 끊겨도 이어갈 수 있음
체크포인트 관리

6.11. 페이즈 관리 명령어

/gsd:add-phase           ← 마일스톤 끝에 새 페이즈 추가
/gsd:insert-phase        ← 기존 페이즈 사이에 긴급 작업 삽입 (소수점 번호, 예: 2.1)
/gsd:remove-phase        ← 미래 페이즈 삭제 및 번호 재정렬
/gsd:list-phase-assumptions 1  ← Phase 1에 대한 가정(assumption) 목록 확인

6.12. 세션 관리 명령어

/gsd:pause-work      ← 작업 중단 시 컨텍스트를 파일로 저장
/gsd:resume-work     ← 이전 세션의 컨텍스트를 복원하여 이어서 작업
/gsd:thread          ← 영구 컨텍스트 스레드 관리 (크로스 세션)

6.13. 리뷰 & 검증 명령어

/gsd:validate-phase 1      ← Phase 1의 검증 갭을 찾아서 채움
/gsd:audit-milestone       ← 마일스톤 전체를 원래 목표 대비 감사
/gsd:audit-uat             ← 모든 페이즈의 미완료 UAT 항목 확인
/gsd:review                ← 외부 AI 도구로 교차 리뷰 요청
/gsd:add-tests 1           ← Phase 1에 대한 테스트 코드 자동 생성

6.14. Git & 배포 명령어

/gsd:ship             ← PR 생성 → 리뷰 실행 → 머지 준비
/gsd:pr-branch        ← .planning/ 커밋을 제외한 깨끗한 PR 브랜치 생성

6.15. 아이디어 & 할일 관리

/gsd:add-todo         ← 대화 중 떠오른 할일을 기록
/gsd:check-todos      ← 기록된 할일 목록 확인 및 선택
/gsd:note             ← 간단한 메모 (추가/목록/승격)
/gsd:plant-seed       ← 미래에 트리거될 아이디어 심기
/gsd:add-backlog      ← 백로그(999.x)에 아이디어 추가
/gsd:review-backlog   ← 백로그 항목을 활성 마일스톤으로 승격

7. 설정 및 커스터마이징

7.1. 설정 변경하기

/gsd:settings

대화형으로 설정을 변경할 수 있습니다.

7.2. 주요 설정 항목

워크플로우 토글

설정	기본값	설명
`research`	`true`	페이즈 계획 전 리서치 수행 여부
`plan_check`	`true`	계획 작성 후 검증 수행 여부
`verifier`	`true`	실행 후 검증 수행 여부
`auto_advance`	`false`	단계 완료 시 자동으로 다음 단계 진행
`nyquist_validation`	`true`	작업 샘플링 검증

모드

설정	옵션	설명
`mode`	`interactive` / `yolo`	interactive = 확인 요청, yolo = 자동 진행
`discuss_mode`	`discuss`	페이즈 논의 방식

병렬 처리

설정	기본값	설명
`parallelization.enabled`	`true`	병렬 실행 활성화
`max_concurrent_agents`	`3`	동시 실행 에이전트 수
`plan_level`	`true`	플랜 단위 병렬 실행
`task_level`	`false`	태스크 단위 병렬 실행

게이트 (확인 포인트)

게이트는 중요한 시점에서 사용자 확인을 요청하는 설정입니다:

게이트	기본값	설명
`confirm_project`	`true`	프로젝트 초기화 전 확인
`confirm_phases`	`true`	페이즈 목록 확인
`confirm_roadmap`	`true`	로드맵 확인
`confirm_plan`	`true`	실행 계획 확인
`execute_next_plan`	`true`	다음 플랜 실행 전 확인

게이트를 false로 설정하면 확인 없이 자동 진행합니다.

7.3. 설정 파일 위치

프로젝트별 설정: .planning/config.json
글로벌 기본값:   ~/.gsd/defaults.json (선택사항)

8. 실전 시나리오별 사용법

시나리오 1: 새 기능 하나 추가 (소규모)

# 방법 A: 가장 간단하게
/gsd:fast "사용자 목록에 검색 필터 추가"

# 방법 B: 조금 더 체계적으로
/gsd:quick "사용자 목록에 검색 필터 추가"

# 방법 C: 리서치까지 포함
/gsd:quick "사용자 목록에 검색 필터 추가" --research

시나리오 2: 중간 규모 기능 개발

# 1. 논의하기
/gsd:discuss-phase 3

# 2. 계획 세우기
/gsd:plan-phase 3

# 3. 실행하기
/gsd:execute-phase 3

# 4. 검증하기
/gsd:verify-work 3

시나리오 3: 버그 수정

# 체계적 디버깅
/gsd:debug "결제 완료 후 주문 상태가 업데이트되지 않음"

# 또는 간단한 버그라면
/gsd:fast "null 체크 누락으로 인한 500 에러 수정"

시나리오 4: 프로젝트 처음부터 끝까지

# 1. 프로젝트 초기화
/gsd:new-project

# 2. 자동으로 모든 페이즈 실행
/gsd:autonomous

# 또는 단계별로 진행하며 다음 행동을 추천받기
/gsd:next

시나리오 5: 세션이 끊겼을 때

# 이전 작업 컨텍스트 복원
/gsd:resume-work

# 또는 현재 상태 확인 후 이어가기
/gsd:progress

시나리오 6: 작업 중 아이디어가 떠올랐을 때

# 간단한 메모
/gsd:note "나중에 캐싱 레이어 추가하면 좋겠다"

# 할일로 등록
/gsd:add-todo "API 응답 속도 개선 필요"

# 백로그에 추가
/gsd:add-backlog "다국어 지원 기능"

시나리오 7: PR 만들기

# .planning/ 파일을 제외한 깨끗한 PR 브랜치 생성
/gsd:pr-branch

# PR 생성 + 리뷰 + 머지 준비까지
/gsd:ship

9. 파일 구조 이해하기

`.planning/` 디렉토리 전체 구조

프로젝트가 진행되면 다음과 같은 구조가 만들어집니다:

.planning/
├── config.json                  ← GSD 설정
├── PROJECT.md                   ← 프로젝트 개요
├── REQUIREMENTS.md              ← 요구사항 정의
├── ROADMAP.md                   ← 마일스톤/페이즈 로드맵
├── STATE.md                     ← 현재 진행 상태
│
├── research/                    ← 프로젝트 초기 리서치 결과
│   ├── ARCHITECTURE.md
│   ├── FEATURES.md
│   ├── PITFALLS.md
│   ├── STACK.md
│   └── SUMMARY.md
│
├── codebase/                    ← 코드베이스 분석 결과 (map-codebase)
│   ├── architecture.md
│   ├── conventions.md
│   ├── concerns.md
│   └── stack.md
│
├── phases/                      ← 페이즈별 작업 디렉토리
│   ├── 1/                       ← Phase 1
│   │   ├── CONTEXT.md           ← 설계 결정사항
│   │   ├── RESEARCH.md          ← 페이즈별 리서치
│   │   ├── PLAN-1.md            ← 실행 계획 1
│   │   ├── PLAN-2.md            ← 실행 계획 2
│   │   ├── SUMMARY-1.md         ← 실행 결과 1
│   │   ├── SUMMARY-2.md         ← 실행 결과 2
│   │   └── UAT.md               ← 테스트 체크리스트
│   ├── 2/                       ← Phase 2
│   │   └── ...
│   └── 3/                       ← Phase 3
│       └── ...
│
├── quick-tasks/                 ← quick 명령으로 실행된 작업들
│   └── QT-001/
│       ├── PLAN.md
│       └── SUMMARY.md
│
└── todos/                       ← 할일 목록
    └── ...

주요 파일 설명

`STATE.md` — 진행 상태 추적

이 파일은 GSD가 자동으로 관리합니다:

## Current State
- **Milestone:** v1.0
- **Active Phase:** 2
- **Status:** executing

## Phase Progress
| Phase | Status | Plans | Completed |
|-------|--------|-------|-----------|
| 1 | ✅ complete | 3/3 | 3/3 |
| 2 |   executing | 2/2 | 1/2 |
| 3 | ⏳ planned | 0/0 | 0/0 |

## Decisions Log
- Phase 1: JWT 인증 방식 선택 (CONTEXT.md 참조)

`ROADMAP.md` — 로드맵

## Milestone: v1.0

### Phase 1: 사용자 인증 ✅
Goal: 로그인/회원가입 시스템 구현

### Phase 2: 상품 관리  
Goal: 상품 CRUD 및 이미지 업로드

### Phase 3: 주문 시스템 ⏳
Goal: 장바구니, 주문, 결제 연동

10. 모델 프로필 시스템

GSD는 각 에이전트에 다른 Claude 모델을 할당할 수 있습니다.

프로필 종류

프로필	설명	비용	추천 상황
quality	모든 에이전트에 Opus 사용	높음	중요한 프로덕션 작업
balanced	계획=Opus, 실행=Sonnet	중간	기본값, 대부분의 경우 적합
budget	작성=Sonnet, 검증=Haiku	낮음	비용 절약이 중요할 때
inherit	현재 세션 모델 사용	가변	외부 프로바이더(OpenRouter 등) 사용 시

에이전트별 모델 배정

에이전트	quality	balanced	budget
planner (계획)	Opus	Opus	Sonnet
roadmapper (로드맵)	Opus	Sonnet	Sonnet
executor (실행)	Opus	Sonnet	Sonnet
debugger (디버깅)	Opus	Sonnet	Sonnet
verifier (검증)	Sonnet	Sonnet	Haiku
codebase-mapper (분석)	Sonnet	Haiku	Haiku

프로필 변경

/gsd:set-profile quality    ← 최고 품질로 변경
/gsd:set-profile budget     ← 비용 절약 모드
/gsd:settings               ← 대화형으로 변경

11. Git 통합

브랜칭 전략

GSD는 3가지 Git 브랜칭 전략을 지원합니다:

`none` (기본값)

현재 브랜치에서 모든 작업 수행
별도의 브랜치를 생성하지 않음
가장 단순한 방식

`phase`

페이즈마다 새 브랜치 생성
브랜치명 템플릿: gsd/phase-{phase}-{slug}
예: gsd/phase-1-user-auth

`milestone`

마일스톤마다 새 브랜치 생성
브랜치명 템플릿: gsd/{milestone}-{slug}
예: gsd/v1.0-mvp-launch

커밋 관리

각 태스크 완료 시 atomic commit 생성
.planning/ 폴더의 변경도 별도 커밋
/gsd:pr-branch로 .planning/ 커밋을 제외한 깨끗한 브랜치 생성 가능

`.planning/`을 Git에 포함할지

config.json의 commit_docs 설정으로 제어:

true (기본값) — .planning/ 파일도 Git에 커밋 (팀 공유 가능)
false — .planning/을 .gitignore에 추가 (로컬에서만 관리)

12. 트러블슈팅 & FAQ

Q: GSD를 이미 사용 중인 프로젝트에서 시작하려면?

/gsd:new-project

를 실행하세요. 기존 코드를 분석한 후 프로젝트를 초기화합니다.

Q: `.planning/` 폴더를 실수로 삭제했으면?

/gsd:health로 진단하고, 가능하면 Git에서 복구하세요:

git checkout -- .planning/

Q: 페이즈 순서를 변경하고 싶으면?

중간에 삽입: /gsd:insert-phase
삭제 및 재정렬: /gsd:remove-phase

Q: 모든 확인을 건너뛰고 자동으로 실행하려면?

/gsd:settings

에서 게이트를 모두 false로 설정하거나, /gsd:autonomous를 사용하세요.

Q: 작업 도중 대화가 너무 길어져서 컨텍스트가 부족해지면?

GSD는 모든 상태를 파일에 저장하므로 /clear로 대화를 초기화해도 됩니다:

/clear
/gsd:resume-work    ← 이전 컨텍스트를 파일에서 복원

Q: 특정 에이전트만 다른 모델로 바꾸고 싶으면?

/gsd:settings에서 개별 에이전트의 모델을 오버라이드할 수 있습니다.

Q: GSD 업데이트는?

/gsd:update

Q: 시스템 상태를 점검하려면?

/gsd:health    ← .planning/ 디렉토리 건강 상태 진단
/gsd:stats     ← 프로젝트 통계 (페이즈, 플랜, 커밋 등)

13. 전체 명령어 요약표

작업 규모별 추천 명령어

작업 규모	추천 명령어	예시
한 줄 수정	`/gsd:fast`	오타 수정, 변수명 변경
작은 기능	`/gsd:quick`	API 엔드포인트 하나 추가
중간 기능	`/gsd:plan-phase` + `/gsd:execute-phase`	검색 기능 구현
큰 프로젝트	`/gsd:new-project` + `/gsd:autonomous`	새 서비스 개발
버그 수정	`/gsd:debug`	원인 불명의 에러
뭘 해야 할지 모를 때	`/gsd:do` 또는 `/gsd:progress`	아무 때나

워크플로우 순서 (외울 필요 없음 — `/gsd:next`가 알아서 안내)

new-project → discuss-phase → plan-phase → execute-phase → verify-work → complete-milestone

전체 명령어 카테고리별 정리

카테고리	명령어
시작	`new-project`, `map-codebase`
계획	`discuss-phase`, `plan-phase`, `add-phase`, `insert-phase`, `remove-phase`
실행	`execute-phase`, `quick`, `fast`, `do`, `autonomous`, `next`
검증	`verify-work`, `validate-phase`, `audit-milestone`, `audit-uat`, `add-tests`
상태	`progress`, `stats`, `session-report`
세션	`pause-work`, `resume-work`, `thread`
Git	`ship`, `pr-branch`
디버그	`debug`
아이디어	`add-todo`, `check-todos`, `note`, `plant-seed`, `add-backlog`, `review-backlog`
설정	`settings`, `set-profile`, `health`, `cleanup`, `update`, `help`
고급	`workstreams`, `new-workspace`, `list-workspaces`, `remove-workspace`, `manager`, `review`

핵심 요약: 모르겠으면 /gsd:do에 하고 싶은 말을 적거나, /gsd:progress로 현재 상태를 확인하세요. GSD가 알아서 안내해줍니다.

에이전틱 엔지니어링 Agentic Engineering

은둔한량 — Tue, 17 Mar 2026 00:43:10 +0900

1. 에이전틱 엔지니어링 (Agentic Engineering) 이란

에이전틱 엔지니어링(Agentic Engineering)은 단순한 코드 생성(바이브 코딩)을 넘어, 인간의 감독 하에 AI 에이전트들이 스스로 목표를 계획하고, 코드를 작성하며, 테스트 및 배포까지 자율적으로 수행하도록 조율(Orchestration)하는 차세대 소프트웨어 개발 방식을 의미합니다.

2. 5가지 핵심 개념

1) Agent & Sub-Agent
- Agent란 ? 목표를 해석하고, 계획을 세우고, 도구를 사용해서 자율적으로 실행하는 주체

해석(목표이해) → 계획(전략수립) → 실행(도구사용) → 평가 루프(결과검증)

멀티 에이전트 오케스트레이터(Multi-Agent Orchestrator)는 여러 개의 특화된 AI 에이전트를 하나의 시스템 내에서 지능적으로 조율하고 협업시키는 프레임워크 또는 시스템을 의미합니다. 단일 범용 AI 모델의 한계를 넘어, 각기 다른 역할(예: 연구, 요약, 코드 작성)을 가진 에이전트들을 적재적소에 배치하여 복잡한 작업을 수행하도록 돕습니다.

다중 에이전트 시스템(Multi-Agent System, MAS)은 여러 자율적인 에이전트들이 상호 작용하며 공동의 문제를 해결하거나 특정 목표를 달성하기 위해 협력하는 시스템이에요. 각 에이전트는 특정 역할이나 전문 분야를 담당하며, 서로 통신하고 조율하면서 문제를 해결합니다.

2) Context Engineering : 에이전트 두뇌 설계, 이제 프롬프트 엔지니어링은 끝났다.
컨텍스트 엔지니어링(Context Engineering)은 LLM(거대언어모델)이 복잡한 작업을 정확히 수행하도록 필요한 정보(데이터, 도구, 제약조건 등)를 실시간으로 구성하여 문맥을 제공하는 시스템 설계 기술입니다. 단순히 질문을 잘하는 프롬프트 엔지니어링을 넘어, 데이터 큐레이션 및 외부 환경(RAG 등)을 능동적으로 연동하여 최적의 AI 응답을 만들어내는 기술입니다.

System Context - Conversation Context - Tool & Environment Context

- 비용과 지연 폭발
- 신호 약화 (Lost-in-the-Middle)
- 캐시효율성
- 필요한 정보만 적시하고 적적한 형태로 제공하라

CLAUDE.md : https://www.builder.io/blog/claude-md-guide

How to Write a Good CLAUDE.md File

Learn how to create, structure, and maintain CLAUDE.md files for Claude Code. Save hours by documenting project conventions that persist across sessions.

www.builder.io

# Project: ShopFront

Next.js 14 e-commerce application with App Router, Stripe payments, and Prisma ORM.

## Code Style

- TypeScript strict mode, no `any` types
- Use named exports, not default exports
- CSS: Tailwind utility classes, no custom CSS files

## Commands

- `npm run dev`: Start development server (port 3000)
- `npm run test`: Run Jest tests
- `npm run test:e2e`: Run Playwright end-to-end tests
- `npm run lint`: ESLint check
- `npm run db:migrate`: Run Prisma migrations

## Architecture

- `/app`: Next.js App Router pages and layouts
- `/components/ui`: Reusable UI components
- `/lib`: Utilities and shared logic
- `/prisma`: Database schema and migrations
- `/app/api`: API routes

## Important Notes

- NEVER commit .env files
- The Stripe webhook handler in /app/api/webhooks/stripe must validate signatures
- Product images are stored in Cloudinary, not locally
- See @docs/authentication.md for auth flow details

3) Tool, Plugin & MCP

		Level 3 - MCP - 표준프로토콜, 모든 Tool/Plugin을 표준화된 인터페이스로 연결
	Level 2 - Plugin : Tool 묶음, GitHub 플러그인 (PR조회 + 생성 + 리뷰)
Level 1 - tool : 개별함수, 파일 읽기, 터미널 실행, 웹검색

< 3가지 계층 구조 >

- 최소 권한 원칙 : 필요한 Tool만 노출
- 검증 가능성 : Tool 호출 결과를 인간이 쉽게 확인
- 에러 핸들링 내장 : 실패시 대안 경로 선택 가능
- 보안 경계 설정 : 읽기 전용 vs 쓰기 가능 명확 구분

4) Hook & Skill : 에이전트 행동 제어

* HOOK 4가지 유형

Hook 유형	동작 시점	실전 예시
Pre-action	에이전트가 행동하기 전	코드 저장 전 Lint 자동 실행
Post-action	에이전트가 행동한 후	커밋 후 자동 테스트 실행
Validation	에이전트 출력의 품질 검증	보안 취약점 스캔
Notification	특정 조건 충족시 인간에게 알림	비용 임계치 초과 경

Claude Code Skills는 skills/ 폴더에 SKILL.md 파일을 작성해 반복적인 개발 작업을 자동화하는 기능입니다. 개인(~/.claude/skills) 또는 프로젝트(프로젝트폴더/.claude/skills) 단위로 스킬을 정의할 수 있으며, 클로드에게 자연어로 해당 스킬을 실행하도록 요청할 수 있습니다.

5) Planning & HITL

Planning Loop

1) 목표분해 2) 계획수립 3) 도구로 실행 4) 결과 평가 5) 재계획

Vibe Coding과 Agentic Engineering의 가장 큰 차이는 테스트 입니다.
견고한 테스트 스위트가 있으면 AI 에이전트가 테스트가 통과할 때까지 반복할 수 있고, 결과에 높은 확신을 가질 수 있습니다.

Agent가 Context를 바탕으로 Plan을 세우고,
Tool/MCP를 사용해 실행하고,
Hook과 Skill로 품질을 제어하고,
Human이 감독한다.

MCP 란 ?

은둔한량 — Sun, 15 Mar 2026 17:53:07 +0900

1. MCP 란 ?

대규모 언어 모델(LLM)은 강력하지만 두 가지 주요 한계가 있습니다. 하나는 학습 시점의 지식에 고착되어 있다는 점이고, 다른 하나는 외부 세계와 상호작용할 수 없다는 점입니다. 즉, 실시간 데이터에 액세스하거나 회의 예약, 고객 기록 업데이트와 같은 작업을 수행할 수 없습니다.
Model Context Protocol(MCP)은 이러한 문제를 해결하기 위해 설계된 개방형 표준(오픈 소스 표준 프로토콜)입니다.

2024년 11월 Anthropic에서 도입한 MCP는 LLM이 외부 데이터, 애플리케이션 (GitHub, Google Drive 등) , 서비스와 통신할 수 있는 안전하고 표준화된 '언어'를 제공합니다. AI가 정적 지식을 넘어 현재 정보를 검색하고 조치를 취할 수 있는 동적 에이전트가 되도록 지원하는 브리지 역할을 하여 AI 에이전트가 로컬 파일, DB, 검색 엔진 등의 도구를 자유롭게 사용하여 실시간 작업 및 데이터 조회를 수행하게 해주는 '손과 발' 역할을 합니다. AI의 정확성, 유용성, 자동화를 높입니다.

2. MCP 작동 원리

1) 요청 및 도구 탐색: LLM은 자체적으로 데이터베이스에 액세스하거나 이메일을 보낼 수 없다는 것을 이해합니다. MCP 클라이언트를 사용하여 사용 가능한 도구를 검색하고, MCP 서버에 등록된 관련 도구 2개(database_query 도구와 email_sender 도구)를 찾습니다.
2) 도구 호출: LLM이 이러한 도구를 사용하기 위한 구조화된 요청을 생성합니다. 먼저 보고서 이름을 지정하여 database_query 도구를 호출합니다. 그러면 MCP 클라이언트가 이 요청을 적절한 MCP 서버로 보냅니다.
3) 외부 작업 및 데이터 반환: MCP 서버는 요청을 수신하고 이를 회사의 데이터베이스에 대한 보안 SQL 쿼리로 변환하여 판매 보고서를 검색합니다. 그런 다음 이 데이터를 포맷하여 LLM에 다시 보냅니다.
4) 두 번째 작업 및 응답 생성: 이제 보고서 데이터를 확보한 LLM은 email_sender 도구를 호출하여 관리자의 이메일 주소와 보고서 콘텐츠를 제공합니다. 이메일이 전송된 후 MCP 서버는 작업이 완료되었음을 확인합니다.
5) 최종 확인: LLM이 최종 응답을 제공합니다. '최신 판매 보고서를 찾아서 관리자에게 이메일로 보냈습니다.'

3. 개발자가 자주 사용하는 MCP

context7
최신 라이브러리 문서와 정확한 코드 예제를 실시간으로 사용할 수 있는 서버입니다. AI의 가장 큰 약점인 오래되거나 부정확한 정보 문제를 해결할 수 있습니다.
https://context7.com/docs/overview
https://github.com/upstash/context7

GitHub - upstash/context7: Context7 Platform -- Up-to-date code documentation for LLMs and AI code editors

Context7 Platform -- Up-to-date code documentation for LLMs and AI code editors - upstash/context7

github.com

주요 기능

문서 검색	최신 공식 문서를 검색하여 정확한 사용법을 가져옵니다.
코드 예제 제공	특정 기능 구현에 필요한 검증된 코드 스니펫을 컨텍스트로 제공합니다.
API 조회	특정 함수나 클래스의 파라미터, 반환값, 오류 코드 등 상세 API 명세를 조회합니다.
버전 맞춤 정보	구버전 데이터가 아닌 현재 사용 가능한 라이브러리 버전에 맞는 정보를 제공합니다.

활용 사례

코드 작성 지원	“Upstash Redis를 사용하여 Rate Limiting을 구현하는 최신 코드를 알려줘”
오류 수정	“이 코드가 최신 SDK 버전에서도 유효한지 문서를 기반으로 확인해 줘”
API 사용법 확인	“이 API 호출에서 401 에러가 발생하는데 문서 상에서 가능한 원인이 무엇인지 알려줘”
마이그레이션 지원	“Kafka 클라이언트 v1에서 v2로 마이그레이션할 때 주의할 점을 문서에서 찾아줘”

Terraform
클라우드 인프라를 직접 배포하고 관리할 수 있도록 돕는 서버입니다.
https://developer.hashicorp.com/terraform/mcp-server

Terraform MCP server overview | Terraform | HashiCorp Developer

Learn about the Terraform model context protocol (MCP) server and how it can help you write Terraform configuration using AI.

developer.hashicorp.com

주요 기능

문서 검색 및 조회	리소스, 데이터 소스, 함수 및 설정 가이드 등 포괄적인 프로바이더 문서를 검색하고 상세 내용을 검색하며 최신 버전을 조회합니다.
모듈 탐색 및 조회	커뮤니티 및 검증된 모듈을 이름/기능별로 검색하고 입/출력, 예시, 하위 모듈 등 상세 정보 및 최신 버전을 조회합니다.
정책 검색 및 조회	거버넌스 및 규정 준수를 위한 Sentinel 정책을 검색하고 구현 세부 정보 및 사용 지침을 조회합니다.
워크스페이스 관리	Terraform Cloud/Enterprise 조직, 프로젝트, 워크스페이스를 생성, 조회, 수정, 삭제합니다.
실행 관리	워크스페이스 내에서 실행 목록을 조회, 상세 정보를 확인 및 생성하며 실행에 대한 작업을 수행합니다.
사설 Registry	조직 내 사설 모듈 및 사설 프로바이더를 검색하고 상세 정보를 조회합니다.
변수 및 변수 세트 관리	조직 내 변수 세트를 생성하고 목록을 조회하며 워크스페이스에 연결 및 분리하고, 변수를 생성, 수정, 목록 조회합니다.
워크스페이스 태깅	워크스페이스에 태그를 추가 및 조회하여 리소스를 체계적으로 분류하고 정리합니다.

활용 사례

프로바이더 문서 활용	“AWS S3 버킷을 버전 관리 활성화하여 구성하는 방법을 알려줘”
모듈 활용	“AWS에 Kubernetes 클러스터를 배포하기 위한 모듈을 보여줘.”
정책 활용	“보안 모범 사례를 강제하기 위해 사용할 수 있는 Sentinel 정책이 무엇인지 알려줘.”
워크스페이스 관리	“내 조직에 ‘production-app’이라는 새 워크스페이스를 생성해 줘”
실행 관리	“staging 워크스페이스에 대한 모든 실행 목록을 보여줘”
사설 모듈 검색	“AWS 관련 사설 모듈을 모두 나열해 줘”
변수 세트 관리	“데이터베이스 구성을 위한 변수 세트를 생성해 줘”
태깅 관리	“개발 환경에 해당하는 모든 워크스페이스에 ‘env:dev’ 태그를 추가해 줘.”

Notion
프로젝트 관리에서 많이 쓰이는 노션 데이터베이스 및 페이지를 검색, 수정, 생성을 하는 서버입니다.
https://developers.notion.com/guides/mcp/mcp

Notion MCP - Notion Docs

Learn how to connect AI agents to your Notion workspace.

developers.notion.com

주요 기능

문서 생성	단순 페이지 생성뿐만 아니라 새로운 데이터베이스(표, 보드 등)를 설계하여 만들거나 기존 템플릿 페이지를 복제합니다.
통합 검색	Notion 워크스페이스는 물론, 연결된 Slack, Google Drive, Jira 등 외부 도구까지 한 번에 검색하여 관련 정보를 찾아냅니다.
작업 관리	페이지나 데이터베이스를 다른 상위 페이지로 이동시켜 워크스페이스 구조를 자동으로 정리하고 페이지의 상태나 날짜 등의 속성을 업데이트합니다.
협업 및 댓글 관리	댓글을 남기거나 기존 댓글 스레드를 읽어오고 워크스페이스 내 팀원 정보를 조회합니다.

활용 사례

프로젝트 초기 세팅	“새로운 ‘Q4 프로젝트’ 데이터베이스를 만들고 담당자, 마감일, 진행 상태 열을 추가해 줘. 그리고 회의록 템플릿을 복사해서 넣어줘.”
통합 정보 검색 및 요약	“Slack과 Notion에서 ‘버그 수정’과 관련된 지난주 논의 내용을 모두 검색해서 ‘개발팀’ 페이지에 요약 보고서로 만들어줘”
워크플로우 자동화	“오늘 날짜가 지난 모든 태스크의 상태를 ‘지연(Overdue)’으로 변경하고 담당자에게 확인 요청 코멘트를 달아줘.
문서 구조 조정	“임시 보관함에 있는 모든 회의록 페이지를 ‘2024년 회의 아카이브’ 페이지 하위로 이동시켜줘.”

Chrome DevTools
Chrome 개발자 도구의 기능을 제공하여 웹 디버깅 및 프론트엔드 개발 자동화에 도움이 되는 서버입니다.
https://github.com/ChromeDevTools/chrome-devtools-mcp

GitHub - ChromeDevTools/chrome-devtools-mcp: Chrome DevTools for coding agents

Chrome DevTools for coding agents. Contribute to ChromeDevTools/chrome-devtools-mcp development by creating an account on GitHub.

github.com

주요 기능

콘솔 제어	브라우저 콘솔 로그를 확인하거나 자바스크립트 코드를 실행합니다.
DOM 검사	현재 웹페이지의 DOM 구조를 탐색하고 특정 요소의 속성을 확인합니다.
네트워크 분석	웹페이지 로딩 시 발생하는 네트워크 요청 및 응답 헤더/바디를 캡처하여 분석합니다.

활용 사례

반응형 테스트	“모바일 뷰포트로 변경했을 때 메뉴 바가 정상적으로 보이는지 스크린샷을 찍어줘”
에러 디버깅	“콘솔에 출력된 에러 메시지를 확인하고 원인을 분석해 줘”
UI 테스트	“로그인 버튼의 DOM 요소가 올바르게 렌더링 되었는지 확인해 줘”

4. 클로드 코드에서 MCP 세팅 및 사용하기

Claude Code에서 MCP(Model Context Protocol)를 설정하려면 구성 파일(mcp.json 또는 managed-mcp.json)을 생성하여 MCP 서버의 실행 명령어를 명시해야 합니다. npm 또는 npx를 사용하여 파일을 작성한 뒤, Claude Code 내에서 MCP 도구를 통해 외부 데이터와 기능을 연동합니다.

MCP 구성 파일 생성: ~/.config/claude-code/mcp.json 파일을 생성하여 MCP 서버를 등록합니다.

{
  "mcpServers": {
    "example-server": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"]
    }
  }
}

사용자 > .claude 에 mcp 를 검색해 보면 저는 이렇게 쓰고 있습니다.

"projects": {
    "C:/APM/Apache24/htdocs/www": {
      "allowedTools": [],
      "mcpContextUris": [],
      "mcpServers": {
        "context7": {
          "type": "http",
          "url": "https://mcp.context7.com/mcp"
        },
        "sequential-thinking": {
          "command": "npx",
          "args": [
            "-y",
            "@modelcontextprotocol/server-sequential-thinking"
          ]
        },
        "playwright": {
          "type": "stdio",
          "command": "npx",
          "args": [
            "@playwright/mcp@latest"
          ],
          "env": {}
        },

실행 및 확인: Claude Code를 실행하고 /mcp 명령어를 사용하여 서버가 정상적으로 로드되었는지 확인합니다.

Claude Code (클로드 코드) 설치 및 사용법

은둔한량 — Sat, 7 Mar 2026 02:42:44 +0900

Claude Code란?

Claude Code는 Anthropic에서 개발한 생성형 AI 모델 Claude를 기반으로 한 코드 생성·분석 특화 AI 활용 방식을 의미합니다.
쉽게 말해, “Claude를 활용해 개발 업무를 자동화·보조하는 개발 워크플로우”라고 이해하면 됩니다.
특히 최근에는 IDE(예: Cursor)나 다양한 개발 환경에서 Claude 모델을 연동해 코드 작성, 리팩토링, 디버깅, 문서화, 테스트 코드 생성 등을 수행하는 형태로 많이 사용됩니다.

1. Claude Code의 핵심 개념

Claude Code는 단순한 코드 자동완성이 아닙니다.
다음과 같은 “맥락 이해 기반 개발 보조”에 강점이 있습니다.

1) 대규모 코드 컨텍스트 이해
Claude는 긴 컨텍스트를 처리할 수 있어:
- 프로젝트 전체 구조 분석
- 여러 파일 간 의존성 이해
- 기존 코드 스타일 유지
- 레거시 코드 리팩토링
등이 가능합니다.

2) 자연어 기반 코드 생성
예시:

“CodeIgniter4에서 MariaDB 기반 로그인 세션 처리 로직 만들어줘”

처럼 설명하면:
- Controller
- Model
- Validation
- Session 처리
- 보안 고려사항
까지 포함해 코드 초안을 만들어줍니다.

3) 리팩토링 & 코드 개선
- 성능 개선
- 보안 취약점 분석
- 메모리 누수 가능성 점검
- 비동기 처리 개선
- 쿼리 최적화 제안
- 특히 대형 프로젝트에서 강점이 있습니다.

2. 설치

1) npm 방법 (Node.js 설치가 되어 있으면 이 방법을 선택하세요.)

npm 방법을 꼭 써야 한다면, 먼저 Node.js를 설치해야 합니다.

1 단계: Node.js 설치
- https://nodejs.org 접속
- LTS 버전 다운로드 및 설치
- 설치 후 PowerShell을 완전히 닫고 새로 열기 (PATH 갱신)

2 단계: 설치확인
node --version # v18.x.x 이상이어야 함
npm --version

3 단계 설치
npm install -g @anthropic-ai/claude-code

npm install -g @anthropic-ai/claude-code

npm install -g @anthropic-ai/claude-code

다른 컴퓨터 윈도우 OS 에서 claude를 설치 하려고 했더니 에러가 났다.

NPM을 찾을 수 없다는 오류입니다. Node.js가 설치되어 있지 않아서 발생하는 문제입니다.

2) 네이티브 설치 (권장 — Node.js 불필요)

Windows에서 Claude Code를 설치하는 방법중 현재 가장 쉬운 방법(네이티브 설치)

https://code.claude.com/docs/ko/overview

Windows CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

설치시 git-bash error가 나면 git for windows가 설치 안되어서 에러가 나는겁니다. 아래 링크에서 설치 !!

https://git-scm.com/install/windows

Git - Install for Windows

Click here to download the latest (2.53.0) x64 version of Git for Windows. This is the most recent maintained build. It was released on 2026-02-02. Other Git for Windows downloads Standalone Installer Git for Windows/x64 Setup. Git for Windows/ARM64 Setup.

git-scm.com

git 설치후 다시 명령어를 치면 클로드코드가 설치 완료됩니다.

* 설치 확인

claude --version

3. claude code 실행

터미널에서 claude 만 치면 클로드코드가 실행이 됩니다. (커서, vs code 등 terminal 에서 치면 됩니다.)

저는 회사에서 결제를 해줘서 사용하고 있습니다. 계정을 연결하고 유료 요금제를 선택해야 사용을 하실 수가 있습니다.

뭘 좀 사용하다보면 사용량 한도가 금방 차지합니다. 월 $100 짜리인데 조금 쓰다 보면 5시간 사용량 한도가 차더라구요

살살 써야겠습니다.

* mcp 추가 - 제가 추가한 mcp 입니다.

* Claude Code Dangerous Mode (--dangerously-skip-permissions)

일반적으로 Claude Code는 파일 수정, 명령어 실행 등 모든 작업마다 사용자 승인을 요청합니다.
Dangerous mode는 이 승인 과정을 전부 건너뜀.

claude --dangerously-skip-permissions

언제 쓰나?

자동화 스크립트 / CI-CD 파이프라인에서 무인(unattended) 실행
승인 없이 대량 파일 작업을 빠르게 처리할 때
Docker 등 격리된 환경에서 실행할 때

4. Claude Code의 장점

- 대형 코드베이스 이해 능력
- 논리적이고 정돈된 코드 출력
- 긴 문맥 유지
- 기술 문서 자동화 능력 우수

5. 한계점

- 매우 최신 라이브러리 정보는 제한적일 수 있음
- 실행 테스트는 직접 필요
- 프롬프트 설계 능력에 따라 결과 품질 차이 발생

6. 결론

Claude Code는 단순한 “코드 자동 완성 AI”가 아니라,

“프로젝트 전체를 이해하고 함께 설계하는 AI 개발 파트너”

에 가까운 개념입니다.

특히 대규모 서비스, 백엔드 구조 설계, 리팩토링, 코드 리뷰 자동화 분야에서 강력한 생산성 향상을 기대할 수 있습니다.

클로드 코드 다른 계정으로 로그인 하는 방법

은둔한량 — Thu, 5 Mar 2026 10:41:29 +0900

클로드 코드가 갑자기 회사에서 여러사람이 쓰다 보니 짤렸다. ㅠㅠ

이런 ....!!

그래서 다른 계정으로 급하게 교체를 하려고 한다.

** 이건 공통으로 사용을 하다보니 limit가 도달을 했다고 또 메시지가 떴다.

로그인 되어 있는 클로드 계정 정보 확인

claude auth status

로그아웃

claude auth logout

Successfully logged out from your Anthropic account.

다른 계정으로 다시 로그인

/login

claude.ai 가 뜨고 로그아웃 후 다른 계정으로 로그인을 한다.

1번 enter

그리고 아래 링크를 연결하면 연결을 요청했습니다라는 창이 뜨고 승인을 누르면

Authentication Code 가 나오는데 이걸 카피해서 넣어주면 끝....

[Git] 브랜치와 커밋 메시지에서 사용하는 prefix

은둔한량 — Fri, 11 Jul 2025 12:28:34 +0900

브랜치와 커밋 메시지에서 사용할 수 있는 다양한 prefix가 있다.

각 prefix는 특정한 변경 유형을 나타내고, 팀이나 프로젝트에 따라 다를 수 있다.

일반적으로 많이 사용되는 prefix는 다음과 같다.

1. Branch prefix

브랜치는 주로 작업의 유형을 나타내는 이름으로 구성된다.

프리픽스	형식	설명	예시
Feature	feature/<이름>	새로운 기능 개발	feature/user-authentication
Bugfix	bugfix/<이름>	버그 수정	bugfix/fix-login-error
Hotfix	hotfix/<이름>	긴급 버그 수정	hotfix/urgent-security-fix
Release	release/<버전>	배포 준비 완료	release/v1.0.0
Chore	chore/<이름>	잡무나 유지보수 작업	chore/update-dependencies
Docs	docs/<이름>	문서 관련 작업	docs/update-readme
Style	style/<이름>	코드 스타일 변경	style/improve-code-formatting
Refactor	refactor/<이름>	코드 구조 개선	refactor/optimize-query-performance

2. Commit message prefix

커밋 메시지 제목은 변경 사항의 유형을 나타내는데 prefix가 사용된다.

프리픽스	설명	예시
feat	새로운 기능 추가	feat: 사용자 로그인 기능 추가
fix	버그 수정	fix: 로그인 예외 처리 버그 수정
hotfix	긴급 버그 수정	hotfix: 긴급 보안 패치
release	배포 준비 완료	release: 버전 1.0.0 배포
chore	잡무나 유지보수 작업	chore: 라이브러리 업데이트
docs	문서 수정	docs: README 업데이트
style	코드 스타일 수정	style: 코드 포맷팅 수정
refactor	코드 구조 개선	refactor: 쿼리 최적화

Ubuntu | ubuntu ffmpeg install, 우분투 ffmpeg 설치하기

은둔한량 — Fri, 27 Jun 2025 15:13:12 +0900

1. apt update

sudo apt update

2. ffmpeg 설치

sudo apt install ffmpeg

3. 설치 확인

ffmpeg -version

4. incoder, decoder 확인

ffmpeg -encoders
ffmpeg -decoders