PIElog — MANAPIE의 글과 실험

// featured post_

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

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

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

read →

// experiences · 8_

  • 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 · 73_

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 →
정확한 사실의 색인, 레퍼런스와 API 문서 - 개발자를 위한 기술문서 입문 ep.04
  • series
  • develop
  • frontend
  • backend
  • infra
  • devops
  • ai
  • reference
  • api
  • openapi
  • docstring

정확한 사실의 색인, 레퍼런스와 API 문서 - 개발자를 위한 기술문서 입문 ep.04

레퍼런스는 가장 조용한 문서입니다. 처음부터 끝까지 읽으라고 만든 글이 아니라, 색인처럼 필요할 때 펼쳐 보라고 만든 글입니다. 그래서 미덕이 완전성과 일관성입니다. 이번 편은 레퍼런스 스펙트럼을 따라 docstring·시그니처·스펙을 짚고, 한 항목을 어떻게 써야 하는지 그 골격을 살핍니다.

read →
한 가지 목적을 해내는 절차, 하우투 가이드 - 개발자를 위한 기술문서 입문 ep.03
  • series
  • develop
  • frontend
  • backend
  • infra
  • devops
  • ai
  • how-to
  • guide
  • procedure

한 가지 목적을 해내는 절차, 하우투 가이드 - 개발자를 위한 기술문서 입문 ep.03

하우투는 목적이 있는 사람을 위한 글입니다. 골격은 단순합니다. 목적·전제·단계·검증·다음 행동. 그러나 분기를 잘못 다루는 순간 글은 무너집니다. 이번 편은 하우투의 골격을 짚고, 분기를 다루는 세 가지 패턴과 자주 망가지는 지점을 봅니다.

read →
처음 온 사람을 데려가는 길, 튜토리얼 - 개발자를 위한 기술문서 입문 ep.02
  • series
  • develop
  • frontend
  • backend
  • infra
  • devops
  • ai
  • tutorial
  • onboarding
  • learning

처음 온 사람을 데려가는 길, 튜토리얼 - 개발자를 위한 기술문서 입문 ep.02

튜토리얼의 가장 흔한 실수는 설명을 하려 든다는 것입니다. 튜토리얼은 학습자에게 작은 성공을 안기는 글이고, 그 성공이 다음 학습으로 이어지는 글입니다. 하우투와 어떻게 다른지, 학습자 여정을 어떻게 설계하는지, 좋은 예와 나쁜 예까지 짚어봅니다.

read →
프로젝트의 첫인상, README - 개발자를 위한 기술문서 입문 ep.01
  • series
  • develop
  • frontend
  • backend
  • infra
  • devops
  • ai
  • readme
  • documentation
  • open-source

프로젝트의 첫인상, README - 개발자를 위한 기술문서 입문 ep.01

README는 한 글이 아니라 여러 글의 시작점입니다. 평가자·사용자·기여자라는 세 유형의 독자를 30초·5분·30분이라는 시간 축으로 갈라보고, Hero / Quick Start / Deep 세 구간으로 골격을 잡습니다. 좋은 예와 나쁜 예, 그리고 체크리스트까지.

read →
왜, 무엇을, 어떻게 - 개발자를 위한 기술문서 입문 ep.00
  • series
  • cover
  • develop
  • frontend
  • backend
  • infra
  • devops
  • ai
  • technical-writing
  • documentation
  • diataxis

왜, 무엇을, 어떻게 - 개발자를 위한 기술문서 입문 ep.00

기술문서를 안 써본 개발자가 가장 자주 겪는 문제는 형식이 아니라 의도입니다. 이 시리즈는 Diátaxis 프레임워크로 문서의 좌표를 잡고, 실무에서 실제로 마주치는 여덟 가지 산출물을 한 편씩 다룹니다. ep.00은 그 지도를 펴 보이는 편입니다.

