PIElog — MANAPIE의 글과 실험

// featured post_

브라우저에서는 되는데요 - 웹뷰는 브라우저가 아니다 ep.00
  • series
  • cover
  • develop
  • frontend
  • webview
  • wkwebview
  • androidwebview
  • hybridapp

브라우저에서는 되는데요 - 웹뷰는 브라우저가 아니다 ep.00

웹뷰는 브라우저에서 주소창만 뗀 것이 아닙니다. 브라우저가 기본으로 켜두던 수십 가지 동작이 웹뷰에서는 앱이 명시적으로 켜야 하는 옵션이고, 그 기본값은 대체로 꺼짐입니다. 이 관점을 세우면 "안 되는 것"의 대부분이 "아직 켜지 않은 것"으로 다시 보이고, 웹이 고칠 문제와 앱에 요청할 문제를 처음부터 가를 수 있습니다.

read →

// experiences · 10_

  • experience
  • develop
  • backend
  • infra
  • devops
  • ai
  • fastapi
  • docker
  • yt-dlp
  • gemini

Chronosaurus를 검색하면 부작용이 나온다 - PIEmuvi 구축기

애플 뮤직·스포티파이·유튜브 뮤직 재생목록을 유튜브 재생 링크로 바꾸는 PIEmuvi를 FastAPI 단일 컨테이너로 만든 기록입니다. 스코어링만으로는 잡히지 않던 오답 세 가지를 채택 자격이라는 별도 축으로 해결한 과정과, 배포에서 세 번 헛짚고 원인을 찾은 진단 기록을 함께 정리합니다.

read →
  • experience
  • develop
  • ai
  • infra
  • devops
  • comfyui
  • cloudrun
  • gcp
  • gpu

서버리스 GPU 위의 AI 이미지 생성기는 왜 로컬보다 느렸을까 - PIEmgmaker 구축기

로컬 Mac mini M4에서 잡 1건에 96분이 걸리던 AI 이미지 생성기를 GCP Cloud Run GPU로 옮겼습니다. 첫 원격 잡은 59분 26초, $1.69였습니다. 원인은 처리량이 아니라 로컬 SSD를 가정한 기본값이었고, 세 가지 처방으로 8분 25초 · $0.24가 됐습니다. 알파 채널 확보 전략부터 메모리 경계, AWS·GCP 선택, 모델 80GB 이전, 유휴 과금까지 2주간의 결정과 함정을 정리합니다.

read →
  • experience
  • develop
  • devops
  • ai
  • claude-code
  • shell
  • jq
  • cli

VSCode에서 돌리는 Claude Code 세션은 왜 안 잡힐까 - ccwhere 구축기

병렬로 띄운 Claude Code 세션을 한눈에 보는 도구를 찾다 기존 도구들이 VSCode 확장의 세션을 못 잡는 이유를 추적했습니다. 해법은 프로세스 추적이 아니라 세션 로그 파일을 직접 읽는 것이었습니다. jq의 16진수 미지원, command substitution 안에서 죽는 tput, 셸 변수 확장이 삼킨 jq 변수까지, 작은 셸 스크립트 하나에 박힌 함정들을 정리합니다.

read →
  • experience
  • develop
  • backend
  • frontend
  • socketio
  • nextauth
  • nextjs
  • debugging

두 라이브러리의 req는 같은 req가 아니었다

채팅 기능을 구현하던 날 socket 레이어의 게이팅을 비워둔 익숙한 손버릇이, 보안 마이그레이션 시점에 정확히 같은 자리에서 청구서로 돌아왔습니다. NextAuth의 SessionStore가 req.cookies만 보고 req.headers.cookie 헤더 자체는 무시한다는 사실을 추적하기까지의 디버깅과, 끝내 root cause를 단정하지 못한 채 in-flight 가드로 봉합한 버그까지의 회고입니다.

read →
  • experience
  • design
  • develop
  • frontend
  • a11y
  • chart
  • react
  • d3
  • interactive

인터랙션과 접근성을 모두 고려한 차트 만들기

44개 차트 데모를 한 자리에 모았습니다. 시각 사용자·키보드 사용자·스크린리더 사용자가 모두 자연스럽도록 처음부터 설계했고, 그 과정에서 정착된 패턴들을 함께 정리했습니다. 그 패턴은 HTML overlay, roving tabindex, 호버와 키보드 포커스의 분리, 데이터 표 fallback입니다.

read →
  • experience
  • develop
  • frontend
  • backend
  • testing
  • jest
  • react
  • nextjs

테스트가 없던 두 레포에 단위·컴포넌트·통합 테스트를 들이며

사람 눈검토만으로 운영 VM에 배포되던 두 레포에 jest를 깔았습니다. 어드민에서 검증한 패턴을 서비스로 옮기는 미러링 전략으로 네 단계를 차례로 진행했고, 그 사이에 만난 함정과 결정 패턴을 정리합니다.

read →
  • experience
  • develop
  • frontend
  • security
  • swiper
  • dependency
  • prototypepollution

같은 critical, 두 앱의 다른 선택

스와이퍼의 두 번째 prototype pollution은 5년 전 패치가 우회된 사례입니다. 같은 CVE를 공유하는 두 앱 중 하나는 제거를, 다른 하나는 메이저 업그레이드를 택했습니다. 의존성의 실효 위험은 advisory가 아니라 코드가 결정합니다.

