튜토리얼
64개의 포스트
Pydantic 기초 — 데이터의 모양을 선언하고 검증하기 (FastAPI 입문 4편)
FastAPI 코드의 절반은 Pydantic이다. 이 편은 FastAPI를 잠시 내려놓고 Pydantic만 떼어 파이썬 코드로 익힌다. 모델을 만들고, 틀린 값에서 나오는 ValidationError를 읽고, 필수·선택·null의 네 가지 조합, 기본(lax) 모드의 타입 변환 규칙과 strict 모드, Field 제약, 중첩 모델, field_validator·model_validator, model_dump·model_validate, camelCase 별칭까지 — 전부 실제 실행 결과로 보여 준다. 필드 타입별로 값이 어떻게 바뀌는지 lax와 strict를 나란히 비교하는 위젯을 포함한다.
에이전트 여럿, 저장소 하나 3편 — 에이전트에 worktree 맡기기: Claude Code·Codex·Worktrunk
2편에서 손으로 만들던 worktree를 이제 도구에게 맡깁니다. Claude Code의 --worktree·.worktreeinclude·worktree.baseRef·격리 강제·정리 규칙·서브에이전트 isolation, Codex 앱과 CLI가 worktree를 다루는 방식의 차이, 그리고 Worktrunk(wt)로 만들기부터 병합·정리까지 한 바퀴를 실제 출력으로 따라갑니다.
에이전트 여럿, 저장소 하나 4편 — Mac을 바꿔 가며 이어서 작업하기
맥북에서 하던 일을 맥 스튜디오에서 이어 가는 방법을 Git만으로 정리합니다. 퇴근 전 WIP 커밋과 push, 출근 후 fetch와 switch, stash가 다른 Mac으로 건너가지 못하는 이유, 두 Mac이 같은 브랜치를 만졌을 때의 pull --rebase와 --force-with-lease, 다른 Mac에 두고 온 커밋 찾기, 그리고 Mac마다 한 번씩 해 둘 인증·includeIf 설정까지 git 2.55 실제 출력으로 따라갑니다.
왜 파이썬이고, 왜 FastAPI인가 — 다른 언어·프레임워크와 비교해 보기 (FastAPI 입문 1편)
API가 무엇인지부터 시작해, 왜 많은 팀이 백엔드 언어로 파이썬을 고르고 그중에서도 FastAPI를 고르는지 Django·Flask·Express·Spring Boot·Go와 나란히 놓고 비교한다. 같은 API를 여섯 프레임워크로 짠 코드를 위젯으로 직접 비교해 보고, FastAPI를 고르지 말아야 할 때, 그리고 어떤 파이썬 버전(3.10~3.15)으로 돌려야 하는지 직접 돌려 본 결과와 함께 정리한다. 일곱 편짜리 FastAPI 입문 시리즈의 첫 편이다.
첫 FastAPI 앱과 라우팅 — 주소를 함수로 잇는 법 (FastAPI 입문 2편)
설치부터 fastapi dev로 첫 서버를 띄우기까지, 그리고 FastAPI의 가장 기본인 라우팅 — @app.get 데코레이터, 경로 매개변수, 쿼리 매개변수, 타입 힌트로 자동 검증되는 422 에러, 라우트 순서 함정, 405와 307 — 을 실제 실행 결과와 함께 설명한다. 주소를 입력하면 어느 함수로 가는지 보여 주는 라우트 매칭기 위젯으로 직접 확인해 볼 수 있다.
에이전트 여럿, 저장소 하나 1편 — 폴더를 동기화하지 말고 Git으로 주고받기
Claude Code와 Codex를 동시에 여러 개 돌리고, 맥북과 사무실 Mac을 오가며 같은 프로젝트를 만지기 시작하면 가장 먼저 떠오르는 방법이 '저장소 폴더를 동기화하자'입니다. 이 글은 그 방법이 왜 조용히 작업을 잃게 만드는지 직접 재현한 실험으로 보여 주고, 원격 하나 → Mac마다 clone → 작업마다 worktree로 이어지는 전체 설계도와 세 원칙, 그리고 소스·비밀·대용량 파일·빌드 산출물을 각각 어디에 둘지 정리합니다.
에이전트 여럿, 저장소 하나 2편 — git worktree 완전 정복
저장소 하나에서 작업 폴더를 여러 개 꺼내 쓰는 git worktree를 처음부터 끝까지 다룹니다. add·list·remove·prune·lock·move를 git 2.55 실제 출력으로 따라가고, 커밋·브랜치·stash·설정은 공유되지만 파일·스테이징·HEAD는 폴더마다 따로라는 사실을 명령으로 하나씩 증명합니다. 같은 브랜치를 두 곳에서 꺼낼 수 없는 이유, worktree마다 node_modules·포트·.env를 따로 챙겨야 하는 함정, switch·stash·clone과의 비교까지 정리합니다.
쿠버네티스 첫걸음 1편 — 클러스터·노드·파드, 그림 한 장으로 끝내는 개념 잡기
쿠버네티스가 어려운 이유는 기능이 많아서가 아니라, 처음 보는 단어가 한꺼번에 쏟아지기 때문입니다. 클러스터·노드·컨트롤 플레인·파드 — 이 네 단어로 구조를 먼저 잡고, 디플로이먼트·서비스·네임스페이스를 얹습니다. 도커와 무엇이 같고 무엇이 다른지, '명령'이 아니라 '원하는 상태'를 적는다는 게 무슨 뜻인지, 그리고 우리 팀에 쿠버네티스가 정말 필요한지 판단하는 기준까지 정리합니다. 파드를 죽이고 노드를 꺼 보며 자가 치유를 눈으로 확인하는 시뮬레이터가 들어 있는 6편 시리즈의 첫 글입니다.
쿠버네티스 첫걸음 2편 — 맥·윈도우에 라이선스 걱정 없이 로컬 클러스터 만들기: Rancher Desktop·OrbStack·Docker Desktop·kind·minikube·k3d 비교
쿠버네티스 자체는 Apache 2.0 오픈소스라 누구나 무료입니다. 라이선스가 걸리는 것은 그걸 노트북에 띄워 주는 데스크톱 앱 쪽뿐입니다. 로컬 클러스터 도구 여섯 가지(Rancher Desktop·OrbStack·Docker Desktop·kind·minikube·k3d)를 라이선스·가벼움·노드 개수·로컬 이미지 사용법으로 비교하고, 조건을 고르면 추천 도구가 나오는 위젯을 제공합니다. kubectl 설치부터 맥·윈도우 각각 클러스터를 만들고 kubectl get nodes로 확인하기까지 복사해서 쓰는 명령으로 안내하며, kubeconfig와 context가 무엇인지, 여러 클러스터를 오갈 때 무엇을 조심할지도 정리합니다. 여러 도구 속에 숨어 있는 k3s를 따로 떼어, 무엇이 기본 포함인지와 k3d·RKE2와의 차이, 리눅스 서버에 명령 한 줄로 팀 공용 클러스터를 만들고 워커를 붙이고 Traefik으로 도메인을 여는 법까지 실습합니다.
쿠버네티스 첫걸음 3편 — kubectl로 파드와 노드 다루기: get·describe·logs·exec, 그리고 파드가 안 뜰 때 읽는 법
kubectl 명령은 '동사 + 리소스 종류 + 이름 + 옵션' 한 가지 문법으로 되어 있습니다. 이 문법 하나로 노드를 살펴보고(get nodes, describe node), 파드를 띄우고(run, apply), 들여다보고(get -o wide, describe, logs, exec), 내 컴퓨터에서 접속하고(port-forward), 지우는(delete) 과정을 실습합니다. 파드 안에 컨테이너가 여럿 들어가는 경우가 무엇인지, 파드 YAML을 한 줄씩 읽는 법, 직접 만든 파드가 왜 되살아나지 않는지도 확인합니다. STATUS를 고르면 원인과 확인 명령이 나오는 파드 진단기와 kubectl 치트시트를 담았습니다.
쿠버네티스 첫걸음 4편 — 디플로이먼트와 서비스로 내 앱 배포하기: 늘리고, 바꾸고, 되돌리기
도커 첫걸음 시리즈에서 만든 hello-api 이미지를 쿠버네티스에 올립니다. 로컬 클러스터 도구별로 내가 빌드한 이미지를 클러스터에 넣는 법, 디플로이먼트 YAML을 한 줄씩 읽는 법, 파드를 죽여도 되살아나는 것 확인하기, replicas로 개수 늘리기, 새 버전을 무중단으로 교체하는 롤링 업데이트와 한 줄 롤백을 실습합니다. 이어서 서비스가 라벨로 파드를 찾는 원리를 셀렉터 실험실 위젯으로 확인하고, ClusterIP·NodePort·LoadBalancer의 차이, ConfigMap·Secret으로 설정 분리, readinessProbe로 준비된 파드에만 트래픽 보내기까지 다룹니다.
쿠버네티스 첫걸음 5편 — kubectl·k9s·Headlamp·Freelens·Lens: 쿠버네티스 관리 도구, 왜 쓰고 무엇을 고를까
쿠버네티스를 다루는 도구는 결국 모두 같은 API를 부릅니다. 그런데도 왜 kubectl을 먼저 익혀야 하는지, 그 위에 k9s(터미널 UI)·Headlamp(공식 GUI)·Freelens(무료 데스크톱)·Lens(상용)가 각각 무엇을 더해 주는지 비교합니다. 2026년 1월 은퇴한 Kubernetes Dashboard의 후속으로 Headlamp가 공식 추천된 배경, Lens의 라이선스 조건과 무료 포크 Freelens, 컨텍스트 전환(kubectx·kubens)·여러 파드 로그(stern)·프롬프트 안전장치(kube-ps1)·패키지 설치(Helm) 같은 보조 도구까지 설치 명령과 함께 정리했습니다. 같은 작업을 도구별로 어떻게 하는지 비교하는 위젯이 들어 있습니다.