read →
어트리뷰션과 도구 지도 - 마케팅 지표 핸드북 ep.12
  • series
  • develop
  • design
  • marketing
  • metrics
  • attribution
  • ga4
  • amplitude
  • mixpanel

어트리뷰션과 도구 지도 - 마케팅 지표 핸드북 ep.12

시리즈의 마지막 편. 한 사용자가 광고를 다섯 번 보고 가입했다면 그 공로는 어느 광고에게 갈까요. 첫 광고, 마지막 광고, 모든 광고에 골고루, 또는 데이터가 학습한 가중치. 어트리뷰션 모델 일곱 종과 마지막으로 실제 도구들 — GA4, Amplitude, Mixpanel의 차이까지. 13개 용어로 시리즈를 마칩니다.

read →
트래킹과 데이터 수집 - 마케팅 지표 핸드북 ep.11
  • series
  • develop
  • design
  • frontend
  • marketing
  • metrics
  • tracking
  • analytics
  • utm
  • pixel

트래킹과 데이터 수집 - 마케팅 지표 핸드북 ep.11

지금까지의 모든 지표가 정확하기 위해서는 데이터가 정확하게 수집되어야 합니다. UTM 파라미터로 채널을 구분하고, 이벤트로 사용자 행동을 잡고, 픽셀과 태그로 외부 매체와 연결하고, 서버사이드 트래킹으로 정확도를 끌어올리는 흐름. 그리고 쿠키 시대 종말과 동의 모드까지. 측정 인프라의 어휘 12개.

read →
실험과 통계 - 마케팅 지표 핸드북 ep.10
  • series
  • develop
  • design
  • marketing
  • metrics
  • ab-test
  • statistics
  • experimentation

실험과 통계 - 마케팅 지표 핸드북 ep.10

지표가 좋아졌다. 그런데 진짜 우리 변경의 효과일까. 아니면 그냥 운일까. 이 질문에 답하기 위한 통계 도구들 — A/B 테스트의 설계, 표본 크기 계산, p-value의 의미, 두 종류의 오류, 그리고 통계적 유의성과 비즈니스 유의성의 차이까지. 12개 용어를 정리합니다.

read →
만족과 추천 - 마케팅 지표 핸드북 ep.09
  • series
  • develop
  • design
  • marketing
  • metrics
  • nps
  • csat
  • viral
  • k-factor
  • referral

만족과 추천 - 마케팅 지표 핸드북 ep.09

만족도의 측정 방법은 하나가 아닙니다. 추천 의향을 묻는 NPS, 즉시 만족을 묻는 CSAT, 노력의 무게를 묻는 CES. 그리고 만족한 사용자가 추천을 통해 새 사용자를 만드는 바이럴 계수와 K-factor. 사용자가 마케팅이 되는 구조의 어휘 10개.

read →
수익과 단위경제 - 마케팅 지표 핸드북 ep.08
  • series
  • develop
  • design
  • marketing
  • metrics
  • ltv
  • cac
  • mrr
  • unit-economics
  • saas

수익과 단위경제 - 마케팅 지표 핸드북 ep.08

광고비를 쓰고, 사용자를 데려오고, 활성화하고, 유지한 결과 회사가 살아남는가의 질문에 답하는 편입니다. LTV와 CAC의 정의와 그 비율, 월 반복 매출과 연 반복 매출, 회수 기간과 기여 마진까지. 가장 무거운 편이자 모든 편이 모이는 편.

read →
이탈(Churn) - 마케팅 지표 핸드북 ep.07
  • series
  • develop
  • design
  • marketing
  • metrics
  • churn
  • retention
  • nrr
  • grr
  • saas

이탈(Churn) - 마케팅 지표 핸드북 ep.07

유지의 반대편을 다룹니다. 한 달 사이에 누가 떠났는가, 그게 매출에 어떤 영향을 주는가. 고객 수 기준 이탈과 매출 기준 이탈의 차이, SaaS의 핵심 지표 NRR과 GRR, 자발과 비자발 이탈의 구분, 그리고 윈백과 부활까지. 11개 용어를 정리합니다.