read →
  • experience
  • develop
  • frontend
  • react
  • nextjs
  • security
  • cve
  • rsc

React/Next.js CVE 6개월 정리

React 19와 Next.js의 6개월 동안 발견된 CVE들을 한 편에 정리합니다. 각 CVE의 문제, 재현 방식, 패치, 그리고 당장 올릴 수 없을 때의 대처법을 코드 예시와 함께 다룹니다.

read →
  • experience
  • develop
  • infra
  • devops
  • gce
  • centos
  • selinux
  • pm2
  • systemd

한 달간 1분 30초마다 죽고 있었던 서버

Next.js 서비스에서 시간을 두고 접속하면 가끔 503이 떨어지던 문제를 추적했습니다. 처음에는 MongoDB 유휴 커넥션을 의심해 옵션을 다듬었고, 다음으로 OOM을 의심했지만 둘 다 원인이 아니었습니다. 진짜 원인은 PM2 데몬 자체가 systemd에 의해 통째로 강제 종료되고 있다는 사실이었고, 그 뿌리에는 SELinux의 사용자 홈 파일 접근 차단이 있었습니다.

read →
Astro + Vercel로 구축하는 개인 기술 블로그 세팅 후기
  • experience
  • develop
  • frontend
  • astro
  • vercel
  • blog
  • ssg

Astro + Vercel로 구축하는 개인 기술 블로그 세팅 후기

플랫폼에 종속되지 않고, 내 도메인에서 글을 온전히 소유할 수 있는 기술 블로그를 구축하려 합니다. 주로 기술이나 디자인에 관한 실무적·교육적 콘텐츠를 다룰 예정이며, 코드 블록과 인터랙티브 데모를 자유롭게 삽입할 수 있는 환경이 필요합니다. 이 글에서는 기술 스택을 선정하기까지의 과정과, 최종 선택한 Astro + Vercel 조합의 구체적인 구현 방법을 정리합니다.

read →

// knowledge · 95_

앱 개발자에게 무엇을 요청할 것인가 - 웹뷰는 브라우저가 아니다 ep.09
  • series
  • develop
  • frontend
  • webview
  • wkwebview
  • androidwebview
  • hybridapp
  • checklist

앱 개발자에게 무엇을 요청할 것인가 - 웹뷰는 브라우저가 아니다 ep.09

웹뷰 이슈의 담당을 가르는 기준은 증상이 아니라 "무엇을 바꾸면 동작이 바뀌는가"입니다. 이 편은 시리즈 전체의 증상을 여섯 계통으로 묶어 원인과 담당을 매핑하고, 그 판정을 이슈 양식과 설정 체크리스트로 옮깁니다. 패스키·플랫폼 결제·공동인증서처럼 웹 코드로 우회할 수 없는 항목도 같은 표 안에서 담당을 가릅니다.

read →
어제 배포했는데 앱에서는 그제 화면입니다 - 웹뷰는 브라우저가 아니다 ep.08
  • series
  • develop
  • frontend
  • webview
  • wkwebview
  • androidwebview
  • hybridapp
  • cache
  • bfcache

어제 배포했는데 앱에서는 그제 화면입니다 - 웹뷰는 브라우저가 아니다 ep.08

캐시 모드는 앱 설정에 종속되고, 렌더러 프로세스는 시스템이 회수하며, 백그라운드에서는 타이머가 흐르지 않습니다. 웹 개발자가 통제할 수 있는 층이 어디까지인지 문서로 확인한 뒤, 폼 초안 복원과 만료 시각 기반 카운트다운, 배포 반영을 위한 캐시 무효화 전략까지 웹 쪽에서 할 수 있는 것으로 착지합니다.

read →
로그인이 풀립니다 - 웹뷰는 브라우저가 아니다 ep.07
  • series
  • develop
  • frontend
  • webview
  • wkwebview
  • androidwebview
  • cookie
  • origin
  • cors
  • securecontext

로그인이 풀립니다 - 웹뷰는 브라우저가 아니다 ep.07

웹뷰의 저장소는 브라우저가 아니라 앱이 소유합니다. 그리고 로컬 번들을 file 스킴으로 로드하는 순간 오리진 판정이 무너지면서 Web Storage, 교차 출처 요청, 보안 컨텍스트가 한꺼번에 따라 무너집니다. 세 층을 분리해서 보면 "로그인이 풀립니다"라는 한 문장 뒤에 서로 다른 원인이 몇 개나 숨어 있는지 가릴 수 있습니다.

read →
앱이 내 CSS를 덮어씁니다 - 웹뷰는 브라우저가 아니다 ep.06
  • series
  • develop
  • frontend
  • webview
  • wkwebview
  • androidwebview
  • darkmode
  • accessibility
  • css

앱이 내 CSS를 덮어씁니다 - 웹뷰는 브라우저가 아니다 ep.06

Android 웹뷰의 prefers-color-scheme는 사용자의 OS 다크모드가 아니라 앱 테마의 isLightTheme로 결정됩니다. 시스템 글꼴 배율은 웹 콘텐츠에 곱해지고, 핀치 확대는 앱이 켜지 않으면 아예 동작하지 않습니다. 마지막 항목은 WCAG 1.4.4 위반이기도 합니다. 이 편은 CSS 바깥에서 들어오는 스타일의 출처를 하나씩 지목하고, 웹이 선언할 것과 앱에 요청할 것을 가릅니다.

