nuung

LLM - 모델 경쟁이 끝나고, “하네스 경쟁”의 시작?!, opencode 와 oh-my-opencode

Mon, 09 Mar 2026 04:59:10 GMT

[ 글의 목적: LLM의 오케스트레이션과 하네스, opencode 와 OMO 의 탄생 배경과 how to use 정리, 이미지 빼고 AI가 안썼어요.. 사람이 썼어요..🥹 ]

모델 경쟁이 끝나고, “하네스 경쟁”의 시작?!

LLM 평가 축은 빠르게 변하고 있습니다. 이제 “모델이 얼마나 똑똑한가”만으로는 체감 품질을 설명하기 어렵습니다!! 실제 현업에서의 생산성은 긴 작업을 얼마나 안정적으로 이어갈 수 있는지, 그리고 도구·컨텍스트·검증 루프를 얼마나 잘 운영하는지에서 갈립니다.

LLM 의 스케일링 법칙(Scaling Laws)은 이제 한계라는 의견이 많습니다. (참조 링크). 더욱이 SLM 을 특정 작업에 맞춰 최적화하고, 고품질 데이터로 재학습시키고, 나아가 MoE 구조로도 사용합니다.

특히 신규 LLM 모델은 진짜 "체감할 수 있는 차이" 에 있어서 *"구체적으로, 그리고 정량적으로 우리의 작업이 얼마나 나아졌는가"* 를 설명하기 매우 어려워졌습니다.

모델 경쟁이 끝난 것은 아닙니다. 하지만 차별화의 중심축은 이미 위 레이어로 올라가고 있습니다. 특히 코딩, 리서치, 마이그레이션, 대규모 리팩토링처럼 길고 복잡한 작업에서는 “한 번 잘 답하는가”보다 “끝까지 안정적으로 완주하는가”가 훨씬 중요합니다. 그리고 그 완주 능력을 만들어내는 것이 바로 에이전트 하네스(Agent Harness)입니다.

하네스?!

에이전트 하네스는 AI 모델을 감싸고, 장기적이거나 복잡한 작업을 안정적으로 수행하도록 관리하는 운영 인프라에 가깝습니다.
모델이 문장을 생성하는 엔진이라면, 하네스는 그 엔진 위에 올라가는 차량의 프레임, 조향 장치, 브레이크, 계기판 처럼 사람 승인 지점, 파일 시스템 접근 제어, 도구 호출 순서, 하위 에이전트 협업, 프롬프트 프리셋, 실패 복구까지 묶어 실제 “작동하는 시스템”으로 만드는 layer 입니다. (참조: 2025 Was Agents. 2026 Is Agent Harnesses. Here’s Why That Changes Everything.)

1. Opencode ?!

1) 정의 및 배경

OpenCode는 스스로를 오픈소스 AI 코딩 에이전트로 소개하며, 터미널 기반 인터페이스, 데스크톱 앱, IDE 확장 형태로 사용할 수 있습니다. LSP 지원, 멀티 세션, 세션 공유 링크, 다양한 모델 프로바이더 연결을 핵심 특성으로 내세웁니다. 즉 OpenCode는 단순한 “채팅형 코딩 도구”라기보다, 에이전트를 실행하는 런타임에 더 가깝습니다.

LSP 기반 코드 이해(심볼/정의/진단 등)
멀티 세션(작업별 세션 관리)
플러그인 지원(동작 확장)
결과 공유(링크 공유) 및 팀 사용 시나리오

즉, OpenCode 자체가 이미 *“에이전트 실행기 + 도구 런타임 + 세션 관리자”* 성격을 갖고 있고, 그 위에 플러그인을 얹어 하네스 역량을 키우는 구조입니다.

2) 작동 원리

아주 아주 기본적인 개념은 "다양한 LLM 들을 하나의 tool 에서 모아서 사용" 이라는 점에서 크게 다르지 않습니다. 세션 단위로 작업 컨텍스트를 유지하며, 사용자는 TUI에서 입력/전환/실행을 수행합니다. (실행 시 TUI와 HTTP 서버가 함께 뜨는 client/server architecture)

최근에는 mode 보다 agent 구성이 중심이지만, 사용 경험상 여전히 많은 분들이 Build 와 Plan 을 “모드”처럼 이해하고 있습니다. ~~(물론 저도요 ㅎ)~~

내장 primary agent는 Build 와 Plan 이고, subagent로는 General 과 Explore 가 제공됩니다. (근데 다들 각자 플러그인을 많이 사용하다보니 순정을 보기 힘들어진 기분)

Build 는 일반 개발 작업용으로 모든 도구 접근이 열려 있고, 실제 편집, 패치, 명령 실행, 검증에 적합합니다.
Plan 은 파일 수정과 bash 실행을 제한하거나 승인 기반으로 다뤄 분석과 설계 중심으로 쓰이도록 설계되어 있고, 분석, 설계, 변경안 검토, 위험 식별에 적합합니다. (기본적으로 파일 수정과 bash 실행이ask 로 제한됨)
General 은 범용적이게 사용하고,Explore 는 읽기 & 탐색 중심!
또 내부적으로는 compaction, title, summary 같은 숨겨진 시스템 에이전트가 자동 실행된다고 합니다.

사실 이런 접근은 이제 아주 일반화가 된 것 같습니다. 저 역시 바이브 코딩과 LLM에 대한 대규모 서베이, Augmented Coding 글과 같이 "plan" 의 중요성을 매우 체감하고 있네요.

사실 권한 제어와 LSP control 이 핵심인 듯 한?!

*[ 권한 제어와 도구들의 디테일 ]*

권한은 allow, ask, deny로 제어되고
read, edit, bash, task, lsp, webfetch, websearch, codesearch 같은 항목별로 통제한다고 합니다.
grep, glob, list 는 내부적으로 ripgrep 을 사용하며, .gitignore 를 따른다고 하며 (디테일), 사실 LLM 기반으로 마치 Re-ACT agent, tool calling 처럼, 도구 호출 중심 실행 프레임워크로 만들어졌다고 보는게 맞는 것 같네요.

*[ LSP(Language Server Protocol) ]*

LLM이 코드베이스와 상호작용할 때 진단 정보(diagnostics) 를 활용합니다. 또한 여러 언어에 대해 내장/자동 설치 LSP를 제공한다고 합니다.
그래서 OpenCode는 단순히 파일 내용을 긁어서 모델에 던지는 수준이 아니라, 정적 분석 계층의 피드백까지 모델 루프 안으로 넣는 구조입니다. ~~(그래서 토큰이 녹아내릴 수 있죠.)~~

3) 플러그인 시스템: 하네스가 붙는 자리

플러그인은 JavaScript/TypeScript "모듈 형태로 훅"을 내보내며, 로컬 플러그인 디렉터리 또는 npm 패키지 방식으로 로드할 수 있습니다.

로컬 파일: 프로젝트/전역 플러그인 디렉터리에 JS/TS 배치
npm 패키지: opencode.json의 plugin 배열에 패키지명을 등록

npm 플러그인은 시작 시 Bun으로 자동 설치되며, 캐시는 ~/.cache/opencode/node_modules/ 에 default로 저장됩니다.

로드 순서는 [ 전역 config → 프로젝트 config → 전역 dir → 프로젝트 dir ] 입니다. 에이전트 하네스 쪽은 보통 설정 충돌, 훅 순서, 컨텍스트 주입 순서 때문에 디버깅이 어려운데, OpenCode는 적어도 플러그인이 어디서, 어떤 순서로 붙는지를 문서화해 둔 편입니다. 그래서 플러그인 생태계가 잘 만들어질 수 있었던 것 같네요.

4) 설치 & 세팅

(작성일 기준이라 공식 홈페이지 한 번 참고하시는게 좋습니다. - https://opencode.ai/ko), 최근에는 데스크톱 앱이 나온 것 같네요!

curl -fsSL https://opencode.ai/install | bash

역시 인기있는 tool 들은 설치와 세팅이 아주 간단합니다. 설치 후 opencode 로 실행이 끝입니다. 이후 /connect 커맨드 활용해서 "프로바이더 (상용 LLM 포함 외부 LLM auth 세팅)" 세팅까지 이어가면 바로 사용 가능합니다!

2. OMO: Oh-my-opencode ?!

1) 정의 및 배경

Oh My OpenCode는 공식 사이트에서 스스로를 “OpenCode 위에 올라가는 specialized orchestration layer” 라고 설명합니다. OMO는 OpenCode를 대체하는 별도 제품이 아니라, OpenCode 위에 에이전트, 훅, MCP, LSP, 설정값을 묶어 더 강한 운영 구조를 제공하는 플러그인 입니다!

그냥 “코드를 잘 써주는 도구”가 아니라

복잡한 빌드 파이프라인 이해
다수 에이전트 병렬 실행
컨텍스트 관리
작업 지속성
세션 복구
문서 검색과 코드 탐색 자동화

를 기반으로 "잘 굴러가게 만드는 하네스" 를 지향합니다. "AI 팀" 에 비유 하며 다수의 전문 에이전트(역할 분업), 스킬(워크플로 템플릿), 커맨드(/refactor 등), 훅(키워드 감지/복구/알림/컨텍스트 주입)을 묶어서 제공한다고 설명합니다. (플러그인 공식 깃헙 레포, 관련 긱뉴스, 제작자 유튜브 인터뷰(팟캐스트))

2) Oh-My-OpenCode의 “각 모드”는 무엇이며, 언제 쓰는가

OMO는 기본적으로 Planner-Sisyphus, Librarian, Explore, Oracle 같은 전문 에이전트를 제공합니다. Sisyphus 를 기본 오케스트레이터로 설명하고, Prometheus, Metis 같은 계획 보조 에이전트, 그리고 frontend-ui-ux-engineer, document-writer, multimodal-looker 같은 역할 특화 에이전트가 있습니다.

다수 에이전트를 “AI 팀”으로 제공

Sisyphus: 기본 오케스트레이터(계획·위임·실행)
Prometheus / Metis / Momus: 계획 수립·사전 점검·계획 리뷰
Oracle / Librarian / Explore: 설계·문서/OSS 리서치·코드베이스 탐색(쓰기 제한)
document-writer: README, API 문서, 가이드 작성
multimodal-looker: PDF/이미지/다이어그램 분석

@ 를 통해서 에이전트를 타겟할 수 도 있습니다!

3) ultrawork, search, analyze ?!

이게 지금의 OMO를 만들어준, 하이라이팅될 수 있던 feature들이 아닐까 하네요, OMO는 "키워드 기반 감지" 로 "하네스" 가 작동이 됩니다. ultrawork 또는 ulw 는 최대 성능 모드, search 또는 find 는 병렬 탐색 모드, analyze 또는 investigate 는 심층 분석 모드로 안내가 됩니다. 또 think deeply, ultrathink 같은 표현은 think mode 훅이 감지해 추론 설정을 조정한다고 합니다.

사용자가 “이번 작업의 성격”만 잘 말해도 하네스가 행동 방식을 바꿔주기 때문입니다. 즉 프롬프트가 단순 지시문이 아니라, 오케스트레이션 정책을 바꾸는 신호가 됩니다.

ultrawork/ulw = 최대 성능 모드

ultrawork, 줄여서 ulw는 OMO README에서 사실상 “마법의 단어”처럼 소개됩니다. 공식 README 표현을 정리하면, 병렬 에이전트 실행, 백그라운드 작업, 적극적 탐색, 완료까지 밀어붙이는 성격을 가진 최대 성능 모드입니다. 대규모 리팩토링, 복잡한 마이그레이션, 여러 파일과 여러 축의 검증이 동시에 필요한 작업에 잘 맞습니다.

작업 범위가 크고(리팩토링/마이그레이션/대규모 기능 추가)
실패 비용이 높고(프로덕션/핵심 모듈)
여러 축(리서치·코드·테스트·문서)을 병렬로 돌려야 할 때

기본 오케스트레이터가 작업을 분해하고, 전문 에이전트를 공격적으로 병렬 실행하는 성격으로 설계돼 있다고 설명합니다. 즉 자체적으로 "각 업무 전문가에게 일을 할당하고, 평가하고, 리팩토링하고 등" 이 모두 묶여있습니다. (다음 섹션에서 저는 어떻게 ulw 를 사용하는지 정리해 뒀습니다!)

search/find = 병렬 탐색 모드

이 모드는 빠른 코드베이스 탐색이 핵심입니다. OpenCode의 내장 Explore 가 원래 읽기 전용 탐색 성격을 갖고 있는데, OMO는 이런 탐색 성격을 더 공격적으로 활용합니다. 레거시 프로젝트 진입점 찾기, 설정 파일 찾기, 실제 호출 경로 파악, 특정 동작이 어디서 시작되는지 확인할 때 특히 유용합니다.

레거시 프로젝트 온보딩
특정 동작의 진짜 진입점/호출 경로를 찾아야 할 때
설정 파일/핵심 클래스/핫스팟 파일을 빠르게 식별해야 할 때

analyze/investigate = 심층 분석 모드

이 모드는 구현보다 해석과 판단에 가깝습니다. 장애 원인 분석, 설계 리뷰, 트레이드오프 비교, “왜 이런 구조가 되었는가”를 증거 기반으로 정리할 때 잘 맞습니다. 공식 사이트의 Oracle 소개와 README 설명을 합치면, 코드 설명과 문제 진단, 아키텍처 판단을 보조하는 방향으로 이해할 수 있습니다.

장애 재현이 어렵거나, 원인이 여러 후보로 갈릴 때
설계 결정을 내려야 하는데 트레이드오프가 복잡할 때
“왜 이 로직이 이렇게 됐는지”를 증거 기반으로 정리해야 할 때

문서는 oracle을 “아키텍처 결정/코드 리뷰/디버깅(읽기 전용)” 상담역으로 설명합니다.

think mode

Think mode는 구현 이전 사고 비용을 늘리는 장치입니다. “바로 고치지 말고 먼저 깊게 생각해라”라는 의도를 하네스 차원에서 반영합니다. 문제 정의가 불분명하거나, 정책과 SDK 제한을 함께 검토해야 하거나, 근거를 모아 판단해야 할 때 특히 유효합니다.

구현 이전에 문제 정의/요구사항 정리/리스크 식별이 필요할 때
장단점/대안 비교가 본질일 때
문서·정책·SDK 제한 때문에 “확실한 판단”이 필요한데 근거를 모아야 할 때

think-mode 훅이 관련 키워드를 감지해 모델 설정(extended thinking 등)을 조정한다고 명시합니다. (사견으로는 생각 자체에 회귀를 할 때가 있어서 적절한 결론에 대한 신호 체계를 만드는게 좋습니다!)

4) 설치 & 세팅

물론 OpenCode 설치가 무조건 선행되어야 합니다. 하지만, 역시 간단합니다. (bun 런타임이 필요합니다.)

bunx oh-my-opencode install

그러면 세팅 가이드가 자동으로 안내를 해줍니다!

3. 실제 사용 예시

일단 하나의 예시를 보면,,

OMO의 ulw 는 진짜 한 줄만 줘도 진정한 의미의 "바이브코딩" 을 합니다. "딸각" 이 가능하죠. 근데 ~~제가 여전히 구시대적인 사람인지 몰라도~~ 저는 이게 너무 와닿지 않습니다. "통제 가능성" 과 "일관성", "규칙" 이 저에게는 너무 중요해서..

1) 일단 플젝 세팅 부터 제대로

1. 무엇을 만들어야 하는지 결정된다면 `stack` 부터 정합니다.

이땐 리서치와 대화형 LLM만 사용합니다. 사실 "통제가능성" 이 중요하기에 제가 익히 잘 아는 stack에서 잘 벗어나지 않습니다.
대부분 ts, react + nextjs, nestjs, python, django + drf or ninja ... 가끔 rust 섞음
아직까진 모노레포를 선호하지는 않습니다. 최근에 모노레포로 한 번 했다가 AI markdown 세팅이나 AI rule 세팅이 더 복잡해져서 바로 버렸습니다.

2. `AGENTS.md` (CLAUDE.md 등 포함) 부터 출발합니다.

요즘은 /init 으로 직접 이 마크다운을 만드는 경우가 많지만, 저는 여전히, Augmented Coding 에서 차용한 TDD와 Tidy code를 아주 적극적으로 사용합니다.
그래서 AGENTS.md 에는 "논리적인 방법론" 들을 정리합니다. 기본적인 역할, TDD, Tidy First, Quality 등에 대해서요.
디렉토리나 스택, 언어 등을 언급하지 않고, 대신 "SYSTEM_DESIGN.md 꼭 참조해라!" 라는 인디케이터만 넣습니다.

3. `SYSTEM_DESIGN.md` 를 만듭니다.

일례로 아래와 같습니다. 제가 python 으로 작업할땐 꼭 아래 시스템 디자인으로 출발합니다. 포인트는 Do not over-apply design patterns

# SYSTEM_DESIGN

This document defines the core system design rules for this project.

---

## 1. Python Version & Typing

- We use **Python 3.13 or higher**.
- Do **not** use the `typing` module for type hints.
- Always use **built-in types** for annotations (e.g., `int`, `str`, `list`, `dict`, etc.).

---

## 2. Code Style

- Follow the **Google Python Style Guide**:
  - 
- Follow **PEP 8** (Python’s official style guide):
  - 

If there is any conflict between local conventions and these guides, prefer clarity and consistency within this project.

---

## 3. Object-Oriented Design

We favor **object-oriented programming (OOP)** and its core principles:

- **Encapsulation** – Group related data and behavior inside classes and hide internal details.
- **Abstraction** – Expose clear interfaces and hide unnecessary implementation details.
- **Inheritance** – Reuse behavior via well-designed base classes and subclasses when appropriate.
- **Polymorphism** – Design interfaces so that different implementations can be used interchangeably.

OOP should improve readability and maintainability, not add unnecessary complexity.

---

## 4. Architectural Pattern

- We **aim for a layered architecture pattern** (e.g., presentation, application/service, domain, infrastructure).
- Each layer should have a clear responsibility and minimal knowledge of other layers.

At the same time:

- Do **not** over-apply design patterns or split the codebase into too many tiny files.
- Avoid “architecture for architecture’s sake.”
- Aim for:
  - **Reasonable maintainability**
  - **Reasonable separation of concerns**
  - **Always pragmatic, balanced design**

In short, we prefer a **practical, moderately layered architecture** that is easy to understand, extend, and maintain, rather than a theoretically "perfect" but over-engineered structure.

이 파일에서 저는 "물리적인 방법론" 과 실제 구현 방향에 대해 정확하고 구체적으로 정리합니다.
특히 python 은 "빠르게, 저렴하게" 라는 측면에서 바이브코딩과 아주 맞닿아 있지만, 언어 특성때문에 볼륨이 조금만 커져도 무너져 내리더라구요. 1부터 10개 작업하면, 2번과 9번의 코드 스타일이 완전하게 달라지는 이슈도 빈번했구요.
그래서 type 을 꽤나 엄격하게 다루는데, mypy 보다는 pyright 가 좀 더 유연한 측면에서 맞는 것 같네요.

4. `pre-commit`, `ruff(eslint & prettier)`, `test(pytest, jest)` 세팅을 바로 합니다.

저는 uv + ruff 으로 아래 기본 세팅은 하고 갑니다. 스크롤이 너무 길어져서 뺄까 했는데, 혹시나 다른 분들을 위한 설정 값 공유!

(아래 pre-commit)

ci:
  autoupdate_schedule: monthly

default_language_version:
  python: python3.13

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v6.0.0
    hooks:
      - id: check-yaml
      - id: check-toml
      - id: check-added-large-files
      - id: check-merge-conflict
      - id: end-of-file-fixer
      - id: trailing-whitespace

  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.15.0
    hooks:
      - id: ruff
        args: [--fix, --exit-non-zero-on-fix]
      - id: ruff-format

  - repo: https://github.com/astral-sh/uv-pre-commit
    rev: 0.10.2
    hooks:
      - id: uv-export
        args:
          - --frozen
          - --no-dev
          - --no-hashes
          - --output-file=requirements.txt
          - --quiet

(아래 toml 에서 기본 설정들)

# ================================================================
# Ruff (Linter & Formatter) Settings
# ================================================================
[tool.ruff]
# 수정에서 제외할 파일 및 디렉토리 목록
exclude = [
    ".bzr",
    ".direnv",
    ".eggs",
    ".git",
    ".hg",
    ".mypy_cache",
    ".nox",
    ".pants.d",
    ".pytype",
    ".ruff_cache",
    ".svn",
    ".tox",
    ".venv",
    "__pypackages__",
    "_build",
    "buck-out",
    "build",
    "dist",
    "node_modules",
    "venv",
    "*/migrations/*.py",
]
# 한 줄의 최대 글자 수
line-length = 100

# --- Linter (코드 분석기) 설정 ---
[tool.ruff.lint]
# 활성화할 규칙 선택:
# E, W: pycodestyle (에러, 경고)
# F: Pyflakes (논리적 오류)
# I: isort (import 정렬)
select = ["E", "F", "W", "I"]
ignore = []

# 모든 수정 가능한 규칙을 자동으로 고치도록 설정
fixable = ["ALL"]
unfixable = []

# --- Formatter (코드 포맷터) 설정 ---
[tool.ruff.format]
# Black과 유사한 포맷팅 스타일을 따릅니다.
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false
line-ending = "auto"

# --- 플러그인별 상세 설정 ---
[tool.ruff.lint.isort]
# 프로젝트에서 사용하는 서드파티 라이브러리 목록
# known-third-party = ["django", "graphene_django"]

# --- 파일/디렉토리별 규칙 무시 설정 ---
[tool.ruff.lint.per-file-ignores]
# settings 파일: 와일드카드 import 허용
# "config/settings/*" = ["F403", "F405"]

# __init__.py 파일: 하위 모듈 노출을 위한 미사용/와일드카드 import 허용
"**/__init__.py" = ["F401", "F403"]

# 테스트 파일: 가독성을 위해 긴 줄 허용
"**/test_*.py" = ["E501"]

js&ts 쪽 파일도 붙여넣을까 했는데 진짜 너무 과하게 길어질 것 같아서 생략..
맥락은 같습니다. 어차피 AI 가 또는 next(or nest) 를 쓰든 프로젝트 init 하면 린터와 포매터 세팅은 따라 나옵니다. 이걸 입맛에 맞는 커스텀 템플릿으로 바꾸는 정도!
그리고 ts 경우 type 을 얼마나 strict 하게 할지, 미리 세팅해두면 아주 도움이 되는 것 같네요.

5. github action CI 부터 역시 바로 세팅합니다.

내용이 너무 길어서 스킵,, 일부분만 사진으로 대체

그리고 github cli 인 gh 를 기가막히게 잘 쓰더라구요. 그래서 더욱이 CI 부터 세팅하려고 합니다. 위는 python, uv 기반 CI 파이프라인이고, 처음부터 멀티 버전 (매트릭스) 대상으로 하지는 않습니다.

2) 그리고 작업 시작, plan.md 부터!

저는 무조건 plan.md 부터 작성합니다. 이게 AGENTS.md 에서 명시한 것들과 일맥상통하기도 하고, "통제 가능성" 이 여전히 중요하기도 하구요. *그리고 여전히 저는 무조건 테스트 코드 부터 작성합니다.*

이를 병목으로 보는 시선도 많아졌더라구요. 되돌아보면 과거에 비해 plan 을 좀 더 넓은 범위로 작성합니다. 예전에는 딱 한 작업, 한 commit 단위 대상으로 plan 을 작성했었습니다. (A 라는 API 만 바꾸고 싶다던지 등)
지금은 조금 더 범위가 큽니다. "알림 관련 기능을 만들건데 이러이러해~ 이러이러한 것을 위한 ORM 모델 부터 핵심 API 만 만들자~" 이런 느낌으로요.
더욱이 plan.md 는 이제 하나의 "체크포인트" 이기도 합니다. 그래서 저는 plans 디렉토리에 따로 모아둬요!

근데 opencode & omo 를 쓰시면 .sisyphus 경로에 자동으로 저장이 되긴 합니다.

plan.md 를 작성했으면 이제 이를 기반으로 작업을 합니다!

opencode + omo 에서는 원래 /start-work 라는 사전 명령어를 사용해서 시작합니다. 그러면 .sisyphus 경로에 자동 저장된 plan 찾아서 바로 작업을 이어가고, agent 에게 일을 할당해주기 시작합니다!

제가 쓰는 AGENTS.md 에 따르면 go 라는 시그널만 주는데, 이는 좀 때에 따라 다르게 하긴 합니다. ulw 가 필요하다 싶으면 Sisyphus 를 사용합니다!

여러 에이전트에게 자동 분할 및 위임되고, 병렬로 작업되는 것을 확인할 수 있습니다. 가장 좋은건, opencode 가 "에이전트의 실행 상태" 에 대해 개괄적으로 모니터링하는 GUI(TUI)가 타 native cli (claude, codex 등) 보다는 좋다는 점!

plan 규모가 좀 있다면 무조건 검토를 시킵니다.

plan.md 기반으로 모든 사항이 적용되었는지 A to Z 를 검토해야 해.
아래 사항에 따라 검토하되, 체크 박스도 모두 제대로 처리 해.

1. AGENTS.md 와 SYSTEM_DESIGN.md 를 1순위로 따르고 있는지 체크.
2. 변경에 따른 하위호환성과 영향 범위를 절대 잊지말고 더블 체크.
3. 관련된 테스트 코드 역시 업데이트 되어야 해.
4. 관련된 테스트가 과하거나, 중복되거나, 이미 자명한데 쓸데없는 테스트를 하거나 하지 않는지 체크
5. 2025년, 2026년 외부 공식 자료와 외부 best example 을 참고해서 개선해줘. 최대한 비판적으로 수용하고 지금 코드를 업데이트 해야 해.

이를 위해 다양한 모델과 서브에이전트를 적극적으로 활용해.

3) 다음 턴 부터는 상황에 따라

저는 Plan 을 한 번 하면 검토를 하고, 검토 output 이 최종이라고 생각하며 자체 H-I-L(human in the loop), E2E 를 합니다.
그 과정에서 리팩토링 & 세부 피쳐를 작업할땐 바로 plan 을 짜지 않고 이때부턴 기본적인 AI md (AGENTS.md 등) 만 활용하고 *skill 을 적극적으로 사용* 합니다.

지금은 거의 3가지 중 하나를 쓰게되더라구요. 특히 제일 많이 쓰는건 ui-ux-pro-max

이런식으로 skill 과 하네스를 섞어서 쓰기도 합니다. 이땐 작업 범위가 좁을수록 output 이 좋았습니다.

4) 절대 AGENTS.md, SYSTEM_DESIGN.md 등을 그대로 두지 않습니다.

진행할 수 록 layer 는 많아지고 무조건 프로젝트는 복잡성이 올라갑니다. 그래서 무조건 이 AI를 위한 마크다운을 초기설정 그대로 두지 않습니다!
무조건 프로젝트 현 상태에 따라 맞춰 업데이트를 합니다! 일례로, 동시성에 대한 경고, web이 아닌 OS응용 프로그램, GUI를 위한 룰, 또는 FE 작업할땐 "DESIGN_SYSTEM.md" 도 만드는데, 이 디자인 룰 역시도요.

최대한 영어로, 최대한 핵심만 짧고 요약해서

AI를 위한 마크다운은 무조건 토큰에 영향을 주고, 이는 비용과 퍼포먼스에 영향을 줄 수 밖에 없습니다. 그래서 저는 무조건 영어로, 최대한 짧고 굵게 작성하려고 합니다.
특히 AGENTS.md 와 같이 기본적으로 에이전트가 물고가는 마크다운 파일은 더욱더요!

5) 한 세션이 너무 길어진다면?

멀티 에이전트는 보통 아래 흐름입니다. (실제로 위에서 사용한 흐름이 모두 아래와 같죠.)

Research Agent
   ↓
Planner Agent
   ↓
Implementation Agent
   ↓
Reviewer Agent
   ↓
Documentation Agent

한 세션에서 너무 볼륨 큰 작업을 하거나, 계속 한 세션에서 작업을 길게 이어간다면, 초기 지시 사항을 잊을 수 도 있습니다! 대표적으로 아래와 같은 허들, 이슈가 있죠.

긴 세션에서 컨텍스트가 사라짐
다른 에이전트가 작업을 이어받을 때 맥락 손실
작업 상태 / 결정 / 다음 단계가 사라짐

그럴때마다 ctrl + c 로 취소하거나 /new 로 바로 새로운 세션을 시작할 필요가 없습니다!

/handoff 를 쓰면 됩니다!
/handoff 는 현재 에이전트나 세션의 작업 상태(context)를 다른 에이전트 또는 다음 단계의 작업으로 넘기는 작업 전달 메커니즘입니다.

자동으로 위 프롬프트가 세팅되고, 바로 그 다음 사진과 같이 핵심 작업이 자동으로 요약이 됩니다. (현재 작업 목표, 지금까지의 결정, 구현된 내용, 남은 작업, 다음 담당자)

그냥 심플하게 새로운 세션으로 가서 해당 내용을 그대로 복사해서 사용하면 끝!

6) 정리

정리해 보면 opencode + OMO 세팅에서 아래 4~5가지 흐름으로만 사용하는 것 같습니다.

프로젝트 세팅부터 AI 마크다운들 포함해서 제대로.
불확실한 요구사항/큰 작업
- Prometheus (Plan Builder) 로 plan
- 때에 따라 Atlas (Plan Executor) 또는 Sisyphus (Ultraworker) 를 통해 ulw 를 붙여 병렬 실행을 유도(하네스 최대 가동).
레거시 코드 파악이 먼저인 작업
- 프롬프트에 find 또는 search 를 포함해 탐색 모드로 시작
- @explore 에게 “진입점/핵심 모듈/핫스팟 파일”을 먼저 뽑게 하고(쓰기 제한이 있어 안전), 이후 Build로.
디버깅/근본원인 분석
- 프롬프트에 investigate를 넣어 분석 모드로 전환
- 설계/논리 검토는 @oracle 을 “읽기 전용”으로 붙여 객관화
볼륨이 크지는 않지만 특정 부분 (또는 역할) 만 업그레이드 할 경우
- 스킬과 하네스 섞어서 사용
- 적극적으로 "외부 공식 자료와 외부 best example" 을 search 하게 유도

특히 3번 4번은 오픈소스 코드들 또는 이미 볼륨이 있고 커진 프로젝트에서 특정 부분만 집중할때 꽤나 좋았었습니다. 요즘처럼 AI 관련 stack들이 생명주기가 반년도 안되는 시대에 이런 접근이나 방법들이 또 언젠가 레거시 처럼 여겨질지도 모르겠네요..!

PS...

아! 가끔 자기전에, 외출전에 랄프(Ralph Loop)를 가동하긴 합니다. 근데 개인적으로 랄프보단 ulw 를 프롬프트로 자동회귀하게 세팅하는게 체감 성능이 좋더라구요..
plan 을 가득 가득 만들어두고 한 호흡으로 진행하라는, 즉 무조건 끝날때까지 진행하는 프롬프트와 ulw 돌리시면 토큰 사용 다 할때까지 돌아가는 마법을 보실 수 도 있습니다..
opencode stats 를 한 번 입력해보세요! - https://opencode.ai/docs/cli/

저는 Cache Read 에 24억 7,120만 토큰 정도 사용했네요! ~~캐시라서 정말 다행~~ 약 30일간 총 27억 토큰 정도 사용했습니다. (그 이상의 기간은 비밀입니다.. 저도 알고싶지 않았습니다..)

출처

[책 리뷰] 우리, 프로그래머들 - 로버트 C. 마틴

Sun, 08 Feb 2026 17:26:52 GMT

[ "길벗 출판사에서 책을 협찬 받아 작성된 서평입니다." ]

우리, 프로그래머들

로버트 C. 마틴: 로버트 C. 마틴(엉클 밥)은 1970년부터 프로그래머로 일해 왔다. 그는 엉클 밥 컨설팅(Uncle Bob Consulting, LLC)의 설립자이며, 아들 미카 마틴과 함께 클린 코더스(Clean Coders, LLC)를 공동 설립했다. 각종 업계 저널에 글을 수십 편 기고했고, 국제 콘퍼런스와 전시회에서 정기적으로 강연하고 있다.

저서 및 편저로는 『Designing Object-Oriented C++ Applications Using the Booch Method』, 『Pattern Languages of Program Design 3』, 『More C++ Gems』, 『Extreme Programming in Practice』, 『Agile Software Development: Principles, Patterns, and Practices』, 『UML for Java Programmers』, 『Clean Code』, 『The Clean Coder』, 『Functional Design: Principles, Patterns, and Practices』 등이 있다. 소프트웨어 개발 업계의 선도적 인물로 3년간 ‘The C++ Report’의 편집장을 지냈고, 애자일 얼라이언스(Agile Alliance)의 초대 의장을 맡았다. 개발자에겐 너무 익숙한 우리 엉클밥 형님..

🔥 길벗 책 링크 - https://gilbut.co/c/26015205VE

리뷰

요새 개발자의 미래에 대한 글과 견해가 쏟아져 나옵니다. 더구나 온라인 세션, 멘토링을 하다 보면 “AI가 코딩 다 하는데 왜 배워요?”, “개발자는 이제 뭐가 남아요?” 같은 질문을 정말 자주 받습니다. 하꼬인 저도 그러는데 로버트 C. 마틴(엉클 밥)은 이런 질문을 얼마나 오래, 얼마나 많이 받아왔을까 싶어 웃음이 나기도 했습니다.

그 쏟아지는 담론 중 제가 가장 오래 붙잡게 된 키워드는 “대체”가 아니라 업의 재정의였습니다. 개발자는 사라지느냐/남느냐의 문제가 아니라, ‘개발자’라는 직업이 어떤 핵을 중심으로 다시 정의되느냐의 문제라는 관점입니다. 웹 퍼블리셔, 웹 디자이너가 “증발”하지 않았듯이, 다들 역할과 책임이 재배치되며 타이틀과 경계가 다시 그려지는 중이니까요.

최근에 꽤 재미있게 본 *"AI가 코딩 다 하는데 왜 배워요?" 에 대한 하버드 세션을 공유합니다. >> 1편, 2편* 거시적으로는 이 책이 말하는 바와 꽤 닮아 있다고 느꼈습니다.

추가로 Velog 에서도 아주 감명깊게 읽었던 테오님의 AI 시대의 개발자: 현업 개발자의 솔직한 이야기 도 같이 붙여봅니다!

*이 책은 “미래 예언서”가 아니라 “정체성의 정의서”에 가깝다!*

책 자체는 자서전을 포함한 에세이에 매우 가깝습니다. 처음에는 솔직히 “내가 말이야~ 수십 년을 했는데~ 미래는 이래~” 같은 류의 에세이라고 짐작했습니다. 그런데 실제로는 반대에 가까웠습니다. 이 책은 프로그래밍/컴퓨터 영역에서 ‘사실’과 ‘계보’를 쌓는 데 유난히 집요합니다.

그리고 그 사실들의 누적이 결국 1장(그리고 후반부 20장)에서 나오는 “미래에 대한 태도”를 떠받치는 근거가 됩니다. 저는 이 구조가 매우 설득력 있게 다가왔습니다. “내가 이렇게 생각한다”가 아니라, “내가 이런 사실들을 지나왔고, 그래서 이런 결론에 닿았는데, 당신은 이 사실들을 보고 무엇을 그리겠는가” 쪽에 더 가깝게 읽혔습니다.

*근데 좀 의아한 건 AI에 대해 생각보다 많이 냉소적으로 평가했다는 점*

좀 더 찾아보니 책의 초안이 2023년 말 ~ 2024년 사이에 작성되었다고 하네요. 놀랍게 여기에 대해 리서치를 좀 해보니 같은 의문을 가진 사람이 리서치 내용을 요약한게 있습니다! (클릭)

*책 소개에서는 각 부를 아래와 같이 설명합니다.*

1부에서 우리의 정체성을 되짚고, 2부에서 거장들의 길을 따라가며, 3부에서 저자의 경험을 통해 전환점을 마주하고, 4부에서 우리가 맞이할 미래를 바라본다.

저도 이 흐름에 거의 동의합니다. 특히 1부/2부가 책의 절반 이상을 차지하는 이유는, ‘미래’보다 ‘뿌리’를 보여주기 위해서라고 느꼈습니다. 개발자라는 역할의 시발점, 존재 가치, 정체성. 전쟁과 알고리즘, 루틴과 서브루틴, 추상화의 탄생 같은 이야기들이 여기서 살아납니다.

읽는 내내 대학 1학년 때 배웠던 개론 수업의 기억도 자꾸 떠올랐습니다. 저는 오히려 그때보다 한참 뒤에 개론을 더 깊게 찾아보고 공부했습니다. 그리고 C를 제대로 배울 때(재수강했을 때), 포인터와 주소, 메모리, 컴퓨터 구조, 운영체제의 가상 메모리가 하나로 맞물리며 머릿속에서 “번쩍”하던 순간—마냥 어렵기만 했던 공학적 지식이 실제 코딩 경험과 함께 퍼즐처럼 맞춰지던 순간을 아직도 잊기 어렵습니다. 비록 그 코드가 단순 출력 함수 호출이었더라도요.

그리고 지금은, 언어를 “학습해서 사용”하는 건 이미 너무 쉬워진 세상입니다. 그래서 모두가 학습의 재정의, 일의 재정의를 이야기합니다. 저 역시 1년 전과 비교하면 일을 처리하는 방식이 하늘과 땅 차이입니다.

그럼 순수 작업 시간이 줄었는가? 솔직히 꼭 그렇진 않습니다. 다만 단위 시간에 처리할 수 있는 일의 양이 체감상 5배 이상 늘었고, 퀄리티가 떨어졌다고 느끼지도 않습니다. 저는 여전히 ‘바이브 코딩’을 하진 않습니다. (솔직히 한 끗 차이긴 합니다. 그런데 그 한 끗이 진짜 큰 차이를 만든다고 믿습니다.)

바이브 코딩과 LLM에 대한 대규모 서베이, 논문 리뷰 와 켄트 벡(Kent Beck) 형님과 함께하는 Augmented Coding, "증강 코딩" 글 참조

체감적으로, 예전에는 [설계 & 문서화 & 구현(테스팅/코딩)/리팩터링] 의 비중이 대략 3, 3, 4 정도였다면, 지금은 6, 3, 1 정도로 바뀌었습니다. 그리고 “코딩 & 리팩터링”은 무조건 diff(view diff)로 달라진 부분 위주로 끝까지 눈으로 최종 검토 합니다. 저는 이 변화가 “AI가 코딩을 대신해 준다”의 결론이라기보다, 사람이 책임져야 하는 지점이 더 선명해지는 방향 이라고 느낍니다.

2부의 거장 파트는 디지털 논리 회로와 컴퓨터 구조에 대한 기본적인 이해—적어도 진공관, 레지스터, 플립플롭에 대한 최소한의 감각—이 없으면 솔직히 지루할 수도 있습니다. 그런데 저자가 풀어내는 방식은, 이해가 부족해도 몰입할 수 있을 만큼 ‘이야기’로 설계되어 있다고 느꼈습니다. (그리고 그 몰입이 결국, “지금 우리가 쓰는 추상화들이 어디서 왔는지”를 체감하게 만듭니다.)

3부는 엉클 밥이 살아온 환경에서 컴퓨터와 프로그래밍이 얼마나 폭발적으로 성장했는지를 보여줍니다. 자연스럽게 개론과 저자의 배경 위로 올라타게 되고, 정말 거시적인 관점에서 “미래가 어떻게 될지”(정확히는 저자가 어떤 미래를 상정하는지)가 어렴풋이 보이기 시작합니다.

저도 변화의 흐름이 파도처럼 거대하다고 느끼지만, 90년대 태생인 제가 체감하는 변화조차 엉클 밥 같은 형님이 눈앞에서 겪었던 변화의 결에 비하면 “생각보다 빠른 게 아닐 수도 있겠다”는 상대화가 되기도 했습니다.

그리고 4부에서 책은 덤덤하게 마무리합니다. 과장된 예언 대신, “프로그래밍의 핵은 생각보다 잘 안 바뀐다”는 태도에 가깝게요. 다만 그 덤덤함이 체념은 아니었습니다.

목차별 리뷰

1부. 서막을 열며

1장. 우리는 누구인가?

1장의 기능은 “정의”다. 프로그래머를 ‘문제를 해결하는 사람’으로만 두지 않고, 디테일을 사랑하고 조합하여 의미를 만드는 사람으로 다시 규정한다. 이 규정은 기술 스택의 변화(언어/프레임워크/플랫폼)를 뛰어넘어, 직업적 정체성의 코어를 고정시키는 문장처럼 작동한다.

“디테일”이라는 단어가 AI 시대에 더 도발적으로 들리는 이유는, 생성형 AI가 바로 그 디테일(코드/문장/구현)을 대량 생산하기 시작했기 때문이다. 그러나 여러 서평이 공통으로 붙드는 축은 "산출물"이 아니라 "책임"이다.

내가 느낀 1장의 정의는 “AI가 대체할 것/못할 것”을 나누는 얄팍한 직업 전망이 아니라, AI와 함께 일할 때 무엇을 끝까지 붙들 것인가를 묻는 선언에 가까웠다.

PS. 사실 1장이 책에서 하고 싶은 말을 다 담고 있다는 걸, 다 읽고 다시 깨닫게 되었다.

2부. 거장

2장. 배비지, 최초의 컴퓨터 엔지니어

“명령어(카드)와 데이터(숫자계기)의 분리”라는 감각은, 오늘날 관점에서 보면 너무 당연해 보이지만, 당시에는 “계산을 하는 장치”를 “계산을 기술하는 장치”로 끌어올리는 발상이었다.

배비지 장에서 인상적인 것은, 천재성보다도 실패의 형태다. 차분기관이 “실패했다”는 사실보다, 실패가 남긴 유산(레지스터적 사고, 반복 가능한 연산 단위, 표준화된 절차)이 더 중요하다.

3장. 힐베르트, 튜링, 그리고 폰 노이만: 최초의 컴퓨터 아키텍트

3장에선 힐베르트의 아래 3가지가 주요 내용이었다.

힐베르트의 공리화 시도 → (괴델) 불완전성의 충격
그 흐름이 “증명=알고리즘(절차)”로 이어진다는 통찰
그 다음, 계산 장치의 설계 철학(내장식 컴퓨터)로 연결

1) 수학의 충격(형식체계의 한계)

“수학 전체를 공리화”하려는 열망과 그 좌절은, ‘인간이 완전한 체계를 만들 수 있다’는 낙관의 붕괴로 읽힌다.
하지만 “폰 노이만이 자연수는 러셀의 역설에 해당하지 않는다” 는 서포팅도 있었다.

2) 계산의 정의(Computability)

배비지 해석기관이 명령어(나무카드 구멍), 데이터(회전식 숫자계기) 완전 분리된 방식이 포인트였고, 이를 튜링이 해당 사고를 확장했다. 튜링머신이 제공한 것은, ‘컴퓨터’가 아니라 “무엇이 계산 가능한가”에 대한 정의였다.
계산 가능성을 엄밀히 정의할수록, “계산 불가능한 것(혹은 계산 비용이 과도한 것)”이 더 선명하게 남는다.

PS. 독일에서 폰(von) 귀족 칭호라고 한다.

위 그림은 튜링 머신의 계산 방식을 도식화 한 그림이다. 책에서는 전혀 다른 표를 활용한다.
서브루틴(재사용) 개념과 상태 전이의 압축(표를 다 들고 있지 않아도 되는 방식)
SD(표준 기술)로 “프로그램을 숫자/기호로 표현”
그 SD를 테이프에 담아 실행하는 U(범용 기계)

이 흐름은, 오늘날 관점에서 “해석기/컴파일러/VM/런타임”으로 계속 환생한다.
다익스트라 장에서 언급한 P-코드와 런타임(가상 머신과 닮음)까지 연결하면, 2부의 거장들은 서로 떨어져 있지 않다. 같은 아이디어가 다른 언어로 재등장한다.

더욱이 "존 폰 노이만이 작성" 이 작성한 EDVAC(에드박) 설계 초안, [ 입력, 출력, 연산, 제어, 기억 장치 ] 구성 요소 다섯개, 오늘날까지 사용하는 내장식 컴퓨터 기초가 된다.

PS. 여기서 전쟁에 대한 얘기, 탄도연구소를 넘어 맨해튼 프로젝트 (오펜하이머 영화 ㅎㅎ), 마크 I 와 ENIAC(에니악)을 경험. 트리니티 프로젝트에 대한 얘기가 나온다.

4장. 그레이스 호퍼: 최초의 소프트웨어 엔지니어

개발자라면 누구나 겪어본 그것! '버그'를 발견한 최초의 프로그래머, 그레이스호퍼

주석, 서브루틴, 멀티프로세싱, 개발 방법론, 디버깅, 컴파일러, 오픈 소스, 사용자 계정 및 그룹, 주소, 이진수, 비트, 어셈블러, 브레이크포인트, 문자, 코드, 디버그, 편집... 이 모든 개념에 그레이스 호퍼의 노력이 묻어있다고 한다.

호퍼가 밀어붙인 것은 “추상적 언어 → 자동 변환(컴파일)”이었다. 여기서 핵심은 기술이 아니라 사회적 합의다. 당시에도 “천공판 구멍 뚫는 사람 다 어디감?” 같은 공포가 등장했고, 그 공포는 단순히 무지의 산물이 아니라 생계의 문제였다.

그런데도 호퍼의 방향은 분명하다.

더 읽기 쉽고 쓰기 쉬운 표현
더 많은 사람이 협업 가능한 언어
기계어로 내려가는 과정을 자동화

AI가 코드를 만든다는 말이 결국 “더 높은 추상화로 올라간다”는 말이라면, 호퍼의 자동 프로그래밍은 전례라고 볼 수 도 있다. 개인적인 견해로 그레이스 호퍼 얘기를 굳이 현 시대의 AI 확장에 대한 해석을 붙이자면, 나는 아래 2개가 중요하다 이해되었다.

(일부 역할은 줄거나 바뀌지만) 전체 산업의 총량은 오히려 커진다.
문제는 기술이 아니라, 전환을 관리하는 사회적/교육적 장치다.

그녀는 해군에 입대했으며, 그 경험이 그녀를 ‘진정한 소프트웨어 엔지니어’의 길로 이끌었다. 처음에는 암호 해독 업무를 하게 될 것이라 예상했지만, 결과적으로 세계에서 두 번째 컴퓨터로 알려진 자동 순차 제어 계산기(ASCC, Mark I의 다른 이름)에서 부책임자이자 세 번째 프로그래머로 일하게 된다.

Who Invented the Mark I Computer?

베티 스나이더의 사례도 흥미롭다. 정렬은 ‘매개변수’에 따라 동작했다. 여러 레코드를 정렬하려면 정렬 기준이 되는 필드의 위치, 크기, 정렬 방향 같은 정보가 필요하고, 이 매개변수를 입력받아 레코드를 정렬하는 방식으로 일종의 “프로그램 생성”이 가능했던 셈이다.

그리고 핵심은, 호퍼가 그 무렵 ACM 논문을 통해 “자동 프로그래밍”을 언급했다는 점이다. 그러자 곧바로 “천공판 구멍 뚫는 사람 다 어디감?” 같은 두려움이 따라붙는다. 다만 이 변화는 대체(replace)라기보다 완화(relieve)에 가까웠다는 맥락으로 읽힌다. A형 컴파일러가 등장하고, 프로그래머의 일자리를 빼앗을지 모른다는 공포가 생기면서도 A-1, A-2 개발이 가속화되고, 이어 A-3(일명 B형 컴파일러)로 이어진다. MATH-MATIC 언어도 그 흐름 안에 있다.

또 한 가지 인상적인 지점은 표현 방식의 선택이다. 호퍼는 A × B = C 같은 수학적 표기 대신, 비즈니스와 더 일반적인 대중을 위해서는 아래처럼 문장형 표현이 선호될 수 있다고 판단한 것으로 정리된다.

MULTIPLY BASE-PRICE AND DISCOUNT-PERCENT GIVING DISCOUNT-PRICE

이러한 맥락에서 영어 기반 언어인 B-0 개발로 이어지고, “추상적인 언어가 프로그래머들이 훨씬 자유롭게 협업할 수 있게 해준다”는 관점이 강조된다. 그리고 COmmon Business-Oriented Language, 즉 코볼(COBOL)의 탄생으로 연결된다. (놀랍게 아직도 살아 있다. 전 세계 금융 트랜잭션의 약 70~80%가 코볼로 작성된 시스템을 거치는 것으로 추정)

5장. 존 배커스: 첫 번째 고수준 언어

하이파이 오디오에 빠져 있던 시절, 훌륭한 스승을 만나 수학으로 방향을 틀었다. 이후 IBM 시설을 구경하던 중 SSEC 프로그래머로 취업했고, 이 일을 계기로 본격적으로 프로그래밍의 세계로 들어간다.

한국 전쟁 시기, IBM의 군수 컴퓨팅 맥락에서 IBM 701이 등장한다. 배커스가 SSEC 다음으로 마주한 대상이 바로 이것이었다. 완전한 전자식 컴퓨터였고, 진공관이 약 4천 개 들어갔다.

현대와 달리 IBM 701에서는 반복문이나 배열 순회를 구현하려면 명령어 자체를 바꾸는 기법이 필요했다. 입력 처리까지 포함해 전반적으로 번거로운 작업이 많았는데, 배커스는 이를 줄이기 위해 “스피드코딩(Speedcoding)”이라는 프로그램을 만든다.

본인 표현으로는 “게으름 때문”이었다고 한다. 부동소수점 연산을 지원하는, 일종의 인터프리터에 가까운 도구였고, 인덱스 레지스터 증가 또는 감소 작업 수행, 간접 주소 지정 같은 기능도 제공했다. 한때 A-0 컴파일러를 폄하하기도 했고, 이후 FORmula TRANslation—포트란(Fortran)이라는 이름의 “예비 보고서”로 이어진다.

6장. 에츠허르 다익스트라: 첫 번째 컴퓨터 과학자

GOTO문을 쓰지 말자고 강조한 인물 중 하나다. 세마포어 개념을 처음 고안했고, 여러 유명 알고리즘을 만들었으며, ALGOL 60 컴파일러 최초 버전 공동 개발 등으로도 알려져 있다. 네덜란드 로테르담 출신. 초반에는 프로그래밍 자체보다 이론 물리학자로 성장하려 했지만, 빈가르덴의 영향이 인생의 전환점이 된다.

다익스트라는 “호출 가능한 서브루틴”의 장점을 분명히 본 사람이다. 제어 흐름이 동일한 명령어 집합을 한 번만 정의해 두고 필요할 때 실행할 수 있다면 얼마나 좋은가를 언급했고, 호퍼식의 “명령어 중복” 방식은 비효율적이며 메모리 낭비라고 봤다.

다익스트라 알고리즘은 최단 경로 알고리즘이다. (요즘은 모르겠지만, 나의 시대에는 꽤 단골 문제였다.) 한 지점에서 다른 특정 지점(혹은 모든 다른 지점)까지의 최단 경로를 구한다. “로테르담에서 흐로닝언까지 가장 짧은 길을 어떻게 찾지?” 같은 질문에서 출발해 설계한 알고리즘으로, 20분 만에 아이디어를 떠올렸고 논문 완성까지는 3년이 걸렸다고 한다.

너무 TMI지만, 나는 이 내용이 유독 기억에 남는다. 네덜란드에 교환학생 경험이 있었고, 사실 나는 네덜란드를 굉장히 IT 친화적으로 생각했다.(python..) 그리고 헤이그에 있으면서 로테르담, 흐로닝언까지 자전거를 타고 다닌 적이 있기 때문이다 ㅎ

하여튼, 이 알고리즘을 기반으로 ARMAC의 성능을 보여주려고 했었다. 그런데 이 코드를 포인터 없이, 재귀 없이, 심지어 서브루틴 호출 명령어조차 없이 작성해야 했다. 각 명령어의 내부 주소를 직접 수정해야 했고, 드럼 메모리와 코어 버퍼 사이에서 데이터가 밀리거나 덮어쓰이지 않도록 최적화도 직접 해야 했다. 아찔한 제약이다.

심지어 차기 컴퓨터 X1의 뒷판 구리 회로가 비싸서, 구리 배선을 최적화하기 위한 “MST(최소 신장 트리)” 알고리즘까지 활용했다.

다익스트라와 존테벨트는 언어와 기계 사이에 추상화 경계(abstraction boundary)를 만들어, 당시 다른 팀보다 앞서나갈 수 있었다. 컴파일러가 ALGOL을 P코드(포터블 코드)로 내리고, 별도의 런타임이 이를 해석해 실행하는 구조였는데, 이 런타임은 오늘날의 가상 머신(VM)과도 닮아 있다.

이후 멀티프로그래밍 시스템 프로젝트를 시작한다. 당시로서는 매우 독창적이었다. 이를 위해 HW level에서 상위 계층이 하위 계층의 복잡한 내부 동작을 알거나 의존하지 못하도록 만들었다. 그리고 여기서 세마포어가 등장한다. 동시 실행되는 프로세스들이 공유 자원을 업데이트할 때 생기는 race condition을 다루는 방법이다. 이 과정에서 “임계 구역(critical section)”과 “불가분 연산(indivisible action)” 같은 용어도 도입된다.

나아가 다익스트라 팀은 해당 시스템의 정확성을 “수학적으로 증명했다”고 믿었다. 「프로그램의 신뢰성에 대하여」 같은 글에서 “프로그래밍은 점점 더 수학적인 활동이 될 것이다”라고 주장하기도 했는데, 저자 관점에서는 이것이 오판이라고 본다.

본질적으로 수학 OK, 두 분야의 접점도 당연히 OK다. 그런데 문제는 “증명”으로 접근했다는 점이다. 그리고 소프트웨어가 그 증명으로 이루어진 수학적 시스템이 되리라 생각했던 것 같다. 지금 보면, 누구도 위와 같은 수학적 증명을 실제 개발에서 하지는 않는다. 소프트웨어 세계의 ‘기하학 원론’은 없고, 앞으로도 없을 것이다. 저자는 소프트웨어가 수학이라기보다 과학에 가깝다고 보기 때문이다. 과학은 어떤 이론이 “옳다”를 증명하는 접근이 아니라, 그 이론이 틀렸다는 것을 관찰할 수 있는가에 가깝다. 소프트웨어를 만들면 “잘 설계된 테스트를 통해 프로그램이 잘못되었는지 관찰하고 오류를 찾아낸다”는 방식이다.

그리고 다익스트라의 “구조적 프로그래밍”이 이어진다. GOTO문에 반대하는 논거를 발표했고, 시장에 파장을 일으켰다. (네, Verilog 하시는 분들은 여전히 GOTO를 볼 수 있습니다.) 순차, 선택, 반복 세 가지만으로 프로그램을 구성하자고 제안한다. 왜 이런 구조인가? → 수학적 증명을 하지 않아도, 코드 자체가 “증명 가능”하도록 만들기 위해서다. 단순히 GOTO를 없앤 것 이상으로, 만들어낸 가치는 크다고 본다. 아키텍처 관점까지도.

7장. 니가드와 달: 첫 번째 OOPL && 8장. 존 케메니: 모두를 위한 첫 번째 언어, BASIC

니가드와 달은 "객체 지향의 발전" 얘기다. SIMULA 67 와 같은 최초 객체 지향 프로그래밍(Object-Oriented Programming Language)이 등장했고 이는 C++ 창시자에게도 영향을 줬다.

더욱이 클래스와 서브클래스 선언 논문 발표하며 "처음으로 객체 용어" 사용 했다.

존 케메니 얘기는 누구나 프로그래밍 영역 접근 할 수 있어야 한다고 믿었던 프로그래머들의 여정에 대한 얘기다. 하지만 자기 천재성에 스스로 눈과 귀 닫아버린 이들의 이야기이기도 하다.

그리고 폰 노이만의 First Draft of a Report on the EDVAC 비공식 문서 보고 엄청 큰 깨달음 얻었다고 한다.

"타임셰어링 혁명" 을 만들었지만 시장에서 고집으로 인해 역사속으로 사라졌다.

9장. 주디스 앨런 && 10장. 톰프슨, 리치, 커니핸

위 2장은 직접 책에서 보길 바란다. 특히 10장의 C언어 얘기, 독자들이 꽤 시대적 흐름으로 더 많은 동감을 할 수 있지 않을까 생각한다.

3부. 급격한 전환점

1970년대부터 2020년까지 얼마나 폭발적으로 성장했는지!

11장. 1960년대

"반(反)문화의 시기" 라고 정의한다. 어릴 때 Digi-Comp I 기계를 가지고 놀며 플립플롭을 “장난감”처럼 다뤘는데, 그걸 제대로 쓰려면 결국 매뉴얼을 공부해야 했다. 그 경험을 바탕으로 릴레이 장치로 더 다양한 시도를 해보고, 트랜지스터·저항기·커패시터 같은 부품을 직접 배우고 만들고 조립해 본 기억이 이어진다.

고등학교에서는 ECP-18을 통해 전자식 컴퓨터 세계를 처음 제대로 경험했고, 이때 첫 프로그래밍 시도가 나온다.

12장. 1970년대

16세에 프로그래머로 일을 시작했다. EASYCODER 책과 함께 허니웰 H200 시리즈용 어셈블리 언어를 다루며, 펀치 카드 더미를 실제로 겪는다. 이후에는 프로그래머 애널리스트 경험도 하고, 대형 미니컴퓨터 프로젝트에 참여했으며, 컴퓨터로 제어되는 레이저 절삭 시스템까지 경험한다.

특히 이 시기에는 여유 시간이 있어 팀과 “방식”에 대한 깊은 논의가 가능했다고 한다. 정렬 알고리즘, 탐색 알고리즘, 인덱싱 방식, 큐잉 방식 등

이직 후에는 System/7을 위한 어셈블리 경험을 하고, 그러던 중 “구조적 프로그래밍 (다익스트라)”의 *"GOTO 가 해롭다는"* 글을 보고 충격을 받는다. System/7에 곧바로 적용하면서 받아들였다고 한다 ㅎ.

"서브루틴은 좋은 것이지만, 모듈 사이를 마구 뛰어다니는 점프는 나쁘다" 이 구분에 완전히 매료된다. 그리고 이에 대한 글을 쓰고, 인생 첫 출장 비행을 하고, 프로그래머 그룹을 처음으로 교육하는 경험도 한다.

그러다 해고를 당하고 TAS로 돌아간다. 일종의 스타트업 같은 곳이었다. 개인을 갈아 넣으며 돌아가는 시스템. 많은 프로젝트, 많은 경험, 압도적으로 많은 코드 경험이 쌓인다. 후반부로 갈수록 컴퓨팅 능력 자체가 커지면서 시장도 더 빠르고 크게 성장한다.

13장. 1980년대

벨 텔레콤과 미팅 기회가 생겨서 “MLT 엔지니어는 어떤 언어를 쓰냐?”라는 질문에 돌아온 답은 "당연히 C였다." 거기에 꽂혔다. 바로 책을 사서 읽었고, 빠져들어 “C 컴파일러를 반드시 구해야 한다”는 생각까지 하게 된다.

회사에서는 시스템 관리자가 된다. 80년대 전화 회사들의 디지털 혁명 배경에는 구리 가격 상승이 있었다. 엄청난 양의 구리선을 회수하고 싶었고, 오래된 릴레이식 스위치를 디지털 스위치로 교체하는 대대적인 아키텍처 변화가 진행된다. 이 과정에서 C와 BOSS를 적극적으로 사용한다.

수년간 몰두하게 만드는 거대한 프로젝트도 이어진다. (E.R. 특허/프로젝트 등)

그리고 애플 II가 등장한다. 회사 사무실에 개인용 컴퓨터가 들어오고, 스프레드시트가 실제 업무 도구가 된다. 이어지는 매킨토시까지. 흥미로운 점은, 이 시기에 폭포수 프로세스가 아니라 특별한 제약 없이 칸반을 이용해 개발했다는 대목이다.

E.R 프로젝트는 H/W, N/W까지 포함해 밑바닥부터 만들었지만 시대 흐름과 맞지 않았던 것 같다고 한다. 프로젝트와 특허는 모두 무산. 개인용 컴퓨터 보급이 본격화된다. 이후 GUI와 개인용 서비스 몇 가지(wator 등) 개발, 그리고 객체 지향에도 도전한다.

14장. 1990년대

시장의 낙관적인 전망과 빠른 성장이 이어지며 “성장”이 눈에 보이던 시대. 동시에 세계 전쟁, 테러 사건 같은 균열도 함께 있었다. 닷컴 버블로 절정까지 치닫는다.

스타트업 경험, 인터넷 경험, 온라인 세상의 체감이 깊어진다. 선 마이크로시스템스에서 C++ 컴파일러가 등장하고, 유즈넷/뉴스그룹에 가입해 폭발적인 성장의 공기를 직접 겪는다. 저자가 감명 깊게 본 그래디 부치의 도 나온다. (불확실한 정보지만 아직 대학교 강의 교재처럼 쓰는 곳이 있는 것 같기도 하다.)

회사는 사업적으로 어려웠지만 경력은 오히려 상승 곡선을 탄다. 뉴스그룹 활동이 주목을 받으며 글 투고를 시작한다. 그러다 헤드헌터에게 전화가 온다(래셔널 와라!). 인하우스로 가는 대신 역으로 컨설턴트를 제안했고, 그 제안이 받아들여진다. 이후 이것이 싹이 되어 프로그래밍 컨설팅 역량을 펼친다. 그중 비네트 프로젝트를 통해 “재사용 가능한 프레임워크”의 성공과 실패를 모두 경험한다.

또한 GOF(Gang of Four)의 책 온라인 리뷰어 경험도 있다. (이 책은 언제 대체재가 나오려나ㅎㅎ.)

현 시대의 거장들 얘기가 갑자기 확확 와닿았다. 그들도 르네상스처럼 일종의 그들만의 "장" 이 있었고 그 "장"을 만들고 이어온게, 이게 정말 중요한게 아닐까 싶기도 하다.

또 저자는 켄트 벡의 XP에 큰 감명을 받아서 직접 만나 이야기한다. 이를 교육과 컨설팅으로 확장한다. TDD를 처음 경험하고 보고 느끼며 충격을 먹는다. 완전히 새로운 코딩 방법이었다고 한다.

PS. TDD는 나에게도 너무 혁명이었다. 물론 저자와 상황과 시대도 달랐었지만, 진짜로 TDD를 프로젝트에 적용했을때 그 새로움, 특히 신규 feature를 추가할때 그 쾌락을 잊을 수 가 없다.

15장. 밀레니엄

불확실성과 침체가 함께 온 시기. 9.11, 전쟁, 2008년 글로벌 금융 위기 등.

그럼에도 XP 교육과 컨설팅은 한동안 호황이었다고 한다. 소프트웨어 전문가 17명이 모여 애자일 선언문(아직 살아있다!! - https://agilemanifesto.org/iso/ko/manifesto.html)을 작성했고, 이것이 큰 파도를 일으켰다고 한다. 그러는 와중에 9.11, 그리고 2001년부터 닷컴 버블 붕괴가 시작된다.

이후 2년간 수요 감소와 침체가 이어지고, 오히려 책을 집필할 수 있었다고 한다. 이때 나온 것이 출간. 그리고 이후 집필로 이어진다.

PS. 사견으로 이 두 권이야말로 아직까지 전 세계 개발자에게 로버트 C. 마틴 “엉클밥”을 알리게 만든 결정적 계기가 아니었나 싶다.

그리고 이후에는 SICP를 기반으로 함수형 프로그래밍의 매력에 빠졌다고 한다. 생각보다 현 시대, 동시대의 거장들이 함수형 프로그래밍을 “매우 맛있게” 표현하는 경우가 있는데, 내가 느끼기엔 이게 약간 예술의 경지가 아닐까 한다.

4부. 미래

16장. 프로그래밍 언어

요즘 프로그래밍 언어 진짜 개많다. 왜 그렇게 많을까? 정말 그렇게 다양할 필요가 있을까? Java, C#, 거시적으로 객관적으로 보면 사실상 거의 동일해 보이기도 한다. 사실 우리가 “모든 것을 지배할 단 하나의 언어”, “성배 같은 언어”를 끊임없이 찾아서 그런 거 아닐까?

저자는 과거에 비해 새언어가 주는 depth 있는 메커니즘 차이가 거의 없는 것처럼 느껴진다고 한다. 그래서 이 상황을 성경 전도서의 “이미 있던 것이 다시 있을 뿐. 태양 아래 새로운 것이 없도다”에 비유하게 된다.

사실 컴퓨터 분야에서만 그런 게 아니라 다른 산업 분야에서도 비슷한 일이 반복되어 왔다. 단 하나의 언어만 남기자고 사회적 협의가 될 수도 있지 않을까? 이러면 모두가 편해질 텐데…

PS. ‘새로움’이 사라졌다기보다 새로움의 무대가 런타임/생태계/운영 비용으로 옮겨 간 것 같기도 하다. 물론 이 새로움이 저자가 원하는 니즈를 충족시키진 못할 것 같다.

PS. 근데 이제 실제로 LLM이라는 것을 “언어” 관점으로 본다면, 하나로 합일화 되고 있는 것 같기도 하다. 다만 전혀 다른 방식이긴 하지만… 이 경우의 합일화는 “프로그래밍 언어가 하나로 통일된다”기보다, 입력 방식(자연어 프롬프트) 이 통일되는 쪽에 가까워 보인다.

타입에 대한 것도, 컴파일에 타입을 검사할까, 런타임에 검사할까? 수십 년째 줄다리기. 정적 언어는 퍼즐처럼 제자리에 다 끼워야 해서 귀찮고 어려운 언어, 동적 언어는 이 단점을 상쇄하지만 그만큼 잘못 끼울 위험이 있는 것이다.

저자는 두 가지를 절충해서 "타입 검사를 형식적으로 엄격하게 하되, 런타임으로 미루자고 제안함. 그리고 언제 적용할지 프로그래머가 선택할 수 있게" 하자고 제안한다.

저자는 언어를 합일화 한다고 하면 리스프 계열 언어가 남는다고 생각한다. (매우 의외)

1) 대부분 극도로 단순함. 요즘 유행하는 언어들이 좀 과하게 문법이 방대하다고 생각함. 그래서 트릭과 기교까지 배워야 한다는 점. 2) 단순하기 때문에 생기는 표현력. 언어 제약에서 벗어나 내가 표현하고 싶은 것을 표현할 수 있게 됨. 3) 리스프는 프로그래밍 언어보다는 데이터를 표현하는 언어에 가까움. 여기에 데이터가 프로그램처럼 해석될 수 있도록 하는 런타임이 결합되어 있는 것.

이 리스프 얘기의 핵심은 결국 “단순함” 자체보다, 코드=데이터(code-as-data) 감각에 있는 것 같다. Clojure 가 리스프를 설명할 때도, 코드-데이터와 매크로 시스템이 리스프 계열을 구분 짓는 특징이라고 정면으로 말한다.

그리고 “폰 노이만 아키텍처 같다”는 비유는, 저장 프로그램 개념(명령과 데이터가 같은 저장소에 있고, 프로그램이 데이터처럼 취급될 수 있음)을 떠올리게 한다는 점에서 의미가 있다. 실제로 Britannica도 폰 노이만 머신의 원리 중 하나로 “데이터와 명령을 한 저장소에 두고, 프로그램을 데이터로 취급할 수 있다”는 점을 강조해왔다.

17장. AI

미래학자들이 우리 모두가 AI 혁명 벼랑 끝에 서 있다고 말한다. 하지만 저자는 이 기술들이 초자연적인 무언가이거나, 인간의 지능이나 창의력에 조금이라도 근접하게 될 것이라고는 보지 않는다.

그 근거로 저자는 인간의 뇌 구조와 뉴런을 꺼내 든다. 뉴런이 얼마나 강력한 계산 단위이며, 뉴런 간 연결(시냅스)의 규모가 얼마나 압도적인지 이야기하면서, “스카이넷” 같은 도약은 쉽게 오지 않을 것이라고 선을 긋는다.

실제로 인간 뇌의 뉴런 수와 시냅스 연결 수에 대한 대표적 추정치만 보아도, 규모 면에서 아직은 우리가 ‘비슷한 것’을 만든다고 말하기 어려운 구간이 있다는 느낌을 준다(뉴런 약 860억, 시냅스 약 100조 수준의 추정 등).

이어서 “신경망(Neural Nets)”으로 넘어간다. 아마 LLM을 포함한 현대 AI의 핵심을 설명하기 위한 길목이다.

여기서 포인트는 분명하다. 여전히 블랙박스이며, 가중치는 미리 예측할 수 없고, 결과값이 “어떤 공식”으로 딱 떨어지게 정해지는 것도 아니라는 것. 즉, 입력을 넣고 출력에서 원하는 것이 나오기를 “기도하듯” 바라는 상태가 생길 수 있다는 말이다. 이 문제의식은 오늘날 XAI(Explainable AI) 논의가 왜 반복되는지와도 맞닿아 있다. 딥러닝 모델은 성능이 뛰어나더라도 내부 작동을 설명하기 어렵다는 이유로 “블랙박스”로 불려 왔고, 그래서 ‘설명 가능성’이 별도의 연구 축이 되어 왔다.

저자는 “학습을 다시 시켜서 더 나아지기를 바라는 것”을 운에 맡기는 전략과 비슷하다고 본다. 그리고 신경망을 만드는 일을 소프트웨어 엔지니어링보다는 “현수교를 만드는 것에 가깝다”고 평가한다.

그런데 저자는 여기서 한 번 더 꺾는다. 신경망은 SW 없이 존재할 수 없고, 이를 둘러싼 도구와 인프라는 소프트웨어가 깊이 관여할 수밖에 없다. 다만, 그 소프트웨어는 운에 맡기는 게 아니다. 프로그래머가 다루는 본질은 여전히 결정론적 결과물이며, 애매한 희망이 아니라 확실한 이진적 사실을 다룬다는 것.

이 주장이 장 전체를 관통하는 “태도”처럼 남는다. AI가 불확실하다는 말이 곧 프로그래밍 자체가 불확실해진다는 뜻은 아니다. 오히려 불확실한 블록을 끼워 넣을수록, 주변의 결정론적 장치(검증·테스트·제약·관측)가 더 중요해진다는 뉘앙스로 읽혔다.

이 장에서 저자가 특히 강조하는 또 하나는, LLM이 현시대 “신경망의 걸작”처럼 보이더라도 지능적·창의적으로 보이는 순간들이 곧장 ‘창의성’의 증거는 아니라는 점이다.

그리고 아주 단적으로 GIGO(garbage in, garbage out) 를 떠올리게 하는 예시(학습 데이터가 범죄적이면 출력도 범죄적으로 기울 수 있음)를 통해, 결국 모델이 무엇을 반사(reflect)하는지 다시 보게 한다.

PS. 출력 품질은 곧 입력 품질(데이터·프롬프트·컨텍스트·정책)의 그림자다. 그러니 책임도 결국 ‘모델 바깥’에 남는다.

그리고 저자는 LLM을 활용해 얻어낸 코드를 직접 리뷰하면서 그 출력물을 신랄하게 비판한다. 여기서는 웃음이 나왔다ㅋㅎㅋㅎㅋㅎ. “코드는 나왔지만, 설계가 없다”는 느낌. 즉, 그럴듯한 구현은 쉽게 생성되지만, 요구사항의 모서리·예외·장기 유지보수·실패 모드·테스트 전략 같은 디테일은 여전히 사람이 붙들어야 한다는 주장으로 이어진다. (이 부분이 가장 의아했는데, 위에서 언급했듯, 최근의 의견은 조금 달라진 듯 하다.)

LXM(X 자리에 Music, Art, Code 등). LXM은 결국 도구이며, C도 도구, IDE도 도구, 결국 사람이 이용해야 한다는 것. 이때 책은 “도구가 사람을 대체한다”는 공포가 역사적으로 반복되어 왔음을 상기시킨다.

초기 프로그래머들—바이너리 코드로 직접 프로그램을 짜던 사람들—이 그레이스 호퍼의 A-0 같은 컴파일러를 두려워했지만, 결과는 정반대였다는 이야기. 실제로 호퍼의 A-0 시스템은 1952년 무렵의 초기 컴파일러(혹은 컴파일러에 준하는 시스템)로 종종 언급되며, 이후 고수준 언어와 도구 생태계의 확장을 여는 흐름에 놓인다. 요지는 “대체”가 아니라 “확장”이다.

왜 지난 세월간 전 세계 프로그래머 수가 폭발적으로 증가했는가? 저자의 답은 간결하다. 컴퓨터를 활용할 수 있는 분야가 아직도 무궁무진하기 때문이다. 그리고 “그렇다면 인간의 어떤 점 때문에 LXM이 프로그래머들을 대체할 수 없을까?”라는 질문으로 다시 돌아온다. 저자는 결국 1부 1장 “우리는 누구인가?”에서의 답, 즉 디테일을 다시 꺼낸다. 불확실한 결과를 ‘쓸 수 있는 결과’로 바꾸는 일, 맥락을 정의하고 책임을 지는 일, 실패를 설계하고 복구를 설계하는 일—이 디테일이 있는 한, 도구는 사람의 자리를 빼앗기보다 사람의 능력을 증폭시키는 방향으로 진화한다는 것이다.

장 끝에서 남는 감정은 묘하게 담백하다. AI는 불가해하고, 그래서 더 조심스럽게 다뤄야 한다. 그러나 그 불가해함이 곧바로 “프로그래머의 종말”을 뜻하지는 않는다. 오히려 프로그래머의 일은 더 명확해진다. 불확실한 것을 시스템 안에 안전하게 배치하는 사람, 그 디테일을 책임지는 사람. 저자가 말하는 미래는 그 점에서 과장되지 않는다. 다만 그래서 더 현실적이다.

18장. 하드웨어 && 19장. 월드 와이드 웹 && 20장. 프로그래밍

저자는 월드 와이드 웹의 미래를 말하면서 “브라우저 같은 것이 사라진다”가 아니라, 브라우저가 ‘인식에서 사라질 것’ 이라고 본다. 이게 가장 인상 깊었다. 마치 지금 우리가 전화번호를 외우지 않고, 통신 인프라를 의식하지 않듯이, 웹도 특정한 형태(브라우저, 주소창, 탭)로 ‘보이는 것’이 아니라 서로 소통하는 프로그램들만 남고, 사용자는 그것을 웹이라고조차 부르지 않게 될 거라는 전망이다.

그렇다면 앞으로의 프로그래밍은 어떻게 바뀔까?

저자는 지난 50년을 되돌아보며 50년 후를 상상했을 때, 자신은 여전히 if, while, 대입문 같은 기본 구문을 쓰고, 컴파일하고, 테스트하고 있을 것 같다고 말한다. 이건 보수적인 선언이라기보다 “핵심은 생각보다 잘 안 바뀐다”는 쪽에 가깝다.

더 흥미로운 건, “근래의 세월에 소프트웨어 역사상 소프트웨어 원칙에 대한 눈에 띄는 발전은 거의 없었다”는 진단이다.

구조적/함수형/객체지향이라는 세 주요 패러다임은 이미 70년대에 등장했고, SOLID 같은 것이 이후에 널리 퍼졌지만, 그 밑바탕 자체는 이미 오래전에 확립되어 있었다는 말이다. 그래서 앞으로 50년 동안 무언가가 극적으로 뒤집힐 거라는 기대를 크게 하지 않는다. 이름이 바뀌고 포장이 달라질 수는 있어도, 본질은 비슷하게 남을 거라는 태도다.

대신 저자가 “진짜로” 기대하는 건 기술의 급진적 변화가 아니라, 프로그래밍 직군에 전문 윤리와 기준, 기법이 자리 잡는 것이다. 도구나 방법론이 늘어나는 것 못지않게, “직업 윤리 의식”이 필요하다는 주장인데, 나는 이 부분이 이 책 전체의 결론처럼 들렸다. 결국 프로그래머의 미래는 더 강력한 도구가 아니라, 더 강한 책임감과 기준에서 갈린다는 식으로.

개인적으로는 이후 집필 후기와 톰 길브의 소감이 정말 재미있었다. 조금 자극적인 농담도 섞여 있는데, 예컨대 “노인은 누군가 들어주는 사람이 있으면 자신의 이야기를 무척 좋아한다” 같은 문장이나, “이 책에 나오는 사람들은 이제 ‘원로’들이다”라는 식의 표현이 그렇다.

그 ‘원로’들의 지혜가 닿길 바라는 마음에서 이 책을 만진다는 말이, 어떤 면에서는 이 책의 가장 솔직한 동기처럼 느껴지기도 했다. 다익스트라가 자기 자신을 거만한 컨설턴트라고 적었다는 이야기나, 그레이스 호퍼 강연에서 감명 깊었던 포인트를 풀어놓는 대목도 그 연장선에서 읽히면서, 본문과는 다른 결로 웃게 만든다.

velog dashboard v2 - MAU 1k+, 아직도 통계를 안보셨나요?!

Tue, 20 Jan 2026 16:15:48 GMT

Velog Dashboard v2

오랜만에 찾아왔습니다!! 빨리 접속하기: https://velog-dashboard.kro.kr/
Github repo: https://github.com/check-Data-Out/velog-dashboard-v2

이 서비스가 velog에 귀속된(?) 구조다 보니 알릴 수 있는 채널이 사실상 velog 밖에 없습니다. 하지만! 뉴스레터 이후로 유입도 계속 올라가고 *어느 순간부터 MAU 1K+ * 를 찍고 있더라구요...!

그리고 애초에 “우리나 편하게 쓰자”로 시작한 프로젝트라 막 공격적으로 알리자! 이런 마음은 애초에 크지 않았고요. 어떻게 알고 찾아오시나요?..!?

간간이 LinkedIn 이나 velog 글에서 통계 지표를 캡쳐해서 활용하시는 분들도 보이고, 그럴 때마다 저희 모두 조용히 뿌듯해하고 있었습니다ㅎㅎㅎ

사실 이 프로젝트는 같이 시작했던 취준생 분들을 위한 (나름의) 취업 장려 프로젝트이기도 했는데, 멤버 절반 이상이 취업을 했습니다! ~~(하거나, 다시 돌아온..!! 상태)~~ 프로젝트의 비공개 KPI는… 달성했습니다. 😎

혹시 이 글을 읽고 계시는 취준생 분이 계시다면! 개인적으로 나 혼자 쓰는 product 이라도 0 to 1 으로 세상에 공개하는 경험과 관리해보는 경험이 정말 큰 도움이 될 것이라고 생각합니다!

아무튼, 살아있다는 근황 겸 소소한 업데이트 공유해봅니다. 🙏🔥

① 직접 통계 새로고침! ② 완전 싱크 맞는 "마크다운 통계 뱃지" (사실 TBD이긴 한..) ③ 토큰 공격 방어!! Fail-fast JWT + Redis 기반 인증 실패 추적/차단 (rate limit)

1. 직접 통계 새로고침 (딸각)

그동안 통계를 “유저가 직접 업데이트” 하지 못하게 막아뒀습니다. 이유는 단 하나... 서버 비용이 0원이라 리소스가 절망적이기 때문 입니다 ㅎㅎ

그래서 통계를 어그리게이션 하는 가장 무거운 배치는 철저하게 GitHub Actions 로만 돌립니다. (무려 20개 배치를 30분마다 돌림 ㅋㅎㅋㅎㅋㅎ)

근데 문제가 있죠.

방금 가입했는데, 배치가 돌 때까지 기다려야 하는 케이스
한 달만에 들어오면 토큰 만료로 인해 레거시/과거 데이터를 보게 되는 케이스 (저도 그렇고.. 배치 도는 순간까지 절대 못 참습니다.)

그래서 이번에 “어느 정도 cap” 을 두고, 유저가 직접 통계를 새로고침 할 수 있는 창구를 만들었습니다.

핵심 흐름

직접 새로고침 버튼 → API 호출 → Redis 큐 적재 → Consumer 구독/처리

Consumer 는 가장 리소스가 널널한 백오피스 서버에서 가동하기로 했습니다!

무한 새로고침 방지 (중복 호출 방지)

15분 리미트가 걸려있습니다. 기준은 버튼 누른 시간이 아니라, “나의 가장 마지막 업데이트 시간”으로부터 15분 입니다 ㅎㅎ. 고로 신규로 오신분은 바로 클릭이 가능하실거에요!

Consumer 가 배보다 배꼽이 커진 이유...!

첫 설계시 "비동기 task를 범용적으로 처리하는 consumer" 는 아니었는데, 만들다 보니 범용성을 목표로 하게 되었습니다.. (일 부분 만큼은 오히려 창업한 product 보다 완성도가 높은 기분) 그래서 핵심 아래 3가지 경우를 중요하게 다뤘습니다.

1) 셧다운 때 / 에러 발생 시 2) 메시지 수신 전용 큐 / 처리 전용 큐 / 실패 전용 큐 분리 + 비동기 작업 처리
3) 실패 시 retry + 완전 실패 시 일정 사이즈만큼 보관 (디버깅/추적)

플로우 차트는 아래와 같습니다.

코드가 궁금하다면 여기서 바로 보실 수 있습니다!! https://github.com/Check-Data-Out/velog-dashboard-v2-back-office/tree/main/consumer

2. 완벽한 "마크다운 통계 뱃지" TBD

*최적화 작업으로 인해,
사실, 아쉽게 26.01.23 이후에야 제대로된 기능으로 사용하실 수 있습니다.. 🙏🙇🏻‍♂️🙏🙇🏻‍♂️🙏🙇🏻‍♂️*

통계 뱃지를 만들어 주신 분들이 이미 많이 있습니다. 근데 이미 기존 뱃지들은 어쩔 수 없이 제대로 된 통계 데이터를 한 번에 불러올 수 없는 구조 입니다.ㅠㅠ

직접 통계를 저장하지 않는 구조, 실시간으로 모든 게시글의 누적 통계를 가져올 수 없음!
과거 이력들은 결국 “코딩된 값”으로 들어갈 수 밖에 없고, “지금 이 순간 내 통계”를 완전하게 동기화 하기가 어려움!

근데 Velog Dashboard 에 등록한 분들은, 완벽한 마크다운 뱃지를 “직접 생성해서” 쓸 수 있습니다. 우측 상단 프로필에 "뱃지 생성기" 가 있습니다!

어떤 형태로 제공하냐면

이미지 URL 을 바로 주고, 마크다운에서 쓸 수 있는 HTML 코드를 같이 줍니다. 그리고 그 이미지 URL 은 아래와 같은 png 를 바로 줍니다.

그래서 GitHub README.md / velog 소개 페이지 / 기타 마크다운/html 지원하는 곳 어디든 다 박을 수 있어요. 짜잔.

뱃지 처리 user flow

1) /badge?username=xxx 로 요청이 들어오면 파라미터 검증을 하고 2) Next(server-side)에서 백엔드 API 호출로 통계/최근글 조회 (클라에 노출 안 됨) 3) React 컴포넌트 → Satori → PNG 로 이미지 생성합니다. 4) img 태그 하나로 끝! 입니다. 5) 최적화 작업으로 이제 캐싱 layer 가 추가되어서 릴리즈 될거에요!

3. 토큰 공격 방어 (Fail-fast JWT + Redis 기반 인증 실패 추적/차단)

이 업데이트는 기능 추가라기보다, 보안을 위해 결국 해야만 했던 방어 작업이다..! 어느 날부터 “가끔” 서버가 트래픽이 피크를 찍는 구간이 있었는데, 역시 해외에서의 무작위 요청! 근데 이게 어떻게 특정 포인트를 알아버린건지 DB connection 을 써야만 하는 API 을 타겟을 제대로 했더라구요..

문제: 쓰레기 토큰 대량 유입 → 연결 풀 고갈

쓰레기 토큰이 대량으로 들어옴 → 인증 미들웨어가 매번 payload 파싱 시도 → 예외가 계속 남 → 방어 없이 계속 들어옴 → 연결 풀이 먼저 말라버림 → "Max client connections reached"

즉, 어차피 의미 없는 토큰인데도 미들웨어가 열심히 달려버리면서 (그리고 중간중간 DB/연결 리소스를 건드리면서) 커넥션 풀이 빠르게 고갈되는 구조였습니다. 사실 이게 구조적인 문제가 좀 있었죠. (애초에 지금 서비스가 직접 회원을 관리하는 구조가 아니기에...)

그래서 전략을 바꿨습니다.

Fail-fast: JWT “형식부터” 먼저 보고, 아니면 바로 컷 (DB까지 갈 자격 없음)
Rate limit: 계속 던지는 IP는 Redis 에 기록해서, 임계치 넘으면 잠깐 차단.
Fail-open: Redis 가 죽어도 서비스는 죽지 않게 (차단 기능만 비활성)

물리적인 시큐어코딩 업데이트

1. JWT 형식 검증 유틸 추가

점(.) 2개인지, 빈 파트 없는지, Base64URL 문자셋인지 같은 기본 형식부터 체크
형식이 아니면 payload 디코딩/파싱 자체를 시도하지 않음

2. Payload 추출을 안전하게 (safeExtractPayload)

깨진 Base64 / 깨진 JSON 이면 null 처리 → InvalidTokenError
예외가 “서비스를 죽이지 않게” 컨트롤
Redis 기반 인증 실패 추적/차단
- IP별 인증 실패 횟수 누적 (윈도우/TTL 적용)
- 임계치 넘으면 429 + retryAfter
- 캐시 에러 시에는 fail-open (서비스 우선)

3. Error handling 개선

InvalidTokenError 발생 시 실패 추적(trackAuthFailure) 연결
500 에러만 Sentry 로 캡쳐 (4xx 커스텀 에러는 제외)

토큰 밸리데이션 & 정상 처리 플로우

Fail-fast + Redis block 플로우

VD2 는 누구나 PR 올릴 수 있게 열려있습니다!

템플릿도 있고, 이슈도 열려있고, 진짜로 “어? 이거 고치고 싶은데?” 하면 바로 들어오실 수 있게 해놨습니다!! https://github.com/Check-Data-Out/velog-dashboard-v2 여기서 관련 레포를 한 눈에 볼 수 있어요.

FE - https://github.com/Check-Data-Out/velog-dashboard-v2-fe
BE(API) - https://github.com/Check-Data-Out/velog-dashboard-v2-api
Back Office - https://github.com/Check-Data-Out/velog-dashboard-v2-back-office

놀랍게도 대시보드 프로젝트는 벌써 1년이 넘었더라구요. ~~시간 진짜 너무 빠르네요.~~ 이 프로젝트는 앞으로도 그냥 이런 “적당한 기술 놀이터” 같은 느낌으로 계속 이어갈 것 같습니다.

통계 데이터 개수만 벌써 곧 1천만개 입니다...! (무료로, 어떻게든, 살아남는 중)

마지막으로

아직 안 써보신 velog 유저분들은 한 번만 딸각 해보세요 :) https://velog-dashboard.kro.kr/
PR/이슈/피드백 모두 환영입니다!!

LLM - 바이브 코딩과 LLM에 대한 대규모 서베이, 논문 리뷰

Sun, 21 Dec 2025 05:41:45 GMT

[ 글의 목적: LLM을 활용한 Vibe Coding (Preprint 상태)에 대한 세계 최초의 포괄적이고 체계적인 리서치 & 논문 리뷰잉, 단순 번역이 아니라 요약, 순서 재정리, 주관이 첨가되어 있음. 스크롤 압박 주의 ]

A Survey of Vibe Coding with Large Language Models

LLM 기반 Vibe coding의 세계 최초 서베이 논문 에 대한 정리 및 분석 글이다. 초점은 "코딩을 위한 LLM, LLM 기반 코딩 에이전트, 코딩 에이전트를 위한 개발 환경, 피드백 메커니즘" 에 맞춰져 있다. 정말 놀라운건, "바이브코딩" 이라는 단어가 등장한지 1년도 안 됐다! OpenAI의 공동 설립자이자 전 테슬라 AI 디렉터(Director of AI)인 안드레이 카페시(Andrej Karpathy)가 자신의 X(구 트위터) 에 내용을 올리면서 시작되었다. 이는 처음에 밈처럼 번지다가 지금은 문화 이상, 도구 그 이상의 가치가 되어버렸다.

이 서베이가 일단 목차부터 재미있다. 그리고 바이브코딩에 대한 전반적인 동향에 대한 리서치 뿐 아니라 진짜 진지하게 학문적으로 접근했다. ~~사실 나에게는 여전히 바이브코딩이라는 단어가 하나의 밈처럼 느껴진다~~

출처: https://x.com/karpathy/status/1886192184808149383

1. Vibe Coding

1) 들어가며...

해당 논문에서는 바이브코딩을 *"대규모 소프트웨어 개발을 위한 엔지니어링 방법론"* 으로 정의한다. (we define Vibe Coding as an engineering methodology for software development grounded in large language models)

새로운 개발 방법론인 “Vibe Coding” 에서는 개발자가 코드를 한 줄 한 줄 확인하기보다는 실행 결과를 관찰하여 AI가 생성한 구현을 검증한다.
이러한 혁신적인 패러다임은 큰 잠재력을 지니지만, 그 효과가 아직 충분히 검증되지 않았고 인간-AI 협업 측면에서 예상치 못한 생산성 저하와 근본적인 과제들이 보고되고 있다.
실제로, 한 연구에서는 Cursor 에디터와 Claude 모델을 활용한 숙련 개발자들의 작업 완료 시간이 기대보다 19% 증가한 것으로 나타나, Vibe Coding의 효용성에 대한 의문을 제기하기도 했다.
논문에서는 자연어로 이루어지는 비구조적 지시만으로는 세밀한 요구사항이나 아키텍처 제약을 전달하기 어려우며, 인간 개발자와 AI 에이전트 간의 효율적인 협업을 위해서는 체계적인 프롬프트 엔지니어링 및 컨텍스트 엔지니어링, 구조화된 지침 제공, 그리고 상호작용 유형별로 균형 잡힌 주체성 분배 등이 필수적임을 보여준다.

Vibe Coding이란 대규모 언어 모델에 기반한 새로운 소프트웨어 개발 방법론으로, 인간 개발자, 소프트웨어 프로젝트, 코딩 에이전트 간의 삼자 상호작용을 중심으로 한다.

Vibe Coding 패러다임에서 인간은 더 이상 직접 코드를 작성하는 주체가 아니라, 의도 전달자이자 맥락 제공자, 그리고 최종 품질 평가자의 역할이 되었다.
프로젝트는 단순한 정적 코드 저장소를 넘어, 코드베이스와 데이터베이스, 도메인 지식까지 아우르는 다층적 정보 공간으로 확장되었다.

2) 바이브코딩의 3자 협업 (Triadic Collaboration)

인간 개발자 (Human Developer, $$H$$)
- 직접 코드를 짜는 작성자에서 의도 표명자(Intent Articulator) 및 품질 판정자(Quality Arbiter)로 역할
- 요구사항을 지시하고, 결과를 검토하여 수용할지 거부할지 결정한다.
소프트웨어 프로젝트 (Software Project, $$P$$)
- 단순한 코드 저장소를 넘어, 코드베이스, 데이터베이스, 도메인 지식을 포함하는 다면적인 정보 공간(Multifaceted Information Space).
코딩 에이전트 (Coding Agent, $$Aθ$$)
- 인간의 의도와 프로젝트의 제약 조건 하에서 코드 생성, 수정, 디버깅을 수행하는 지능형 실행자(Intelligent Executor)

이들의 관계는 "반복적인 지시-피드백 루프(Iterative Instruction-Feedback Loop)" 를 통해 작동하며, 개발자는 코드의 세부 사항보다는 결과(Outcome) 를 중심으로 검증한다.

이 3자 관계는 수학적으로 제약된 마르코프 결정 과정(Constrained MDP) 으로 정식화 할 수 있다.

(1) 시스템 정의: $$V = \langle H, P, A_{\theta} \rangle$$

Vibe Coding 시스템 $$V$$는 다음 세 요소로 구성된다.

$$H$$ (인간):
- 요구사항 인지 능력 ($$H_{req}: D \rightarrow I$$): 도메인 요구사항($$D$$)을 자연어 지시($$I$$, Instruction)로 변환한다.
- 품질 판별 능력 ($$H_{eval}: O \rightarrow {0, 1} \times F$$): 에이전트의 산출물($$O$$)을 보고 수락(1)/거부(0)를 결정하고 피드백($$F$$)을 준다.
$$P$$ (프로젝트): 프로젝트의 컨텍스트 공간은 $$P = \langle C_{code}, C_{data}, C_{know} \rangle$$로 정의된다.
$$A_{\theta}$$ (에이전트): 매개변수 $$\theta$$를 가진 LLM으로, 조건부 생성 함수 $$A_{\theta}: I \times P \times E \rightarrow O$$를 수행한다 ($$E$$는 실행 환경).

(2) Constrained MDP 공식: $$V_{MDP}$$

이 협업 과정은 다음과 같은 5개의 튜플로 정의된다.

$$ V_{MDP} = \langle S_P, A_{H \rightarrow A_{\theta}}, T_{A_{\theta}|P}, R_H, \gamma \rangle $$

$$S_P$$ (상태 공간): 프로젝트의 현재 상태 (코드 및 데이터의 상태)에 의해 정의된다.
$$A_{H \rightarrow A_{\theta}}$$ (행동 공간): 인간의 지시가 에이전트의 행동을 촉발한다.
$$T_{A_{\theta}|P}$$ (전이 함수): 에이전트가 코드를 수정하여 프로젝트 상태를 변화시키는 과정이며, 프로젝트 사양에 의해 제약된다.
$$R_H$$ (보상 함수): 인간의 평가(수락/거부 및 피드백)에 의해 결정되는 보상이다.
$$\gamma$$ (감가율): 미래 보상의 가치를 조정하는 할인 계수다.

(3) 에이전트의 생성 과정 (Conditional Generation Process)

에이전트가 코드를 생성하는 과정은 다음 확률 분포로 표현된다.

$$ P_{\theta}(Y | I, K, E) = \prod_{t=1}^{T} P_{\theta}(y_t | y_{

$$I$$: 인간의 의도 (지시).
$$K$$: 프로젝트 컨텍스트의 부분집합 ($$K \subseteq P$$).
$$E$$: 실행 환경.
$$C_t$$: 생성 단계 $$t$$에서의 동적 컨텍스트(Dynamic Context) ($$C_t = A(I, K, E, y_{
Human Layer: 지시사항 ($$c_{instr}$$).
Project Layer: 코드, 데이터, 지식 ($$c_{code}, c_{data}, c_{know}$$).
Agent Layer: 도구 정의, 메모리, 현재 작업 ($$c_{tool}, c_{mem}, c_{tasks}$$).

(4) 최적화 목표 (Optimization Objective)

Vibe Coding의 핵심 목표는 제한된 컨텍스트 윈도우($$L_{max}$$) 내에서 최적의 컨텍스트 전략($$F^*$$) 을 찾아 보상을 최대화하는 것이다!

$$ F^* = \mathop{\arg\max}{F} \mathbb{E}{\tau \sim T} [R(P_{\theta}(Y | C_F(\tau)), Y_{\tau}^*)] \quad \text{s.t.} \quad |C_F(\tau)| \le L_{max} $$

즉, 프로젝트의 방대한 정보 중에서 어떤 정보($$C_F(\tau)$$)를 에이전트에게 제공해야 인간이 원하는 이상적인 결과($$Y_{\tau}^*$$)와 가장 유사한 결과를 낼지 결정하는 최적화 문제다!

(5) 반복적 진화 및 피드백 (Iterative Evolution)

인간의 피드백을 통해 요구사항이 점진적으로 구체화되는 과정은 다음과 같이 표현된다:

$$ (o_{k+1}, I_{k+1}) = \begin{cases} (o_k, I_k) & \text{if } A_k = o_k \text{ (완전 수락, 종료)} \ (A_{\theta}(o_k \setminus A_k; \delta_k, I_k, K), I_k) & \text{if } \delta_k \in F \text{ (부분 수정)} \ (A_{\theta}(I_k \cup {\delta_k}, K), I_k \cup {\delta_k}) & \text{if } \delta_k \in I_{new} \text{ (요구사항 확장)} \end{cases} $$

설명: 인간은 에이전트의 산출물($$o_k$$)을 보고 일부만 수락($$A_k$$)하고 수정 사항($$\delta_k$$)을 지시하거나, 아예 새로운 요구사항을 추가하여 지시 집합($$I$$)을 확장($$I_{k+1}$$)한다. 이는 "점진적 요구사항 명료화(Progressive Requirement Clarification)"를 수학적으로 표현한 것이다.

3) 뭐라는거에요..?

처음에 논문의 위 설명을 보고 굉장히 당황스러웠다ㅎㅎ;; 논문에서는 바이브코딩의 이 3자 협업이 "새로운 공학" 이며 "수학적으로 계산 가능한 시스템" 이라는 걸 증명하기 위해서 정리했다.

쉽게 좀 바꿔서 이해해보자면 아래와 같다.

인간을 "사장님/팀장님" 으로, "무엇(What)" 을 만들지 지시하고, 결과물이 나오면 "왜 합격/불합격인지(Why)" 을 판단하며
에이전트를 "손이 엄청 빠른 인턴" 으로, 사장님이 시키는 대로, 그리고 회사의 규칙대로 실제로 "어떻게(How)" 일을 처리할지 고민하고 실행하며
프로젝트를 "회사 창고/규정집" 으로, 인턴이 일을 할 때 참고해야 하는 "어디서(Where)" 에 해당하는 정보를 의미한다.

그리고 "수학적 접근"으로 결국 논문에서 중요하다고 강조하는 것들은 아래 3가지라 이해된다.

말을 잘해야 한다 (Context Engineering)
보는 눈을 길러야 한다 (Evaluation)
반복해야 한다 (Iterative Loop)

그니까.. 바이브코딩은 결국 최적화 문제라는거다..!! 제한된 컨텍스트 윈도우($$L_{max}$$) 내에서 최적의 컨텍스트 전략($$F^*$$) 을 찾아 보상을 최대화하는 것을 목표로 해야 한다..! 이를 Markov decision process로 접근한 것이다.

진짜 얼마나 LLM쪽 AI, model 이 대격변인지 보여주는 사진이다..

4) 코딩을 위한 대규모 언어 모델들

논문에서는 코딩을 위한 LLM(Code LLMs)을 Vibe Coding 생태계를 지탱하는 핵심 인프라로 보고 있다. 어떻게 Code 전용 LLM을 구성했는지 개괄적인 내용을 다룬다.

(1) 데이터 기초(Data Foundation)

코드 말뭉치 (Code Corpora): 주로 GitHub나 Stack Overflow 같은 오픈 플랫폼에서 데이터를 수집한다. 'The Stack'과 같은 데이터셋은 허가된 라이선스가 있는 코드만을 선별하여 법적 리스크를 줄였다.
데이터 구성 전략은 인기 있는 언어에 집중하는 '깊이 중심(depth-focused)' 전략과 다양한 언어를 포괄하는 '너비 중심(breadth-focused)' 전략으로 나뉜다.
- 깊이 중심 The Stack (v1): 라이선스 문제가 없는(permissively licensed) 소스 코드 3.1TB를 사용하며, 단 30개의 프로그래밍 언어에만 집중했다. 특히 라이선스와 데이터 출처(provenance) 관리에 엄격했다.
- 너비 중심 The Stack v2: 깊이 중심이었던 v1과 달리 커버리지를 대폭 확장했습니다. 무려 619개의 언어를 포함하며 데이터 양도 67.5TB로 폭증했다.
- GPT-Neo: "The Pile"이라는 다양한 혼합 말뭉치(mixed corpora)를 사용했고,
- CodeLlama: SlimPajama 데이터셋의 6,270억(627 billion) 토큰과 The Stack의 코드를 결합하여 광범위한 학습을 수행했다.
- Arctic-SnowCoder: 필터링된 데이터 조합을 통해 4,000억(400 billion) 토큰을 사용했다.
지침 및 선호도 데이터 (Instruction & Preference Datasets): 단순히 코드를 완성하는 것을 넘어 사용자의 의도를 따르게 하기 위해, 커밋 메시지나 자연어 지침이 포함된 데이터셋(CommitPack, OpenCodeInstruct 등)을 사용한다. 비용 절감을 위해 'Self-Instruct'나 'Evol-Instruct'와 같이 AI가 합성 데이터를 생성하여 학습에 활용하는 방식이 주류가 되고 있다고 한다.

생각보다 라이선스와 출처에 엄격했던 모델이 꽤 있다는 점에 놀랐다. 조금 덧붙이면, 9월에 Claude Code Meetup Seoul 가서 클로드 코드 개발 관계자가 바이브코딩엔 Typed Language(정적 타입 언어) 를 더 추천한다고 했다. Rust, TypeScript(TS) 이 2가지를 가장 먼저 말했던게 기억에 남는다 ㅎㅎ (~~제발 python + mypy 조합으로 다시 학습시키고 싶다..~~)

(2) 사전 학습 기술 (Pre-training Techniques)

얼마나 방대한양을 사전 조사했는지 알 수 있는 "대표 코딩 데이터셋 개요" table,, (중간에 짤렸다. 논문 본문 참조.)

마스크 언어 모델링 (MLM): 문맥을 양방향으로 이해하는 데 유리하며 주로 코드 이해(Code Understanding) 모델(CodeBERT 등)에 사용된다.
자동 회귀 모델링 (Autoregressive): 이전 문맥을 바탕으로 다음 토큰을 예측하는 방식으로, 코드 생성(Code Generation) 모델(CodeGPT, CodeLlama 등)의 기초가 된다.
중간 채우기 (Fill-in-the-Middle): 코드의 앞부분(prefix)과 뒷부분(suffix)을 보고 중간을 채우는 능력으로, 코드 완성 기능에 필수적이다!
지속적 사전 학습 (Continual Pre-training): Llama 2와 같은 일반 목적의 LLM을 가져와서 코드 데이터로 추가 학습시켜 코딩 능력을 강화하는 전략이다.(예: CodeLlama, DeepSeek-Coder-V2). 이는 기존 지식을 잊어버리는 '재앙적 망각(catastrophic forgetting)'을 방지하면서 전문성을 높이는 것이 핵심 과제이다.

이 이상은 논문에서 해당 섹션을 참고하는 것을 추천한다. "Fill-in-the-Middle" 과 같은 pre-training을 할까 했었는데 실제로 적극적으로 하는 것에 놀랐다. ~~근데 왜 내 코드에는 syntax 안지키는 코드만 fill in 할까?~~

(3) 사후 학습 기술 (Post-training Techniques)

지도 미세 조정 (SFT): 모델이 지침을 잘 따르도록(Instruction Following) 가르친다. 최근에는 매개변수의 일부만 업데이트하는 LoRA(Low-Rank Adaptation) 같은 효율적인 튜닝 기법이 널리 쓰인다. 데이터의 양보다는 '질'이 중요하다는 것이 입증되어, 적지만 고품질의 데이터를 선별해 학습시키는 추세다.
- 이게 "바이브코딩" 을 발전시키는 중추로 보인다. 인간이 작성한 문제-해결 예시를 반복적으로 변형하여 대규모의 학습 데이터를 생성하는 Instruction Evolution 기법과 같이 말이다.
- 보안 강화를 위한 특수 튜닝으로 취약점 없는 코드를 생성하도록 모델을 훈련시켜 보안 수준을 크게 향상시킨 사례도 보고되었고, 성능 최적화나 코드 수정 및 디버깅 작업에 특화된 튜닝 전략들도 연구되고 있다 한다.
강화 학습 (Reinforcement Learning): 모델을 인간의 선호도나 객관적인 정답에 맞게 정렬(Alignment) 한다.
- RLHF/DPO: 인간의 피드백이나 선호 데이터를 이용해 모델을 최적화
- 실행 피드백 활용: 코딩 도메인의 특수성을 활용하여, 컴파일러의 성공 여부나 유닛 테스트 통과 여부를 보상(Reward) 신호로 사용하여 강화 학습을 수행한다(CodeRL, PPOCoder). 이는 수학이나 코딩처럼 정답 검증이 가능한 영역에서 특히 효과적이다.

5) 코딩 에이전트

코딩 에이전트는 LLM 기반으로 동작하며, 코드 자동 완성 수준을 넘어 자율적으로 프로그래밍 작업을 수행하는 인공지능 요원을 의미한다.

이러한 에이전트들은 코드 생성 기능과 함께, 문제 해결을 위한 계획 수립 능력(planning), 현재까지의 진행 상황이나 중요한 정보를 기억하는 메모리 메커니즘(memory), 그리고 외부 도구나 환경과 상호작용할 수 있는 툴 통합 능력(tool integration) 등을 갖추고 있다.

이 챕터는 코딩 에이전트를 인지 시스템(Cognitive System) 으로 보고, 인간 개발자와 유사하게 사고하고 행동하도록 만드는 5가지 핵심 구성 요소를 소개한다.

(1) 분해 및 계획 능력 (Decomposition and Planning Capability)

작업 분해 (Task Decomposition): '생각의 사슬(Chain-of-Thought, CoT)'이나 '생각의 나무(Tree-of-Thoughts, ToT)'와 같은 기법을 사용하여 복잡한 요구사항을 단계별로 추론하고 분할한다.
계획 수립 (Plan Formulation): 에이전트는 PDDL(Planning Domain Definition Language) 같은 형식을 사용하거나, ReAct(Reasoning + Acting) 패턴을 통해 '생각-행동-관찰'의 루프를 반복하며 동적으로 계획을 수정한다. (PS. 개인적으로 ReAct 패턴 이 정말 나에게 "에이전틱한 것이 뭔가" 에 대해 진지하게 고민할 수 있는 포인트를 만들어 줬다.)

(2) 메모리 메커니즘 (Memory Mechanism)

단기 및 장기 기억: 인간의 인지 구조를 모방하여, 현재 추론 중인 내용은 단기 기억(Short-term)에, 방대한 프로젝트 지식이나 과거 디버깅 이력은 벡터 데이터베이스(Vector DB) 등을 활용한 장기 기억(Long-term)에 저장한다.
메모리 관리: 정보를 단순히 저장하는 것을 넘어 통합(consolidation), 인덱싱(indexing), 망각(forgetting, 에빙하우스 망각 곡선 적용) 등의 관리 작업을 통해 효율성을 극대화한다.

(3) 행동 실행 (Action Execution)

도구 호출 (Tool Invocation): 터미널, 파일 시스템, 컴파일러, 웹 검색 등 외부 도구를 API 형태로 호출합니다. 최근에는 MCP (Model Context Protocol) 와 같은 표준화된 인터페이스가 등장하여 에이전트와 도구 간의 상호운용성을 높이고 있다. (PS. 최근엔 claude 가 "SKILL" 이라는 공을 던졌다.)
코드 기반 행동 (Code-based Action): JSON 형식의 정적인 행동 정의보다, 실행 가능한 파이썬 코드 자체를 행동(Action)으로 생성하여 실행하는 방식이 더 강력한 유연성과 수정 능력을 보여주는 추세다.

(4) 성찰: 반복, 검증 및 디버깅 (Reflection: Iteration, Validation, and Debugging): Vibe Coding의 핵심인 '결과 중심 검증'을 가능하게 하는 것.

반복적 개선 (Iterative Refinement): 초기 생성된 코드에 대해 스스로 비평(Self-Critique)하거나 컴파일러/테스트 결과를 반영하여 코드를 점진적으로 개선한다.
지능형 디버깅 (Intelligent Debugging): 실행 중 발생하는 에러나 중간 변수 상태를 분석(Self-Debugging)하여 논리적 오류를 찾아낸다. 예를 들어, Reflexion 프레임워크는 실패 기록을 장기 기억에 저장하여 다음 시도 때 같은 실수를 반복하지 않도록 한다.
자가 개선(self-improving) 에이전트는 17~53% 의 추가 성능 향상을 입증했다. 과거 단순한 코드 생성 보조 도구(Assistant) 수준이었던 AI가 이제는 스스로 환경을 설정하고, 코드를 실행하며, 오류를 수정하는 자율적 에이전트(Autonomous Agent) 단계로 진화했음을 보여주고 있다.

(5) 에이전트 협업 (Agent Collaboration)

역할 분담 (Role-Based Collaboration): 기획자, 프로그래머, 테스터, 리뷰어 등 에이전트에게 특정 페르소나와 역할을 부여한다.
협업 프레임워크: MetaGPT나 ChatDev와 같이 가상의 소프트웨어 회사를 모델링하여, 에이전트들이 표준 운영 절차(SOP)에 따라 대화하며 소프트웨어를 개발하는 방식이 대표적이다.

사견으로 이 "에이전트 협업" 관점이 요즘 개발자들이 가장 활발하게 시도하는 섹터라고 보인다. 다양한 mcp 또는 병렬 호출, 최근의 skills 에 이르기까지, "동시 다발적으로 다양한 형태로 에이전트에게 일을 던지고 A to Z 를 하게 하는 행위" 에 다들 뭔가 하나씩 시도하는게 보인다.

6) 코딩 에이전트 개발 환경

(1) 에이전트가 생성한 코드를 실제로 실행하기 위해서는 격리된 실행 환경(isolated execution environment) 이 필요하다.

Claude CLI가 홈 디렉터리를 삭제해 Mac이 초기화되었어요. ~~긱뉴스와 레딧에서 아주 인상깊었던 일이다.~~

컨테이너화 기술 (Containerization): Docker와 같은 기술을 사용하여 운영체제 수준에서 가상화를 수행한다. 이는 에이전트에게 일관된 실행 환경을 제공하고, 호스트 시스템과 분리된 독립적인 파일 시스템 및 네트워크 공간을 보장한다.
보안 격리 메커니즘 (Security Isolation): 샌드박스(Sandbox)는 1차 방어선 역할을 합니다. gVisor 와 같은 도구나 WebAssembly 기반 엔진, 그리고 Intel SGX/PKU 와 같은 하드웨어 기반 격리 기술을 사용하여 에이전트가 시스템의 민감한 자원에 접근하지 못하도록 권한을 엄격히 제한한다.
클라우드 기반 실행 플랫폼: Kubernetes 와 같은 오케스트레이션 도구를 통해 에이전트의 작업을 격리된 포드(pod)에 할당하고, 수천 개의 CPU 코어에서 대규모로 코드를 실행하고 평가할 수 있는 확장성을 제공한다.

(2) 대화형 개발 인터페이스 환경 (Interactive Development Interface Environment)

개발자가 에이전트와 협업하는 접점(IDE)이 어떻게 진화하고 있는지 설명 하는 섹션이다.

AI 네이티브 개발 인터페이스: 기존의 코드 편집기를 넘어, 개발자가 자연어로 의도를 말하면 에이전트가 코드를 생성하고 수정하는 대화형 방식이 주류가 되고 있다. 커서(Cursor)와 같은 도구는 인라인 제안(Inline Suggestion)과 대화형 상호작용(Conversational Interaction)을 결합하여 문맥을 이해하는 지원을 제공한다.
원격 개발 (Remote Development): GitHub Codespaces와 같이 클라우드 상에 미리 구성된 표준화된 개발 환경을 제공하여, 에이전트가 로컬 환경 설정 문제없이 즉시 작업을 수행할 수 있도록 한다. 비슷하게 클로드가 또 https://claude.ai/code 를 통해 웹에서 바이브코딩이 가능하게 만들어버렸다.
도구 통합 프로토콜 표준: 에이전트가 다양한 도구와 원활하게 소통하기 위한 표준이 만들어졌다. (PS. 클로드가 MCP 공을 던진 뒤로 약간 멱살끌고 가는 느낌)
- MCP (Model Context Protocol): 소스 코드나 문서 같은 문맥 정보를 교환하는 범용 인터페이스.
- LSP (Language Server Protocol): 코드 자동 완성이나 진단 기능을 언어에 상관없이 제공.
- DAP (Debug Adapter Protocol): 디버깅 상호작용을 표준화.

(3) 분산 오케스트레이션 플랫폼 환경 (Distributed Orchestration Platform Environment)

CI/CD 파이프라인 통합: 에이전트가 생성한 코드가 실제 소프트웨어 제품에 통합되기 전에 자동으로 빌드, 테스트, 배포되는 파이프라인(Jenkins, GitHub Actions 등)과 연동된다. ('Vibe Coding'에서도 품질 보증을 위한 필수적인 관문으로 판단된다. 최후의 보루 느낌)
클라우드 컴퓨팅 오케스트레이션: TOSCA와 같은 명세나 Kubernetes를 사용하여 컴퓨팅 리소스를 동적으로 할당하고 관리한다. 이를 통해 에이전트의 워크로드를 효율적으로 처리한다.
다중 에이전트 협업 프레임워크: 복잡한 개발 작업을 수행하기 위해 AutoGen, CrewAI, MetaGPT와 같은 프레임워크를 사용한다. 이들은 기획자, 개발자, 테스터 등 서로 다른 역할을 가진 에이전트들이 협력하여 문제를 해결하도록 조직화하며, 단일 에이전트보다 높은 신뢰성과 확장성을 제공한다. 나아가 LLMOps라 불리는 기법을 통해 에이전트 자체의 성능 모니터링과 로그 피드백을 자동화하려는 시도를 하고 있다.

그리고 이를 발판으로 더 이상 "Single Agent" 로만 접근하지 않는다. 위 논문에서와 같이, AutoGen, CrewAI, MetaGPT, LangGraph 와 같은 프레임워크는 이러한 패러다임을 잘 보여주고 있다.

7) 피드백 메커니즘

(1) 컴파일러 피드백(Compiler Feedback)

에이전트가 작성한 코드를 컴파일하거나 정적 분석함으로써 얻는 피드백
컴파일 에러, 타입 체크 오류, 린트 경고 등이 이에 해당하며, 이러한 피드백을 통해 명백한 문법 오류나 타입 불일치 등을 에이전트가 즉각 수정할 수 있다.
예를 들어 "세미콜론 누락"과 같은 컴파일 오류 메시지를 에이전트에게 전달하면, 에이전트는 해당 문제를 해결하도록 코드를 변경한다.

(2) 실행 피드백(Execution Feedback)

생성된 코드를 실행하여 얻는 런타임 결과나 테스트 결과를 말한다.
프로그램을 실제로 돌려봄으로써 발생하는 예외(exception) 메시지, 실행 로그, 또는 미리 작성된 테스트케이스의 통과/실패 여부 등이 이에 포함된다.
에이전트는 예를 들어 "테스트 X 실패: 입력 5에 대해 8이 아닌 10을 반환함"과 같은 피드백을 받아, 논리 오류를 찾아내고 수정하는 과정을 거친다.

(3) 인간 피드백(Human Feedback)

개발자 또는 도메인 전문가가 에이전트의 출력에 대해 주는 직접적인 피드백이다.
예컨대, 에이전트가 생성한 코드에 대해 개발자가 "이 부분의 알고리즘 복잡도가 높습니다. 더 효율적으로 개선하세요."와 같이 조언하거나, "보안상 이 함수에서는 사용자 입력을 검증해야 합니다."와 같은 지침을 추가로 제공할 수 있다.
인간 피드백은 일반적으로 자연어 형태로 제공되며, 에이전트는 이를 해석하여 코드를 개선한다. 이때 RLHF(Reinforcement Learning from Human Feedback) 등 학습 기법을 통해 향후 더 나은 출력을 내도록 에이전트를 조정하는 경우도 있지만, Vibe Coding 맥락에서는 실시간 협업 측면의 피드백 제공이 주를 이룬다.

에이전트 스스로가 자신의 출력을 검토 및 개선하는 메커니즘이다.
예를 들면, 에이전트가 코드를 생성한 후 곧바로 그 코드를 다시 한번 검토하여 잠재적 버그나 개선점을 찾아내는 것이다.
최근 제안된 Reflexion 기법 등은 에이전트에게 비판적 리뷰어의 프롬프트를 추가로 주어, 에이전트가 자기 코드의 결함을 찾아내고 수정하도록 유도한다.
이러한 자기 피드백 루프를 통해 추가 학습 없이도 출력 품질을 향상시키는 효과가 보고되었다. Self-refinement 는 내부 피드백으로 분류되지만, 충분히 체계화된다면 강력한 자동 디버깅 수단으로 활용될 수 있다.

바이브 코딩 개발 모델 프레임워크와 소프트웨어 개발 모델 비교 그래프

CodeCoR: An LLM-Based Self-Reflective Multi-Agent Framework for Code Generation 논문을 보면 CodeCoR 는 Prompt Agent, Coding Agent, Test Agent, Repair Agent 가 밀접하게 협력하는 "자기 성찰(Self-Reflective)" 기반 멀티 에이전트 프레임워크이다.

2. Vibe Coding Development Models

논문은 다음 세 가지 축을 기준으로 모델을 나눈다. 1. 인간의 품질 통제 (Human Quality Control): 개발자가 코드를 얼마나 꼼꼼히 리뷰하고 이해하는가? 2. 구조적 제약 메커니즘 (Structured Constraint Mechanisms): 사전 기획이나 자동화된 테스트가 포함되는가? 3. 문맥 관리 능력 (Context Management Capability): 프로젝트의 기존 코드나 문서를 얼마나 잘 참조하는가?

논문은 이 부분을 "현상, 리서치" 정도로 접근한 것 같다. 오히려 논문의 이 분류와 현 상태덕분에 프로젝트 성격에 따른 '트레이드오프(Trade-off)' 와 '다른 사람은 어떻게 하는지?' 에 대해 더 자세하게 알 수 있었다.

1) 다섯 가지 개발 모델

(1) 무제약 자동화 모델 (UAM, Unconstrained Automation Model)

핵심: AI를 전적으로 신뢰하고, 코드를 줄 단위로 검사하지 않으며 기능 동작 여부만 확인한다. ("Vibe Coding"의 원래 정의에 가장 가까움)
특징: 에이전트에게 광범위한 자율성이 부여되며, 개발 속도가 매우 빠르고 진입 장벽이 낮아 비전문가도 프로토타입을 빠르게 만들 수 있다. 전통적인 RAD(Rapid Application Development) 와 유사하다.
단점: 인간의 면밀한 감독 없이 진행되므로 코드 품질이나 아키텍처 일관성이 떨어질 위험이 있다. 동시에 보안 취약점이나 기술 부채가 쌓이기 쉽고, 유지보수가 어렵다. (이로 인한 사건 사고 이슈가 아주 쏟아지고 있다..)
- 바이브코딩의 배신, AI 에이전트 때문에 DB 날린 개발자
- 하루 만에 AI로 만든 앱, 보안은 안전할까? 바이브 코딩의 양면성
추천: UAM은 일회용 프로토타입이나 개인용 도구처럼 실패 위험이 낮은 시나리오에 적합, 일회성 프로토타입, 개인용 도구 개발.

(2) 반복적 대화 협업 모델 (ICCM, Iterative Conversational Collaboration Model)

핵심: AI는 '드라이버(Driver)', 인간은 '내비게이터(Navigator)'가 되어 짝 프로그래밍(Pair Programming) 하듯 지속적인 대화로 개발한다. AI가 코드 생성 → 사람이 검토 및 이해 → 테스트로 검증 → 결과에 따라 수정 or 확정 의 반복.
특징: 인간이 AI가 짠 코드를 이해하고 검토한 뒤 수락한다. 속도와 품질의 균형을 맞출 수 있으며, 팀 단위 프로젝트에 적합하다.
- 애자일 개발의 페어 프로그래밍(pair programming) 관행과 유사하다고 평가된다.
- IDE에 붙은(내재된) agent 를 활용할때, cursor 에서 자동완성을 수동적으로 사용할때 가장 흔하게 볼 수 있지 않을까 한다.
단점: 개발자의 높은 역량이 요구되며, 잦은 리뷰로 피로도가 높을 수 있다.

(3) 계획 주도 모델 (PDM, Planning-Driven Model)

핵심: 전통 소프트웨어 공학의 아키텍처 우선 원칙을 Vibe Coding에 적용한 모델이다. 코딩 전에 인간이 기술 사양서, 코딩 규칙 등 '청사진(blueprint)' 을 완벽히 설계한 뒤 AI에게 구현을 맡긴다.
특징: 전통적인 워터폴(Waterfall) 방식의 현대적 적용으로 보인다. 구조가 탄탄하고 모듈화가 잘 된 코드를 얻을 수 있다.
단점: 초기 기획 문서 작성에 시간이 많이 걸린다. 하지만 이러한 선투자는 이후 유지보수 비용과 재작업 부담을 줄여주며, 팀 협업 시 프로젝트의 이해도를 높이는 효과가 있다.
추천: 복잡한 풀스택 애플리케이션, 아키텍처가 중요한 프로젝트에 추천된다.

(4) 테스트 주도 모델 (TDM, Test-Driven Model)

핵심: TDD(테스트 주도 개발) 를 적용하여, 인간이 테스트 케이스를 먼저 작성하고 AI가 이를 통과하는 코드를 작성하게 한다. 여기서 조금 더 AI의 손을 빌리면 *"켄트 벡(Kent Beck) 형님과 함께하는 Augmented Coding, "증강 코딩" 잘해보기"* 형태가 되는 것 같다.
특징: 테스트 케이스 자체를 명세(specification) 로 사용한다는 점이 특징이다. 인간의 주관적 리뷰 대신 기계적인 검증(테스트 통과 여부)으로 품질을 보증한다. 리팩토링 안정성이 매우 높다.
단점: 테스트 코드를 짜는 초기 비용이 든다.
추천: 핵심 알고리즘, 프로덕션 레벨의 애플리케이션에 추천된다.

(5) 컨텍스트 강화 모델 (CEM, Context-Enhanced Model)

핵심: 이는 독립적인 워크플로우라기보다는, 위의 4가지 모델에 결합할 수 있는 '수평적 강화 능력'(보강 기법) 이라고 명시한다.
특징: RAG(검색 증강 생성) 기술 등을 활용해 AI에게 프로젝트 전체의 코드, 문서, 스타일 가이드를 주입한다. 그 결과, 에이전트는 코드를 생성할 때 기존 프로젝트 코드와 일관된 명명법과 스타일을 따르고, 기존 함수나 API를 정확히 호출하며, 프로젝트의 아키텍처적 제약을 준수하는 코드를 만들어낼 수 있다.
- CEM은 앞서 언급한 네 모델과 자유롭게 조합될 수 있는데, 예를 들어 UAM + CEM 조합은 신속하면서도 일정 수준 통제가 가미된 프로토타이핑을 가능하게 하고, ICCM + CEM 은 방대한 코드베이스 협업에, PDM + CEM은 설계 명세 준수에, TDM + CEM 은 최고 수준의 코드 품질 확보에 각각 적합한 접근을 제공한다.
- 구현 측면에서, CEM은 프로젝트 초기화 시 벡터 DB 인덱스를 생성하고 대화 흐름마다 관련 정보를 검색하여 맥락으로 주입하는 자동 검색 전략이나, 개발자가 참조할 파일을 직접 지정하는 수동 참조 전략 등으로 실현된다.
효과: AI가 기존 프로젝트의 스타일을 따르고 API를 정확히 호출하도록 하여 환각을 줄이고 일관성을 높인다. 대규모 레거시 코드 유지보수에 필수적이다. (컨텍스트 윈도우를 생각해보자)

위 5가지 분류에 따르면 나는 *PDM + CEM 으로 셋업하고 -> TDM 으로 확장하는 형태에* 가장 가깝다. 켄트 벡(Kent Beck) 형님과 함께하는 Augmented Coding, "증강 코딩" 잘해보기 에서도 언급했듯, AI 를 위한 markdown 이 정말 중요해졌고, 이는 RAG와 매우 유사하게 작동된다.

2) 미래 전망 및 과제 (Future Impact and Open Challenges)

위 사진은 원래 논문에서 가장 먼저 등장하는 "Figure 1" 이다. 다 보고 다시 이 그림을 볼때 더 개괄적으로 거시적인 분류에 대해 좀 더 와닿았다.

The taxonomy of Vibe Coding is categorized into large language model foundations, coding agent architectures, development environments, and feedback mechanisms. Each area encompasses specific techniques and frameworks that collectively advance the systematic integration of LLMs and agents into intelligent and collaborative software development workflows.

(1) 개발 프로세스의 재설계 (Reengineering of Development Process)

단계적 주기에서 연속적 마이크로 반복으로: 전통적인 '기획-구현-테스트(SDLC)'의 긴 주기가 "프롬프트-생성-검증(Prompt-Generate-Validate)" 이라는 초고속 반복 주기(수 분~수 초)로 대체된다. 설계와 구현의 경계가 흐려지며, 개발자는 실행 결과(Vibe)를 보며 실시간으로 요구사항을 수정한다. (끊임없이 대화하며 점진적으로 목표를 만족시켜가는 iterative goal satisfaction 방식)
개발자 역할의 재정의: 개발자는 코드를 직접 짜는 '저자(Author)'에서, AI에게 맥락을 제공하고 결과를 조율하는 '문맥 엔지니어(Context Engineer)' 이자 '아키텍트(Architect)' 로 역할이 바뀌고 있다.
프로젝트 관리의 난관: 코드 생성 속도가 예측 불가능(어떤 기능은 1분, 어떤 건 수 시간)해져 공수 산정이 어려워지며, 기존의 코드 리뷰 방식(라인 단위 검토)이 작동하지 않게 된다.

(2) 코드 신뢰성과 보안 (Code Reliability and Security)

수동 리뷰의 한계: AI가 짠 코드를 인간이 일일이 검토하는 것은 Vibe Coding의 장점(속도)을 깎아먹는 모순이다. 또한, 개발자가 AI가 생성한 복잡한 로직을 완전히 이해하지 못할 수도 있다. (개발 속도와 확실성 사이의 트레이드오프 딜레마)
통합된 보안 피드백 루프: 따라서 인간의 개입 없이도 AI가 코드를 생성하는 즉시 보안 취약점을 잡는 자동화된 가드레일이 필수적이다. 전통적인 정적/동적 분석 도구(SAST/DAST)를 프롬프트-생성-검증 사이클에 내장하여, 에이전트가 코드를 내놓을 때마다 자동으로 보안 스캐닝과 품질 분석을 수행하고 그 피드백을 즉각 에이전트에게 제공하는 통합 피드백 루프가 이상적
- 생성 전(Pre-Generation): 프롬프트 단계에서 보안 요구사항 주입.
- 생성 중(In-flight): 코드가 생성되는 즉시 정적 분석(SAST) 수행
- 샌드박스 동적 분석: 실행 시점에 동적 분석(DAST) 및 퍼징(Fuzzing)을 통해 런타임 취약점 탐지
AWS의 AI 보조 코드 생성기인 Amazon CodeWhisperer(현 Amazon Q Developer) 는 코드 완성 시 보안 취약점 스캔 결과를 함께 제시하는 초기 기능을 선보였는데, 향후에는 이보다 더욱 지능적이고 상황 인지적인 보안 검사 에이전트가 개발되어, Vibe Coding 과정 전반에 걸쳐 인간을 대신해 지속적인 경계 역할을 수행해야 할 것이다.
마지막 방어선으로서 인간 개발자가 최종 감수를 하는 방안도 고려된다. 예컨대 Vibe Coding을 적용하더라도, 안전이 중요한 코드나 윤리적으로 민감한 영역에서는 최종 배포 전에 보안 전문가 또는 개발 리드가 결과물을 점검하여 승인하는 절차를 유지함으로써, 속도와 안전성 사이의 균형을 찾는 것이다. Vibe Coding의 보편화를 위해서는 이러한 다층적인 보안/신뢰성 확보 체계에 대한 연구 개발이 시급하다.

(3) 에이전트 감독의 확장성 (Scalable Oversight)

새로운 위험 요소: 자율 에이전트는 연쇄 오류(Cascading Errors) 를 일으키거나, 불필요한 라이브러리를 마구 설치하는 의존성 증식(Dependency Proliferation) 문제를 야기할 수 있다.
확장 가능한 감독 아키텍처: 인간이 모든 걸 감시할 수 없으므로, "약한 감독자가 강한 에이전트를 통제(Weak-to-Strong Generalization)" 하는 기술이 필요합니다.
- 계층적 감독: 작은 AI 모델이 큰 AI 모델을 1차로 감시.
- 다중 에이전트 토론(Multi-Agent Debate): 여러 에이전트가 서로의 코드를 비평하며 오류를 찾아내는 기술 필요.
- 자동화된 감시견(Watchdog): 에이전트가 권한을 넘어서는지 감시하는 별도의 AI 도입.

(4) 인간적 요소 (Human Factors)

새로운 협업 방식에 대한 거부감이나 신뢰 부족은 Vibe Coding 채택의 큰 장애가 될 수 있다. 따라서 에이전트의 의사결정 근거를 설명하는 설명가능성(XAI) 제공, 개발자가 에이전트의 진행 상황을 쉽게 이해하고 개입할 수 있는 UI/UX 디자인, 그리고 개발자의 심리적 안정감을 높일 수 있는 컨트롤 옵션 등이 중요하다.
멘탈 모델의 전환: 개발자는 '알고리즘 구현'보다는 '의도 표현(Intent Articulation)' 과 '문맥 구성(Context Engineering)' 에 집중해야 한다.
새로운 필요 역량: 프롬프트 엔지니어링, 작업 분해 능력(Task Decomposition), 그리고 AI가 만든 결과물을 검증하는 품질 감독 능력이 코딩 능력보다 중요해진다.
책임과 신뢰의 문제: AI가 버그를 만들었을 때 누구의 책임인가? 개발자가 AI를 맹신(Over-reliance)하거나 지나치게 불신하는 문제를 어떻게 해결할 것인가에 대한 조직적 논의가 필요하다.
주니어들에게 더 이상 간단한 코드 작성 작업보다는 요구사항 명세 작성이나 테스트 시나리오 설계에 집중하게 될 수 있다. 이때 숙련된 개발자와 초급 개발자 간의 업무 분담을 어떻게 새롭게 정의할지, 조직 내 평가 체계나 커리어 패스를 어떻게 조정할지도 인적 측면의 과제다.
인간이 최종 결정권자로 남아있는 구조를 어떻게 구현할지도 고민해야 합니다. 자동화된 에이전트에게 과업을 위임하더라도, 중요한 제품이나 시스템에 대해서는 인간이 결과를 최종 승인하도록 하는 Human-In-The-Loop 메커니즘을 설계함으로써 예측하지 못한 실수를 방지해야 한다.

출처

논문 원본 - https://arxiv.org/abs/2510.12399
바이브 코딩 어원 트윗 - https://x.com/karpathy/status/1886192184808149383
마르코프 결정 과정(Constrained MDP)
CodeCoR: An LLM-Based Self-Reflective Multi-Agent Framework for Code Generation
Claude CLI가 홈 디렉터리를 삭제해 Mac이 초기화되었어요

python - 기본적인 파이썬 스타일 가이드와 import, init 그리고 모듈화

Wed, 12 Nov 2025 16:52:58 GMT

[ 글의 목적: 파이썬 스타일 가이드와 import & init, 기본적인 "모듈화" 팁 기록, ~~사실은 교육자료로 쓰려고 작성함~~ ]

파이썬 스타일 가이드와 import, init 그리고 모듈화

python 의 자유도 덕분에 진입 장벽이 낮기에 초기엔 코드 스타일이 굉장히 다이나믹하다.. (정말 막 써도 실행이 되니까..!) 하지만 코드는 작성하는 시간보다 읽는 시간이 길다. 그리고 우리는 항상 AI를 포함한 '누군가' 와 같이 일한다. 일관된 스타일은 가독성을 높이고 유지보수 비용을 낮춘다. 특히 LLM의 시대에는 이 규칙, 일관성이 더 중요해지고 있고 Zen of Python 에서도 “Readability counts” 라고 강조한다.

이 글에서는 PEP 8 (Python 공식 스타일 가이드)과 Google Python Style Guide (대규모 협업을 위한 권장 규칙), PEP 484 (타입 힌트 표준), 그리고 Python import 시스템 (정규 패키지 vs 네임스페이스 패키지, 절대 vs 상대 import)에 기반하여 글을 작성해보고자 한다.

1. 스타일 가이드

1) PEP8 핵심

PEP 를 처음듣는다면 잠깐 이 글을 추천.

네이밍(Naming): 함수·변수는 소문자 스네이크케이스(snake_case), 클래스는 단어마다 대문자(CapWords/PascalCase) 사용, 상수는 대문자+snake_case로 작성한다. (예: MAX_COUNT)
들여쓰기(Indentation): 스페이스 4칸을 사용한다. 탭 혼용은 금지되고, 기존 코드가 탭을 쓰지 않는 한 새 코드에는 탭을 사용하지 않는다.
라인 길이(Line Length): 한 줄에 79자 제한을 권장한다. Docstring이나 주석은 72자 이내로 줄 바꿈한다. (팀 합의로 88자나 100자 등으로 늘릴 수도 있으나, 일단 팀 내부에서는 일관성 있게 유지해야 한다. PEP 8에 따르면 팀 프로젝트의 경우 99자까지 허용할 수 있지만 docstring/comment는 여전히 72자 권장이다.)
- 정말 왈가왈부가 많은 부분이다 ㅎㅎ. 개인적으로 88자~100자 사이를 더 선호한다. 특히 logging 처리나 문자열처리에 이 길이제한이 너무 과하다고 많이 느낀다.
공백/여백(Whitespace): 불필요한 공백을 지양한다. 예를 들어 쉼표나 콜론 앞에는 공백을 넣지 않고 뒤에만 넣는다. 키워드 인자 기본값 설정 시에도 = 양옆에 공백을 넣지 않는 것이 규칙이다.
- 타입 힌트가 있을 때는 예외: def func(arg: int = 0) -> None: 처럼 기본값 설정의 = 앞뒤에 공백을 넣는 것이 권장된다.
- 추가로 주석은 스페이스 2칸을 띄우고 # 주석 을 붙인다.
import 순서: PEP 8 권장 순서는 ① 표준 라이브러리 ② 서드파티 ③ 로컬 모듈 순으로, 각 블록마다 알파벳 순서를 유지한다. 각 그룹 사이에는 빈 줄을 넣어 구분한다.
- 완전 사견이고 취향일 수 있는데 여기서 python에 얼마나 익숙한지 차이가 보인다고 느껴진다. 왜냐면 애초에 처음 python을 사용하면 표준 라이브러리, 서드파티를 잘 구분못하기에...
Docstring: 공개 API에는 Docstring을 작성하고, 세부 규칙은 PEP 257을 따른다. 요약은 한 줄로, 이어서 공백 줄, 그리고 자세한 설명 순으로 적는다. 따옴표 3개(""")로 감싸고, 한 줄 요약은 마침표로 끝내도록 한다.
사람 대신 자동 포매터(formatter) 와 린터(linter) 가 스타일을 강제하도록 해보자! uv & ruff 설치부터 project initializing 참조!

개인적으로 어떤 언어든 익숙해지기전부터 save할때 auto-formatting 은 절대 비추천한다. 린팅과 포멧팅을 수기로 돌리는게 이런 rule에 대해 익숙해지기 쉽다고 생각한다.

2) Google Python Style Guide 포인트

https://google.github.io/styleguide/pyguide.html 참조. 많아보이지만 생각보다 복잡하지 않아서 한 10분이면 한 숨에 다 읽을 수 있다.

구글 스타일가이드에서 가장 핵심포인트는 “이렇게 해도 된다”보다 “이렇게 하지 말라”는 금지를 분명하게 한다는 점이다.

PEP 8 기반 + 명확한 가이드: Google 스타일 가이드는 기본적으로 PEP 8을 따르면서, 각 항목마다 팀 컨벤션으로서 “Yes/No”와 권장/비권장/결론을 명시해준다. 이를 통해 스타일 논쟁을 줄이고 모두가 동일한 결정을 따르도록 유도한다.
Docstring과 타입: Google 스타일 가이드는 Docstring에 Args/Returns/Raises 섹션을 명확히 적는 형식을 제시하며, 함수와 메소드에 타입 힌트 사용을 적극 권장한다. 예를 들어, 인자와 리턴 타입을 명시하고, 예외 발생 가능성을 Docstring에 기술하도록 권고한다. 또한 새로운 공개 API를 작성할 때는 반드시 타입 어노테이션을 포함하고, pytype 등의 정적 검사기를 CI에 적용할 것을 요구한다. (PEP 484의 선택적 타입 체크 개념을 적극 도입하는 추세와 맥을 같이 한다.)

def analyze_sales_data(
    transactions: list[dict[str, str | int | float]],
    min_amount: float = 0.0,
    category_filter: str | None = None
) -> dict[str, float]:
    """거래 데이터를 분석하여 카테고리별 총액을 계산합니다.

    Args:
        transactions: 거래 정보를 담은 딕셔너리 리스트.
            각 딕셔너리는 'category', 'amount', 'date' 키를 포함해야 함
        min_amount: 집계에 포함할 최소 거래 금액 (기본값: 0.0)
        category_filter: 특정 카테고리만 필터링 (None이면 모든 카테고리 포함)

    Returns:
        카테고리명을 키로, 총 거래액을 값으로 하는 딕셔너리

    Raises:
        ValueError: min_amount가 음수인 경우
        KeyError: 필수 키('category', 'amount')가 누락된 경우
    """

    if min_amount < 0:
        raise ValueError("min_amount는 0 이상이어야 합니다")

    result: dict[str, float] = {}

    for transaction in transactions:
        # 필수 키 검증
        if 'category' not in transaction or 'amount' not in transaction:
            raise KeyError("거래 데이터에 'category'와 'amount' 키가 필요합니다")

        category = transaction['category']
        amount = transaction['amount']

        # 타입 검증 및 변환
        if not isinstance(category, str):
            continue
        if not isinstance(amount, (int, float)):
            continue

        # 필터링 조건 확인
        if category_filter and category != category_filter:
            continue
        if float(amount) < min_amount:
            continue

        # 집계
        result[category] = result.get(category, 0.0) + float(amount)

    return result

명확한 금지 규정: 예를 들어 mutable 한 type 기본 인자 사용 금지, 예외 사용 가이드, global 변수 사용 지양 등 실무에서 발생하는 문제 상황에 대한 규칙이 제시되어 있어, 팀원들이 의도를 파악하기 쉽다.

그러니 당장 인하우스에서 직접 A to Z 코드 스타일 정의하기 어렵다면, 그냥 PEP8 + Google Python Style Guide 를 그대로 녹이는 건 어떨까?

3) “mypy 같은 static type checker 없어도” 시그니처 힌트 습관화!

PEP 484(Type Hints)은 파이썬에 표준화된 타입 표기법을 도입한 제안으로, 3.5 버전부터 적용되었다. 이는 타입 주석을 활용해 정적 분석과 리팩토링, IDE 지원을 개선하려는 목적이었다. 예를 들어 함수 인자와 반환값에 타입을 써두면, IDE가 자동완성이나 오류 검출을 더 잘해줄 수 있다.
동적 타입 언어에 선택적 적용: 타입 힌트는 강제 사항이 아니며, 런타임에 아무 검사도 하지 않는다. 파이썬 인터프리터는 타입 어노테이션을 무시하고 (__annotations__ 에 저장만 함) 실행에 영향을 주지 않는다. 대신 mypy 같은 별도 오프라인 타입 체크 도구로 검사하도록 설계되었다. 다시 말해 파이썬은 여전히 동적 타이핑 언어이고, 타입 힌트는 권장사항일 뿐이다. (PEP 484에도 “타입 힌트를 절대 의무화하지 않을 것”이라고 명시되어 있다.)
그럼에도 불구하고, 타입 힌트는 점진적으로 많은 프로젝트에서 채택되고 있다. 표준 라이브러리의 typing 모듈이 다양한 타입 힌트 표현을 제공하고, Python 3.9+에서는 list[int] 같이 내장 컬렉션에 제네릭 표기를 지원하며, 3.10부터는 X | Y 형태의 유니언 표기법도 추가되는 등 타입 힌트 문법이 꾸준히 발전 중이다.
- 그러니 from typing 과 같은 import 는 이제 사실 굳이..? 필자는 그렇기에 최소 3.10 이상, 가능하다면 3.12 이상 사용을 권한다.
- dataclass, Pydantic 에서도 이 제네릭 표기를 지원한다!

새 코드엔 타입 힌트 권장: 팀 차원에서 새로운 함수나 메소드를 작성할 때는 파라미터 타입과 리턴 타입을 꼭 명시하도록 한다. 기존 코드를 리팩토링할 때도 함수 시그니처에 타입을 추가하는 것을 권장한다. (Google Style Guide도 신규 public API에 타입 어노테이션을 반드시 추가하도록 요구한다.)
컨테이너 타입 명시: list[int], dict[str, Any] 처럼 내부 요소 타입을 제네릭으로 명시한다. Python 3.9부터 list[int] 구문을 지원하므로 별도 from typing import List를 하지 않고도 표기가 가능하다. 불특정 타입은 Any를 사용하고, 가능하면 구체적인 Protocol이나 TypeVar로 대체를 고민한다.
유니언과 옵션: X | Y 표기 (typing.Union[X, Y]의 축약)로 여러 타입을 허용할 수 있다. Optional[X]도 X | None으로 쓸 수 있다 (| 연산자 지원은 Python 3.10+).

TypedDict/Protocol 활용: 복잡한 구조는 TypedDict(PEP 589)로 키-값 타입을 정의하거나, Protocol(PEP 544)로 인터페이스를 정의해두면 코드 이해에 도움이 된다. 이러한 고급 타입은 팀원들이 충분히 숙지한 경우에 단계적으로 도입한다.

아래는 타입 힌트를 포함한 간단한 함수 예시이다. 타입 힌트로 함수의 입력과 출력이 명확히 드러나므로, 읽는 사람이 함수 의도를 쉽게 파악할 수 있다. 또한 잘못된 타입을 넣으려고 하면 IDE나 린터가 경고해줄 수 있다.

from typing import Iterable, Sequence

def topk(items: Sequence[int], k: int) -> list[int]:
    """Return top-k largest integers from the sequence."""
    if k < 0:
        raise ValueError("k must be non-negative")
    return sorted(items, reverse=True)[:k]

def join_csv(tokens: Iterable[str]) -> str:
    """Join iterable of strings into one CSV string."""
    return ",".join(tokens)

위 코드에서 topk 함수는 정수 시퀀스를 받아 상위 k개 정수를 리스트로 반환하며, join_csv는 문자열 이터러블을 받아 콤마로 연결한 문자열을 반환한다. 각각 타입 어노테이션(Sequence[int], list[int], Iterable[str], str)을 달아두었기 때문에 함수 사용법이 명확해진다.

이제 대부분의 DTO 도 dataclass 선에서 모두 정리가 가능하다. python - 파이써닉한 dataclass 와 ENUM

2. 모듈화, import, init

1) Python import 시스템 개요

모듈과 패키지: 파이썬에서 파일 하나(.py)는 곧 모듈(module)이고, 폴더는 패키지(package)로 취급된다. 모든 패키지는 모듈의 한 종류일 뿐이며, 단지 __path__ 라는 속성을 지닌 모듈이 패키지가 된다. 서브패키지는 점으로 상위 패키지와 연결된 "네임스페이스" 로 구성된다! (예: email.mime.text는 email 패키지 아래 mime 패키지의 text 모듈).
"네임스페이스" 라는 단어가 아직 익숙하지 않다면, 다음 2개의 링크 및 글을 추천한다. (1) 네임스페이스 설명 위키, (2) Namespaces in Python
정규 패키지 vs 네임스페이스 패키지: 파이썬 3.2까지의 전통적인 패키지는 정규 패키지(regular package) 로, 해당 디렉터리에 __init__.py 파일이 있어야 패키지로 인식되고 첫 import 시 __init__.py 가 실행되어 패키지 네임스페이스가 구성된다. 반면 파이썬 3.3부터 도입된 네임스페이스 패키지(namespace package) 는 __init__.py 없이도 패키지로 인식되며, 하나의 논리 패키지를 여러 디렉터리에 걸쳐 분산시킬 수 있다. 즉, 동일한 패키지 이름을 가진 폴더가 여러 경로에 있어도 하나의 패키지 네임스페이스로 합쳐진다 (이 기능은 PEP 420에 정의됨).
사실 __init__.py 은 구버전의 잔재로 보이지만 여전히 활용도가 높다. 파이썬 3.4부터 import 동작을 표현하는 ModuleSpec 객체 개념이 도입되었다. importlib.machinery.ModuleSpec 은 모듈을 찾고 적재할 때 필요한 메타데이터를 담고 있어, import 시스템을 더 일관되고 투명하게 만들었다. PEP 451 덕분에 finders/loaders 등의 내부 API가 단순화되고 향후 개선의 발판이 마련되었다. (이 부분은 import 훅을 직접 구현하는 경우를 제외하면 파이썬 사용자에게 내부 동작이 투명해진 정도의 의미가 있다.)

Python's Import System - Module object|Regular/Namespace Packages|Finders & Loaders|Relative imports 영상을 아주 적극적으로 추천한다.

2) init.py의 탄생 배경과 현재 위치

과거의 역할: 과거 파이썬에서는 디렉터리가 패키지로 인식되기 위해 반드시 __init__.py 파일이 필요했다. 이 파일이 존재하면 해당 폴더를 패키지로 간주하여 import 할 수 있었고, import 시 파일 내부의 코드가 실행되면서 패키지 초기화가 이루어졌다. 또한 패키지 수준에서 사용될 변수나 함수를 정의하거나, 하위 모듈을 import 해서 네임스페이스에 미리 올려주는 등의 초기화 용도로 활용됐다.
PEP 420 이후: 파이썬 3.3부터는 __init__.py 가 없어도 패키지를 만들 수 있게 되었는데(Implicit Namespace Packages, PEP 420), 여러 분산된 패키지를 하나로 취급할 수 있는 유연성이 생겼다. 따라서 지금은 꼭 필요하지 않은 경우라면 패키지 초기화 파일을 생략할 수 있다. 예컨대 단순히 여러 작은 패키지를 모아 네임스페이스만 공유하고 싶은 경우(예: company.plugin.alpha, company.plugin.beta 등 여러 배포 패키지를 하나의 논리 패키지로 묶을 때) __init__.py 없이도 동작하게 할 수 있다.

3) 그럼에도 실무에서는 init.py가 다음 상황에서 여전히 유용하거나 필요하다.

초기화 코드가 필요한 경우: 패키지 import 시 한 번 실행되어야 하는 설정이나 검증 코드가 있다면 __init__.py 에 넣어둘 수 있다. 네임스페이스 패키지는 이러한 코드를 쓸 곳이 없다.

# mypackage/__init__.py
import sys
import logging

# 패키지 버전 정의
__version__ = "1.0.0"

# 최소 Python 버전 검증
MIN_PYTHON = (3, 8)
if sys.version_info < MIN_PYTHON:
    raise RuntimeError(
        f"This package requires Python {MIN_PYTHON[0]}.{MIN_PYTHON[1]} or higher. "
        f"You are using Python {sys.version_info.major}.{sys.version_info.minor}."
    )

# 패키지 레벨 로거 설정 (한 번만 실행)
logger = logging.getLogger(__name__)
logger.addHandler(logging.NullHandler())

print(f"Initialized {__name__} v{__version__}")

# main.py
import mypackage  # "Initialized mypackage v1.0.0" 출력 + 버전 검증 실행

print(mypackage.__version__)  # "1.0.0"
print(mypackage.logger)  #

정규 패키지의 경우, 최초 import package 시에 package/__init__.py 가 실행되어 패키지의 __dict__ (네임스페이스)이 채워진다. 이때 필요한 변수를 설정하거나, 로그를 설정하는 등 초기화 작업을 수행할 수 있다. 다만, 복잡한 초기화는 지양하고 가능하면 최소한의 작업만 하는 것이 좋다 (import 시간 지연을 피하기 위해).

공개 API 재노출: 패키지 내부 구현 경로를 숨기고, 일관된 상위 API만 노출하고 싶을 때다. __init__.py 에서 하위 모듈의 클래스나 함수를 import 해서 상위 패키지 네임스페이스에 올려주면, 사용자는 깊은 경로를 신경쓰지 않고도 일관된 방법으로 사용할 수 있다.

*** 가령 디렉토리 구조가 아래와 같을 때 *** 

mylib/
  __init__.py
  internal/
    __init__.py
    database.py  -> class DatabaseConnection
    auth.py      -> class Authenticator
  utils/
    __init__.py
    validators.py -> validate_email()

# mylib/__init__.py
"""공개 API 정의 - 사용자는 내부 구조를 몰라도 됨"""

# 내부 모듈에서 핵심 클래스/함수만 가져와서 패키지 최상위 네임스페이스에 노출
from .internal.database import DatabaseConnection
from .internal.auth import Authenticator
from .utils.validators import validate_email

# from mylib import * 시 노출할 항목 명시
__all__ = ["DatabaseConnection", "Authenticator", "validate_email"]

__all__ 에 명시된 이름들은 from package import * 할 때 가져올 대상이고, 일반 import에는 영향 주지 않는다.
이 방법은 서로 import 하는 것에 대한 이해도가 없다면! 순환 참조를 일으킬 수 있으므로 유의해야 한다. 특히 패키지 간 의존성이 복잡한 경우 __init__.py 에서 너무 많은 것을 가져오면 import 순환 문제가 생길 수 있다. 따라서 상호 의존성이 없는 경량 객체 위주로 활용하는 것이 좋다.

# 실제 사용 예시
# 사용자 코드 - 간결한 import (내부 구조 은닉)
from mylib import DatabaseConnection, Authenticator, validate_email

# 내부 경로를 알 필요 없음!
db = DatabaseConnection()
auth = Authenticator()
is_valid = validate_email("user@example.com")

패키지 리소스 접근: importlib.resources 등을 활용할 때, 패키지를 정규 패키지로 두는 편이 리소스 경로 관리가 명시적이다. 네임스페이스 패키지는 물리적 디렉터리가 여러 개일 수 있어 리소스 파일 관리가 복잡해질 수 있다. 예를 들어 files() 함수를 통해 패키지 리소스를 읽을 수 있다.

from importlib.resources import files
config_text = files("my_pkg.data").joinpath("config.toml").read_text(encoding="utf-8")

위 코드는 my_pkg/data/config.toml 파일을 읽는 예시다. 과거에는 pkg_resources 등을 사용했지만, 이제 표준 라이브러리에서 안전하고 일관된 방법을 제공하므로 이를 쓰는 것이 권장된다. 이처럼 패키지 구조와 코드가 분리되어 있을 경우(data 폴더 등), 정규 패키지의 __init__.py 에 해당 서브패키지를 명시적으로 import 해두면 (필요 시) 리소스 접근에도 용이하다.

4) 절대 vs 상대 import (PEP 328)

절대 경로 import 우선: 기본 원칙은 절대 경로 import를 사용하라는 것이다. 절대 import란 import my_project.utils.parser 또는 from my_project.utils import parser 처럼 최상위 패키지명부터 명시하는 방식이다.
이는 모듈 출처를 명확히 보여주며, 리팩토링(모듈 이동/이름 변경) 시에도 영향 범위를 좁게 만든다. PEP 8에서도 “모든 import는 기본적으로 절대 import로 해라. 내부 모듈과 표준 라이브러리가 이름 충돌할 경우 절대 import가 모호성을 줄인다”라고 권고한다.
상대 import 사용 시기: from . import submodule 같은 명시적 상대 import는 "동일 패키지 내 모듈을 참조할 때" 사용할 수 있다. 다만, PEP 8에 따르면 상대 import는 패키지 레이아웃이 복잡해서 절대 경로가 너무 장황해질 때 등 제한적인 경우에만 쓰고, 일반적으로는 지양한다. 특히 최상위 패키지 경로가 바뀔 수 있는 대형 프로젝트가 아니라면 절대 import로 충분하다. 상대 import를 남용하면 다른 개발자가 코드의 의존 관계를 파악하기 어려워질 수 있다.
Python 2와의 관계: PEP 328 이전엔 (Python 2 시절) 현재 패키지 기준의 암시적 import가 가능했지만, Python 3에서는 명시적 상대 import만 허용하고 기본은 절대 import로 동작한다. 요즘 코드는 모두 Python 3이므로 특별히 from __future__ import absolute_import 등을 신경 쓸 필요는 없지만, 과거 코드 일부를 가져올 경우 이런 맥락을 알아두면 도움이 된다.

`absolute_import` 왜 씀?

Python 2.4 이하에서는 패키지 내부에서 import string을 실행하면, Python이 먼저 패키지 디렉토리 내부에서 상대 import를 시도한다.

# 디렉토리 구조
pkg/
  __init__.py
  main.py
  string.py      # 사용자가 만든 모듈

# pkg/main.py (Python 2.4 이하)
import string  # 어떤 string을 import할까?

print(string)

Python 2.4 이하에서는 표준 라이브러리의 string 모듈 대신 같은 패키지 내의 pkg/string.py 를 import한다. 이것이 암묵적 상대 import(implicit relative import) 문제 다. 그래서 최상단에 from __future__ import absolute_import 를 사용해 이를 해결했다.

# pkg/main.py (Python 2.5+)
from __future__ import absolute_import

import string  # 이제 표준 라이브러리의 string을 import!

# 같은 패키지의 string.py를 import하려면 명시적으로:
from . import string as pkg_string  # 명시적 상대 import
# 또는
from pkg import string as pkg_string  # 절대 import

만약 여러분들이 매우 과거 python 과 씨름중이라면,, 레거시와 싸우고 있다면,, 이를 꼭 알아야 한다..!

5) 모듈화 원칙과 import/패키지 전략 팁!

아래 내용은 디자인패턴을 차치하고 관점을 SWE의 "모듈화" 에 맞춘 최소한의 가이드에 가깝다.

단일 책임 원칙(Single Responsibility Principle): 모듈이나 패키지는 하나의 역할에 집중하도록 설계한다. 예를 들어 api/, core/, utils/ 처럼 기능별로 디렉터리를 나누고, 각 디렉터리에는 그 책임에 맞는 모듈만 포함시킨다.
관심사 분리(Separation of Concerns): 계층 구조를 명확히 분리하여, 예컨대 api 패키지는 입출력(플라스크 엔드포인트 등)만, core 는 비즈니스 로직만, adapters 는 DB나 외부 API 연동만 담당하도록 한다. 이렇게 나누면 import 방향도 한쪽으로 흐르게 되어(상위 계층 -> 하위 계층) 순환 의존을 피할 수 있다.
안정된 API 노출: 내부 구현 세부 사항은 숨기고, 각 계층의 공개 API만 init.py 등을 통해 노출한다. 예를 들어 core/__init__.py 에서 핵심 서비스 함수만 import하여 외부에 공개하면, 바깥에서는 core.run() 처럼 사용하고 내부 구조가 바뀌어도 인터페이스는 유지할 수 있다. (다만 public, common API는 변경 시 호환성에 주의해야 하므로, 팀 합의하에 버전 관리나 deprecation 절차를 둔다.)
배포 관점: 실제 패키징(배포)할 때는 폴더 구성과 pyproject.toml/setup.cfg 메타데이터 등이 일관되어야 한다. 이는 PyPA(Python Packaging Authority) 에서 제공하는 가이드에 따라 설계한다. 프로젝트 루트에 pyproject.toml 설정을 두고, 패키지 폴더들은 src/ 디렉터리를 활용하는 등의 표준 패키징 레이아웃을 따르면 배포 시 문제가 적다. 또한 namespace 패키지를 쓸 때는 관련된 모든 배포 패키지에서 __init__.py 를 빼야 한다는 점도 유의한다. (한 군데라도 넣으면 네임스페이스 패키지가 제대로 동작하지 않는다.) PS. 참고로 PyPA는 "파이썬 패키징 관리 그룹" 이다.

my_project/
    api/          # 외부 요청/응답 처리 (입출력 계층)
        __init__.py   (공개 API 재노출)
        ...  
    core/         # 핵심 도메인 로직 (엔진/서비스 계층)
        __init__.py   (공개 API 재노출)
        ...
    adapters/     # DB, 외부 API 등 인프라 연동
        __init__.py   (필요한 경우 설정)
        ...
    utils/        # 여러 곳에서 쓰이는 공용 유틸리티
        __init__.py   (특별한 초기화는 없음)
        ...

각 패키지의 __init__.py 에는 해당 계층에서 외부에 공개할 필요한 심볼들만 임포트하여 노출한다. 예를 들어 core/__init__.py 에는 from .service import run 정도만 넣고 나머지 내부 구현은 숨긴다.
이렇게 하면 상위 레벨에서 from my_project.core import run 처럼 명확하게 쓸 수 있고, 내부 구조 변경이 있어도 run의 인터페이스만 유지하면 된다. 반면 utils 처럼 단순 헬퍼 모음이라면 굳이 __init__ 에 재노출을 하지 않고 각 모듈을 필요한 곳에서 직접 import 해 써도 무방하다.

출처

python - uv & ruff 설치부터 project initializing, 왜 주목 받는가?

Tue, 30 Sep 2025 17:44:02 GMT

[ 글의 목적: 의존성 관리와 패키징을 위한 uv 세팅 부터 활용 기록, 린팅과 포맷팅을 동시에 지원하는 ruff 까지 같이하는 세팅 기록 / *최종 업데이트 25.10.16* ]

uv & ruff 설치부터 project initializing

Uv, Ruff 모두 Astral(아스트랄) 회사의 오픈소스, 라이브러리이다. python 생태계는 정말 "파이써닉" 한 방향으로 계속 진화하고 있다. poetry 만 해도 엇그제 같은데, 아스트랄의 제품들이 정말 무서울 정도로의 속도로 관련 오픈소스들을 압살하고 있다..! 제일 대표작 Uv, Ruff 오픈소스를 개괄적으로 살펴보자!

실제 세팅만 보고 싶다면 2. uv & ruff 설치와 세팅 을 바로 보면 됩니다~

1. 왜 지금 uv와 ruff인가?

0) Astral(아스트랄) 을 아시나요?!

*"파이썬 생태계의 생산성을 높이는 고성능 개발 도구를 만든다"* 라는 일념하에 세워진 아스트랄은 창업자 Charlie Marsh 가 “파이썬 툴링은 훨씬 더 빨라질 수 있다” 는 가설을 Ruff 로 스스로 검증하며 쏘아올려졌다. ~~(상남자다..)~~ - Announcing Astral, the company behind Ruff

23년 4월, "We’ve raised $4m in seed funding led by Accel" 라고 언급되어 있듯, "400만 달러 - 한화 약 57억" 을 시드받고 날개를 활짝 핀 것 같다. 도구는 오픈소스(무료)로 유지하고, 그 위에 유료 hosted service를 만든다는 유료화 목표가 있는 것 같다. 아마 클라우드를 도입할 것 같은데, 어떻게 BM을 만들지 미래가 정말 궁금하다.

대표적으로 아래 3개에 집중하고 있다. 출시 순서도 ruff -> uv -> pyx -> ty 이다. 이 글에서는 ruff 와 uv 만 다뤄보고자 한다.

Ruff: 린팅·포매팅(편집기 통합 포함)
uv: 패키지/프로젝트/스크립트/도구/파이썬 버전까지 원스톱 관리
pyx: "Python-native package registry" -> 얘가 아스트랄의 첫번째 유료화 서비스이다. 아직 상용화는 안한 듯 하다. 클로즈 베타인지, 위시리스트를 받는 것 같다. - pyx: a Python-native package registry, now in Beta. 꽤 신박하니 소개 글 추천!
ty: 타입 체커, 얘는 진짜 핫하다. 2025-09-19 공개된 문서 - https://docs.astral.sh/ty/

1) 인기/성장 지표

● uv

Poetry 는 수년간 꾸준히 발전하며 약 33.9k 개의 스타를 얻었지만, 2024년에 등장한 uv 는 불과 1년 만에 스타 개수가 36k를 넘어섰다. 나중에 다시 언급하겠지만, 나는 poetry 가 가상환경을 더 불편하게 업데이트 한 것에 좀 불편함이 있다.

2024년 10월 기준으로 PyPI 에서 전체 패키지 다운로드의 약 13.3% 가 uv를 통해 이루어졌고, uv 자체도 월 2천8백만 건 이상의 다운로드 수를 기록 하며 거대한 성장세를 증명하고 있다. 도대체 어떻게 한건가..

● ruff

이 정도면 주작아닌가 싶을정도로 ruff 의 성장 기울기는 미쳤다. 불과 2년여 만에 ruff는 GitHub 스타 27k+ 를 돌파해 Black 을 포함한 기존 도구를 넘어섰다. 실제로 ruff는 주당 약 270개의 스타를 얻으며 핫한 프로젝트 1위에 올랐는데, 이는 Black의 스타 증가 속도(주당 약 107개)보다 두 배 이상 빠른 수치라고 한다. - AwesomePython

현재 Flake8, Black 등의 역할을 하나로 통합하면서도 수백만 건의 주간 다운로드를 보여주고 있다. 사실 이미 나도 린팅은 black & flake8 버리고 ruff 로 갈아타버렸다. 사실 python 에서 린팅을 위해 사전 세팅이 꽤 많다. 그리고 이를 위한 써드파티나 플러그인도 필요하니, toml 에 종속적인 것을 위해 ruff 로 갈아타고, 자연스럽게 uv 로 스며들고 있다.

2) uv 는 뭘 해결하고, 왜 빠를까?

아스트랄의 미션과 비전에 얼라인하는 "초고속 패키지/프로젝트 매니저" 오픈소스를 만든 것이다. pip, virtualenv, pipx, pyenv, poetry 등과 같은 도구를 "일원화" 하는게 가장큰 목표이다. 그리고 첫 탄생과 다르게 이제 uv 만으로 라이브러리를 배포하고 버저닝 할 수 있다. (나에게는 이게 가장 큰 요인이었다.) ~~언급된 도구들 진짜 다 써본 것 같은데 개인적으로 아나콘다가 최악이다..~~

uv ill like uv 글에 따르면 "Initially Armin Ronacher started rye as a “cargo for python” to unify the fragmented python tooling landscape (for a great overview check out this talk by Anna-Lena Popkes)." 라고 언급되어 있다.

Armin Ronacher가 시작한 실험적 패키징 툴 Rye 가 있는데, Astral의 창업자 Charlie Marsh가 이 아이디어를 이어받아 uv를 통합 후속 프로젝트로 출시한 것 이다.

현재 빠르다고 하는 애들보다 더 빠르다고 한다. (pip 대비 10~100배). 근본적인 빠른 이유는 Rust 기반 컴파일 바이너리파일이기 때문인데, 여러 최적화 스킬이 있다. - uv: Python packaging in Rust

글로벌 패키지 캐시를 도입하여 동일한 패키지를 반복 설치할 때 다시 다운로드하거나 빌드하지 않는다.
또한 파일 복사 시 Copy-on-Write와 하드링크를 활용하여 가상환경을 만들 때 디스크 복사 비용을 최소화하고
이어서 바로 종속성 해석을 같은 프로세스에 처리해서, python 을 중복 실행하는 오버헤드를 없앴다고 한다.

딥 위키에서 uv 를 보면 더 이해하기 쉽다. 시간있을때 https://deepwiki.com/search/-uv-python-installer-lets-thin_90419ea2-54e1-4a0d-81bd-8894df0eedb7 를 따라가면서 한 번 봐보자!

● pip은?

일단 pip 은 기본적으로 "순차적인 백트래킹" 방식으로 의존성 체크를 한다. 예로 1버전 시도 -> 충돌 -> 1.1버전 시도 이런식으로 말이다. 그렇기에 순환 참조를 포함한 복잡한 의존성 그래프에서는 최적의 조합을 찾지 못하거나 해결에 실패하는 '의존성 지옥(dependency hell)'에 빠질 수 있다. 게다가 이 과정에서 종종 전체 패키지 파일(wheel)을 다운로드하여 메타데이터를 확인해야 하므로 I/O 비용이 크다!

● uv는?

언급한대로 "SAT 해결기 기반 접근법" 을 사용한다. (SAT: Boolean Satisfiability Problem, 부울 충족 가능성 문제) 유사한 문제로 취급하는 PubGrub 알고리즘에서 영감을 받았다고 한다. - Resolver internals

3) uv 장단점, 기존 것과 비교

● uv 장점

rust 바이너리기반 훨등한 속도. Poetry Was Good, Uv Is Better: An MLOps Migration Story 에서 poetry 대비 CI/CD 속도가 기하급수적으로 빨라졌다는 (약 10배) 후기도 있다.
"찐 통합 툴". installer, pyenv, virtualenv 심플하게 할 수 있으며 (이상한) pipx 대신 uvx, uv tool 로 대신할 수 있다. uv publish 로 twine 없이 배포할 수 있다.
"표준 준수, 심플한 세팅". PEP 621/631 에 맞는 toml 하나로 패키지 메타데이터 + 의존성 관리가능! 특히 2024년 말 도입된 PEP 735(dependency groups 표준) 을 빠르게 지원.
uv sync, uv run 이 의존성 동기화를 "알아서 보장" 해줘서 workflow 의 몇 단계를 하나로 함축시킬 수 있음.

● 사견으로

poetry 대신 uv 로 무조건 모든 프로젝트를 넘어가지는 않았다. 위 4가지 장점은 사실 poetry 도 매우 잘 해준다. 다만 poetry 가 내게 불편 포인트를 줬던건 1) 다중 python 버저닝을 따로 다루는 것, 2) 가상환경을 즈그들 방식대로 한다는 점. 이다.

사실 2번이 매우 열받는 포인트인데, source .venv ... 로 vscode 에게 가상환경 먹여줘야 할 때, 그리고 중앙관리식 가상환경을 쓰면 오히려 사용자인 내가 가끔 까먹는다. 이게 관성에 벗어나는 방식이라...

또, 프로덕션에서는 나는 굳이 uv 또는 poetry 를 사용해서 서버를 운영하지는 않는다. 추가 써드파티나 의존성을 전혀 하고 싶지 않아서 인데, uv 는 오히려 production 에서도 사용해볼까 한다.

● uv 단점

CLI 커맨드가 꽤 많다. 그리고 생각보다 마냥 간단하지는 않다. uv lock --upgrade 과 같이 아니 왜 update 가 아닌건데? ㅎㅎ.
uv pip install 과 uv add 는 다르다. uv add 를 하고 uv sync 로 설치하는 흐름. 애매한 경계선에 있는 명령어들 때문에 헷갈릴 수 있다.
poetry 는 python 으로 만들어졌다. 근데 uv 는 rust 로 만들어졌다. 사실 python 생태계에서는 이게 꽤나 중요할지 모른다. rust 로 만들어진 python 을 위한 생태계 툴이라니,, 제 3의 기여자를 만들기 어렵다고 판단된다.

근데 아스트랄이 소통을 많이 하는 듯 하다. 다양한 장단점을 흡수하고 개선하며 정말 지속적으로 빠르게 발전하고 있다.

4) ruff 는 뭘 해결하고, 왜 빠를까?

아스트랄의 시작이자, 이름을 알린 태초의 라이브러리, ruff는 기존에 Python 코드 품질 관리를 위해 Flake8, isort, pylint, Black 등 여러 도구를 조합해야 했던 불편함을 해결하고자 했다. 위에 언급한대로, 아스트랄은 "파이썬 툴링은 훨씬 더 빨라질 수 있다" 는 가설을 Ruff 로 (Charlie Marsh) 스스로 검증하며 시작됐다.

PEP8 을 따라가기위해 pycodestyle 검사 (사내룰, 구글 스타일 가이드 등) -> flake8 -> isort (import 정렬) -> 포맷팅엔 black 등의 순서로 진행했고, 각 세팅마저 달랐다. 나의 과거글 python - flake8, Black 도입, pre-commit & clean code-style 실천하기 에서도 정말 간단한 세팅에 노고가 좀 필요했다.

근데 ruff 요놈은 한 번 딸각에 해결한다. 더욱이 uv 랑 같이쓰면 세팅이 매우매우 깔끔하고 편해진다. poetry 쓰는 사람들도 ruff 는 바로 써보면 좋겠다. poetry 랑도 합이 잘 맞는다.

● 왜 빠른가?

단순하게 Rust 기반이라서 빠른 것 보다, 핵심적으로 아래 3가지가 꼽힌다.

ruff는 파일 단위 병렬처리를 통해 다중 코어를 적극 활용.
- 수백 개 파일을 검사할 때 파일별 토큰화, 파싱을 스레드로 병렬 실행한다.
- 토큰화 과정 등에서 CPU의 SIMD 명령어를 활용하여 문자열 검색 같은 작업을 한 번에 묶어서 처리한다.
- Ruff: Extremely Fast Python Linter — Here’s Why
한번 소스 코드를 파싱하면 그 결과를 기반으로 여러 규칙을 한꺼번에 적용.
- 토큰화/구문분석을 단 1회만 수행하고 다양한 체크를 실행한다. 즉, 다중 검사일땐 사실 모두 토큰화가 필요했는데, 이를 뛰어넘을 수 있는 것이다!
저수준 구현에서도 세세한 최적화.
- 예를 들어 Python의 BigInt 처리에 대응하기 위해 Rust에서는 작은 정수는 64비트로, 매우 큰 정수만 힙 할당하도록 변경하여 정수 토큰화 성능을 약 8% 개선했고
- 토큰 위치를 내부적으로 “행-열” 대신 바이트 오프셋으로 저장하여 위치 계산을 빠르게 하는 기법으로 전체 처리 시간을 10% 감소시켰다고 한다.

이러한 세심한 튜닝 덕분에 ruff는 Flake8 등의 10~100배 속도로 코드베이스를 토큰화 하고 검사하고 포맷팅할 수 있다!

5) ruff 장단점, 기존 것과 비교

● ruff 장점

ruff는 하나의 툴로 800개 이상의 린트 규칙(기존 Flake8 플러그인 다수 포함)을 제공하고, 코드 자동포맷팅 기능도 지원한다.
린팅, 포맷팅 속도가 거의 실시간이다. 대규모 코드베이스에서도 ruff를 돌리는 데 걸리는 시간은 블링크 수준이라, 실시간 피드백을 받기에 충분하다.
더 이상 프로젝트에 flake8, black, isort 등을 모두 설치하고 설정할 필요 없이 [tool.ruff] 하나의 설정으로 일관성 있게 관리할 수 있다.
- 특히 ruff의 포매터는 Black과 >99.9% 동일한 결과를 내도록 설계되어, 기존 Black 사용 프로젝트도 쉽게 ruff로 전환할 수 있다.
- 예를 들어 Django 전체 코드 포맷 비교에서 ruff와 Black의 결과 차이는 극히 일부분(2772개 파일 중 34파일)뿐이었다고 한다.
- ruff가 기본적으로 Black의 스타일 가이드를 따르고, 라인 길이 등 기본값도 Black과 동일하게 설정되어 있어서 기존 코드에 최소한의 변경만 주기 때문.
ruff는 IDE/에디터 통합과 CI 연동이 잘 되어 있다! (탄생때부터 이걸 노린 듯하다.)
- VS Code 확장이나 PyCharm 플러그인 등이 이미 나와 있어 빠른 피드백을 얻을 수 있고
- GitHub Actions용 액션이나 pre-commit 훅도 공식 지원하여 쉽게 품질 검증 파이프라인에 넣을 수 있다.
ruff는 지금까지도 빠르게 진화하고 있다. 규칙 커버리지도 계속 늘어나고 있고, 향후 static type checker(ty) 까지 개발 중일 정도로 툴체인 확장을 모색하고 있다.

● ruff 단점

ruff는 기본적으로 모든 검사를 내장하고 있어, Flake8처럼 사용자가 간편하게 플러그인을 추가하는 방식은 지원하지 않는다.
- 따라서 혹시 기존 프로젝트에서 매우 특수한 Flake8 플러그인을 쓰고 있었다면, 또는 사내 전용 flake8 룰세팅이 있다면, 직접 개발하지 않는 이상 이를 도입할 수 "없다".
- ruff에 해당 규칙이 구현되길 기다리거나 직접 기여해야 한다. (그래도 인기 있는 검사들은 거의 다 포함되어 있고 부족한 부분도 빠르게 채워지고 있다고 한다.)
Pylint 처럼 "정적 분석 수준에서 코드의 논리적 버그" 까지 잡아주는 기능은 ruff에는 없다. (ruff는 타입체커가 아니고 주로 스타일, 버그 패턴 위주 검사임).
- 타입 안정성 검사 등을 위해서는 mypy 같은 도구를 별도로 운용해야 할 수도 있다. (이는 앞서 언급한 장점대로, ty 등과 캐미가 어떻게 되냐에 따라 굉장히 달라질 듯 하다.)
- 그 외에 ruff 역시 Rust로 만들어졌다는 점에서, Python으로 작성된 flake8/pylint보다 사용자가 룰을 커스터마이징하거나 기여하기 어렵다는 의견이 있다.

2. uv & ruff 설치와 세팅

MacOS 기준

1) uv install & init

$ curl -LsSf https://astral.sh/uv/install.sh | sh

다른 공식자료들, 외부 자료들 때문과 PATH 때문이라도 로 brew 로 하지 않았으면 한다.. Rust나 Python이 없어도 uv 바이너리를 시스템에 설치해준다.

$ mkdir myproject && cd myproject
$ uv init .

타 써드파티와 매우 유사하다. init 을 하면 pyproject.toml 이 만들어지며 poetry 와 유사하게 [project] 메타데이터 및 의존성 섹션을 활용한다. README.md, .python-version 과 git 까지 세팅해준다.

uv init --lib mylib       # 라이브러리 템플릿
uv init --package mypkg   # 패키징 가능한 프로젝트(기본 빌드 시스템 부여)

재미있는 포인트는, 라이브러리 템플릿, 패키징 가능한 플젝 템플릿도 바로 제공해준다.

2) uv 파이썬 버저닝과 가상환경

● python 버전 변경

uv python pin 3.13 과 같이 하며, 자동으로 관련 값들을 업데이트 해준다.

uv python list 로 내가 지금 설치한 python version 과 path 를 모두 한 눈에 확인할 수 있다. 좋다! 물론 이는 위 사진에서 cpython-3.13.0-... 을 보면 알겠지만 alias 를 포함한 것이다. (정확하게는 심볼릭 링크)

● 가상환경은 어떻게 함?

오피셜하게는 uv venv 이다. 근데 uv run 을 하면 가상환경과 프로젝트 세팅 & 인터프리터 세팅을 바로 할 수 있다. 즉, 뭔가를 지금 플젝에 세팅한대로 python 을 실행할때, 마치 poetry run ... 처럼, uv run ... 을 하면 된다.

uv add fastapi 와 같이 패키지를 설치하며, 기존 가상환경이 없으면 add 만으로 바로 가상환경을 만든다.

결론적으로 "가상환경 activation은 source .venv/bin/activate 와 같이, 개인적으로 나에게 아주아주 익숙하고 편한 방식으로 관리할 수 있다. 진짜 이름마저 찰떡.

● lock file 다루기

만약 패키지매니저가 처음이라면, lock 이 익숙하지 않을 수 있다. 간단하다. "모든 개발자·머신·배포 환경에서 동일한 설치 결과를 재현하기 위해" uv.lock 을 사용한다. 그래서 플랫폼(운영체제/아키텍처/파이썬 버전) 차이까지 고려한 보편(크로스플랫폼)적인 패키지 정보들을 제공한다.

uv lock 으로 lock file 을 만들고 기존 lock 과 uv lock --check 로 최신성만 빠르게 검사할 수 있다. uv run --locked 와 uv sync --locked 으로 엄격한 모드로 실행하고 싱크를 맞추게 할 수 있다.

그리고 add 와 pip install 핵심 차이는 아래와 같다. (lock file 갱신 여부 차이)

- `uv add`: pyproject/lockfile **갱신** + .venv 설치
- `uv pip install`: lockfile **미갱신**(실험/임시 설치에 유용)

3) uv 적용하기 (not uv to uv || uv sync)

● 다른 uv 기반 플젝에서 시작하기

uv.lock 이 있다면 uv sync 한 번 으로 가능하다. (사실 이건 poetry 도 그럼). 락파일이 있다면 그 버전 그대로 설치하고, 락파일이 없고 pyproject.toml 만 있다면 uv sync 하기 전에 uv lock 으로 명시적 생성 후 실행하는 것을 추천한다.

그 외 아스트랄 uv 공식 docs의 Features 에서 확인하길 바란다. uv tree, uv build, uv publish 사실 poetry 랑 거의 동일하다고 느껴진다.

● pip 또는 타 패키지매니저에서 시작하기

일단 버저닝을 진짜 100% 완벽하게 하고 싶다면, "준비된 requirements.txt" 로 시작하는게 가장 깔끔하다.
해시와 python 지원 버전이 같이 명시된 require 파일이면 베스트지만, 버전까지만 명시되어도 괜찮다. 어짜피 uv 가 나머지를 판단해준다. uv init 을 하자!
그리고 python version 맞추는게 중요할텐데, uv python pin 3.13 를 하거나 uv init --python 3.13 로 시작한다. 만약 local 에 해당하는 python version이 없다면? uv python install 3.13 를 하면 된다.
이제 uv add -r requirements.txt 로 설치하면 끝이다. 관성적으로 흐름이 정말 기존 tool과 크게 다르지 않다.
또는 기존 txt의 고정 버전을 제약(constraints) 으로 적용해 uv.lock에 반영하려면, uv add -r requirements.in -c requirements.txt 를 하자. - Migrating from pip to a uv project
혹시 모르니 uv lock -> uv sync 로 완벽하게 lock file 도 싱크를 맞춰주자.

4) ruff install & init

uv 를 쓴다고 가정하고, ruff 를 설치할땐 아래와 같이 한다. "--group" 이 앞서 언급한 PEP 735(dependency groups 표준) 이다.

$ uv add --group dev ruff

위 사진과 같이 dependencies.dev 섹션에 추가 된다. poetry add -D ruff 와 동일한 맥락이다. 근데 설치없이 uv 의 uvx 를 통해 바로 실행할 수 있다! (이는 비추천)

uvx ruff check
uvx ruff format

● 기본 사용법

린팅

ruff check .                 # 재귀적으로 모든 파이썬 파일 검사
ruff check path/to/file.py   # 특정 파일
ruff check . --fix           # 자동 수정 가능한 항목만 적용
ruff check --unsafe-fixes        # 비적용이지만 제안 표시
ruff check --fix --unsafe-fixes  # 실제 적용

포맷팅

ruff format                  # 코드 포맷
ruff format --check --diff   # CI에서 포맷 불일치 검출

● 기존것들이랑 섞어서 쓸 수 있음?

Migrating to ruff from black and flake8 글과 같이 ruff의 목표는 Black, Flake8, isort 등을 모두 대체하는 것 이므로 굳이 기존 린터/포매터를 함께 쓸 필요는 없다.

Black 대체: 만약 기존에 Black으로 포맷팅해오던 프로젝트라면, ruff 설치 후 ruff check --diff 실행과 black 실행의 차이점 파악. 상호 세팅 차이가 있는 것을 업데이트 하고 (포메팅 규칙) black 을 삭제하면 된다.
Flake8/기타 린터 대체: 맥락은 거의 위와 동일하다. Flake8 설정(.flake8이나 setup.cfg의 [flake8] 섹션 등, 와 이거 진짜 개인적으로 싫다.)
그 외는 아래 표를 살펴보자!

도구 / 플러그인	ruff로 대체 가능?	ruff 규칙 접두사	참고
Flake8	예	F (Pyflakes), E/W (pycodestyle)	대부분의 조건에서 완벽하게 대체 가능합니다.
Black	예 (포맷터)	ruff format	99.9% 이상 호환되지만 일부 의도된 차이점이 있습니다.
isort	예	I	임포트 정렬 기능이 내장되어 있습니다.
pyupgrade	예	UP	최신 파이썬 문법을 제안합니다.
flake8-bugbear	예	B	잠재적인 버그와 설계 문제를 찾아냅니다.
flake8-comprehensions	예	C4	더 관용적인 컴프리헨션 작성을 돕습니다.
pydocstyle	예	D	독스트링 컨벤션을 강제합니다.
flake8-bandit	예	S	일반적인 보안 문제를 확인합니다.
Pylint	부분적으로	PL	ruff는 완벽한 대체재가 아니며, 규칙 집합이 다릅니다.
사용자 정의 플러그인	아니요	해당 없음	ruff는 서드파티 플러그인을 지원하지 않으며, 규칙은 핵심 프로젝트에 기여해야 합니다.

5) uv + ruff default conf (with pre-commit hook)

pre-commit hook 이 뭔가요?! 한다면 -> python - flake8, Black 도입, pre-commit & clean code-style 실천하기 글을 참조해 주세요!

● `.toml` 에 세팅하기

# ================================================================
# Ruff (Linter & Formatter) Settings
# ================================================================
[tool.ruff]
# 수정에서 제외할 파일 및 디렉토리 목록
exclude = [
    ".bzr",
    ".direnv",
    ".eggs",
    ".git",
    ".hg",
    ".mypy_cache",
    ".nox",
    ".pants.d",
    ".pytype",
    ".ruff_cache",
    ".svn",
    ".tox",
    ".venv",
    "__pypackages__",
    "_build",
    "buck-out",
    "build",
    "dist",
    "node_modules",
    "venv",
    "*/migrations/*.py",
]
# 한 줄의 최대 글자 수
line-length = 120

# --- Linter (코드 분석기) 설정 ---
[tool.ruff.lint]
# 활성화할 규칙 선택:
# E, W: pycodestyle (에러, 경고)
# F: Pyflakes (논리적 오류)
# I: isort (import 정렬)
select = ["E", "F", "W", "I"]
ignore = []

# 모든 수정 가능한 규칙을 자동으로 고치도록 설정
fixable = ["ALL"]
unfixable = []

# --- Formatter (코드 포맷터) 설정 ---
[tool.ruff.format]
# Black과 유사한 포맷팅 스타일을 따릅니다.
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false
line-ending = "auto"

# --- 플러그인별 상세 설정 ---
[tool.ruff.lint.isort]
# 프로젝트에서 사용하는 서드파티 라이브러리 목록
known-third-party = ["django", "rest_framework", "graphene_django"]

# --- 파일/디렉토리별 규칙 무시 설정 ---
[tool.ruff.lint.per-file-ignores]
# settings 파일: 와일드카드 import 허용
"config/settings/*" = ["F403", "F405"]

# __init__.py 파일: 하위 모듈 노출을 위한 미사용/와일드카드 import 허용
"**/__init__.py" = ["F401", "F403"]

# 테스트 파일: 가독성을 위해 긴 줄 허용
"**/test_*.py" = ["E501"]

# 긴 문자열이 많은 파일들, 줄 길이(E501) 등 규칙 무시
"utils/(모자이크)/*" = ["E501", "W291", "W293"]
"batch/*" = ["E501", "W291", "W293"]
"artifacts/*" = ["E501", "W291", "W293"]

# 기타 특정 파일들의 줄 길이(E501) 규칙 무시
"utils/(모자이크).py" = ["E501"]
"config/(모자이크)/(모자이크).py" = ["E501"]
"config/(모자이크).py" = ["E501"]
"apps/(모자이크).py" = ["E501", "W291"]

위는 실제 내가 프로젝트에 적용해서 사용하는 ruff 세팅이다. 통으로 수정을 제외하는 디렉토리, 한 줄 최대 글자 수, 활성화 린팅 그룹 세팅과 포맷팅 세팅, 자체 플러그인, 자체 써드파티, 특정 파일의 특정 규칙만 무시하기!

[tool.ruff.lint] 에서 I 를 추가했기에 import 역시 isort 대로 린팅&포맷팅을 한다.

● uv pre-commit

https://github.com/astral-sh/uv-pre-commit 에서 uv 관련된 pre-commit 들을 볼 수 있다. 특히 배포환경에서는 uv 등의 패키지매니저를 굳이 사용하지 않을때 중요한건 requirements.txt 을 lock file 에 준하게 strict 한 버전으로 만들어야 한다는 것! 그래서 아래와 같은 pre-commit 을 사용할 수 있다!

- repo: https://github.com/astral-sh/uv-pre-commit
  # uv version.
  rev: 0.8.22
  hooks:
    - id: uv-export

uv export --format requirements.txt --all-groups --output-file requirements.txt 로 dev 그룹을 포함한, dev를 제외하려면 --no-dev, lock file 기준의 requirements file을 얻을 수 있다.

uv export --format requirements-txt --all-groups > requirements.txt 로도 가능하다.

● ruff pre-commit

이 정도 pre-commit 은 세팅하자.

repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
  rev: "v0.13.2"  # 사용하고자 하는 ruff 버전 태그
  hooks:
    - id: ruff-check    # 린트 검사 (--fix 없을 경우 검사만)
      args: [--fix]      # 자동수정 활성화 - 권장
    - id: ruff-format   # 포매팅 (Black 대체)

● CI/CD, github actions 에서 workflow

- uses: actions/checkout@v4
- uses: astral-sh/ruff-action@v3

CI/CD 파이프라인에 추가할때 위와 같이 넣으면 된다!

● `.vscode` 에서도 쓰려면

.vscode/settings.json 에 아래 설정값을 추가해보자!

{
  "[python]": {
    // 1. 기본 포맷터를 'ruff'로 지정합니다.
    "editor.defaultFormatter": "charliermarsh.ruff",

    // 2. 파일을 저장할 때마다 자동으로 포맷팅을 실행합니다.
    "editor.formatOnSave": true,

    // 3. 저장 시 추가적인 코드 액션을 실행합니다.
    "editor.codeActionsOnSave": {
      // 3a. 수정 가능한 모든 린트 오류를 자동으로 수정합니다.
      "source.fixAll.ruff": "always",
      // 3b. isort 규칙에 따라 임포트 구문을 자동으로 정렬합니다.
      "source.organizeImports.ruff": "always"
    }
  },

  // 4. ruff가 프로젝트의 가상 환경을 올바르게 인식하도록 인터프리터 경로를 지정합니다.
  //    이렇게 하면 ruff가 설치된 패키지를 정확히 인지하고 'import' 관련 오류를 줄일 수 있습니다.
  "ruff.interpreter": ["${workspaceFolder}/.venv/bin/python"],

  // 5. (선택 사항) ruff 실행 시 추가 인자를 전달할 수 있습니다.
  //    예: 특정 설정 파일을 강제하거나, preview 기능을 활성화할 때 유용합니다.
  "ruff.lint.args": ["--config=pyproject.toml", "--preview"],
  "ruff.format.args": ["--config=pyproject.toml", "--preview"]
}

3. 바쁜분들을 위한 올인원 세팅 커멘드

uv 이니셜라이징하고, ruff 랑 pre-commit 인스톨 후 lock 파일 싱크맞추기

uv init .
uv add --group dev ruff pre-commit
uv lock
uv sync --all-groups

# requirements.txt 만들기
uv export --format requirements-txt --all-groups > requirements.txt

ruff 린팅 포맷팅 세팅과 러닝

# .toml 에 최소한의 ruff 세팅
[tool.ruff]
line-length = 120

[tool.ruff.lint]
select = ["E", "F", "I"]
ignore = []

[tool.ruff.format]
# Black 호환 기본값 권장. 필요 시만 조정.

uv run ruff check  # 린팅

# 자동 수정, 포맷팅
uv run ruff check . --fix
uv run ruff check . --fix --unsafe-fixes   # 위험도가 높은 자동수정까지 허용

빠르게 pre-commit 에 등록해서 사용하기

# .pre-commit-config.yaml (예: ruff 전용 리포지토리 사용)
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
  rev: "v0.13.2"
  hooks:
    - id: ruff-check
      args: [--fix]
    - id: ruff-format

uv run pre-commit run --all-files

github ci/cd 퀵 구성 (workflow)

name: ci
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # uv 설치 + 캐시
      - uses: astral-sh/setup-uv@v6
        with:
          enable-cache: true  # 선택사항이지만 명시 권장

      # 프로젝트 환경을 락 기준으로 정확히 동기화 (dev 포함)
      - run: uv sync --locked --all-groups

      # 포맷 확인(자동 수정 금지). 방금 sync 했으므로 run은 no-sync로 빠르게
      - run: uv run --no-sync ruff format . --check

      # 린트(gh 어노테이션). 마찬가지로 no-sync
      - run: uv run --no-sync ruff check . --output-format=github

PS. github CI/CD 에서 testing 때문에 uv 를 사용하지, 진짜 ruff만 쓸꺼면 uv 필요 없다! PS. .vscode/settings.json 를 쓰는 것은 비추천한다. 무지성 날코드 후 오토세이브로 구원받는 습관을 들이게 된다. ~~내 얘기가 맞다.~~

출처

켄트 벡(Kent Beck) 형님과 함께하는 Augmented Coding, "증강 코딩" 잘해보기

Mon, 15 Sep 2025 17:53:54 GMT

Augmented Coding

바이브 코딩과 증강 코딩은 다르다. We used AI to code 2x faster. Then spent 3x more time fixing bugs. 여전히 뜨거운 감자인 바이브 코딩, 그리고 이제 사이 중간 어느메에서 "AI와 협업" 으로서 "잘" 사용하려는 움직임이 많이 있다. 지금의 나에게는 "Augmented Coding" 이 정답에 가깝게 느껴진다. ~~언젠간 오답이 될 수 있지만~~

1. Kent Beck's "Augmented Coding"

Farmers in olden times had a saying, “Don’t eat the seed corn.” Better to go hungry in the spring, plant the corn, & eat later. My coding genie, unfortunately, doesn’t know this saying.

농부가 다음 시즌 파종을 위해 남겨둬야 할 씨앗까지 먹어버리면 미래 수확을 포기하게 된다. Kent Beck 은 "Vibe Coding" 의 가장 큰 폐해는 *"지금 편하자고 코드 구조를 망가뜨리면 미래의 개발 옵션(Optionality)을 잃게 되는 것"* 이라고 지적한다.

Features 는 새로운 테스트를 작성하고 실행되게 하는 것과 같은 "기능 구현" 을 의미하고, 이 과정에서 결합도가 올라가고 디자인이 저하되기도 한다.

Options 는 구조를 개선하고 결합도를 줄이고, 응집도를 높여 "optionality" 를 높이는 것을 의미한다. Kent Beck 은 아래 그림과 같이, 들숨&날숨으로 기능 개발하고, 구조 개선하는 것을 비유한다. 그리고 아래 그림의 우측과 같이 AI는 한 호흡에 우다다 해버린다. (Genie Just Inhales)

1) Vibe Coding VS Augmented Coding

바이브 코딩 (Vibe Coding): 최종적으로 시스템이 어떻게 동작하는지에만 관심을 두는 방식. 코드의 품질이나 구조보다는 "일단 돌아가게만 해줘"라는 식의 접근법에 가깝다. 에러가 발생하면 다시 AI에게 에러 메시지를 주고 해결하고의 사이클 반복한다.
증강 코딩 (Augmented Coding): 작동하는 깔끔한 코드(Tidy Code That Works) 를 목표로 한다. 코드의 품질, 복잡도, 테스트 커버리지 등을 중요하게 생각하며, 개발자가 주도권을 가지고 AI를 활용하는 방식. 과거와 같이 좋은 코드를 추구하되, AI의 도움으로 타이핑의 양을 줄이고 생산성을 높이는 것.

켄트 벡은 바이브 코딩과 증강 코딩의 차이를 위와 같이 정의한다. 그리고 B+ 트리 프로젝트를 "Augmented Coding" 방식으로 한 것에 대해 설명한다. 그가 프로젝트를 리뷰한 내용에서 많은 인사이트를 얻을 수 있다.

2) AI가 길을 잃고 있다는 3가지 신호

켄트 벡은 AI와 협업할 때, AI가 잘못된 방향으로 가고 있음을 알려주는 3가지 신호를 경계해야 한다고 말한다.

Loops: AI가 비슷한 코드를 계속 생성하거나, 해결되지 않는 문제에 갇혀 무한 루프처럼 행동하는 경우.
Functionality I hadn't asked for (even if it was a reasonable next step): 요청하지 않은 기능을 구현할 때. 논리적인 다음 단계로 보여도, 명시적으로 요청하지 않은 기능을 AI가 스스로 구현하기 시작하면 주의해야 한다!
Any indication that the genie was cheating, for example by disabling or deleting tests: 테스트를 삭제하거나 비활성화하는 등, 문제 해결을 위해 "cheating" 할 때 주의해야 한다!

이러한 신호가 보일 때 개발자가 적극적으로 개입하여 방향을 바로잡아주는 것이 '증강 코딩'의 핵심이라고 볼 수 있다.

3) 증강 코딩의 핵심 원칙

(원문뿐 아니라, Kent Beck 의 다른글과 해외 관련 글을 참고했다.)

Constrain Context (맥락 한정하기): AI에게는 당장 다음 단계에 필요한 정보만 제공하기. 요구 사항이나 코드베이스의 일부 등 꼭 필요한 맥락만 주어 AI가 한 번에 너무 많은 것을 고려하지 않게 하기. 결국 context window 를 생각해서라도 이게 꽤 중요하다고 생각한다. 하지만 아이러니하게도 이 'context sizing'을 잘하려면, 기존 코드베이스가 이미 '낮은 결합도와 높은 응집도'를 가져야 한다고 생각한다.
Preserve Optionality (옵셔널리티 유지하기): "씨앗 옥수수" 비유처럼, AI의 나쁜 설계 제안을 그대로 받아들이지 않고 미래의 선택지를 남겨두기. 구조를 해치는 코드나 과도한 결합도 상승을 경계하여, 향후 변경과 확장이 쉽도록 설계상의 여지를 유지해야 한다. 이런 핀트가 보이면 개발자가 적극적으로 개입해야 한다!
Balance Expansion & Contraction (확장과 수축의 균형): 기능 추가(확장)와 리팩터링(수축)을 번갈아가며 조화시키기! 새로운 기능을 추가하여 복잡성이 늘어났다면, 곧바로 리팩터링을 통해 복잡성을 줄이는 주기를 유지하기.
Maintain Human Judgment (인간의 판단 유지): 최종 결정은 인간이 내리는 원칙. AI가 생성한 코드나 제안을 주기적으로 "검토(review)" 하고, 아키텍처나 설계상의 중요한 결정은 개발자가 가이드해야 한다는 것이다.

이를 바탕으로 켄트 벡은 "AI와 페어프로그래밍" 을 위해 "AI와 함께하는 개발 워크플로우" 를 소개했다. 그 팁들을 좀 더 살펴보자!

2. AI와 페어프로그래밍, "증강 코딩" 팁

1) TDD와 Tidy code를 위한 시스템 프롬프트

켄트 벡은 AI가 TDD 사이클(Red-Green-Refactor)을 잘 따르도록 유도하는 시스템 프롬프트를 공유했다. - https://github.com/KentBeck/BPlusTree3/blob/ca80e4d85a99cd0af2effe717f709d43e80403bc/rust/docs/CLAUDE.md / (프롬프트 덩어리들 양이 진짜 살벌하다 ㅋㅎㅋㅎ)

이를 한글로 번역하자면, 아래와 같다. 켄트 벡 답게 TDD 와 Tidy First 를 아주 강조한 시스템 프롬프트 다. 즉, 테스트 주도 개발(TDD) 사이클을 녹여내고, Tidy First 원칙 (구조 개선을 우선하는 원칙) 을 적용하여 기능 추가와 코드 정돈을 엄격히 분리하고 있다.

항상 plan.md의 지시사항을 따른다. 내가 "go"라고 하면, plan.md에서 표시되지 않은 다음 테스트를 찾고 그 테스트를 구현한 뒤, 그 테스트를 통과시키는 데 필요한 최소한의 코드만 구현한다.

# 역할과 전문성

당신은 켄트 벡(Kent Beck)의 테스트 주도 개발(TDD)과 Tidy First 원칙을 따르는 시니어 소프트웨어 엔지니어다. 당신의 목적은 이러한 방법론을 정확히 준수하도록 개발을 이끄는 것이다.

# 핵심 개발 원칙

- 항상 TDD 사이클(레드 → 그린 → 리팩터)을 따른다.
- 가장 단순한 실패하는 테스트부터 작성한다.
- 테스트를 통과시키는 데 필요한 최소한의 코드만 구현한다.
- 테스트가 모두 통과한 이후에만 리팩터링한다.
- 캔트 벡의 “Tidy First” 접근을 따라 구조적 변경과 행위 변경을 분리한다.
- 개발 전 과정에서 높은 코드 품질을 유지한다.

# TDD 방법론 가이드

- 기능을 작은 증가분으로 정의하는 실패하는 테스트부터 시작한다.
- 행위를 설명하는 의미 있는 테스트 이름을 사용한다(예: `shouldSumTwoPositiveNumbers`).
- 테스트 실패는 명확하고 정보가 풍부하도록 만든다.
- 테스트를 통과시키는 데 충분한 코드만 작성한다—그 이상은 하지 않는다.
- 모든 테스트가 통과하면, 리팩터링 필요성을 검토한다.
- 새로운 기능에 대해 이 사이클을 반복한다.
- 결함을 수정할 때는, 먼저 API 레벨의 실패하는 테스트를 작성하고, 문제를 재현하는 가능한 가장 작은 테스트를 추가한 다음, 두 테스트 모두 통과시키도록 구현한다.

# Tidy First 접근

- 모든 변경을 두 가지 유형으로 명확히 구분한다:
  1. **구조적 변경(Structural Changes)**: 행위를 바꾸지 않는 코드 재배치(이름 변경, 메서드 추출, 코드 이동 등)
  2. **행위 변경(Behavioral Changes)**: 실제 기능을 추가하거나 수정하는 변경
- 같은 커밋에 구조적 변경과 행위 변경을 절대 섞지 않는다.
- 둘 다 필요하다면 항상 구조적 변경을 먼저 수행한다.
- 구조적 변경 전후로 테스트를 실행해 행위가 바뀌지 않았음을 검증한다.

# 커밋 규율

- 다음 조건을 모두 만족할 때만 커밋한다:
  1. **모든** 테스트가 통과한다.
  2. **모든** 컴파일러/린터 경고가 해소되었다.
  3. 변경이 단일한 논리 단위를 이룬다.
  4. 커밋 메시지에 구조적 변경인지, 행위 변경인지 명확히 표기한다.
- 크고 드문 커밋보다 작고 빈번한 커밋을 선호한다.

# 코드 품질 기준

- 중복을 가차 없이 제거한다.
- 이름과 구조로 의도를 명확히 표현한다.
- 의존성을 명시적으로 만든다.
- 메서드는 작게 유지하고 단일 책임에 집중한다.
- 상태와 부작용을 최소화한다.
- “작동할 수 있는 가장 단순한 해법”을 사용한다.

# 리팩터링 가이드라인

- 리팩터링은 테스트가 통과(그린 단계)할 때만 수행한다.
- 표준 리팩터링 패턴을 올바른 명칭과 함께 사용한다.
- 한 번에 하나의 리팩터링만 적용한다.
- 각 리팩터링 단계 후에 테스트를 실행한다.
- 중복을 제거하거나 가독성을 높이는 리팩터링을 우선한다.

# 예시 워크플로우

새로운 기능을 구현할 때:

1. 기능의 작은 부분을 위한 단순한 실패하는 테스트를 작성한다.
2. 테스트를 통과시키는 데 필요한 최소한만 구현한다.
3. 테스트를 실행해 통과(그린)함을 확인한다.
4. 필요한 구조적 정리를 수행한다(Tidy First). 각 변경 후 테스트를 실행한다.
5. 구조적 변경을 별도의 커밋으로 기록한다.
6. 다음 작은 증가분을 위한 또 다른 테스트를 추가한다.
7. 기능이 완성될 때까지 이를 반복하되, 행위 변경과 구조적 변경의 커밋을 분리한다.

이 과정을 한 치의 오차도 없이 따르며, 빠른 구현보다 깔끔하고 잘 테스트된 코드를 항상 우선한다.

항상 한 번에 하나의 테스트를 작성하고, 그 테스트를 실행 가능하게 만든 다음, 구조를 개선한다. 매번 모든 테스트(장시간 테스트는 제외)를 실행한다.

2) 그래서 우리의 실전은?

~~여기서부터는 사견이 많이 담겨 있다.~~

바로 결론을 보자면, 나에게는 크게 2가지다. *(1) AI markdown 과 시스템 프롬프트, (2) 단계별 진행* 이 개괄적으로 증강 코딩을 위해 매우 중요한 것 같았다. 여기선 하나 하나를 다 뜯어보기보단 개괄적으로 내가 접근하는 방법을 적어보고자 한다.

(1) AI markdown

요즘엔 "AI markdown 문서" 라고 해서, AGENT.md, CLAUDE.md, GEMINI.md, MODEL_CARD.md ... 등 종류가 정말 많다. 그나마 널리 인식되는게 이 3가지 정도? (그 외 아주 춘추전국 시대다.)

AGENT.md 적극적으로 활용하자.
- https://news.hada.io/topic?id=22635
- https://agents.md/
- 저장소 루트에 두고 프로젝트의 전체적이고 개괄적인 내용이 들어가면 좋다. 위 링크들 참조
CLAUDE.md, GEMINI.md 등과 같은 LLM 전용 markdown 적극적으로 활용하기
- 이게 정말 정말 중요하다. 켄트 벡의 시스템 프롬프트를 그대로 활용해도 괜찮으니 꼭 전용 markdown 과 LLM CLI (gemini, claude ... cli) 를 사용해봤으면 한다.
- https://yozm.wishket.com/magazine/detail/3339/ 에서와 같이 "계층적 구조" 도 정말 효과적이다.
- Claude Code: Best practices for agentic coding 글에서 소개하는 가이드와 common-workflows 에서 다루는 workflow 를 꼭 참조했으면 한다.
- 여기서 "시스템 프롬프트 디테일의 차이" 가 나는데, Vibe Coding 이 되어버리거나 Augmented Coding 로 리드하느냐의 '한 끗' 차이가 여기서 나온다.
LLM CLI 를 안써도, Claude 에서 github repo 로 바로 연결하거나, gemini 에서 source code repo 를 바로 연결해서 사용하더라도, 이 AI markdown 지침서는 꼭 repo 에 포함시켜 보자. 이 경우에도 굉장히 많은 도움이 된다. (다만 context를 더 주의해야 한다.)
가능하다면, 영어로 작성하자. 토큰의 양으로 보나 LLM 의 이해도와 물리적 퍼포먼스(학습 원천 데이터에 따른 중간 단계들의 생략) 관점에서 영어는 언제나 AI에게 유리하다.

PS) README.md 파일을 AI를 위한 제물처럼 쓰는 경우가 있는데, README.md 는 인간을 위해 좀 남겨두었으면 한다..

(2) 단계별 진행

켄트 벡은 plan.md 라는 step by step 지침서를 매번 만들어서 code cycle 을 돌리는 것 같다. 이게 Vibe Coding 과 가장 물리적인 차이가 아닐까? 이 plan.md 가 곧 TODO Lists & Checklists 이기도 하고, 이 TODO를 모아서 backlog.md 로 만들어서 관리하기도 한다고 한다.

여기서 위에서 언급한 3) 증강 코딩의 핵심 원칙 이 중요하다고 생각한다. 켄트 벡이 언급한 바와 같이 plan.md 등을 활용해 Features -> Options 로 진행하고, 한 cycle 의 주도권을 잡고 있어야 한다고 생각한다.

좀 더 구체적으로는 plan.md 로 Red → Green → Refactor 사이클을 한 스텝씩 진행하고, 행위 변경과 구조 변경을 "따로 진행" 하며 커밋 단위에서 절대 섞지 않는 것이다.

그리고 이 "단계별 진행" 은 위에서 언급한 2) AI가 길을 잃고 있다는 3가지 신호 에서 "즉시 개입" 해서 제어해야 한다. (그래야 돈도 아낀다..)

근데 처음엔 Stop 을 한 뒤에 context 를 이어가는 게 굉장히 난해했다. 그때 계층적 구조, 계층적 AI markdown 들이 도움이 되었고, 그 계층적 구조는 다시 context window 의 sizing 에서도 유리했다.

3. 앞으로 코딩은?

켄트 벡은 AI와 함께하는 프로그래밍이 기존의 프로그래밍과 본질적으로 다르지 않고, 오히려 더 나은 프로그래밍 경험이 될 수 있다고도 언급한다. AI라는 새로운 '지니(genie)'와 함께 더 즐겁게 코딩할 수 있는 시대를 맞이하는게 좀 더 맞지 않을까.

Understanding Human-AI Augmentation in the Workplace: A Review and a Future Research Agenda 에서도 자동화(automatic)에서는 역할 대체가 중심이지만, 보조(augmentation)에서는 인간이 판단·결정·감독(directing, decision-making, oversight)하는 역할이 필수임을 강조한다.

How AI Has Transformed the Role of Software Developers 에서는 AI 도구들이 루틴한 코드 작성, 테스트 실행 등을 자동화하면서, 개발자들이 비즈니스 요구 사항, 아키텍처 결정, 보안 및 리뷰, 성능 최적화 등에 더 많이 관여하게 됨. 즉, 단순한 코드 작성자의 역할은 줄고, 코드 리뷰/감독/전략적 사고 역할이 늘고 있다고 언급한다.

결국 개발자의 역할이 AI를 감독하고, 더 나은 설계와 아키텍처에 집중할 수 있게 해주는 파트너로서 개발자의 본질적 가치를 더욱 부각시키는 역할을 하게 될 것이라고 기대된다. 그리고 아주 솔직하게 그 역할만큼은 안 빼앗기려고 하지 않을까?

출처

LLM - OpenAI 가 알려주는 할루시네이션의 이유?, Why Language Models Hallucinate 따끈한 논문 리뷰

Mon, 08 Sep 2025 16:55:58 GMT

[ 글의 목적: OpenAI 가 말아주는 할루시네이션 이야기, 내가 생각하는 핵심 위주로 요약 및 정리 ]

Why Language Models Hallucinate?!

[ 논문 페이지: arXiv / 원문: OpenAI 블로그 / PDF: OpenAI PDF ]

25년 9월 5일 공식 홈페이지에 올라온 따근따근한 글, "할루시네이션은 왜 생기는가!". 해당 논문은 할루시네이션의 "기술적, 통계적" 이유와 이를 야기하는 "훈련 및 평가 방식(기존 벤치마크)" 을 지적하는게 핵심 주제다.

해당 글의 썸네일인 "세종대왕 맥북 프로 던짐" 사건
구글 오버뷰의 "하루에 돌 1개 섭취" 사건
2023년 뉴욕에서, Schwartz 변호사가 변론서(legal brief)에 6건의 판례 인용을 했는데 모두 "가짜" 였던 사건 등

이 사건들, 특히 마지막은 LLM의 할루시네이션이 실무에 끼칠 수 있는 리스크를 명확히 보여준 대표적인 사례로 남아 있다.

OpenAI는 할루시네이션이 단순한 버그가 아니라, *훈련 및 평가 인센티브 구조 자체가 환각을 조장한다* 는 근본적 원인을 제시한다. 어떤 얘기인지 좀 더 깊게 살펴보자.

1. 할루시네이션이 왜 발생하는가?

Large Language Model 은 "확률적 언어 모델" 이다. 이 내용이 너무 질려버린 사람이 있을 수 있기에 LLM자체에 대한 설명은 Intro to Large Language Models 글 로 대체한다.

결국 주어진 context 에서 "가장 가능성 높은 다음 단어 예측" 하도록 훈련된다. 문법·철자와 같이 일관적 패턴 은 학습으로 정복할 수 있지만, 단발성 사실(singletons) 처럼 데이터에 거의 등장하지 않는 정보는 통계적으로 일반화가 불가능하다.

즉, 모델은 “이게 진짜 사실인가?”를 배우는 것이 아니라, “이 문장이 훈련 데이터에 나왔는가?”를 학습하기 때문에, 결국 사실에 근거하지 않은 추측 을 내놓게 된다. (아래, 논문 저자 Adam 의 생일을 물어보는 질문)

1) 문제는 학생이 아니라 시스템이다!!

(논문 초록, Abstract) 논문은 마치 "어려운 시험 문제에 직면한 학생"처럼, LLM이 불확실성을 인정하기보다는 추측하도록 보상받는 환경에 놓여있다고 비유한다. 해결책 역시 새로운 모델 아키텍처가 아닌, 기존 벤치마크의 점수 체계를 수정하는 '사회-기술적 완화' 방안을 제안한다.

PS) 일각에서는 OpenAI가 자기에게 유리한 평가로 프레임 전환을 하고 있다는 비판도 있다...!

Like students facing hard exam questions, large language models sometimes guess when uncertain, producing plausible yet incorrect statements instead of admitting uncertainty.

이진 0-1 채점 방식 하에서, 정답은 +1점, 오답은 0점, 그리고 "모르겠습니다(I don't know, IDK)"와 같은 불확실성의 표현 역시 0점을 받는다. 이 구조에서 불확실한 문제에 대해 추측하는 행위는 오답일 경우 0점으로 본전이지만, 정답일 경우 +1점을 얻을 수 있는 비대칭적 이득을 제공한다. 따라서 점수 극대화를 목표로 최적화된 모델에게 추측은 변칙적인 행동이 아니라 합리적이고 학습된 행동이 된다.

AI 모델이 누군가의 생일을 모를 때, "모르겠다"고 답하면 무조건 0점을 받지만, "9월 10일"이라고 추측하면 365분의 1 확률로 점수를 얻을 수 있다. 이러한 시스템은 모델이 정직한 소통가보다는 영리한 시험 응시자가 되도록 유도한다. 이 얘기는 뒤에 더 상세하게 다룬다.

2) 인간의 지각 경험에서 오는 환각과는 근본적인 차이가 있다.

(서론에서) 언어 모델의 환각은 정보 생성 과정에서 발생하는 통계적 오류와 평가 시스템에 의해 강화되는 학습된 행동에 가깝다고 한다. 그래서 인간이 경험하는 할루시네이션(환각)과 LLM에서의 할루시네이션은 근본적인 차이가 있음을 분명히 한다.

2. 환각은 이진 분류 오류와 밀접하게 연관되어 있다.

Hallucinations need not be mysterious — they originate simply as errors in binary classification. If incorrect statements cannot be distinguished from facts, then hallucinations in pretrained language models will arise through natural statistical pressures. We then argue that language models hallucinate because the training and evaluation procedures reward guessing over acknowledging uncertainty, and we analyze the statistical causes of hallucinations in the modern training pipeline.

논문은 할루시네이션 현상을 현대 LLM 파이프라인의 두 가지 주요 단계에 걸쳐 분석한다. 첫 번째는 오류가 처음 발생하는 '사전 훈련(Pre-training)' 단계 이고, 두 번째는 오류가 지속되는 '사후 훈련(Post-training)' 단계 이다.

논문은 복잡한 텍스트 생성 문제를 Is-It-Valid (IIV) 라고 불리는 더 간단한 지도 학습 기반 이진 분류 문제로 환원한다. 이는 "이것이 유효한 언어 모델 출력인가?"라는 질문에 답하는 분류기를 가정한다. (즉, 주어진 텍스트 출력(response)이 유효한지(+) 또는 오류인지(-)를 분류)

생성 모델이 유효한 출력을 생성하는 것은 이러한 예/아니오 질문에 답하는 것보다 어떤 면에서 더 어렵다. 왜냐하면 유효한 출력을 생성하려면 암묵적으로 각 후보 응답에 대해 "이것이 유효한가"라는 질문에 답해야 하기 때문이다.

이러한 환원을 통해 논문은 생성 오류율과 IIV 오분류율 사이에 다음과 같은 핵심적인 수학적 관계를 정립한다.
$(generative error rate)≳2⋅(IIV misclassification rate)$
생성 오류율이 IIV 오분류율의 두 배 이상이 될 수 있다는 수학적 관계를 제시한다.

1) 사전 훈련(Pre-training) 단계에서의 오류

Arbitrary-fact hallucinations

데이터에 간결하게 설명할 수 있는 패턴이 없을 때 발생하는 인식론적 불확실성(epistemic uncertainty) 으로 인해 발생
싱글톤 비율(Singleton Rate): 훈련 데이터에 단 한 번 등장하는 사실의 비율이 환각 빈도를 결정.
사전 훈련 데이터에 한 번만 나타나는 특정 사실의 비율(singleton rate)이 환각률의 하한이 된다는 것을 보여준다. (ex - 위 언급된 Adam 의 생일!)

Poor Model Families

모델의 아키텍처나 표현 능력이 특정 개념을 잘 나타내지 못할 때 발생한다. 예를 들어, 옛날의 트라이그램 언어 모델은(n-gram 모델) 제한된 문맥으로 인해 문법적으로 틀린 문장을 자주 생성했고 DeepSeek-V3 모델이 글자 세기 작업에서 오류를 내는 것도 모델의 한계 때문으로 분석된다.

그 외

Calibration (오류가 없는 언어모델은 "보정 상태"가 될 수 없다(δ가 0이 될 수 없음), 세부 내용은 논문 참조!)

계산적 난이도(Computational Hardness) - 암호 해독과 같은 문제
분포 변화(Distribution Shift) - 훈련 데이터 분포와 크게 다른 OOD(Out-of-Distribution) 프롬프트
GIGO(Garbage In, Garbage Out), 대규모 훈련 코퍼스에 포함된 수많은 사실적 오류가 기본 모델에 의해 복제될 수 있음이 언급된다.

2) 사후 훈련(Post-training) 단계에서의 오류

사후 훈련은 인간 피드백 기반 강화 학습(RLHF), 직접 선호 최적화(DPO), AI 피드백 기반 강화 학습(RLAIF)과 같은 기법을 통해 사전 훈련된 기본 모델의 오류를 줄이고 인간의 선호도에 맞게 조정하는 것을 목표로 한다. 하지만 논문은 이러한 방법들이 할루시네이션을 제거하는 데 실패한다고 주장한다. 그 이유는 이 기법들이 최적화하려는 목표, 즉 주류 평가 벤치마크 자체가 근본적으로 잘못 정렬되어 있기 때문이라 한다.

논문은 GPQA, MMLU-Pro, SWE-bench 등 10개의 널리 사용되는 벤치마크에 대한 메타 분석을 수행했으며, 그 결과 거의 모든 벤치마크가 이진 채점 방식을 사용한다는 것을 언급한다.

정답 = 1점, 오답 = 0점, “모르겠다” = 0점

WildBench 만이 불확실성 표시에 대해 최소한의 점수를 부여하지만, 그마저도 IDK 응답이 사실 오류나 환각이 있는 "공정한(fair) 할루시네이션" 응답보다 낮은 점수를 받을 수 있어 여전히 추측을 장려할 수 있다고 지적한다.

따라서 모델은 기대값 관점에서 “찍는 것이 항상 유리” 하다. “모르겠습니다”보다는 그럴듯하게라도 답하는 쪽이 보상 구조상 이득이 된다. 논문에서는 이를 어려운 시험 문제에 직면했을 때 불확실하면 추측하는 학생들의 행동에 비유한다.

이로 인해 언어 모델은 항상 "시험을 치르는 모드(test-taking mode)"에 있게 되며, 자신의 지식 부족을 인정하기보다는 과신에 찬 답변을 생성하도록 유도된다고 한다.

3. 그래서 어떻게 할루시네이션을 줄일 수 있는가?

1) 환각 문제 해결을 위한 사회-기술적 완화 (Socio-technical Mitigation)

기존 리더보드와 벤치마크의 채점 체계를 바꿔야 한다고 주장한다. “불확실성 표명” 자체에 보상을 주어, 모델이 정직하게 모른다고 답할 수 있는 환경을 조성해야 한다!

기존 주류 평가 벤치마크에 매몰되어 환각이 심화되거나 조장할 수 있으니, 불확실성 캘리브레이션을 반영한 새로운 지표를 만들자!

2) Explicit Confidence Targets

모델이 확률적 진실성 대신 선택적 진실성 을 따르도록 유도해야 한다. - behavioral calibration

"t보다 높은 확신이 있는 경우에만 답변하고, 오류는 t/(1-t)점 감점, 정답은 1점, '모르겠습니다'는 0점"과 같이 명확한 지침을 제공하는 것
예: 확신도 70% 이상일 때만 답변, 그 이하는 “모르겠다(IDK)” 처리.

3) Search (and reasoning) are not panaceas

~~이는 사실 논문에서 줄이기 위한것이 아니라 "한계점에 대한 언급"~~

검색 증강 생성(RAG)과 같은 기술이 할루시네이션을 줄이는 데 효과적임이 입증되었지만 이러한 기술이 만병통치약이 아님을 강조한다. 이진 채점 시스템은 검색이 확실한 답변을 제공하지 못할 때에도 여전히 추측에 보상하기 때문. 또한, 검색은 글자 세기 예시와 같은 계산 오류나 다른 내재적 환각에는 도움이 되지 않을 수 있다.

논점에서 살짝 벗어나지만 RAG 를 위해 Vector DBMS를 선택하는 것도 필수가 아니라는 점이다. 사견으로, 이론상 RAG 가 할루시네이션을 더 줄이려면 Vector 보다는 *"유사한게 아니라 명확하고 확실하게 검색되는 것"* 이 더 도움을 줄 수 있다.

결국 RAG를 위한 output 도 prompt 의 일부분이고, 결국 RAG 도 context window 에 제한적이다. 가끔 현업에서 모든 정보를 vector 에 담아서 "어떻게든 증강하겠지~~" 라는 기도메타를 보는데.. ~~~사실 어느정도 내 얘기기도 하다..~~ 오히려 100% 확실한 정보만, 짧고 굵게 매핑할 수 있는 라벨링이 훨씬 유의미하지 않을까 생각한다.

그 외는 사실 결론과 이어지는 것이다.

4. 결론: '더 똑똑한' AI가 아닌 '더 정직한' AI !!

할루시네이션은 지도 학습(supervised learning)에서의 오분류(misclassifications)와 유사하게 생성 오류(generative errors)로 발생하며, 이는 교차 엔트로피 손실(cross-entropy loss) 최소화의 자연스러운 결과로 나타난다.

논문은 생성 문제를 “이 출력이 유효한가?”라는 IIV(Is-It-Valid) 이진 분류로 환원하고, 두 오류 사이의 하한 관계를 명시한다. 생성 오류율 ≥ 2 × IIV 오분류율.

이 관계는 사전훈련만 놓고 보더라도 모델이 피할 수 없는 통계적 제약(예: 싱글턴 비율처럼 데이터에 한 번만 등장하는 사실의 비중)이 환각으로 이어짐을 보여준다.

그러나 환각은 사후훈련 단계에서 “없어지지 않는다.” 오늘의 주류 벤치마크는 정답=1, 오답=0, IDK=0인 0-1 채점 을 널리 쓰며, 이 구조는 모를 때 ‘찍는’ 편이 기대값 상 유리 하도록 모델을 길들인다.

그 결과 모델은 항상 시험 응시 모드(test-taking mode) 로 작동하며, 불확실성 표명보다 자신감 있는 오답!! 을 택하게 된다. 이는 환각을 “미스터리한 버그”가 아닌, 평가 인센티브가 낳은 학습된 행동 으로 설명해 준다.

핵심 처방은 모델 구조가 아니라 평가 시스템을 '간단히 수정(simple modification)' 하는 것이라고 언급한다.
기존 리더보드의 주 지표를 정확도 일변도에서 “불확실성 인식/자제”를 보상하는 형태로 수정하면 (예: 확신이 낮을 땐 답변을 유보하게 만드는 명시적 confidence 타깃, 행동적 캘리브레이션) “찍기”의 기대이익을 제거하고 정직한 불확실성 표현 을 유도할 수 있다.
오답(특히 자신감 높은 오답)에는 유의미한 페널티, 적절한 IDK/유보에는 부분 크레딧을 부여하는 채점으로 주요 벤치마크 전체를 업데이트해야 한다.

PS) 엄청나게 큰 대형 모델이 있으면 덜할까? 논문에서는 사실 거의 아니다라고 보는 것 같다. 오히려 "작은 모델이 한계를 아는 태도, 대답을 유보하는 모습" 을 쉽게 보일 수 있다고 언급한다.

[책 리뷰] Continuous Deployment - 발렌티나 세르빌

Sun, 31 Aug 2025 12:03:47 GMT

[ "한빛미디어 서평단 <나는리뷰어다> 활동을 위해서 책을 협찬 받아 작성된 서평입니다." ]

Continuous Deployment, 지속적 배포 (oreilly)

발렌티나 세르빌(Valentina Servile): 방콕에 본사를 둔 소트웍스의 수석 소프트웨어 개발자로, 분산 시스템의 지속적 배포 분야에서 수많은 고객과 협업하며 컨설팅을 해왔다. 여러 다기능 팀에서 근무하며 대규모 분산 시스템과 마이크로서비스, 지속적 배포 프랙티스, 진화하는 아키텍처 등 다양한 기술 스택을 쌓아왔다. 평소 코드 작성은 물론, 다른 동료를 멘토링하는 일을 즐긴다. 소트웍스의 고객사에서 소프트웨어 배포 프랙티스를 개선하고 안정적인 릴리스를 더 자주 수행함으로써 비즈니스 환경 변화에 신속하게 대응할 수 있도록 지원하는 일에 보람을 느낀다.

thoughtworks 링크에서 저자에 대한 내용과 책 자체에 대한 소개를 좀 더 많이 볼 수 있다. -> 초반 챕터들의 맛보기와 팟캐스트를 이용할 수 있다!
🔥 한빛 책 링크

리뷰

이제 github action 의 test code runing 하는 yaml 파일은 꼭 먼저 만들고 시작하게 된다. (물론 린팅 -> 테스팅 단계로) 하지만 이는 어디까지나 “최소한의 규칙 점검” 에 가깝다.

이 책이 묻는 본질은 한층 직설적이다. 우리는 왜 CI/CD를 구성하는가? 『지속적 배포』는 도구 사용법보다 팀이 공동으로 가져야 할 관점과 습관에 집중한다. O’Reilly 특유의 교과서적 정밀함과, 현장에 닿아 있는 실무성의 균형이 돋보인다.

책은 아래와 같은 5개의 파트로 이뤄져 있다. 개념을 모두 뿌려두고, S/W 생명 주기에 맞춰 이를 어떻게 적용하는지의 흐름이다.

Part 1: CD 개념·배경 정리(Dev/Ops·XP·CI/CD의 계보 포함)
Part 2: 개발 이전 — 작업 슬라이싱·가치 중심 설계·팀 규칙
Part 3: 개발 단계 — 트렁크 기반 개발, 기능 토글, 파이프라인
Part 4: 개발 이후 — 프로덕션 중심 검증·릴리스 전략(카나리 등)
Part 5: 사례 연구 — N26·TravelPerk·AutoScout24 등 도입기

책의 성격은 *“사용법”이라기보다는 "팀 차원의 ‘계몽’과 행동 변화를 유도"* 하는 책에 가깝다.

주관적인 하이라이트

트렁크 기반 개발(TBD) - Trunk-Based Development

책의 기본 원리는 명확하다. “더 작게, 더 자주, 더 안전하게.” 배포는 릴리스와 다르며, 코드는 항상 운영 환경에 들어갈 수 있어야 한다. 사용자는 기능 토글(Feature Toggles) 과 카나리(Canary) 등으로 노출을 통제한다.

핵심은 실패를 전제로 설계하는 것이다. “잘못된 커밋의 비율”보다 실패 감지 속도와 우아한 복구(낮은 MTTR) 가 더 중요하다. 긴 브랜치와 늦은 병합이 만들어내는 충돌 비용을 짧은 수명 브랜치 + 잦은 통합으로 끊고, 파이프라인 신뢰도를 높이며 커밋 단위의 책임을 선명하게 만든다.

브랜치 수명 제한(예: 1~2일), “Definition of Merge” 합의(필수 체크·리뷰 SLA)
메인 브랜치의 항상 배포 가능 상태 보장(빨간 파이프라인 금지 원칙)
롤백 대신 롤포워드를 표준화(토글/리버전 플랜 사전 준비)

기능 토글(Feature Toggles)

기능 토글은 미완성 기능도 배포 가능하게 만든다. 최상위/중첩 토글과 확장·축소 패턴으로 노출을 세밀하게 제어하며 배포와 릴리스의 결합을 해체한다. 운영 관점에서 중요한 것은 토글의 수명 관리다. 토글은 채무가 되기 쉽다.

토글 분류: 릴리스 토글(기능 노출), 운영 토글(긴급 차단), 실험 토글(A/B), 권한 토글(세그먼트)
거버넌스: 토글 생성 시 만료 기준·제거 시점 명시, 대시보드화, “좀비 토글” 주기적 청소
프로그레시브 딜리버리: 카나리 → 점진적 확대 → 자동 롤백 조건(에러율/지연/전환율)

작업 슬라이싱 전략

수평 분할(레이어 중심)보다 수직 분할(사용자 가치 단위)을 우선한다. INVEST 원칙(Independent·Negotiable·Valuable·Estimable·Small·Testable) 을 티켓 템플릿에 내장하고, 각 항목을 즉시 쪼갤 수 있는 기준으로 삼는다.

“완성 기능”이 아니라 가치 흐름의 얇은 조각을 목표로 설계
각 슬라이스에 명확한 수용 기준(AC) 과 관측 지표(로그·메트릭·이벤트) 부여
인터페이스 변경이 필요한 경우, 백워드 호환과 계약 테스트로 무중단 전환

프로덕션 중심 품질 보증

“승인 절차가 안전을 보장한다”는 착시에서 벗어나야 한다. 운영 환경에서만 검증 가능한 사실(데이터 볼륨/형상, 실제 트래픽 패턴, 네트워크·인프라 구성)을 근거로 프로덕션 테스트를 표준화한다.

관측 가능성(Observability): 트레이스·로그·메트릭 일체화, 기능별 SLI/SLO
셰도우 트래픽·리플레이, 실사용 세그먼트 기반 실험, 오토 롤백 규칙 사전 정의
품질의 단위를 “테스트 통과 여부”에서 “운영 지표의 안정성” 으로 전환

전체 스택 예제와 현실 이슈

React·Spring Boot·SQL로 이어지는 예제는 세션/상태, 클라이언트 캐시 무효화, DB 마이그레이션 같은 현업 난제를 직접 다룬다. 필요하면 파이프라인 일시 중지 → 로컬 검증 같은 우회 전략도 제시한다.

DB는 Expand → Migrate → Contract(전개·이행·축소) 3단계로 안전하게 바꾸고, 배치·백필 작업은 멱등성과 재시도 정책으로 보호한다. 배포 전략은 서비스 성격에 따라 롤링/블루-그린/카나리를 선택한다.

사례 연구에서

핀테크·이동 서비스·이커머스 등 서로 다른 도메인(N26, TravelPerk, AutoScout24 등)의 사례를 통해 CD → 조직 문화 혁신 → 배포 빈도 증가 → 비즈니스 민첩성으로 이어지는 경로가 드러난다. 이 파트는 기술 채택기를 넘어서 조직 변화기에 가깝다.

“우리의 제약(규제/리스크/조직도)을 토글·카나리·슬라이싱으로 어떻게 흡수할 것인가?” 에 대한 고찰을 준다.
또한 규모가 조금 있는 조직에서 “변경 리드타임·배포 빈도·MTTR을 어떤 OKR로 연결할 것인가?” 에 대한 고민포인트가 될 것 같다.

결론

Part 1의 “왜 CD인가” 논증은 독자에 따라 다소 길게 느껴질 수 있다. 또한 관료성이 항상 악은 아니다. 어떤 조직은 git-flow·배치 릴리스를 유지해도 만족할 수 있다. 반대로 문화 성숙 없이 TBD만 밀어붙이면 “배포 담당자”로 책임이 쏠리는 역효과 가 생길 수 있다고 생각한다.

그럼에도 트렁크 기반 개발·기능 토글·프로덕션 검증을 하나의 체계로 묶어, ‘배포 공포증’을 조직의 학습 사이클로 전환한다는 점과 즉시 적용 가능한 패턴과 현실적 우회 전략을 모두 담았기에, 당장 배포 흐름을 개선하려는 팀, 장기적으로 전달 문화를 재정립하려는 조직, 그리고 개인(팀) 모두에게 추천할 만하다.

개인적으로 [PART 3 개발 단계] 가 특히 인상적이었다. JVM(Spring) 환경에서 기능 토글을 코드 레벨로 구현하는 실습이 포함되어 있어, 추상적인 개념이 채워지는 느낌이 있다. ~~사실 이런 느낌의 코드를 처음봐서 그런것 같다.~~

CHAPTER 01 지속적 배포 _1.1 수개월, 수년마다 한 번 배포 _1.2 며칠마다 한 번 배포
_1.3 지속적 배포 _1.4 익스트림 프로그래밍 _1.5 데브옵스 _1.6 지속적 통합 _1.7 지속적 전달 _1.8 최종 프로덕션 게이트 _1.9 시사점 _1.10 지속적 배포는 위험한가? _1.11 정리하기

CHAPTER 02 이점 _2.1 원피스 플로와 린 생산 _2.2 DORA 메트릭 _2.3 품질 시프트 레프트 _2.4 정리하기

CHAPTER 03 사고방식의 전환 _3.1 변경사항을 정의하는 것과 적용하는 것 _3.2 진행 중인 작업 숨기기 _3.3 분산 시스템 _3.4 프로덕션 경로 간의 계약 _3.5 배포는 릴리스가 아니다 _3.6 엔드투엔드 전달 라이프 사이클 _3.7 정리하기

CHAPTER 04 최소 요건 _4.1 자율적 다기능 팀 _4.2 이해관계자의 신뢰 _4.3 정리하기

CHAPTER 05 도전 과제 _5.1 배포에 민감한 시스템 _5.2 유저 설치 소프트웨어 _5.3 규제 대상 산업 _5.4 인지 부하 _5.5 정리하기

[PART 02 개발 이전]

CHAPTER 06 예정된 작업 나누기 _6.1 수평 분할 vs 수직 분할 _6.2 지속적 배포를 하면
_6.3 효과적인 수직 분할 _6.4 예제: 그로서루 _6.5 정리하기

CHAPTER 07 프로덕션 빌드 _7.1 배포성 요건 _7.2 테스트성 요건
_7.3 관찰 가능성 요건 _7.4 보안 요건 _7.5 성능 요건 _7.6 (좀 더) 완전한 유저 스토리 템플릿 _7.7 예제: 그로서루 유저 스토리에 CFR 추가 _7.8 정리하기

[PART 03 개발 단계]

CHAPTER 08 플랫폼 아키텍처 재구축 _8.1 유저 스토리 _8.2 그로서루 애플리케이션 _8.3 정리하기

CHAPTER 09 라이브 기능 리팩터링 _9.1 해야 할 일 _9.2 상품 식별 체계 _9.3 현재 상태 _9.4 목표 상태 _9.5 어떻게 목표를 달성할까? _9.6 확장/축소 구현 _9.7 정리하기

CHAPTER 10 데이터와 데이터 손실 _10.1 해야 할 일 _10.2 현재 상태 _10.3 목표 상태 _10.4 어떻게 목표를 달성할까? _10.5 이중 쓰기 구현 전략 _10.6 이중 읽기 구현 전략 _10.7 NoSQL
_10.8 정리하기

[PART 04 개발 이후]

CHAPTER 11 프로덕션에서 테스트 _11.1 왜 프로덕션에서 테스트를 해야 하나? _11.2 어떻게 프로덕션에서 테스트를 할까?
_11.3 스테이징 이후의 스토리 _11.4 정리하기

CHAPTER 12 릴리스 _12.1 안티패턴: 빅뱅 릴리스 _12.2 안티패턴: 부분 배포로 일부만 릴리스 _12.3 릴리스에 기능 토글 응용 _12.4 카나리 릴리스 _12.5 A/B 테스트 _12.6 정리하기

[PART 05 사례 연구]

CASE STUDY A 오토스카우트24 _A.1 오토스카우트24의 당시 상황 _A.2 오토스카우트24의 지속적 배포 도입 _A.3 오토스카우트24의 지속적 배포 구현

CASE STUDY B 오토 _B.1 오토의 당시 상황 _B.2 오토의 지속적 배포 도입 _B.3 오토의 지속적 배포 구현 _B.4 참고 자료

CASE STUDY C N26 _C.1 N26의 당시 상황 _C.2 N26의 지속적 배포 도입 _C.3 N26의 지속적 배포 구현 _C.4 참고 자료

CASE STUDY D 클라이밋파트너 _D.1 클라이밋파트너의 당시 상황 _D.2 클라이밋파트너의 지속적 배포 도입 _D.3 클라이밋파트너의 지속적 배포 구현

CASE STUDY E 모타빌리티 오퍼레이션즈 _E.1 모타빌리티 오퍼레이션즈의 당시 상황
_E.2 모타빌리티 오퍼레이션즈의 지속적 배포 도입 _E.3 모타빌리티 오퍼레이션즈의 지속적 배포 구현

CASE STUDY F 레아 그룹 _F.1 레아 그룹의 당시 상황 _F.2 레아 그룹의 지속적 배포 도입
_F.3 레아 그룹의 지속적 배포 구현

CASE STUDY G 메이즈 _G.1 메이즈의 당시 상황
_G.2 메이즈의 지속적 배포 도입 _G.3 메이즈의 지속적 배포 구현

CASE STUDY H 메이즈 _H.1 트래블퍼크의 당시 상황 _H.2 트래블퍼크의 지속적 배포 도입 _H.3 트래블퍼크의 지속적 배포 구현

velog dashboard v2 - 트랜드 글 메일로 받아보세요~~

Wed, 20 Aug 2025 16:33:27 GMT

Velog Dashboard v2

Velog Dashboard, 신규 feature update 공유! 빨리 접속하기: https://velog-dashboard.kro.kr/ Github repo: https://github.com/check-Data-Out/velog-dashboard-v2

Velog 통계를 한눈에 확인할 수 있는 서비스를 100% 무료로 제공하고 있습니다! Velog 생태계가 살아 있는 한 저희도 함께 성장하며, 오히려 선순환 구조에 기여할 수 있기를 바라고 있습니다. (요즘 광고글 트랜딩에 너무 많아요~~~ AI 필터링 도입해주세요~~ 쩨발,, 과해 ㅠㅠ)

저희 팀은 주 1회 이상 정기 회의를 진행하며, 그 과정에서 작지만 잦은 업데이트들이 꾸준히 이루어지고 있습니다!! 현재 코드 커버리지는 90% 이상을 달성했고, 프론트엔드에서는 E2E 테스트까지 도입했습니다!
또한 지금까지 총 9대의 서버를 무료로 확보하여 운영해 왔는데, 이를 안정적으로 유지하기 위해 많은 노력을 기울였습니다. 무료 서버를 여기저기 모아 쓰는 게 결코 쉽지 않다는 걸 몸소 체감하고 있습니다. 아래 소개할 인프라 개괄도를 보시면 그 과정이 더 재미있게 다가올지도 모르겠습니다.
이번 글은 서비스의 생존 소식을 전하고, 동시에 그간의 업데이트 현황을 공유드려보고자 합니다~~ 🎉🫡

*업데이트 요약본*

① LLM 기반 주간 메일링 분석(트렌드·작성 글 분석) - 매주 월요일 오전에 발송! ② 리더보드 고도화(기간별 조회/좋아요 증감, 사용자·게시글 단일 클릭 이동) ③ Velog API 의존 최소화(내부 탐색·네비게이션 시 자체 저장 정보 활용) ④ 30분 캐시 레이어 도입으로 응답 체감 속도 개선 ⑤ 샤딩·풀링 아키텍처 재정비 ⑥ DevOps 도입

1. 메일링 서비스

Velog 의 주간 트랜드! + 글을 안쓰면 재촉까지!! 그리고 여러분들의 누적 조회 변동량 + 작성한 글에 대한 분석!!

글을 쓰면 어떤지 분석을 해드려요, LLM 을 활용한 서비스랍니다 :) 어떤 분석인지 궁금하면 빨리 등록해서 메일을 받아보셔요! >> 빨리 접속하기

세부 구현

이번에 구현한 “벨로그 글 트렌드 분석” 배치 작업은 추상 클래스 기반 템플릿 메서드 패턴으로 설계했습니다. 내부적으로는 3가지 배치 작업으로 나누어져 있으며, 이를 뒷받침하는 3개의 독립 외부 모듈이 존재합니다.

@dataclass
class AnalysisContext:
    """분석 컨텍스트 정보"""

    week_start: datetime
    week_end: datetime
    velog_client: VelogClient


# ==================================== #
# LLM 호출 부분 ...
# ==================================== #

    async def _analyze_data(
        self, raw_data: list[TrendingPostData], context: AnalysisContext
    ) -> list[WeeklyTrendInsight]:
        """LLM을 사용한 트렌드 분석"""
        try:
            # LLM 입력 데이터 준비
            llm_input = [post_data.to_llm_format() for post_data in raw_data]

            # LLM 분석 실행
            llm_result = analyze_trending_posts(
                llm_input, settings.OPENAI_API_KEY
            )
            ...

# ==================================== #
# AWS SES 호출 부분 ...
# ==================================== #

class WeeklyNewsletterBatch:
    def __init__(
        self,
        ses_client: SESClient,
        ...


        # 최대 max_retry_count 만큼 메일 발송
        while failed_count < self.max_retry_count and not success:
            try:
                self.ses_client.send_email(newsletter.email_message)
                ...

이번 배치는 단순히 “그냥 만들자!” 보다는 “잘 만들어 두자!”에 가까웠습니다.
특히 처음으로 유저에게 직접 발송되는 메일링을 다루다 보니, 유지보수에 열려 있고 변경하기 쉬운 구조가 무엇보다 중요했습니다.
외부 모듈은 총 3개로, llm, velog, SES email입니다. (각자 조금씩 다른 디자인 형태로 설계 되었습니다! 실제 코드 보러가기)
이 모듈들은 퍼사드(Facade) 패턴과 Lazy Init 싱글톤 패턴으로 구현하여, 내부 비즈니스 로직과 철저히 분리해 두었고, 개별 유닛테스트로 동작을 보장하게 되어있습니다.
즉, 내부에서는 해당 모듈의 클라이언트에 접근해 필요한 핵심 비즈니스 로직을 호출하는 것 외에는 어떤 의존성도 가지지 않도록 설계했습니다. 그리고 호출시 주입하도록 했구요! ~~물론 구현 과정에서 배보다 배꼽이 더 커졌던 것 같긴 하지만요…~~

주간 트렌드 분석
주간 사용자 트렌드 분석
트렌드 메일 발송

배치를 3가지 유형으로 분리한 것도 같은 맥락입니다. 각각의 역할을 명확히 나누어 유연성과 확장성을 확보할 수 있도록 했습니다. 약간의 아쉬움은 존재하지만 과한 집착은 오히려 안티패턴을 만들어~~

2. 리더보드

Velog Dashboard 사용자들은 이제 기간별 조회수 증가량과 좋아요 증가량 리더보드를 더 쉽고 빠르게 확인할 수 있습니다!

또한 새로운 기능이 추가되었습니다!

사용자 클릭 시 → 해당 사용자 Velog 페이지로 이동
게시글 기준 정렬 시 → 해당 게시글로 바로 이동

이를 구현하기 위해 기존에는 저장하지 않던 velog profile 관련 정보(username 등)를 불가피하게 저장하게 되었습니다.
그래도 긍정적인 것은 그 결과, 서비스 자체에서는 더 이상 Velog API를 직접 호출하지 않아도 됩니다!! (물론 통계 집계에는 여전히 Velog API를 사용합니다.) -> 간헐적으로 velog api 가 뻗을때 저희도 Timeout 이 되는 이슈가 있었는데 사실 이제 없다는 의미 ㅎㅎ (첫 로그인 외...)

추가로 Cache Layer를 도입했습니다!

깃허브 docker compose 보러가기

stand-alone 형태로 독립시켜서 가동했고, 여러가지 업데이트가 있을 것 같아 레포를 파서 버저닝을 하게 되었습니다.
그래서 리더보드는 30분 단위 캐싱으로 훨씬 쾌적해졌습니다!! 앞으로 이 캐싱의 적용 범위는 계속 늘어날 것 같습니다!
현재는 쿼리 최적화도 병행하고 있지만, DBMS 구조적 한계가 있어 우선 캐싱부터 적용했습니다.

3. DBMS 샤딩과 캐시 layer 추가

1) 처음엔 버티컬 샤딩을 하려고 했었다...

초기에는 Supabase 기반으로 운영했습니다! 다만 다음 이슈들이 겹치며 이소 준비를...

Postgres 17 전환과 TimescaleDB 지원 변경

Supabase가 Postgres 17 번들을 예고하면서 timescaledb가 번들에서 제외(Deprecated)되어, 업그레이드 전에 드롭이 필요해졌습니다. -> 시계열 워크로드를 계속 운영하기엔 마이그레이션·대안 검토 비용이 커졌습니다.
데이터 egress 비용 압박!!, batch 에서 bulk 로 데이터를 많이 밀어넣다보니 egress 가 유독 한계치를 계속 찍었습니다.. 이 탓에 일단 구독을 해버렸었죠.. (월 2.5만) 근데 supabase 를 no-code tool로 사용할 거라면 돈내고도라도 쓰는데, 우리는 이미 가용할 수 있는 무료 서버도 많았죠...

2) PgBouncer로 풀링 + 간이 분산을 시도

설계 초안

토폴로지: 1대 Primary, 2대 Replica(Read-only), 앞단에 PgBouncer
의도: 커넥션 폭주 완화(풀링) + 간이 라운드로빈

근데 PgBouncer 는 경량 커넥션 풀러입니다. 자체적으로 다중 호스트 라우팅/샤딩을 하지 않았죠...

다만 DNS 라운드로빈(또는 host 리스트 뒤 LB) 을 물려두면, PgBouncer의 server_round_robin 옵션으로 서버 커넥션 재사용 방식을 라운드로빈에 가깝게 바꿀 수 있었습니다.
뭐,, 결론적으로 PgBouncer는 샤딩 도구가 아니라 풀러이므로, “읽기/쓰기 분리”나 “키 기반 샤딩 라우팅”은 별도 계층이 필요했죠,, 탈락!

3) 진짜로 원했던 건 ‘유저 그룹’ 기반 수평 샤딩

도메인 특성상 핵심 테이블이 유저 중심이고, 모든 유저가 group 키를 갖도록 최초부터 설계했습니다. 따라서 횡적 분할(샤딩) 을 통해!

단일 노드 I/O 병목을 회피
그룹 단위의 데이터 지역성(locality) 확보
장애/스케일 전략의 독립성 제고

라는 뻔한(X, 큰꿈) 목표를 노렸고 pgcat 으로 시도 했었죠.. ~~하지만.. SQL 기반으로 분산 처리 가능하다는데 제대로 작동을 안함~~

그니까 사실 pgcat 은 sqlparser 기반의 쿼리 파서를 실행해서 SELECT → Replica / 그 외(트랜잭션·DML 포함) → Primary 로 자동 라우팅하는 기능은 명백하게 가지고 있었습니다.. (pgcat github)

*근데 더 depth 있게 SQL 의 특정 key 값만 판단해서 라우팅을 하려면 모듈을 오버라이딩 해야 했죠..*

사실 더 정확하겐 SET SHARDING KEY 를 통해 샤드 라우팅을 할 수 있는데, 이는 결국 백오피스든, API에서든, 이를 위한 서드파티 구성이 필요하다는 의미..
일단 본능적으로 한 보 후퇴,, 그래서 일단 P.D.D (Primary + 2 Dup) 세팅으로 하되, 다음을 노리는 것으로 방향을 잡았습니다. (근데 사실 아직까지 못끝낸거 실화?...)

4) redis 기반 cache layer, 이를 위한 모듈

캐시에서 조금 그럴듯 한 얘기를 붙이자면 Interface Segregation Principle 지향했고CacheConfig, Redis 구현체를 위한 ICache "Strategy Pattern" 과 RedisCache 를 하나의 "Adapter" 로 사용하고자 했습니다.

// cache.config.ts
const cacheInstance: ICache = new RedisCache(cacheConfig);
export const cache = cacheInstance; // 전역에서 하나의 인스턴스 사용

위와 같이 Singleton 으로 사용했고, 필요할때만 전역에서 불러와 사용합니다.
ICache 덕에 test code 에서 주입하기도 좋습니다!
캐싱 전략은 우선적으로 TTL 밖에 없습니다!

5) 그래서 현 최종 인프라 개괄도

~~개발새발인 것 같지만 이게 최대치~~

4. DevOps

Prometheus + PLG stack 을 기본 베이스로 깔고, (Prometheus)node-exporter 들로 서버 자체 매트릭을 가져오는 정도를 목표로 세팅했습니다. (사실 아직 완료는 못했고 중에 있습니다.)

근데 웬걸, alloy 라는 걸로 바뀌어 버렸네?
굳이 왜..? 를 좀 더 찾아보니 "Grafana는 Prometheus, Promtail, Grafana Agent 등 서로 다른 수집 도구들을 하나로 통합" 하고 싶었다고 하네요.. - https://grafana.com/blog/2024/04/09/grafana-agent-to-grafana-alloy-opentelemetry-collector-faq/?utm_source=chatgpt.com ~~근데 사실 오히려 좋아~~

단계	일정 (2025년 기준)	주요 내용
Promtail LTS 시작	2025-02-13	기능 업데이트 종료, 보안·버그 수정만 지원 (Grafana Labs, Grafana Labs)
Alloy 기능 통합	Loki 3.4 이후	Promtail 기능 및 구성 변환 도구 Alloy에 통합 (Grafana Labs, Grafana Labs)
Promtail EOL	2026-03-02	공식 지원 및 업데이트 완전 종료 (Grafana Labs, Grafana Labs)

메트릭, 로그, 트레이스 통합 수집 → Alloy,
시각화/알람 → Grafana,
스토리지 → Loki/Prometheus

이 3강 체제로 "Observability" 를 끌어올리려고 합니다!

마무리와 TOBE

(혹시나 궁금하신 분들 위해..) DAU 는 약 50+- a 선으로 나오고 있습니다. 꾸준히 보는 사람만 보는? 그런 좀비 서비스랄까요ㅎㅎ 일단 제가 가장 열심히 DAU에 일조하고 있는 듯
통계 데이터는 약 300만개에 달하게 되었습니다. P.D.D 세팅이 시급합니다.. 어서 제발 끝내자..

이제 다음 feature 는 진짜 다른 플랫폼 통계 데이터 aggregation 으로의 확장일 것 같습니다. 아마 미디엄이나 티스토리 둘 중 하나가 될 것 같네요!

여기까지가 Velog Dashboard v2의 생존기(?)와 업데이트 소식입니다! ~~매번 글을 너무 과하게 쓰는 것 같아서 많이 줄였습니다 ㅋㅎㅋㅎ~~

[책 리뷰] 객체 지향 시스템 디자인 원칙 - 마우리시오 아니체

Sun, 20 Jul 2025 10:09:43 GMT

[ "길벗 출판사에서 책을 협찬 받아 작성된 서평입니다." ]

객체지향 시스템 디자인 원칙

Maurício Aniche(마우리시오 아니체): 아디옌(Adyen, 네덜란드 기술 기업)에서 테크 리드로 근무(근데 최근 우버로 이직하신 듯), 아디옌의 테크 아카데미를 포함해 엔지니어를 위한 추가 교육과 훈련에 중점을 둔 엔지니어링 지원 이니셔티브 팀을 이끌고 있다. 또한 네덜란드 델프트 공과대학교(Delft University of Technology)에서 소프트웨어 공학 조교수로 재직 중. 2021년 올해의 컴퓨터 과학 교사 상을 받았고, 혁신적인 강사에게 수여되는 명예로운 TU 델프트 교육 펠로우십(Delft Education Fellowship)을 받았다. - 링크드인 & 저자 블로그

~~요새 저자들 링띤을 어떻게든 찾아내서 책 잘 읽었다고 슬쩍 메시지를 보내본다. 모르는 부분 물어보는 재미가 아주 쏠쏠하다.~~

🔥 길벗 책 링크 - https://www.gilbut.co.kr/book/view?bookcode=BN004492 🔥 코드 참조 깃허브 레포 - https://github.com/enshahar/SimpleObjectOrientedDesignCode (옮긴이, 오현석님께서 모두 한글로 재구성 해주셨다.) 🔥 그리고 이를 python 으로 직접 포팅한 레포 - https://github.com/Nuung/SimpleObjectOrientedDesignCode

리뷰

시장에는 객체지향 설계(OOP)와 디자인 패턴 관련 책들이 정말 넘쳐난다. 그럼에도 이 책이 매력적이었던 포인트는, 저자의 머릿말에서부터 “이 정도면 충분한 디자인을 이루는 방법” 에 대해 이야기하고 있기 때문이다. 이 책은 실제로 아래 그림 한 장으로 표현할 수 있다.

이상하게 가장 오래 기억에 남는 문장은 6장에서 나오는 "프레임워크와 싸우지 마라" 이다. 도메인 주도 설계(DDD)에 깊이 몰입하다 보면, ‘프레임워크는 거들 뿐’이라는 말에 너무 진심이 되어버릴 때가 있다. 실제로 나도 과거에 프레임워크 의존성을 싹 걷어낸 뒤, REST API 하나 만들기 위해 어답터 패턴을 굳이 도입하고, 퍼사드를 하나 더 추가하면서 “프레임워크랑 싸운” 경험이 있다. (나름 프레임워크 의존성 없는 독립 모듈에 프레임워크를 얹어 보겠다는 일념으로)

물론 그 시도가 틀렸다고 말할 순 없지만, 책에서 말하듯 어디에서는 프레임워크에 의존하지 말아야 하고, 어디에서는 과감하게 활용해야 하는지의 경계를 짚어주는 부분이 특히 와닿았다. (해당 장에서는 "인프라 계층" 에 대한 것을 다루는데, 아주 좋음!)

이 책은 전체적으로 짧다. 그렇기에 실습 없이 읽으면 아무런 의미가 없다. 꼭 깃허브에 공개된 예제 코드를 따라가는 것을 추천한다.

2장부터 5장은 코드작게, 일관성, 의존성, 추상화까지 SOLID 원칙을 하나씩 top-down 하는 흐름이고,
6장과 7장이 인프라를 포함한 외부 의존성 (모듈)에 대해 다루며,
8장 이상과 현실에 대한 얘기를 하며 끝난다.

솔직히 말하면, 많은 설계/아키텍처 책들은 읽다 보면,, 마치 "성공하는 100가지 법칙!" 같은 책을 읽는 느낌이 든다. 책 내용이 안좋다는게 아니라, 유니콘에 대한 해설책 느낌이랄까.

물론 이 책도 모든 걸 해결해주지는 않지만, 점진적인 고도화 전략과 각 장별로 전달하려는 핵심을 예제 기반으로 잘 녹여낸다는 점에서 실전성 높은 책이라고 생각이 든다. (각 장에서 핵심을 설명하고, “피플그로우!” 라는 실전 예제가 항상 느낌표와 함께 따라온다. 이 반복도 의외로 인상 깊다.)

무엇보다도 좋았던 건, 처음부터 완벽하지 않아도 괜찮다고 말해준다는 점이다. 처음에는 모든 책임을 명확히 구분하거나, 도메인을 제대로 정의하지 못하는 게 당연하며, 그것을 점진적으로 개선해가는 방향이 더 현실적인 접근이라는 메시지가 담겨 있다. "진짜 좋은 디자인은 세 번쯤 다시 작성한 후에야 얻어진다!"

나는 이 책을 처음에는 한숨에 읽고, 그 뒤 코드를 하나하나 Python으로 포팅하면서 다시 읽었는데, 생각보다 시간이 정말 오래 걸렸다. ~~사실 Python으로 다시 짜는 데 대부분의 시간이 들었다는 건 비밀이다.~~ 디자인 책은 아무리 라이트하다고 해도, 주제 자체가 결코 라이트하지 않다는 점을 다시금 느꼈다.

이 책은 마틴 파울러, DDD, 전통적인 디자인 패턴 등 다양한 고전과 참고 문헌을 바탕으로 하고 있다. 하지만 그 모든 걸 당장 직접 찾아가며 읽을 필요는 없다.

오히려 이 책이 그런 책들에 들어가기 전, 특히 DDD를 공부하기 전에 읽으면 딱 좋은, 전초전 같은 느낌의 책이다. “왜 디자인 패턴?” “왜 객체지향?” “좋은 코드란 대체 뭘까?”라는 질문에 대해 가볍고도 넓게 훑어준다. 이 책을 읽은 다음 ‘클린 아키텍처’와 DDD를 읽으면, 훨씬 더 잘 이해할 수 있을 것이다.

이제 실제 코드 구현은 AI 가 대부분이 한다. 하지만 사견으로 여전히 "적절한 디자인" 은 답답한 구석이 너무나 많다. 그리고 "적절한 디자인" 이라 함은 S/W 구준, 서비스의 현실적인 상황, 팀 내부의 상황 등을 포함해 내&외부에 따라 trade-off 정도가 천차만별이다.

나는 여전히 이 부분에서 필연적으로 AI 를 control 할 인력이 필요하다고 본다. 당장의 cache layer 를 구현하는데, TTL 전략 외 LRU, LFU 까지 강제 구현해버려서 짜증이 났다.

철저하게 TTL 만 사용할꺼고 필요로 하는데, 이 때문에 storage 와 strategy 인터페이스(추상화) 까지 만들어 버렸다. 물론 이게 틀린게 아니라 내가 원한 것 보다 너무 과했기 때문이다. 이걸 다시 리펙토링 하며 가다듬다보면 '이럴꺼면 내가 처음부터 하지',,, 라는 생각도 많이 든다.

이 부분은 더 고도화되겠지만 본질적으로 거시적인 관점에서 trade-off 에 맞는 output 을 평가하는 주체는 아직까지 "인간" 의 영역이고, 이 영역은 더 소중해 질 것으로 보인다. 그렇기 때문에 이런류의 책이 "더 이상 필요 없다 / 이제 AI 가 다 해준다" 라는 평가에는 강력하게 반대한다.

목차별 리뷰

1장 모든 게 복잡도 관리다

이 책은 기존의 객체지향 베스트 프랙티스를 단순히 반복하지 않는다. 원제인 Simple Object Oriented Design 이 암시하듯이, 복잡도를 줄이는 것, 즉 단순한 구조와 유지보수 가능한 시스템을 어떻게 설계할 수 있는가에 초점을 맞춘다.

얘기 시작. 복잡성을 줄이거나 그대로 유지하기 위한 작업을 수행하지 않으면 S/W 시스템은 시간이 지남에 따라 복잡성이 증가한다.

저자는 매니 레만(Lehman)의 논문, "대규모 프로그램의 생명 주기에서 법칙, 진화, 보존에 대한 이해" 라는 논문에서 인용하며 논의를 시작한다. 요지는 단순하다. *복잡성은 줄이거나 유지하지 않으면 반드시 증가한다.* 즉, 이를 방치하면 시스템은 유지보수하기 점점 어려워지고, 결과적으로 개발 속도는 느려지고 품질은 낮아진다.

[ 단순한 객체지향 디자인을 위한 여섯 가지 핵심 원칙 ]

책에서는 단순함을 지향하는 객체지향 디자인을 위해 다음 여섯 가지 원칙을 제시한다.

단순한 코드
메서드와 클래스는 작고 단순하게 유지해야 한다. 코드의 "크기" 자체가 복잡성을 야기할 수 있다.
→ 즉, 짧고 명료한 함수, 작은 클래스 단위를 유지해야 함.
일관성 있는 객체
객체는 항상 유효한 상태를 유지해야 한다.
외부에서 Basket 클래스를 마음대로 수정할 수 있다면 이는 곧 무결성 침해로 이어진다.
이를 위해선 다음 키워드 정도를 떠올릴 수 있다.
- 불변성(immutable), 적절한 getter/setter 제공, 접근 제어자 활용 등
적절한 의존성 관리
높은 응집도(high cohesion)와 낮은 결합도(low coupling)를 동시에 지향해야 한다.
자식 클래스가 바뀔 때마다 부모 클래스도 바뀐다면, 이는 변경 전파의 악순환이다.
→ 이러한 상황을 방지하기 위한 핵심은 디커플링(decoupling)이다.
좋은 추상화
추상화는 단순성과 확장성 사이의 균형을 제공한다.
단순함을 추구하다 보면 어느 순간 클래스의 메서드가 지나치게 많아지며 혼란을 유발할 수 있다.
의미 있는 추상화 계층을 도입하는 것이 해결책이다.
외부 의존성과 인프라를 적절히 다루기
비즈니스 로직과 외부 시스템(DBMS, API 등)과의 의존성은 분리되어야 한다.
예: DB 연결 로직이 여기저기 흩어져 있다면, 추후 캐시 도입이나 DB 교체 시 유지보수 지옥이 펼쳐진다.

※ 참고: DDD에서는 이러한 외부 시스템과 자원을 “인프라”로 분류한다.
좋은 모듈화
시스템을 작고 명확한 컴포넌트 단위로 나누는 것이 중요하다.
이는 이해하기 쉽고, 변경하기 쉬운 코드를 만드는 데 핵심이다.

[ 일상적인 활동으로서의 단순한 디자인 ]

복잡도를 낮추는 행위는 일회성 이벤트가 아니라, 일상의 루틴처럼 지속적으로 수행되어야 한다.

복잡성 줄이기는 개인 위생과 같다
매일 조금씩 관리하지 않으면, 쌓이고 쌓여 나중에는 감당이 안 되는 수준이 된다.
복잡성이 필요할 수도 있지만 영구적이어서는 안 된다
예외적 상황에서 복잡한 구조가 불가피하더라도, 이를 영구 구조로 유지하면 안 된다. (하지만 소 잡는 칼로 닭 잡지 마라! 점진적 접근!)
지속적으로 복잡성을 해결하는 것이 비용 효율적이다
미뤄놓으면 나중에 더 큰 비용을 치른다. 리팩터링과 점진적 개선을 게을리하지 말아야 한다.
고품질 코드는 좋은 실무 프랙티스를 촉진한다
→ 이른바 "깨진 유리창 이론"처럼, 더 나은 코드가 더 좋은 문화를 만든다.
복잡성을 통제하는 것은 생각보다 어렵지 않다
꾸준한 주의와 실천이 있다면 충분히 관리 가능한 수준이다.
디자인을 단순하게 유지하는 것은 개발자의 책임이다
아무도 해주지 않는다. 개발자 스스로가 구조를 정리하고 유지할 책임이 있다.
“이 정도면 충분히 좋은 디자인이다”라는 마음가짐
완벽한 디자인을 고집하기보다, 지금 당장 필요한 수준에서 가장 깔끔한 해법을 추구해야 한다.
『A Philosophy of Software Design』에선, *"진짜 좋은 디자인은 세 번쯤 다시 작성한 후에야 얻어진다"* 라는 말이 등장한다. 전적으로 동의하는 대목이다.

[ 정보 시스템 아키텍처 구성 요소 ]

이 책에서는 복잡도를 줄이기 위해 객체지향 아키텍처를 어떻게 구성할 것인가에 대해서도 간략히 소개한다:

엔터티(Entity)
비즈니스 개념을 표현하는 핵심 객체.
예: Invoice 클래스는 청구서라는 개념을 속성과 메서드로 표현한다.
서비스(Service)
복잡한 비즈니스 로직을 캡슐화.
예: GenerateInvoice는 장바구니의 품목을 종합해 최종 청구서를 생성한다.
리포지터리(Repository)
데이터 저장 및 조회 로직을 담당.
DB와의 통신은 이 계층에서 처리.
DTO (Data Transfer Object)
계층 간 정보 전달에 사용되는 단순한 데이터 구조체.
유틸리티 클래스
언어나 프레임워크가 제공하지 않는 범용 기능을 모은 클래스.
→ 다만 너무 남용하면 도메인 의미를 흐릴 수 있어 주의 필요.

2장 코드를 작게 유지하기

(개인적인 해석으로) 이 장의 핵심 주제는 단 하나다.

“코드를 작게 나누는 것이 복잡도 제어의 출발점이다.”

크고 복잡한 코드일수록 변경에 취약하며, 버그가 발생하기 쉽고, 테스트와 협업이 어렵다.
반대로 작고 응집력 있는 코드 단위는 더 안전하고 유지보수도 용이하다.

클래스와 메서드는 작아야 한다. 긴 메서드는 언제든 버그의 온상이 될 수 있다. 그래서 기본 원칙은 단순하다. “작은 단위는 항상 큰 단위보다 낫다.”

[ 복잡한 메서드를 비공개 메서드로 나눠라 ]

응집력 있는 컴포넌트는 단일한 책임을 가진다. 즉, 한 가지 일만 하는 메서드로 쪼개야 한다. 이를 위한 체크리스트는 다음과 같다:

새 메서드의 목적을 설명하는 명확한 이름을 붙일 수 있는가?
새 메서드가 응집력 있고, 작으며, 외부 공개 메서드에서 쉽게 호출될 수 있는가?
많은 파라미터나 클래스에 의존하지 않고 간결하고 명확한가?
정적 메서드로 만들 수 있을 정도로 독립적인가? -> 정적 메서드로 만들 수 있다는 건, 해당 코드가 객체 상태에 의존하지 않는다는 뜻이기도 하다.

[ 복잡한 코드 단위를 다른 클래스로 옮겨라 ]

특정 코드가 현재 클래스의 주요 책임과 관련이 없다면, 그 코드는 다른 클래스로 옮겨야 한다. 아래 질문들을 스스로 던져보자:

이 코드는 클래스의 나머지 코드와 다른 작업을 하는가?
이 코드에 별도의 이름과 클래스가 필요할 정도로 독립적인 의미가 있는가?
독립적인 테스트가 필요한가?
클래스 전체가 너무 비대해지고 있진 않은가? → 이럴 땐 분리하라.

[ 코드를 작은 단위로 나누지 말아야 할 때 ]

항상 쪼개는 게 답은 아니다. 오히려 쪼개면 복잡해지는 경우도 있다. 아래는 쪼개지 말아야 할 때의 기준이다:

퍼즐 조각들이 독립적으로 존재할 수 없을 때 억지로 분리하면 메서드 시그니처가 복잡해짐
해당 로직이 교체될 가능성이 낮을 때
별도로 테스트할 만한 가치가 없을 때

PS. 여기서 “클래스병” 조심하자 — 존 오스터하우트의 Software Design Philosophy 에서 말하듯, 불필요하게 클래스를 쪼개면 오히려 관리가 더 힘들어진다.

[ 리팩터링하기 전에 전체적으로 살펴보라 ]

무작정 리팩터링하지 말고 먼저 최종 구조를 머릿속에 그려보라. → 미래를 고려한 변화인지 반드시 확인하고 실행할 것.

리팩터링 후 모습은 어떤가?
그 모습이 지향하는 설계 철학에 부합하는가?
지금의 디자인에 문제가 있는 건가?

[ 예제: 직원 데이터 임포트하기 ]

이 책은 "피플그로우!" 프로젝트를 계속 고도화 해간다. 상단 깃허브 레포, https://github.com/Nuung/SimpleObjectOrientedDesignCode 에서 실제 코드를 볼 수 있다. (근데 python 으로 포팅해봄)

여기서 import_employee_service라는 덩치 큰 서비스를 점진적으로 리팩터링하고 쪼개나간다.

└── ch2
    ├── v1
    │   ├── __init__.py
    │   ├── csv_parser_library.py
    │   ├── employee_repository.py
    │   ├── employee.py
    │   ├── import_employee_service.py
    │   └── import_result.py
    └── v2
        ├── __init__.py
        └── import_employee_service.py

[ 코드를 읽기 쉽게 만들고 문서화하라 ]

클린코드에선 코드 작성 vs 읽기 시간의 비율은 1:10 이라는 언급이 있었고, 개발자는 전체 시간의 60%를 코드 읽기에 소비한다는 논문도 있다. 이 사실만으로도 “읽기 쉬운 코드”의 중요성은 충분히 강조된다.

1. 좋은 이름을 계속 찾아라

유비쿼터스 언어(Ubiquitous Language, 개발 팀원 모두가 도메인 개념을 이해하고 의사소통하기 위해 사용하는 일관성 있는 공통 언어) 를 기반으로 하라. 팀 전체가 도메인을 공유하는 언어로 일관성 있게 표현해야 한다. → 좋은 네이밍은 단순한 기교가 아니라, 팀 커뮤니케이션의 기반이다.

2. 의사결정을 문서화하라

조건 분기나 로직이 복잡할수록 “왜 이런 결정을 했는가”를 문서화해야 한다. → 조건문은 “결과”이고, 주석(설명, 외부 docs등)은 그 “배경”이다.

3. 코드에 주석을 추가하라

너무 많은 주석은 오히려 혼란을 주지만, 주석이 전혀 없는 코드도 읽기 힘들다. 잘 정제된 핵심 주석은 코드 품질의 일부다.

주석에 대한 의견은 다양하지만, 개인적으로 임베디드 시스템이나 byte 한 개에 목숨거는게 아닌 이상, 무슨 TCP 의 14byte 못지키면 죽는게 아닌 이상, 개인적으로 제발 주석을 좀 썻으면 한다. 그리고 책에서는 "왜 했는가?" 도 주석에 남길 필요가 있는 경우가 있다고 언급한다! ~~매우 동감! 쩨발!~~

[ 새로운 복잡성을 기존 클래스에서 분리하라 ]

비즈니스 복잡성 증가함에 따라 코드는 성장할 수 밖에 없지만, 성장은 통제돼야 한다. 많은 경우 클래스가 무한정 성장하는 이유는 개발자가 기존 코드를 변경하지 않고 새로운 기능을 추가할 수 있게 해주는 적절한 추상화나 확장 지점이 부족하기 때문. ~~(뼈를 너무 맞아서 좀 아픈 대목)~~

1. 복잡한 비즈니스 로직을 자체 클래스로 분리하라

새로운 복잡한 로직은 전용 클래스로 독립시켜야 한다. 단, 해당 로직이 작용하는 대상 클래스와 논리적으로 가까운 곳에 위치시키는 것이 좋다.

2. 큰 비즈니스 흐름을 분해하라

여러 단계가 복합적으로 얽힌 비즈니스 흐름은 다음과 같은 방식으로 나눠보자! 핵심은, 하나의 흐름을 여러 개의 작고 응집력 있는 단위로 나누는 것이다.

GOF 패턴 예시:
- 책임 연쇄 패턴(Chain of Responsibility)
- 데코레이터 패턴
- 옵저버 패턴
더 복잡한 경우:
- 도메인 이벤트 기반 시스템을 고려하자
- 이벤트 기반 아키텍처로 재설계할 수도 있다

SRP(Single Responsibility Principle)는 “하나의 변경 이유만 있어야 한다”는 원칙이다.

이 장에서 강조하는 “작은 단위로 쪼개기” 는 SRP와 결을 같이하지만, SRP가 “책임”에 초점을 둔다면, 이 장은 “크기와 응집력”에 초점을 둔다. 초기 설계 단계에서는 "책임"을 명확히 정의하기 어렵기 때문에, 그보다 더 간단한 접근은 “일단 작게 쪼개기” 라고 한다.

3장 객체의 일관성 유지하기

이 장에서는 객체가 스스로 자신의 상태를 "일관성 있게 유지하도록" 설계하는 것이 얼마나 중요한지를 중심으로 다룬다. 특히 도메인 모델에서의 일관성 유지란 단순히 값 검증을 넘어서, 객체가 책임져야 할 행위와 상태에 대한 깊은 이해를 요구한다.

PS. 일관성(consistency)은 객체가 정확하고 신뢰할 수 있는 정보를 가지고 있음을 나타냄 PS. 반면 DBMS 에서는 무결정(integrity)이 "정보를 정확하게 유지하는 것"을 의미 (일관성은 주로 데이터의 가용성과 관련 있음)

[ 항상 일관성을 유지하라 ]

1. 클래스가 스스로 일관성을 책임지게 하라

데이터의 일관성을 보장하는 책임은 데이터가 속한 클래스 내부에 있어야 한다. 예를 들어, 교육 과정 등록 기능에서 Offering 클래스는 최대 참가자 수를 넘기지 않도록 직접 add_employee() 메서드 내에서 유효성 검사를 수행하고, 등록 시 자동으로 빈 자리를 줄인다. 외부에서 이를 처리하면 중복된 로직이 생기고, 시스템 전반에서 예기치 못한 불일치 상태가 생길 수 있다.

2. 전체 작업과 복잡한 일관성 검사를 캡슐화하라

단일 클래스가 책임지기 어려운 경우, 서비스와 엔티티가 함께 협력하여 일관성을 보장할 수 있도록 설계해야 한다. 서비스는 흐름을 조율하고, 엔티티는 그 안에서 내부 상태를 보장하는 식이다.

3. 예제, `Employee` 엔터티 업데이트!

클래스 내부 일관성 보장하도록

오퍼링 직언 추가 되면 잔여 허용 인원 자동으로 하나 줄이고
자리가 꽉 찬 경우라면 새로운 직원이 추가되지 않도록

동시성과 디자인

비기능적 요구 사항이 디자인 결정에 영향을 미칠 수 있다. 오퍼링에 직원 추가하는 요청이 동시에 일어난다면, 지금 디자인은 작동하지 않을 수 있음.

class Offering:
    """Training offering with enhanced enrollment management"""

    def __init__(self, training: Training, date_: date, maximum_number_of_attendees: int):
        self._id: int | None = None
        self._training = training
        self._date = date_
        self._employees: Set[Employee] = set()
        self._maximum_number_of_attendees = maximum_number_of_attendees
        self._available_spots = maximum_number_of_attendees

    @property
    def employees(self) -> Set[Employee]:
        """Get immutable copy of enrolled employees"""
        return frozenset(self._employees)  # Return immutable set

    def add_employee(self, employee: Employee) -> None:
        """Add employee to offering with validation and prevent duplicates"""
        if self._available_spots == 0:
            raise OfferingIsFullException()
        if employee in self._employees:
            # 이미 등록된 직원이면 spots 차감하지 않고 무시
            return
        self._employees.add(employee)
        self._available_spots -= 1

    def has_available_spots(self) -> bool:
        """Check if offering has available spots"""
        return self._available_spots > 0

    @property
    def available_spots(self) -> int:
        """Get number of available spots"""
        return self._available_spots

    @property
    def training(self) -> Training:
        """Get training for this offering"""
        return self._training

    def is_employee_registered(self, employee: Employee) -> bool:
        """Check if employee is registered for this offering"""
        return employee in self._employees

[ 효과적인 데이터 유효성 검사 메커니즘을 디자인하라 ]

1. 사전 조건을 명시적으로 정의하라

메서드는 자신이 기대하는 입력 조건을 분명하게 설정해야 한다. 예를 들어, addEmployee(employee) 메서드에 None 값이 들어오면 단순히 무시하는 것이 아니라, 아예 None 이 들어올 수 없음을 전제로 코드 설계를 해보는 것. 그렇게 함으로써, 숨은 오류 발생을 방지할 수 있고 유지보수가 쉬워진다.

근데 모든 경우에 대해 다 처리하면, 내부 개발 코드만 더 늘어난다. 이때 중요한 것이 *"존재하지 않는 오류 정의"* 하는 것이다.

2. 유효성 검증 컴포넌트를 만들라

비즈니스 룰이 복잡해질수록 검증 로직은 분리되어야 재사용성과 가독성이 높아진다. 이 때 Specification Pattern 과 같은 명세 패턴을 도입해, 특정 조건을 만족하는지를 명확히 정의할 수 있다. 다만 모든 유효성 검사를 엔티티 내부에 구현하는 것은 피하고, 서비스 계층에서 조율하는 방향이 좋다.

3. null은 신중하게 사용하고, 피할 수 있다면 피하라

null은 호출자에게 모든 책임을 전가하기 때문에 위험하다. 가능하면 빈 객체, 옵션 값, 또는 에러 객체로 대체하는 것이 바람직하다. (특히 파이썬과 같은 언어에서는 None 검사 분산이 코드 복잡도를 높이는 주범이 될 수 있다ㅠㅠ)

근데 빈 값이 가능하다면?

값 없음을 나타내는 객체를 만들어 보는 것은 어떨지? (빈 리스트 등)
문제 발생시 null 리턴이 아니라, 문제가 무엇인지 설명하는 클래스 리턴은?

4. 예제: 교육 과정에 직원 추가하기

class AddEmployeeToOfferingService:
    """Service for adding an employee to a training offering with validation"""

    def __init__(
        self,
        offerings: OfferingRepository,
        employees: EmployeeRepository,
        validator: AddEmployeeToOfferingValidator,
    ):
        self._offerings = offerings
        self._employees = employees
        self._validator = validator

    def add_employee(self, offering_id: int, employee_email: str) -> None:
        """Add an employee to an offering after validation"""
        offering_opt = self._offerings.find_by_id(offering_id)
        employee_opt = self._employees.find_by_email(employee_email)

        if not offering_opt or not employee_opt:  # 1
            raise InvalidRequestException("Offering and employee IDs should be valid")

        offering = offering_opt
        employee = employee_opt

        validation = self._validator.validate(offering, employee)  # 2
        if validation.has_errors():  # 3
            raise ValidationException(validation)

        offering.add_employee(employee)  # 4


class ValidationResult:
    """Result of a validation check, containing errors if any"""

    def __init__(self):
        self.errors: List[str] = []

    def has_errors(self) -> bool:
        """Check if there are any validation errors"""
        return bool(self.errors)

    def add_error(self, error: str) -> None:
        """Add a validation error message"""
        self.errors.append(error)


class ValidationException(Exception):
    """Exception raised for validation failures"""

    def __init__(self, validation_result: ValidationResult):
        self.validation_result = validation_result
        super().__init__(f"Validation failed with errors: {validation_result.errors}")


class AddEmployeeToOfferingValidator:
    """Validator for adding an employee to a training offering"""

    def __init__(self, trainings: TrainingRepository):
        self._trainings = trainings

    def validate(self, offering: Offering, employee: Employee) -> ValidationResult:
        """Validate if an employee can be added to an offering"""
        validation = ValidationResult()

        if not offering.has_available_spots():  # 1
            validation.add_error("Offering has no available spots.")

        times_participant_took_the_training = self._trainings.count_participations(
            employee, offering.training
        )

        if times_participant_took_the_training >= 3:  # 2
            validation.add_error("Participant can't take the training again.")

        if offering.is_employee_registered(employee):
            validation.add_error("Participant already in this offering.")

        return validation

DDD(Domain-Driven Design)와 클린 아키텍처에서는 도메인 서비스와 애플리케이션 서비스를 명확히 구분할 것을 권장한다.

애플리케이션 서비스는 작업을 조정하는 책임만을 가지며, 비즈니스 규칙을 포함하지 않는다. 즉, 외부 요청을 받아 도메인 객체를 호출하고 그 결과를 반환하거나 후속 작업을 조정하는 역할에 집중한다.
반면, 도메인 서비스는 도메인 내의 중요한 비즈니스 규칙을 담는 위치다. 특히 도메인 엔티티만으로 표현하기 어렵거나 여러 엔티티가 협력해야만 정의 가능한 로직은 도메인 서비스에 위치시킨다.

이렇게 제어 흐름과 비즈니스 로직을 명확히 분리하면 도메인 모델의 순수성과 코드 유지 보수성이 향상된다. 그러나 필자는 처음부터 이 분리를 강박적으로 지키기보다는, 단순한 서비스 코드 안에 제어와 로직을 함께 담아 빠르게 구현하는 방식을 선택한다.

즉, 처음엔 하나의 서비스가 애플리케이션과 도메인 역할을 모두 수행하게 한 뒤, 코드가 점차 커지고 복잡성이 증가하면 그때서야 역할을 분리하는 점진적 리팩터링을 제안한다. 이는 실용주의적인 접근으로, 지나치게 이른 추상화와 과도한 레이어 분리를 피하고, 현실적인 개발 흐름을 존중한 방식이다.

[ 상태 확인을 캡슐화하라 ]

객체의 상태 확인은 그 자체로도 캡슐화되어야 한다. 단순히 속성 값을 외부로 노출하기보다는, 객체 내부에서 판단 가능한 책임을 맡기고, 클라이언트는 그 판단 결과만 신뢰하도록 해야 한다.

복잡한 구조일수록 상태 확인 로직이 분산되기 쉽고, 이로 인해 "샷건 수술(Shotgun Surgery)" 현상이 발생할 수 있다. 이는 어떤 기능 변경이 시스템 여러 곳의 코드를 동시에 수정하게 만드는 대표적인 안티패턴이다 (Wikipedia - Shotgun Surgery).

1. 명령하라, 질문하지 마라!

OOP의 고전적인 원칙인 Tell, Don’t Ask는 마틴 파울러가 강조한 철학으로, 객체에게 데이터를 꺼내와서 외부에서 판단하게 하지 말고, 객체에게 무엇을 해야 할지를 명령하라는 뜻이다.
즉, if (obj.canDoX()) { obj.doX(); }와 같은 패턴은 obj.tryToDoX()처럼 하나의 메시지로 통합하는 것이 좋다.

이 원칙은 객체의 내부 구현을 숨기고, 역할 중심의 인터페이스를 설계하는 데 핵심이 된다.

[ 필요한 게터와 세터만 제공하라 ]

객체의 캡슐화를 유지하려면, 게터(getter)와 세터(setter)를 남발해서는 안 된다. 게터를 통해 내부 상태를 지나치게 노출하거나, 세터를 통해 객체 외부에서 무분별하게 값을 변경하게 되면 객체가 스스로의 일관성을 책임지기 어려워진다.

(특히나 python 에서도 이걸 좀 잘 생각해야 한다. 중요한 것들을 마냥 attribute 로 접근해서 휘젓고 다니지 못하게 해야 한다!)

1. 상태를 변경하지 않고 클라이언트에 너무 많은 정보를 노출하지 않는 게터

CQS(Command-Query Separation) 원칙에 따르면, 메서드는 명령(command) 또는 조회(query) 중 하나만 수행해야 한다.

명령은 상태를 변경하지만 값을 반환하지 않아야 하고,
쿼리는 값을 반환하지만 상태를 변경하지 않아야 한다.

이 원칙을 지키면, 예측 가능한 인터페이스 설계가 가능해지고, 사이드 이펙트를 방지할 수 있다.
객체의 상태를 외부에서 해석하게 하지 말고, 그 의미를 추상화한 메서드를 제공하는 것이 바람직하다. 예를 들어 hasAvailableSpots()는 availableSpots > 0이라는 내부 판단을 외부에 감추면서도 의미를 정확히 전달한다.

2. 세터는 객체를 설명하는 속성에만 사용한다

객체의 핵심 상태나 일관성이 중요한 필드에는 세터를 제공해서는 안 된다.
대신, 의미 있는 메서드를 통해 의도를 표현하고, 내부에서 상태 변경과 유효성 검사를 함께 수행하는 방식이 좋다.
예를 들어, setAvailableSpots(int) 같은 메서드보다는 addEmployee(Employee)처럼 도메인 맥락에 맞는 행위 중심 메서드가 더 안전하고 명확하다.

[ 객체 집단의 불변 조건을 보장하도록 애그리게이트를 모델링하라 ]

객체 집단의 일관성을 보장하기 위해서는 애그리게이트라는 구조적 단위를 설계해야 한다. DDD에서 애그리게이트는 관련된 객체들을 하나로 묶고, 그 집단의 일관성을 유지하는 단위이며, 이 집단의 대표로서 애그리게이트 루트(aggregate root) 가 존재한다.

애그리게이트 루트는 다음과 같은 역할을 수행한다:

클라이언트는 루트에만 접근할 수 있다.
루트 객체를 통해서만 내부 객체의 상태가 변경된다.
루트의 허가 없이는 하위 객체를 직접 변경할 수 없다.
모든 클라이언트는 애그리게이트 루트에 대한 참조만 유지해야 하며, 하위 객체에 대한 참조는 허용되지 않는다.

이것은 단순한 캡슐화(encapsulation) 가 아니라, 도메인 모델에서 일관성(consistency) 을 강제하기 위한 핵심 원칙이다.

또한, 객체를 데이터베이스에 저장할 때도 루트 단위로 저장 및 조회해야 하며, 루트 객체마다 하나의 리포지터리(Repository) 또는 DAO(Data Access Object)가 있어야 한다.
내부 구성 객체가 아니라 루트를 중심으로 트랜잭션과 상태 변경이 관리되는 것이다.

1. 애그리게이트 루트의 규칙을 깨지 마라

실제 개발 과정에서는 하위 객체 중 하나만 빠르게 수정하고 싶어지는 유혹이 발생할 수 있다. 예를 들어:

성능상의 이유로 루트를 통하지 않고 하위 객체에 직접 접근하고 싶을 때
사용하는 프레임워크나 라이브러리가 내부 객체에 직접 접근하게 만들 때
깊은 객체 트리를 구성한 경우, 루트를 통해 접근하면 보일러플레이트 코드가 많아지는 경우 등

이런 경우에도 루트를 우회하지 말고, 설계 규칙을 우선 유지하는 것이 이상적이다. 그러나 저자는 여기서 질문을 던진다:

"이 규칙이 과연 불변의 진리인가?"

상황에 따라서는 성능, 단순성, 유지보수성 등을 이유로 트레이드오프가 필요할 수 있음을 인정하고, 현실적인 타협점을 만드는 유연함도 중요하다고 지적한다.

2. 예제: Offering 애그리게이트

class Offering:
    """Represents a training offering with enrollment management"""

    def __init__(
        self,
        training: Training,
        date_: date,
        maximum_number_of_attendees: int,
    ):
        self._id: int = None
        self._training = training
        self._date = date_
        self._enrollments: List[Enrollment] = []  # 1
        self._maximum_number_of_attendees = maximum_number_of_attendees
        self._available_spots = maximum_number_of_attendees

    def enroll(self, employee: Employee) -> None:  # 2
        """Enroll an employee in the offering"""
        if not self.has_available_spots():
            raise OfferingIsFullException()

        now = date.today()
        self._enrollments.append(Enrollment(employee, now))
        self._available_spots -= 1

    def cancel(self, employee: Employee) -> None:  # 3
        """Cancel an employee's enrollment in the offering"""
        enrollment_to_cancel = self._find_enrollment_of(employee)
        if enrollment_to_cancel is None:
            raise EmployeeNotEnrolledException()

        now = date.today()
        enrollment_to_cancel.cancel(now)

        self._available_spots += 1

    def _find_enrollment_of(self, employee: Employee) -> Optional[Enrollment]:  # 4
        """Find the enrollment for a specific employee"""
        for enrollment in self._enrollments:
            if enrollment.employee == employee:
                return enrollment
        return None

    def has_available_spots(self) -> bool:
        """Check if there are available spots in the offering"""
        return self._available_spots > 0

    @property
    def training(self) -> Training:
        """Get the training for this offering"""
        return self._training

    def is_employee_registered(self, employee: Employee) -> bool:  # 5
        """Check if an employee is registered for this offering"""
        return any(enrollment.employee == employee for enrollment in self._enrollments)

이 Offering 클래스는 애그리게이트 루트로서 다음과 같은 역할을 수행하고 있다

1) enroll()과 cancel()은 외부에서 호출되는 메서드이며, 내부 상태(_enrollments, _available_spots)를 직접 변경하지 못하게 하고 모든 로직을 루트 내부에서 처리한다.
2) 내부 데이터 구조(List[Enrollment])에 직접 접근하지 못하게 private 속성으로 두고, 검색 및 조회는 루트 메서드를 통해 캡슐화한다.

이처럼 애그리게이트 루트가 모든 상태 변경의 관문 역할을 하며, 전체 집합의 일관성을 책임진다. 그러나 이 구현 방식은 등록 목록을 순회하여 특정 직원의 등록 정보를 찾는 구조이기 때문에, 참가자 수가 많아질수록 성능 저하의 우려가 있다. (6장에서 다시 다룬다.)

4장 의존성 관리하기

소프트웨어에서 의존성(Dependency) 은 피할 수 없는 개념이다. 예컨대 서비스 클래스는 여러 레포지토리(repository)와 엔터티(entity)에 의존해서 동작한다. 이 말은 곧 다른 클래스와 “결합”된다는 의미다.

우리는 지금까지 설계 상 큰 클래스 대신 작은 클래스를 사용하고, 하나의 클래스가 모든 일을 하지 않도록 신경 써 왔다. 이는 “단일 책임 원칙(SRP)”과도 연결된다. 따라서 어떤 클래스가 다른 클래스에 의존하는 것 자체는 바람직할 수 있다. 실제로 혼자 모든 걸 처리하려 하기보다 역할을 나누고 협력하는 것이 객체지향의 핵심이다.

그러나 문제는 의존이 늘어날수록, 그 중 하나의 문제가 전체로 전파될 가능성도 함께 커진다는 점이다. 그래서 의존을 무분별하게 설정하면 안 된다.

중요한 건, "이 클래스가 어떤 클래스에 의존하는가?", "그 의존이 정말 좋은 의존인가?", 이 두 가지 질문에서 의존성 관리는 출발한다.

[ 고수준 코드와 저수준 코드를 분리하라 ]

의존성 관리에서 가장 먼저 떠올려야 할 개념은 바로 고수준(high-level)과 저수준(low-level)의 구분이다.

고수준 코드는 “무엇을 해야 하는가(what)”에 대해 설명한다.
저수준 코드는 “어떻게 수행할 것인가(how)”에 대해 설명한다.
고수준 코드를 먼저 읽으면 전체 기능이 어떤 역할을 하는지 빠르게 이해할 수 있으며, 저수준의 변경이 고수준에 영향을 주지 않도록 구조화할 수 있다.
이는 추상화 수준의 차이로 설명된다. 고수준은 더 추상적이고, 따라서 더 안정적이다. 고수준이 다른 고수준에 의존한다면 변경으로 인한 영향이 적다.

[ 의존성 역전 원칙 (DIP, Dependency Inversion Principle) ]

*"세부사항에 의존하지 말고, 추상화에 의존하라."* 이 원칙은 단순히 “의존성을 뒤집어라”는 말이 아니다. 진짜 의미는 다음과 같다.

고수준 모듈은 저수준 모듈에 의존하지 말고, 공통된 추상화(인터페이스)에 의존하라.
저수준 모듈도 동일한 추상화에 의존하게 만들라.

이 원칙은 Robert C. Martin의 SOLID 원칙 중 하나이며, 유지보수성과 확장성을 크게 높여준다.

이 책에서도 강조되지만, 스티브 프리먼과 냇 프라이스의 『테스트 주도 개발로 배우는 객체 지향 설계와 실천』에서는 인터페이스가 구조를 얼마나 유연하게 만들어주는지 아주 명확히 보여준다. 테스트가 용이한 구조로 잘 설계하고 싶다면, DIP와 인터페이스 활용을 잘하면 좋다.

[ 고수준 코드와 저수준 코드를 분리하지 않아도 되는 경우 ]

모든 상황에서 고수준과 저수준을 무조건 분리할 필요는 없다.
예를 들어 고수준의 구현 세부 사항을 비공개 메서드(private method) 로 캡슐화할 수 있다면, 필요할 때 쉽게 내부로 이동 가능하다. 리팩터링의 기회를 엿보면서 점진적으로 개선하면 된다.

근데 절대 섞지 말아야 할 것은 인프라 코드와 비즈니스 코드 이다. 예컨대 SQL 쿼리, HTTP 호출, 메시지 전송과 같은 인프라스트럭처 세부 구현은 비즈니스 코드와 절대 한데 섞이면 안 된다.

비즈니스 로직이 외부 시스템에 직접 의존하게 되면 테스트도 어렵고, 재사용도 어렵고, 변경에도 취약해진다.

[ 예제: 메시지 처리 작업 ]

(나의 깃허브 레포 기준, python/ch4/v1/message_sender.py 위치, MessageSender)

class MessageSender:
    """Service for sending messages"""

    def __init__(
        self,
        bot: Bot,
        user_directory: UserDirectory,
        repository: MessageRepository,
    ):
        self._bot = bot
        self._user_directory = user_directory
        self._repository = repository

    def send_messages(self) -> None:
        """Send all messages that need to be sent"""
        messages_to_be_sent = self._repository.get_messages_to_be_sent()
        for message_to_be_sent in messages_to_be_sent:  # 1
            user_id = self._user_directory.get_account(message_to_be_sent.email)  # 2
            self._bot.send_private_message(
                user_id,
                message_to_be_sent.body_in_markdown,
            )  # 3
            message_to_be_sent.mark_as_sent()  # 4

이 MessageSender 클래스는 충분히 고수준이다.

Bot, UserDirectory, MessageRepository라는 인터페이스에만 의존하고 있다.
이 인터페이스의 구체 구현체(저수준 클래스) 는 다른 곳에 있다.
이 구조 덕분에, 세부 구현이 바뀌더라도 MessageSender의 로직은 그대로 유지될 수 있다.
MessageSender는 자신의 “관심사”에 집중할 수 있고, 각 협력자들이 “어떻게” 일하는지는 알 필요조차 없다.

[ 불필요한 세부 사항이나 요소에 의존하는 것을 피하라 ]

복잡한 시스템일수록 정보 은닉(information hiding) 의 중요성이 커진다.

여기서 말하는 정보 은닉이란 단지 “숨기자”는 차원을 넘어, 변화 가능성이 높은 요소와 그렇지 않은 요소를 구분해 의존 구조를 설계하는 것이다. 핵심은 어떤 요소가 바뀌더라도 다른 구성 요소에 파급효과를 일으키지 않도록 만드는 것. 이를 위해선 '의존성을 최소화하고, 꼭 필요한 것에만 의존하도록' 제한하는 설계가 필수적이다.

1. 여러분이 소유한 클래스만 요구하거나 반환하라

여기서 ‘여러분이 소유한 클래스’란 도메인 모델에 속하며, 여러분이 직접 통제하고 수정할 수 있는 클래스를 의미한다. 반대로, 외부 라이브러리나 SDK 등은 여러분의 코드 바깥에 있으며, 변경을 예측하기 어렵고 주기적으로 업데이트되는 요소들이다.
예를 들어 채팅 도구 SDK를 도입한다고 할 때, 이 SDK가 제공하는 클래스를 그대로 코드 전반에 퍼뜨리면, SDK의 버전이 바뀔 때마다 전방위적으로 코드를 수정해야 할 수도 있다. 즉, SDK에 정의된 클래스를 직접적으로 전달하거나 반환하는 순간, 강결합이 시작되는 것이다.
이러한 강결합을 피하기 위해선 외부 의존성과 도메인 모델 사이에 적절한 추상화 계층을 두는 것이 중요하다.

2. 클라이언트에게 필요한 것 이상을 제공하지 마라

하나의 도메인 엔티티를 여러 곳에서 재사용하는 것은 자연스럽고 흔한 일이다. 하지만 문제는 엔티티 전체를 노출할 때 발생한다.
예컨대, 어떤 클라이언트는 단지 이름과 이메일만 필요로 하지만, 전체 엔티티를 전달받게 되면, 그 엔티티의 어떤 속성이든 변경될 가능성을 갖는다. 이로 인해 의도치 않은 변경 전파와 데이터 노출 문제가 발생할 수 있다.
따라서, 엔티티 전체가 아닌 필요한 정보만 제공하는 것이 중요하며, 이를 실현하기 위한 대표적인 방법이 바로 클라이언트 요청과 엔티티를 분리하고, 정보를 추상화하는 것이다. DTO(Data Transfer Object)나 응답 전용 뷰 모델 같은 것들이 이에 해당한다.

[ 너무 많은 클래스에 의존하는 클래스를 분리하라 ]

예제: MessageSender 서비스 분리하기, (나의 깃허브 레포 기준, python/ch4/v2/message_sender.py 위치, MessageSender)

class MessageSender:
    """Service for sending messages via multiple channels"""

    def __init__(
        self,
        bot: Bot,
        user_directory: UserDirectory,
        repository: MessageRepository,
        email_sender: EmailSender,  # 1
        user_prefs: UserPreferences,  # 1
    ):
        self._bot = bot
        self._user_directory = user_directory
        self._repository = repository
        self._email_sender = email_sender
        self._user_prefs = user_prefs

    def send_messages(self) -> None:
        """Send all messages that need to be sent"""
        messages_to_be_sent = self._repository.get_messages_to_be_sent()
        for message_to_be_sent in messages_to_be_sent:
            user_id = self._user_directory.get_account(message_to_be_sent.email)
            self._bot.send_private_message(user_id, message_to_be_sent.body_in_markdown)
            if self._user_prefs.send_via_email(message_to_be_sent.email):  # 2
                self._email_sender.send_message(message_to_be_sent)
            # 메시지를 보낸 것으로 표시한다
            message_to_be_sent.mark_as_sent()

이제 추가로, 이메일을 보내고싶어 EmailSender 추가했고, 사용자가 수신 가능한지 체크하기 위해 UserPreferences 추가했다.
이메일 발송 관련 로직이나 사용자 선호 설정이 변경되면 MessageSender도 변경해야 하며, 이는 SRP(Single Responsibility Principle)를 위반한 셈이다.

class MessageBot:
    """Handles sending messages through a bot interface"""

    def __init__(
        self,
        bot: Bot,
        user_directory: UserDirectory,
    ):
        self._bot = bot
        self._user_directory = user_directory

    def send(self, msg: Message) -> None:  # 2
        """Send a message to a user via the bot"""
        user_id = self._user_directory.get_account(msg.email)
        self._bot.send_private_message(user_id, msg.body_in_markdown)

Bot과 UserDirectory를 묶어 새로운 클래스로 만들어서 분리한다면?!
이렇게 설계를 변경하면, MessageSender는 더 이상 모든 세부 구현에 직접 관여하지 않고, 간접 결합된 협력자(MessageBot)를 통해 메시지를 발송하게 된다. 최종적으로 리팩터링된 MessageSender는 다음과 같다:

class MessageSender:
    """
    Service for sending messages via multiple channels, utilizing a MessageBot.
    """

    def __init__(
        self,
        message_bot: MessageBot,
        repository: MessageRepository,
        email_sender: EmailSender,  # 1
        user_prefs: UserPreferences,  # 1
    ):
        self._message_bot = message_bot
        self._repository = repository
        self._email_sender = email_sender
        self._user_prefs = user_prefs

    def send_messages(self) -> None:
        """Send all messages that need to be sent."""
        messages_to_be_sent = self._repository.get_messages_to_be_sent()
        for message_to_be_sent in messages_to_be_sent:
            self._message_bot.send(message_to_be_sent)
            if self._user_prefs.send_via_email(message_to_be_sent.email):  # 2
                self._email_sender.send_message(message_to_be_sent)
            # 메시지를 보낸 것으로 표시한다
            message_to_be_sent.mark_as_sent()

의존성이 간결해지고, 각 클래스는 자신의 책임에 충실해진다. 이 구조는 테스트 가능성과 변경 대응력을 높여주는 좋은 예시다.

[ 의존성을 주입하라(의존성 주입을 사용하라) ]

의존성 주입(DI)은 객체가 협력자(다른 객체)를 직접 생성하지 않고, 외부로부터 주입받는 설계 기법이다. 이를 통해 디자인의 유연성과 테스트의 용이성을 동시에 얻을 수 있다.

과거에는 객체 생성 비용이나 성능 문제로 인해 DI를 꺼리는 경우도 있었지만, 이제는 런타임 객체 관리 및 메모리 관리 기술이 발전했기 때문에, 주입 가능한 구조를 채택하는 것이 더 나은 선택이 되었다.

1. 상태를 변경하는 작업에 정적 메서드를 사용하지 마라

정적 메서드는 런타임 시점에 대체하거나 모킹(mocking)하기가 어렵기 때문에 테스트가 불가능한 구조가 된다. 상태 변경을 수반하는 로직일수록 정적 메서드를 피하고, 명시적인 객체와 메서드를 통해 의존성을 표현해야 한다.

2. 항상 협력자를 주입하라: 그 외에는 원하는 대로 하라

위 예시에서 MessageSender는 Bot, UserDirectory, MessageRepository를 사용한다. 이들을 직접 생성하지 않고 외부에서 주입받으면, 다양한 구현체(Mock, Stub, Spy 등)로 교체가 가능해진다.
즉, 협력자를 명시적으로 받고, 사용자는 인터페이스나 추상 타입에 의존하도록 설계하라.

3. 클래스와 의존성을 함께 생성하는 전략

복잡한 의존 그래프를 가진 시스템에서는 객체 생성 시점에 많은 고민이 필요하다. 이를 효율적으로 처리하기 위해선 DI 컨테이너나 프레임워크(SPRING, Google Guice 등)를 사용하는 것이 유리하다.
현대적인 프레임워크는 대부분 DI 설계를 기본 전제로 두고 있기 때문에, 이런 흐름을 따르는 것이 유지보수와 확장성 면에서 안정적인 선택이다.

5장 추상화 잘 디자인하기

에츠허르 데이크스트라 왈, *"추상화는 모호하다는 것과 본질적으로 다르다. 추상화의 목적은 모호해지는 것이 아니라, 절대적으로 정확한 새로운 의미 수준을 만드는 것"* (The purpose of abstraction is not to be vague, but to create a new semantic level in which one can be absolutely precise)

이 말은 이 장 전체의 핵심을 가장 명확히 설명해준다. 추상화란 복잡한 구현을 감추는 것이 아니라, 의미를 더 정확히 드러내기 위해 불필요한 세부사항을 제거하는 것이다. 즉, 본질에 집중하고, 비본질을 과감히 덜어내는 행위가 추상화의 본질이다.

추상화는 개념, 기능, 프로세스를 클라이언트가 내부 메커니즘을 몰라도 이해 가능한 방식으로 설명한다.
본질적인 특성에 집중하고, 구현은 신경 쓰지 않으며 신경 쓸 필요도 없다.

[ 추상화와 확장 지점을 디자인하라 ]

추상화는 단순히 복잡성을 숨기는 도구가 아니라, 변화에 유연하게 대응할 수 있도록 구조를 여유 있게 설계하는 기반이 된다. 즉, 새로운 기능을 쉽게 추가하거나 기존 기능을 확장하거나 변경할 수 있도록 만든다.

1. 추상화의 필요성 식별하기

추상화는 멋있어 보인다고 도입해서는 안 된다. 불필요한 추상화는 오히려 복잡도를 증가시킬 뿐이다. 추상화를 적용하기 전에는 반드시 ‘그럴만한 이유’가 있어야 한다.

✔ 대표적 원칙: 추상화는 변화의 방향성이 명확할 때만 도입하라.
참고: Robert C. Martin (Clean Architecture)에서는 “변경의 이유가 둘 이상일 때 분리하라”는 단일 책임 원칙(SRP) 아래, 변경 가능성이 존재하는 지점에 추상화를 도입해야 한다고 강조한다. 이처럼 추상화는 목적 있는 복잡성이다.

2. 확장 지점 디자인하기

확장 지점을 설계할 때는 단순히 인터페이스를 나누는 것 이상을 고려해야 한다.

향후 어떤 부분이 가장 자주 변경될 것인가?
어떤 방식으로 확장될 가능성이 높은가?

이런 질문에 대한 답을 바탕으로 유연한 구조를 미리 설계해야 한다.
잘 설계된 확장 지점은 이후 변화에 따라 조건문이 아니라 클래스 추가로 대응할 수 있게 만들어준다.

3. 좋은 추상화의 속성

좋은 추상화는 무엇(What)과 어떻게(How)를 분리 한다.

클라이언트는 “무엇을 할 수 있는가”만 알면 된다.
“어떻게 수행되는가”는 감춰져도 무방하다.

4. 추상화에서 배워라

추상화는 한 번에 완벽히 만드는 것이 아니다. 점진적으로 발전시키며 리팩터링을 반복해야 한다. 꾸준함이 결국 좋은 추상화로 이어진다.

5. 추상화에 대해 배워라

추상화를 더 잘 다루고 싶다면, 디자인 패턴은 훌륭한 교과서다.

GoF 디자인 패턴은 다양한 추상화 사례를 담고 있다.
특히 전략, 상태, 책임 연쇄, 데코레이터, 템플릿 메서드, 커맨드 패턴 등은 행위의 변화와 확장을 위한 추상화 관점에서 매우 유용하다.
또한, 오픈 소스 프레임워크는 실전에서 적용된 추상화의 정수다. 그 패턴과 모듈화를 분석하며 배우는 것이 가장 효과적이다.

6. 추상화와 결합

추상화와 결합도는 함께 고려되어야 한다.

추상화는 결합도를 낮추고 유연성을 높이는 도구이지만, 잘못하면 불필요한 의존성과 인터페이스 남용으로 결합이 오히려 증가할 수도 있다.
즉, "적절한 추상화 + 낮은 결합도"가 목표다.

[ 예제: 직원에게 배지 수여하기 ]

(python/ch5/v1/badge_giver.py 의 BadgeGiver)

class BadgeGiver:
    """Assigns badges to employees based on their training history"""

    def give(self, employee: Employee) -> None:  # 1
        """Give badges to the employee"""
        self._per_training(employee)
        self._per_quantity(employee)

    def _per_training(self, employee: Employee) -> None:
        """Assigns badges based on specific training completions"""
        trainings_taken: TrainingsTaken = employee.trainings_taken
        # 품질 관련 교육을 받은 경우 배지를 받는다     # 2
        if trainings_taken.has("TESTING") and trainings_taken.has("CODE QUALITY"):
            self._assign(employee, Badge.QUALITY_HERO)
        # 보안 관련 교육을 모두 들으면 배지를 받는다
        if trainings_taken.has("SECURITY 101") and trainings_taken.has("SECURITY FOR MOBILE DEVS"):
            self._assign(employee, Badge.SECURITY_COP)
        # ... 다른 배치 수여 규칙들

    def _per_quantity(self, employee: Employee) -> None:  # 3
        """Assigns badges based on the quantity of trainings completed"""
        trainings_taken: TrainingsTaken = employee.trainings_taken
        if trainings_taken.total_trainings() >= 5:
            self._assign(employee, Badge.FIVE_TRAININGS)
        if trainings_taken.total_trainings() >= 10:
            self._assign(employee, Badge.TEN_TRAININGS)
        if trainings_taken.trainings_in_past_3_months() >= 3:
            self._assign(employee, Badge.ON_FIRE)

    def _assign(self, employee: Employee, badge: Badge) -> None:
        """Assign a badge to the employee"""
        employee.win_badge(badge)

Employee 에게 다양한 규칙에 따라 뱃지를 수여하는 class
로직이 명확히 나뉘지 않아 변경에 취약하며, 로직 복잡성이 커지면 메서드 내부가 조건문으로 난잡해질 가능성 존재. 일단 class 단위를 쪼개보자.

(python/ch5/v2/badge_giver.py 파일 내부 class 들)

class BadgeGiver:
    """Assigns badges to employees based on their training history"""

    def give(self, employee: Employee) -> None:  # 1
        """Give badges to the employee by applying different badge rules"""
        BadgesForTraining().give(employee)
        BadgesForQuantity().give(employee)


class BadgesForTraining:
    """Applies badge rules related to specific training completions"""

    def give(self, employee: Employee) -> None:
        """Assigns badges based on specific training completions"""
        trainings_taken: TrainingsTaken = employee.trainings_taken
        ... 생략 ...


class BadgesForQuantity:
    """Applies badge rules related to the quantity of trainings completed"""

    def give(self, employee: Employee) -> None:  # 3
        ... 생략 ...

로직이 명확하게 나뉘며, 각 책임 클래스에서의 단위 변경이 쉬움
하지만 여전히 로직이 많아지고 규칙이 다양해지면 복잡도는 상승

class Badge(Enum):
    """Enum representing different types of badges"""

    SECURITY_COP = "SECURITY_COP"
    FIVE_TRAININGS = "FIVE_TRAININGS"
    TEN_TRAININGS = "TEN_TRAININGS"
    ON_FIRE = "ON_FIRE"
    QUALITY_HERO = "QUALITY_HERO"

class BadgeRule:
    """Interface for a badge rule"""

    def give(self, employee: Employee) -> bool:
        """Determines if the badge should be given to the employee"""
        pass

    def badge_to_give(self) -> Badge:
        """Returns the badge associated with this rule"""
        pass


class QualityHero(BadgeRule):
    """Badge rule for Quality Hero badge"""

    def give(self, employee: Employee) -> bool:
        trainings_taken: TrainingsTaken = employee.trainings_taken
        return trainings_taken.has("TESTING") and trainings_taken.has("CODE QUALITY")

    def badge_to_give(self) -> Badge:
        return Badge.QUALITY_HERO


class SecurityCop(BadgeRule):
    """Badge rule for Security Cop badge"""

    def give(self, employee: Employee) -> bool:
        trainings_taken: TrainingsTaken = employee.trainings_taken
        return trainings_taken.has("SECURITY 101") and trainings_taken.has("SECURITY FOR MOBILE DEVS")

    def badge_to_give(self) -> Badge:
        return Badge.SECURITY_COP


class FiveTrainings(BadgeRule):
    """Badge rule for Five Trainings badge"""

    def give(self, employee: Employee) -> bool:
        trainings_taken: TrainingsTaken = employee.trainings_taken
        return trainings_taken.total_trainings() >= 5

    def badge_to_give(self) -> Badge:
        return Badge.FIVE_TRAININGS


class TenTrainings(BadgeRule):
    """Badge rule for Ten Trainings badge"""

    def give(self, employee: Employee) -> bool:
        trainings_taken: TrainingsTaken = employee.trainings_taken
        return trainings_taken.total_trainings() >= 10

    def badge_to_give(self) -> Badge:
        return Badge.TEN_TRAININGS


class OnFire(BadgeRule):
    """Badge rule for On Fire badge"""

    def give(self, employee: Employee) -> bool:
        trainings_taken: TrainingsTaken = employee.trainings_taken
        return trainings_taken.trainings_in_past_3_months() >= 3

    def badge_to_give(self) -> Badge:
        return Badge.ON_FIRE

BadgeRule 을 추상화 해서 (python interface 없기에 ABC 활용)
ENUM 도 활용했고, 결국 BadgeGiver 자체는 BadgeRule 에 따라 give 가 true 라면 badge_to_give 로 수여만 하면 된다.


class BadgeGiver:
    """Assigns badges to employees based on a list of rules"""

    def __init__(self, rules: List[BadgeRule]):  # 1
        self._rules = rules

    def give(self, employee: Employee) -> None:
        """Applies each rule to the employee and assigns badges accordingly"""
        for rule in self._rules:  # 2
            if rule.give(employee):
                employee.win_badge(rule.badge_to_give())

BadgeGiver 는 오직 룰을 적용하는 컨트롤러 역할만 수행하며 OCP (Open-Closed Principle) 를 만족시킴!

이 다음 BadgesForTraining 자체를 팩토리 패턴과 BadgeRule 인터페이스 상속을 구현한 예제가 이어짐. 이는 책에서 확인하는 것을 추천.

[ 단순한 추상화를 선호하라 ]

1. 경험적 규칙

추상화가 꼭 필요한가? → 단순한 것이 항상 낫다.
추상화의 필요성이 명백하게 드러나는가? → 이쯤 되면 고려해야 한다.
좋은 추상화가 필요하게 되리라는 걸 안다면? → 처음부터 추상화를 두려워 말라.

2. 단순한 것이 항상 더 낫다

추상화는 도구이지 목표가 아니다.
단순함을 추구하다 보면 불필요한 추상화를 피하고, 꼭 필요한 순간에만 의미 있는 추상화를 만들 수 있다.
if 구문으로 가득찬 코드, 클리스 등. 더욱이 "잘못된 추상화 보다 중복이 더 저렴하다" 라고 말한 사람도 있다(루비 개발자, 샌디 메츠). 하지만 중복은 잘된 추상화 보다 비용이 더 많이 든다는 점도 아주 중요한 시사점이다.

3. 이쯤 되면 추상화를 고려해야 한다

같은 클래스를 계속 반복적으로 수정하는가?
클래스가 계속 커지는 가?
변화를 구현하기 위해 if 조건문이 추가 되는가?
기존 비즈니스 규칙을 시스템의 다른 부분에 결합시키는 과정이 어거지로 이어붙이는 것 같은가?

4. 처음부터 추상화를 모델링하는 것을 두려워하지 마라

추상화를 사후에 도입하려 하면 더 큰 비용이 든다. 처음부터 확장성을 고려한 모델링은 오히려 단순함을 보장해준다.
단, 미리 설계하되, 지금 필요한 만큼만 구현하라. 추상화를 위한 추상화는 독이다.

6장 외부 의존성과 인프라 다루기

[ 도메인 코드와 인프라를 분리하라 ]

인프라와 도메인 코드를 분리하는 이유는 단순히 아키텍처적 우아함을 위한 것이 아니다. 실제로 외부의 세부 사항이 시스템 전반에 영향을 미치지 않도록 하기 위해, 그리고 테스트 가능성을 높이고 유지보수성을 확보하기 위해 반드시 필요하다.

외부 세부 사항은 테스트를 어렵게 한다.
예컨대 AWS SDK, 타사 데이터베이스 클라이언트처럼 외부와 직접 통신하는 코드가 프로젝트 곳곳에 퍼져 있다면, 테스트 시에는 이를 일일이 mocking 해야 하며, 환경이 조금만 바뀌어도 문제가 생길 수 있다.
캡슐화 없이는 외부 라이브러리의 변경에도 영향을 받는다.
외부 API는 버전이 올라가며 추상화가 바뀌고, 리턴 구조가 달라질 수 있다. 이 변화가 전파되지 않도록 하려면 중간에 캡슐화 계층이 필요하다.
인프라 코드는 저수준이다.
DB, 메시지 큐, 외부 API 등은 시스템 아키텍처의 하부를 구성하며, 이들이 변경되었을 때 영향도를 최소화하려면 추상화와 분리가 선행되어야 한다.

잘 된 추상화는 인프라 세부 사항을 감추고, 시스템의 다른 부분이 변경 없이 그대로 동작할 수 있도록 해준다. 그러나 DBMS → SQS 로 바뀌는 수준의 변화까지 무리 없이 감추기란 어렵다.

결국 어느 수준까지 분리할 것인가, 어떤 방식으로 분리할 것인가에 따라 트레이드오프가 필연적으로 존재한다.

1. 인터페이스가 필요한가?

다음 조건 중 하나라도 해당된다면 인터페이스를 도입하자!

동일 인프라에 대해 여러 구현이 예상될 경우
예: EmployeeRepository를 RDB, NoSQL, Mock 등 다양한 방식으로 구현
인프라 구조에 대한 지식이 아직 부족할 경우
추상적인 인터페이스를 만들고 구체 구현은 나중에 교체 가능
여러 군데에서 동일 인프라를 사용하는데, 공통화되지 않은 경우
인터페이스를 도입하면 무거운 클래스 대신 가벼운 추상 계층으로 관리 가능

하지만 주의할 점은, 기저 인프라가 복잡할수록 세부사항이 누출되기 쉽고, 이를 막는 것도 쉽지 않다는 점이다.

2. 코드에서는 세부 사항을 숨기고, 개발자에게는 숨기지 마라

외부에 공개되는 코드 수준에서는 인프라의 디테일을 철저히 숨겨야 한다. 하지만 팀 내부나 문서에서는 그 디테일을 명확히 공유하고, 숨기지 않아야 한다. 그래야 변경 시 충돌과 오해가 줄어든다.

즉 개발자에게 까지 제발 숨기지 말라는 것이다. 이게 문서화를 통해서든, 가이드를 통해서든 말이다.

3. 인프라 변경하기: 괜한 걱정일까, 실제로 일어날까?

아주 솔직하게 DBMS 종류가 바뀌는 사건들은 마냥 흔한 일은 아니다. 하지만 인프라 변경은 현실이다. 단일 서버에서 RDS로, MySQL에서 Postgres로, 자체 이메일 시스템에서 SES로… 등의 변화는 "생각 보다 매우 빈번" 하다.

더욱이 서비스가 성장한다면 말이다. "변경은 없을 것이다"는 단순한 낙관주의다. 따라서 변경 가능성을 가정하고 구조를 짜야 한다.

4. 예제: 데이터베이스 접근과 메시지 봇

class EmployeeRepository(ABC):
    """Abstract repository interface for Employee operations"""

    @abstractmethod
    def find_by_email(self, email: str) -> Optional[Employee]:
        """Find employee by email address"""
        pass

    @abstractmethod
    def save(self, employee: Employee) -> None:
        """Save employee to repository"""
        pass

    @abstractmethod
    def update(self, employee: Employee) -> None:
        """Update existing employee in repository"""
        pass


class HibernateEmployeeRepository(EmployeeRepository):
    """Employee repository implementation simulating Hibernate interaction"""

    def __init__(self, session: MockSession):
        self._cache: Cache[Employee, str] = Cache()
        self._session = session

    def find_by_id(self, id_: int) -> Optional[Employee]:
        """Find an employee by their ID"""
        return self._session.find(Employee, id_)

    def find_by_last_name(self, last_name: str) -> Set[Employee]:  # 2
        """Find employees by their last name, using cache"""
        if not self._cache.contains(last_name):
            # Simulate database query
            result_list = self._session.create_query(
                "from Employee e where e.lastName = :lastName", Employee
            ).set_parameter(":lastName", last_name).get_result_list()
            self._cache.add_all(last_name, set(result_list))
        return self._cache.get(last_name)

    def find_by_email(self, email: str) -> Optional[Employee]:
        """Find an employee by their email address"""
        return self._session.create_query(
            "from Employee e where e.email = :email", Employee
        ).set_parameter(":email", email).get_single_result_or_null()

    def save(self, employee: Employee) -> None:
        """Save a new employee"""
        self._session.persist(employee)

    def update(self, employee: Employee) -> None:
        """Update an existing employee"""
        self._session.merge(employee)

이 예제는 EmployeeRepository 라는 추상 계층을 통해 도메인과 인프라를 분리하고 있다.
특정 로직에만 cache 를 추가하고 싶은 경우, HibernateEmployeeRepository 내에서 _cache 필드만 추가(활용)하면 된다.
사실 요즘 완벽한 도메인 분리는 못해도 무조건 layered pattern 까지는 지키려고 노력하는데, 이도 비슷한 궤

[ 인프라를 최대한 활용하라 ]

요즘 당연하게 데이터 영속성을 위해 DBMS 를 사용하고, API를 효율적으로 만들기 위해 웹F/W 에 의존한다. 그리고 최근 몇십 년 동안 폭발적으로 발전해왔다. *근데 class 디자인에 맞지 않는다는 이유로 기능 무시하는 것은 아까운 일* 이다.

1. 디자인을 망가뜨리지 않도록 최선을 다하라

디자인에서 모든 선택에 트레이드오프 관계가 있다. 해당 예제 등록 취소하기는 에그리게이트를 우회하려는 것에 대해 다룬다.
특히 cancel 이라는 method 는 오퍼링 내의 모든 등록 내용 확인하는 로직이 있었기 때문 순회를 하지말고, 여기서 DBMS 를 활용해 직접 등록 정보를 다 가져와서 cancel 처리하게 하면 됨. (이를 리펙토링 하는 과정을 직접 책 보면서 따라가는 것 추천.)

[ 자신이 소유한 것에만 의존하라 ]

외부 라이브러리, SDK 등을 직접 사용하는 대신, 반드시 내부 래퍼 또는 어댑터를 두자. 이를 통해 다음과 같은 장점이 생긴다.

외부 변경에 대한 완충 작용
도메인 코드에서 의미 있는 인터페이스 제공
테스트 용이성

결과적으로 서드파티 의존성이 코드 전반에 퍼지는 것을 방지 한다. 통제하기 어려운 것이 내 손안에 들어온다!

1. 프레임워크와 싸우지 마라

(개인적으로 매우 와닿았음 ㅋㅋ)

모든 의존성과 완전한 분리는 실현 불가능한 목표 이다. 오히려 완전한 분리가 코드 복잡도의 폭발적 증가 를 낳을 수 있다.
즉, 프레임워크를 무시하거나 거스르는 것이 곧 좋은 아키텍처는 아니다.
도메인과 프레임워크는 분리하되, 프레임워크의 강점을 적절히 활용하는 타협이 필요하다.

2. 간접 누출에 주의하라

ORM 생각해보자. 다들 object & orm method 의 모든 부분이 raw query 로 어떻게 사용되는지 완벽하게 파악하고 사용하는가?
하지만 ORM의 기능을 무비판적으로 사용하면 성능이나 트랜잭션 이슈가 발생할 수 있다.
추상화의 깊이를 항상 점검하고, 불필요한 간접 누출을 경계하자.

[ 저수준 인프라 오류를 고수준 도메인 오류로 캡슐화하라 ]

저수준 인프라 라이브러리는 다음과 같은 문제를 가진다.

고유한 error code 체계
raw exception 노출
메시지 구조가 도메인에 맞지 않음

따라서 다음과 같이 바꿔야 한다

외부 오류 → 의미 있는 도메인 오류 (EmailAlreadyRegisteredError, DataConsistencyError 등)
이 과정에서 도메인 계층은 외부 시스템의 오류를 전혀 알 필요가 없어진다.

애플리케이션은 이를 기반으로 UX 수준에서 적절한 피드백을 구성 가능해진다!

7장 모듈화 달성하기

6장까지 다뤘던 단순성, 일관성 유지, 좋은 추상화, 확장 지점, 인프라 세부 사항의 캡슐화와 격리 는 사실상 모두 모듈화라는 큰 주제 아래 자연스럽게 수렴된다. 이 장은 그러한 원칙들을 모듈 수준에서 구현하고 지켜내는 방법에 대한 이야기다.

캡슐화의 확장 우리가 데이터를 클래스 내부에 감추는 것처럼, 모듈 또한 연관된 기능들을 내부에 감추고 외부에는 필요한 것만 드러내야 한다. 이 때의 '모듈'은 단순한 코드 묶음이 아니라, 구조적 경계이자, 소프트웨어의 관리 단위다.
복잡한 기능 위에 단순한 인터페이스 제공 좋은 모듈은 클라이언트 입장에서 쓰기 쉬워야 한다. 복잡한 로직은 내부에 숨기고, 이를 감싸는 단순하고 명확한 API만 노출해야 한다. 이는 단순한 함수 수준이 아니라, 모듈 전체 수준에서도 동일하게 적용된다.
내부 변경이 외부에 영향을 주지 않도록 좋은 모듈은 내부 세부 사항이 변경되더라도, 이를 사용하는 클라이언트 코드가 변경되지 않아도 되도록 설계되어야 한다. 즉, 모듈은 클라이언트를 보호하는 방패가 되어야 한다.
안정적이고 하위 호환 가능한 인터페이스 모듈의 가장 핵심은 일관된 인터페이스 설계다. 이 인터페이스가 깨질 경우, 모듈을 사용하는 수많은 클라이언트가 일제히 영향을 받는다. 따라서 명확하고 지속 가능한 통신 방식이 필수적이다.
확장 지점의 설계 시스템이 커질수록 기능 추가와 변형이 요구된다. 이때 모듈은 유연한 확장을 허용하되, 그 방식은 일관되고 예측 가능해야 한다. 즉, 확장 지점은 있어야 하지만, 아무나 아무 데나 꽂을 수 있게 해서는 안 된다.
모듈 간 세부 사항 비공개화 모듈은 자신의 내부를 감추고, 다른 모듈의 내부를 알지 않아야 한다. 그래야만 모듈 간 결합도를 줄일 수 있으며, 독립적으로 변경과 진화를 꾀할 수 있다.
클라이언트는 누출된 세부 사항에 의존하지 않도록 주의 만약 어떤 모듈이 내부 구현을 의도치 않게 노출한다면, 이를 사용하는 측에서 그 부분에 의존하게 될 수 있다. 이 의존성은 이후 변경 시 ‘모듈의 구현 변경이 전파되는 리스크’를 낳는다.
모듈의 명확한 소유권과 규칙 여러 팀이 함께 시스템을 만들 때, 모듈이 분리되어 있지 않으면 갈등이 생기기 쉽다. 어떤 코드에 누가 책임을 질지 모호해지기 때문이다. 명확한 소유권과 규칙이 있는 모듈은 조직적 커뮤니케이션 비용까지 줄여준다.

사견을 덧붙이자면, 모듈화는 어떤 기법이라기보다는 앞선 장들의 내용을 충분히 소화한 결과물에 가깝다. 단순히 "모듈을 설계하자"는 의도를 넘어서, 좋은 코드와 아키텍처를 고민하다 보면 결과적으로 자연스럽게 형성되는 단위가 모듈이라는 생각이다.

또한, 나의 경우 모듈화를 할 때 마치 내가 오픈소스를 만들고 있다는 상상을 해보는 것도 꽤 도움이 되었다. 일종의 라이브러리나 SDK를 만든다고 생각하고, 사용자 입장에서 인터페이스를 설계하다 보면 오히려 더 집중하게 되고, 실용적인 결과물을 만들 수 있게 된다.

8장 실용적인 접근법

✔ 실용적으로 접근하되, 딱 필요한 만큼만

완벽한 설계보다는 지금 필요한 만큼의 단순한 해결책이 우선이다. 미래를 대비한 과도한 설계는 실제로 쓰이지도 않을 가능성이 높고, 오히려 현재를 더 복잡하게 만들 수 있다. 실용성은 포기하지 않는 선에서 절제된 추상화와 설계가 요구된다.

✔ 과감하게 리팩터링하되, 단 작은 단위로 나눠서

리팩터링은 주저해서는 안 되는 작업이지만, 동시에 무작정 갈아엎는 식이어서는 안 된다. 이 장에서는 리팩터링을 '과감하게' 하되, 안전하게 작은 단위로 쪼개서 실행할 것을 강조한다. 시스템 전체를 한 번에 뒤엎는 방식이 아니라, 변화 가능성을 감지하고 작은 확신들로부터 개선을 시작하는 태도가 중요하다.

✔ 코드가 완벽하지 않다는 사실을 받아들여라

모든 코드가 완벽할 수는 없으며, 완벽을 추구하다가 실제 문제 해결이 늦어지는 일은 피해야 한다. 때로는 어설픈 코드라도 현재 문제를 해결하는 것이 더 가치 있을 수 있다. 물론 그 임시방편이 '영원한 기술 부채'가 되지 않도록, 지속적으로 개선할 수 있는 여지를 남겨두는 태도가 필요하다.

✔ 재디자인을 고려하라

지속적인 기능 추가와 요구사항 변화 속에서, 기존 구조가 더 이상 적절하지 않게 되는 시점이 온다. 그럴 때는 과감하게 재디자인을 검토해야 한다. 이는 리팩터링보다 큰 결정이지만, 때로는 시스템의 생명력을 연장시키는 유일한 선택이 되기도 한다. 단, 재디자인은 개인의 열정이 아니라, 정량적이고 조직적인 판단에 기반해야 한다.

✔ 여러분은 주니어 개발자들에 대한 책임이 있다

시스템의 구조와 코드는 단지 기계가 해석할 수 있도록 짜는 것이 아니라, 함께 일하는 사람들—특히 주니어 개발자—가 이해할 수 있도록 짜야 한다. 좋은 설계는 곧 좋은 학습 자료이자 멘토링 수단이 된다. 코드가 혼란스럽고 복잡할수록, 팀 전체의 성장 가능성은 낮아진다. 경험 많은 개발자일수록, 이 책임을 자각해야 한다.

python - 동시성 처리, with 구문과 context manager

Fri, 11 Jul 2025 08:38:33 GMT

[ 글의 목적: python 에서 context manager 가 필요한 상황과 원리, with 에 대한 deep dive, python 3.13 기준!! ]

Python context manager

python 에는 with 구문이 있다. (사실 2005년 PEP 343 부터 있었던 고인물). 동시성 얘기와 context manager 얘기하는데 왜 with 냐? 사실 이 질문은.. 고민이 역전된 질문이다. 정확히 말하면 with는 context manager를 사용하기 위한 문법이기때문!

사실 batch 중심 서비스에서 celery 쓰긴 과해서, 기존 운영 DBMS 에 추상화된 task model 로 단일 python runtime process 띄워서 처리하는데, 이 "task" 객체 모델링하다가 삘받아서 쓰는 정리글인건 비밀이다.

1. 동시성 처리

이제는 멀티코어 프로세서가 일반화되고 I/O 집약적인 작업을 효율적으로 처리하기 위해 동시성 프로그래밍이 거의 기본 개념이 되어버렸다. (왜 동시성 처리가 필요한지는 이제 너무 식상한 얘기가 되어버린 것 같은..)

이제 멀티스레딩, 멀티프로세싱뿐만 아니라, 단일 스레드 내에서도 이벤트 루프와 코루틴을 활용해 동시성을 극대화할 수 있다. (python 코루틴(coroutine) - 동시성과 병렬성, 동기와 비동기 작업, blocking과 non-blocking 그리고 코루틴 / javascript - 기본 동작 원리와 v8 js 엔진 참조)

근데 with 랑 context manager 얘기하면서 왜 동시성 얘기 부터 하느냐? 사실 동시성 프로그래밍에서 *가장 까다로운 문제는 바로 "공유 리소스 관리(Shared Resource Management)"* 이기 때문이다.

즉 여러 스레드나 코루틴이 파일, 데이터베이스 커넥션, 네트워크 소켓과 같은 공유 리소스에 동시에 접근할 때, 접근 순서를 제어하고 사용 후 리소스를 안정적으로 해제하지 않으면 경쟁 상태(Race Condition), 데드락(Deadlock), 리소스 누수(Resource Leak) 등 심각한 문제로 이어질 수 있기 때문이다.

import threading

lock = threading.Lock()
shared_resource = 0

def worker():
    global shared_resource
    # with 구문이 lock의 획득(acquire)과 해제(release)를 보장합니다.
    with lock:
        # 이 블록은 한 번에 하나의 스레드만 실행할 수 있는 임계 영역(Critical Section)입니다.
        data = shared_resource
        data += 1
        # 다른 스레드가 끼어들 수 있는 잠재적 위험 구간
        time.sleep(0.1) 
        shared_resource = data

# ... 스레드 생성 및 실행 ...


# 또는 장고에서 
from django.db import transaction

def my_view():
    with transaction.atomic():
        # 이 블록 안의 작업이 하나의 트랜잭션으로 묶임
        do_something()
        do_something_else()

python 하면 위 코드는 식상할 정도로 뭔가 많이 본 형태다. 누군가 "왜 with 를 쓰나요?" 라고 한다면, "lock 을 저 block 에서만 사용하고 빠빠이 하려고요!" 라고만 답하게 된다면, 조금 더 아래를 내려보자!

1) 동시성 처리에서 Context Manager가 필수적인 이유

결론부터 말하면, 안전한 리소스의 '획득'과 '해제'를 보장하기 때문 이다.

동시성 환경에서는 여러 실행 흐름이 언제든지 CPU를 점유하고 리소스에 접근할 수 있다. 이때 리소스 접근을 제어하는 '락(Lock)'을 획득하고 사용 후 반드시 '해제'해야 한다.

만약 락을 해제하는 코드가 실행되기 전에 예외가 발생한다면? 해당 락은 영원히 해제되지 않아 다른 스레드들은 무한정 대기하는 데드락 상태에 빠지게 된다.

Context Manager 는 with 블록에 진입할 때 리소스를 획득하고, 블록을 빠져나올 때 예외 발생 여부와 관계없이 반드시 리소스를 해제하는 작업을 수행하도록 보장한다. 이것이 동시성 프로그래밍에서 Context Manager가 필수적인 이유다.

with 없는 lock 획득 예시

import threading

lock = threading.Lock()

def unsafe_operation():
    lock.acquire()  # 락 획득
    # ... 공유 리소스 작업 ...
    if some_error_condition:
        raise ValueError("오류 발생!")
    lock.release()  # 예외 발생 시 이 코드는 절대 실행되지 않음!

위 문제는 try ... finally 로 해결 가능

# 조금 나아진 예시: try...finally 사용
def slightly_better_operation():
    lock.acquire()
    try:
        # ... 공유 리소스 작업 ...
        if some_error_condition:
            raise ValueError("오류 발생!")
    finally:
        lock.release() # finally 블록으로 해제를 보장

이 code 형태는 java 에서도 매우 유사하다.
하지만 위 예시는 lock 이 필요한 부분에서 코드 자체가 겁나 지저분해진다는 한계가 있다. 그렇다고 매번 try ... finally 구문을 추상화 해서 사용할 수 도 없는 것.. (자주 바뀌게 되어있음...)

이걸 with 로 해결한 파이써닉한 처음 예제!

import threading

lock = threading.Lock()

def safe_operation():
    with lock: # 진입 시 lock.acquire(), 탈출 시 lock.release() 자동 호출
        # ... 공유 리소스 작업 ...
        if some_error_condition:
            raise ValueError("오류 발생!")
    # with 블록이 끝나면 예외가 발생해도 락은 안전하게 해제됨

with 를 쓰는게 확실하게 깔끔하다. (물론 depth 가 깊어진다는 trade-off도 있다.)
그러면 이 with 가 이걸 어떻게 해결한다는 건가? 어떻게 진입 시 lock.acquire(), 탈출 시 lock.release() 자동 호출을 한다는 것이가!?!?

2) 아니 그래서 with 가 뭔 상관인데유

with, 걍 resource leak 방지 하려고 한거 아녀유?

매우 맞다. 근데 이는 "with" 의 특성때문에 이 목적이 가능한거다!

# 리소스 누수 예시
def leak_file_descriptors():
    # 이 함수를 반복 호출하면 결국 에러 발생
    f = open('temp.txt', 'w')
    f.write('leak')
    # f.close()를 의도적으로 누락

(위 코드) 파일을 열고 close() 를 호출하지 않는 코드가 반복 실행되면 운영체제가 프로세스에 할당한 파일 디스크립터(File Descriptor) 개수 제한에 도달 해 "Too many open files" 오류가 발생한다. with 는 이걸 원천적으로 막아준다.

# 리소스 누수 방지
def no_leak_example():
    with open('temp.txt', 'w') as f:
        f.write('safe')
    # with 블록이 끝나면 f.close()가 자동으로 호출됨

with 는 컨텍스트 관리 프로토콜(Context Management Protocol) 을 따르는 객체와 함께 동작한다.

with 는 "Context Manager"를 위한 "Syntactic Sugar" 이다. contextlib — with 문 컨텍스트를 위한 유틸리티
쉽게 말하면 __enter__() 와 __exit__() 메소드를 구현한 객체로 *with 문 사용 시 자동으로 호출되는 메서드들이다.* ~~(만약 던더메서드, 매직메서드를 모른다면 이 글은 도움이 못된다.)~~

__enter__(self) : with 블록에 진입할 때 호출된다. 리소스를 획득하고 설정하는 역할을 하며, as 키워드로 변수에 할당할 값을 반환한다.
__exit__(self, exc_type, exc_value, traceback) : with 블록을 "빠져나올 때" 반드시 호출된다. 리소스를 해제하는 역할을 한다. 만약 블록이 예외 없이 정상 종료되었다면 세 인자(exc_type, exc_value, traceback)는 모두 None이 된다. 예외가 발생했다면 해당 예외 정보가 전달된다. __exit__ 메서드가 True 를 반환하면 예외가 전파되지 않고 억제된다.

with 의 바이트 코드

import dis

def my_func():
    with open('file.txt', 'w') as f:
        f.write('hello')

dis.dis(my_func)

   3           RESUME                   0

   4           LOAD_GLOBAL              1 (open + NULL)
               LOAD_CONST               1 ('file.txt')
               LOAD_CONST               2 ('w')
               CALL                     2
               BEFORE_WITH
       L1:     STORE_FAST               0 (f)

               ...생략...

   4   L2:     LOAD_CONST               0 (None)
               LOAD_CONST               0 (None)
               LOAD_CONST               0 (None)
               CALL                     2
               POP_TOP
               RETURN_CONST             0 (None)
       L3:     PUSH_EXC_INFO
               WITH_EXCEPT_START
               ...생략...

왜 갑자기 바이트코드냐면,, 지금 cpython 3.14 이상인 main인 깃헙 레포에는 with 에 대한 코드를 찾기 어렵다.. "Remove the BEFORE_WITH and BEFORE_ASYNC_WITH instructions. Add the new :opcode:LOAD_SPECIAL instruction" 때문 ㅠ
덧붙이자면 with 문은 Python 3.11 부터 도입된 특화 적응형 인터프리터(Specializing Adaptive Interpreter) 덕분에 고도로 최적화된 바이트코드를 사용한다. - https://peps.python.org/pep-0659/ & https://www.youtube.com/watch?v=shQtrn1v7sQ (아니 그니까 좀 python 최소한 3.11 이상은 써라 제발 좀)
여튼 BEFORE_WITH 가 __enter__ 이며 WITH_EXCEPT_START 가 with 에서 예외 발생 시 __exit__(...) 호출 하기 위한 세팅이다. ~~파이썬이 이렇게나 상위 문법을 지원해줘서 감사할따름~~

2. contextlib 모듈과 제너레이터

사실 __enter__ 와 __exit__ 를 가진 클래스를 매번 작성하는 것은 "귀찮다". 이럴때마다 파이써닉이 와닿는데, contextlib 내장 라이브러리가 이 과정을 훨씬 쉽게 만들어주는 @contextmanager 데코레이터를 제공한다.
https://github.com/python/cpython/blob/main/Lib/contextlib.py 에서 실제 해당 내장 라이브러리의 코드 참조!

1) `@contextmanager` 데코레이터의 내부 구현

@contextmanager 데코레이터는 제너레이터(Generator) 함수를 손쉽게 Context Manager로 변환해 준다. 이 데코레이터는 내부적으로 _GeneratorContextManager 라는 헬퍼 클래스를 사용하여 제너레이터를 컨텍스트 관리 프로토콜에 맞게 래핑한다.

def contextmanager(func):
    """@contextmanager decorator.

    Typical usage:

        @contextmanager
        def some_generator():
            
            try:
                yield 
            finally:
                

    This makes this:

        with some_generator() as :
            

    equivalent to this:

        
        try:
             = 
            
        finally:
            
    """
    @wraps(func)
    def helper(*args, **kwds):
        return _GeneratorContextManager(func, args, kwds)
    return helper

_GeneratorContextManager

class _GeneratorContextManager(
    _GeneratorContextManagerBase,
    AbstractContextManager,
    ContextDecorator,
):
    """Helper for @contextmanager decorator."""

    def __enter__(self):
        # do not keep args and kwds alive unnecessarily
        # they are only needed for recreation, which is not possible anymore
        del self.args, self.kwds, self.func
        try:
            return next(self.gen)
        except StopIteration:
            raise RuntimeError("generator didn't yield") from None

    def __exit__(self, typ, value, traceback):
        if typ is None:
            try:
                next(self.gen)
            except StopIteration:
                return False
            else:
                try:
                    raise RuntimeError("generator didn't stop")
                finally:
                    self.gen.close()
        else:
            if value is None:
                # Need to force instantiation so we can reliably
                # tell if we get the same exception back
                value = typ()
            try:
                self.gen.throw(value)
            except StopIteration as exc:
                # Suppress StopIteration *unless* it's the same exception that
                # was passed to throw().  This prevents a StopIteration
                # raised inside the "with" statement from being suppressed.
                return exc is not value
            except RuntimeError as exc:
                # Don't re-raise the passed in exception. (issue27122)
                if exc is value:
                    exc.__traceback__ = traceback
                    return False
                # Avoid suppressing if a StopIteration exception
                # was passed to throw() and later wrapped into a RuntimeError
                # (see PEP 479 for sync generators; async generators also
                # have this behavior). But do this only if the exception wrapped
                # by the RuntimeError is actually Stop(Async)Iteration (see
                # issue29692).
                if (
                    isinstance(value, StopIteration)
                    and exc.__cause__ is value
                ):
                    value.__traceback__ = traceback
                    return False
                raise
            except BaseException as exc:
                # only re-raise if it's *not* the exception that was
                # passed to throw(), because __exit__() must not raise
                # an exception unless __exit__() itself failed.  But throw()
                # has to raise the exception to signal propagation, so this
                # fixes the impedance mismatch between the throw() protocol
                # and the __exit__() protocol.
                if exc is not value:
                    raise
                exc.__traceback__ = traceback
                return False
            try:
                raise RuntimeError("generator didn't stop after throw()")
            finally:
                self.gen.close()

_GeneratorContextManager 가 이미 매우, 충분히 잘 만들어져 있기때문에, (제발 다시 처음부터 만들지 말고) @contextmanager 이거 부터 사용할지 고민해봐야 한다.

__enter__ 메서드

context manager에 진입할 때 호출
제너레이터의 첫 번째 yield까지 실행
yield된 값을 반환 (보통 with 문의 as 변수에 할당)

__exit__ 메서드

context manager에서 나갈 때 호출
예외가 없으면: 제너레이터가 정상 종료되는지 확인
예외가 있으면: 제너레이터에 예외를 전달하여 처리 기회 제공
예외 억제 여부를 결정하여 반환

간단한 해당 class 의 flow chart 는 아래와 같다.

예외 발생시의 `gen.throw(value)` 조금만 더 보자!

예외가 있으면, __exit__ 메서드는 전달받은 예외 정보(typ, value, traceback)를 사용하여 제너레이터의 throw() 메서드를 호출한다.
즉, gen.throw(value) 를 통해 제너레이터가 yield 에서 멈춰있던 지점으로 예외를 '주입' 한다. 그러면 제너레이터 함수 안의 try...except 블록에 의해 잡히게 된다.
그러니까 @contextmanager 를 사용한 함수에서 try...except 에서 잡히게 된다는 거고, try...except 를 써야 좀 더 depth 있는 디버깅을 할 수 있다는 것!

수동 클래스 구현 vs. @contextmanager 데코레이터

# 방법 1: 클래스로 직접 구현
class Timer:
    def __enter__(self):
        self.start = time.time()
        print("타이머 시작")
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        end = time.time()
        print(f"소요 시간: {end - self.start:.2f}초")
        return False # 예외를 억제하지 않음

# 방법 2: @contextmanager 데코레이터 사용
from contextlib import contextmanager
import time

@contextmanager
def timer():
    start = time.time()
    print("타이머 시작")
    try:
        yield # __enter__의 반환값 (여기선 None), 이 지점에서 with 블록 코드가 실행됨
    finally:
        # with 블록을 빠져나오면 이 코드가 실행됨
        end = time.time()
        print(f"소요 시간: {end - start:.2f}초")

# 사용법은 동일
with timer():
    time.sleep(1)

@contextmanager 를 사용하면 try...yield...finally 패턴으로 __enter__ 와 __exit__ 의 로직을 훨씬 직관적으로 표현할 수 있다.

yield 이전까지의 코드: __enter__ 에 해당
yield 이후 finally 블록 안의 코드: __exit__ 에 해당

_GeneratorContextManager는 __enter__가 호출되면 제너레이터를 yield 지점까지 실행하고, __exit__ 가 호출되면 예외 정보를 제너레이터의 throw() 메서드로 주입하거나 next() 를 호출하여 finally 블록이 실행되도록 한다.

더욱이 이제 "바이트코드" 로 구현되어 있어서 최소한의 오버헤드를 추가 한다고 한다.

2) 얘랑 제네레이터랑 무슨 연관이 있음?

사실 제네레이터를 모르면 위 예제들이나 설명이 와닿지가 않는다. (python 코루틴(coroutine) - iterator, generator, asyncio, async, await 그리고 코루틴 (2) 참조) 단순한 정의를 보면 python 에서 제네레이터는 "이터레이터를 생성하는 함수" 이다. yield 표현식을 사용하고 다음 호출 시 마지막으로 실행된 yield 표현식 이후부터 실행을 재개한다.

실행 흐름의 일시 중단 및 재개: yield 키워드는 함수의 실행을 잠시 멈추고 제어권을 호출자에게 넘겨준다. with 블록의 코드가 실행되는 동안 제너레이터는 yield 지점에서 대기하게 된다.
상태 유지: 제너레이터 함수 내의 "지역 변수"는 yield 를 통해 중단되었다가 다시 재개될 때까지 그 상태를 그대로 유지한다. (start 변수처럼)
예외 주입: 제너레이터의 throw() 메서드를 사용하면 제너레이터가 멈춰있는 yield 지점 외부에서 예외를 발생시킬 수 있다. @contextmanager 는 이 기능을 활용해 with 블록의 예외를 제너레이터 내부로 전달한다. 이 얘기가 바로 위에서 본 "예외 발생시의 gen.throw(value)" 얘기다.

그리고 사실 대용량 처리일 수 록, "메모리 관점의 이점이 상당하다." 이건 당연히 제네레이터의 특성이자 이를 기반으로 할 수 있는 with 의 결과론적인 이점이다.

리소스 누수 방지 & 리소스 자동 정리 & 제네레이터 & 캐시 지역성

3) 실제 사용하면 좋은 케이스

데이터베이스 연결 관리

데이터베이스 연결은 열고 닫는 것뿐만 아니라, 작업 성공 시 commit, 실패 시 rollback을 수행해야한다.

from contextlib import contextmanager
import sqlite3

@contextmanager
def db_transaction(db_path):
    conn = sqlite3.connect(db_path)
    cursor = conn.cursor()
    print("DB 커넥션 및 트랜잭션 시작")
    try:
        yield cursor # with 블록에서 사용할 커서 객체를 반환
        print("트랜잭션 커밋")
        conn.commit()
    except Exception as e:
        print(f"예외 발생: {e}, 트랜잭션 롤백")
        conn.rollback()
        raise # 예외를 다시 발생시켜 호출자에게 알림
    finally:
        print("DB 커넥션 종료")
        conn.close()

# 사용 예시
with db_transaction('app.db') as cursor:
    cursor.execute("INSERT INTO users (name) VALUES ('Alice')")
    # 만약 여기서 예외가 발생하면 자동으로 롤백됩니다.

근데 사실 SQLAlchemy 같은 대부분의 최신 DB 라이브러리는 이미 자체적으로 뛰어난 Context Manager를 내장하고 있어 직접 만들 필요는 거의 없다.

# SQLAlchemy의 내장 Context Manager 예시
from sqlalchemy.orm import Session

with Session(engine) as session:
    session.add(User(name="Bob"))
    # 예외 발생 시 자동으로 롤백, 정상 종료 시 커밋 (설정에 따라 다름)
    session.commit()
# 세션은 자동으로 닫힘

그리고 본문 가장 초기에 언급한 django transaction 예제도 내부적으로 context manager protocol 에 따른 형태로 class가 구현된 것을 볼 수 있다. ㅎㅎ

분산 락과 동기화

여러 서버에 걸쳐 리소스 접근을 동기화해야 할 때 Redis 같은 외부 저장소를 이용해 분산 락을 구현할 수 있다. 이때도 Context Manager는 매우 유용하다.

(나쁜예)

import redis

# 락을 획득했지만, 프로세스가 갑자기 죽으면 락이 해제되지 않을 수 있음
def bad_distributed_lock(r, lock_key):
    is_acquired = r.set(lock_key, "locked", nx=True, ex=30)
    if is_acquired:
        # ... 임계 영역 작업 ...
        r.delete(lock_key) # 작업 중 오류가 나면 실행되지 않음
    else:
        print("락 획득 실패")

(context manager 예시)

from contextlib import contextmanager
import redis
import uuid

@contextmanager
def distributed_lock(r: redis.Redis, lock_key: str, timeout: int = 30):
    lock_id = str(uuid.uuid4())
    # 락 획득 시도 (nx=True는 키가 없을 때만 set)
    if not r.set(lock_key, lock_id, nx=True, ex=timeout):
        raise TimeoutError("분산 락을 획득할 수 없습니다.")

    try:
        yield lock_id # 락을 획득했음을 알림
    finally:
        # 내가 획득한 락이 맞는지 확인하고 안전하게 삭제 (Lua 스크립트 사용)
        release_script = """
        if redis.call("get", KEYS[1]) == ARGV[1] then
            return redis.call("del", KEYS[1])
        else
            return 0
        end
        """
        r.eval(release_script, 1, lock_key, lock_id)

# 사용 예시
r = redis.Redis()
try:
    with distributed_lock(r, "my-distributed-lock") as lock_id:
        print(f"락 획득 성공 (ID: {lock_id})")
        # 여러 서버에서 공유하는 중요한 작업 수행
except TimeoutError as e:
    print(e)

API 비율 제한과 리소스 조절

외부 API 호출 시 *"비율 제한(Rate Limiting)"* 이 필요하거나, 스레드 풀 같은 리소스를 사용하고 안전하게 종료(shutdown)하는 데도 Context Manager가 이상적이다.

(나쁜예)

import time
import requests
from concurrent.futures import ThreadPoolExecutor

# 스레드에 안전하지 않은(non-thread-safe) API 클라이언트
class UnsafeAPIClient:
    def __init__(self, requests_per_second=1):
        self.interval = 1.0 / requests_per_second
        self.last_request_time = 0

    def make_request(self, url):
        # 여러 스레드가 이 부분을 동시에 통과할 수 있어 비율 제한이 깨짐 (Race Condition)
        time_since_last = time.time() - self.last_request_time
        if time_since_last < self.interval:
            time.sleep(self.interval - time_since_last)

        self.last_request_time = time.time()
        print(f"{threading.current_thread().name}: Requesting {url} at {self.last_request_time:.2f}")
        return requests.get(url)

# 스레드 풀을 생성하고 제대로 종료하지 않음
def bad_api_usage():
    client = UnsafeAPIClient(requests_per_second=2) # 초당 2회 제한
    executor = ThreadPoolExecutor(max_workers=5)

    urls = ['https://api.example.com/data'] * 5

    # 여러 스레드에서 안전하지 않은 클라이언트를 공유하며 작업 제출
    for url in urls:
        executor.submit(client.make_request, url)

    # executor.shutdown(wait=True) 호출을 잊어버림!
    # 프로그램이 즉시 종료되지 않거나, 스레드 리소스가 누수될 수 있음.
    print("모든 작업을 제출했지만, 스레드 풀을 종료하지 않았습니다.")

위와 같이 스레드 풀을 수동으로 관리하고, 비율 제한이 스레드에 안전하지 않은 경우는

경쟁 상태 (Race Condition): UnsafeAPIClient의 비율 제한 로직은 여러 스레드가 동시에 접근하면 바로 꺠진다. 여러 스레드가 거의 동시에 time_since_last 를 확인하고 sleep 없이 바로 요청을 보내기 때문에 의도한 비율 제한을 바아로 초과하게 된다.
리소스 누수 (Resource Leak): ThreadPoolExecutor 를 생성한 후 shutdown() 메서드가 호출되지 않았다! -> 백그라운드 스레드가 정리되지 않아 프로그램이 비정상적으로 대기하거나 리소스가 계속 점유되는 문제가 발생한다. (이거 생각보다 그냥 놓치면 나중에 디버깅하기 어렵다. 평소 습관이 중요...)

(context manager 예시)

from concurrent.futures import ThreadPoolExecutor
from contextlib import contextmanager
import threading

# 스레드 풀을 안전하게 관리하는 Context Manager
@contextmanager
def thread_pool(max_workers):
    executor = ThreadPoolExecutor(max_workers=max_workers)
    try:
        yield executor
    finally:
        # with 블록이 끝나면 반드시 shutdown이 호출됨
        executor.shutdown(wait=True)

# 스레드에 안전한 비율 제한 로직을 제공하는 Context Manager
@contextmanager
def rate_limiter(client_instance):
    with client_instance.lock: # 스레드 락으로 임계 영역 보호
        time_since_last = time.time() - client_instance.last_request_time
        if time_since_last < client_instance.interval:
            time.sleep(client_instance.interval - time_since_last)
        client_instance.last_request_time = time.time()
    yield

class SafeAPIClient:
    def __init__(self, requests_per_second=1):
        self.interval = 1.0 / requests_per_second
        self.last_request_time = 0
        self.lock = threading.Lock() # 스레드 동기화를 위한 락

    def make_request(self, url):
        with rate_limiter(self): # 컨텍스트 매니저로 비율 제한
             print(f"{threading.current_thread().name}: Requesting {url} at {time.time():.2f}")
             return requests.get(url)

# Context Manager를 활용한 안전한 병렬 API 요청
def good_api_usage():
    client = SafeAPIClient(requests_per_second=2)
    urls = ['https://api.example.com/data'] * 5

    with thread_pool(max_workers=5) as executor:
        futures = [executor.submit(client.make_request, url) for url in urls]
        # 결과 처리...

    print("모든 작업이 완료되고 스레드 풀이 안전하게 종료되었습니다.")

사실, 눈치챗듯 위 thread_pool 은 좀 과하다 ㅎㅎ;
ThreadPoolExecutor 가 이미 __enter__ 와 __exit__ 메서드를 구현하고 있기 때문에 불필요한 중복이다 ㅎ. 하나의 예시를 위해 가져와서 사용했다.
with ThreadPoolExecutor(max_workers=5) as executor 로 처리 가능하다.

# ThreadPoolExecutor를 직접 Context Manager로 활용
def good_api_usage_simplified():
    client = SafeAPIClient(requests_per_second=2)
    urls = ['https://api.example.com/data'] * 5

    # ThreadPoolExecutor 자체가 Context Manager이므로 별도 래퍼 함수 불필요
    with ThreadPoolExecutor(max_workers=5) as executor:
        futures = [executor.submit(client.make_request, url) for url in urls]
        # 결과 처리...
        # concurrent.futures.as_completed(futures) 등을 사용하여 완료된 순서대로 결과 처리 가능

    print("모든 작업이 완료되고 스레드 풀이 안전하게 종료되었습니다.")

핵심 요약

결국 Context Manager는 *"리소스의 안전한 획득과 해제를 보장하는 파이썬의 핵심 메커니즘"* 이다. 그리고 이걸 with 구문으로 사용할 수 있다. (__enter__ 와 __exit__ 자동 호출)
결국 with 문은 동시성 환경에서 발생할 수 있는 경쟁 상태(Race Condition), 데드락(Deadlock), 리소스 누수(Resource Leak) 등의 심각한 문제들을 원천적으로 방지 하는 짱편한 문법이다.
특히 @contextmanager 데코레이터와 제너레이터의 조합은 복잡한 클래스 구현 없이도 직관적인 try...yield...finally 패턴으로 리소스 관리 로직을 표현할 수 있게 해준다.
특히 * 3.11 이상의 특화 적응형 인터프리터 덕분에 성능 오버헤드도 최소화되었으니*, 파일 I/O, 데이터베이스 트랜잭션, 스레드 동기화, 분산 락 등 리소스가 관련된 모든 곳에서 Context Manager를 적극 활용해보자!

출처

[책 리뷰] LLM 엔지니어링 - 폴 이우수틴 , 막심 라본

Sun, 29 Jun 2025 14:26:09 GMT

[ "한빛미디어 서평단 <나는리뷰어다> 활동을 위해서 책을 협찬 받아 작성된 서평입니다." ]

LLM 엔지니어링

Paul Iusztin(폴 이우수틴): 7년 이상 생성형 AI, 컴퓨터 비전 및 MLOps 설루션을 구축한 시니어 ML/MLOps 엔지니어. 최근에는 Metaphysic에서 대규모 신경망을 프로덕션에 적용하는 핵심 엔지니어로 근무했다. 또한 프로덕션급 ML 교육 채널인 Decoding ML을 설립해 사람들이 ML 시스템을 구축할 수 있도록 IT 기사와 오픈 소스 강좌를 제공하고 있다. - 링크드인 / PS) 실제 폴 이우스틴의 미디엄 에서 해당 책의 원본, 원문 내용을 많이 찾아볼 수 있다.

Maxime Labonne(막심 라본): Liquid AI의 모델 최적화 총괄 책임자. 파리 폴리테크닉 연구소에서 ML 박사 학위를 취득했으며, AI/ML 분야의 구글 개발자로 일하고 있다. LLM 과정과 LLM AutoEval 등의 도구, NeuralDaredevil과 같은 SOTA 모델을 포함해 오픈 소스 커뮤니티에 활발히 기여하고 있으며, 기술 블로그도 꾸준히 운영하고 있다. 저서로는 『핸즈온 그래프 인공신경망 with Python』(홍릉, 2024)이 있다. - 링크드인

🔥 한빛 책 링크 - https://www.hanbit.co.kr/store/books/look.php?p_code=B8130648672 🔥 코드 참조 깃허브 레포 - http://github.com/inrap8206/LLM-Engineers-Handbook

리뷰

실제 MVP의 핵심 기능을 직접 정하고, ML & MLOps 관점에서 아키텍처 설계부터 실습까지 점진적으로 나아가는 구성은 이 책의 가장 큰 미덕이다. 각 장을 넘길수록 기능이 하나씩 추가되고, 아키텍처가 세밀하게 확장되어 가는 방식은 단순한 튜토리얼을 넘어선다. 프로젝트가 완성되는 시점에서 "이 책은 처음부터 꽤나 치밀하게 설계되었다는 것"을 깨달았고, 그 흐름 속에 독자를 몰입하게 만든다는 점에서 확실히 '밀도' 있는 구성이다.

무엇보다도 토이 프로젝트의 완성도가 기대 이상으로 재밌다. 단순히 ‘구현했다’ 수준을 넘어 실제 운영 가능한 수준의 기획과 구조, 그리고 실험 기반 접근이 더해져 있어서 진짜 ‘프로젝트 하나 만든다’는 느낌이 강하다. 단순한 예제 코드가 아닌, 실전 감각이 묻어난 프로젝트라는 점에서 분명 큰 만족감을 준다. *입문자용이 아니라서 아주아주 마음에 들었던 책..* FTI 아키텍쳐 하나 제대로 배운 것 만으로도 만족!

[아쉬웠던 포인트 들]

책의 설명은 굉장히 상세하지만, 그만큼 진입장벽도 있다. 실습 환경을 세팅하거나 파이프라인 흐름을 따라가는 과정에서, 시각적으로 빠르게 이해하는 데 한계가 있다. 영상이나 인터랙티브한 문서가 병행되었다면 더 많은 독자들이 이 책의 가치를 누릴 수 있었을 것이다. (근데 나중에 발견한 링크, https://decodingml.substack.com/p/build-your-second-brain-ai-assistant 참조하면 도움이 꽤 될 듯 하다.)

그리고 한국 독자 기준으로는 데이터셋이 꽤 낯설 수 있다. 필자의 경우 GitHub, Notion, LinkedIn, Velog 데이터를 기반으로 커스터마이징하여 실습을 진행했는데, 국내 데이터셋에 맞춘 튜닝 사례나 팁이 조금이라도 언급되었으면 훨씬 현실감 있는 접근이 가능했을 것이다.

매우 주관적으로 "범위와 구성이 약간 과했다" 는 생각이 든다. 특히 도메인 주도 설계(DDD) 파트는 실제로 직접 카테고리를 확장하거나 데이터 파이프라인을 커스터마이징할 때 예상보다 많은 구조 변경이 필요했다. ~~(물론 내가 못해서...)~~ 가벼운 레이어를 분리정도로 했어도 괜찮은 프로젝트 사이즈가 아닐까!? 했다.

"LLM 평가 파트의 아쉬움" 이 있다. 아주 개인적으로는 도메인 특화 모델의 평가에 더 깊이 들어가주기를 바랐다. 파인튜닝 이후 모델을 어떻게 평가해야 하는지, 특히 정량적 지표가 부정확하거나 불충분할 때 어떻게 QA 해야 하는지가 궁금했으나, 방법론적인 틀 정도만 제시되고 넘어간 점은 아쉬웠다. 물론, 특화 도메인의 평가가 어렵다는 점은 현실적으로 공감되지만 말이다.

이 책은 ‘한 번 읽고 덮을 책’이 아니다. 처음부터 끝까지 따라하며 실습하는 것도 좋지만, 직접 파이프라인을 추가하고, 특성을 바꾸고, 평가 방식을 고민하며 R&D하는 데 활용하면 훨씬 큰 가치를 지닌다. 단지 구현에 그치지 않고, 업계에서 자주 마주치는 안티패턴을 경계하면서 고응집 / 저결합 아키텍처를 지향한다는 점도 매우 인상 깊다.

(요즘 읽은 책 중에 가장 읽기 어려웠던 책이다. 바쁜 일상 속에서도 쉽게 놓치고 싶지 않은 내용이 너무 많았기에, 욕심내며 읽게 된 책이었다. 그런 만큼 다시 두 번, 세 번 반복해서 보는 가치가 있는 책이기도 하다.)

목차별 리뷰

CH 1. LLM Twin 개념과 아키텍처 이해

이 장에서는 LLM Twin을 만들기 위한 전략적 접근과 아키텍처 설계 개념을 다룬다. 먼저, LLM Twin을 현실화하기 위한 MVP(Minimum Viable Product) 전략으로 출발하여, 실제로 어떤 기능이 핵심인지 정의한다. 이 때 단순히 모델 개발이 아닌, 제품 관점에서의 기능 정의와 프로세스 구성에 포인트를 두고 있는게 인상 깊다.

< ML 시스템은 기본적으로 다음과 같은 전체 흐름을 가진다. >

새로운 데이터 수집, 정제, 검증
학습 환경과 추론 환경의 분리
비용 효율적 모델 서빙
데이터셋 및 모델의 버전 관리와 추적
인프라 및 모델 모니터링
확장 가능한 인프라 기반 배포
학습과 배포 자동화

이러한 이상적인 시스템 구성은 구글 클라우드 팀이 제시한 아래 그림에서도 확인할 수 있다.

< 이를 위한 가장 단순한 아키텍처는 `모놀리식 배치 아키텍처`다. >

이 구조는 학습과 서빙 사이의 왜곡(training-serving skew)을 피할 수 있다는 장점이 있지만, 다음과 같은 단점을 가진다.

특성 재사용성이 낮음
데이터 양이 증가하면 PySpark, Ray 등으로 리팩터링 필요
팀 간 협업 어려움
실시간 학습 전환의 어려움

< 단점을 극복하기 위한 대안으로 `무상태 실시간 아키텍처` >

하지만 실시간으로 대용량 데이터를 처리하며 지속 학습을 수행하는 것은 여전히 도전적이다. 예컨대 영화 추천 시스템처럼, 사용자 상태와 맥락에 따라 전혀 다른 예측이 필요한 경우, 이러한 시스템 설계는 복잡해진다.

< 이러한 문제의 해결을 위해, 구글은 다음과 같은 아키텍처를 제시했다. >

(실제 MLOps: 머신러닝의 지속적 배포 및 자동화 파이프라인 의 구글 문서에서도 따온 이미지로 설명함)

< FTI 아키텍처 - ML 시스템의 본질 >

Feature - Training - Inference 로 구성된 FTI 아키텍쳐가 논리적인 ML 구조에 가장 부합하고, 구글 그림을 3개로 단순화 할 수 있다고 한다.

전통적인 웹 시스템에서의 DB - Business Logic - UI 계층처럼, 각각의 독립성과 연결성을 모두 갖춘 구조로 설명된다. 그렇기 때문에 "다양한 팀에서 관리하고, 재사용할 수 있는 형태" 라고 한다.

< 1. 특성 파이프라인 (Feature Pipeline) >

원시 데이터를 수집하고 필요한 특성과 레이블로 가공
이 결과는 특성 저장소(Feature Store)에 저장됨
다양한 팀에서 재사용할 수 있는 형태로 구성됨

< 2. 학습 파이프라인 (Training Pipeline) >

Feature Store에서 특성과 레이블을 불러와 모델 학습을 진행
하나 이상의 모델을 생성하고, 이를 모델 레지스트리(Model Registry)에 저장

< 3. 추론 파이프라인 (Inference Pipeline) >

입력: 특성, 레이블, 학습된 모델
출력: 예측값
사용 방식: 배치 또는 실시간 형태

각 파이프라인은 독립적으로 실행 가능한 모듈이며, 각각 다른 팀이 운영하거나 독립적으로 확장/교체할 수 있다.

그리고 저자는 ML 시스템이 아무리 복잡해져도 이 기본 구조는 변하지 않을 것이라고 한다. (저자는 각 파이프라인이 현업에서 보통 어떤 팀이 담당할지도 언급을 한다.)

CH 2. 도구 및 설치

이 장은 개념적 설명보다는 LLM Twin 구축에 필요한 도구 소개와 사전 환경 세팅 가이드에 초점이 맞춰져 있다. 개발 환경을 제대로 구축하는 것은 이 책의 실습을 따라가기에 필수이며, 특히 Python에 익숙하지 않은 독자라면 진입장벽이 다소 높을 수 있다. (사실 이 책 자체가 익숙하지 않는 독자 대상이 아닌 듯 하다.)

참고로 https://github.com/inrap8206/LLM-Engineers-Handbook 에 레포 세팅을 따라가려면 대부분의 API 키 세팅이 필요하니, 해당 장에서 미리 clone 하고 .env.sample 에 맞춰 키세팅을 하는 것을 추천한다.

< Python 환경 세팅 >

pyenv: 다양한 버전의 Python을 손쉽게 설치하고 관리할 수 있는 도구.
poetry: 패키지와 의존성 관리를 위한 현대적인 도구. pyproject.toml 중심의 구성 파일을 사용하여 환경을 선언적으로 관리한다. python - poetry 설치부터 project initializing, 활용하기 참조
poe the poet: poetry의 스크립트 실행 기능을 더 직관적으로 만들어주는 도구. CLI 명령어를 간편하게 정의할 수 있으며, 공식 사이트는 poethepoet.natn.io.
- 참고로 프로젝트 세팅할때 poetry self add 'poethepoet[poetry_plugin]' 해야 함!

< HuggingFace >

모델과 토크나이저를 쉽게 불러올 수 있는 모델 레지스트리 기능을 제공.
여러 프로젝트에서 동일한 모델을 재사용하거나 커스터마이징할 때 유용.

< ZenML >

오케스트레이터, 아티팩트, 메타데이터 관리 기능을 갖춘 프레임워크.
ML 워크플로우를 재현 가능하고 구조적으로 설계할 수 있도록 도와준다.
핵심은 DAG(Directed Acyclic Graph) 기반의 처리.
비슷한 도구로는 Airflow, Prefect, Metaflow, Dagster 등이 있다.
ZenML은 특히 실습과 실전 프로젝트 모두에 적합하도록 구성된 모던한 워크플로우 엔진이라는 점에서 강점이 있다.
poetry run poe local-zenml-server-up 로 local-server zenml 을 바로 띄울 수 있다.

❯ poetry run poe local-zenml-server-up

Poe <= sys.platform
Poe => poetry run zenml up --blocking
The local ZenML dashboard is about to deploy in a blocking process. You can connect to it using the 
'default' username and an empty password.
Deploying a local ZenML server with name 'local'.
Initializing the ZenML global configuration version to 0.67.0
Starting ZenML Server as blocking process... press CTRL+C once to stop it.
INFO:     Started server process [97367]
INFO:     Waiting for application startup.
Not writing the global configuration to disk in a ZenML server environment.
Not writing the global configuration to disk in a ZenML server environment.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8237 (Press CTRL+C to quit)
INFO:     127.0.0.1:65079 - "GET / HTTP/1.1" 200 OK

< Comet ML >

실험 추적을 위한 대표적 SaaS 도구.
반복적인 모델 실험을 효율적으로 추적 가능.
다음과 같은 지표를 시각화 및 기록:
- 학습 및 평가 손실
- gradient norm (손실 함수에 대한 기울기의 크기)
- 모델 예측 결과 등

< Opik >

프롬프트 모니터링 도구로 소개됨.
생성형 AI의 성능을 추적하고 품질을 정량화하기 위한 도구로 보임 (자세한 내용은 다소 제한적이지만, 프롬프트 기반 실험을 추적하는 데 활용 가능).

< 데이터 저장 및 처리 도구 >

MongoDB: 문서 기반의 대표적인 NoSQL 데이터베이스. 비정형 데이터를 유연하게 다룰 수 있음.
Qdrant: 고성능 벡터 검색 DB. 대규모 임베딩 데이터를 저장하고 빠르게 검색할 수 있는 백터 DB로, RAG 시스템과 궁합이 좋음. (PS. 저자의 말을 빌리자면 요즘 대부분의 성능에서 모난 곳 없이 가장 안정적이라고 한다.)

< AWS 세팅 및 SageMaker 소개 >

SageMaker는 학습과 추론을 위한 클라우드 기반 ML 플랫폼.
GPU 클러스터에서 모델을 학습하거나 파인튜닝할 수 있으며, REST API 형태로 배포 가능.
LLM Twin을 배포할 때, 전 세계 사용자들이 실시간으로 접근 가능하도록 만드는 핵심 인프라 역할을 수행.

PS. 이 장은 진짜 재미있는게 저자의 짬바가 느껴지는 SaaS & PaaS 를 소개해줘서 오히려 좋았다. 그 목적과 이유도 명백해서 더 와닿았고 ㅎㅎ.

CH 3. 데이터 엔지니어링

이 장에서는 LLM Twin 프로젝트의 데이터 수집과 저장 구조, 즉 ETL 파이프라인을 어떻게 설계하고 구현하는지에 대한 전체 그림을 다룬다. MongoDB를 데이터 웨어하우스로 상정하고, 크롤러 → 파이프라인 → 저장의 흐름으로 진행되며, 핵심은 '카테고리 중심 수집 체계'와 'ZenML 기반 자동화'에 있다.

"카테고리" 기반 수집 구조

수집 데이터는 플랫폼 단위로 나누지 않고, 데이터 카테고리에 귀속 시켜 구성한다. 예를 들어 Medium은 ‘아티클’, GitHub은 ‘레포지토리’, LinkedIn 포스트는 ‘게시물’처럼 정의하여 확장성 있는 구조를 만든다.

PoC에서는 수백 개 단위로 충분할 수 있지만
실 운영환경에서는 수천 개 이상의 데이터가 필요하다
따라서 '완성도 높은 설계'보다는 '점진적 진화'를 강조한다

이게 특성 파이프라인과 어떻게 연결되는가? -> MongoDB 에 저장된 원시 데이터를 가져와 *"특성으로 변환"* 하는 후속작업을 통해 Qdrant Vector DB 에 저장할 것이다.

참고로 여기서부턴 http://github.com/inrap8206/LLM-Engineers-Handbook 레포를 보면서 따라오는게 좋다. (clone 을 먼저 하는 것을 추천)

전체적인 구조

데이터 수집 파이프라인 상세 분석

ZenML Pipeline: digital_data_etl



Step 1: get_or_create_user
User 생성/조회



Step 2: crawl_links
링크별 크롤링 실행





Inputs:
• user_full_name: str
• links: list[str]

Outputs:
• UserDocument → MongoDB
• Article/Post/Repo Documents → MongoDB

Crawler Dispatcher 패턴

URL 패턴 매칭:
• https://medium.com/* → MediumCrawler
• https://linkedin.com/* → LinkedInCrawler
• https://github.com/* → GithubCrawler
• 기타 → CustomArticleCrawler (기본값)

Registry 패턴:
_crawlers = {"regex_pattern": CrawlerClass}
동적 크롤러 선택 및 실행

Medium Crawler 상세

기술 스택:
• Selenium WebDriver (헤드리스 Chrome)
• BeautifulSoup4 (HTML 파싱)
• chromedriver-autoinstaller

크롤링 프로세스:
1. driver.get(link) - 페이지 로드
2. scroll_page() - 동적 콘텐츠 로딩
3. BeautifulSoup으로 HTML 파싱
4. 제목, 부제목, 본문 추출

추출 데이터:
{"Title": str, "Subtitle": str, "Content": str}

GitHub Crawler 상세

기술 스택:
• subprocess (git clone)
• os.walk (파일 탐색)
• tempfile (임시 디렉토리)

크롤링 프로세스:
1. tempfile.mkdtemp() - 임시 디렉토리
2. git clone [repo_url]
3. 파일 트리 순회 및 읽기
4. ignore 패턴 필터링

추출 데이터:
{file_path: file_content} 딕셔너리

LinkedIn Crawler (Deprecated)

기술적 이슈:
• LinkedIn의 보안 강화로 로그인 차단
• reCAPTCHA 및 봇 감지 시스템
• 현재 _is_deprecated=True 상태

원래 구현 내용:
• 프로필 정보 수집 (About, Experience)
• 포스트 및 이미지 수집
• 무한 스크롤 처리

⚠️ 대안:
LinkedIn API 또는 수동 데이터 수집 필요

MongoDB 저장 프로세스



ArticleDocument
content: dict
link: str
platform: str
author_id: UUID
author_full_name: str


PostDocument
content: dict
image: Optional[str]
platform: str
author_id: UUID
author_full_name: str


RepositoryDocument
content: dict (file tree)
name: str
link: str
platform: str = "github"
author_id: UUID


UserDocument
first_name: str
last_name: str
full_name: property
id: UUID (auto)


저장 메서드:
• instance.save() - 단일 문서 저장
• Model.bulk_insert(documents) - 배치 저장
• Model.get_or_create(**kwargs) - 중복 방지


MongoDB 컬렉션:
• Database: twin
• Collections: users, articles, posts, repositories
• Connection: mongodb://llm_engineering:llm_engineering@127.0.0.1:27017

ZenML 기반 Pipeline 구조

ZenML 파이프라인 digital_data_etl은 다음과 같은 구조다.

get_or_create_user
- 사용자 정보를 생성하거나 조회
- user_full_name, UUID 기준으로 처리
crawl_links
- 전달받은 링크들을 기준으로 크롤링 수행
- 링크 리스트는 ZenML step에 입력으로 들어감

이 파이프라인은 완전히 모듈화되어 있고, 입력/출력에 따라 자동으로 MongoDB 에 저장된다. poetry poe run-digital-data-etl 로 실행하면 된다.

poetry run python -m tools.run --run-etl --no-cache --etl-config-filename digital_data_etl_maxime_labonne.yaml
poetry run python -m tools.run --run-etl --no-cache --etl-config-filename digital_data_etl_paul_iusztin.yaml

digital_data_etl_maxime_labonne.yaml 과 digital_data_etl_paul_iusztin.yaml 에 설정에 따라 실행되며 아래와 같이 zenml 이 추적된다.

Dispatcher & Registry 패턴

크롤러 로직은 Dispatcher로 관리되며, URL 패턴에 따라 자동으로 적절한 크롤러가 선택된다.

예를 들어 아래와 같다.
- https://medium.com/* → MediumCrawler
- https://github.com/* → GithubCrawler
- 기타 → CustomArticleCrawler

이는 내부적으로 _crawlers = {regex_pattern: CrawlerClass} 형태의 Registry를 유지하며, 각 Crawler는 템플릿 메서드 패턴으로 공통 구조를 따르면서도 플랫폼에 특화된 로직을 담는다.

개인적으로 해당 파이프라인은 독자마다 철저하게 커스텀해서 세팅하는 것을 강력 추천한다. 솔직히 "카테고리" 와 "MongoDB" 적재 세팅만 맞추면 파이프라인은 알아서 구성하는 것이 나을 것 같다. 나의 경우 github, velog, 그리고 notion 을 사용했다. (참고로 처음 읽을땐 그냥 한 번 처음부터 끝까지 따라가보고 난 뒤에 바꿨다.)

(PS. 다른 원천 데이터 셋을 구성하려면, 스크래핑과 크롤링에 익숙하지 않은 사람이라면 해당 장에서 꾀나 애먹을 수 도 있다.)

MongoDB 저장 구조 및 Document 구성

데이터 저장은 twin 이라는 데이터베이스 내 아래 컬렉션들로 구성된다.

users
- UserDocument (full_name, id 등)
articles
- ArticleDocument (content, link, platform, author_id 등)
posts
- PostDocument (content, image, platform 등)
repositories
- RepositoryDocument (file tree, name, link 등)

저장 방식은 다음과 같다.

instance.save() → 단일 문서 저장
Model.bulk_insert(docs) → 다수 문서 저장
Model.get_or_create(**kwargs) → 중복 방지 저장

PS. 깃허브 레포 기준 llm_engineering/domain/base/nosql.py 에 기본 ODM class 를 구현했다. 사실 이 부분에서 이 책은 확실히 진입장벽이 높다고 많이 느겼다. (근데 코드와 다르게 설명은 이제 막 NoSQL 이 뭔지 배운 사람에게 설명하는 듯하다 ㅋㅋㅋ)

이후 poe the poet 로 사전에 세팅된 poe command 로 바로 시작할 수 있다.

CH 4. RAG 특성 파이프라인

개인적으로 이 책의 정수는 4장부터라고 생각된다. 본격적으로 Retrieval-Augmented Generation(RAG)에 대한 구조와 개념이 실제 시스템에 어떻게 구현되는지를 보여주는 장이며, 단순 이론에 그치지 않고 LLM Twin 프로젝트의 구체적인 사례로 연결되는 부분이 핵심이다.

RAG의 개요와 목적

RAG는 이름 그대로 Retrieval(검색), Augmented(증강), Generation(생성)의 세 단계를 조합한 구조다. 모든 LLM은 기본적으로 매개변수화된 지식(parameterized knowledge)에 의존한다. 즉, 사전 학습된 데이터에 기반한 지식을 제공하므로 최신 정보가 반영되지 않거나 사전에 포함되지 않은 정보를 요청하면 할루시네이션(환각) 문제가 발생할 수 있다.

이를 해결하기 위해 외부 정보에 접근할 수 있는 구조가 필요하며, 대표적인 해결책이 RAG다. 특히 금융 비서, 실시간 뉴스 기반 어시스턴트처럼 외부 정보의 실시간 접근이 필수적인 도메인에서는 RAG 구조가 매우 효과적이다.

1. 수집 파이프라이닝

데이터 추출 모듈: 다양한 소스(Crawling, DW 등)에서 원시 데이터 수집
정제 모듈: 수집된 데이터를 표준화, 정규화, 정제
청킹 모듈: 모델 처리 효율성을 위해 작은 단위로 문서 분할
임베딩 모듈: 청킹된 문서를 벡터화
로딩 모듈: 임베딩 결과와 메타데이터를 함께 Vector DB에 저장

2. 검색 파이프라이닝

사용자 입력(텍스트, 이미지 등)을 임베딩
Vector DB에서 유사한 벡터를 K개 검색 (코사인 거리 등 활용)
검색 결과를 LLM 프롬프트에 보강 정보로 삽입

여기서 사용하는 거리 계산법 중 가장 일반적인 것은 코사인 거리이며, 수식은 다음과 같다:

$$ \text{Cosine Similarity}(A, B) = \frac{A \cdot B}{||A|| \times ||B||} $$

$$ \text{Cosine Distance} = 1 - \text{Cosine Similarity} $$

두 벡터 사이 각도의 코사인 값을 1에서 뺀 값이며, -1 에서 1 사이 값을 가진다.(벡터 서로 반대일 때 -1, 수직일 때 0, 같은 방향 1)

3. 생성 파이프라이닝

검색된 문서 + 사용자 입력 → 프롬프트로 구성
LLM에 전달하여 최종 답변 생성
프롬프트도 버전 관리가 필요하면 LangFuse 같은 도구로 모니터링 및 관리 가능

임베딩

임베딩은 단어, 이미지, 추천 시스템의 항목 등 객체를 연속적인 벡터 공간에 벡터로 인코딩한 밀집된 숫자 표현이다. 의미론적 의미(semantic meaning) 와 의미론적 관계(semantic relationship)를 포착하는데 도움 준다. (ML은 오직 숫자만 처리 가능하다. 왜? 임베딩 필요? 는 skip)

(출처: https://uracle.blog/2025/03/14/embedding/)

일반적인 차원: 64 ~ 2048차원
시각화 도구: UMAP (사람이 인지하는 2-3차원 보다 훨씬 높기 때문에 시각화 못함. 근데 강제로 3차원으로 축소해서 시각화)
초기 기법: Word2Vec, GloVe
현대 기법: BERT, RoBERTa, sentence-transformers (Python)
벤치마크: HuggingFace의 MTEB

이미지 임베딩은 CNN, 특히 ResNet을 주로 활용하며, 이런 임베딩된 값들을 저장하기 위해 기존 스칼라 기반 DB는 이를 다루기 어려워 Vector DB가 부상하게 됐다. vecotr dbms 대신 FAISS 같은 독립형 벡터 인덱스도 유사도 검색에 효과적이긴 하지만 포괄적인 관리 기능 부족하다.

원-핫 인코딩과 같은 간단한 방법은 왜 안하는가? -> "차원의 저주 문제"가 있다.

텍스트 임베딩 기법으로 Word2Vec, GloVe 등이 초기에 등장했고, 오늘날엔 BERT, RoBERTa 트랜스포머 모델이 유명하다. 더욱이 요즘에 쉽게 임베딩 모델 바로 사용가며, python Sentence Transformers 패키지 같은거 사용해보면 좋다!

PS) 허깅 페이스 MTEB(Massive Text Embedding Benchmark) 통해 임베딩 모델 성능 비교 가능.

Vector DB의 작동 방식 요약

임베딩된 입력 쿼리 → Vector DB로 전달
ANN(Approximate Nearest Neighbor) 방식으로 근접 벡터 검색
후처리로 정렬, 필터링 등의 단계 존재

RAG 최적화의 세 단계

검색 전처리 (Pre-retrieval)
- 데이터 인섹싱과 쿼리 최적화
- 인덱싱 개선, 쿼리 전처리, 슬라이딩 윈도우, 데이터 세분화 개선 (enhancing data granularity), 메타데이터 구조화, small-to-big, 쿼리 라우팅, 쿼리 재작성, 쿼리 확장 기법 등
검색 최적화
- 임베딩 모델 개선 혹은 instructor 모델 활용
- 하이브리드 검색 (필터링 + 벡터 검색)
검색 후처리
- 리랭킹, 프롬프트 압축, 필터링 등

정리하자면 RAG는 검색 전처리, 검색, 검색 후처리 세 가지 핵심 단계 개선하는게 중요

LLM Twin에서의 특성 파이프라인 구현

LLM Twin은 DDD(Domain-Driven Design) 원칙을 기반으로, 데이터 흐름과 상태를 명확히 나눈다.

데이터 범주: 게시물, 기사, 레포지터리
데이터 상태: 정제됨 / 청킹됨 / 임베딩됨
Pydantic 도메인 엔티티, OVM (VecotrBaseDocument class 참조), 디스패처 계층(핸들러 적용) 와 같이 잘 짜여진 구조얘기도 같이 나온다! 이 부분은 정말 직접 구축할 때 많은 도움이 될 것 같다.

텍스트는 단순히 문자열로 저장됐다고 해서 특성(feature)이 아니며, 모델 입력을 위한 구조화, 즉 토큰화 과정이 반드시 필요하다.

LLM Twin은 배치 기반 파이프라인을 선택하며, 스트리밍 기반은 복잡도 및 실시간성을 요구하는 도메인에 한정해 사용한다. 대표적으로 아래와 같은 구조로 구성된다.

LLM Twin RAG 특성 파이프라인 5단계

데이터 추출
데이터 정제
문서 청킹
임베딩
Vector DB 적재 (Qdrant 활용)

배치 vs 스트리밍 파이프라인

배치(Batch) 방식은 데이터를 일정 단위로 모아서 처리하는 형태로, 상대적으로 구현이 단순하고 안정적임.
스트리밍(Streaming) 방식은 실시간으로 데이터를 처리해야 하므로 구현 복잡성이 높음.
- 메시징 큐(MQ), 이벤트 기반 아키텍처, 낮은 지연 시간 설계 필요
- 실시간 업데이트가 중요한 틱톡, 소셜 미디어 추천 시스템, 사기 탐지 시스템 등에서 필수적
LLM Twin에서는 시스템 복잡도를 고려해 배치 방식을 채택함. 즉 배치 방식으로 Qdrant Vecotr DB Upsert 되는 형태.

CDC(Change Data Capture) 활용

배치 기반 데이터 처리 후, Qdrant Vector DB에 Upsert 방식으로 적재함.
데이터 동기화를 위해 CDC(Change Data Capture) 방식 활용
CDC 활용 (Elasticsearch - ELK stack & Postgresql & Logstash, query based CDC 만들기 by docker compose / 카프카 클러스터와 파이썬 (2) - Debezium & Postgresql & Django, log based CDC 만들기 (source & sink connector) 참조!)
업계에서는 로그 기반 CDC를 더 선호하는 추세 (더 안정적이고 누락 없이 데이터 반영 가능)

두 번의 스냅샷 저장 이유

데이터 정제 후 저장 → LLM 파인튜닝에 사용
문서 청킹 + 임베딩 후 저장 → RAG 검색용으로 활용

실제 특성 파이프라인 메인 코드

@pipeline
def feature_engineering(author_full_names: list[str], wait_for: str | list[str] | None = None) -> list[str]:
    raw_documents = fe_steps.query_data_warehouse(author_full_names, after=wait_for)

    cleaned_documents = fe_steps.clean_documents(raw_documents)
    last_step_1 = fe_steps.load_to_vector_db(cleaned_documents)

    embedded_documents = fe_steps.chunk_and_embed(cleaned_documents)
    last_step_2 = fe_steps.load_to_vector_db(embedded_documents)

    return [last_step_1.invocation_id, last_step_2.invocation_id]

위 코드에서는 청크 전/후 데이터를 구분하여 각각 Vector DB에 적재한다. 병렬성 확보를 위해 GIL 제약을 피하고, 각 fetch 함수는 ThreadPoolExecutor 기반으로 실한다.

전체 파이프라인은 poetry poe run-feature-engineering-pipeline 명령어로 실행 가능 하다.

CH 5. 지도 학습 파인튜닝

LLM을 실제 응용 프로그램에 효과적으로 적용하기 위한 핵심 과정이 바로 지도 학습 기반 파인튜닝(SFT) 이다. 사전학습된 모델이 언어 일반 능력을 갖추고 있다면, SFT는 여기에 실전 적합성을 더해주는 역할을 한다. 즉, "일반적인 언어 이해"와 "실전 문제 해결 능력"의 간극을 메우는 것이 SFT의 목적이다.

이 장은 크게 세 부분으로 나뉜다. 1) 지시문 데이터셋 생성, 2) SFT 기법, 3) 파인튜닝 구현이다.

지시문 데이터셋: 파인튜닝에서 가장 어려운 부분

지도 학습 파인튜닝은 기본적으로 자연스러운 지시문-응답(instruction-response) 쌍이 필요하다. 하지만 원시 텍스트를 이러한 구조로 전환하는 것은 쉽지 않다.
이 과정은 거의 노가다 수준의 수작업이 필요하고, 무엇보다 데이터 품질이 매우 중요하다.

Open-Orca/SlimOrca (https://huggingface.co/datasets/Open-Orca/SlimOrca) 와 같은 오픈 데이터셋은 좋은 참고 예시이다.
LIMA (Less Is More for Alignment) 논문에 따르면, 700억 파라미터 모델도 고품질 데이터 샘플 1,000개만으로도 효과적으로 튜닝 가능하다.

SFT 목적에 따른 모델 유형

파인튜닝 주요 목적은 "작업 특화 모델" 과 "도메인 특화 모델" 을 개발하는 것이다.

작업 특화 모델(Task-specialized Model)
번역, 요약, 감정 분석 등 특정 작업에 최적화
→ 작은 모델(8B 이하)도 효율적
도메인 특화 모델(Domain-specialized Model)
의료, 법률, 금융, 엔지니어링 등 특정 분야 용어와 언어 패턴 학습
→ 도메인 복잡성에 따라 난이도 매우 상이

규칙 기반 필터링 기법

데이터 품질 관리를 위한 체계적인 방식

길이 필터링: 너무 짧거나 긴 응답 제외
키워드 필터링: 저품질 키워드 포함 여부로 제거
형식 검사: JSON, 코드 예제 등 구조 일관성 유지
중복 제거:
- 정확 중복
- 퍼지(Fuzzy) 중복 (MinHash 등)
- 의미론적 유사도 기반 중복 제거 (밀집 벡터 - Dense Vector 기반 등)

과적합을 방지하기 위해 유사 샘플 제거는 반드시 필요하다.

데이터 품질 평가와 자동화 방안

수작업은 시간과 비용이 많이 들기 때문에, 최근에는 LLM을 평가자로 삼거나, 보상 모델, 분류기 기반 예측 모델 등을 사용하는 방식이 시도되고 있다.

참고: ArmoRM-Llama3-8B-v0.1의 보상 모델 기반 아키텍처

LM Twin에서의 실제 적용

3장에서는 크롤링한 데이터를 기반으로 지시문 데이터셋을 자체 생성한다. → 여기엔 두 가지 큰 난제가 존재

크롤링 데이터의 비정형성
크롤링 가능한 기사 수의 한계

이를 해결하기 위해 합성 데이터 생성 파이프라인을 구성한다.

위 그림과 같이 원시 텍스트에서 지시문 데이터셋으로 합성 데이터 생성 파이프라인을 만들 수 있다. (실제 python 코드 예시가 이어진다.)

지시문 템플릿 구조화

지시문-응답 쌍은 모델별로 템플릿이 조금씩 다르다. 예를 들어 OpenAI GPT 계열과 HuggingFace 기반 모델은 프롬프트 구조가 다를 수 있다.

<|im_start|>system
당신은 유용한 AI 도우미입니다.
<|im_end|>
<|im_start|>user
토끼와 거북이 이야기를 요약해줘.
<|im_end|>
<|im_start|>assistant
거북이가 느리지만 꾸준히 가서 결국 토끼를 이깁니다.
<|im_end|>

SFT 기법 세 가지

(출처: https://huggingface.co/blog/mlabonne/sft-llama3)

전체 파인튜닝: 모든 파라미터를 다시 학습
LoRA (Low-Rank Adaptation):
- 학습 가능한 저랭크 행렬 도입
- 메모리 사용량 감소 / 빠른 학습 / 파괴 없는 튜닝
- 작업 간 빠른 전환 가능
QLoRA:
- LoRA + 양자화(quantization) 기법
- NF4 (4비트 커스텀 데이터 타입) 활용 → 소형 GPU에서도 학습 가능

학습 하이퍼파라미터 구성

학습 품질을 좌우하는 핵심 요소들

학습률 & 스케줄러
배치 크기 (Batch Size)
최대 시퀀스 길이 & 패킹 전략
에포크 수 (Epochs)
옵티마이저 선택 (AdamW 등)
가중치 감소(Weight Decay)
그레디언트 체크포인팅 (Gradient Checkpointing)

이후 장에서는 실제로 SFT 학습 코드 예시와 함께 실습이 이어진다. 이 장은 실제 SFT의 이론부터 실전 구현까지를 아우르는, 모델을 현실의 문제 해결 도구로 전환하는 과정의 핵심이다.

이후 CH 6 ~ 11 ...

책이 양이 엄청 방대하기에 이후 장은 핵심 주제에 대해서만 요약하고자 한다. 총 평에서 언급했듯 LLM 에 관심이 있다면, 해당 책 정도는 꼭 한 번 찍먹이라도 하면 도움이 많이 될 것 같다.

CH 6 선호도 정렬을 활용한 파인튜닝

단순한 SFT(Supervised Fine-Tuning)를 넘어서, DPO(Direct Preference Optimization) 같은 선호도 기반 학습 기법에 대한 얘기.

CH 7 LLM 평가, 모델 평가, RAG 평가, TwinLlama-3.1-8B 평가

모델의 성능은 정량 지표만으로는 절대 충분하지 않다는 것을 강조한다. 특히 RAG 시스템이나 커스텀 모델에서는, 단순 BLEU, ROUGE와 같은 전통적 자연어 지표보다 '실제 문제 해결 능력'이 훨씬 중요해진다.
이 챕터에서는 모델 평가, RAG 평가, TwinLlama-3.1-8B 모델 평가까지 다루며, 성능 지표와 주관적 평가의 균형을 어떻게 잡을 것인지에 대해 말한다. 개인적으로 기대했던 도메인 특화 파인튜닝에 대한 구체적 평가 방안은 부족했지만, 지표 설계 자체를 실험적으로 풀어내는 의도가 담겨 있었다.

CH 8 추론 최적화, 모델 최적화 전략, 병렬 처리, 양자화

모델 최적화 전략: 레이턴시 감소, 메모리 효율성 증대 / key value 캐싱
병렬 처리: multi-GPU 환경과 tensor 병렬, pipeline 병렬 등 다양한 방법론 소개
양자화: 특히 최근 논의가 활발한 int4, int8 양자화를 활용한 경량화 접근이 구체적으로 설명된다.

CH 9 RAG 추론 파이프라인, LLM Twin의 RAG 추론 파이프라인과 RAG 기법, 구현

CH 10 추론 파이프라인 배포, 모놀리식 & MSA, 오토스케일링

CHAPTER 11 DevOps, MLOps, LLMOps, LLM Twin 파이프라인을 클라우드에 배포와 LLMOps 적용기

DevOps: CI/CD 기반 배포 자동화
MLOps: 실험 추적, 모델 버전 관리, 재현성 보장
LLMOps: 프롬프트 버전 관리, 벡터 인덱스 동기화, 쿼리 추적 등 LLM 기반 시스템에 특화된 운영 전략
"운영 가능한 시스템"을 만들기 위한 최소한의 규칙을 지켜야 한다. 특히 클라우드에 올릴 때 발생하는 문제들, 실험 결과를 롤백하거나 재현해야 할 때의 장애 포인트들을 미리 체크해볼 수 있다.

LLM - Diffusion LLM vs Autoregressive LLM (근데 이제 논문을 곁들인...)

Sun, 15 Jun 2025 09:04:32 GMT

[ 글의 목적: 250615 기준, 현재 Diffusion LLM 의 상태와 최대한 쉽게 매커니즘 정리, 기존(Autoregressive) 과 비교 ]

Diffusion LLM

GPT 3.5 의 전율이 엊그제 같은데 벌써 2년이 넘었다니.. 올해 3월 인셉션(Inception Labs) Mercury 이 공개되면서 더 많은 대중의 관심을 끌게된 "dLLM". 기존 autoregressive 방식과 어디가 어떻게 얼마나 차이가 나는 걸까? 이제 "차세대 언어모델" 로 주목받으며 (또는 과장이라 비난 받기도 하고) 커져가는 diffusion llm 의 거시적인 흐름을 살펴보자!

1. 기존 LLM의 한계와 Diffusion의 등장 배경, 현 상태

기존 autoregressive LLM(ARM)들은 왼쪽에서 오른쪽으로 순차적으로 토큰을 생성하는 방식으로 작동한다. GPT 시리즈가 대표적인 예로, 각 토큰은 이전에 생성된 모든 토큰들을 조건으로 하여 다음 토큰의 확률 분포를 계산한다. (LLM - Intro to Large Language Models 참조)

# Autoregressive 생성 방식 (순차적)
P(x) = ∏ᵢ P(xᵢ | x₁, x₂, ..., xᵢ₋₁)

# 실제 생성 과정
x₁ = predict_next_token(prompt)
x₂ = predict_next_token(prompt + x₁)
x₃ = predict_next_token(prompt + x₁ + x₂)
# ... 순차적으로 계속

1) autoregressive 단점?!

하지만 이 방식은 태생적인 순차 병목현상을 가지고 있다. 각 토큰은 앞선 토큰들이 '모두 생성된 후' 에야 만들어질 수 있어서, (일반적인) 병렬화가 불가능하고 긴 시퀀스 생성 시 속도가 크게 저하 된다. ('추론모델' 도 사실 스스로 만들어낸 토큰을 스스로 참조하면서 다시 depth 있게 접근하는 방식이다.)

그래서 아래와 같은 한계가 있다.

속도 제약: 각 토큰은 앞선 토큰들이 모두 생성된 후에야 만들어질 수 있어 병렬화가 불가능(어려움)
누적 오류: 앞서 잘못 생성된 토큰이 뒤의 모든 토큰에 영향을 미침
유연성 부족: 중간 부분을 수정하거나 특정 부분만 재생성하기 어려움

prompt = "파이썬은"
x₁ = "어려운"  # 잘못된 생성
x₂ = "프로그래밍"  # x₁에 영향받아 계속 잘못된 방향
x₃ = "언어다"  # 전체적으로 부정확한 결과
# 중간 수정이 불가능 → 처음부터 다시 생성해야 함

이런 한계를 극복하고, ARM 자체의 통념을 깨기 위해 처음부터 Diffusion 형태로 학습한 LLaDA 와 같은 모델이 나왔다. 아래 "2. Diffusion LLM의 간단 메커니즘" 에서 다시 자세하게 살펴보자. 우선 당장의 "Diffusion LLM 의 성능은 어떤가?" 부터 살펴보자.

2) diffusion llm 의 요즘 성능 벤치마크

최근 재미있는 포인트는 Diffusion과 autoregressive 언어 모델 간의 성능 격차가 극적으로 줄어들었다고 한다. LLaDA 8B는 15개 벤치마크에서 LLaMA3 8B와 경쟁력 있는 성능을 달성하면서도 LLaMA3의 15T 토큰 대비 단 2.3T 훈련 토큰만 사용했다.

ARC-C 추론 작업에서 LLaMA3 8B의 82.4, LLaDA 8B의 88.5 로 우수한 성능을 보였으며, Mercury Coder는 HumanEval에서 88.0%를 달성하면서 초당 1,109 토큰을 생성했다. 이는 GPT-4o Mini의 59 토큰/초에 비해 압도적이다. (아래 사진)

PS) LLaDA의 88.5 점과 LLaMA3 82.4 얘기는 Supervised Fine‑Tuning(SFT) 이후를 말한다.

SEDD(Score Entropy Discrete Diffusion)는 기존 diffusion 모델보다 25-75% 개선된 perplexity를 제공하며, BD3-LMs는 LM1B 데이터셋에서 28.23 perplexity로 기존 방법 대비 13% 향상을 달성했다.

Mercury 시리즈는 NVIDIA H100 GPU에서 초당 1000토큰 이상을 생성 했다고 한다. - 이게 사실이라면 GPT-4o Mini보다 약 19배 빠르면서도 비교 가능한 코딩 성능을 유지한다. (아직 100% fact 인지는 판단 안 된 듯)

속도 우위는 단순한 처리량을 넘어선다. Diffusion 모델은 병렬 토큰 생성, 양방향 추론, 환각을 줄이는 반복적 개선을 지원한다. 특히 autoregressive 모델이 어려워하는 역순 작업에서 뛰어나며, 중국어 시 완성 벤치마크에서 LLaDA가 GPT-4o를 데모에서는 앞섰다고도 한다. 속도, 품질, 제어 가능성의 조합은 지연에 민감하고 높은 처리량이 필요한 애플리케이션에서 diffusion LLM을 최적의 선택으로 만든다.

PS) 논외지만, 최근 중국 논문의 피인용수가 폭발적으로 증가하고 있다고 한다 ㅎㅎ..

요약

LLaDA 8B: 단 2.3T 토큰으로 훈련했음에도, LLaMA3 8B (15T) 와 유사하거나 더 나은 성능(예: ARC-C에서 88.5 vs 82.4)을 보여줬다고 한다.
Mercury Coder 는 HumanEval 정확도 88.0%, 초당 1,109 토큰 생성을 한다고 "주장" 하고 있고, 이게 fact 라면 GPT-4o Mini (59 tokens/s) 대비 19배 이상 빠른 추론 속도가 된다.
병렬 토큰 생성, 양방향 추론, 반복적 개선 가능이 가능하고, 역순 생성 등 autoregressive 모델이 어려워하는 작업에서 유리하다.
*빠른 속도와 낮은 지연 시간 덕분에 고성능·실시간 처리 요구 앱에서 diffusion LLM이 유리할 수 있다.*

2. Diffusion LLM의 간단 메커니즘

사실 "Diffusion" 이라는 개념 자체가 이제와서 엄청 핫해진건 아니다. 15년대 부터 논문에 등장했다고 하는데, 진짜 "대중적으로 유명"해진건 "Stable Diffusion, DALL-E 2" 라고 생각된다. (근데 사실 학문적 논문은 20년이 전환점이라고 보인다.)

같은 맥락에서 Diffusion LLM은 이미지 생성에서 검증된 점진적 디노이징(denoising) 프로세스를 텍스트에 적용한 접근법이다. 완전히 마스크된 텍스트에서 시작하여 여러 단계에 걸쳐 동시에 여러 토큰을 정제해나가는 방식으로 작동한다.

1) 핵심 동작 원리

일단 기존의 diffusion model 을 조금 알아야 한다. Diffusion model 은 데이터를 만들어내는 deep generative model 중 하나로, data로부터 noise를 조금씩 더해가면서 data를 완전한 noise로 만드는 forward process(diffusion process) 와 이와 반대로 noise로부터 조금씩 복원해가면서 data를 만들어내는 reverse process 를 활용한다. (What are Diffusion Models?)

그림에서 예시로, "대략적인 윤곽(스케치) → 스케치 채우기 → 세부사항 → 마무리" 비유를 많이 한다. 이를 자연어에서 비유해 보자면 아래와 같은 흐름이다.

# 예시: "AI가 미래를 바꿀 것이다" 문장 생성하기

# 1단계: 모든 곳이 빈칸인 상태로 시작
"[____] [____] [____] [____] [____]"

# 2단계: 가장 확실한 단어들부터 채우기
"[____] [미래를] [____] [것이다] [____]"

# 3단계: 남은 빈칸들 채우기  
"[AI가] [미래를] [____] [것이다] [____]"

# 4단계: 마지막 빈칸 완성
"[AI가] [미래를] [바꿀] [것이다] [____]"

# 최종: 완성된 문장
"AI가 미래를 바꿀 것이다"

PS) 예시를 클로드한테 만들어 달라고 했다. 이제 클로드한테 선생님라고 해야할 듯...

이렇게 접근하면 아래와 같은 이점이 생긴다.

병렬 처리 가능: 기존 방식(첫 번째→두 번째→세 번째)과 달리 모든 위치를 동시에 처리 가능 하다.
전체 맥락 고려: 문장 전체의 흐름과 의미를 처음부터 고려할 수 있다.
오류 수정 기회: 여러 단계를 거치면서 잘못된 예측을 바로잡을 수 있다.

# Diffusion 생성 방식: 모든 위치를 동시에 고려
def generate_text_diffusion():
    # 1. 완전히 빈 상태로 시작
    text = ["[MASK]"] * 문장길이

    # 2. 여러 단계에 걸쳐 점진적으로 완성
    for 단계 in range(총_단계수, 0, -1):
        # 현재 상태에서 각 위치의 단어 예측
        예측결과 = model.predict(text, 현재_단계=단계)

        # 가장 확실한 예측부터 빈칸 채우기
        text = 확실한_예측만_반영(text, 예측결과)

    return text

2) 텍스트의 이산적 특성

텍스트의 이산적 특성 때문에 연속적인 이미지 확산과는 다른 접근이 필요하다. 텍스트는 다음과 같은 개별 단위들로 구성된다.

문자 단위: 'ㄱ', 'ㄴ', 'ㄷ' 또는 'a', 'b', 'c'
단어 단위: "사과", "바나나", "오렌지"
토큰 단위: "안녕", "하세요", "!"

각 단위는 명확히 구분되고, 그 사이에 "중간 상태"가 없다. 예를 들어 "사과"와 "바나나" 사이에 "사바나나" 같은 중간 단어는 의미가 없듯이 말이다. 이 특성 때문에 텍스트 처리에서 "특별한 접근이" 필요하다. 왜냐면 아래와 같인 이유때문이다!!

"딥러닝에서" 연속적인 숫자로 변환(임베딩)해야 한다.
"확률 모델링에서" 각 토큰별로 확률을 계산해야 한다.
"생성 모델에서" 한 번에 하나씩 토큰을 선택해야 한다.

3) Absorbing State

그래서 "Absorbing State" 와 같은 특별한 접근법이 등장했다.

사실 더 정확하게는 D3PM(2021)에서 absorbing state를 포함한 이산 확산 모델이 제안되었고, 여전히 성능 문제가 있었다. 하지만 SEDD(2023)에서 score entropy라는 새로운 손실 함수로 이를 크게 개선했다.

Google Research 등에서 발표한 D3PM, D3PM(Discrete Denoising Diffusion Probabilistic Models) 논문에서 Absorbing State는 "모든 토큰이 최종적으로 [MASK]라는 특별한 상태로 흡수되는 과정" 으로 정의한다. (Structured Denoising Diffusion Models in Discrete State-Spaces) 이 과정이 아래와 같다.

# 원본 문장
"파이썬은 배우기 쉬운 언어다"

# Forward Process: 점진적으로 단어들이 [MASK]로 변함
# t=1: "파이썬은 배우기 쉬운 [MASK]"  
# t=2: "파이썬은 [MASK] 쉬운 [MASK]"
# t=3: "[MASK] [MASK] [MASK] [MASK]"  ← 모든 단어가 흡수됨

# Reverse Process: 거꾸로 [MASK]에서 원래 단어 복원
# t=3→2: "[MASK] [MASK] [MASK] 언어다"
# t=2→1: "파이썬은 [MASK] 쉬운 언어다" 
# t=1→0: "파이썬은 배우기 쉬운 언어다"  ← 완전 복원

# https://pmc.ncbi.nlm.nih.gov/articles/PMC10909201/
# 공식 논문의 수학적 표현을 쉽게 번역하면!

# Forward Process (원본 → 마스크)
# αt = 시간 t에서의 원본 토큰 유지 확률
q(z_t | x) = αt * 원본토큰 + (1-αt) * [MASK]

# 예시: α₃ = 0.7이면
# 70% 확률로 원본 유지, 30% 확률로 [MASK]로 변환

# Reverse Process (마스크 → 원본)
# 신경망이 마스크된 토큰의 원본을 예측
p_θ(z_{t-1} | z_t) = 모델이_예측한_토큰_분포(z_t, t)

더 자세한 정보는 Simple and Effective Masked Diffusion Language Models 를 추천한다.

하지만, D3PM 에서는 Mean Prediction 방식의 한계, Concrete Score Matching 의 문제 등이 있었고, 이후 Stanford 와 Pika Labs 가 공동 개발한 Score Entropy Discrete Diffusion (SEDD) 은 이산 공간에서의 score matching 이론적 기반을 마련했다. 특히 음수값 문제, 확장성 문제, 연속시간 근사 문제를 해결하는 새로운 score entropy 손실 함수를 도입하여, 이산 데이터(특히 자연어)에 대한 Diffusion 모델의 이론적 토대를 확립했다.

이후 현재 LLaDA 까지 발전되어 왔다.

LLaDA의 학습 및 추론 방식을 도식화 하면 위와 같다. 학습 과정에서는 입력에 점진적으로 잡음(Noise)을 추가하여 마스킹 토큰을 생성고 입력 전체가 마스킹 되면, 다시 원본 문장을 점진적으로 복원한다. 추론 과정에서는 프롬프트가 아닌 응답 부분만 마스킹 처리한 후, 이 부분을 예측하는 방식을 통해 응답을 생성한다.

색이 어두울수록 나중에 예측된 토큰이며, 밝을수록 일찍 예측된 토큰이다.

Google DeepMind의 실제 구현

Google DeepMind의 Gemini Diffusion 모델은 이 매커니즘을 바탕으로 구현됐다. "전통적인 autoregressive 모델이 한 번에 하나씩 토큰을 생성하는 반면, diffusion 모델은 노이즈를 단계적으로 정제하여 출력을 생성한다"고 설명한다. - https://deepmind.google/models/gemini-diffusion/

4) Diffusion 이 만능인가여?!

결론 부터 보자면 아직은 시기 상조라고 보여진다. 하지만 핵심은 "특정 섹터에서는 기존 방식의 가격대비 성능을 뛰어넘고" 있다.

Autoregressive의 여전한 강점

생태계 성숙도
- HuggingFace Transformers, vLLM, TensorRT-LLM 등 완성된 최적화 도구들 수천 개의 사전훈련된 모델과 광범위한 커뮤니티 지원
- 프로덕션 검증된 배포 인프라 (Kubernetes operators, monitoring tools)
확장성과 품질
- GPT-4, Claude, Gemini 등 100B+ 매개변수의 (엄청 라지스케일의) 대규모 모델들
- 복잡한 추론, 긴 맥락 이해에서 여전히 우수한 성능
- Chain-of-thought, few-shot learning 등에서 자연스러운 강점.
예측 가능성
- 토큰별 순차 생성으로 디버깅과 해석이 용이
- 확률 분포가 명확해서 불확실성 정량화가 쉬움 (물론 이게 어떻게 black box 확률을 계산했냐를 알 수 있다는 뜻은 아님)
- 길이 제어가 자연스러움 (EOS 토큰까지 생성)
특정 작업에서의 우위
- 대화형 AI에서 자연스러운 turn-taking
- 코드 생성에서 논리적 흐름 유지
- 창작 글쓰기에서 일관된 스타일 유지

Diffusion의 현실적 한계

훈련 복잡성
- 노이즈 스케줄 튜닝, 마스킹 전략 등 하이퍼파라미터 민감도 높음
- Autoregressive 대비 수렴 안정성 낮음
- 디버깅이 어려운 확률적 과정
제한된 규모
- 현재 대부분 8B 이하, 100B+ 규모 모델 부재
- 스케일링 법칙이 아직 완전히 검증되지 않음
특정 작업에서의 약점
- 매우 긴 시퀀스 생성에서는 여전히 느림
- 순차적 추론이 중요한 수학 문제 해결에서 한계
- 실시간 대화에서 응답 품질 vs 속도 트레이드오프

요약

고속 대량 처리: Diffusion 이 유리할 수 있음
복잡한 추론: 아직 Autoregressive 여전히 강세로 보임
안정적 프로덕션: (시장 성숙도를 포함하면) Autoregressive가 더 안전
비용 효율성: Diffusion이 유리 (동일 성능 대비를 의미)

3. 모델 중심 요약 및 정리

주관을 100% 담은 Diffusion LLM 을 위한 논문/모델 주의 시계열 정리

[2021.07] Google Research + MIT = D3PM: Discrete Denoising Diffusion Probabilistic Models 발표
[2023.10] SEDD (Score Entropy Discrete Diffusion)
[2023.12] Apple, PLANNER, Latent Language Diffusion Model 발표 (NeurIPS 2023)
[2024.06] Cornell Tech의 Volodymyr Kuleshov 그룹, MDLM - Masked discrete Diffusion Language Model
[2025.02] LLaDA 8B 공개, *단 2.3T 토큰으로 학습했음에도 LLaMA3 8B (15T) 에 밴치마크 비교 우위*
[2025.02] Inception Labs: Mercury Coder 시리즈
[2025.03] BD3-LMs: Block Discrete Diffusion 기반의 language model
[2025.05] Google DeepMind: Gemini Diffusion 모델 구조 공개 (Google I/O)

출처

[책 리뷰] 주니어 백엔드 개발자가 반드시 알아야 할 실무 지식 - 최범균

Thu, 29 May 2025 16:03:22 GMT

[ "한빛미디어 서평단 <나는리뷰어다> 활동을 위해서 책을 협찬 받아 작성된 서평입니다." ]

주니어 백엔드 개발자가 반드시 알아야 할 실무 지식

최범균: 나이를 먹어서도 백발에 개발을 하고 싶은 코딩을 좋아하는 개발자다. 좋은 책을 쓰는 것을 꿈꾸고 있고, 꾸준히 블로그와 브런치에 글을 쓰고 있다. ‘스프링4 프로그래밍 입문’, ‘JSP 2.3 웹 프로그래밍’, ‘개발자가 반드시 정복해야 할 객체 지향과 디자인 패턴’ 등의 책을 집필했다. https://javacan.tistory.com/ 블로그와 https://www.youtube.com/@madvirus 유투브 열심히 지금까지도 지식공유를 해주신다!

코딩을 할 수 있게 된 것일 뿐: 실무에서 마주한 주니어 백엔드 개발자의 첫 위기

리뷰

책 소개에 나오는 사례가 완벽하게 학부생때 경험한 시나리오였다. 커넥션풀, DBMS 에 대한 낮은 이해도, 사실 "연결"이 왜 메모리를 먹는지도 잘 몰았던 시절, 연결에 왜 timeout 을 줘야하는지도 몰랐던 그 때가 바로 떠올랐다.

개인적으로 무엇보다 개발은 실수를 하며 심연을 해맬때 결국 가장 큰 성과를 얻었다. ~~근데 지금도 심연에 있는 기분이 들때가 많다..~~ 결국 오답노트가 공부에 가장 큰 도움이 되었다. 이 책은 *그 좋은 오답노트 수첩을 훔쳐보는 기분이다.* 시니어 분들에게는 향수와 가이드할 목차를, 주니어 분들에게는 겪어 보지 못한 실수도 같이 해보며 따라갈 수 있는 실마리를 줄 것 같다.

인스턴트가 넘쳐나는 LLM 시대에 (어쩌면 벌써) Classic 을 읽는 기분이다.

- 성능의 근본 개념과 접근법을 다룬 2장,
- 실질적이고 깊이 있는 DB 이야기로 가득 찬 3장,
- 프레임워크를 떠나 API 서버와 인프라 전반을 다루는 4장 (외부 API 연동, 동시 요청 제한, 서킷 브레이커, HTTP 커넥션 풀, 연동 서비스 이중화 등),
- 이어서 코드 수준에서 동기/비동기, 스레드 처리, 메시징, 트랜잭션 아웃박스, CDC까지 짚어주는 5장,
- 레이스 컨디션, 락과 세마포어, DB 동시성 처리 등을 다룬 6장,
- IO 병목과 네트워크 관점에서의 자원 효율화 방식을 설명한 7장,
- 실무에서 반드시 필요한 보안 기초(시큐어 코딩 포함)를 정리한 8장,
- 리눅스 기반의 OS 및 서버에 대한 기본 지식(계정 권한, 디스크 용량, 크론 등)을 다룬 9장,
- 네트워크 기본 개념을 복습하는 10장,
- 그리고 마지막으로 자주 사용되는 서버 구조 및 설계 패턴(MVC, 계층형 아키텍처, DDD, 마이크로서비스, CQRS 등)을 다룬 11장까지.

각 장은 위와 같은 구성으로, 2장을 시작으로 실무에서 꼭 짚고 넘어가야 할 체크포인트들을 순차적으로 다루며, 각 주제에 필요한 핵심 사전 지식을 자연스럽게 덧붙이는 방식으로 전개된다. 요즘 주니어 개발자를 위한 가이드는 확실히 잘 나오는 듯하다... ~~그런데 왜 중니어, 시니어를 위한 책은 없는 걸까 ㅠㅠ~~

물론 이 책이 모든 부분을 CS/OS 레벨이나 네트워크의 HW나 DB의 스토리지 레벨까지 깊게 파고들지는 않지만, 그 대신 얕고 넓게, 무엇보다 “실제로 겪은 실무 사례”와 함께 폭넓게 정리되어 있다는 점이 강점이다. 사실 이런 책은 실마리만 잘 잡아주면 된다. 이후의 depth는 각자의 몫이니까.

더욱이 조금 더 주관적인 의견을 덧붙이자면, DBMS(특히 인덱싱과 쿼리 최적화), 네트워크, 리눅스 기반 OS 활용만 제대로 마스터해도 대부분의 서비스 이슈는 어떻게든 해결 가능하다고 믿는다. 하나 덧붙이자면 서비스로직 처리할때 비동기, 동시성, lock 개념 정도..?

마무리하자면, 이 책은 마치 옆자리 팀장님이 “나는 그럴 땐 이렇게 했었어~” 하며 빠르게 구두로 알려주는 느낌이다. 그리고 그 말 한마디에 문득 실마리가 풀리던, 그 익숙한 순간처럼 읽힌다.

~~근데 아주 솔직히 내가 진짜 0-1년차 였다면 이 책이 한 숨에 읽히진 않았을 것 같다. 그리고 마냥 웃으면서 볼 수도 없었을 것 같고 ㅎㅎ~~

목차별 리뷰

2장 느려진 서비스, 어디부터 봐야 할까

1) 처리량과 응답 시간

API 호출이라는 단순한 흐름(application → server → DB)을 바탕으로 성능을 바라보는 시각은 명쾌하다. 응답 시간이라는 것은 단순히 서버 코드만의 문제가 아니며, TTFB(Time to First Byte), TTLB(Time to Last Byte) 처럼 전체 체인을 기준으로 측정되어야 한다. 특히 파일 다운로드의 경우, 두 시간 차이가 클 수 있다. 아래 글 한번 읽어보길 추천

구글이 "100ms의 지연이 검색 횟수를 0.2% 감소, 400ms 지연은 0.4% 감소시킨다"는 발표를 한 적 있다. (응답 시간)퍼포먼스는 사용자 경험(UX)의 핵심이다.

실제 서비스에서의 서버 처리 시간은 단순히 비즈니스 로직을 수행하는 시간이 아니라, DB 커넥션, 외부 API 연동, 응답 데이터 생성까지를 포함한다. 결국 이 모든 항목의 병목을 파악하려면 구간별 실행 시간을 측정하고 분리 분석하는 능력이 필요하다.

특히 TPS(Transaction Per Second)를 기준으로 병목을 판단하는 관점은 실무에서 유용하다. 단순히 요청 수를 보는 것이 아니라, "얼마나 처리 완료됐는가?" 를 보는 기준은 진짜 서비스를 운영하는 입장에서 중요하다.

시간당 시스템 처리하는 작업량, TPS(transaction per second) or RPS(request per second) - 여기서는 주로 TPS ("처리 완료" 가 중요)

동시에 처리할 수 있는 요청을 증가 시키던지, 한 개 요청을 처리하는 시간을 단축 시키던지의 방향으로 TPS를 높여야 하고, 사실 측정을 위해서는 모니터링이 중요하다.

2) 서버 성능 개선 기초

서버의 성능 저하 증상은 다음과 같이 나타난다.

전체 응답 시간이 10초 이상으로 증가
연결 시간 초과
서버 재시작 후 일시 회복되나 반복 발생

이 경우 단순히 서버를 재시작하는 것으로는 근본적인 해결이 안 된다. 정확한 병목 지점을 찾아내야 하고, 이를 위해선 구간별 실행 시간을 측정 할 수 있어야 한다.

수직 확장(Scale-up): CPU, RAM 등을 늘려 한 서버의 스펙을 강화
수평 확장(Scale-out): 서버 대수를 늘리고, 로드밸런서를 통해 분산 처리

긴급한 상황에서는 수직 확장이 효과적일 수 있지만, 지속 가능한 확장은 수평 확장이며, 특히 다수의 요청을 안정적으로 처리하기 위해 필수적이다.

3) DB 커넥션 풀

DBMS도 결국 서버다. 요청이 들어올 때마다 DB에 새로 접속하면 비효율적이다. 그래서 DB 커넥션 풀을 이용해 일정 수의 커넥션을 유지하고 재활용한다. 커넥션 풀을 구성할 때 고려해야 할 주요 요소는 다음과 같다.

최대/최소 커넥션 수
커넥션 유지 시간 (타임아웃)
커넥션 대기 시간

(관련해서 Django 5.1의 커넥션 풀 적용기를 참고하면 실무 적용 힌트를 얻을 수 있다.) 예시로, 커넥션 풀 크기: 5, 쿼리 처리 시간: 0.1초 → 초당 최대 50쿼리 처리 가능하다.

대기 시간이 3초를 초과한다면, 요청을 거절하거나 "잠시 후 다시 시도" 메시지를 보내는 것이 더 나은 사용자 경험일 수 있다.

4) 캐시 전략

DB 조회 자체를 줄이기 위해 캐시를 도입하는 것도 병목 개선의 중요한 방법이다. 책에서 캐시의 크게 두 유형을 소개한다. 있다

로컬 캐시 (프로세스 내부 메모리 기반, 빠르지만 스케일링 어려움)
리모트 캐시 (redis 등 외부 서버, 느리지만 공유 가능)

각각 장단점이 정반대이므로 상황에 맞게 선택해야 한다. 예를 들어 트래픽이 순간적으로 튀는 경우에는, 사전에 데이터를 캐시에 미리 올려두는 "워밍(warming)" 전략이 유효하다.

단, 캐시 무효화(invalidation) 가 매우 중요하다. 원본 데이터가 변경되었을 때 캐시도 함께 갱신되거나 삭제되지 않으면 오히려 더 큰 문제가 된다.

대용량 API 응답 시에는 GC(Garbage Collection) 및 메모리 사용량도 주의해야 한다. Java에서는 스트림 방식, Go나 Rust로 전환하는 등 GC 부담을 줄이기 위한 다양한 접근이 있다. (디스코드 사례)

5) 응답 데이터 압축

응답 시간의 상당 부분은 데이터 전송 시간이 차지한다. 네트워크 속도는 제어하기 어렵지만, 전송할 데이터의 크기는 줄일 수 있다.

HTML, CSS, JS, JSON과 같은 정적 텍스트는 gzip 압축 을 통해 최대 70%까지 줄일 수 있다.
HTTP의 Accept-Encoding 헤더를 통해 브라우저와 서버 간 압축 여부 협상이 가능하다.

이는 사용자 응답 속도 개선뿐 아니라 클라우드 전송 비용 절감에도 매우 효과적이다. 정적 파일은 가능하면 CDN을 활용해 가까운 곳에서 받아오게 하고, 브라우저 캐시를 최대한 활용해야 한다. 이 또한 응답 시간과 비용 모두를 줄이는 데 도움이 된다.

6) 대기 처리

일부 서비스는 특정 시간에 엄청난 트래픽이 몰린다. (ex. 콘서트 티켓 예매, 이벤트 시작 직후 등) 이때 단순한 스케일링(up or out)으로는 대응이 어렵고, 오히려 단순 비용만 증가할 수 있다. 따라서 "현재 수용 가능한 요청만 받고 나머지는 대기시키는" 방식이 실용적이다.

이런 방식은 마치 은행의 창구 번호표 시스템과 같다. 대표적인 방식은 유량 제어(rate limiting) 가 있고, 이는 보통 미들웨어나 클라이언트 사이드에서 구현한다.

3장 성능을 좌우하는 DB 설계와 쿼리

이 장은 신입이라면! 쿼리 실행 계획을 직접 비교해보며 따라가 보는 것을 추천한다! 예시도 실무에 맞게 잘 준비되어 있어 Follow-up 하며 익히기에 적절하다. ~~PS) 개인적으로 너무 귀에 딱지가 앉은 내용들이라 많이 함축했다.~~

데이터 양이 조금만 많아져도 Full Table Scan 은 쿼리 성능에 큰 영향을 미친다. 이는 DB가 조건 없이 테이블의 모든 데이터를 순차적으로 읽는 방식인데, 단일 인덱스 또는 복합 인덱스를 적극적으로 활용해 피해야 한다.

단일 인덱스: 하나의 컬럼만을 기준으로 한 인덱스
복합 인덱스: 두 개 이상의 컬럼을 묶어 조건절에 활용
선택도가 높은 컬럼: 중복 값이 적은 컬럼일수록 인덱스 효과가 크다.
커버링 인덱스 (Covering Index): 실행하는 쿼리에 필요한 모든 컬럼을 포함한 인덱스.
- 예: SELECT name, age FROM users WHERE email='abc@xyz.com'의 경우 (email, name, age)로 인덱스를 구성하면 쿼리 수행 시 테이블을 접근하지 않아도 된다.

다만, 인덱스는 추가/변경/삭제 연산 시마다 쓰기 성능에 오버헤드가 발생한다. 항상 트레이드오프를 고려해야 한다.

자주 호출되는 Aggregation 쿼리(합계, 카운트 등)는 실시간 계산보다 사전 집계해서 저장하는 방식이 효과적이다.

예: 사용자의 총 좋아요 수, 누적 조회수 등을 별도 필드에 미리 저장
단, 집계 값이 변경되는 트리거가 있는 경우, 동기화 로직이 필요하다.

서비스가 장기 운영되면 데이터 양이 계속 누적된다. 이 중 자주 조회되지 않는 오래된 데이터는 별도 테이블로 분리하거나, 이관/보관 처리하는 것이 효율적이다.

1) DB 인프라 확장 - Primary / Replica 구조

읽기와 쓰기 분리: Primary 는 쓰기 전용, Replica 는 읽기 전용으로 나눠 부하를 분산
단, 아래와 같은 주의점이 존재한다:

Replica는 Primary의 변경 사항을 비동기적으로 복제하기 때문에, 지연이 발생한다.
따라서 인증/인가, 사용자 세션 등 실시간성이 중요한 SELECT는 반드시 Primary에서 수행해야 한다.

쿼리 타임아웃 & 배치 작업 시 청킹(Chunking)

장시간 실행되는 쿼리는 타임아웃을 유발할 수 있으므로, 대용량 데이터 처리 시에는 청크 단위로 나눠서 처리한다.
특히 배치 작업에서는 병렬 처리 또는 페이지 단위로 나눠서 로직을 구성하는 것이 필수적이다.

DBMS는 동시에 허용할 수 있는 최대 연결 수가 정해져 있다.

연결 수 초과는 전체 서비스에 장애를 유발할 수 있으므로, 커넥션 풀 또는 연결 수 제한 설정을 잘 조정해야 한다.

여러 데이터 수정이 정합성에 민감한 작업이라면 반드시 하나의 트랜잭션으로 묶어야 한다.

BEGIN → 작업들 → COMMIT or ROLLBACK
트랜잭션을 적절히 활용하면 장애 복구 시에도 데이터 무결성을 보장할 수 있다.

2) 서비스 중인 DB 테이블 수정 시 특히 주의할 점

MySQL 은 테이블 구조를 변경할 때, 실제로는 새로운 테이블을 생성한 뒤, 기존 데이터를 복사하고, 이후 기존 테이블을 새 테이블로 교체하는 방식으로 작동한다.

이 과정에서 UPDATE, INSERT, DELETE 등의 DML이 일시적으로 허용되지 않을 수 있다.
운영 서비스에서 테이블 변경이 병목이나 서비스 중단으로 이어질 위험이 크다.

PostgreSQL 은 다행히 대부분의 구조 변경(ADD COLUMN, ALTER TYPE, RENAME 등)이 내부 메타데이터 변경으로 처리되어, Non-blocking(비차단) 방식으로 작동하는 경우가 많다. (PS. 이 책의 DBMS 기준은 대부분 MySQL 을 말한다.)

그러나 컬럼 타입 변경 등 일부 연산은 여전히 테이블 전체를 리라이트(재작성)할 수 있으므로 사전 확인 필요.
운영 중인 DB 테이블에 변경을 가할 경우, DBMS마다 동작 방식과 영향 범위가 다르므로 반드시 사전 검증이 필요하다. 무중단 배포를 위해서는 마이그레이션 절차의 자동화와 사전 롤백 시나리오도 함께 준비하는 것이 바람직하다.

4장 외부 연동이 문제일 때 살펴봐야 할 것들

외부 시스템이 우리보다 성능이 떨어지거나 트래픽을 감당하지 못할 경우가 많다. 이때 우리는 '서버'가 아니라 '클라이언트'가 되는 셈이다. 이 입장에서 체크 할 것을 알려주는 장이다.

1) 외부 API 호출시 타임아웃 설정은 필수

타임아웃이 설정되어 있지 않으면, 외부 API가 응답을 주지 않아도 무한정 기다리게 된다. 그 결과

전체 시스템 처리량이 급격히 하락하고
커넥션 풀 고갈 → 요청 처리 지연
최악의 경우 서비스 다운으로 이어진다

따라서 반드시 타임아웃을 명확히 설정해야 하며, 실무에서는 기본적으로 짧게(수 초 내외) 잡고, 예외적인 경우만 늘려야 한다.

2) 재시도(Retry) 전략

재시도는 단순히 '다시 해보자'가 아니라 조건과 설계가 중요한 전략이다. 책에서는 재시도 가능한 조건은 다음 세 가지를 제시한다.

단순 조회(읽기) 기능일 때
연결 타임아웃이 발생했을 때
멱등성(idempotent)을 보장하는 변경 기능일 때

읽기 타임아웃(read timeout)은 실제로 API 요청이 두 번 발생하게 되므로, 외부 비용(예: 과금)이 발생할 수 있으면 신중하게 판단해야 한다.

재시도는 ‘몇 번’, ‘얼마 간격으로’가 핵심이다. 무한 재시도는 곧 Retry Storm이라는 안티패턴으로 이어지며, 외부 시스템을 더 위험하게 만들 수 있다.

외부 API 호출에 제한이 있거나 트래픽 보호가 필요할 경우

초과 요청에 대해 503(Service Unavailable)을 즉시 응답
벌크헤드(Bulkhead) 패턴을 적용하여, 문제가 생긴 외부 API와 나머지 시스템이 영향을 분리하여 받도록 설계

3) 서킷 브레이커(Circuit Breaker)

전기 누전차단기처럼, 외부 시스템이 일정 횟수 이상 실패하면 즉시 실패(Fail Fast)로 전환해 전체 시스템을 보호하는 방식이다.

초기 상태: 닫힘(Closed) → 정상 호출
일정 실패율 이상: 열림(Open) → 호출 금지
일정 시간 후: 반열림(Half-Open) → 일부 호출로 상태 확인

4) 외부 API 응답 지연과 DBMS 커넥션 고갈

외부 API의 응답이 늦어질 경우, 그 응답을 기다리는 동안 DB 커넥션을 점유하게 되면

DBMS 커넥션 풀이 고갈되고
후속 요청들은 대기 → 응답 시간 증가
결국 타임아웃 및 서비스 에러로 이어짐

커넥션은 최대한 빨리 반납하는 게 핵심이다. 외부 연동과 DB 작업은 명확히 분리하고, 가능하면 응답 대기 전에 커넥션부터 반납해야 한다.

5) HTTP 커넥션 풀과 웹서버 고려

웹서버 레벨에서의 커넥션 풀 관리도 중요하다. 예를 들어, keep-alive 설정이 적절치 않으면 서버 리소스를 불필요하게 점유하게 된다. 클라이언트와의 커넥션도 ‘적절한 수명과 갯수 제한’이 필수다.

5장 비동기 연동, 언제 어떻게 써야 할까

*개인적으로 5장부터 7장은 처음 개발을 배우던 나에게 항상 "벽" 처럼 느껴졌던 부분이다.* 동기와 비동기, "왜 비동기 처리를 하지?" 부터 비동기 처리하면서 고민해야 할 동시성 이슈, 또한 동시 실행에 대한 제어와 제한 이 모든게 따라온다.

참고로 대부분의 예시는 java 이다. python 에서도 사실 코루틴, 경량 스레드 (또는 직접 thread를 만드는) 측면에서 아주 동일하게 접근 가능하며, 더욱이 node 는 Asynchronous (이벤트 루프) 자체에 집중하고 따라가면 될 것 같다.

5장은 아래 사진 한 장이 시작이자 끝이다 ㅎ

쇼핑몰에서 주문이 들어오면 판매자에게 푸시 보내기
학습을 완료하면 학생에게 포인트 지급하기
컨텐츠 등록할 때 검색 서비스에도 등록하기
인증 번호를 요청하면 SMS로 인증 메시지 발송하기

등 위 케이스에서 API 가 "동기" 로 응답 또는 외부 서비스 (API) 응답까지 기다릴 필요가 있을까? 이 부분 부터 시작이다. 대게 아래와 같은 특징을 가진다.

연동의 시차가 생겨도 문제가 크지 않다.
실패했을 때 재시도가 가능하다.
나중에 수동으로 처리해도 크리티컬하지 않다.
실패해도 무시해도 된다. (단순 알림)

이러한 전제를 바탕으로, 이 책은 여러 실전적 비동기 처리 방식들을 소개한다.

1) 별도 스레드로 실행하기

대표적인 예시로는 Spring Framework의 @Async 어노테이션을 통해 특정 메서드를 비동기 실행하는 방법이 있다. 다만 주의할 점은 다음과 같다:

try-catch 구문 사이에 비동기 코드가 껴 있으면 에러 전파가 안된다
즉, 트랜잭션 롤백이 되지 않음 → 호출부가 아닌 정의부에서 에러처리 필요
그리고 중요한 사실: 스레드는 메모리를 많이 사용한다

이러한 점을 간과하면 비동기 처리가 오히려 시스템 리소스를 잡아먹는 병목이 될 수 있다.

2) 메시징

아주 주관적으로 나의 경우 "메시징 시스템, 이벤트 기반 아키텍쳐" 를 배우고 이해하는 순간 진짜 새로운 세계가 열렸던 기분이 들었었다. (메시징 관련 시리즈 보러가기)

Producer: 메시지를 발행 Consumer: 메시지를 구독하고 처리

Producer는 유실에 대비해야 하며, 타임아웃과 실패에 대한 에러 처리 로직을 마련해야 한다.
예를 들어, 재시도할 수도 있지만, 중복 처리를 피하기 위한 고유 식별자 부여가 필수적이다.
재시도 → 중복 → 소비자 쪽에서 idempotent하게 처리
로그를 남긴다면 후처리 가능한 형태의 데이터로 남겨야 한다

메시지는 일반적으로 아래 2가지로 개념적 분리를 한다

이벤트(Event): "무엇이 발생했다"를 알리는 것 (ex: 주문됨, 배송완료됨)
커맨드(Command): "무엇을 해달라"는 요청 (ex: 포인트 지급)

3) 글로벌 트랜잭션이 필요한 이유

단일 서비스에서 여러 리소스를 조작할 때, 또는 분산 환경에서 여러 DB나 시스템을 하나의 트랜잭션처럼 다뤄야 할 때 등장하는 개념이 바로 글로벌 트랜잭션이다.

사용자가 상품을 주문하면,
- 주문 DB에 저장하고
- 동시에 푸시 알림을 메시지 큐에 넣어야 함
그런데 푸시 메시지를 먼저 보냈는데 주문이 실패했다면?
- 알림은 갔지만 실제 주문은 존재하지 않는 비정상 상태가 된다. → 이를 방지하려면 글로벌 트랜잭션(2PC 또는 Outbox 패턴) 같은 처리가 필요하다.

위 상황을 아래와 같이 접근할 수 있다.

주문 처리 트랜잭션이 끝난 후, 메시지를 메시지 큐에 전파
메시지 큐에 넣는 로직은 트랜잭션 외부에서 처리
Outbox 테이블에 먼저 메시지를 적재한 후, 커밋 후에 큐로 전달

4) 궁극적 일관성

분산 시스템의 핵심 개념 중 하나다.

데이터 복제가 실시간은 아니지만, 결국 언젠가는 일치하는 상태에 도달한다
이 과정에서 일시적 불일치가 발생할 수 있음 → 비동기 메시징도 이와 유사

5) CDC(Change Data Capture)

DB의 변경사항을 감지하여, 외부 시스템과 연동하는 비동기 처리 기술
예시: Postgres → Kafka → ELK Stack으로 전파
실제로 아래 두 글에서 Logstash 기반의 CDC 와 Debezium 기반 CDC, 아래 2가지 글을 작성한 적이 있는데 해당 책 내용과 참조하면 많은(?) 도움이 되지 않을까 한다 ㅎㅎ

6장 동시성, 데이터가 꼬이기 전에 잡아야 한다

서버가 동시에 들어오는 수많은 요청을 어떻게 처리할 것인가는 백엔드 실무에서 매우 중요한 주제다. 특히 하나의 공유 자원에 여러 요청이 동시에 접근하게 되면, "동시성(concurrency)" 문제가 발생하고, 이는 쉽게 데이터 꼬임 또는 경쟁 상태(race condition) 로 이어질 수 있다.

대표적인 예로는 투표 시스템이 있다. 특정 API에 요청이 몰릴 경우, 실제로는 투표 수가 100번 증가했어야 하는데, 중간에 요청이 섞이며 50번만 반영되는 식의 문제다. 이런 문제를 피하기 위한 동시성 제어는 시스템 전반에서 이루어져야 한다.

1) 프로세스 수준에서의 동시 접근 제어

서버는 일반적으로 다음 두 가지 방식 중 하나로 동시 요청을 처리한다:

스레드 기반 처리: 각 요청마다 독립된 스레드를 생성하거나 할당하여 처리
비동기 IO 기반 처리: 이벤트 루프 기반으로, IO 작업이 완료될 때 콜백으로 응답을 처리

공유 자원에 대한 접근은 반드시 임계 영역(critical section)을 정의하고, 해당 영역에 접근하는 코드에 대해서는 락(lock)을 걸어야 한다. 이 흐름은 다음과 같다:

잠금 획득 → 임계 영역 접근 → 잠금 해제

Java에서는 synchronized, ReentrantLock 등이 활용되고, 이를 일반화하면 mutex(mutual exclusion)라 한다.

또한 세마포어(semaphore)를 활용하면, 특정 자원에 동시 접근 가능한 스레드 수를 제한할 수 있다. 예를 들어, Velog Dashboard V2의 비동기 배치 시스템 에서는 세마포어 형태로 최대 요청 수를 제한하고 있다.

또 하나의 좋은 전략은 아예 공유 자원을 사용하지 않는 것, 즉 불변(immutable) 객체를 사용하는 방식이다. 불변 객체는 상태 변경 자체가 없으므로 동시 접근 제어가 필요 없다.

2) DB와 관련된 동시성 제어

동시성 문제는 DB에서도 동일하게 나타난다. 이에 대한 대표적인 접근법은 아래 두 가지로 나뉜다:

비관적 잠금(Pessimistic Locking)
- "실패할 가능성이 높다"는 가정 하에, 미리 다른 접근을 막는 방식
  → 데이터에 베타적 잠금(exclusive lock)을 걸어, 한 번에 하나의 클라이언트만 접근 가능
낙관적 잠금(Optimistic Locking)
- "성공할 가능성이 높다"는 가정 하에, 변경 전후 값을 비교해 충돌 여부를 판단
  → 실제 락 없이 version 필드나 updated_at 비교로 처리

특히 트랜잭션 범위 내에서 외부 시스템(예: PG사, 결제 API)과 연동해야 하는 경우에는, 비선점 낙관적 방식보다는 선점 비관적 방식이 더 안전하다. 예컨대 결제 취소까지 함께 고려되어야 한다면, 먼저 확실하게 잠금을 걸어야 한다.

또한 증분 쿼리 방식(예: UPDATE SET count = count + 1)은 DBMS가 원자적으로 처리해주는지를 반드시 확인해야 한다. 일부 DB는 이조차도 race condition을 일으킬 수 있다.

3) 잠금 사용 시 주의 사항

잠금을 사용할 때 반드시 고려해야 할 중요한 이슈는 다음과 같다!

잠금은 반드시 해제되어야 한다.
잠금을 놓치면, 해당 자원은 영구적으로 접근 불가해지며 시스템이 멈춘다.
대기 시간 설정을 명확히 해야 한다.
무한 대기 대신 timeout을 명시해줘야 대기하는 스레드가 적절히 포기할 수 있다.
교착 상태(deadlock)를 피하자.
예: 스레드 A는 잠금 X를 가지고 Y를 기다리고, 스레드 B는 Y를 가지고 X를 기다리는 상황
→ 이를 피하기 위해 잠금 순서를 일관되게 정하거나, 타임아웃 및 실패 처리 로직을 함께 두는 것이 중요하다.

4) 동시성 회피 전략: 단일 스레드 처리

사실상 가장 간단하고 강력한 전략은 바로 단일 스레드 처리(single-threaded processing) 이다.
예를 들어, Redis 기반 큐, Kafka consumer group, Node.js의 이벤트 루프 모델 등은 모두 기본적으로 단일 스레드 방식으로 설계되어 동시성 문제 자체를 회피하는 전략이다.

7장 IO 병목, 어떻게 해결하지에서는

네트워크 IO 에 대한 이해와 자원 효율화, 특히 가상 스레드 얘기,
논블로킹 IO 로 성능 올리는 방법과 언제 무엇을 트레이드 오프하냐에 대한 얘기를 다룬다.

8장 실무에서 꼭 필요한 보안 지식에서는

인증과 인가부터 토근 보안, RBAC(Role Based Access Control) 구조, 데이터 암호화,
Hash-based Message Authentication Code (무결성 인증 보장), 방화벽, 감사 로그, 비정상 접근 처리를 다룬다.

9장 최소한 알고 있어야 할 서버 지식에서는

대부분 OS 와 shell 기반 인프라 관리에 대한 얘기이며, 진짜 이 정도 기본은 해야한다고 매우 동감하는 장이었다.
OS 계정과 권한, 프로세스 체크, 디스크 관리, File Descriptor, 서버 timezone, cron(tab),
alias, 네트워크 정보 체크 (ifconfig, netstat 등) 를 다룬다.

10장 모르면 답답해지는 네트워크 기초, 11장 자주 쓰는 서버 구조와 설계 패턴를 넘어 부록까지 너무 알차다. 진짜 딱 신입오면 너무 주고싶은 책이다.

~~사실 이제 사무실에 이 책을 두고 새로 오시는 분에게 꼭 찔러주고 싶다. 이걸로 온보딩 과제를 만들어 볼까도 싶다 ㅎ~~

velog dashboard v2 - 벌써 120만개가 모인, 리뷰 & 0.6 version (feat. 서버 비용 0원)

Wed, 21 May 2025 07:18:21 GMT

Velog Dashboard v2

Velog Dashboard 정식 릴리즈 이후 약 2.5개월간의 "결과" 와 0.6 version 빨리 접속하기: https://velog-dashboard.kro.kr/ Github repo: https://github.com/check-Data-Out/velog-dashboard-v2

누구세요?

velog dashboard 라는 프로젝트는 *"딸각" 으로 velog 전체 통계를 보여주는* web-application project 입니다!
- velog dashboard v2 - 베타 오픈!!
- velog dashboard v2 - 딸깍으로 전체 통계 보기
오픈 1주일만에 100명이상 빠르게 등록해주시며, (🙏🙇🏻‍♂️) 확실하게 velog 의 통계 쉽고 한 눈에 보고 싶은 마음이 있는 것을 증명해주셨습니다.ㅎㅎ 사실 꽤 예전에도 이런 시도가 많았는데요, 다 사양되고, 개개인에 의존하고 있는 형태였었습니다.
사실 "velog dashboard 제작기 (1) - 벨로그 통계를 편하게 보고 싶어요 ㅠ" 라는 것으로 23년도 11월 즈음 한 번 등장한 적이 있었으나, 제가 만든 해당 플젝이 velog 쪽 DBMS 를 터뜨려버렸습니다...
그래서 머리부터 발끝까지 완전 재정비해서 0 to 1, 지금은 1 to 10 을 향해 나가고 있는 project 입니다!! ㅎㅎ

아직 확인 안해보신 velog 유저분들 가볍게 "딸각" 으로 전체 통계 한 번 보고가셔요!!~

성과 공유

일단 daily 통계 개수가 벌써 120만개가 넘었습니다..!🥳🥳🎉 그래서요.. supabase 가 더 이상 무료 티어 못쓴대요.. (사실 egress 때문) 좋은 소식인지 슬픈 소식인지 애매하네요 🥹

하지만 "수평 분할!!", 샤딩을 세팅 중이며, 받지 못했던 신규 사용자 분들을 더 적극적으로 받을 수 있게 되었습니다!! 이 때문에 어디서 사용해보라고 적극적으로 말을 못했었어요 ㅎㅎ..

이제 더 편하게 확인해주세요!! 🔥🔥

1) 게시글 수

17,248 개
저는 이 부분에서 놀랐는데, "전체 통계 궁금하신 분들은 velog 헤비유저였습니다." ~~(당연한 것인가?!)~~
사실 처음 가설로는 velog 사용하시는 분들 대부분 본능적으로 전체 통계가 궁금할 것 이라고 생각했는데, 압도적인 헤비 유저분들의 리텐션차이가 있었습니다!!

2) 사용자 별 평균 & 중앙값 게시글 수

Average: 약 87 개
Median: 약 56 개
평군과 중앙값 에서 알 수 있듯, "long tail",, 소수 상위 유저가 견인하고 있는 게시글 수 형태 입니다 ㅎㅎ
가볍게 파레토 법칙 기반의 상위 10% 사용자 게시글이 몇 % 차지하는지 보면 아래와 같더라구요?!

항목	값	해석
상위 10% 유저 수	20명	-
상위 10% 게시글 수	7,320개	*전체의 42.44%*
하위 50% (6~10분위) 유저 수	99명	-
하위 50% 게시글 수	2,377개	*전체의 13.78%*

3) Active User

(PS. 철저하게 GA 랑 web-server log 에 의존한 분석.. 오차 분명 존재 가능성 농후 :'))

DAU & MAU

DAU: 평균 약 30-50 선
MAU : 평균 약 1000-2000 사이 선
사실 생각보다 많아서 놀랬습니다,, ~~왜 많아요..?~~

역시 위에서 살펴본 바와 같이 우리 헤비 유저 분들이 견인하고 있는 수치입니다. 물론 여기엔 제가 정말 매일 아주 잘 사용하고, 만족하고 있습니다 ㅎ ~~나 쓸라고 만든 product~~
유입은 Direct 가 가장 많았는데, 긍정적으로 해석하자면 "대부분의 daily 활성 사용자 분들은 즐겨찾기 로 들어오고 계셨다~" 라고 볼 수 있습니다! 왜냐면 저흰 마케팅이란걸 전혀 안하기때문.. 유입 채널은 velog 의 "제 게시글 뿐" ...
혹시나 코호트를 포함한 이상을 바라신다면,, pass ㅎㅎ 사실 추적을 위한 세부 세팅을 안해둬서 (애초에 구해볼 생각을 안했어서..) ~~귀찮아서 패스입니다..~~

Update!!

사실 안보이는 부분 업데이트가 정말 많았습니다.. 매우 슬프게 다들 투여할 수 있는 시간이 제한적이라 ㅠㅜ 특히 "최적화(메모리, 네트워크 사용량, 레이턴시, 랜더링 퍼포먼스)" 많은 노력을 했습니다 ㅎㅎ)

1) 타임존 관련 이슈 해결!

그렇게 당하고 또 당해버린 타임존 이슈.. 이 때문에 00시 부터 09시 까지 저희 통계는 stop the world 가 되었죠.. KST 기준 새벽에 쓴 글이 어제 쓴글이 되어버리기도 하구요

"통계값을 가져오는 배치" 는 KST 기준으로 데이터를 동기화 하고 있었습니다. 그리고 "날짜 값만" 저장했죠!
하지만 API 서버에서 이를 간과하고 SQL 들이 모두 UTC 기준으로 "하루"를 책정하고 있었죠..
그 덕분에 FE 에서받는 시간관련값이 어떤 곳은 KST 로 변환되서 주고, 어떤 곳은 UTC 그대로 주고 있었죠.. (FE 에서 아주 아찔)
더욱이 api server, node runtime 과 supabase 모두 UTC 기준으로 모두 셋업되어 있었습니다! ㅎㅎ
처음에 급한대로 FE 에서 일단 시간 보정을 했는데, 다들 아시다시피 client-side, 즉 브라우저에서 실행되는 Date 는 대부분의 method 가 브라우저 시간을 따라가더라구요! 결국 아래와 같은 강제 KST 보정 함수 를 사용하고 있습니다!

const KST_DIFF = 9 * 60 * 60 * 1000;

/**
 * KST로 변환된 날짜 정보를 담는 인터페이스
 */
export interface KSTDateFormat {
  /** "YYYY-MM-DD" 형식의 날짜 문자열 */
  short: string;

  /** ISO 8601 형식 + KST 오프셋 포함 문자열 */
  iso: string;

  /** KST로 보정된 Date 객체 */
  full: Date;
}

/**
 * 주어진 날짜 문자열을 KST(한국 표준시) 기준으로 변환함.
 *
 * @param {string} [date] - 변환할 날짜 문자열 (예: "2025-05-15T08:00:00Z")
 * @returns {KSTDateFormat | undefined} 날짜가 없으면 undefined 반환
 */

export const convertDateToKST = (date?: string): KSTDateFormat | undefined => {
  if (!date) return;

  // UTC 날짜 파싱
  const utcDate = new Date(date);

  // UTC+9 (KST) 시간으로 변환
  const kstTimestamp = utcDate.getTime() + KST_DIFF;
  const kstDate = new Date(kstTimestamp);

  // UTC 메서드를 사용하여 KST 시간을 추출
  // (UTC 메서드에 KST 시간을 넣으면 원하는 결과를 얻을 수 있음)
  const year = kstDate.getUTCFullYear();
  const month = (kstDate.getUTCMonth() + 1).toString().padStart(2, '0');
  const day = kstDate.getUTCDate().toString().padStart(2, '0');
  const hours = kstDate.getUTCHours().toString().padStart(2, '0');
  const minutes = kstDate.getUTCMinutes().toString().padStart(2, '0');
  const seconds = kstDate.getUTCSeconds().toString().padStart(2, '0');

  return {
    short: `${year}-${month}-${day}`,
    iso: `${year}-${month}-${day}T${hours}:${minutes}:${seconds}+09:00`,
    full: kstDate,
  };
};

왜? 라면, "하루" 라는 기준이 client side 브라우저 시간대에 따라 달라지지만, 저희 서비스는 "하루" 를 배치에서 무조건 KST 기준으로 하기 때문에 only KST 라는 기준을 세워야 했습니다!! (철저한 Korea 로컬라이제이션)
사실 실제 root cause 를 찾는 과정과 debugging 은 위 시나리오처럼 간단하지 않았습니다.. 시작은 리더보드와 Query Explain 이 던진 공이었죠 ㅎㅎㅎㅎㅎ 🥹 그리고 모든 SQL 을 갈아 엎었구요. ㅎㅎㅎㅎ

아직 확인을 안하셨다면? 아래와 같이 "상단 상태바" 형태로 인디케이터가 있습니다~~

3) 드디어, 리더보드: 리더보드 기능이 생겼습니다!!

[ 사용자 또는 게시글 기준 / 조회수 증가 또는 좋아요 증가 / 10위 또는 30위 / 30일 또는 7일 ] 필터로 리더보드를 볼 수 있습니다!
저희가 username 은 저장하지 않고 있어요! email 없으신 분들은 리더보드에서 제외됩니다!!

4) QR 코드 로그인!

다중 로그인에 불편함이 있으셨을거에요!! 이제 QR 코드 한 방으로 자동 로그인이 가능합니다!! PC to PC 를 위해서 QR 밑에 url 로 추가하려고 합니다!!

5) 드디어, 공식 'Extension'

이는 저희쪽 API를 활용한 익스텐션이며, 벨로그 페이지에서만 보여주는 전체 요약 통계 입니다!!
이를 바탕으로 readme 의 카드, 특정 곳에 임베딩 등과 같이 아주 다양한 곳에서 활용 가능성을 기대하고 있습니다~~
~~아직 익스텐션 앱스토어에 릴리즈는 못했습니다 / 계속 허가를 안해줘..~~

다운로드는 여기서!!
- https://drive.google.com/file/d/1Ccn7WnYFQ6dJP29LZW9BwUxqhqZAhS8D/view?usp=sharing
- 추가하는 방법이 궁금하시다면?! - https://support.google.com/chrome_webstore/answer/2664769?hl=ko

6) 마무리

센트리를 붙여서 live-time issue 트래킹이 가능해요!! nextjs 의 build output, source map 때문에 애를 먹었습니다..
전체적으로 FE 사이즈 조절, 반응형 고도화를 했어요!!
과거의 daily 통계값은 아마 이제 5~6개월까지만 보관하려고 합니다!!
- 이 때문에 게시글 하나 하나의 전체 범위 통계 변화 조회가 아니라, 최대 6개월 내외로 조회가 가능하게 될 것입니다. 🙏🙇🏻‍♂️

서버 비용은 0 원!!!

어떻게?

사실 너무 별거 없어서 공유 드릴 말이 없는데, 많이 문의 주셔서 다시 남겨보자면! Oracle + Supabase + git action 조합이라 그렇습니다.
특히 엄청난 transaction 들이 필요한 API 도 딱히 없고 (최근에 추가된 리더보드 빼고) 엄청난 DAU 가 있는 것 도 아니라 완전 버틸만 합니다.
stand-by 상태 oracle instance 가 총 8대 정도라 (api + fe 만 6개 가용, 팀원들 인스턴스 ㅎㅎㅎ) 추산치 & 예상치로 1~5만까지는 거뜬할 것 같네요. (로드밸런서만 잘 버텨준다면)
결국 저희한테 제일 중요한게 *"통계 batch"* 인데, 지금 https://github.com/Check-Data-Out/velog-dashboard-v2-back-office/actions 보시면 20개 aggregation (scraping) 배치가 열일중!!

무료 티어 근데 더 못쓴대요..

그래서 supabase 무료 티어를 "샤딩" 하려고 합니다 흐흐흐 😈😈. duplication 을 하려는 것은 아니고 완벽한 물리적 분할, Horizontal Partitioning 을 하려고 합니다!
덕분에 더 많은 velog 사용자분들의 daily 통계를 보여드릴 수 있습니다!!

TO BE

1) LLM 을 활용 해보려고 합니다!

왜?

근본적으로 "벨로그 통계" 는 어떻게 보면 마케팅에서 콘텐츠 성과 측정과 같은 목적이죠! 성과 측정은 콘텐츠의 퀄리티 또는 방향에 대해서 고민하게 되고, 결국 더 좋은 방향으로 가게 됩니다!!
하지만 이는 너무 마케팅 관점이라, 진정으로 "내가 가고 싶은 방향" 이라는 다를 수 있다고 생각했어요! "동기부여" 관점과 "내가 가고 싶은 방향" 을 align 하기 위해서는 "동반자" 가 될 수 있는 어떤 것이 있으면 훨씬 좋다고 생각했고, 단순한 aggregation 이 아니라, 자연어와 함께 개개인의 "콘텐츠 동반자가 되는" LLM 을 붙이고 싶었습니다!!

내용

"주간 트랜드" 와 "사용자의 주간 게시글" 을 LLM 활용해 "내용을 포함한 글의 트랜드 & 통계 변화 분석" 해서 "주간 메일링" 을 하려고 합니다!!
계속 프로프팅 하고, mail template 과 내용을 바꿔가며 테스트해보고 있습니다! 아마 아래와 같은 형태가 아닐까? 합니다! (ps. 특정 데이터는 모킹된 가짜)

2) 다중 플랫폼의 통계를 가져와 보려고 합니다!!

바로 다음 타켓은 티스토리 & Medium 입니다!

둘 다 좋은 통계를 제공하는데요, 더욱이 티스토리는 "유입 분석" 역시 제공합니다. (과거 다음블로그 시절, 완전하게 콘텐츠 광고로 사용되었기 때문에...)
하지만 velog-dashboard v2 는 궁극적으로 "콘텐츠 통계 aggregation" 으로 나아가고 있고, 이를 발판 삼아 *"기술 블로그들의 aggregation & contents hub" 가 되고자 합니다!*

사실 가끔 velog 통계에 왜 그렇게 집착하냐고 듣는데 ㅋㅋ 여기가 "시작인 것" 뿐 입니다. ㅎㅎ 저희 25년도 North Start는 velog를 쓰는 모든 사람이 전체 통계를 아주 편하고 빠르게 보게하는 것 입니다!! ~~26년, 27년 North Start는 다음 기회에 ㅎㅎ~~ 여전히 갈 길이 멀었지만, 지금까지 그래왔던 것 처럼 step by step 으로 소소하게 업드레이드 되는 모습 계속 보여드리겠습니다 :) 🙇🏻‍♂️🫡🫡🔥🔥🔥

빨리 접속하기: https://velog-dashboard.kro.kr/ Github repo: https://github.com/check-Data-Out/velog-dashboard-v2

python - 파이써닉한 dataclass 와 ENUM

Thu, 01 May 2025 16:23:49 GMT

[ 글의 목적: python 에서 dataclass 와 ENUM 을 쓰면서 생긴 팁 기록 & 공유 ]

Pythonic한 dataclass 와 ENUM

3.7 부터 등장한 dataclass (PEP-557), 3.4 부터 등장한 ENUM(PEP-435), 사실 필자는 3.8 부터 해당 기능들을 제대로 쓰기 시작했다! 쓰면서 생긴 나름의 사용 방법을 공유하고자 한다 ㅎ (기본적인 사용법은 거의 skip, 만약 처음이라면 해당 글을 비추천!)

1. dataclass

1) 정의 & 기본 사용법

얘의 본질적인 등장 핵심은 "클래스 정의를 간결하게 만들어주는 것" 이며, 기본적으로 생기는 dunder method 에 __init__(), __repr__(), __eq__() 를 알아서 정의해주는 것 이다. (물론 비교 연산자, __hash__ 등도 정의를 하게 할 수 있다.)
가장 와닿는 예시를 보면, server-side 에서 특정 layer 마다(또는 외부/내부, 도메인 등) "데이터(Object)" 를 주고 받을때 "너 어떻게 생겼니" 를 가르쳐 줘야 한다. (물론 상남자라면 dict 만 쓰면 된다. ~~평생 혼자 개발하면 된다.~~) 특히 만약 사내에서 python 으로 "DDD" 를 해보자! 한다면 이제 난리나는 부분들이 이 지점이 아닐까 한다 ㅎ

class ProductDTO:
    def __init__(self, id, name, price, in_stock=True):
        self.id = id
        self.name = name
        self.price = price
        self.in_stock = in_stock

    def __repr__(self):
        return f"ProductDTO(id={self.id!r}, name={self.name!r}, price={self.price!r}, in_stock={self.in_stock!r})"

    def __eq__(self, other):
        if not isinstance(other, ProductDTO):
            return NotImplemented
        return (self.id, self.name, self.price, self.in_stock) == (other.id, other.name, other.price, other.in_stock)

아주 심플한 상품 DTO 를 위해 __init__ 만 있어도 된다. 하지만 기본적으로 출력이나 equal 연산 정도는 해줘야 의미가 있다. (== 연산) 이게 쌓이고 쌓이다 보면 꽤나 아찔한 상황이 있다.
이때 원래 고민의 포인트는 자연스럽게 *"Pydantic 를 쓰냐 마냐"* 였지만, 사견으로 대부분의 경우 dataclass 선에서 정리가 가능한 것 같다. 시리얼라이징/디시리얼라이징 필요 없고, 외부 의존성도 필요없고, (상대적) 훨씬 유연하고, 오버헤드가 없어서 상대적으로 빠르다.

@dataclass
class ProductDTO:
    id: int
    name: str
    price: float
    in_stock: bool = True

ProductDTO 를 위와 같이 아주 심플하게 세팅 가능하다. 물론 "API 입출력, 사용자 입력 validation, 데이터 보정이 필요한 경우" 는 무조건 dataclass 를 사용하는 것은 비추천 한다. 오히려 pydantic.dataclasses.dataclass 를 쓰는 것도 좋은 수단이라고 생각한다. - https://docs.pydantic.dev/latest/concepts/dataclasses/
아래 부터는 "사견이 가득 담긴" 기록이다. 모든 활용을 쓰는 것 보다 실제 필자가 많이 쓴 것 정도, 실무에서 많이 사용해 본 것들 위주로 리스트 해봤다.

2) mutable / immutable

dataclass 는 기본적으로 "mutable" 한 객체이다. 하지만 외부 API 응답에 대한 단순 정의 같이 "굳이 바뀔필요 없고, 바뀌어서도 안되는 것" 들은 실수를 방지하게 위해 "immutable" 한게 좋다. (서버 설정 값, 배치 시작 설정 값 등)
그럴때 @dataclass(frozen=True) 를 쓰면 바로 read-only 객체, "immutable" 해진다.

@dataclass(frozen=True)
class DeliveryStatus:
    order_id: str
    status: str
    updated_at: str

# 외부 API 응답 파싱
resp = DeliveryStatus(order_id="ORD123", status="in_transit", updated_at="2025-05-01T12:00:00")

# 값을 바꾸려 하면?
resp.status = "delivered"
# ❌ FrozenInstanceError: cannot assign to field 'status'

이게 또 좋은 포인트는 hashable해져서 dict의 키나 set 요소로도 사용 가능 해지는 것이다. good example 은 아니지만 위 예시를 그대로 이어가보면, 아래와 같이 메모리 활용으로 O(1) 속도로 같은 응답 체크가 가능해진다! ㅎㅎ

cache = {resp: "cached"}
if resp in cache:
    print("이미 받은 응답입니다.")

참고로 무조건 hashable 해지는게 아니다. 필드에 mutable 객체가 있을 경우 TypeError 발생한다! 이는 밑을 쭉 따라가면 대응 가능한 포인트가 있다 ㅎ

3) `default_factory`

사실 팁이라기 보단 생각보다 놓칠 수 있는 default_factory, 그리고 사실 python 3.9 이상이라면 무조건 사용했을 값이다. 즉 *"기본값이 리스트, 딕셔너리, set 등 mutable 한 타입일 때는 무조건 써야 하는 값이다."*
어떤 문제가 있었을까? "mutable" 한 object 대상으로 "값을 공유하는" 이슈가 있었다. 사실 이슈라기 보다는 python 자체가 기본값은 "정의 시점" 에 평가되는데, dataclass 최초 객체가 생길때 list 하나 만들었으면, 다음번에 만들때 계속 해당 list object 를 공유하기 때문!

@dataclass
class Basket:
    items: list[str] = []

a = Basket()
a.items.append("apple")

b = Basket()
print(b.items)  # ['apple'] 😱 ???

그래서 "default_factory" 를 쓰며, 3.9 이상에서는 안쓰면 ValueError 가 발생한다. -> ValueError: mutable default for field items is not allowed: use default_factory

from dataclasses import dataclass, field

@dataclass
class Basket:
    items: list[str] = field(default_factory=list)

a = Basket()
a.items.append("apple")

b = Basket()
print(b.items)  # [] → 완전히 독립된 객체

4) `__post_init__`

dataclass 를 만들때 벨리데이션이 필요한 경우가 있다. 여기서 pydantic 에 대한 고민이 들지만, 정말 특정 필드에 대한 검증만 하면 된다면, __post_init__() 를 사용해 볼 수 있다.

@dataclass
class User:
    name: str
    age: int
    email: str

    def __post_init__(self):
        if self.age < 0:
            raise ValueError(f"❌ 나이(age)는 음수가 될 수 없습니다: {self.age}")
        if "@" not in self.email:
            raise ValueError(f"❌ 이메일 형식이 잘못되었습니다: {self.email}")

절대 음수가 올 수 없는 값에 대해 ValueError 를 만들어 줄 수 있다. 위의 DeliveryStatus 라는 값 예시에서도, 외부에서 주는 값이라면, 그리고 status 가 절대 될 수 없는 값이 있다면, 이 방법이 아주 유용하다.
외부 API 응답은 성공했는데 응답이 기대한 것과 다를때에 대한 검증이 dataclass 만으로 바로 가능하기 때문이다.

from datetime import datetime
from dataclasses import dataclass

@dataclass
class Event:
    title: str
    date: str  # 입력은 str으로 오지만…

    def __post_init__(self):
        parsed_date = datetime.fromisoformat(self.date)
        object.__setattr__(self, 'date', parsed_date)
        # 참고로 self.date ... 로도 접근 가능

더욱이 "값 보정" 을 할 수도 있다. 근데 개인적으로 값 보정 자체를 __post_init__ 에서 하는 것은 비추천, "공백 제거 정도" 와 위 예시에서 date 가 어쩔 수 없이 문자열로 받지만, datetime 으로 casting 할 때 유의미 했다.
위 예시는 self.date 를 안썻는데, 이유는 frozen=True 경우는 불가능 하기 때문 이다!

5) `asdict` / `astuple`

DTO 나 아주 간단한 객체에 대한 데이터 명시로 사용할때, "직렬화" 가 필요한 경우 사용했다. 특히 중첩된 dataclass, 또는 Kafka (or other message queue) 를 위해서 사용할 때!

from dataclasses import dataclass, asdict

@dataclass
class User:
    name: str
    age: int

@dataclass
class Post:
    title: str
    author: User

p = Post(title="Hello", author=User(name="Alice", age=30))
print(asdict(p))

{
    'title': 'Hello',
    'author': {
        'name': 'Alice',
        'age': 30
    }
}

자동으로 중첩 구조까지 재귀적으로 dict 변환이 된다. 이걸 이제 json.dumps() 할 수 있다! 외부 API / 서버 / 이기종 시스템을 위한 데이터 전송 세팅 준비가 (시리얼라이징) 딸깍 완료! 된다! - 참고로 100% 안전하지는 않는다... datetime 은 직렬화 불가..
그에 반해 사실 astuple 을 많이 쓰지는 않았는데 딱 한 번 매우 동감하며 쓴 기억이 있다. (LLM function call 을 위한) 임시 배치 프로세스를 만들었는데 SQL 을 만들때 "파라미터" 들을 dataclass 로 부터 출발해서 만들때!! 예시로 보면 아래와 같다!

from dataclasses import dataclass, astuple

@dataclass
class User:
    name: str
    age: int

u = User(name="Alice", age=30)
print(astuple(u))  # ('Alice', 30)

INSERT INTO 에 아주 이쁘게 ('Alice', 30) 를 넣을 수 있다. 즉, 순서형 데이터가 필요한 경우 꽤나 유용하게 쓸 수 있었다.
그리고 다른 일례로, dict는 mutable이라 hashable하지 않지만, tuple은 가능 (단, 내부에 mutable 요소가 없을 경우) 하기 때문에 if astuple(obj1) == astuple(obj2): ... 이런 해쉬 기반으로 아주 빠른 비교가 가능하다.

6) `order` 옵션을 통해, data간 대소비교!

dataclass는 기본적으로 __eq__() 만 만들어주지만, order=True 를 설정하면 __lt__, __le__, __gt__, __ge__ 까지 자동으로 추가된다!! 즉, 아래처럼 객체끼리 정렬, 크기 비교가 가능해진다.

from dataclasses import dataclass

@dataclass(order=True)
class User:
    score: int
    name: str

users = [
    User(score=50, name="Alice"),
    User(score=90, name="Bob"),
    User(score=75, name="Charlie"),
]

sorted_users = sorted(users)  # score 기준으로 정렬됨

만약 여러분들이 heapq (우선순위 큐) 를 쓴다면? 최소/최대값을 찾아야 한다면?! 대소 비교 (<, > 비교) 가 필요하다면?! 쓰는 것을 추천!

참고로 선언된 순서로 소팅 우선순위가 된다!

@dataclass(order=True)
class Person:
    sort_order: int  # 이걸 기준으로 정렬됨
    name: str

7) `slots=True` 로 메모리 최적화?!

참고로 이건 Python 3.10+ 전용이다. 최근에 배치 프로세스 만들때, 사용자 데이터 분석 할 때 (bluk 로 가져올때) 사용했다. 목적은 단순하다. dataclass 만들때 __dict__ 속성도 만들어진다. 근데 이걸 못하게 하는거다! (ps. python class 만들때 __dict__ 가 만들어짐)

from dataclasses import dataclass

@dataclass
class MyData:
    x: int
    y: int

d = MyData(1, 2)
d.z = 3  # 동적으로 필드 추가
print(d.__dict__)  # {'x': 1, 'y': 2, 'z': 3}

위 예시에서 z attribute 가 만들어지는 것을 막을 수 있다. 참고로 원래 python 에서는 class 에서 이걸 막으려고 전통적으로 __slots__ 을 사용했고, 아래와 같은 방식으로 사용했다. (아마 python 2 부터 가능한 것으로 알고 있다.)

@dataclass
class A:
    __slots__ = ['x', 'y']
    x: int
    y: int
    z: int  # ⚠️ 이 필드는 누락되었기 때문에 AttributeError 발생 가능

하지만 이제 데코레이터에 slots=True 를 추가하면 바로 가능!

@dataclass(slots=True)
class B:
    x: int
    y: int
    z: int  # 걱정 없음, 자동 처리됨

특히 여기에 대한 아주 강력한 추천 글이 있다! - Usage of slots?

ps) 이 외에 분명 엄청 많지만, 최대한 사견을 담은 것 위주로 리스팅했다. 더욱이 unsafe_hash 같은 것은 비추천.. 한다..!

2. ENUM

"왜?" 와 "정의" 에 대해서는 최대한 간략하게만 살펴보자
Enumeration, 열거형은 개인적으로 *"휴먼 에러 최소화"* 에 초점이 가득 담긴 친구라고 생각한다.
"정해진 것" 만 값으로 넣을 수 있게 강제화 하니 IDE 에서 체크하기도 쉽고, 가독성 올라가고, 타입 안정성 올라가고, 더불어 "상수" 니까 자연스럽게 "유지보수성" 을 증가시킨다.

여기서는 enum 을 쓰면서 기억에 남았던 것들, 좋은 사례를 모아보고자 한다.

1) python 에서 Literal type 과 ENUM

python 은 보기드문 "순수 객체 지향 언어" 이다. (java 등과는 다르게 원시 타입이 없다.) str, int type 들도 "class" 이고, 객체의 인스턴스가 된다.
과한 자유로움은 장점이자 단점이 되고, 단점을 보강하기 위해 type 을 사용한다. (사실 "협업" 과 "유지보수" 가 최고 목표 아닐까?) python 은 본격적으로 이 부분을 지원한게 PEP 484 – Type Hints 로 시작된다. (물론 이전에 다양한 접근 방식이 존재했지만, official 부분만 놓고 보자면!)
이 흐름속에서 등장한게 Literal 이다. 이유는 단순하다. 정적 타입 힌팅이 강화되면서 str, int 등 기본 타입은 제한할 수 있었지만, 특정 값만 허용하는 타입 제한은 불가능했기 때문 이다. - PEP 586 – Literal Types

enum 과 차이는 아래와 같다.

항목	`enum.Enum`	`typing.Literal`
정의 목적	상수 집합을 클래스로 정의하고, 값과 의미를 묶기 위함	함수 인자나 변수 값이 특정 값 중 하나임을 명시적으로 제한
런타임 존재 여부	런타임에도 존재하며 객체처럼 동작함	타입 힌트 전용, 런타임에는 아무 기능도 없음
값의 의미 표현	각 멤버는 이름과 값을 가지며, 독립된 의미 부여 가능	단순한 리터럴 값 (`"A"`, `1` 등)을 나열하는 것
확장성	메서드 추가 등 확장 가능 (`Color.RED.hex()`)	불가능, 단순한 값 고정
타입 검사 도구 활용	mypy, pyright 등에서도 동작 가능	타입 힌트로만 작동 (정적 분석 도구에만 의미 있음)
용례	상태, 종류, 옵션 등의 구분 (`UserType.ADMIN`)	함수 인자의 값 제한 (`Literal["asc", "desc"]`)

외부 API 호출 응답값 제한, pydantic & dataclass 에서 자유롭게 쓸 수 있고, 함수 파라미터에서 특정 값을 가장 쉽고 빠르게 정의 할 수 있어서 개인적으로 Literal 은 여전히 잘 쓰고 있다.

ps) Python 3.9~3.11에 걸쳐 typing 라이브러리 일부 기능은 built-in 이 되었으며, 필자는 거의 더 이상 typing 를 사용하지 않고 있다.

2) `str` class 상속 같이 받기

.value attribute 접근 필요가 없어진다.

class Reliability(Enum):
    HIGH = "high"

reliability = Reliability.HIGH
print(type(reliability))    # 
print(reliability)          # Reliability.HIGH 출력
print(reliability.value)    # "high" 출력
print(f"신뢰도: {reliability.value}")  # "신뢰도: high" 출력

위 enum 을 아래와 같이 사용할 수 있다.

class Reliability(str, Enum):
    HIGH = "high"

reliability = Reliability.HIGH
print(reliability)          # "high" 출력
print(f"신뢰도: {reliability}")  # "신뢰도: high" 출력

python 의 다중상속의 MRO(Method Resolution Order), "왼쪽에서 오른쪽으로" 우선적으로 적용한다. 즉, str 의 문자열 표현과 관련된 메서드(__str__, __repr__, __add__ 등)는 str 의 구현이 사용되기 때문이다.

단점

type 제한 하려고 enum 썼는데 아니 type 을 다중으로 해버리네? 라고 생각할 수 있다. 위 같은 방식이면 isinstance 와 같은 빡센 타입 체킹에서 예상치 못한 동작이 있을 수 있다!!
- (ex - isinstance(reliability, str) 가 True 가 되기 때문. 근데 이걸 유도할 수 도 있다. 문자열 비교가 필요하면 말이다.)
그래서 한 가지 대안은 아래와 같다! 직접 __str__ 을 오버라이딩 하는 것!

    def __str__(self):
        return self.value

ps) str 상속해서 메모리 오버헤드 걱정이 된다면.. python 을 안쓰는 것을 추천.. 한다..

3) 비교 가능한 Enum 만들기 (`IntEnum` 사용)

모든 언어에서 "문자열 비교" 는 비싼 연산 중 하나다. Enum 값들을 문자열 형태로 만들다 보면 "비교 연산" 에서 계속 문자열 비교를 하는 경우가 있다.

class Priority(Enum):
    LOW = "low"
    MEDIUM = "mi"
    HIGH = "high"

이렇게 선언해두면 if current_status == Priority.LOW 와 같은 동등 비교 중심으로만 연산하게 된다. 더욱이 동등 연산자의 전자가 문자열이라면, 자연스럽게 문자열로 바꿔 "문자열 비교 연산" 을 하게 된다.

class Priority(IntEnum):
    LOW = 1
    MEDIUM = 2
    HIGH = 3

이제 비교 연산이 가능해진다. if current_status.value > Priority.HIGH.value 와 같이, HIGH 가 아닌 모든 것들에 대해 일관적인 조건 체크를 빠르게 할 수 있다.
이 방식이 가장 두드러지는 것은 "로깅 레벨" 에서 볼 수 있다.

4) `auto()` 함수와 Flag Enum으로 비트 플래그 만들기

나는 "값" 이 중요한게 아니라 "키" 가 중요해! 일 경우 auto 를 쓸 수 있다. 사실 위에 예시와 같이 "상태" 는 "값" 보다는 "의미, 키" 가 중요하다.
auto()는 기본적으로 1부터 시작해 1씩 증가하는 값을 제공한다. 실수로 같은 값을 넣어서 이슈가 있을 가능성 자체가 없어진다. (_generate_next_value_ 메서드를 내부적으로 활용한다. 이를 오버라이딩하면 전혀 다른 값으로 증가하게 할 수 있다.)

from enum import Enum, auto

class Status(Enum):
    PENDING = auto()    # 1
    ACTIVE = auto()     # 2
    INACTIVE = auto()   # 3

새로운 "키" 가 추가되어도 "값" 에 신경 안쓰고 바로 늘릴 수 있다. 하지만 순서에 따라 할당 받는 값 이 달라지며 이 경우 value 비교연산은 안하는게 좋다. 그리고 이 auto() 를 활용해 Flag enum 을 좀 더 편하게 사용이 가능하다.

그 전에 "비트 연산" 을 알아야 이해가 쉽다. (비트마스킹 등)

| (OR): 두 비트 중 하나라도 1이면 1
& (AND): 두 비트가 모두 1이면 1
^ (XOR): 두 비트가 서로 다르면 1
~ (NOT): 비트 반전 (1→0, 0→1)
<<, >> (SHIFT): 비트를 좌/우로 이동

이걸 통해 뭘 할 수 있을까? 아래와 같은 예시처럼, 한 바이트로 8가지 상태 (비트당 하나의 상태값 표시 가능) 에 표현이 가능하다. (사실 8가지가 아니라 경우의 수로 보면 총 2^8 = 256가지의 다른 조합 표현이 가능하다.)

# 이렇게 8개 변수 대신
is_read = True
is_write = False
is_execute = True
# ...5개 더

# 이렇게 하나의 변수로 표현
permissions = 0b10100101  # 한 바이트로 8가지 상태 표현

물론 보는 사람이 "사람" 이라서 가독성이랑 유지보수성이 부족하다. H/W 에 가까운 개발을 할수록 사실 이런 비트연산은 "기본" 에 가까워진다. 근데 이걸 Enum 개념을 조금 차용해서 Flag 를 활용하면?! 아래와 같이 쓸 수 있다.

# 여러 개의 if문 대신
if user.can_read and (user.is_admin or user.is_owner) and not user.is_banned:
    # 작업 수행...

# 비트 연산으로 한 번에 처리
required_perm = READ | (ADMIN | OWNER) & ~BANNED
if user.permissions & required_perm == required_perm:
    # 작업 수행...

실제 Flag Enum 은 아래와 같이 Flag 클래스를 상속받아 비트 플래그 Enum을 만들 수 있다.

from enum import Flag, auto

class Permission(Flag):
    READ = auto()      # 1 (binary: 001)
    WRITE = auto()     # 2 (binary: 010)
    EXECUTE = auto()   # 4 (binary: 100)

    # 조합된 값, 복합 상태 값! -> 이게 진짜 강력하다!
    READ_WRITE = READ | WRITE          # 3 (binary: 011)
    ALL = READ | WRITE | EXECUTE       # 7 (binary: 111)

# 사용 예시
user_perm = Permission.READ | Permission.WRITE  # 3

# 비트 연산으로 권한 확인
if Permission.READ in user_perm:
    print("사용자는 읽기 권한이 있습니다")

가장 편리한 지점은, 어짜피 비트 연산을 눈으로 매번 따라가면 실수하기 쉽다. 그러니까 자연스럽게 auto 랑 같이 섞어서 쓸 수 있고, 더욱이 *"복합 상태 값" 이 진짜 강력한 것이다.*
만약 통신에 이 개념을 사용하면, 데이터 전송 효용성 과 그에 따른 비용 절약 을 기본으로 깔고 갈 수 있다. (사실 실제로 최적화 관점에서 많이들 사용한다.)

5) Enum 값의 유일성 강제하기 (unique 데코레이터)

Enum 은 기본적으로 "값" 의 중복을 허용하며 이를 "alias(별칭)" 으로 받아들인다.

from enum import Enum

class Color(Enum):
    RED = 1
    CRIMSON = 1  # RED의 별칭
    GREEN = 2

근데 "값" 자체의 유일함이 중요하다면, @unique 데코레이터를 사용하면 된다!

from enum import Enum, unique

@unique
class Color(Enum):
    RED = 1
    GREEN = 2
    BLUE = 3
    # DUPLICATE = 1  # 이렇게 하면 ValueError 발생

이게 빛을 발하는 경우는, auto() 랑 커스텀을 같이 할 때 인 것 같다. 즉, auto 에 unique 를 달아줘서 의도치 않은 실수 방지를 강제할 수 있다!

from enum import Enum, auto, unique

@unique
class Status(Enum):
    START = auto()
    RUNNING = auto()
    STOP = 1  # ValueError 발생 가능성!

6) 복합 값을 가진 Enum 만들기

Enum 값으로 튜플이나 복잡한 객체를 사용할 수 있다! 사실 개인적으로 협업할때 가장 선호하는 형태이긴 하다. 특히 단순한 Enum 이 아니라 *"상태 값을 나타내는" 경우*, "사람"을 위해서 코드의 가독성을 올려보자!

class HttpStatus(Enum):
    OK = (200, "Success")
    NOT_FOUND = (404, "Not Found")
    SERVER_ERROR = (500, "Server Error")

    def __init__(self, code, message):
        self.code = code
        self.message = message

status = HttpStatus.NOT_FOUND
print(f"Status: {status.code}, Message: {status.message}")

여기에 이어서 "문서화에 활용" 할 수 있다!!

class LogLevel(Enum):
    """로깅 레벨을 정의하는 열거형 클래스"""

    DEBUG = 10
    """디버깅 목적의 상세 정보"""

    INFO = 20
    """일반적인 정보 메시지"""

    WARNING = 30
    """잠재적 문제 상황에 대한 경고"""

    ERROR = 40
    """프로그램 실행은 가능하나 오류가 발생함"""

이 얼마나 아름다운 "사람" 과 "협업" 을 위한 Enum 인 것인가!! 더 나아가 Enum 의 __doc__ 을 살펴보면 좋다. - https://tech.isyncbrain.com/python/enum/alias/sqlalchemy/2022/05/15/annotated-enum.html (Enum __doc__ 을 SQLAlchemy 와 함께 활용한 예제!)

7) `_missing_` 메서드로 커스텀 룩업 구현하기

from enum import Enum

class Color(Enum):
    RED = "red"
    GREEN = "green"
    BLUE = "blue"

Color("RED")  # ValueError: 'RED' is not a valid Color

사실 "RED" 는 존재하는 것 ("red") 이다. 이런 경우, Enum 에 정의되지 않은 값이 주어졌을 때의 처리 방식을 커스터마이징 할 수 있다. 바로 _missing_ 를 통해서!

class CaseInsensitiveEnum(str, Enum):
    @classmethod
    def _missing_(cls, value):
        if isinstance(value, str):
            # 대소문자 구분 없이 찾기
            for member in cls:
                if member.value.lower() == value.lower():
                    return member
        raise ValueError(f"{value!r}는 {cls.__name__}의 유효한 값이 아닙니다")

class Color(CaseInsensitiveEnum):
    RED = "red"
    GREEN = "green"
    BLUE = "blue"

# 대소문자 구분 없이 값 찾기
assert Color("RED") == Color("red") == Color.RED

이렇게 하면 "RED", "Red", "red" 등 다양한 형태의 문자열을 동일하게 인식하여 Color.RED로 매핑할 수 있다.
참고로 _missing_ 에서 return None 을 하는 등의 행위 말고, raise ValueError 가 더 올바른 Enum 접근 방법이다!

8) `str` & `repr` 커스터마이징

Enum의 출력 형식을 커스터마이징을 하는 경우가 꽤 있는데, 미리 아래와 같은 base enum 을 하나 만들어 두고, 이걸 상속 받는 방식도 나쁘지 않다!

class FormattedEnum(Enum):
    def __str__(self):
        return f"{self.name} ({self.value})"

    def __repr__(self):
        return f"{self.__class__.__name__}.{self.name}"

class HttpStatus(FormattedEnum):
    OK = 200
    NOT_FOUND = 404
    ERROR = 500

print(HttpStatus.OK)        # "OK (200)"
print(repr(HttpStatus.OK))  # "HttpStatus.OK"

로깅에 많은 도움이 된다고 생각한다. 그러니 디버깅에서도 활용도가 높았다.

ETC

ps) 그 외 Enum 상속에 대한 것 (사실 예시에서 바로 보임), Enum.__members__ 로 속성 값 딕셔너리로 다 가져오는 것, 함수형으로 Enum 동적 생성하기 등이 있다.

ps) 더욱이 @property 는 "불변 상수 / 메타데이터" 가 목적인 Enum 에 잘 안맞는다고 생각한다. 잘못 사용하면, "로직" 이 추가되는 side effect 가 다분히 존재한다고 생각한다!

출처

[책 리뷰] 그림으로 배우는 도커 - 스즈키 료

Fri, 25 Apr 2025 04:31:37 GMT

[ "한빛미디어 서평단 <나는리뷰어다> 활동을 위해서 책을 협찬 받아 작성된 서평입니다." ]

그림으로 배우는 도커

스즈키 료: 별명은 호게 상. 어쩌다 들어간 대학의 정보통신 계열 학과에서 프로그래밍을 접한 후 정보통신 분야에 빠져들었다. 2012년 모 전자 메이커 대기업에 취직해서 백엔드 엔지니어로서 ISP 서비스 개발에 종사했다. 2021년 미라이토디자인으로 이직, 현재는 Zenn(엔지니어 정보 공유 커뮤니티)에 투고하거나 회사 유튜브 채널에 진지한 동영상이나 그렇지 못한 동영상을 공개하고 있다(?)고 한다. (자료를 이 이상으로 찾지 못했다..)

🔥 책 예제 소스 // 구글 도서, 책 미리 보기 // 한빛 책 링크

리뷰

『그림으로 배우는 도커』 는 총 7부로 구성되어 있으며, 1부부터 5부까지는 도커의 기본 개념과 명령어, Dockerfile 작성법까지 점진적으로 설명하고, 6부에서는 실무에 가까운 컨테이너 활용 및 복합 이미지 구축을 다루며, 7부에서는 실제 운영 환경에서 마주치는 디버깅, 트러블슈팅, 그리고 환경 구성 노하우까지 전반적으로 포괄하고 있다.

*이 책의 가장 큰 장점은 단연 "그림" 이다!!(책 이름 값이 쩔어요~)*

단순한 시각 보조 수준을 넘어, 도커의 내부 동작과 추상적 개념들을 직관적으로 이해하게 해주는 데 압도적으로 효과적이다. 도커를 처음 접했던 시절, 유튜브 영상 하나 와 여기저기 흩어진 문서들로 간신히 image 하나를 만들어보고 감탄했던 기억이 있다. 외장하드에 우분투를 넣고 들고 다니며 겨우 컨테이너 하나 띄워봤던 그 어설픈 시작과 비교하면, 이 책은 입문자에게 너무나 친절하고, 중급자에게는 뼈대가 정리되는 경험을 선사한다.

특히 이 책은 '당장 도커를 다뤄야 하는 사람' 에게 실질적인 도움이 되는 책 이다. 시스템의 깊은 구조나 리눅스 커널 수준에서 컨테이너의 작동 원리를 파고들기보다는, 도커를 어떻게 사용할 수 있는지를 실습 중심으로 풀어낸다. container, image, Dockerfile, 그리고 docker compose 까지, "순차적" 으로 기능을 확장해 나가며 자연스럽게 독자가 불편함을 느끼고 그 불편함을 해결하는 흐름으로 구성되어 있다.

5부까지의 실습 은 각각의 도커 명령어를 하나하나 직접 실행하면서 기본기를 다지고, 이후 Dockerfile 을 중심으로 필요한 설정을 직접 추가해가며 컨테이너를 구성한다. 이 과정을 통해 단순 실행에서 끝나는 것이 아니라 '왜 이렇게 구성해야 하는가' 를 되짚게 되고, 최종적으로는 웹 메일함 프로젝트를 compose 파일 하나로 통합 실행하면서 도커를 실무에 도입할 수 있는 감각을 얻게 된다.

(출처: https://gngsn.tistory.com/129)

다만 이 책은 도커의 작동 원리 자체를 깊이 있게 이해하고자 하는 독자에게는 분명 아쉬움이 남는다. 예를 들어 리눅스 커널의 cgroup과 namespace가 어떻게 자원 격리와 프로세스 분리를 구현하는지, overlay filesystem이 어떻게 이미지 레이어를 효율적으로 구성하고 병합하는지에 대한 구조적 설명은 거의 등장하지 않는다.

또한 컨테이너의 PID 네임스페이스와 유저 네임스페이스, 네트워크 브리징 방식 등 도커의 겉모습이 아닌 '안쪽 구조'를 궁금해하는 독자라면, 이 책의 실습 위주 구성은 다소 단조롭게 느껴질 수 있다. 실습 중심의 빠른 흐름은 입문자에게는 유익하지만, 개념과 구조를 충분히 곱씹으며 이해하고 싶은 독자에게는 설명이 생략되거나, 추상적인 레이어에서 멈춘다는 점이 아쉽다.

개념적 깊이보다는 실용적 완성도가 돋보이는 책이며, 현업 개발자라면 책장 한켠에 두고 필요할 때마다 꺼내보게 될, 그런 실전형 책인 것 같다.

목차별 리뷰

1부 가상화와 도커 기본 지식

(1장 ~ 4장)

가상화란, 소프트웨어로 하드웨어 자원을 추상화하여 마치 물리적인 머신처럼 보이도록 하는 기술이다. 이를 통해 하나의 물리 머신에서 여러 개의 가상 머신(VM)을 운용할 수 있고, 각각의 VM은 자체 OS 및 서비스를 운영하므로 충돌 없이 다중 서비스를 구축하는 데에 유리하다.

가상화의 방식은 크게 세 가지로 나뉜다.

호스트형 가상화: 호스트 OS 위에 가상화 소프트웨어(VirtualBox 등)를 설치해 게스트 OS를 가동한다. 이 구조는 하드웨어 접근 시 반드시 호스트 OS를 경유해야 하므로 성능 저하가 발생할 수 있다.
하이퍼바이저형 가상화: 하드웨어 위에 직접 하이퍼바이저를 설치하고 그 위에 게스트 OS들이 가동되는 구조이다. 별도의 호스트 OS가 존재하지 않아 성능 면에서 유리하다.
컨테이너형 가상화: 도커와 같은 도구로 애플리케이션을 컨테이너 단위로 격리한다. 게스트 OS가 없으며, 커널은 호스트와 공유한다. 즉, 커널 수준의 격리를 통해 VM보다 가볍고 빠른 환경 제공이 가능하다.

컨테이너형은 리눅스 커널에 의존하기 때문에, 리눅스 기반이 아닌 환경에서는 리눅스 커널을 별도로 사용해야 한다. 또한 호스트 머신의 CPU 아키텍처(예: amd64, arm64)는 컨테이너의 실행에도 영향을 미친다. 예를 들어 애플 실리콘(macOS/arm64)에서는 해당 아키텍처를 지원하는 이미지를 사용해야 한다.

도커 구성 요소

도커의 핵심 구성은 다음 세 가지이다.

도커 데몬(dockerd): 백그라운드에서 동작하며 이미지 빌드, 컨테이너 생성 및 관리를 담당. (실제 도커 핵심 엔진 로직)
도커 CLI: 사용자가 명령어를 입력하는 인터페이스
도커 API: CLI나 다른 도구가 데몬과 통신할 수 있도록 하는 API

이러한 구조 덕분에 CLI나 GUI(도커 데스크탑 등)는 결국 API를 호출하는 방식으로 동일한 기능을 수행한다.

CLI 클라이언트를 위한 명령어 모음세트가 결국 docker compose (.yaml) 과 같다고 이해하면 된다.

도커 허브(Docker Hub)는 도커 이미지의 저장소로, GitHub처럼 버전 관리가 가능하고, 동시에 패키지 매니저와 같은 역할도 수행한다. 사용자는 이를 통해 공식 이미지나 개인 이미지 저장 및 배포가 가능하다.

컨테이너 및 이미지 규격은 OCI(Open Container Initiative) 라는 비영리 단체에서 정의하고 있으며, 이는 도커 외에도 Podman 등 다양한 도구들이 이 표준을 따르게 해준다.

도커는 리눅스의 핵심 기능을 조합하여 컨테이너를 구현하고 있으며, 그 핵심은 다음 세 가지이다.

namespace: PID, mount, network 등 시스템 자원을 격리
cgroups: 자원(CPU, memory 등) 사용 제한
chroot: 루트 디렉토리 변경으로 파일 시스템 격리

이로 인해 각 컨테이너는 독립된 PID 1(최상위 프로세스)을 가지며, 이는 호스트와 충돌하지 않는다. 컨테이너 내부에서 ps 명령어를 입력하면 자신의 PID 1만 보이는 것도 이 때문이다.

더 depth 있는 커널에 대한 정보는 https://amsekharkernel.blogspot.com/2016/11/what-is-linux-namespace-cgroups.html 와 Linux Kernel Documentation 의 https://docs.kernel.org/admin-guide/namespaces/index.html, https://docs.kernel.org/admin-guide/cgroup-v2.html 를 추천한다.

이미지

이미지는 컨테이너 실행에 필요한 실행 파일, 라이브러리, 설정 등을 여러 개의 레이어(layer) 로 구성한다. 각 레이어는 tar 아카이브 파일이며, 불변 속성을 갖는다. 여러 이미지가 공통 레이어를 공유할 수 있어 저장 공간 및 네트워크 사용을 최적화할 수 있다.

Dockerfile 은 이미지를 만들기 위한 설정 파일로, 새로운 레이어를 추가하는 역할을 한다.

도커 명령어 기초 지식

초기에는 모든 명령어가 docker 접두사를 사용했지만, 명령어가 너무 많아지면서 v1.13 이후부터 docker container, docker image, docker network 등으로 분기되었다. 이로 인해 명령어 체계가 좀 더 직관적으로 구성되었다.

docker container run [OPTIONS] IMAGE [COMMAND] [ARG...]

특히 4.6장 명령어 치트 시트, 정리가 진짜 잘 되어 있다. sub 명령어 묶음과 container 의 status 에 따라서 flow chart 처럼 정리된 것을 보고 해당 장표 찢어서 어디 벽에 붙여 놓을까 했다. ㅎ

2부 도커 컨테이너 활용법

(5장 ~ 11장)

컨테이너는 PID1과 함께 탄생하고 죽는다

도커 컨테이너 내부에서 실행되는 첫 번째 프로세스는 Linux 시스템 상의 PID1에 해당하며, 이 프로세스가 종료되면 컨테이너 자체가 종료된다.

이는 컨테이너가 본질적으로 하나의 단일 프로세스를 중심으로 동작하는 경량 VM이라는 점을 극명하게 보여주는 설계다. 그래서 컨테이너 정지는 곧 PID1 프로세스의 종료를 의미하고, 그 이후 컨테이너는 stop 명령으로 정지시키거나 rm 명령으로 삭제하는 방식으로 관리된다. (필자는 stop 상태 그대로 둔 적이 딱히 없다고 한다! 물론 나도...)

앞으로 명령어의 상세한 내용은 도커레퍼런스 를 적극 참조하자!

실행(run)과 제거(rm)는 컨테이너 조작의 기본

docker container run ubuntu whoami 처럼 이미지를 기반으로 한 번만 실행하고 끝내는 방식도 가능하다.

~~(그림 설명이 진짜.. 너무 친절하다!!!)~~

이때 whoami 는 명령어 이후 인자는 모두 ARG...로 처리된다. 실행 후 자동 삭제는 --rm 옵션으로 가능하다. (--name 과 --rm 이 조합이 좋음)

--name 으로 컨테이너 이름을 지정하면 관리가 쉬워진다. docker run --rm --name test ubuntu echo hello 같은 조합은 일회성 테스트에 유용하다.

대화형 셸 실행을 위한 옵션

--interactive --tty, 줄여서 -it

--interactive 는 컨테이너의 표준 입력(stdin) 을 열어둔 상태로 유지하여, 사용자가 입력을 계속 보낼 수 있도록 하는 것
--tty 는 가상 터미널(TTY) 을 할당한다. 즉, 컨테이너에서 실행되는 프로세스가 터미널인 것처럼 동작할 수 있게 하는 것이다!

docker container run -it --rm python python3 형태로 Python REPL 을 바로 열 수 있다. bash 셸을 실행할 경우 docker run -it ubuntu bash 와 같이 활용이 가능하다.

포트 매핑으로 웹서버 외부 공개

docker container run --publish 8080:80 nginx 와 같이 --publish 또는 -p 옵션으로 호스트와 컨테이너 간의 포트 바인딩이 가능하다.
이는 웹 개발이나 테스트 시 로컬에서 접속할 수 있는 환경을 만들 때 기본적인 패턴이다!

DB 서버는 환경 변수 세팅이 필수

MySQL 을 예로 들면 아래와 같이 "필수 환경 변수 값" 들이 있다.

docker container run \
--name db \
--rm \
--env MYSQL_ROOT_PASSWORD=secret \
--publish 3306:3306 \
mysql

대부분의 공식 이미지들은 필수 환경 변수들이 명시되어 있으며, MYSQL_DATABASE, MYSQL_USER, MYSQL_PASSWORD 등 추가적인 설정도 가능하다.

도커 허브에 공식 이미지마다 환경 변수 문서가 잘 정리되어 있다!

백그라운드 실행은 detach

--detach 또는 -d 옵션으로 실행하면 컨테이너는 백그라운드에서 실행되고, 사용자 셸은 즉시 반환된다. (사실 이거 detach 가 아니라 daemon 인 줄 알았다.. attach 가 있고, 이 행위와 반대의 detach 개념이라는 점..!) -> 정확하게는 "표준 입출력을 분리" 하는 옵션이다.

docker run -d ... 는 nginx, mysql 같이 지속적으로 동작해야 하는 서버성 컨테이너에 필수적인 실행 방식이다.

컨테이너 출력 확인 logs

docker container logs [OPTIONS] CONTAINER, --follow (-f) 옵션과 함께 사용하면 실시간 로그 확인이 가능하다.

실행 중인 컨테이너에서 명령어 실행

docker container exec [OPTIONS] CONTAINER COMMAND [ARG...]
docker container run [OPTIONS] IMAGE [COMMAND] [ARG...]

docker container exec -it db bash, exec 는 기존에 가동 중인 컨테이너의 내부에서 별도의 프로세스를 실행하는 방식이다.

이미 실행 중인 컨테이너에 접속해서 새로운 명령어를 실행할 수 있는 방법이 exec 이다. run 은 새로운 컨테이너를 만드는 것이고, exec 은 기존에 살아 있는 컨테이너에 명령을 추가로 집어넣는 것이다.

예를 들어 docker container exec -it db bash 와 같은 명령어는 마치 SSH 를 사용하는 것처럼 컨테이너 내부에 진입하는 효과를 준다. 하지만 이는 프로세스 단위의 실행일 뿐, 실제 SSH 가 아니며, VM 과는 다르게 컨테이너는 전체 운영체제를 제공하지 않기 때문에 혼동하면 안 된다! (이는 "호스팅형 가상화" 와 "컨테이너형 가상화" 차이를 알아야 한다는 것이다!)

3부 도커 이미지 활용법

(12장 ~ 15장)

이미지의 기본 내용

도커 이미지는 여러 레이어(layer)로 구성되어 있으며, 최상단의 쓰기 가능 레이어(writable layer) 외에는 모두 읽기 전용(read-only layer)이다. 이미지를 구성하는 각 레이어는 설치나 설정 등 시스템 상태의 변화를 담고 있으며, 최종적으로 컨테이너를 만들 때 이 레이어들 위에 쓰기 가능한 레이어가 덧붙여진다.

메타데이터(metadata)는 이미지 전체의 속성으로 환경 변수, 기본 실행 명령 등을 포함한다.
이미지 명명 방식은 [HOST[:PORT_NUMBER]/][NAMESPACE/]REPOSITORY[:TAG] 형태다.
- HOST 생략 시 기본값은 docker.io
- NAMESPACE 생략 시 library 사용 (공식 이미지)
- TAG 생략 시 latest가 기본값이나, 이는 이미지의 최신 상태가 예기치 않게 변경될 수 있으므로 주의가 필요하다.

도커 이미지 관련 주요 명령어는 docker image --help를 통해 확인 가능하며, --help 옵션을 적극적으로 사용하는게 많은 도움이 된다!

❯ docker image --help
Usage:  docker image COMMAND

Manage images

Commands:
  build       Build an image from a Dockerfile
  history     Show the history of an image
  import      Import the contents from a tarball to create a filesystem image
  inspect     Display detailed information on one or more images
  load        Load an image from a tar archive or STDIN
  ls          List images
  prune       Remove unused images
  pull        Download an image from a registry
  push        Upload an image to a registry
  rm          Remove one or more images
  save        Save one or more images to a tar archive (streamed to STDOUT by default)
  tag         Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE

Run 'docker image COMMAND --help' for more information on a command.

이미지 기본 조작

docker image ls [OPTIONS] [REPOSITORY[:TAG]] : 호스트 머신에 존재하는 이미지 목록을 확인
docker image pull [OPTIONS] NAME[:TAG|@DIGEST] : 외부 레지스트리에서 이미지 다운로드, docker container run 명령어에서도 자동 수행된다!
docker image inspect [OPTIONS] IMAGE [IMAGE...] : 이미지의 상세 메타데이터를 JSON 형식으로 출력
- 특히 RepoTags, Config.Env, Config.Cmd 항목을 확인하면 유용하다!

이미지 조작 명령어는 디버깅과 환경 구성 시의 핵심 도구이며, JSON으로 나오는 상세 정보를 통해 이미지 구성과 환경 변수, 실행 커맨드를 사전에 파악할 수 있다.

vi를 설치한 우분투 이미지를 작성하고 공유하기

docker container run --name myubuntu --interactive --tty ubuntu:22.04 bash
apt update & apt install vim & which vi -> 그냥 ubuntu 이미지에서 which vi 하면 존재하지 않는다!, 이 순서로 myubuntu 에 vim 을 설치하는 것!
컨테이너에서 이미지 작성, docker container commit [OPTIONS] CONTAINER [REPOSITORY:[TAG]] 을 통해 이미지를 새로 만들어 보자!

❯ docker container commit myubuntu vi-ubuntu:commit
sha256:2204542f690c950e74aef2c8d2af737b1f9edb06d3edbb6eb1294a92e718ff62

❯ docker image ls vi-ubuntu
REPOSITORY   TAG       IMAGE ID       CREATED          SIZE
vi-ubuntu    commit    2204542f690c   10 seconds ago   185MB

❯ docker container run --rm vi-ubuntu:commit which vi
/usr/bin/vi

commit 은 컨테이너에서 이미지를 만들지만, 만들어진 이미지는 git 관리 또는 파일 저장소 업로드 불가능하다. 그래서 export 를 활용한다.

이러면 tar 아카이브 파일로 추출이 가능하며, 이후 tar 를 기반으로 image 처럼 읽어 올 수 있다! 그럼 두 명령어는 어떤 차이가 있을까?!

container 중심 말고 당연히 "IMAGE" 중심으로 tar 아카이브파일을 만들고 불러오는 것도 가능하다.

docker image save [OPTIONS] IMAGE [IMAGE...] (다수 이미지 지정 가능하다는 의미) 로 이미지를 tar 아카이브 파일로 작성 가능하며, load 명령어로 다시 이미지화 가능하다! 왜씀? 이미지 백업, 이관 & 이동에 활용!

4부 도커파일 활용법

(16장 ~ 19장)

위에서 살펴본 "tar" 파일 중심으로는 이미지 내용을 알 수 없다. 그렇다고 모르는 tar 를 합쳐서, 하나 하나의 layer 로 활용해서 쓰기에도 쉽지 않고 버전관리도 어렵다. 하지만 도커의 "이미지" 자체를 만들일은 굉장히 많다. 그때 도커파일(Dockerfile)을 사용해야 한다.

Dockerfile 은 컨테이너 환경을 코드로 명확하게 정의하고, 반복 가능한 이미지를 만들 수 있게 해주는 강력한 도구다. 기존엔 컨테이너를 만들고 설정하고 저장하는 흐름이 container run → exec → commit 으로 다소 수동적이었다면, 도커파일은 그 과정을 완전히 코드화할 수 있게 해준다.

특히 이미지를 tar로 만들면 내부 내용이 추상화되어 파악하기 어렵기 때문에, 어떤 이미지든 그 빌드 과정을 명시적으로 남길 수 있는 도커파일은 매우 중요하다.

명령어	설명	예시
FROM	베이스 이미지 지정	FROM ubuntu:22.04
ARG	빌드 시점 변수	ARG VERSION=1.0
ENV	환경 변수 설정	ENV NODE_ENV=production
LABEL	이미지 메타데이터	LABEL maintainer="you@example.com"
WORKDIR	작업 디렉토리 설정	WORKDIR /app
COPY	로컬 파일 복사	COPY . /app
ADD	파일 복사, URL 다운로드, 압축 해제	ADD https://example.com/file.tar.gz /app/
RUN	빌드 시 명령어 실행	RUN apt-get update && apt-get install -y curl
CMD	기본 실행 명령어	CMD ["npm", "start"]
ENTRYPOINT	컨테이너 실행 명령어	ENTRYPOINT ["python3", "app.py"]
EXPOSE	수신 대기 포트	EXPOSE 8080
VOLUME	볼륨 마운트 디렉토리	VOLUME ["/data"]
USER	실행 사용자/UID 설정	USER appuser
HEALTHCHECK	상태 확인 명령어	HEALTHCHECK CMD curl --fail http://localhost:8080
SHELL	기본 셸 지정	SHELL ["/bin/bash", "-c"]
ONBUILD	파생 이미지용 명령어	ONBUILD COPY . /app/src

이 도커파일 명령어들은 이미지가 만들어지는 과정을 '계층별로' 기록하는 역할을 한다. RUN 같은 명령은 실행 결과가 새로운 이미지 레이어로 저장되고, ENV, LABEL, EXPOSE 같은 명령은 이미지의 메타데이터로 저장된다. 도커 이미지가 결국 읽기 전용 레이어들의 조합이고, 도커파일은 그 조합의 '조리법'인 셈이다.

특히 FROM은 도커 이미지의 연쇄 구조를 만들어낸다. 하나의 이미지가 다른 이미지의 기반이 되고, 그 위에 또 다른 이미지가 올라가는 구조인데, 이건 마치 Git의 커밋 히스토리를 타고 올라가듯이 도커 이미지의 뿌리까지 따라갈 수 있다는 뜻이다. 도커 허브에서 이미지를 봤을 때, 어떤 베이스 이미지에서 파생되었는지 확인하는 것도 가능하다.

실습 예시 요약

vi가 가능한 우분투 이미지
- FROM ubuntu
- RUN apt-get update && apt-get install -y vim
- 단순하지만, 이미지 생성 과정을 명확히 기록할 수 있어 재현성과 이식성이 높아짐
시간대 설정 및 로그 출력이 설정된 MySQL 이미지
- FROM mysql:latest
- ENV TZ=Asia/Seoul
- COPY ./my.cnf /etc/mysql/conf.d/
- RUN echo "설정된 시간대와 로그 출력을 위한 설정 포함"
- 운영 환경에 필요한 세밀한 설정을 담을 수 있음
간단한 파이썬 웹 서버 이미지
- FROM python:3.11
- COPY ./app.py /app/app.py
- CMD ["python", "/app/app.py"]
- 단일 파일 기반의 웹 서비스도 도커를 통해 바로 배포 가능한 형태로 구성

5부 ~ 7부, 직접 보면 더 도움이 될 부분들

5부 고급 도커 컨테이너 활용법

5부에서는 도커를 단순한 실행 도구가 아니라, 서비스 환경을 제어하는 방법으로 확장하는 과정을 보여준다. 핵심은 두 가지다: 볼륨과 네트워크.

볼륨: 컨테이너는 기본적으로 휘발성인데, volume 기능을 통해 데이터를 유지할 수 있다. volume create, --mount 옵션을 사용해 데이터를 보존하고, 컨테이너 재시작 시에도 동일한 상태를 유지하게 된다.
- 바인드 마운트를 활용하면 호스트 머신의 디렉토리와 컨테이너 내부를 동기화할 수 있어, 로컬에서 코드나 설정 파일을 수정하면 바로 컨테이너에 반영된다. 실습에서는 루비 컨테이너에 로컬 스크립트를 실행하거나, MySQL 데이터의 지속성을 확보하는 방식으로 이를 체득하게 된다.
- --volume 과 --mount 의 커멘트 차이, 특히 볼륨 마운트와 바인드 마운트를 차이에 집중하는게 아주 좋았다. ~~개인적으로 mount 는 거의 써본적이 전무하다.~~

네트워크: docker network create, --network 옵션을 사용해 여러 컨테이너 간의 통신을 설정할 수 있다. 기본 브릿지 네트워크 외에 독립 네트워크를 정의하고, PHP 컨테이너와 MySQL 컨테이너가 서로 통신할 수 있게 연결하는 구조는 실제 서비스 구성에서 매우 자주 활용된다.

전체적으로 실습 위주이며, 단순한 실행 단계를 넘어서, 컨테이너 간의 협업을 이해하게 해준다. 이 과정은 일종의 "도커로 시스템 아키텍처를 설계하는 감각"을 키우는 데 도움된다.

아래는 개인적인 사견 및 정리

각 컨테이너는 network namespace 안에 있고(서로 격리된 네트워크 공간) 컨테이너마다 veth pair (virtual ethernet pair) 를 생성해서, 하나는 컨테이너 내부에, 다른 하나는 도커 브릿지 네트워크(docker0) 에 연결한다. 그래서 컨테이너 내부 통신 흐름은 아래와 같은 느낌이다.

[컨테이너1] veth0 <--> [브릿지 docker0] <--> veth1 [컨테이너2]

볼륨은 VFS 구조 하에 컨테이너의 mount namespace를 활용해 호스트 디렉토리 또는 독립된 볼륨을 연결하며, 핵심은 mount() syscall을 통해 실제 경로가 연결된다는 점이다.

6부 웹서비스 개발 환경 구축

6부는 개발자가 자주 마주치는 스택 구성 (PHP, MySQL, Mailpit 등)을 도커파일 기반으로 직접 만들어보고, docker compose 로 통합하는 구조를 다룬다. 핵심은 다음과 같다.

Dockerfile을 단계적으로 구성: 각 서비스별로 Dockerfile을 만들고, COPY, RUN, ENV 등을 활용해 설정값과 초기 상태를 명확히 한다.
개별 컨테이너로 실습한 내용을 Compose로 통합: compose.yaml을 통해 의존성을 명시하고, 이름, 네트워크, 볼륨까지 정리한 하나의 선언적 환경 정의 파일로 완성된다.

이 과정에서 중요한 포인트는 "각 컨테이너가 배타적으로 동작하는 게 아니라, 서로 보완하며 작동한다"는 개념이다. 웹 서버가 DB를 참조하고, 메일 서버가 로그를 수신하는 방식은 서비스 간의 연결성과 설정의 유연함을 도커로 어떻게 구성할 수 있는지를 체감할 수 있다.

특히 compose.yaml로 정리할 때의 구조화된 쾌감은 단순한 실습을 넘어선 실전 감각으로 이어진다.

7부 운영 시 주의할 점과 트러블슈팅

7부는 도커를 현업에서 운영단에서 활용하는 시선을 제공한다.

유료 플랜, 도커 계정과 같은 정책적 변화
애플 실리콘 맥에서 ISA 호환 이슈 대응
환경 변수와 .dockerignore, 여러 compose.yaml 파일 결합 활용
디버깅: docker inspect, logs, exec 등을 통해 문제 상황을 좁혀가는 방식

이 파트는 기술적인 팁 외에도, 운영 중 마주칠 수 있는 현실적인 문제들을 예방하고 해결하는 방법론이 담겨 있다. 도커를 쓰면서 언젠가 반드시 맞닥뜨릴 상황들 — 퍼포먼스 문제, 아키텍처 호환성, 계정/정책 변화 등 — 에 대한 대비가 된다.

7부는 실습보다도, 읽으면서 ‘현실 감각’을 얻는 장이다. 개인적으로 이 책에서 가장 유익했던 챕터이기도 하며, 도커를 단순히 실행 도구가 아닌 서비스 운영 플랫폼으로 인식하게 되는 계기였다.

[책 리뷰] NLP 와 LLM 실전 가이드 - 리오르 가지트, 메이삼 가파리

Sat, 29 Mar 2025 14:22:30 GMT

[ "한빛미디어 서평단 <나는리뷰어다> 활동을 위해서 책을 협찬 받아 작성된 서평입니다." ]

NLP 와 LLM 실전 가이드

리오르 가지트(Lior Gazit): 금융 분야 머신러닝 그룹의 수석 디렉터이자 신생 스타트업의 수석 머신러닝 자문위원으로서 업계에서 풍부한 지식과 경험을 바탕으로 존경받는 리더이다. 링크드인

메이삼 가파리(Meysam Ghaffari): 현재 MSKCC에서 근무하며 의료 문제를 해결하기 위한 머신러닝과 자연어 처리 모델의 개발과 최적화에 전념하고 있다. 머신러닝 분야에서 9년 이상, 자연어 처리와 딥러닝 분야에서 4년 이상의 실무 경험이 있다. 링크드인

🔥 8 ~ 9 장을 위한 박조은(옮긴이) 님의 youtube 영상

🔥 실습 코드, 실습 레포

리뷰

진짜 공부하고 싶게 만드는 책이다. 흩어져있는 자연어의 A to Z 를 정석같이 일목요연하게 정리되어 있어서, 모든 챕터 하나 하나가 이정표 역할을 한다. 특히 NLP 입문자에 가까운 나에게 길 잃지말라고 계속 가이드를 준다.

각 챕터가 배경 지식을 하나씩 쌓아가는 형태고, 서술하는 방식이 "장 소개", "목차와 전체 내용" 을 짚고 세부 내용으로 하나씩 진행하는게 "자연어 처리" 라는 분야의 official docs 를 읽는 것 같다.

책은 (주관적으로) 크게 3개 섹터로 이뤄지는 것 같다.

ML을 위한 기초 지식, ML을 학습하기 위한 기존의 방법들 (자연어 처리 중심)
현 시점 SOTA, LLM 에 대한 얘기, 활용과 실습 중심
그리고 미래에 대한 전망

초반부에서 다루는 선형대수, 확률, 통계는 실제로 머신러닝 실습을 하는 사람이라면 반드시 알고 있어야 하는 내용들이다. 다만 이 책은 자세한 설명을 일일이 파고드는 스타일이 아니라, 중요한 핵심 개념을 "놓치지 않게" 딱딱 짚어준다. 개인적으로는 이 부분이 정말 좋았다. 너무 깊게 들어가면 NLP 입문자 입장에서 부담스러울 수 있는데, 딱 적절한 수준에서 정리해준다.

CH3부터 CH6까지는 기존 머신러닝 기반 자연어 처리의 전통적인 구조를 설명한다. 전처리, 피처 엔지니어링, 분류, 모델 평가로 이어지는 이 흐름이 아주 교과서적이다.

특히 좋았던 점은 많은 책들이 대충 넘기는 텍스트 전처리를 이 책은 굉장히 다양한 방법론과 함께 자세히 짚고 간다는 것이다. 소문자화, 특수문자 제거, 정규표현식, 불용어 제거, 표제어 추출, 개체명 인식(NER), 품사 태깅(POS tagging) 등이 각각 어떤 맥락에서 중요하고, 어떤 선택지를 고려할 수 있는지 다룬다. 단순한 예제 코드가 아니라 실무적인 감각으로 설명한다.

그리고 CH6부터는 트랜스포머 기반 딥러닝 언어 모델로 넘어가는데, 여기서부터는 NLP 입장에서의 최신 기술 스택에 대한 안내서처럼 구성된다. RNN, CNN을 넘어서 왜 트랜스포머가 등장했는지, BERT와 같은 모델이 어떻게 문맥을 이해하고 분류 성능을 높일 수 있는지 서술한다.

개인적으로는 여기까지 읽고 "실전 가이드 맞네" 라는 생각이 들었다. 설명은 교과서 같지만, 적용은 실전에 가깝게 잘 정돈되어 있다.

CH7부터 CH9까지는 GPT, BERT, LLaMA, PaLM 같은 대규모 언어 모델의 구조와 트렌드, 활용 사례를 다룬다. 특히 OpenAI의 RLHF 접근 방법을 풀어낸 부분은 실전에서 LLM을 접했던 입장에서 더 인상 깊었다. (~~최근에 읽었던 "GPT API를 활용한 인공지능 앱 개발" 책의 내용을 응축해둔 듯한 느낌~~)

그리고 10장부터는 자연어 처리와 LLM의 현재와 미래에 대한 이야기다. 이 부분은 책의 인문학적인 성격도 살짝 느껴졌다. 무어의 법칙부터 시작해 GPU, TPU, 양자컴퓨팅, LLMOps, 임베딩 구조, 백터DB, RAG의 중요성까지 기술적인 내용과 산업 트렌드를 폭넓게 다룬다. 여기서 인상 깊었던 건 단순히 기술의 발전만을 다룬 것이 아니라, 아래 흐름으로 으로 알려줘서, 지금 그 흐름 위에 있다는 걸 다시 인지 할 수 있었다.

산업 전반에 어떤 변화가 일어났는지
왜 CAIO(Chief AI Officer) 같은 포지션이 등장했는지
다중 에이전트, AutoGen, LFM(대규모 기초모델) 같은 흐름이 왜 주목받는지

딥러닝 기반 자연어 처리의 전통적인 접근부터 LLM, RAG, 그리고 미래까지 이어지는 흐름 속에서 지금 어디에 서 있는지, 앞으로 뭘 알아야 할지를 알려주는 책이다.

현대는 (어떤 형태의) 비즈니스 이전에 테크가 존재할 수는 없다고 생각하며 기술 그 자체로는 결코 목적이 될 수 없다고 생각한다. 우리는 언제나 '무엇을 이루고자 하는가'라는 목적에서 출발해야 한다. 그리고 그 목적을 이루기 위해 가장 날카롭고 적절한 수단과 도구를 선택하는 것이다. 이 책은 바로 그런 관점에서, 다양한 도구와 방법론들을 마치 잘 정리된 도구 상점처럼 펼쳐 보인다.

목차별 리뷰

모든 목차를 다루기엔 책에서 다루는 범위와 영역이 너무 거대해서 할 수 없다..! 상대적으로 유연한 초반부만 좀 세부적으로 정리하고, 후반부는 철저하게 리뷰 중심이다. (PS. 참고로 저작권을 위해 모든 내용은 당연히 있으면 안된다.)

CH1. 자연어 처리 개요 살펴보기

이 장에서는 자연어 처리의 역사와 접근 방식을 간결하게 조망한다. 초창기 튜링 테스트를 시작으로, 50~60년대 룰 기반 처리 방식과 조지타운 실험 사례 가 소개된다. 이후 70년대까지는 구조화된 접근과 개념 기반 온톨로지 도입을 통해 시스템이 조금씩 발전했다.

80년대 후반부터는 대규모 말뭉치를 활용한 통계적 접근법이 등장하면서 자연어 처리 분야가 실질적인 전환점을 맞이했다. 이 시기를 기점으로 머신러닝 기반의 자연어 처리가 본격화되고, 21세기 이후 인터넷과 함께 폭발적으로 증가한 데이터는 비지도, 준지도 학습 알고리즘의 발전을 촉진시켰다. 2010년대 이후 신경망 기반 딥러닝 기술의 등장은 자연어 처리의 패러다임을 또 한 번 바꾸었다.

자연어 처리가 단순 규칙 기반의 기술에서 데이터 기반 학습 기술로 진화해왔음을 시대별 사례를 통해 자연스럽게 보여준다. 최신 기술을 이해하는 데 앞서, 지금 우리가 딥러닝을 자연스럽게 사용하는 배경이 어떤 역사와 전환을 거쳤는지 알 수 있는 장이었다.

자연어 처리 기본 접근 전략

불용어 제거 문장의 전반적인 의미에 큰 영향을 주지 않는 단어들을 제거하는 과정이다. 그러나 상황에 따라 불용어도 중요한 의미를 가질 수 있어 무조건 제거하는 것은 위험할 수 있다. 문맥을 고려한 판단이 필요하다는 점이 강조된다.
어간 추출과 표제어 추출 단어의 시제나 복수형, 파생 접사 등을 제거해 어근 형태로 축소하는 방법이다. 어간 추출은 규칙 기반으로 잘라내는 반면, 표제어 추출은 문맥에 따라 사전 기반으로 판단한다. 두 방식 모두 단어 간 유사성을 높이는 데 쓰이지만, 역시 맥락에 따라 선택이 달라질 수 있다.
데이터 정규화와 정제 단어 단위의 전처리 외에도 텍스트 전반의 구조를 정리하는 과정이다. 특수문자 제거, 소문자화, 중복 공백 제거 같은 기본적인 작업부터, 실제 적용 시에는 파이프라인 형태로 여러 단계의 처리가 연결된다.
전처리 파이프라이닝 여러 전처리 단계를 순차적으로 자동 처리할 수 있도록 구성하는 방식이다. 정제, 정규화, 필터링, 토큰화 등을 하나의 흐름으로 묶는 설계 방식으로, 이후 모델 학습에 사용될 데이터를 일관성 있게 다듬을 수 있다.
사전 학습 모델과 트랜스포머의 등장 BERT, 트랜스포머 같은 모델이 자연어 처리에 끼친 영향이 간단히 소개된다. 기존의 전처리나 피처 엔지니어링에만 의존하던 방식에서 벗어나, 모델 자체가 문맥을 이해하는 구조로 바뀌었음을 시사한다.

CH2. 머신러닝과 자연어 처리를 위한 선형대수, 확률, 통계 마스터하기

거의 7~~9년 전 기억이 나서 굉장히 슬펐다(?). ~~~그때 진짜 싫었는데..~~~ 그리고 솔직히 스스로 depth 있게 modeling 을 안하니, 이 개념을 놓치고 살았고, ~~~앞으로도 놓치고 살고 싶다는 생각이 들었다 ㅎㅎ.~~ 만약 이 개념이 생소하면 https://youtu.be/k_yto_vDRF0?si=m2oNb5lfz68rcHcs 과 같은 영상이라도 한 번 보는 것을 추천한다. 엄청 자세하게 정리하려고 하지는 않았는데, 스스로 정리차원에서 하나씩 곱씹어봤다.

ML 을 위한 기본적인 선형대수학

[1] 스칼라, 벡터, 행렬

스칼라 (Scalar): 단일 수 (예: 3, -5, 0.2).
벡터 (Vector): 숫자의 나열로, 행 벡터와 열 벡터로 구분됨.
행렬 (Matrix): 2차원 숫자 배열로, 머신러닝에서 데이터를 표현하는 기본 구조.
텐서 (Tensor): 다차원 배열을 의미하며, 벡터와 행렬을 일반화한 개념.

[2] 벡터 연산

벡터 덧셈: 동일한 차원의 벡터끼리 요소별 덧셈 수행.
벡터 내적 (Dot Product): 두 벡터의 대응 원소 곱의 합.
- 내적 결과는 스칼라 값. 내적은 다른 벡터에 얼마나 투영되는지 측정하는데 사용.
- 내적은 교환법칙 성립, 벡터 순서가 결과에 영향 X
- 내적이 0이면 두 벡터는 서로 직교(orthogonal).
- 내적 공식:

$$ \mathbf{a} \cdot \mathbf{b} = a_1b_1 + a_2b_2 + \dots + a_nb_n $$

벡터 외적 (Cross Product): 3차원 벡터에서 정의되며, 두 벡터에 모두 수직(orthogonal)인 벡터를 생성하며, 방향은 오른손 법칙을 따른다. 외적 결과는 벡터 값.
벡터의 노름 (Norm)
- 벡터의 크기를 나타내는 값. 벡터 자신과 내적은 제곱 노름.
- 가장 많이 사용되는 노름: 유클리드 노름 (Euclidean Norm)
- 유클리드 노름 공식:

$$ |\mathbf{a}|_2 = \sqrt{a_1^2 + a_2^2 + \dots + a_n^2} $$

[3] 행렬 연산

행렬 전치 (Transpose): 행과 열을 바꾸는 연산.
- 행 벡터 ↔ 열 벡터 변환.
- 전치 연산 예시:

$$ A^T_{m \times n} = A_{n \times m} $$

행렬과 벡터의 곱: 결과는 벡터가 됨.
행렬의 행렬곱 (Matrix Multiplication):
- $$A (m × n)$$ 과 $$B (n × p)$$ 가 있을 때, 결과는 $$(m × p)$$ 행렬.
- 교환법칙 성립하지 않음: $$(AB \neq BA)$$

[4] 고윳값과 고유 벡터 (Eigenvalues and Eigenvectors)

정의:
- 행렬 $$(A)$$ 에 대해 다음을 만족하는 벡터 $$(\mathbf{v})$$ 와 상수 $$(\lambda)$$ 가 존재할 때:

$$ A\mathbf{v} = \lambda \mathbf{v} $$

$$(\lambda)$$는 고윳값(Eigenvalue), $$(\mathbf{v})$$ 는 고유 벡터(Eigenvector).
- 고윳값 분해 (Eigendecomposition):
대각화 가능한 행렬 $$(A)$$ 는 다음과 같이 표현 가능:
- $$(D)$$: 대각행렬 (고윳값이 대각 원소로 위치)
- $$(P)$$: 고유 벡터를 열 벡터로 가지는 행렬

$$ A = PDP^{-1} $$

ML에서의 활용:
- 주성분 분석(PCA): 데이터 차원 축소를 위해 고윳값 분해 활용.
- 특잇값 분해(SVD): 비정방 행렬의 차원 축소에 활용.

ML 을 위한 기본적인 확률

[1] 확률 개념

시행 (Trial): 한 번의 실험.
실험 (Experiment): 확률적 결과를 가지는 과정.
표본 공간 (Sample Space): 가능한 모든 결과의 집합.
사건 (Event): 표본 공간의 부분집합.

[2] 확률 변수 (Random Variable)

이산 확률 변수 (Discrete Random Variable):
- 가능한 값이 유한 개 또는 셀 수 있는 경우.
- 확률 질량 함수(PMF, Probability Mass Function)로 표현.
연속 확률 변수 (Continuous Random Variable):
- 값이 연속적인 경우.
- 확률 밀도 함수(PDF, Probability Density Function)로 표현.

[3] 조건부 확률과 독립성

조건부 확률 (Conditional Probability):
- 사건 B가 발생한 상태에서 사건 A가 발생할 확률:

$$ P(A|B) = \frac{P(A \cap B)}{P(B)} $$

독립 사건 (Independent Events):
- 사건 A와 B가 서로 독립이면:

$$ P(A \cap B) = P(A)P(B) $$

[4] 최대 우도 추정법 (Maximum Likelihood Estimation, MLE)

MLE 개념:
- 확률 분포의 매개변수를 추정하는 방법.
- 가능도 함수 (Likelihood Function)를 최대화하는 매개변수 선택.
로그 우도 (Log-Likelihood):
- 곱셈 연산보다 덧셈이 계산적으로 더 유리하여 로그 우도 사용:

$$ \log L(\theta) = \sum_{i=1}^{n} \log P(x_i | \theta) $$

자연어 처리에서 활용:
- 다음 단어 예측에서 가장 높은 확률을 갖는 단어를 선택하는 방식으로 사용.
- 즉, 주어진 문맥 𝑤 1 , 𝑤 2 , . . . , 𝑤 𝑡 − 1 가 있을 때, 다음 단어 𝑤 𝑡 의 확률을 최대화하는 모델을 찾는 것. 가능도 함수(Likelihood Function) 활용.

[5] 베이지안 추정 (Bayesian Estimation)

베이즈 정리 (Bayes' Theorem):
- 사전 확률과 데이터에 기반한 사후 확률 계산:

$$ P(\theta | D) = \frac{P(D | \theta) P(\theta)}{P(D)} $$

MLE 와 달리 사전 확률을 고려하는 방식.

[6] 추가 개념

하우스홀더 반사 행렬 (Householder Reflection Matrix):
- 벡터를 특정 차원에서만 0이 아닌 성분을 갖도록 변환하는 행렬.
대각화 가능성 (Diagonalizability):
- 행렬이 대각화 가능하면 계산이 용이함.
가역 행렬 (Invertible Matrix):
- 역행렬이 존재하는 행렬.
가우스 소거법 (Gaussian Elimination):
- 연립 방정식 풀이를 위한 행렬 변형 기법.
행렬의 대각합 (Trace of a Matrix):
- 대각 원소의 합.
- 선형 변환의 고윳값 합과 동일.

CH3. 자연어 처리에서 머신러닝 잠재력 발휘하기

데이터 탐색

자연어 처리 모델의 성능은 입력 데이터 품질에 크게 좌우된다. 이 장에서는 데이터를 탐색하고 정제하는 과정에서 고려해야 할 핵심 요소들을 설명한다. 먼저 결측치는 전체 분석의 왜곡을 야기할 수 있으므로 반드시 처리해야 하며, 중복 데이터 역시 불필요한 중복 학습을 유발할 수 있으므로 제거 대상이다.

데이터 표준화에서는 각 특성(feature)의 평균을 0, 표준편차를 1로 맞추는 Z-score 정규화가 자주 사용된다. 반면 최소-최대 스케일링은 데이터를 0과 1 사이로 정규화하는 방법으로, 각 값의 상대적인 크기를 유지하며 모델이 특정 특성에 과도하게 민감하지 않게 도와준다.

Z-score 정규화 (Standardization) $$x' = (x - μ) / σ$$
- μ는 특성의 평균 (mean)
Min-Max 정규화 (Min-Max Scaling)

$$ x' = \frac{x - x_{\text{min}}}{x_{\text{max}} - x_{\text{min}}} $$

이상치 처리는 모델 안정성에 중요하다. 윈저화는 일정 범위 밖의 값들을 경계 값으로 조정해 이상치의 영향을 줄이는 기법이다. 또는 강건한 통계 기법을 활용해 이상치를 억제할 수도 있다. 중요한 건 이상치를 제거하는 것이 아니라, 그것이 분석 결과에 어떤 영향을 미치는지 파악하고 도메인 지식과 함께 판단해야 한다는 점이다.

데이터 오류 수정은 통계적 이상 탐지나 수동 검사 외에도 머신러닝 기반 접근법이 가능하다. 도메인 지식이 병행되면 신뢰도는 더욱 높아진다. 이후 가장 중요한 과정 중 하나는 특성 선택(feature selection) 이다. 정보량 기반 방법, 카이제곱 검정, 상관계수 분석, 라쏘 회귀(L1 패널티) 등을 통해 유의미한 특성을 골라야 한다. 또한, 고차원 데이터에서는 차원 축소 기법인 PCA(주성분 분석), LDA(선형 판별 분석)도 유효하다.

일반적인 머신러닝 모델 인프런, 파이썬 머신러닝 완벽 가이드 (추천...)

선형 회귀는 연속적인 수치 예측에 적합하고,
로지스틱 회귀는 이진 분류에 활용된다.
결정 트리는 해석이 쉬운 구조로 분류와 회귀 모두 가능하지만 과적합되기 쉬우며,
랜덤 포레스트는 여러 결정 트리를 앙상블하여 안정성과 성능을 향상시킨다.
SVM(서포트 벡터 머신) 은 고차원에서의 마진 최대화를 통해 분류 문제에 강력하며,
인공 신경망은 복잡한 비선형 관계를 학습할 수 있어 텍스트, 음성, 이미지 등 다양한 도메인에서 활용된다.

특히, 트랜스포머는 자연어 처리에서 혁신적 성능을 보여준 구조로, 셀프 어텐션을 기반으로 문맥을 효과적으로 반영하는 구조다. 이는 후속 챕터에서 더 깊이 다루어진다.

모델 과소적합과 과대적합

모델이 너무 단순해서 학습 데이터조차 설명하지 못하는 경우는 과소적합(underfitting), 반대로 지나치게 복잡해 학습 데이터에만 특화된 경우는 과대적합(overfitting)이다. 이 둘의 균형을 맞추는 것이 편향-분산 트레이드오프이다.

이를 해결하기 위한 전략으로는

정규화 기법(L1 라쏘, L2 릿지, 또는 두 방법을 혼합한 엘라스틱넷),
교차 검증,
조기 종료(validation loss가 더 이상 줄어들지 않을 때 학습 중단),
드롭아웃(신경망 일부 노드를 임의로 비활성화),
데이터 증강,
앙상블 등이 있다.

데이터 분할

모델 학습 과정에서 데이터를 훈련(train), 검증(validation), 테스트(test) 세트로 나누는 것은 일반적인 접근이다. 기본적으로 8:2로 훈련-테스트를 나누거나, 더 정교하게는 K-폴드 교차 검증으로 평가의 일관성을 확보한다. 계층화 K-폴드는 클래스 불균형을 다루는 데 유용하며, 시계열 데이터의 경우 시간 순서를 고려하여 분할해야 한다.

하이퍼파라미터 튜닝

모델 학습 전에 설정하는 값들인 하이퍼파라미터(hyperparameter)는 모델 성능에 큰 영향을 미친다. 예를 들어, 학습률, 정규화 강도, 은닉층 수 등이다.

이를 튜닝하기 위한 방법에는

그리드 탐색(grid search): 조합을 전수조사
랜덤 탐색(random search): 무작위 조합을 샘플링
베이지안 최적화: 이전 결과 기반으로 다음 탐색 지점 예측

특히 SMBO(Sequential Model-Based Optimization)는 성능 예측 모델을 통해 탐색 효율을 높인다. 하이퍼파라미터 튜닝은 탐색 공간이 크고 평가 비용이 높기 때문에 샘플링 전략과 병렬화 등이 고려되어야 한다.

앙상블 모델

앙상블 학습은 여러 모델의 예측을 결합하여 전체 성능을 향상시키는 방법이다.

배깅(Bagging - Bootstrap Aggregating)

작동 원리: 원본 데이터셋에서 부트스트랩 샘플링(복원 추출)을 통해 여러 서브셋을 생성하고, 각 서브셋에서 동일한 유형의 모델을 학습시킨 후 결과를 통합한다.
통합 방식: 분류 문제에서는 투표(voting), 회귀 문제에서는 평균(averaging)을 사용한다.
장점: 분산(variance)을 감소시켜 과적합을 줄이고 모델의 안정성을 높인다.
주요 알고리즘:
- 랜덤 포레스트: 부트스트랩 샘플링으로 얻은 각기 다른 훈련 데이터를 사용하고, 특성 또한 매번 랜덤하게 선택하여 다양성을 높이는 방법이다.
- 배깅 결정 트리: 동일한 알고리즘을 사용하지만 다른 훈련 데이터로 여러 모델을 훈련시키는 방법이다.

부스팅(Boosting)

작동 원리: 약한 학습기(weak learner)를 순차적으로 학습시키며, 이전 모델이 잘못 예측한 샘플에 더 높은 가중치를 부여한다.
특징: 이전 모델의 오류에 집중하여 점진적으로 예측 성능을 향상시킵니다.
주요 알고리즘:
- AdaBoost(Adaptive Boosting): 오분류된 샘플에 더 높은 가중치를 할당하며, 각 모델의 정확도에 따라 최종 예측에 다른 가중치를 부여한다.
- Gradient Boosting: 이전 모델의 잔차(residual)나 오차에 대해 다음 모델을 학습시킵니다. 이 방식은 손실 함수의 기울기(gradient)를 최소화하는 방향으로 진행된다.
- XGBoost, LightGBM, CatBoost: Gradient Boosting의 최적화된 구현으로, 속도와 성능 측면에서 개선되었다.

스태킹(Stacking)

작동 원리: 여러 기본 모델(base model)의 예측 결과를 새로운 특성으로 사용하여 메타 모델(meta-model)을 학습시킨다.
구현 방식: 다양한 알고리즘으로 여러 기본 모델을 학습시킵니다 (예: 결정 트리, SVM, 로지스틱 회귀 등).
- 각 기본 모델의 예측값을 새로운 특성으로 변환한다.
- 이 새로운 특성들을 입력으로 사용하는 메타 모델을 훈련시킨다.
장점: 각 모델의 강점을 활용하고 약점을 상쇄하여 전체적인 예측 성능을 향상시킨다.
구현 시 고려사항: 기본 모델 결과의 과적합을 방지하기 위해 교차 검증을 통한 예측값 생성이 중요하다.

CH4. 자연어 처리 성능을 위한 텍스트 전처리 과정 최적화

전처리는 중요한 초기 단계이다. "원시 상태" 의 자연어를 "머신러닝 알고리즘이 쉽게 이해할 수 있는 형식" 으로 변환하는 과정 포함한다.

자연어 처리에서의 소문자 변환, 특수 문자와 구두점 제거, 불용어 제거, 개체명 인식 (NER), 품사 태깅(POS 태깅), 전처리 파이프라인 을 다룬다. NLTK, spaCy, 사이킷런 라이브러리 활용한다. (with 쥬피터노트북)

1. 자연어 처리에서의 소문자 변환

소문자 변환은 텍스트 전처리에서 가장 먼저 수행되는 작업 중 하나로, 전체 어휘 집합의 복잡도를 줄이고 통일성을 확보하는 데 도움이 된다. 예를 들어 "Apple"과 "apple"을 동일하게 처리함으로써 분류기나 모델이 더 안정적으로 학습할 수 있다.
하지만 모든 상황에서 유용한 것은 아니다. 특히 개체명 인식(NER)에서는 대문자 정보가 중요한 신호가 되기 때문에, 무작정 소문자로 바꾸는 것이 오히려 성능 저하로 이어질 수 있다.
책에서 소개된 정규 표현식 예시인 re.sub(r'[^A-Za-z0-9]+', '', text)는 공백까지 제거하는 잘못된 패턴으로 보인다. re.sub(r'[^A-Za-z0-9\s]+', '', text) 처럼 공백은 살리고 특수 문자만 제거하는 패턴을 말하고자 한 것 같다.

2. 특문과 구두점 제거

텍스트에서 특수 문자나 구두점은 대부분 의미가 약하거나 노이즈로 작용하는 경우가 많다. 따라서 이들을 제거함으로써 모델의 학습을 보다 효과적으로 만들 수 있다. 그러나, 예외적인 경우(예: 감정 분석에서 느낌표)에는 정보 손실로 이어질 수 있어 주의가 필요하다.

3. 불용어 제거

불용어(stopwords)는 텍스트 의미에 큰 영향을 주지 않는 단어들로, 예: a, an, the, and, in, at 등이 있다. 불용어 제거를 통해 어휘 크기와 특성 공간의 차원을 줄여 효율성을 높일 수 있다.
한글 불용어 제거

4. 맞춤법 검사와 교정

텍스트 내 오타나 철자 오류는 전처리 단계에서 수정해야 한다. 사소한 오탈자 하나가 모델의 처리 단위를 바꿔 성능을 저하시킬 수 있기 때문이다.

5. 표제어 추출

단어를 기본 형태 또는 사전 형태인 표제어로 단순화하는 텍스트 정규화 방법이다.
예: "cats" → "cat", "mice" → "mouse". 단어의 품사 정보까지 고려하므로 정교한 처리가 가능하다.

6. 어간 추출

단어를 기본적이거나 뿌리 형태로 축소하는 과정이다. 이때 뿌리를 어간(stem) 이라 한다.
품사나 문맥은 고려하지 않기 때문에 다소 과도한 변형이 발생할 수 있음을 유의해야 한다.
KoNLPy 의 okt 형태소 분석기가 어간 추출 기능 제공한다.

개체명 인식

NER은 텍스트 내에서 사람, 조직, 장소와 같은 고유명사를 탐지하고 분류하는 작업이다.
주로 조건부 무작위장(CRF), 순환 신경망(RNN) 기반 모델이 사용된다.
트랜스포머 기반의 BERT 역시 최근 NER 성능을 크게 향상시킨 대표적 모델이다.
이 챕터에서는 관련 구현 예제를 깃허브 코드로 제공한다.

품사 태깅

단어에 명사, 동사, 형용사 등의 품사 태그를 부여하는 과정으로, 다음 세 가지 접근이 있다.

규칙 기반 방법
예: 단어가 -ing로 끝나면 동명사일 가능성, 앞에 관사가 있으면 명사일 가능성
통계 기반 방법
은닉 마르코프 모델(HMM), 조건부 랜덤 필드(CRF)를 활용한 확률적 추론 기반
문맥에 따라 가장 가능성 높은 품사를 선택한다.
딥러닝 기반 방법
RNN, 특히 LSTM 셀을 사용한 시퀀스 모델 기반의 접근
입력 레이어에 워드 임베딩을 넣고, LSTM 레이어를 통해 문맥 정보를 처리한 뒤, 출력 레이어에서 품사 태그를 예측한다.
최근에는 BERT 같은 트랜스포머 기반 모델이 더 높은 정확도로 POS 태깅을 수행한다.
관련 코드도 깃허브 레포에 포함되어 있다.

정규 표현식

regex, regexp, 쉽고 빠른 유효성 검증 가능한 접근 법이다.
검색 및 교체, 특정 패턴에 따른 데이터 추출에 유리하다!

토큰화

tokenization, 텍스트를 토큰 단위로 분리하는 과정이다.
단어 토큰화: 공백이나 구두점을 기준으로 분리
문장 토큰화: 마침표, 느낌표 등을 기준으로 분리
서브워드 토큰화: WordPiece(BERT), Byte Pair Encoding(BPE) 등을 활용해 희귀어(OOV)를 처리
- BERT에서는 WordPiece 방식이 사용되며, 드물거나 긴 단어도 부분적으로 분할해 처리할 수 있는 장점이 있다.

전처리 파이프라인 예시와 개체명 인식 및 품사 태깅은 깃허브 레포 코드로 상세하게 볼 수 있다.

CHAPTER 5 텍스트 분류 강화: 전통적인 머신러닝 기법 활용하기

텍스트 분류의 유형

텍스트 분류는 말 그대로 텍스트 데이터를 어떤 카테고리에 속하는지 판단하는 작업이다. 이때 사용할 수 있는 학습 방식은 크게 지도 학습, 비지도 학습, 준지도 학습으로 나뉜다.

지도 학습은 레이블이 부여된 데이터를 통해 학습하고, 이후에는 새로운 텍스트에 대해 자동으로 레이블을 예측할 수 있다. 주요 알고리즘으로는 나이브 베이즈, 로지스틱 회귀, 서포트 벡터 머신(SVM)이 있다. 특히 SVM은 초평면을 이용한 분류로 유명하다.
비지도 학습은 레이블 없이 데이터 내 숨겨진 구조나 패턴을 발견하는 접근이다. 군집화(Clustering), LDA(Latent Dirichlet Allocation, 잠재 디리클레 할당), Word2Vec, GloVe와 같은 임베딩 기반 학습 등이 대표적이다. 특히 Word2Vec과 GloVe는 단어를 밀집 벡터로 표현하여 의미론적 유사성을 잘 반영할 수 있도록 한다.
준지도 학습은 지도와 비지도의 중간 형태로, 레이블이 일부만 부여된 상황에서 지도학습과 비지도학습을 혼합하여 모델을 훈련시킨다. 대표적인 방법으로 레이블 전파(Label Propagation), 공동 훈련(Co-training) 등이 있다.

TF-IDF를 활용한 텍스트 분류

가장 전통적인 텍스트 분류 접근은 원-핫 인코딩(One-hot Encoding)이나 단어의 등장 빈도를 바탕으로 특징을 추출하는 방법이다. 흔히 사용하는 방법이 단어의 출현 빈도를 기준으로 문서를 벡터화하는 단어 가방(Bag of Words, BoW) 모델이다.

BoW의 단점은 문서마다 단어의 중요도를 반영하지 못하는 것인데, 이를 보완하기 위해 등장한 것이 TF-IDF(Term Frequency - Inverse Document Frequency)이다.

TF 는 특정 문서에서의 단어 빈도
IDF 는 그 단어가 다른 문서에서 얼마나 드물게 나타나는지를 수치화

이를 곱한 TF-IDF 값이 클수록 특정 문서에서 해당 단어가 중요하다고 판단한다.

TF-IDF 는 단어의 중요도를 반영한 특징 벡터를 만들어 SVM, 로지스틱 회귀 등의 분류기에 적용할 수 있으며, 실무에서도 여전히 많이 사용되는 전통적인 접근이다.

Word2Vec을 활용한 텍스트 분류

Word2Vec 은 단어를 저차원의 실수 벡터로 임베딩하는 모델이다. 두 가지 주요 학습 방법이 존재한다.

CBOW(Continuous Bag of Words): 주변 단어들을 보고 중심 단어를 예측
Skip-gram: 중심 단어를 보고 주변 단어들을 예측

Word2Vec은 학습 과정에서 확률적 경사 하강법(SGD)과 역전파(backpropagation)를 사용하여 모델 파라미터를 최적화한다. 결과적으로 학습된 임베딩은 유사한 의미를 가진 단어들이 벡터 공간에서 가까운 위치를 갖도록 표현된다.

Word2Vec을 활용하면 문서 전체를 단어 임베딩의 평균이나 합으로 표현하여 분류 문제에 활용할 수 있다.

토픽 모델링: 비지도 텍스트 분류의 특정 사례

토픽 모델링은 비지도 학습의 대표적인 사례로, 문서가 어떤 주제를 다루는지 자동으로 파악하는 방법이다. 가장 대표적인 알고리즘은 LDA(Latent Dirichlet Allocation)이다.

LDA는 각 문서가 여러 토픽의 혼합으로 구성되었고, 각 토픽은 단어들의 확률분포로 표현된다고 가정한다. 이를 통해 문서에 숨겨진 주제 분포를 추정한다.

LDA는 클러스터링이나 추천 시스템 등 다양한 NLP 태스크에 활용되며, 레이블이 없는 상황에서 유용하게 쓰인다.

머신러닝 시스템 설계

실제 분류 모델을 만들기 위해서는 학습 데이터를 분할하고(훈련/검증/테스트), 모델을 훈련한 후 적절한 평가 지표로 성능을 검증해야 한다. 또한 하이퍼파라미터 튜닝은 반드시 필요한 과정이다.

하이퍼파라미터는 학습 전에 설정하는 파라미터로, 학습 중에는 변경되지 않는다. 예를 들어 나이브 베이즈의 알파값, SVM의 C 값, 로지스틱 회귀의 정규화 계수 등이 이에 해당한다.

하이퍼파라미터는 모델의 성능에 큰 영향을 미치기 때문에 그리드 서치나 랜덤 서치 같은 방법으로 적절히 탐색해야 한다.

CH6. 텍스트 분류의 재해석: 딥러닝 언어 모델 깊게 탐구하기

딥러닝은 텍스트 데이터를 다루는 데 있어 기존의 RNN, CNN을 넘어서는 혁신적인 전환점을 마련해왔다. 이 장에서는 딥러닝과 자연어 처리(NLP)의 결합을 어떻게 실현할 수 있는지, 그리고 최근 가장 각광받는 트랜스포머 기반 언어 모델들이 어떤 구조와 원리로 작동하는지를 다루고 있다.

(이미지 출처: https://heung-bae-lee.github.io/2019/12/08/deep_learning_03/)

신경망의 기본 구성은 입력층, 은닉층, 출력층으로 나뉜다. 특히 은닉층은 입력과 출력 사이에서 정보를 가공하며, 가중치의 곱과 편향을 합산한 뒤 활성화 함수를 통해 비선형성을 도입한다. 주요 활성화 함수로는 Sigmoid, Tanh, ReLU, ELU 등이 있으며, 각각의 특성에 따라 네트워크의 성능이나 수렴 속도에 영향을 준다.

또한 학습의 반복을 나타내는 Epoch, 한 번의 학습에서 사용하는 데이터 크기를 의미하는 배치 크기(Batch size) 등의 하이퍼파라미터는 과대적합과 과소적합을 피하면서 최적 성능을 달성하는 데 매우 중요하다.

다양한 신경망 아키텍처

FNN (Feedforward Neural Network): 기본적인 전방향 신경망
MLP (Multilayer Perceptron): 은닉층이 1개 이상인 구조
CNN (Convolutional Neural Network): 이미지 처리에 적합한 구조로, NLP에서도 특징 추출 목적으로 사용됨
RNN (Recurrent Neural Network): 시퀀스 데이터를 다룰 수 있는 구조로, 이전 상태의 정보를 메모리 셀에 저장
AE (Autoencoder): 입력을 압축하고 다시 복원하는 방식의 비지도 학습 모델
GAN (Generative Adversarial Network): 생성자와 판별자가 경쟁하는 구조

트랜스포머 이해하기

트랜스포머는 논문 Attention is All You Need에서 처음 소개된 모델로, 순차적 연산이 필요했던 RNN과 달리 병렬 처리가 가능하다는 점에서 큰 혁신을 일으켰다. 핵심은 Self-Attention 메커니즘이다.

Self-Attention (셀프 어텐션)은 입력 시퀀스 내에서 각 단어가 다른 단어들과 얼마나 연관이 있는지를 파악하고, 그에 따라 가중치를 부여하는 방식이다. 이를 위해 각 단어 임베딩은 선형 변환을 거쳐 쿼리(Q), 키(K), 값(V)로 변환된다. 그 후, 다음 수식을 통해 어텐션 점수가 계산된다:

$$ \text{Attention}(Q, K, V) = \text{softmax}\left( \frac{QK^T}{\sqrt{d_k}} \right)V $$

이 점곱 어텐션은 Scaled Dot-Product Attention이라 불리며, 계산된 값이 너무 크거나 작아지는 것을 방지하기 위해 $$\sqrt{d_k}$$ 로 나눈다.

한편, 트랜스포머는 순차 정보를 고려하지 않기 때문에 입력 임베딩에 위치 인코딩을 더해 각 단어의 순서를 보완한다. 위치 인코딩은 사인/코사인 함수를 활용하여 각 차원별로 주기적인 위치 정보를 부여한다.

가장 좋았던 부분은 "BERT를 텍스트 분류에 미세 조정을 하는 방법" 이 있다는 것이다. 물론 이론적인 부분이 과반이지만 앞서 설명한 얘기를 기반으로 진행하기 때문에 설명이 친절한 편이라고 생각된다. 실제로 해당 장의 마지막엔 실습이 코드와 함께 있음 (물론 실제 하려면 사전 세팅이나 준비 사항이 꽤 많이 필요함)

CH7. 대규모 언어 모델 이해하기

이번 장에서는 대규모 언어 모델(LLM, Large Language Model)의 탄생 배경과 발전 과정을 중심으로 설명하고 있다. 본격적으로 LLM이 주목받기 시작한 2018~2019년부터, 2023년에 이르기까지 NLP 분야에서 일어난 변화들을 연대기적으로 서술한다.

OpenAI가 ChatGPT로 널리 알린 RLHF는 LLM 발전의 가장 중요한 전환점 중 하나였다.

기존의 언어 모델은 단순히 대량의 데이터를 이용한 사전 학습(Pretraining)과, 정답이 있는 문제에 대한 지도 학습(Supervised Fine-Tuning)만으로는 사용자의 기대에 부합하는 응답을 생성하기 어려웠다. 이를 해결하기 위해 도입된 것이 RLHF다.

기본적인 흐름은 다음과 같다.

Supervised Fine-Tuning (SFT)
우선 사람이 직접 작성한 고품질 응답 데이터를 바탕으로 언어 모델을 지도 학습한다.
Reward Model (RM) 학습
사람이 두 응답 중 더 좋은 것을 선택하여 쌍 비교 데이터(pairwise preference)를 제공하면, 이를 통해 모델이 무엇이 더 좋은 응답인지를 학습하는 보상 모델(Reward Model)을 구축한다.
PPO (Proximal Policy Optimization)
이후 모델의 출력을 RM을 통해 평가하면서 강화학습을 진행한다. PPO는 강화학습에서 흔히 사용되는 기법으로, 모델의 정책이 너무 급격하게 변화하지 않도록 안정성을 확보하는 목적을 가진다. 이 과정을 통해 모델은 사람의 피드백을 반영한 보다 유용하고 안전한 응답을 생성할 수 있게 된다.

실제로 OpenAI는 RLHF를 통해 GPT-3를 ChatGPT로 발전시켰고, Google은 PaLM을, Meta는 LLaMA 시리즈를, Anthropic은 Constitutional AI를 적용한 Claude를 발표했다. 특히 RLHF 기반 모델은 사용자의 피드백을 받아 들이며, 이전보다 훨씬 정교한 대화와 문장 생성을 보여주었다.

CH8. 대규모 언어 모델의 잠재력을 끌어내는 RAG 활용 방법

이 장에서는 최근 LLM 응용에서 핵심 키워드가 된 RAG (Retrieval-Augmented Generation)의 개념과 활용법, 그리고 이를 실제로 구현하기 위한 기술 스택으로 LangChain을 소개한다. 또한, OpenAI API 기반 접근법과 로컬에서 LLaMA, GPT-J 같은 오픈소스 모델을 세팅하는 실전적인 예제도 포함되어 있다.

LangChain 파이프라인

RAG를 제대로 활용하기 위해서는 LLM 단독으로는 부족하고, 외부에서 정보를 검색하고, 이를 활용하여 답변을 생성하는 파이프라인이 필요하다. 이를 위해 LangChain 프레임워크가 소개된다.

LangChain은 다양한 LLM과 데이터 소스를 연결하고, 체계적으로 응답을 생성할 수 있게 도와주는 파이썬 기반 오픈소스 라이브러리이다.

Component (컴포넌트): LangChain의 최소 단위로, 프롬프트 템플릿, LLM, 메모리, 툴 등 다양한 유형이 존재
Chain (체인): 여러 컴포넌트를 순차적으로 연결하여 하나의 일관된 흐름을 만드는 구조
Agent (에이전트): 체인과 달리, 스스로 의사결정을 하고, 필요한 툴을 골라 사용하며 상황에 맞게 동작을 수행

RAG 뿐만 아니라, LangChain에서는 메모리라는 개념도 중요한데, 이는 이전 대화나 정보를 저장하여 이후 대화에 활용하는 기능이다. 메모리를 활용하면 대화형 에이전트가 앞선 대화 내용을 기억하고 이를 기반으로 더 자연스럽고 일관성 있는 대화를 이어갈 수 있다. 특히 LLM이 가진 한계 중 하나인 컨텍스트 윈도우 문제를 보완할 수 있는 중요한 장치이다.

CH9. 대규모 언어 모델이 주도하는 고급 응용 프로그램 및 혁신의 최전선

이번 장에서는 대규모 언어 모델(LLM)을 활용한 고급 시스템 설계와 최근 주목받고 있는 다양한 응용 기술들을 실습 중심으로 소개한다. 특히 LangChain을 활용한 고급 RAG, 프롬프트 최적화, 다중 에이전트 구성까지 이어지는 내용이 흥미롭다.

Retriever, Memory, Chain, Agent를 단순히 나열하는 수준이 아니라, 여러 개의 컴포넌트를 유기적으로 연결하여 더욱 정교한 시스템을 구축한다.

예를 들어, 사용자의 질문이 들어왔을 때 적절한 Retriever를 조건부로 선택하거나, 검색된 여러 정보를 우선순위로 정렬한 후 LLM에 전달하는 등 보다 실용적인 로직을 실습 형태로 설명하고 있다.

프롬프트 압축 (LLM Lingua)

LLM을 사용할 때 가장 큰 문제 중 하나는 프롬프트 토큰의 한계와 비용이다. 특히 RAG 구조에서는 외부 검색 결과를 LLM 입력으로 넣을 때, 프롬프트가 지나치게 커질 수 있다.

이를 해결하기 위한 방법으로 LLMLingua가 소개된다. LLMLingua는 대규모 언어 모델이 처리할 프롬프트를 축약(compression)하는 도구로, 입력 문서에서 의미를 최대한 유지하면서도 토큰 수를 줄여준다.

책에서는 실제로 LLMLingua를 활용하여 동일한 정보를 담고 있지만 압축된 프롬프트를 LLM에 넣고, 성능 및 비용을 개선하는 방법을 코드로 보여준다.

AutoGen (Microsoft)

Microsoft가 개발한 AutoGen은 다중 에이전트 프레임워크의 대표적인 사례로, LangChain과는 다른 접근 방식을 제공한다.

AutoGen의 핵심은 에이전트가 사전에 정해진 프로세스를 따르는 것이 아니라, 대화를 통해 문제를 협의하고 해결할 수 있도록 설계된 점이다. 에이전트들은 스스로 토론하며 어떤 에이전트가 어떤 작업을 수행할지 결정하고, 순차적 또는 병렬적으로 문제를 해결한다.

책에서는 간단한 AutoGen 사용법과 함께, AutoGen이 어떻게 에이전트 간의 자연스러운 협업을 지원하는지를 설명하고, 이를 활용한 RAG + Multi-Agent 시스템의 예시도 소개한다.

CH10. 대규모 언어 모델과 인공지능이 주도하는 과거, 현재, 미래 트렌드 분석 & CH11. 세계적 전문가들이 바라본 산업의 현재와 미래

대규모 언어 모델의 발전을 논할 때 컴퓨팅 파워는 빠질 수 없는 이야기이다. 기존에는 무어의 법칙(2년마다 트랜지스터 수가 2배 증가)을 바탕으로 꾸준한 하드웨어 성능 향상을 기대했지만, 2020년대를 지나며 물리적 한계와 비용 문제로 의문이 제기되었다. 그럼에도 무어의 법칙은 여전히 산업계에서 중요한 기준점으로 작용하고 있다.

이와 동시에 Tensor Processing Unit(TPU), GPU의 발전, 그리고 딥러닝 특화 하드웨어의 등장으로 LLM 훈련과 추론 환경은 크게 개선되었다. 특히 TPU와 GPU 클러스터를 활용한 클라우드 컴퓨팅의 확산으로, 개인이나 중소기업도 대규모 언어 모델을 실험하고 서비스할 수 있는 환경이 마련되었다.

프롬프트 엔지니어링과 RAG의 재조명

프롬프트 엔지니어링은 LLM을 활용한 애플리케이션 개발의 첫 번째 단계로 자리 잡았다. 그 뒤를 이어 RAG (Retrieval-Augmented Generation)이 재조명되고 있는데, 이는 검색된 정보와 언어 모델을 결합하여 보다 정확하고 신뢰성 있는 결과를 제공하기 위함이다.

RAG의 성능은 단순히 모델의 크기나 파라미터 수에 의존하는 것이 아니라,

검색된 데이터의 구조 설계
Vector DBMS의 선택
임베딩 품질

등에 의해 크게 좌우된다.
여기서 임베딩은 텍스트 데이터를 벡터로 변환하는 과정으로, 손실 압축 메커니즘이기 때문에 어느 정도 정보 손실이 발생한다. 따라서, 효율적인 임베딩 설계가 RAG의 성능을 좌우한다.

LLM을 활용한 응용은 다음과 같은 복잡도 단계를 가진다.

프롬프트 엔지니어링
RAG
미세 조정(Fine-Tuning)
모델 재학습
사전학습(Pretraining)

각 단계로 갈수록 비용과 기술적 복잡성은 급격히 증가하지만, 그만큼 얻을 수 있는 커스터마이징의 폭도 커진다.

최근에는 이러한 워크플로우를 체계화한 LLMOps가 등장했다. LLMOps는 LLM의 개발, 배포, 모니터링, 버전 관리, 평가를 포함하는 LLM 기반 MLOps의 확장된 개념이다.

책의 마지막은 글로벌 기업의 AI 담당자들과의 인터뷰로 구성되어 있다. 그 중에서도 인상 깊었던 것은 이베이의 CAIO 니잔 메켈-보브로브 박사의 발언이었다.

니잔 박사는 앞으로의 트렌드로 대규모 기초 모델 (LFM, Large Foundation Model) 로의 전환을 강조했다. 이는 특정 용도에만 국한된 모델이 아니라, 다수의 태스크를 포괄할 수 있는 범용적인 모델의 필요성을 뜻한다. 실제로 OpenAI, Google, Meta 역시 모두 LFM 중심으로 연구를 이어가고 있으며, 다중 언어 지원, 복합적인 reasoning, 멀티모달 학습 등으로 확장되고 있다.

팔란티어 CTO는 K-LLMs 즉, 특정 도메인 또는 조직에 맞게 커스텀된 LLM들의 활용 가능성을 강조했다. 앞으로는 단일 대규모 모델보다는 다양한 크기의 특화된 LLM들을 유기적으로 조합하는 전략이 중요해질 것으로 보인다.

리눅스 - SIGTERM 과 SIGKILL ?!, 근데 Signal 을 곁들인 (ps. kill -9 만 쓰시나요?)

Sun, 23 Mar 2025 17:29:01 GMT

[ 글의 목적: 리눅스 OS 에서 process 를 kill (IPC 중 signal 방식) 할때 SIGTERM, SIGKILL 동작에 대한 기록 ]

SIGTERM과 SIGKILL에 대한 심층 분석

습관적으로 pkill -9 ... 을 때리다가 어떻게 OS 는 process를 "safe" 한 방식으로 죽일 수 있을까 부터 시작해 UNIX/Linux 의 Signal IPC 까지 올라가서 러프하게 정리한 글이다.

한 번 상상해보자. python 으로 작성한 a.py 에 while True 가 있어도, Ctrl + C 한 방이면 KeyboardInterrupt 발생하면서 stop 되고 결국 프로세스는 죽는다. 이 흐름을 정말 A to Z 까지 알고 있는가? 이게 왜 중요한가? 우린 OS 의 "프로세스" 와 "쓰레드" 의 생명주기와 IPC 는 기억하지만, 이 흐름은 놓치고 있는 경우가 많다. ~~(근데 나도 몰랐다.)~~

썸네일은 gpt 와 claude 의 콜라보다. 우측 하단의 "쾅" 이 클로드인데, 역시 튜닝의 끝은 순정인가,, 잼민이 감성..

Python 의 `KeyboardInterrupt` 이어서..

위에 얘기한 흐름을 다시 정리해보자면, 우리는 shell 에서 python 을 실행한다. python a.py 와 같이.
해당 a.py 는 python 이라는 S/W 를 기반으로 runtime 이 구성되고, python interpreter 가 실행되며 foreground 프로세스로 실행 한다.
이 상태에서 Ctrl + C를 누르면, 터미널은 이를 특수 제어 문자(ETX - End of Text, 0x03)로 인식한다. (이는 python 에서 인식하는게 아니라 OS 에서 인식한다!!)
터미널은 이 키 입력(0x03)을 감지하면 foreground에서 실행 중인 프로세스(예: Python)에 SIGINT 시그널을 보낸다. 이건 POSIX 표준이자 리눅스/유닉스/macOS에서 동일하게 작동하는 규칙 이다.
이때 Python 인터프리터는 자체 등록한 SIGINT 핸들러를 통해 KeyboardInterrupt 예외를 발생시킨다.
Python은 인터프리터(ex - CPython 구현체)가 시작될 때 signal 모듈을 통해 자체적으로 SIGINT 에 대한 핸들러를 기본으로 등록해 두고 있다.

이 예시외에도 nginx 같은 S/W level 의 web-server process 를 죽일때, gunicorn 이나 apache & tomcat 으로 돌아가는 spring server 를 죽일때도 비슷한 흐름이다.
이제부터 Signal 에 대해서 좀 더 자세하게 알아보자. 가장 먼저 종료 signal 의 대표적인 예시인 SIGTERM 과 SIGKILL 차이점은 아래와 같다.

SIGINT, SIGTERM, SIGKILL 비교표

셋 다 프로세스를 멈추는 신호(Signal)이며, SIGTERM, SIGKILL 은 "프로세스 종료" 에 더 가깝다. 여기서는 사실 SIGTERM, SIGKILL 에 대해 더 자세히 알아보고자 한다.

구분	SIGINT (2)	SIGTERM (15)	SIGKILL (9)
의미	사용자 중단 요청 (Interrupt)	정상 종료 요청 (Termination Request)	강제 종료 (Forced Kill)
발생 시점	주로 사용자가 Ctrl+C 입력	일반적으로 `kill` 명령 사용 시 기본값	`kill -9` 또는 시스템 강제 종료 시
기본 동작	프로세스에 인터럽트 요청 → 정상적인 종료 처리 실행	종료 핸들러 실행 기회 제공	즉시 강제 종료
프로세스 대응	무시 가능, 시그널 핸들러로 처리 가능	무시 가능, 시그널 핸들러로 처리 가능	무시 불가능 (non-maskable, non-catchable)
우선순위	사용자 개입 수준	일반 종료 시퀀스	최우선, 무조건 종료
리소스 정리	가능 (시그널 핸들러에서 정리 가능)	가능 (핸들러 내부에서 리소스 정리 수행 가능)	불가능 (리소스 누수 위험 있음)
커널 개입	커널이 시그널 전달 → 프로세스 핸들링	커널이 시그널 전달 → 프로세스 핸들링	커널이 직접 종료 (컨텍스트 무시하고 즉시 종료)
사용 예시	사용자가 `Ctrl+C` 입력	`kill PID` (기본값)	`kill -9 PID`
시스템 콜	`kill(pid, SIGINT)`	`kill(pid, SIGTERM)`	`kill(pid, SIGKILL)`
프로세스 상태 전이	Running → Signal Handling → (계속/종료)	Running/Waiting → Terminating → Zombie → Removed	Running/Waiting → Zombie → Removed
자식 프로세스 처리	일반적으로 전파되지 않음	애플리케이션 설정에 따라 자식에게도 전파 가능	자식 프로세스 포함 전체 강제 종료 (kill -9 트리 구조 시)
비동기성	처리 핸들링 가능 (시그널 핸들러 등록)	비동기적으로 처리 가능	즉시 처리됨, 핸들링 불가

SIGTERM 은 "정중한 종료 요청"으로, 프로세스에게 "작업을 마무리하고 종료해달라"는 의미이며, SIGKILL 은 "즉각적인 강제 종료 명령"으로 프로세스에게 어떤 기회도 주지 않고 즉시 종료시킨다.

1. 프로세스 간 통신(IPC)과 시그널

심플하게 IPC 와 종류, 특히 "시그널" 에 대해 살펴보자!
위키피디아 - Signal(IPC)
리눅스 man - signal(7) — Linux manual page

1) IPC의 개념과 종류

프로세스 간 통신(Inter-Process Communication, IPC)은 서로 다른 프로세스가 데이터를 교환하고 동기화하는 메커니즘이다. UNIX/Linux 시스템에서 IPC의 주요 방식은 다음과 같다.

파이프(Pipe)와 명명된 파이프(Named Pipe)
- 단방향 데이터 흐름을 제공
- 예: | 연산자를 사용한 파이프라인
메시지 큐(Message Queue)
- 비동기적 메시지 전달 시스템
- msgget(), msgsnd(), msgrcv() 시스템 콜 사용
공유 메모리(Shared Memory)
- 여러 프로세스가 동일한 메모리 영역에 접근
- 가장 빠른 IPC 방식
세마포어(Semaphore)
- 공유 자원에 대한 접근 제어
- 상호 배제(mutual exclusion)를 보장
소켓(Socket)
- 네트워크를 통한 프로세스 간 통신
- 로컬 및 원격 통신 모두 지원
시그널(Signal)
- 비동기적인 이벤트 알림
- 프로세스 제어 및 예외 상황 처리에 사용

2) 시그널의 특징과 역할

시그널은 UNIX/Linux 시스템에서 가장 오래된 IPC 메커니즘 중 하나로, 다음과 같은 특징이 있다.
- 비동기성: 프로세스가 어떤 작업을 하고 있든 상관없이 전달 가능
- 경량성: 시그널은 단순한 정수 값으로, 오버헤드가 적음
- 이벤트 드리븐: 특정 이벤트 발생 시 프로세스에 알림을 제공
- 제한된 정보: 시그널 번호 외에 추가 데이터를 전달하기 어려움

3) 주요 시그널 종류

신호 이름	번호	설명	기본 동작	원인
SIGHUP	1	행업(Hangup)	종료	제어 터미널이 종료될 때
SIGINT	2	인터럽트	종료	Ctrl+C 키 입력
SIGQUIT	3	종료 및 코어 덤프	코어 덤프와 함께 종료	Ctrl+\ 키 입력
SIGILL	4	잘못된 명령어	코어 덤프와 함께 종료	잘못된 CPU 명령 실행
SIGTRAP	5	트랩	코어 덤프와 함께 종료	디버깅용 트랩
SIGABRT	6	중단	코어 덤프와 함께 종료	abort() 함수 호출
SIGFPE	8	부동 소수점 예외	코어 덤프와 함께 종료	0으로 나누기 등 연산 오류
SIGKILL	9	강제 종료	종료 (무시 불가)	관리자 권한으로 강제 종료
SIGUSR1	10	사용자 정의 1	종료	사용자/애플리케이션 정의
SIGSEGV	11	세그멘테이션 오류	코어 덤프와 함께 종료	잘못된 메모리 참조
SIGUSR2	12	사용자 정의 2	종료	사용자/애플리케이션 정의
SIGPIPE	13	파이프 깨짐	종료	닫힌 파이프에 쓰기 시도
SIGALRM	14	알람	종료	alarm() 함수로 설정된 타이머 만료
SIGTERM	15	종료	종료	kill 명령의 기본값
SIGCHLD	17	자식 상태 변경	무시	자식 프로세스가 종료되거나 중지될 때
SIGCONT	18	계속 실행	중단된 프로세스 재개	중단된 프로세스를 계속 실행
SIGSTOP	19	중지	프로세스 중지 (무시 불가)	프로세스 중지
SIGTSTP	20	터미널 중지	프로세스 중지	Ctrl+Z 키 입력
SIGTTIN	21	터미널 입력	프로세스 중지	백그라운드 프로세스가 터미널에서 읽기 시도
SIGTTOU	22	터미널 출력	프로세스 중지	백그라운드 프로세스가 터미널에 쓰기 시도

SIGUSR1 로 재미있는 걸 해볼 수 있지 않을까?

2. OS 관점에서 `SIGTERM` 과 `SIGKILL` 의 차이

정확하겐 POSIX 표준에 정의된 시그널 관련 시스템 콜과 라이브러리 함수를 해당 레포에서 직접 확인할 수 있다. - https://github.com/torvalds/linux?tab=readme-ov-file

1) SIGTERM (15) - 정상적인 종료 요청

시그널 전송 과정
- 사용자가 kill PID를 실행하면, 커널의 kill() 시스템 콜이 호출된다.
- 시스템 콜 인터페이스를 통해 커널 공간으로 전환된다.
- 커널은 프로세스 테이블에서 PID에 해당하는 프로세스를 찾는다.
시그널 전달 및 큐잉
- 커널은 해당 프로세스의 task_struct 내의 시그널 마스크와 핸들러 정보를 확인한다.
- SIGTERM 시그널이 해당 프로세스의 시그널 큐(sigqueue)에 추가된다.
- 프로세스의 시그널 큐는 보류 중인 시그널(pending signals)을 관리한다.
컨텍스트 스위칭과 시그널 처리
- 다음 스케줄링 시점에 프로세스가 CPU를 획득하면, 커널은 해당 프로세스의 시그널 큐를 검사한다.
- SIGTERM 이 발견되면, 커널은 다음을 확인한다:
  - 시그널이 블록되었는지 (프로세스가 sigprocmask()로 블록했는지)
  - 사용자 정의 핸들러가 등록되었는지 (sigaction()으로 설정)
핸들러 실행
- 만약 SIGTERM 핸들러가 등록되어 있다면
  - 커널은 사용자 공간의 스택에 시그널 프레임을 추가한다.
  - 프로세스의 실행 컨텍스트를 시그널 핸들러로 변경한다.
  - 프로세스는 핸들러 내에서 정리 작업을 수행한다:
    - 열린 파일 디스크립터 닫기 (close())
    - 데이터베이스 커넥션 종료
    - 임시 파일 삭제
    - 로그 파일에 종료 메시지 기록
    - 자식 프로세스에게 종료 시그널 전파
- 시그널 핸들러가 완료된 후, 프로세스는 인터럽트되었던 지점(또는 시그널 핸들러 반환 후의 지점)으로 돌아간다!
프로세스 종료
- 핸들러 실행 후, 애플리케이션은 일반적으로 exit() 시스템 콜을 호출하여 정상 종료한다.
- 만약 핸들러가 없거나 시그널이 무시되지 않았다면, 기본 동작(default action)인 종료가 수행된다.
- 프로세스 종료 시 다음 과정이 진행된다:
  - 모든 스레드 종료
  - 프로세스 리소스 정리 (메모리, 파일 핸들 등)
  - 부모 프로세스에 SIGCHLD 시그널 전송
  - 프로세스 상태가 좀비(zombie) 상태로 전환
좀비 프로세스 정리
- 부모 프로세스가 wait() 또는 waitpid()를 호출하면, 자식의 종료 상태를 회수하고 프로세스 테이블 엔트리가 완전히 제거된다.
- 만약 부모가 wait()를 호출하지 않으면, 좀비 프로세스가 남게 된다.

2) SIGKILL (9) - 강제 종료

시그널 전송 과정:
- 사용자가 kill -9 PID를 실행하면, 역시 kill() 시스템 콜이 호출된다.
- 커널 공간으로 전환되어 프로세스 테이블을 검색한다.
특수 처리
- SIGKILL 은 특별한 시그널로 커널은 이를 프로세스의 시그널 큐에 넣지 않는다.
- 대신, 즉시 프로세스 종료 절차를 시작한다! 프로세스의 시그널 마스크나 핸들러 설정을 확인하지 않는다! (무시할 수 없는 시그널)
강제 종료 프로세스:
- 커널은 프로세스의 모든 스레드에 대해 즉시 실행을 중단시킨다.
- do_exit() 커널 함수가 호출되어 프로세스 종료 절차를 진행한다:
  - 프로세스의 가상 메모리 공간을 해제한다.
  - 열린 파일 디스크립터를 강제로 닫는다.
  - 시스템 V IPC 리소스를 해제한다.
  - 프로세스가 소유한 세마포어를 해제한다.
  - 프로세스 상태를 EXIT_ZOMBIE 로 변경한다.
  - 부모 프로세스에 SIGCHLD 시그널을 보낸다.
사용자 공간 코드 실행 없음
- SIGKILL 은 프로세스의 사용자 공간 코드가 실행될 기회를 전혀 주지 않는다.
- 이는 애플리케이션이 자신의 리소스를 정리할 수 없음을 의미한다.
- 커널만이 프로세스의 커널 리소스(파일 핸들, 메모리 등)를 정리한다.
- PS) 그러니까 SIGTERM call 이 더 안전한 종료 접근법이다!!
좀비 프로세스와 후속 처리:
- SIGTERM 과 마찬가지로, 프로세스는 부모가 wait()를 호출할 때까지 좀비 상태로 남는다.
- 부모 프로세스가 이미 종료된 경우, init 프로세스(PID 1)가 고아 프로세스를 자식으로 대려와 좀비를 정리한다.

3) 두 시그널의 핵심 차이점

실행 컨텍스트
- SIGTERM: 프로세스의 사용자 공간 코드(시그널 핸들러)가 실행된다.
- SIGKILL: 전적으로 커널 공간에서 처리되며, 사용자 코드는 실행되지 않는다.
리소스 정리
- SIGTERM: 애플리케이션이 자신의 리소스(임시 파일, 네트워크 연결, 데이터베이스 트랜잭션 등)를 정리할 수 있다.
- SIGKILL: 애플리케이션 수준의 리소스 정리가 불가능하며, 커널 수준의 리소스만 정리된다.
실행 시간
- SIGTERM: 핸들러 실행과 정리 과정으로 인해 종료에 시간이 걸릴 수 있다.
- SIGKILL: 즉시 종료되어 지연이 최소화된다.
안전성
- SIGTERM: 정상적인 종료 절차를 통해 데이터 무결성을 보장할 가능성이 높다.
- SIGKILL: 데이터 손실이나 불일치, 네트워크 연결 문제 등을 야기할 수 있다.

사실 이 때문에 두 시그널을 두고 다양한 밈들이 있다.

4) 우아한 종료(Graceful Shutdown)의 중요성

데이터 무결성 보장
- 불완전한 작업이 없도록 보장
- 트랜잭션 완료 또는 롤백
- 디스크 버퍼 플러시
클라이언트 영향 최소화
- 기존 연결의 적절한 종료
- 오류 메시지 대신 정상 응답 제공
- 세션 데이터 보존
분산 시스템 일관성
- 클러스터 노드 간 상태 동기화
- 리더 선출 또는 장애 조치 트리거
- 로드 밸런서에서 노드 제거

그러니 우리가 만약 응용 프로그램을 직접 만들게 된다면, 이 "Graceful Shutdown" 을 위한 SIGTERM 핸들러를 직접 추가해서 처리하는 방향으로 접근해보자!

5) 종료 시간 제한(Timeout)의 설정

대부분의 시스템에서는 우아한 종료에 시간 제한을 두는 것이 중요하다.

Kubernetes의 종료 프로세스
- Pod가 SIGTERM 을 받은 후 terminationGracePeriodSeconds 동안 기다린다 (기본 30초).
- 시간이 초과되면 SIGKILL 을 보내 강제 종료한다.
Systemd의 종료 프로세스
- TimeoutStopSec 설정으로 종료 타임아웃을 지정 (기본 90초).
- 타임아웃 후 SIGKILL 을 보낸다.
Docker의 종료 프로세스
- docker stop 명령은 컨테이너에 SIGTERM을 보낸다.
- 기본적으로 10초 후 SIGKILL 을 보낸다.
- docker stop --time= 옵션으로 타임아웃 조정 가능.
적절한 타임아웃 설정 전략
- 애플리케이션의 일반적인 정리 시간을 측정
- 최악의 경우 시나리오(많은 연결, 큰 트랜잭션 등) 고려
- 마진을 추가하되, 너무 길지 않게 설정
- 배포 중단 시 전체 시스템 영향 고려

그러니 이제 SIGTERM 을 위해 kill PID 을 기본으로 사용하되, 경우에 따라 kill -9 PID 를 사용하는게 어떨까? ~~to. 스스로에게...~~

4. shell script로 실습!

1) SIGTERM을 먼저 사용하기

효과적인 프로세스 종료를 위한 최선의 방법!

단계적 접근

# 1. 먼저 SIGTERM으로 정상 종료 시도
kill 

# 2. 일정 시간 대기 (5-10초)
sleep 10

# 3. 프로세스가 여전히 실행 중인지 확인
if ps -p  > /dev/null; then
    echo "Process still running, sending SIGKILL..."
    kill -9 
else
    echo "Process terminated gracefully."
fi

스크립트 자동화

#!/bin/bash

terminate_with_timeout() {
    local pid=$1
    local timeout=${2:-30}  # 기본 30초 타임아웃

    # 프로세스가 존재하는지 확인
    if ! ps -p $pid > /dev/null; then
    echo "Process $pid does not exist."
    return 0
    fi

    # SIGTERM 전송
    echo "Sending SIGTERM to process $pid..."
    kill $pid

    # 타임아웃 내에 종료되는지 확인
    local count=0
    while ps -p $pid > /dev/null && [ $count -lt $timeout ]; do
    sleep 1
    count=$((count + 1))
    echo "Waiting for process to terminate: $count/$timeout seconds"
    done

    # 여전히 실행 중이면 SIGKILL 전송
    if ps -p $pid > /dev/null; then
    echo "Process still running after $timeout seconds, sending SIGKILL..."
    kill -9 $pid
    return 1
    else
    echo "Process terminated gracefully."
    return 0
    fi
}

# 사용 예: terminate_with_timeout  [timeout_in_seconds]

2) 그러니, 다시 정리하는 SIGKILL을 남용하지 말아야 하는 이유!

여러분들의 응용프로그램에게 SIGKILL 의 남용이 초래할 수 있는 문제들!

데이터 일관성 문제
- 데이터베이스 트랜잭션 중단으로 인한 데이터 불일치
- 파일 쓰기 작업 중 강제 종료로 인한 파일 손상
- 캐시와 영구 저장소 간의 불일치 발생
리소스 누수
- 임시 파일이 제거되지 않음
- 공유 메모리 세그먼트가 정리되지 않음
- 네트워크 포트가 적절히 해제되지 않음
- 외부 리소스 락(lock)이 해제되지 않음
분산 시스템 문제
- 클러스터에 종료 통지가 전송되지 않음
- 리더 선출 프로세스가 비정상적으로 트리거됨
- 다른 노드와의 통신이 정상적으로 종료되지 않음
실제 사례 분석
- 데이터베이스 서버의 SIGKILL 종료는 WAL(Write-Ahead Log) 손상을 초래할 수 있음
- 메시지 큐의 SIGKILL 종료는 메시지 중복 처리나 유실을 초래할 수 있음
- 분산 락 관리자의 SIGKILL 종료는 "뇌 분할(split-brain)" 현상을 초래할 수 있음

3) 복잡한 애플리케이션의 종료 전략

다중 노드 등의 복잡한 형태, 조금 더 큰 규모의 시스템에서의 안전한 종료 전략은 자식 부터 부모로 올라오거나 치명적인 것에서 덜 치명적인 순서로 접근하는게 필요하다!

다중 계층 애플리케이션
- 종료 순서가 중요함: 클라이언트 계층 → 애플리케이션 계층 → 데이터 계층
- 각 계층은 다른 종료 유예 시간이 필요할 수 있음
리더-팔로워 시스템
- 팔로워 노드 먼저 종료
- 리더 노드는 새로운 리더 선출 후 종료
- 리더 변경 사항이 모든 노드에 전파된 후 완전 종료
장기 실행 작업이 있는 시스템
- 진행 중인 작업의 체크포인트 생성
- 작업 큐의 적절한 상태 저장
- 재시작 시 중단된 지점부터 계속할 수 있는 메커니즘 구현
데이터베이스 종료
- 트랜잭션 커밋 또는 롤백
- 버퍼된 데이터 디스크에 쓰기
- 체크포인트 생성
- 메타데이터 업데이트

출처

1) 리눅스 시그널 관련 문서

리눅스 매뉴얼 페이지
- man 7 signal
- man 2 kill
- man 2 sigaction
- man 3 signal
리눅스 커널 소스 코드
- kernel/signal.c
- include/linux/signal.h
위키피디아 - Signal(IPC)
리눅스 man - signal(7) — Linux manual page
리눅스 핸드북 sigterm vs sigkill

2) 관련 표준 및 사양

POSIX.1-2017 시그널 사양 - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
시그널 안전 함수 목록 - https://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html#tag_15_04_03

nuung

LLM - 모델 경쟁이 끝나고, “하네스 경쟁”의 시작?!, opencode 와 oh-my-opencode

모델 경쟁이 끝나고, “하네스 경쟁”의 시작?!

하네스?!

1. Opencode ?!

1) 정의 및 배경

2) 작동 원리

사실 권한 제어와 LSP control 이 핵심인 듯 한?!

3) 플러그인 시스템: 하네스가 붙는 자리

4) 설치 & 세팅

2. OMO: Oh-my-opencode ?!

1) 정의 및 배경

2) Oh-My-OpenCode의 “각 모드”는 무엇이며, 언제 쓰는가

다수 에이전트를 “AI 팀”으로 제공

3) ultrawork, search, analyze ?!

*ultrawork/ulw = 최대 성능 모드*

search/find = 병렬 탐색 모드

analyze/investigate = 심층 분석 모드

think mode

4) 설치 & 세팅

3. 실제 사용 예시

일단 하나의 예시를 보면,,

1) 일단 플젝 세팅 부터 제대로

1. 무엇을 만들어야 하는지 결정된다면 stack 부터 정합니다.

2. AGENTS.md (CLAUDE.md 등 포함) 부터 출발합니다.

3. SYSTEM_DESIGN.md 를 만듭니다.

4. pre-commit, ruff(eslint & prettier), test(pytest, jest) 세팅을 바로 합니다.

5. github action CI 부터 역시 바로 세팅합니다.

2) 그리고 작업 시작, plan.md 부터!

plan.md 를 작성했으면 이제 이를 기반으로 작업을 합니다!

plan 규모가 좀 있다면 무조건 검토를 시킵니다.

3) 다음 턴 부터는 상황에 따라

4) 절대 AGENTS.md, SYSTEM_DESIGN.md 등을 그대로 두지 않습니다.

최대한 영어로, 최대한 핵심만 짧고 요약해서

5) 한 세션이 너무 길어진다면?

6) 정리

PS...

출처

[책 리뷰] 우리, 프로그래머들 - 로버트 C. 마틴

우리, 프로그래머들

리뷰

목차별 리뷰

1부. 서막을 열며

1장. 우리는 누구인가?

2부. 거장

2장. 배비지, 최초의 컴퓨터 엔지니어

3장. 힐베르트, 튜링, 그리고 폰 노이만: 최초의 컴퓨터 아키텍트

4장. 그레이스 호퍼: 최초의 소프트웨어 엔지니어

5장. 존 배커스: 첫 번째 고수준 언어

6장. 에츠허르 다익스트라: 첫 번째 컴퓨터 과학자

7장. 니가드와 달: 첫 번째 OOPL && 8장. 존 케메니: 모두를 위한 첫 번째 언어, BASIC

9장. 주디스 앨런 && 10장. 톰프슨, 리치, 커니핸

3부. 급격한 전환점

11장. 1960년대

12장. 1970년대

13장. 1980년대

14장. 1990년대

15장. 밀레니엄

4부. 미래

16장. 프로그래밍 언어

17장. AI

18장. 하드웨어 && 19장. 월드 와이드 웹 && 20장. 프로그래밍

velog dashboard v2 - MAU 1k+, 아직도 통계를 안보셨나요?!

Velog Dashboard v2

1. 직접 통계 새로고침 (딸각)

핵심 흐름

무한 새로고침 방지 (중복 호출 방지)

Consumer 가 배보다 배꼽이 커진 이유...!

2. 완벽한 "마크다운 통계 뱃지" TBD

어떤 형태로 제공하냐면

뱃지 처리 user flow

3. 토큰 공격 방어 (Fail-fast JWT + Redis 기반 인증 실패 추적/차단)

문제: 쓰레기 토큰 대량 유입 → 연결 풀 고갈

물리적인 시큐어코딩 업데이트

1. JWT 형식 검증 유틸 추가

2. Payload 추출을 안전하게 (safeExtractPayload)

3. Error handling 개선

토큰 밸리데이션 & 정상 처리 플로우

Fail-fast + Redis block 플로우

VD2 는 누구나 PR 올릴 수 있게 열려있습니다!

ultrawork/ulw = 최대 성능 모드

1. 무엇을 만들어야 하는지 결정된다면 `stack` 부터 정합니다.

2. `AGENTS.md` (CLAUDE.md 등 포함) 부터 출발합니다.

3. `SYSTEM_DESIGN.md` 를 만듭니다.

4. `pre-commit`, `ruff(eslint & prettier)`, `test(pytest, jest)` 세팅을 바로 합니다.

`absolute_import` 왜 씀?