read →
코호트와 리텐션 곡선 - 마케팅 지표 핸드북 ep.06
  • series
  • develop
  • design
  • marketing
  • metrics
  • retention
  • cohort
  • pmf
  • growth

코호트와 리텐션 곡선 - 마케팅 지표 핸드북 ep.06

DAU와 MAU가 현재 시점의 사진이라면, 리텐션은 시간을 따라 사용자가 얼마나 남는지의 영상입니다. 같은 날 가입한 사람을 묶어 따라가는 코호트, 그 코호트의 잔존을 그린 리텐션 곡선, 그리고 그 곡선이 평탄해지는 모양에서 PMF를 읽는 법까지. 10개 용어를 정리합니다.

read →
유지와 참여 - 마케팅 지표 핸드북 ep.05
  • series
  • develop
  • design
  • marketing
  • metrics
  • retention
  • dau
  • mau
  • engagement
  • session

유지와 참여 - 마케팅 지표 핸드북 ep.05

활성화한 사용자가 계속 돌아오는가의 문제. 일·주·월 활성 사용자를 묶는 단위, 두 단위를 나눠 만드는 Stickiness, 세션의 정의와 그 안의 시간 지표들. DAU가 늘었는데 사용자는 그대로일 수 있는 이유와 그 함정까지 정리합니다.

read →
활성화와 온보딩 - 마케팅 지표 핸드북 ep.04
  • series
  • develop
  • design
  • marketing
  • metrics
  • activation
  • onboarding
  • aha-moment

활성화와 온보딩 - 마케팅 지표 핸드북 ep.04

가입은 끝이 아니라 시작입니다. 가입한 사람이 실제로 서비스의 가치를 경험하고 다시 돌아오는 사용자로 전환되는 구간 — 활성화. Activation Rate, Time-to-Value, Aha Moment, Onboarding Completion까지 11개 용어를 정리합니다. 페이스북의 10명 친구 추가, 슬랙의 2,000개 메시지 같은 Magic Number 사례도 함께.

read →
유입과 클릭 - 마케팅 지표 핸드북 ep.03
  • series
  • develop
  • design
  • marketing
  • metrics
  • ctr
  • cvr
  • ux
  • landing-page

유입과 클릭 - 마케팅 지표 핸드북 ep.03

광고 클릭 직후부터 가입·구매 전까지의 짧은 구간에서 일어나는 일을 측정하는 지표들입니다. 클릭률과 전환율의 관계, 이탈률과 나가기 비율의 차이, 첫 화면(Above-the-fold)이 모든 것을 결정하는 이유, 그리고 히트맵과 클릭맵이 무엇을 보여주고 무엇을 가리는지까지. 디자이너에게 가장 직접적인 편.

read →
광고 효율 지표 - 마케팅 지표 핸드북 ep.02
  • series
  • develop
  • design
  • marketing
  • metrics
  • advertising
  • roas
  • roi
  • mer
  • kpi

광고 효율 지표 - 마케팅 지표 핸드북 ep.02

광고비를 얼마나 썼는지(ep.01)에 이어 그래서 얼마를 벌었는지를 다룹니다. ROAS와 ROI의 차이, 광고 매니저가 자기 광고만 본다는 한계, 증분 ROAS와 블렌디드 CAC가 등장한 이유까지. SaaS와 이커머스의 사고 차이도 함께 정리합니다.

read →
광고 비용 지표 - 마케팅 지표 핸드북 ep.01
  • series
  • develop
  • design
  • marketing
  • metrics
  • advertising
  • kpi
  • cpm
  • cpc
  • cpa

광고 비용 지표 - 마케팅 지표 핸드북 ep.01

광고비를 어디에 어떻게 쓰고 있는지 보여주는 비용 지표를 정리합니다. 노출 단가, 클릭 단가, 액션 단가의 차이와 함께 노출·도달·빈도가 같은 노출 데이터를 세 각도에서 본다는 점을 다룹니다. 가상 서비스 센티와 토스·당근·카카오 광고를 사례로 사용합니다.