read →
화면이 잘리고 손이 미끄러집니다 - 웹뷰는 브라우저가 아니다 ep.05
  • series
  • develop
  • frontend
  • webview
  • wkwebview
  • androidwebview
  • viewport
  • safearea
  • css

화면이 잘리고 손이 미끄러집니다 - 웹뷰는 브라우저가 아니다 ep.05

레이아웃 뷰포트와 시각 뷰포트를 나눠 보면 100vh 문제, 키보드에 가려지는 하단 버튼, 노치에 잘리는 헤더가 한 축으로 정렬됩니다. iOS와 안드로이드 크롬과 Android WebView가 서로 다른 시간표로 움직였다는 점, 그리고 CSS로 막을 수 있는 제스처와 없는 제스처의 경계를 버전 조건과 함께 정리합니다.

read →
한글이 덜 조합된 채로 넘어갑니다 - 웹뷰는 브라우저가 아니다 ep.04
  • series
  • develop
  • frontend
  • webview
  • ime
  • hangul
  • composition
  • vue

한글이 덜 조합된 채로 넘어갑니다 - 웹뷰는 브라우저가 아니다 ep.04

조합 이벤트 세 개와 isComposing, 그리고 폐기 예정인 keyCode 229를 같이 봐야 하는 이유를 스펙과 MDN 문서로 정리합니다. 전송 버튼·엔터 중복·실시간 조회·Vue의 v-model까지, 증상별로 틀린 코드와 고친 코드를 나란히 놓고 무엇을 웹에서 막고 무엇을 앱에 요청할지 가릅니다.

read →
폼이 내 디자인이 아닙니다 - 웹뷰는 브라우저가 아니다 ep.03
  • series
  • develop
  • frontend
  • webview
  • wkwebview
  • androidwebview
  • hybridapp
  • forms
  • accessibility
  • autofill
  • passkey
  • webauthn

폼이 내 디자인이 아닙니다 - 웹뷰는 브라우저가 아니다 ep.03

폼 컨트롤은 웹이 마크업으로 선언하고 실제 UI는 플랫폼이 그립니다. 그래서 CSS가 닿지 않고, 커스텀으로 다시 만들면 접근성이 통째로 웹의 책임이 됩니다. 2026년 기준으로 표준 select를 스타일링할 수 있게 된 조건, 파일 선택의 플랫폼별 정반대 기본값, 패스키가 앱과 도메인의 연결을 요구하는 조건, 그리고 인증번호 자동입력이 iOS와 안드로이드에서 갈리는 지점을 근거와 함께 정리합니다.

read →
눌렀는데 아무 일도 안 일어납니다 - 웹뷰는 브라우저가 아니다 ep.02
  • series
  • develop
  • frontend
  • webview
  • wkwebview
  • androidwebview
  • hybridapp
  • navigation

눌렀는데 아무 일도 안 일어납니다 - 웹뷰는 브라우저가 아니다 ep.02

링크와 스킴과 다운로드와 인쇄는 따로 고장 나는 것처럼 보이지만, 실제로는 웹뷰가 "이 요청을 어디로 보낼지" 정하는 하나의 지점을 함께 지납니다. 각 요청이 어느 콜백으로 넘어가는지, 앱이 무엇을 켜지 않으면 사라지는지, 그리고 사용자 제스처가 언제 만료되는지를 공식 문서 기준으로 정리합니다. 웹 코드에서 바꿀 것과 앱에 요청할 것을 갈라 놓는 데까지 갑니다.

read →
같은 엔진, 다른 껍데기 - 웹뷰는 브라우저가 아니다 ep.01
  • series
  • develop
  • frontend
  • webview
  • wkwebview
  • androidwebview
  • useragent
  • debugging
  • hybridapp

같은 엔진, 다른 껍데기 - 웹뷰는 브라우저가 아니다 ep.01

iOS는 웹뷰 엔진이 OS 버전에 묶여 올라가고, Android는 웹뷰가 별도 APK로 앱처럼 올라갑니다. 이 비대칭이 "특정 기기에서만 안 됩니다"의 뿌리입니다. 사용자 에이전트에서 신뢰할 수 있는 신호와 무너진 신호를 가르고, WebView DevTools와 Safari 웹 인스펙터로 실기기 환경을 특정하는 절차, 릴리즈 빌드에서 디버거가 막혔을 때의 대안까지 정리합니다.

read →
브라우저에서는 되는데요 - 웹뷰는 브라우저가 아니다 ep.00
  • series
  • cover
  • develop
  • frontend
  • webview
  • wkwebview
  • androidwebview
  • hybridapp

브라우저에서는 되는데요 - 웹뷰는 브라우저가 아니다 ep.00

웹뷰는 브라우저에서 주소창만 뗀 것이 아닙니다. 브라우저가 기본으로 켜두던 수십 가지 동작이 웹뷰에서는 앱이 명시적으로 켜야 하는 옵션이고, 그 기본값은 대체로 꺼짐입니다. 이 관점을 세우면 "안 되는 것"의 대부분이 "아직 켜지 않은 것"으로 다시 보이고, 웹이 고칠 문제와 앱에 요청할 문제를 처음부터 가를 수 있습니다.

read →
부록: 그 외 GoF 객체 패턴들 - 디자인 패턴, 객체 수준 편 ep.11
  • series
  • develop
  • frontend
  • backend
  • design-patterns
  • gof
  • typescript
  • object-oriented
  • appendix

부록: 그 외 GoF 객체 패턴들 - 디자인 패턴, 객체 수준 편 ep.11

Visitor, Memento, Flyweight, Iterator, Command, Chain of Responsibility, Prototype, Bridge, Mediator, Template Method를 한 편으로 다룹니다. 각 패턴마다 핵심 정의, 실무에서 보이는 자리, 그리고 본편이 아닌 부록에 머무른 이유를 간결하게 정리합니다. 시즌 1 객체 수준 편의 마지막 편입니다.

read →
State와 폼 상태 머신 - 디자인 패턴, 객체 수준 편 ep.10
  • series
  • develop
  • frontend
  • backend
  • design-patterns
  • gof
  • typescript
  • object-oriented
  • state
  • behavioral
  • finite-state-machine

State와 폼 상태 머신 - 디자인 패턴, 객체 수준 편 ep.10

주문 처리 상태(draft → submitted → paid → shipped)를 TypeScript로 정리하고, 분기문이 자라는 안티패턴을 State로 풀어내는 과정을 살펴봅니다. 같은 결정 구조가 폼 상태 머신(idle → validating → submitting → success/error)에서 어떻게 다시 나타나는지를 함께 봅니다. Strategy와의 경계도 다시 한 번 짚습니다.

read →
Observer와 알림 UX의 윤리 - 디자인 패턴, 객체 수준 편 ep.09
  • series
  • develop
  • frontend
  • backend
  • design-patterns
  • gof
  • typescript
  • object-oriented
  • observer
  • behavioral
  • ux-ethics

Observer와 알림 UX의 윤리 - 디자인 패턴, 객체 수준 편 ep.09

EventEmitter와 Pub/Sub의 구조를 TypeScript 코드로 정리하고, Push와 Pull 방식의 차이, 메모리 누수의 함정을 짚습니다. 같은 결정 구조가 사용자에게 닿는 알림 UX에서 어떻게 다시 나타나는지, 그리고 그 알림이 dark pattern과 가까워지는 경계를 함께 살펴봅니다.

read →
Strategy와 다크모드 스위칭 - 디자인 패턴, 객체 수준 편 ep.08
  • series
  • develop
  • frontend
  • backend
  • design-patterns
  • gof
  • typescript
  • object-oriented
  • strategy
  • behavioral
  • design-system

Strategy와 다크모드 스위칭 - 디자인 패턴, 객체 수준 편 ep.08

switch문 안티패턴을 Strategy로 정리하는 TypeScript 예제와 정렬·결제 알고리즘 교체를 살펴봅니다. 같은 결정 구조가 다크모드, 다국어, 플랫폼별 분기에서 어떻게 다시 나타나는지를 함께 살펴봅니다. Strategy와 State의 경계도 짚습니다.

read →
Composite와 디자인 토큰 계층 - 디자인 패턴, 객체 수준 편 ep.07
  • series
  • develop
  • frontend
  • backend
  • design-patterns
  • gof
  • typescript
  • object-oriented
  • composite
  • structural
  • design-tokens

Composite와 디자인 토큰 계층 - 디자인 패턴, 객체 수준 편 ep.07

파일시스템과 UI 트리 예제로 Composite 패턴의 구조를 살펴보고, 같은 결정 구조가 디자인 토큰의 primitive → semantic → component 계층에서 어떻게 다시 나타나는지를 함께 봅니다. 토큰이 다른 토큰을 참조하는 일이 왜 Composite의 가장 자연스러운 사례인지를 짚습니다.

read →
Facade와 디자인 시스템 라이브러리 API - 디자인 패턴, 객체 수준 편 ep.06
  • series
  • develop
  • frontend
  • backend
  • design-patterns
  • gof
  • typescript
  • object-oriented
  • facade
  • structural
  • design-system

Facade와 디자인 시스템 라이브러리 API - 디자인 패턴, 객체 수준 편 ep.06

결제 시스템을 단일 PaymentFacade로 정리하는 TypeScript 예제를 통해 Facade의 구조를 살펴보고, Adapter와의 차이를 명확히 합니다. 같은 결정 구조가 디자인 시스템 컴포넌트 라이브러리의 API 표면(무엇을 노출하고 무엇을 가릴 것인가)에서 어떻게 다시 나타나는지를 함께 봅니다.

read →
Decorator와 Wrapper 컴포넌트의 윤리 - 디자인 패턴, 객체 수준 편 ep.05
  • series
  • develop
  • frontend
  • backend
  • design-patterns
  • gof
  • typescript
  • object-oriented
  • decorator
  • structural
  • react

Decorator와 Wrapper 컴포넌트의 윤리 - 디자인 패턴, 객체 수준 편 ep.05

Logger, Cache, Auth 데코레이터를 체인으로 쌓는 TypeScript 예제로 Decorator의 구조를 살펴보고, HOC와의 차이를 정리합니다. 같은 결정 구조가 Wrapper 컴포넌트와 Compound Component 사이에서 어떻게 다른 답을 내놓는지, 그리고 덧붙임에는 어떤 윤리가 따라오는지를 함께 봅니다.