read →
검증과 운영 — 테스트, 인증, 조직 문화 - 앱·웹 접근성 실무 가이드 ep.06
  • series
  • develop
  • devops
  • a11y
  • wcag
  • testing
  • certification
  • organization

검증과 운영 — 테스트, 인증, 조직 문화 - 앱·웹 접근성 실무 가이드 ep.06

자동화 도구가 발견하는 30~40% 너머의 영역, 한국 WA 인증 절차, 이슈 우선순위 산정 공식, CI/CD 파이프라인 접근성 게이트, 조직의 챔피언 모델, 그리고 5단계 성숙도 모델까지. 검사 통과로 끝나지 않는 운영의 영역을 마지막 편에서 정리하며 시리즈를 마무리합니다.

read →
개발자와 디자이너를 위한 - 마케팅 지표 핸드북 ep.00
  • series
  • develop
  • design
  • cover
  • marketing
  • metrics
  • glossary
  • kpi
  • ux

개발자와 디자이너를 위한 - 마케팅 지표 핸드북 ep.00

마케팅 지표 136개를 개발자와 디자이너의 시선으로 정리한 13부작 시리즈의 출발점입니다. 가상 서비스 센티(Centi)를 일관된 예시로 두고, 퍼널 단계별·실무 시나리오별·UI 컴포넌트별 세 가지 색인으로 입구를 세 개 만들었습니다. 어느 쪽으로 들어와도 원하는 용어에 닿도록 설계했습니다.

read →
모바일·프레임워크 — iOS, Android, React, Vue, Flutter - 앱·웹 접근성 실무 가이드 ep.05
  • series
  • develop
  • mobile
  • frontend
  • ios
  • android
  • react
  • a11y

모바일·프레임워크 — iOS, Android, React, Vue, Flutter - 앱·웹 접근성 실무 가이드 ep.05

SwiftUI의 accessibility 수정자와 Compose의 semantics, Flutter의 Semantics 위젯을 비교하고, 네이티브·하이브리드·웹뷰 아키텍처별 접근성 함정을 짚습니다. React Aria·Radix·Headless UI 같은 헤드리스 라이브러리, jsx-a11y 린트 규칙, VoiceOver와 TalkBack 차이까지 한 편에 모았습니다.

read →
개발 단계 — 시맨틱 HTML과 ARIA, 키보드, 스크린리더 - 앱·웹 접근성 실무 가이드 ep.04
  • series
  • develop
  • frontend
  • a11y
  • wcag
  • semantic-html
  • aria
  • keyboard

개발 단계 — 시맨틱 HTML과 ARIA, 키보드, 스크린리더 - 앱·웹 접근성 실무 가이드 ep.04

네이티브 HTML이 ARIA + JavaScript 20줄을 대체하는 이유, W3C ARIA 5대 규칙, 랜드마크와 라이브 리전 설계, 모달 포커스 트랩 구현, 복합 위젯의 표준 키보드 패턴까지. 가장 많은 실수가 발생하는 단계인 만큼 가장 길게 다룹니다.

read →
디자인 단계 — 색·타이포·모션·시스템 - 앱·웹 접근성 실무 가이드 ep.03
  • series
  • design
  • ux
  • a11y
  • wcag
  • contrast
  • dark-mode
  • design-system

디자인 단계 — 색·타이포·모션·시스템 - 앱·웹 접근성 실무 가이드 ep.03

WCAG 명도 대비 기준의 실전 적용, 색상에만 의존하지 않는 정보 전달, 다크·고대비 모드 동시 대응 전략, 포커스 인디케이터와 터치 타겟 디자인, 그리고 디자인 시스템 컴포넌트에 접근성 명세를 끼워 넣는 패턴을 정리합니다.

read →
// see all posts_ 81 posts →