read →
Adapter와 레거시 컴포넌트 마이그레이션 - 디자인 패턴, 객체 수준 편 ep.04
  • series
  • develop
  • frontend
  • backend
  • design-patterns
  • gof
  • typescript
  • object-oriented
  • adapter
  • structural
  • migration

Adapter와 레거시 컴포넌트 마이그레이션 - 디자인 패턴, 객체 수준 편 ep.04

Object Adapter와 Class Adapter의 차이를 TypeScript 코드로 정리하고, 결제 게이트웨이 통합 예제를 통해 외부 의존을 격리하는 방식을 살펴봅니다. 같은 결정 구조가 디자인 시스템 마이그레이션, 특히 v1 컴포넌트 위에 v2 인터페이스를 입히는 점진적 작업에서 어떻게 다시 나타나는지를 함께 봅니다.

read →
Singleton과 전역 상태·테마 컨텍스트 - 디자인 패턴, 객체 수준 편 ep.03
  • series
  • develop
  • frontend
  • backend
  • design-patterns
  • gof
  • typescript
  • object-oriented
  • singleton
  • creational
  • design-system

Singleton과 전역 상태·테마 컨텍스트 - 디자인 패턴, 객체 수준 편 ep.03

Singleton의 TypeScript 구현과 Eager·Lazy 초기화를 정리합니다. 숨겨진 의존성, 테스트 어려움 같은 안티패턴 논점을 짚고, 디자인 시스템의 ThemeProvider와 React Context가 정말 Singleton인지, 그 결정이 한 개여야만 하는지를 함께 살펴봅니다.

read →
Builder와 폼·필터·쿼리 빌더 UX - 디자인 패턴, 객체 수준 편 ep.02
  • series
  • develop
  • frontend
  • backend
  • design-patterns
  • gof
  • typescript
  • object-oriented
  • builder
  • creational
  • ux

Builder와 폼·필터·쿼리 빌더 UX - 디자인 패턴, 객체 수준 편 ep.02

telescoping constructor가 자라는 자리에 Builder를 두는 이유를 짚고, TypeScript 코드로 fluent interface와 Director의 역할을 정리합니다. 같은 결정 구조가 폼·필터·쿼리 빌더 UI에서 어떻게 다시 나타나는지를 함께 살펴봅니다.

read →
Factory와 디자인 시스템의 컴포넌트 팩토리 - 디자인 패턴, 객체 수준 편 ep.01
  • series
  • develop
  • frontend
  • backend
  • design-patterns
  • gof
  • typescript
  • object-oriented
  • factory
  • creational
  • design-system

Factory와 디자인 시스템의 컴포넌트 팩토리 - 디자인 패턴, 객체 수준 편 ep.01

Simple Factory, Factory Method, Abstract Factory를 TypeScript 코드로 비교합니다. 각 형태가 무엇을 분리하려는 결정인지를 짚고, shadcn/ui 같은 디자인 시스템 라이브러리가 Abstract Factory의 모양을 그대로 따른다는 점을 함께 봅니다.

read →
패턴은 코드가 아니라 결정의 이름이다 - 디자인 패턴, 객체 수준 편 ep.00
  • series
  • cover
  • develop
  • frontend
  • backend
  • design-patterns
  • gof
  • typescript
  • object-oriented

패턴은 코드가 아니라 결정의 이름이다 - 디자인 패턴, 객체 수준 편 ep.00

GoF 카탈로그를 따라가되 각 편에서 그 패턴이 답하려 했던 질문을 함께 짚습니다. 같은 질문이 디자인·시스템 결정에서 다시 나타나는 자리를 연결해 봅니다. 코드 예제는 TypeScript로 통일했습니다.

read →
SI 납품용으로 변환하기: 화석을 인정하는 문서 만들기 - 두 개의 아키텍처 정의서 ep.07
  • series
  • develop
  • backend
  • infra
  • devops
  • architecture
  • documentation
  • adr

SI 납품용으로 변환하기: 화석을 인정하는 문서 만들기 - 두 개의 아키텍처 정의서 ep.07

살아 있던 내부용 정의서를 SI 납품용으로 변환합니다. 납품용은 살릴 수 없는 문서, 곧 화석입니다. 요구사항 추적표를 채우고, 버전과 승인 이력을 붙이고, 특정 시점에 박제합니다. 공공 SI의 감리·검수 맥락을 짚고, 인수인계를 통해 화석이 유지보수팀의 살아있는 문서로 다시 태어나는 흐름까지 그리며 시리즈를 닫습니다.

read →
내부 공유용 정의서: 거짓말하지 않는 문서 만들기 - 두 개의 아키텍처 정의서 ep.06
  • series
  • develop
  • backend
  • frontend
  • infra
  • devops
  • architecture
  • documentation
  • adr

내부 공유용 정의서: 거짓말하지 않는 문서 만들기 - 두 개의 아키텍처 정의서 ep.06

지금까지 모은 재료로 내부 공유용 정의서를 완성합니다. 핵심 과제는 두 번째 죽음, 거짓말을 막는 것입니다. 거짓말이 자라는 메커니즘을 짚고, 천천히 변하는 것만 직접 쓰기·다이어그램을 코드로 그리기·결정을 쌓기·검증을 자동화하기라는 네 원칙으로 거짓말할 수 없는 구조를 만듭니다.

read →
흩어진 정책을 모으다: 횡단 관심사 - 두 개의 아키텍처 정의서 ep.05
  • series
  • develop
  • backend
  • frontend
  • infra
  • architecture
  • documentation
  • security
  • observability

흩어진 정책을 모으다: 횡단 관심사 - 두 개의 아키텍처 정의서 ep.05

횡단 관심사는 여러 컴포넌트에 걸치는 정책입니다. 한 곳에 모아 두지 않으면 컴포넌트마다 다르게 구현되고 어딘가에서는 빠집니다. 이 편에서는 스폿의 여섯 가지 횡단 관심사를 관심사와 컴포넌트의 매트릭스로 정리하고, 같은 외부 의존이라도 동기와 비동기 경로에서 에러 전략이 어떻게 갈라지는지 봅니다.

read →
결정을 남기다: ADR - 두 개의 아키텍처 정의서 ep.04
  • series
  • develop
  • backend
  • frontend
  • infra
  • architecture
  • documentation
  • adr
  • decision-record

결정을 남기다: ADR - 두 개의 아키텍처 정의서 ep.04

ADR은 하나의 설계 결정을 맥락·결정·대안·결과로 남기는 형식입니다. 스폿의 여섯 가지 결정을 ADR로 적고, 결정에도 상태와 수명이 있다는 점을 상태 머신으로 봅니다. 같은 ADR이 내부용에서는 살아있는 로그로, 납품용에서는 요구사항에 매핑되는 목록으로 갈라지는 지점도 다룹니다.

read →
뷰를 그리다: C4와 4+1 - 두 개의 아키텍처 정의서 ep.03
  • series
  • develop
  • backend
  • frontend
  • infra
  • architecture
  • documentation
  • c4
  • diagram

뷰를 그리다: C4와 4+1 - 두 개의 아키텍처 정의서 ep.03

하나의 시스템을 여러 관점으로 나눠 그리는 법을 다룹니다. 4+1 뷰 모델로 누가 무엇을 보는지 가르고, C4의 컨테이너 뷰로 스폿의 구조를, 런타임 뷰로 동기와 비동기 두 경로가 갈라지는 순간을, 배포 뷰로 코드가 어디서 도는지를 그립니다. 같은 그림을 두 문서가 어떻게 다르게 싣는지도 비교합니다.

read →
요구사항에서 시작하기: 품질 속성과 드라이버 - 두 개의 아키텍처 정의서 ep.02
  • series
  • develop
  • backend
  • frontend
  • infra
  • architecture
  • documentation
  • quality-attributes

요구사항에서 시작하기: 품질 속성과 드라이버 - 두 개의 아키텍처 정의서 ep.02

기능 요구사항은 거의 어떤 구조로도 만족됩니다. 구조를 가르는 것은 가용성·성능·보안 같은 품질 속성과 제약입니다. 이 편에서는 품질 속성을 시나리오로 표현하는 법을 익히고, 스폿의 드라이버 여섯 가지를 도출한 뒤, 그것이 어떻게 설계 결정으로 이어지는지 추적합니다.

read →
아키텍처 문서의 표준 지형도 - 두 개의 아키텍처 정의서 ep.01
  • series
  • develop
  • backend
  • frontend
  • infra
  • architecture
  • documentation
  • c4
  • adr
  • arc42

아키텍처 문서의 표준 지형도 - 두 개의 아키텍처 정의서 ep.01

아키텍처 문서를 다루는 네 가지 표준 도구를 정리합니다. ISO/IEC/IEEE 42010은 문서가 답해야 할 질문의 틀을, arc42는 문서의 골격을, C4는 다이어그램을 그리는 법을, ADR은 결정의 기록 형식을 정합니다. 같은 도구를 내부용과 납품용이 어떻게 다르게 쓰는지도 함께 봅니다.

read →
아키텍처 정의서는 왜 화석이 되거나 거짓말이 되는가 - 두 개의 아키텍처 정의서 ep.00
  • series
  • cover
  • develop
  • backend
  • frontend
  • infra
  • architecture
  • documentation
  • c4
  • adr

아키텍처 정의서는 왜 화석이 되거나 거짓말이 되는가 - 두 개의 아키텍처 정의서 ep.00

같은 시스템을 내부 공유용과 SI 납품용, 두 개의 정의서로 나란히 작성하며 비교하는 시리즈입니다. 첫 편에서는 아키텍처 문서가 실패하는 두 가지 방식을 정의하고, 시리즈 전체가 사용할 샘플 시스템을 소개합니다. 이 시리즈가 끝나면 자신만의 정의서를 설계할 기준틀을 갖게 됩니다.

read →
전략 종합: 무엇부터 어디까지 - 사용자 대상 소프트웨어 테스트 가이드 ep.09
  • series
  • develop
  • design
  • frontend
  • testing
  • strategy
  • qa

전략 종합: 무엇부터 어디까지 - 사용자 대상 소프트웨어 테스트 가이드 ep.09

시리즈의 마지막 편입니다. 지금까지 다룬 모든 종류의 테스트를 정리하고, 팀 규모와 코드베이스 성숙도에 따라 무엇부터 도입할지를 결정합니다. 테스트 전략 매트릭스 양식과 흔히 빠지는 함정, 그리고 내일부터 할 수 있는 세 가지 실행 항목으로 시리즈를 닫습니다.

read →
운영 중 모니터링: 진짜 사용자가 마주하는 것 - 사용자 대상 소프트웨어 테스트 가이드 ep.08
  • series
  • develop
  • frontend
  • testing
  • monitoring
  • sentry
  • datadog
  • observability

운영 중 모니터링: 진짜 사용자가 마주하는 것 - 사용자 대상 소프트웨어 테스트 가이드 ep.08

릴리스 전에 모든 것을 검증해도, 배포 직후에 비로소 시작되는 검증이 있습니다. 진짜 사용자가 마주하는 환경에서 일어나는 일을 관찰하는 것이 운영 모니터링입니다. 에러 추적, 실사용 분석, 합성 모니터링이 함께 작동할 때 비로소 사용자 경험이 끝까지 검증됩니다.

read →
성능: 사용자가 느끼는 속도 - 사용자 대상 소프트웨어 테스트 가이드 ep.07
  • series
  • develop
  • frontend
  • testing
  • performance
  • web-vitals
  • lighthouse

성능: 사용자가 느끼는 속도 - 사용자 대상 소프트웨어 테스트 가이드 ep.07

사용자는 페이지가 빠르다고 느끼거나 느리다고 느낍니다. 그 느낌을 객관적으로 측정 가능한 지표로 옮긴 것이 Core Web Vitals입니다. 합성 측정과 실사용 측정이 각자 잡아내는 것이 다르고, 회귀를 막으려면 두 축이 함께 작동해야 합니다.

read →
접근성 자동 검사와 수동 확인 - 사용자 대상 소프트웨어 테스트 가이드 ep.06
  • series
  • develop
  • design
  • frontend
  • testing
  • a11y
  • accessibility
  • wcag
  • axe-core

접근성 자동 검사와 수동 확인 - 사용자 대상 소프트웨어 테스트 가이드 ep.06

접근성은 누구에게 동작하는가의 문제입니다. 키보드만 쓰는 사용자, 스크린리더로 읽는 사용자, 색을 구별하지 못하는 사용자에게도 같은 경험이 가야 합니다. 자동 검사와 수동 확인이 각자 잡아내는 영역이 다르고, 둘을 함께 운영해야 의미가 있습니다.

read →
E2E 테스트: 사용자 흐름 따라가기 - 사용자 대상 소프트웨어 테스트 가이드 ep.05
  • series
  • develop
  • frontend
  • testing
  • e2e
  • playwright
  • cypress

E2E 테스트: 사용자 흐름 따라가기 - 사용자 대상 소프트웨어 테스트 가이드 ep.05

E2E 테스트는 사용자가 실제로 마주하는 시점에서 시작합니다. 진짜 브라우저, 진짜 클릭, 진짜 흐름. 가장 사용자에 가까운 테스트이자 가장 비싸고 깨지기 쉬운 테스트입니다. 무엇을 시나리오로 잡고, 어떻게 신뢰할 수 있게 운영할지 다룹니다.

read →
통합 테스트: 모듈이 만날 때 - 사용자 대상 소프트웨어 테스트 가이드 ep.04
  • series
  • develop
  • backend
  • frontend
  • testing
  • integration-test
  • msw
  • testcontainers

통합 테스트: 모듈이 만날 때 - 사용자 대상 소프트웨어 테스트 가이드 ep.04

단위 테스트가 모두 통과해도 실제 환경에서 작동하지 않는 일이 있습니다. 문제는 보통 모듈이 만나는 경계에 있습니다. 통합 테스트는 그 경계를 검증하는 일입니다. 테스트 더블, 계약 테스트, 환경 격리까지 다룹니다.

read →
컴포넌트와 시각 회귀 - 사용자 대상 소프트웨어 테스트 가이드 ep.03
  • series
  • develop
  • design
  • frontend
  • testing
  • component
  • visual-regression
  • storybook

컴포넌트와 시각 회귀 - 사용자 대상 소프트웨어 테스트 가이드 ep.03

함수 단위의 안전망이 자리잡았다면, 다음은 화면입니다. 컴포넌트 테스트는 UI 단위의 동작을, 시각 회귀 테스트는 픽셀 단위의 변화를 잡아냅니다. 디자인 시스템을 운영한다면 거의 필수에 가까운 영역입니다.

read →
TDD: 테스트를 먼저 쓰는 개발 방식 - 사용자 대상 소프트웨어 테스트 가이드 ep.02
  • series
  • develop
  • frontend
  • testing
  • tdd
  • bdd

TDD: 테스트를 먼저 쓰는 개발 방식 - 사용자 대상 소프트웨어 테스트 가이드 ep.02

TDD는 단순히 테스트를 빨리 쓰는 방식이 아니라, 테스트가 설계의 도구가 되는 사고법입니다. Red-Green-Refactor 사이클이 코드의 모양을 어떻게 바꾸는지, 모든 상황에 맞는 방식인지, 그리고 BDD와의 관계까지 살펴봅니다.

read →
단위 테스트: 가장 작은 안전망 - 사용자 대상 소프트웨어 테스트 가이드 ep.01
  • series
  • develop
  • frontend
  • testing
  • unit-test
  • vitest
  • jest

단위 테스트: 가장 작은 안전망 - 사용자 대상 소프트웨어 테스트 가이드 ep.01

단위 테스트는 가장 작고 가장 빠른 테스트입니다. 함수 하나가 어제와 똑같이 동작한다는 보장이 있을 때, 그 위에 무엇을 쌓아도 무너지지 않습니다. 이 편에서는 무엇을 단위로 보고, 어디까지 테스트해야 하는지, 그리고 실무에서 자동화의 첫 발을 떼는 법을 살펴봅니다.

read →
사용자가 느끼는 품질을 어떻게 검증하나 - 사용자 대상 소프트웨어 테스트 가이드 ep.00
  • series
  • cover
  • develop
  • frontend
  • testing
  • qa

사용자가 느끼는 품질을 어떻게 검증하나 - 사용자 대상 소프트웨어 테스트 가이드 ep.00

테스트는 코드를 검증하는 일이 아니라 사용자가 마주할 미래를 미리 가보는 일입니다. 이 시리즈는 사용자 대상 소프트웨어의 테스트를 범위, 품질 속성, 시점이라는 세 가지 축으로 정리합니다. 그 위에 단위 테스트부터 운영 중 모니터링까지, 실무에 하나씩 도입할 수 있는 순서로 풀어갑니다.

read →
본 시리즈 바깥의 인접 문서들 - 개발자를 위한 기술문서 입문 ep.09
  • series
  • develop
  • design
  • frontend
  • backend
  • infra
  • devops
  • ai
  • user-manual
  • design-doc
  • security
  • appendix

본 시리즈 바깥의 인접 문서들 - 개발자를 위한 기술문서 입문 ep.09

본 시리즈는 내부 개발 협업에서 쓰는 문서에 초점을 맞췄습니다. 그러나 그 바깥에도 자리한 문서들이 있습니다. 비개발자가 읽는 사용자 매뉴얼, 구현 직전에 동료에게 의견을 구하는 디자인 문서, 공개와 비공개 사이의 보안 문서. 이번 편은 각자의 위치를 짚어두며 시리즈를 마칩니다.

read →
매일 쓰는 협업의 글: PR · 커밋 · 온보딩 - 개발자를 위한 기술문서 입문 ep.08
  • series
  • develop
  • frontend
  • backend
  • infra
  • devops
  • ai
  • commit
  • pull-request
  • onboarding
  • code-review

매일 쓰는 협업의 글: PR · 커밋 · 온보딩 - 개발자를 위한 기술문서 입문 ep.08

기술문서라고 하면 큰 글을 떠올리지만, 개발자가 가장 자주 쓰는 글은 커밋 메시지와 PR 설명입니다. 거기에 온보딩 문서가 더해지면, 팀의 일상이 만들어집니다. 이번 편은 좋은 커밋의 골격, 리뷰가 즐거워지는 PR, 그리고 첫 주를 단축시키는 온보딩을 다룹니다.

read →
운영의 언어: 런북과 포스트모템 - 개발자를 위한 기술문서 입문 ep.07
  • series
  • develop
  • frontend
  • backend
  • infra
  • devops
  • ai
  • runbook
  • postmortem
  • incident
  • on-call
  • blameless

운영의 언어: 런북과 포스트모템 - 개발자를 위한 기술문서 입문 ep.07

운영 문서는 평소엔 안 읽힙니다. 읽힐 때는 누군가 잠에서 깬 새벽 3시이거나, 무언가가 막 망가진 직후입니다. 그래서 톤이 다릅니다. 군더더기가 없어야 하고, 감정이 빠져 있어야 하고, 사실이 우선해야 합니다. 이번 편은 런북의 응급 카드 구조와 포스트모템의 비난 없는 글쓰기를 다룹니다.

read →
의사결정의 기록: ADR과 RFC - 개발자를 위한 기술문서 입문 ep.06
  • series
  • develop
  • frontend
  • backend
  • infra
  • devops
  • ai
  • adr
  • rfc
  • decision-record
  • architecture

의사결정의 기록: ADR과 RFC - 개발자를 위한 기술문서 입문 ep.06

팀의 큰 결정은 어딘가에 적혀야 합니다. 결정 *전*의 글은 RFC, 결정 *후*의 글은 ADR입니다. 둘은 같은 주제를 다루지만 톤·구조·수명이 다릅니다. 이번 편은 ADR과 RFC의 위치 차이, 각자의 템플릿, 그리고 ADR의 상태 머신을 다룹니다.

read →
왜 이렇게 만들었는가: 아키텍처와 개념 설명 - 개발자를 위한 기술문서 입문 ep.05
  • series
  • develop
  • frontend
  • backend
  • infra
  • devops
  • ai
  • explanation
  • architecture
  • c4-model
  • diagram

왜 이렇게 만들었는가: 아키텍처와 개념 설명 - 개발자를 위한 기술문서 입문 ep.05

익스플레네이션은 왜의 글입니다. 결정의 배경, 다른 길과의 비교, 트레이드오프를 다룹니다. 이번 편은 C4 모델로 줌 레벨을 잡고, 여섯 가지 대표 다이어그램의 쓰임을 정리한 뒤, 설명문이 자주 빠지는 두 함정(묘사와 변호)을 짚습니다.

read →
// see all posts_ 105 posts →