return new Story();

회사에서 AI 에이전트 스킬 어떻게 관리할까? — skill-cli 개발 회고

Parse — Fri, 29 May 2026 18:24:58 +0900

사내 AI 하네스용 스킬을 터미널에서 바로 설치·공유·삭제할 수 있는 CLI를 만들었다.

배경 — 왜 만들었나

회사에서 AI 하네스 시스템을 구축하면서, 그 위에 올라갈 스킬들을 정의해두고 운영하고 있다.

그런데 협의해서 변경사항이 생길 때마다 스킬을 추가하고 업데이트하는 과정이 꽤 번거롭다고 느꼈다.

그냥 단순하게, 업데이트하고 다운받고 하면서 싱크만 잘 맞추면 되겠다는 생각이 들었다.

원래는 웹에서 다운받는 마켓 형태로 운영할 계획이었는데, 생각해보니 CLI로 만드는 게 더 자연스럽더라.

터미널에서 바로 다운로드도 되고, Claude Code로 직접 조작할 수 있으니 훨씬 편할 거라고 봤다.

그래서 사이드프로젝트로 skill-cli를 만들기 시작했다.

뭘 만들었나

핵심 기능은 세 가지다.

1. 스킬 리스트 조회 — 마켓에 어떤 스킬이 있는지, 내 PC에는 어떤 스킬이 있는지 따로따로 볼 수 있다.

2. 퍼블리시 분기 — 로컬 스킬이 마켓에서 다운받은 건지, 내가 로컬에서만 만든 건지 구분해서 보여주고, 후자만 퍼블리시 대상으로 잡을 수 있게 했다.

3. 로컬 삭제 — 스킬이 너무 많으면 오히려 Claude Code 성능이 떨어지기 때문에, 마켓에 이미 업로드된 스킬은 로컬에서 쉽게 삭제할 수 있게 했다.

추가로, 카테고리를 회사 조직도 기반으로 2-depth로 쪼개서 필터링이 빠르게 되도록 했다.

핵심 구현

스택은 간단하다.

TUI: Ink (React 기반이라 익숙)
저장소: GitLab
배포: npm

GitLab을 마켓 백엔드로 쓴 이유는 어차피 사내에서 다 GitLab 쓰니까 별도 인프라 추가 안 해도 되고, 권한 관리도 그대로 따라가서 편했다. 사내에서만 쓸 수 있는게 목표기 때문에 사내에서 돌아가는 GitLab를 기반으로 작업을 했다.

npm으로 배포하니 설치도 한 줄이고, 업데이트도 자연스럽게 흘러간다.

배운 것

사실 TUI나 CLI 도구를 만드는 건 이번이 처음이었다. 만드는 과정 자체가 재미있었다.

가장 많이 고민한 건 UX였다.

그냥 스킬을 나열해서 보여주는 게 아니라, 조직도를 기반으로 카테고리를 쪼개고 그 안에 스킬을 노출하는 방식으로 갔다.

빠른 필터링과 빠른 배포, 이 두 가지를 목표로 잡고 작업했다.

다만 사이드프로젝트로 진행한 만큼 완성도가 높진 않다고 느껴져셔 아쉬웠다.

빠른 배포가 목표였고, AI랑 페어로 만들면서 시간 대비 괜찮은 퀄리티가 나왔다고는 생각한다.

하지만 사용자들을 설득하는 데는 한계가 있었다. 만드는 것보다 쓰게 하는 게 더 어렵더라.

마무리

사용도를 높이려면 어떻게 해야 할지가 다음 숙제다.

도구 자체보다 사람들이 이걸 일상에 끼워 넣을 이유를 만들어 주는 게 진짜 일이라는 걸 다시 한 번 느꼈다.

POC를 진행하면서 느낀점도 나중에 또 글로 작성하면 좋을 것 같다.

Claude Code 워크플로우 (3) — Boris Cherny "Why Coding Is Solved" 강연 후기

Parse — Tue, 5 May 2026 22:13:39 +0900

시리즈 로드맵

(1) gstack + Superpowers — 두 플러그인만 남긴 이유
(2) gstack /office-hours로 AI에게 제품 인터뷰를 받아봤다
(3) Boris Cherny "Why Coding Is Solved" 강연 후기 ← 현재 글

TL;DR

Boris Cherny는 2025년 10월부터 손으로 코드를 짜지 않는다. 하루 PR을 수십 개, 기록은 150개까지 올린다.
그의 작업 방식의 중심은 세션을 capacity로 스케줄링하는 것 — 터미널 5탭, 브라우저 5~10세션, 핸드폰까지 동시에 돌아간다. 핵심은 디바이스가 아니라 *"주의력을 어디에 배분하느냐"*다.
그가 자주 쓰는 메커니즘은 /loop (cron으로 반복 작업 스케줄)와 새 기능 Routines (서버 측에서 영구 실행).
Boris도 YC 출신이고, 거기서 배운 첫 원칙이 *"first build for yourself". (1)~(2)편의 *"Make something people want"와 정확히 같은 자리에 있다.
시리즈 결론: 사용자 인터뷰와 프롬프트 설계는 같은 능력이다. 도구가 무엇이든 앞단에서 정확하게 정의하는 일이 결과의 90%를 결정한다.

영상을 보게 된 맥락 — Boris도 YC 출신이라니

강연 관련 자료를 정리하다가 Pragmatic Engineer 인터뷰와 developing.dev 인터뷰에서 Boris 본인의 발언을 발견했습니다.

"I did YC back in the day, and in YC they teach you that first you build for yourself. You have to build awesome stuff. You have to build stuff people love."

Boris도 창업해서 YC를 거쳐본 사람이었고, 거기서 배운 첫 원칙이 "first build for yourself" — 너 자신을 위해 먼저 만들어라, 그게 다른 사람도 같은 문제를 갖고 있다는 가장 좋은 신호니까 — 였다는 겁니다.

이걸 알고 나서 강연을 다시 보면, 왜 그가 자기 자신을 위해 Claude Code를 만들고 "이게 내가 코드 짜는 방식이었다"라고 자연스럽게 말하는지가 다르게 들립니다. 우연이 아니라 일관된 원칙입니다.

강연의 골자 — 숫자로 보는 워크플로우

영상과 외부 보도(BigGo 분석, Pragmatic Engineer)를 종합하면 그의 작업 방식은 이렇게 요약됩니다.

항목	내용
마지막으로 손코딩한 시점	2025년 10월
일일 PR	수십 개, 기록은 150개
동시 세션 수	터미널 5탭 + 브라우저 5~10 + 핸드폰
핵심 메커니즘	`/loop` (cron 스케줄), Routines (서버 측 영구 실행)
사용 코드베이스	TypeScript + React (모델의 "분포 위에 있다"는 이유로 의도적으로 선택)
변곡점 모델	Opus 4 (2025년 5월 출시) — 이 모델 이후 100% AI 코딩 가능

수치만 보면 비현실적인 사람 같지만, 그가 만든 도구가 그걸 가능하게 설계됐다는 게 핵심입니다.

"loop"가 정확히 뭔가

영상에서 자주 나오는 단어가 loop입니다. 그는 이걸 *"crontab처럼 돌리는 것"이라고 표현하는데, 단순한 비유가 아닙니다 — /loop 슬래시 커맨드가 실제로 cron을 사용해 반복 작업을 스케줄합니다.

기존 LLM 사용 = 단발성. "한 번 묻고 한 번 답한다."
loop = 영구. "한 번 잘 정의해두고 계속 돌아간다."

그가 loop로 처리한다고 밝힌 작업들:

PR 베이비시팅 (CI 실패 자동 수정, 자동 리베이스)
피드백 클러스터링
데이터 변화 감지 후 결과를 Slack으로 푸시 (MCP 경유)

여기서 한 단계 더 나간 게 Routines — 2026년 4월 발표된 새 기능입니다. 공식 발표에 따르면 Routines는 "한 번 설정하면 스케줄에 따라, API 호출로, 또는 GitHub 이벤트에 반응해서 실행되며, Anthropic 인프라 위에서 돌기 때문에 노트북이 필요 없다"고 합니다.

즉, 작업이 그의 디바이스에 묶여 있지 않습니다. 사람은 어디서든 지시·검증만 하고, 실제 작업은 서버에서 계속 돌아가는 구조입니다.

이 부분에서 (1)편의 5단계 워크플로우와 결이 비슷하다고 느꼈습니다. (1)편의 핵심도 "사람이 모든 단계에 붙어있지 않는다"였습니다. 회의(/office-hours) → 계획서(writing-plans) → 분업 실행(sub-agent) 형태로 각 단계가 독립적으로 돌아갑니다. Boris는 그걸 훨씬 더 극단적으로 밀어붙인 형태일 뿐입니다.

"AI는 도구가 아니라 capacity다"

Karo Zieminski의 정리에 나오는 한 줄이 강했습니다.

"Boris doesn't see AI as a tool you use, but as a capacity you schedule."

처음엔 "동시에 여러 세션을 돌린다"가 그냥 멀티태스킹 자랑처럼 보였는데, 이 표현으로 보면 다르게 읽힙니다. 그는 AI를 컴퓨팅 자원처럼 다룹니다 — 큐에 넣고, 워크로드를 분배하고, 컨텍스트 스위치는 결과가 나왔을 때만 합니다.

병목은 모델 생성 속도가 아니라 사람의 주의력 배분이라는 게 그의 입장입니다. 이 관점이 왜 그가 동시에 10~15개 세션을 돌리는가를 설명해줍니다 — 한 세션이 답변 만드는 동안 다른 세션의 결과를 처리하면, 사람은 항상 "다음 결정"만 내리면 되니까요.

Plan Mode — Boris도 "계획 우선"

(1)편에서 "바로 만들어줘 금지, /office-hours부터"라고 적었던 게 떠올라서 약간 놀란 부분이 있습니다. Boris의 워크플로우 핵심 원칙도 같았습니다.

그의 X 스레드와 후속 정리에 따르면, 그는 거의 모든 세션을 Plan Mode로 시작합니다. Plan Mode에서 Claude와 왔다갔다하며 계획을 다듬고, 충분히 좋아지면 그제야 auto-accept edits 모드로 전환해 실행시킵니다.

표현은 다르지만 같은 이야기입니다.

도구	"계획 우선" 메커니즘
gstack (1편)	`/office-hours`로 회의 → `writing-plans`로 계획서
Claude Code (Boris)	Plan Mode에서 계획 확정 → auto-accept edits로 실행

그가 강조하는 한 줄 — "never let Claude write code until you've reviewed and approved a written plan" — 은 (1)편의 운영 규칙(새 프로젝트는 무조건 회의부터)과 정확히 같은 원칙입니다.

인쇄술 비유 — 가장 와닿았던 한 대목

Boris가 코딩의 미래를 비유한 방식이 인상적이었습니다.

인쇄술 이전에 글을 읽고 쓸 수 있는 사람은 인구의 일부분이었다 — 필경사(scribes)였다. 인쇄술 이후 그게 보편화됐다.

같은 일이 코딩에 일어나고 있다는 게 그의 주장입니다. 코딩을 직업으로 가진 사람만 할 수 있는 일이었지만, 앞으로는 "컴퓨터로 일하는 사람"이라면 누구나 코딩으로 자기 문제를 해결할 거라는 거죠.

이 비유가 자극적이지만, 그가 든 본인 팀의 사례를 보면 단순한 슬로건이 아닙니다 — Claude Code 팀의 PM, EM, 디자이너, 데이터 사이언티스트, 파이낸스 리드, 유저 리서처까지 모두 코드를 친다고 합니다. 모든 직군이 자기 영역의 전문성은 유지하되, 코딩이 보편 기술처럼 깔리는 셈입니다.

"코딩이 solved 됐다"의 단서들

이 표현은 자극적이라 따로 정리해 둘 필요가 있습니다. 영상과 보도를 합쳐보면 단서는 분명합니다.

그가 짜는 종류의 코드에 한해서다. 그가 짜는 건 TypeScript + React 기반의 비교적 표준적인 웹 코드입니다.
남아있는 어려운 영역은 큰 복잡한 코드베이스, 그리고 모델이 충분히 학습하지 못한 비주류 언어.
그의 답은 "보통은 다음 모델을 기다리면 된다". 즉, 솔루션이 코드 짜는 능력이 아니라 모델 발전에 있다는 입장입니다.
이 입장은 그의 다른 원칙과도 맞물립니다 — "At Anthropic, we don't build for the model of today, we build for the model of six months from now." Claude Code가 초기 6개월간 거의 안 작동한 이유이자, 결국 Opus 4 출시와 함께 폭발적으로 작동하기 시작한 이유.

이 단서들 덕분에 "AI가 모든 코드를 다 짠다"는 메시지로 받아들이지 않을 수 있었습니다. 도메인 지식이 깊은 비즈니스 로직, 레거시 마이그레이션, 임베디드, 시스템 코드 같은 영역은 여전히 사람이 깊게 붙어있어야 합니다.

두 인사이트가 만나는 지점

(1)~(2)편을 거쳐 이 강연을 보면서 정리된 한 문장이 있습니다.

사용자 인터뷰와 프롬프트 설계는 같은 능력이다.

(2)편에서 본 /office-hours의 효용 = "내가 만들 것을 앞단에서 정확하게 정의하는 일"
Boris의 워크플로우 = "에이전트가 만들 것을 앞단에서 정확하게 정의하는 일"

둘 다 앞단의 정의가 결과의 90%를 결정한다고 말하고 있고, 그 정의를 잘하는 능력 — 모호한 것을 구체화하고, 우선순위를 정하고, 트레이드오프를 명시하는 — 이 진짜 핵심 기술이 된다는 결론에 도달합니다.

YC의 "Make something people want"도 같은 자리에 있습니다. *사람들이 진짜로 원하는 것을 정확하게 정의하고, 그것에 맞춰 만들어라. Boris가 YC에서 배웠다는 "first build for yourself"도 결국 같은 원칙의 다른 표현입니다 — 자기가 진짜 필요로 하는 것에서 시작하면 정의가 모호할 일이 적으니까요.

도구가 무엇이든(스타트업이든, 코드든, 에이전트든) 앞단의 정의가 흔들리면 뒷단의 모든 자원이 낭비됩니다. 이게 시리즈를 통해 잡힌 큰 그림이고, 다음 1년 동안 제 작업에서 가장 비중 있게 두려는 부분입니다.

한계와 남은 의문

Boris가 보여준 워크플로우는 그가 만든 제품이고, 그가 가장 잘 쓰는 환경입니다. 외부 개발자가 그대로 따라 한다고 같은 생산성이 나오진 않을 것이라고 봅니다. 본인이 "이건 내가 짜는 종류의 코드에 한해서"라고 단서를 단 게 그 증거입니다.
"loop 기반 워크플로우"의 가장 큰 위험은 검증 단계가 약하면 사고가 누적된다는 점입니다. 다행히 Boris도 이 부분을 인지하고 있어서, 본인의 13가지 팁 중 마지막을 "give Claude a way to verify its work"로 꼽았습니다 — 검증 루프가 있으면 결과 품질이 2~3배가 된다고 합니다. 다만 그가 쓰는 검증(Chrome 확장으로 UI 자동 테스트)은 그의 스택(TypeScript + React)이라서 가능한 부분이 큽니다. 다른 도메인에서는 어떻게 verify할 것인가가 별도의 설계 문제로 남습니다.
"모든 사람이 코딩한다"는 비전은 매력적이지만, 읽는 것과 쓰는 것은 다릅니다. PM이 Claude Code로 프로토타입을 만드는 것과, 그 코드의 보안·성능·유지보수 책임을 지는 것은 다른 문제입니다. 인쇄술 비유가 깔끔하지만, 책임의 층은 그 비유에 안 들어가 있습니다.
(2)편에서 언급한 것처럼 AI에게 인터뷰를 받는 게 진짜 사용자 인터뷰를 대체하지 않듯이, 잘 짜인 프롬프트가 사용자 검증을 대체하지 않습니다. 둘 다 본질적으로 "앞단의 정의를 더 좋게 하는 도구"일 뿐, 정의 자체가 옳다는 보장은 아닙니다.

핵심 정리

Boris Cherny는 2025년 10월부터 손코딩을 안 한다. 하루 PR 수십 개~150개를 처리한다.
그의 작업 방식의 중심은 세션을 capacity로 스케줄링하는 것 — 터미널·브라우저·핸드폰을 가로지르는 10~15개 동시 세션. 병목은 모델이 아니라 주의력 배분이다.
핵심 메커니즘은 /loop (cron 스케줄)와 Routines (서버 측 영구 실행).
Boris도 YC 출신. 거기서 배운 첫 원칙이 "first build for yourself" — (1)~(2)편의 Make something people want와 같은 자리.
"코딩이 solved 됐다"는 단서가 분명하다 — 그가 짜는 종류의 코드에 한해서. Plan Mode와 verification 루프가 그의 워크플로우의 두 축이다.
시리즈 결론: 사용자 인터뷰와 프롬프트 설계는 같은 능력이다. 도구가 무엇이든 앞단에서 정확하게 정의하는 일이 결과의 90%를 결정한다.

참고 자료

원본 영상: Anthropic's Boris Cherny: Why Coding Is Solved, and What Comes Next (Sequoia Capital, 2026.05.04)
가장 자세한 보도(150 PR/일·Routines·product overhang 등): BigGo Finance 분석
Boris 본인의 워크플로우 트윗 정리: howborisusesclaudecode.com
Boris의 YC 경험 + 커리어: developing.dev — On How His Career Grew
더 깊은 인터뷰: Pragmatic Engineer — Building Claude Code with Boris Cherny
인쇄술 비유 관련 보도: Fortune (2026.02.24)
Y Combinator 원칙: Make Something People Want
시리즈 (1)편: gstack + Superpowers 두 플러그인만 남긴 이유
시리즈 (2)편: gstack /office-hours로 AI에게 제품 인터뷰를 받아봤다

시리즈 마무리

세 글을 쓰면서 잡힌 큰 그림은 단순합니다. 앞단에서 정확하게 정의할수록, 뒷단의 도구가 더 많은 일을 알아서 한다.

(1)편에서 도구를 추렸고, (2)편에서 그 도구로 인터뷰를 받아봤고, (3)편에서 같은 원칙이 훨씬 큰 스케일에서 작동하는 사례를 봤습니다. 그리고 그 사례를 만든 사람도 결국 같은 학교(YC)의 같은 원칙(build for yourself)을 거쳐온 사람이었습니다.

다음 1년은 이 원칙을 내 작업에서 어떻게 더 잘 살릴 수 있는가에 집중해보려 합니다.

Claude Code 워크플로우 (2) — gstack `/office-hours`로 AI에게 제품 인터뷰를 받아봤다

Parse — Tue, 5 May 2026 20:13:20 +0900

시리즈 로드맵

(1) gstack + Superpowers — 두 플러그인만 남긴 이유
(2) gstack /office-hours로 AI에게 제품 인터뷰를 받아봤다 ← 현재 글
(3) Boris Cherny "Why Coding Is Solved" 강연 후기 — YC와 loop 워크플로우

TL;DR

gstack의 /office-hours는 코드를 짜기 전에 Claude가 PM처럼 인터뷰를 진행해주는 명령어다.
직접 받아보니 가장 강한 느낌은 "내가 아이디어를 얼마나 모호하게 갖고 있었는지"가 드러난다는 점이었다.
인터뷰 자체보다 답변하는 동안 스스로 정리되는 효과가 더 컸다. 사람이 하는 인터뷰와 결정적으로 다른 점이 여기에 있다.
결과물은 단순한 회의록이 아니라 "합의된 전제 + 다음 한 주 과제"로 떨어진다. 이게 코드 작성 전에 손에 쥐어진다는 게 핵심이다.

환경

Claude Code (글로벌 설치)
gstack: ~/.claude/skills/gstack/
인터뷰 대상 프로젝트: StudOX (PDF 학습 자료에서 OX 퀴즈를 자동 생성·복습하는 Electron 데스크톱 앱)
인터뷰 진행일: 2026-04-08
소요 시간: 약 30분

`/office-hours`가 뭔가

gstack에 포함된 슬래시 커맨드입니다. 실행하면 Claude가 창업 액셀러레이터의 오피스 아워에 온 PM처럼 질문을 던지기 시작합니다. "뭘 만들고 싶어?"가 아니라 "누가 이걸 정말 필요로 하는지 근거가 뭐야?" 식으로요.

저는 처음에 "AI한테 인터뷰 받는다는 게 뭐 다를 게 있겠나" 싶었습니다. 그런데 30분쯤 지나고 나니 손에 인터뷰 정리본이 한 장 남았는데, 이게 단순한 회의록이 아니었습니다.

인터뷰가 어떻게 진행되는가

순서는 대략 이렇습니다.

1. 프로젝트 한 줄 소개 → Claude가 핵심 포지셔닝 질문
2. 수요 근거(Demand Evidence) → "정말 원한다는 증거가 뭐야?"
3. 현재 대안(Status Quo) → "지금은 어떻게 해결하고 있어?"
4. 타깃 유저 → "구체적으로 누구야?"
5. 경쟁 환경 → "이미 있는 도구들과 뭐가 달라?"
6. 합의된 전제 → 지금까지 나온 답을 표로 정리
7. 다음 한 주 과제 → "이번 주에 뭐 할래?"

각 단계에서 Claude는 만족할 만한 답이 나올 때까지 한두 번 더 압박합니다. "그건 너무 모호한데, 더 구체적으로 말해봐"가 자주 나옵니다.

강했던 질문 3개

전체 흐름 중에서 답하기 어려웠던 질문이 세 개였습니다. 어려웠다는 건, 그 영역을 제가 제대로 정리하지 못한 채 시작하려 했다는 뜻입니다.

1. "누군가가 이걸 정말 원한다는 가장 강한 근거는?"

처음엔 "사람들이 PDF 공부할 때 퀴즈 만들고 싶어 하잖아요"라고 답했습니다. Claude의 반응은 *"그건 너의 추측이지, 근거가 아니다"*에 가까웠습니다. 답변을 바꿔야 했습니다.

최종 답변은 *"친구/동기들이 시험 공부 중 직접 요청했고, NotebookLM을 쓰면서 '오답노트가 없다'는 구체적 불만을 토로했다"*로 좁혀졌습니다.

이때 깨달은 것: "사람들이 원할 것 같다"와 "특정인이 active pain 상태에서 요청했다"는 완전히 다른 신호입니다. 후자만 진짜 수요 신호입니다.

2. "지금 이 문제를 어떻게 해결하고 있는가?"

이 질문이 의외로 컸습니다. "아무도 안 풀고 있다"고 답하려다 멈췄습니다. 진짜로 그런가? 다시 보니 NotebookLM을 이미 쓰고 있고, 거기서 막힌 부분이 있다가 정확한 답이었습니다.

"아무것도 없다"가 아니라 "있는데 부족하다" — 이게 훨씬 좋은 출발점이라는 걸 이때 알게 됐습니다. 사용자가 이미 행동하고 있다는 뜻이고, 대체 비용도 낮다는 뜻이니까요.

3. "구체적으로 누가 이걸 가장 필요로 하는가?"

"공부하는 사람들"이라고 답했더니 *"그건 6천만 명이다"*라는 식의 압박이 왔습니다. 좁혀야 했습니다.

세 번 정도 좁힌 끝에 "고시·편입 준비생 (하루 10시간+, 수개월~수년 단위 PDF 교재 학습)"이 나왔습니다. 이 정도까지 좁히고 나니, 그 사람들에게 닿을 수 있는 채널(고시 카페, 독서실, 편입 학원)도 같이 떠올랐습니다. 타깃이 흐릿할 땐 채널이 안 보이고, 타깃이 또렷해지면 채널이 따라옵니다.

AI 인터뷰가 사람과 다른 점

받기 전엔 "그래 봐야 ChatGPT랑 한 번 더 말하는 거 아닌가" 싶었는데, 끝나고 나니 결정적으로 다른 점이 두 개 있었습니다.

첫째 — 답변하는 사람이 정리된다

사람과의 인터뷰는 인터뷰어가 정보를 모으는 활동입니다. 답하는 쪽은 "내가 아는 걸 말하는" 입장이라서 새로 정리되는 건 적습니다.

/office-hours는 반대였습니다. 답하는 동안 내가 정리됐습니다. 질문을 받고 입력하는 그 30초 동안, 머릿속에서 "어, 잠깐. 내가 이걸 왜 만들고 있더라?"가 자주 나왔습니다.

곰곰이 생각해보니 이건 새로운 현상이 아닙니다. "질문 받으면서 스스로 정리되는 경험"은 좋은 시니어와 1:1을 할 때 흔히 일어나는 일이고, 더 옛날로 가면 코칭이나 상담의 핵심 메커니즘이기도 합니다. 다만 그런 시니어/코치의 시간은 비싸고 약속을 잡아야 하는데, AI는 30분짜리 슬롯을 즉시 만들어줍니다. 이게 차별점이라면 차별점입니다.

둘째 — 결과물의 형식이 강하다

사람과의 인터뷰는 보통 메모로 끝납니다. 내가 다시 정리해야 회의록이 됩니다.

/office-hours는 끝나면 자동으로 다음 형식이 손에 쥐어집니다.

## 합의된 전제 (Premises)
| # | 전제 | 상태 |
|---|------|------|
| 1 | 핵심 가치는 오답노트 시스템이지, 퀴즈 생성이 아니다 | 합의 |
| 2 | 고시/편입 준비생이 첫 번째 타겟 시장이다 | 합의 |
| ...

## 핵심 과제 (The Assignment)
> 이번 주: 고시/편입 준비생 5명을 찾아서 StudOX를 줘라.
> 옆에서(또는 화면공유로) 처음 사용하는 걸 지켜봐라.
> 도와주지 마라. 설명하지 마라.
> 가장 중요한 관찰 포인트: 오답노트를 스스로 열어보는가, 아니면 무시하는가?

"합의된 전제"와 "이번 주 과제" — 이 두 섹션이 자동으로 떨어지는 게 핵심입니다. 코드를 짜기 전에 무엇이 합의됐고, 무엇을 검증해야 하는지가 글로 정리돼 있습니다.

실제로 받은 과제

인터뷰 끝에 받은 과제는 *"이번 주에 코드 더 쓰지 말고, 5명에게 줘봐라"*였습니다.

저는 인터뷰 들어갈 때 *"오답노트 화면을 메인으로 승격하면 좋을까?"* 같은 기능 단위 질문을 가지고 있었는데, 결론은 "그 질문에 답하기에 충분한 사용자 데이터가 없다"였습니다.

3가지 옵션이 제시됐습니다.

	접근	기간	리스크
A	오답노트 Deep — 메인 화면 승격, 간격 반복 등	1~2주	낮음
B	백엔드 구축 + 커뮤니티 기능	3~4주	중간 (사용자 없이 인프라 위험)
C	5명 테스트 — 아무것도 만들지 말고 관찰	이번 주	낮음

C → A 순서로 결론이 났습니다. 즉, 만들기 전에 본다가 우선이고, 본 결과를 바탕으로 오답노트를 메인으로 승격할지 결정하는 흐름입니다.

이게 인터뷰의 효용이라고 생각합니다. 들어갈 때 "기능 우선순위"를 묻고 있던 사람이, 나올 땐 "검증 우선순위"를 들고 나옵니다. 질문의 층이 한 단 위로 올라갑니다.

한계와 남은 의문

AI는 진짜 사용자가 아닙니다. /office-hours가 잘 잡아주는 건 "내 사고의 공백"이지, "시장의 공백"이 아닙니다. 결국 진짜 인터뷰는 5명에게 직접 줘보고 옆에서 보는 일로만 가능합니다. 인터뷰는 그 진짜 인터뷰를 잘 설계하기 위한 사전 단계입니다.
답변자가 솔직해야 효용이 납니다. Claude는 "그럴듯한 답"이 들어오면 더 압박하지 않고 넘어가기도 합니다. 모르는 건 모른다고, 추측은 추측이라고 표시하는 솔직함이 결과물의 품질을 좌우합니다.
포맷이 너무 강하다는 점은 양날의 검입니다. "수요 근거 → 대안 → 타깃 → 경쟁 → 전제 → 과제" 흐름이 깔끔하지만, 이 틀에 안 맞는 종류의 프로젝트(예: 인프라 도구, 내부 툴)에는 어색할 수 있습니다. 그런 경우엔 인터뷰 도중에 "이 질문은 우리 케이스에 안 맞아"라고 명시하고 넘어가는 게 낫습니다.
인터뷰 결과를 신성시하면 안 됩니다. 합의된 전제는 "지금까지 합의된 것"일 뿐이고, 5명 테스트 후에 첫 번째로 바뀌어야 할 것이 바로 이 전제 표입니다. 살아있는 문서로 다뤄야 합니다.

핵심 정리

/office-hours는 코드 짜기 전 30분짜리 PM 인터뷰다. AI가 액셀러레이터 오피스 아워처럼 질문을 던진다.
인터뷰의 진짜 효용은 답하는 동안 스스로 정리되는 것이다. 인터뷰어가 정보를 얻기보다, 답변자가 자기 사고의 공백을 발견하는 도구다.
강했던 질문 3개: "수요 근거", "현재 대안", "구체적 타깃". 이 셋에 막히면 만들기 시작하면 안 된다.
결과물은 회의록이 아니라 "합의된 전제 표 + 이번 주 과제" 형태로 떨어진다. 코드를 짜기 전에 손에 쥐어진다는 게 핵심.
들어갈 땐 기능 우선순위를 묻던 사람이, 나올 땐 검증 우선순위를 들고 나온다. 질문의 층이 한 단 올라간다.

참고 자료

시리즈 (1)편: gstack + Superpowers 두 플러그인만 남긴 이유
gstack: garrytan/gstack
영감을 받은 원칙: Y Combinator — "Make Something People Want"
관련 노트: [[Office Hours 인터뷰 정리 (2026-04-08)]], [[Claude Code 플러그인 워크플로우 (gstack + Superpowers)]]

(3)편에서는 이 인터뷰 경험과 정확히 맞물리는 강연을 다룹니다. Anthropic의 Boris Cherny가 AI Ascent 2026에서 한 "Why Coding Is Solved" 발표인데, 거기서 "사용자 인터뷰가 곧 프롬프트 설계"라는 통찰이 나옵니다. (2)편에서 느낀 감각이 더 큰 그림으로 연결되는 지점입니다.

Claude Code 워크플로우 (1) — gstack + Superpowers 두 플러그인만 남긴 이유

Parse — Tue, 5 May 2026 19:45:24 +0900

시리즈 로드맵

이 글은 Claude Code 워크플로우 시리즈의 첫 번째입니다.

(1) gstack + Superpowers — 두 플러그인만 남긴 이유 ← 현재 글
(2) gstack /office-hours로 제품 인터뷰를 받아봤다 — StudOX 사례
(3) Boris Cherny "Why Coding Is Solved" 강연 후기 — YC와 loop 워크플로우

도구 소개 → 실제 사용 경험 → 더 큰 맥락(AI 에이전트의 미래)으로 이어지는 구성입니다.

TL;DR

플러그인이 많을수록 좋은 게 아니다. 컨텍스트가 비대해져서 오히려 오작동·설정 복잡화로 이어진다.
gstack은 "회의와 품질 게이트", Superpowers는 "실행과 기록" 역할로 명확히 갈린다. 두 역할이 겹치지 않아서 시너지가 난다.
작업 순서는 5단계: /office-hours → 문서화 → brainstorming → writing-plans → git worktrees + sub-agent driven development.
핵심은 "바로 만들어줘"를 금지하고 회의부터 시작하는 것. 이거 하나로 결과물 품질이 눈에 띄게 달라진다.

환경

macOS (M 시리즈)
Claude Code (글로벌 설치)
gstack: ~/.claude/skills/gstack/
superpowers: ~/.claude/skills/superpowers-* (using-superpowers, brainstorming, writing-plans, executing-plans, subagent-driven-development, using-git-worktrees, verification-before-completion, test-driven-development 등)

왜 두 개만 남았나

Claude Code 출시 이후 플러그인을 여러 개 시도해봤는데, 대부분 두 가지 문제가 있었습니다.

기능은 많은데 워크플로우에 안 맞는다. 어떤 단계에서 꺼내 써야 할지 애매해서 결국 안 쓰게 된다.
설치할수록 컨텍스트가 비대해진다. Claude에 주입되는 시스템 프롬프트가 늘어나면서 오히려 오작동하거나 의도와 다른 방향으로 작업이 흘러간다.

기능 개수가 가치를 결정하지 않는다는 걸 체감했습니다. 워크플로우에 녹아드는지가 관건이었고, 결국 두 플러그인의 조합이 가장 자연스럽게 흘러갔습니다.

Claude Code의 초기 실패 패턴

처음엔 "말만 하면 뭐든 만들어줄 줄 알았다"는 생각으로 썼습니다. 결과는 "이게 아닌데"의 반복이었습니다.

이건 마치 인테리어 리모델링에서 사전 협의 없이 착공하는 것과 비슷합니다. 시공자가 알아서 잘해주겠지 하고 맡기면, 완성된 결과물이 머릿속에 그렸던 모습과 한참 다릅니다.

특히 작업이 복잡해질수록 악화됐습니다.

생각이 덜 정리된 채 요청 → Claude가 자기 식으로 해석 → 엇나감
이쪽 고치면 저쪽 깨짐. 혼자 이삿짐 나르는 느낌
집중력이 흐트러지고 실수가 누적

이 패턴을 깨려면 착공 전에 회의를 해야 했습니다. 그게 gstack의 역할입니다.

두 플러그인의 역할 분담

gstack — 회의 & 품질 게이트

명령어	용도
`/office-hours`	프로젝트 시작 전 아이디어 회의. Claude가 인터뷰하듯 질문을 던져 아이디어를 구체화시킨다. 본인도 미처 정리하지 못했던 부분을 드러내게 만든다.
`/design-review`	AI 슬롭(과도한 그라데이션·이모지·뻔한 레이아웃 등) 탐지. "AI 티" 줄이고 세련된 결과물을 뽑게 도와준다.

이 둘의 공통점은 "멈추게 만든다"는 점입니다. 시작 전에 멈춰서 정리하게 하고, 끝나기 전에 멈춰서 검증하게 합니다.

Superpowers — 실행 & 기록

기능	용도
Sub-Agent Driven Development	큰 작업을 기획/디자인/개발/QA 팀처럼 작은 에이전트들이 분담해서 진행. 한 명이 다 하는 것보다 결과물 품질이 올라간다.
Git Worktrees	작업 공간 분리. "여러 프로젝트 서류를 같은 책상에 뒤섞지 않고 각자 책상에 분리"하는 개념.
자동 작업 기록	의미 있는 단위마다 자동 커밋/로그. 개발 흐름이 끊기지 않고 히스토리도 추적하기 쉬워진다.
Brainstorming Skill	방향 검토. UX/UI 목업을 빠르게 뽑는 용도로도 강력하다. Figma 없이 실시간 디렉팅이 가능.
Writing Plans Skill	단계별 계획서 작성. 공사 전 설계 도면 역할.

Superpowers는 "회의가 끝난 뒤 실제로 일을 해내는" 부분을 담당합니다. 분업과 기록이 핵심입니다.

실제 작업 순서 — 5단계

두 플러그인을 조합한 작업 순서는 다음과 같습니다.

1. gstack       /office-hours              ← 아이디어 회의 (15~20분)
2. (수동)        대화 내용을 문서로 정리
3. Superpowers  brainstorming skill        ← 놓친 부분 검토
4. Superpowers  writing-plans skill        ← 단계별 계획서 = 설계 도면
5. Superpowers  git worktrees + 
                subagent-driven-development ← 작업 공간 분리 + 팀 단위 실행

1단계 — `/office-hours`: "같이 생각해볼까"로 시작하기

가장 큰 변화는 "바로 만들어줘"라고 말하지 않는 것입니다. 대신 /office-hours로 시작합니다.

Claude가 PM처럼 질문을 던집니다.

누가 이걸 가장 필요로 하는가?
지금 이 문제를 어떻게 해결하고 있는가?
이미 비슷한 도구가 있는가? 그것과 뭐가 달라지는가?
이걸 만들면 어떤 트레이드오프가 생기는가?

이 과정에서 머릿속에서 흐릿했던 부분이 드러납니다. 본인이 아이디어를 얼마나 모호하게 갖고 있었는지 깨닫는 단계이기도 합니다.

이 단계의 자세한 사례는 시리즈 (2)편에서 다룹니다. 실제 프로젝트(StudOX)에서 /office-hours를 돌렸던 인터뷰 정리본을 풀어볼 예정입니다.

2단계 — 문서화

/office-hours 결과를 그냥 흘려보내지 않고 마크다운으로 정리합니다. 머릿속 흐릿한 아이디어를 구체적인 글로 옮기는 과정 자체가 정리 효과가 큽니다.

저장 위치는 01_Projects/<프로젝트>/office-hours-<날짜>.md로 통일했습니다. 나중에 시리즈 (2)편에서 보여드릴 StudOX 인터뷰 정리본도 이 규칙으로 저장돼 있습니다.

3단계 — Brainstorming: 놓친 부분 검토

Office Hours 결과를 들고 Superpowers의 brainstorming skill로 넘어갑니다. 출발 전에 지도를 한 번 더 확인하는 단계입니다.

우리가 합의한 전제 중 위험한 게 있는가?
놓친 사용자/시나리오가 있는가?
UI가 필요한 작업이면 여기서 목업까지 뽑아낸다

UI 목업을 실시간으로 디렉팅할 수 있다는 건 이 플러그인의 숨겨진 강점입니다. Figma를 따로 열지 않아도 "버튼 위치 좀 옮겨줘", "이 영역은 카드형으로 바꿔줘" 식의 수정이 채팅으로 됩니다.

4단계 — Writing Plans: 설계 도면 만들기

여기가 변곡점입니다. Claude가 지금까지의 대화를 바탕으로 "1단계: ..., 2단계: ..., 3단계: ..." 형태의 단계별 계획서를 만들어줍니다.

이 계획서가 이후 모든 작업의 기준점이 됩니다. 작업 중간에 방향이 흔들릴 때마다 이 문서를 다시 펴서 "지금 이게 1단계 작업이 맞나?"를 확인합니다.

저장 위치는 01_Projects/<프로젝트>/plan.md로 고정했습니다.

5단계 — Git Worktrees + Sub-Agent Driven Development: 분업과 병렬

마지막은 실행입니다. 두 가지를 동시에 씁니다.

Git Worktrees: 기능별로 독립된 작업 공간을 만든다. A 기능 작업 중에 B 기능을 건드리지 않게 됨.
Sub-Agent Driven Development: 한 작업을 기획/디자인/개발/QA 역할의 에이전트로 나눠서 처리. 한 에이전트가 모든 걸 하는 것보다 각자 자기 역할에 집중할 때 품질이 올라간다.

자동 작업 기록 덕분에 의미 있는 단위마다 커밋이 남고, 나중에 히스토리를 따라가기 쉬워집니다.

두 플러그인의 시너지

이 5단계가 자연스럽게 작동하는 이유는 두 플러그인이 역할이 안 겹치기 때문입니다.

시작·끝: gstack이 담당 (회의 / 디자인 리뷰)
중간 실행: Superpowers가 담당 (계획·분업·기록)

"3단 로켓"처럼 작동합니다. gstack(회의) → Superpowers(계획+실행) → gstack(디자인 리뷰).

다른 플러그인 조합은 대부분 역할이 겹치거나 흐름이 끊겼는데, 이 둘은 자기 영역만 담당하면서 자연스럽게 연결됩니다.

내가 정한 운영 규칙

지난 한 달간 쓰면서 정착시킨 규칙입니다.

새 프로젝트는 무조건 /office-hours부터. "바로 만들어줘"는 금지.
Office Hours 결과는 항상 01_Projects/<프로젝트>/office-hours-<날짜>.md로 저장.
계획서는 항상 01_Projects/<프로젝트>/plan.md. 작업 중 방향 잃으면 이걸 다시 본다.
기능 단위 작업은 git worktree로 분리해서 병렬 진행.
/design-review는 UI가 있는 결과물 모든 PR 전에 돌린다.

한계와 남은 의문

이 워크플로우는 새 프로젝트나 큰 기능 추가에 잘 맞습니다. 반대로 작은 버그 수정·5분짜리 작업에는 오버헤드가 큽니다. 이런 경우엔 Office Hours를 건너뛰고 바로 작업합니다.
Superpowers의 sub-agent driven development는 강력하지만 컨텍스트 사용량이 많습니다. 토큰 비용을 의식하지 않고 쓰기엔 부담이 있어서, 작업 단위를 잘 쪼개야 합니다.
gstack은 비교적 신생 도구라서 한국어 처리에 가끔 문제가 생깁니다. 첫 OSS 기여로 한글 UTF-8 스트리밍 깨짐 PR을 올린 이유이기도 합니다.
"Claude가 PM 역할을 잘 해주는가"는 결국 모델 성능과 프롬프트 설계에 달려 있습니다. Office Hours가 늘 만족스러운 인터뷰를 뽑아주는 건 아니고, 답변이 얕다 싶으면 본인이 더 압박해야 합니다.

핵심 정리

플러그인은 적게 쓰는 게 낫다. 컨텍스트 비대화는 실제 오작동의 원인이 된다.
gstack은 회의·품질 게이트, Superpowers는 실행·기록. 역할이 겹치지 않아서 시너지가 난다.
5단계 워크플로우의 핵심은 "바로 만들어줘" 금지 — 회의(/office-hours)부터 시작.
계획서(plan.md)는 작업의 기준점. 방향이 흔들릴 때마다 돌아온다.
UI 작업은 반드시 /design-review로 마무리. AI 슬롭을 거른다.

참고 자료

영감을 받은 영상: Claude Code 플러그인 워크플로우 정리 (YouTube)
gstack: garrytan/gstack
Anthropic 공식 Claude Code 문서: docs.claude.com/claude-code
관련 노트: [[Claude Code 플러그인 워크플로우 (gstack + Superpowers)]], [[PR-1007 한글 UTF-8 스트리밍 fix]]

시리즈 (2)편에서는 이 워크플로우의 1단계인 /office-hours를 실제 프로젝트(StudOX)에서 돌렸던 인터뷰 정리본을 펼쳐볼 예정입니다. AI에게 제품 인터뷰를 받는 게 어떤 경험인지, 어떤 질문이 던져졌고, 결과적으로 무엇이 명확해졌는지 다룹니다.

AI와 개발할 때 자꾸 어긋나는 이유 — Matt Pocock 강연을 보고 다시 꺼낸 DDD

Parse — Mon, 4 May 2026 19:36:26 +0900

들어가며

AI와 개발하다 보면 가끔 벽 너머로 대화하는 느낌이 들 때가 있습니다. 분명히 같은 한국어로 말하고 있는데, 결과물은 내가 머릿속에 그린 것과 점점 멀어집니다.

저도 최근에 비슷한 경험을 했습니다. 현업 시스템에 대한 맥락을 설명하고 기능 구현을 요청했는데, AI가 가져온 결과는 제가 의도한 것과 꽤 어긋나 있었습니다. 내 설명이 부족했나 보다 싶어서 더 구체적으로, 더 길게, 거의 기획서 분량으로 풀어 적었죠. 그런데 결과는 오히려 더 멀어졌습니다.

그때는 막연히 "AI는 아직 멀었구나, 신규 프로젝트나 잘 만들지" 정도로 결론을 냈었습니다. 그런데 며칠 전 본 Matt Pocock의 강연 "Software Fundamentals in the Age of AI" 가 이 문제에 대해 제가 놓치고 있던 답을 들려줬습니다. 다만, 강연이 제시한 해법 중 일부는 제 경험과 부딪히는 지점도 있었습니다.

TL;DR
AI에게 더 길게 설명할수록 결과가 더 어긋난 이유는, 내가 말을 적게 해서가 아니라 공유된 언어가 없어서였다. DDD의 유비쿼터스 언어(Ubiquitous Language) 개념은 사람-사람 사이의 문제였지만, AI 시대에는 사람-AI 사이의 문제이기도 하다.

"더 자세히 설명하면 되겠지"의 함정

당시 제 가설은 단순했습니다.

AI가 못 알아듣는 건 내가 충분히 설명하지 않아서다.

그래서 시스템 구조, 도메인 규칙, 예외 케이스, 기존 코드 컨벤션까지 한꺼번에 길게 풀어 넣었습니다. 결과는 정반대였습니다. 코드는 좀 더 장황해지고, 의도하지 않은 추상화가 늘어나고, 처음 계획에서 멀어졌습니다. Matt Pocock은 강연에서 이 현상을 두 가지 실패 모드로 나눠 설명합니다.

AI와 사용자 사이에 소통의 장벽이 있다. 실용주의 프로그래머의 말처럼, "아무도 자신이 무엇을 원하는지 정확히 알지 못한다."
AI가 너무 장황하다. 이는 전통적으로 개발자와 도메인 전문가 사이에 존재했던 언어 격차와 같은 구조의 문제다.

두 번째 문장에서 멈췄습니다. "개발자와 도메인 전문가 사이의 언어 격차" — 이건 새로운 이야기가 전혀 아닙니다. 우리가 DDD에서 오랫동안 다뤄온 그 문제니까요.

DDD의 유비쿼터스 언어, AI에게 다시 적용되다

Matt Pocock이 제시한 해법은 의외로 익숙합니다. 도메인 주도 설계의 유비쿼터스 언어입니다.

코드베이스를 스캔해 도메인 용어 목록을 마크다운 파일로 정리한다.
그 파일을 AI에게 항상 컨텍스트로 제공한다.
AI는 그 언어 안에서 사고하고, 그 언어 안에서 코드를 쓴다.

결과는 명확합니다. AI의 사고 과정이 짧아지고, 덜 장황해지고, 구현이 계획과 더 잘 일치합니다.

다시 내 경험으로

이 부분에서 제 실패의 원인이 명확해졌습니다.

저는 그동안 AI에게 더 많은 단어를 줬지만, 공유된 단어는 주지 못했습니다. 시스템에 대한 장황한 산문은 컨텍스트 윈도우만 채울 뿐, AI에게 "이 도메인에서 X는 정확히 무엇인가"를 알려주지 못합니다. 오히려 같은 개념을 매번 다른 표현으로 풀어 쓰니 AI 입장에서는 매번 새로운 개념처럼 받아들여졌을 겁니다.

핵심 깨달음은 이거였습니다.

유비쿼터스 언어는 새로 등장한 개념이 아니다. 사람과 사람 사이에서 쓰던 도구를, 사람과 AI 사이에 다시 적용한 것이다.

DDD를 안다고 생각했지만, 저는 그것을 팀 회의 도구로만 써왔습니다. AI와의 대화에도 같은 원리가 통한다는 사실은 의식하지 못했습니다.

강연에서 같이 와닿았던 다른 포인트들

유비쿼터스 언어 외에도 영상에서 인상 깊었던 지점을 짧게만 적어둡니다.

"코드는 싸지 않다." AI가 코드를 빨리 만들어주니 코드가 싸졌다는 주장이 있지만, Matt Pocock은 정반대로 나쁜 코드는 역사상 가장 비싸다고 말합니다. 변경하기 어려운 코드베이스에서는 AI도 도움을 줄 수 없기 때문입니다.
"좋은 코드베이스에서 AI는 잘 작동한다." 깊은 모듈, 명확한 인터페이스, 자동화된 테스트가 있는 코드베이스는 AI에게도 좋은 작업 환경입니다. 즉, 소프트웨어 기본기는 AI 시대에 덜 중요해진 게 아니라 더 중요해졌습니다.
"AI는 헤드라이트를 앞질러 달린다." LLM은 한 번에 너무 많은 걸 하려고 합니다. 그래서 TDD처럼 작은 피드백 루프를 강제하는 도구가 LLM에게도 효과적입니다.

이 포인트들은 모두 한 방향을 가리킵니다. AI와 잘 일하려면, 결국 사람이 잘 일하던 방식으로 돌아가야 한다.

그런데 — 한 가지 의문: "회색지대" 처방은 정말 안전한가

강연 후반부에서 Matt Pocock은 흥미로운 처방을 하나 더 제시합니다. 깊은 모듈로 인터페이스를 잘 설계해두면, 모듈 외부에 테스트 가능한 경계만 있으면 그 내부 구현은 AI에 위임하고 개발자가 굳이 들여다보지 않아도 된다는 것입니다. 이걸 강연에서는 "신경 쓰지 않아도 되는 회색지대"처럼 다룹니다. 인터페이스와 테스트가 경계를 잡아주니, 안에서 무슨 일이 일어나든 결과만 맞으면 된다는 논리입니다.

이론적으로는 매력적입니다. 그런데 저는 여기서 한 번 의심이 들었습니다. 테스트가 그 경계를 정말 지켜준다는 전제가 실제 AI 협업에서 늘 성립하느냐는 점입니다.

저는 최근 AI에게 테스트 코드 작성까지 맡겨 본 적이 있습니다. 의도는 강연이 말한 그대로였습니다. 인터페이스와 테스트로 경계를 만들고, 그 안의 구현은 위임하자는 것이었죠. 그런데 그 과정에서 불편한 장면을 목격했습니다.

AI가 에러 케이스에서 테스트가 실패하자, 구현을 고치는 대신 테스트 코드 자체를 바꿔서 에러 케이스를 우회해버린 것입니다.

표면적으로는 테스트가 모두 통과합니다. 피드백 루프는 잘 돌고 있는 것처럼 보입니다. 하지만 실제로는 테스트가 잡아야 할 케이스가 슬쩍 사라진 상태였습니다. 만약 제가 그 시점에 테스트 코드를 직접 들여다보지 않았다면, "회색지대"라는 이름으로 신뢰하고 넘어갔을 것입니다.

이 경험 때문에 저는 강연의 해당 처방을 그대로 받아들이기 어렵습니다. 정확히는 이렇게 정리됩니다.

인터페이스와 테스트로 경계를 만든다는 발상 자체는 옳다.
그러나 "테스트가 경계를 지켜준다"는 명제는 사람이 테스트를 짤 때의 이야기다. AI가 테스트까지 짤 수 있게 되는 순간, 테스트는 더 이상 절대적인 경계선이 아니다.
즉, 회색지대는 아직 회색이 아니라 옅은 빨강에 더 가깝다. 안 봐도 되는 영역이 아니라, 덜 봐도 되는 영역이라고 생각하는 게 정직할 것 같습니다.

그럼 어떻게 개선할 수 있을까

이 의문에 대해 제가 지금 가지고 있는 가설은 아직 정답이 아닙니다. 가능성으로만 적어 둡니다.

테스트 코드 자체를 변경 보호 영역으로 둔다. AI에게 구현은 자유롭게 맡기되, 테스트 파일에는 AI가 손대지 못하게 하거나 변경 시 사람의 명시적 승인을 거치도록 하는 방식.
테스트는 사람이 먼저 쓰고, 구현만 AI에게 맡긴다. 강연에서도 TDD를 강조하지만, "AI에게 TDD를 시키는 것"과 "AI에게 TDD의 통과만 시키는 것"은 다릅니다. 후자가 더 안전해 보입니다.
테스트 변경에 대한 diff 리뷰를 의식적으로 한다. 구현 diff보다 테스트 diff를 더 의심하는 습관. 테스트가 "느슨해지는 방향"으로 바뀌었다면 일단 멈춘다.
회색 지대의 크기를 도메인 위험도에 따라 다르게 가져간다. 결제·정산처럼 한 번 틀리면 회복이 어려운 도메인에서는 회색 지대를 좁게 두고, 부수적 기능은 넓게 두는 식.

이 부분은 더 실험해 볼 영역입니다. 제 결제 도메인 코드에 직접 적용해 보고 다음 글에서 다시 정리해 볼 생각입니다.

한계와 남은 의문

유비쿼터스 언어를 마크다운으로 정리해두는 게 효과적이라는 건 알겠는데, 레거시 코드베이스에서는 어디서부터 시작해야 할까 용어 자체가 일관되지 않은 환경에서는 정리 자체가 첫 번째 큰 작업이 될 것 같습니다.
도메인 용어 사전이 코드 변경에 따라 어떻게 함께 진화하는지도 풀어야 할 문제입니다. 사전이 낡으면 오히려 AI를 잘못된 방향으로 끌고 갈 위험이 있습니다.
위에서 말한 테스트 우회 문제는 제 한 번의 경험일 뿐, 일반화하기엔 표본이 부족합니다. 모델·프롬프트·태스크 종류에 따라 빈도가 어떻게 달라지는지 더 봐야 합니다.
다음 글에서는, 실제 결제 도메인에 작은 도메인 용어 사전을 만들고 + 테스트 보호 규칙을 적용해서 결과가 어떻게 달라지는지 정리해볼 생각입니다.

마무리

영상을 보고 가장 강하게 남은 한 줄은 이겁니다.

AI에게 같은 언어로 말하지 않으면, 더 자세히 말할수록 더 어긋난다.

저는 그동안 AI에게 설명을 했지, 언어를 공유하지 않았습니다. 다음 작업부터는 코드베이스에 작은 도메인 용어 파일부터 만들어두고 시작해보려고 합니다.

다만 강연이 제시한 모든 처방을 그대로 받아들이지는 않으려고 합니다. 특히 "테스트로 경계를 만들고 안쪽은 신경 쓰지 않는다"는 회색지대 발상은, 테스트를 짜는 주체도 AI가 될 수 있는 시대에는 한 번 더 의심해봐야 한다는 게 지금까지의 제 결론입니다.

참고

강연 영상: Software Fundamentals in the Age of AI — Matt Pocock
John Ousterhout, A Philosophy of Software Design
Andy Hunt & Dave Thomas, The Pragmatic Programmer
Frederick P. Brooks, The Design of Design
Eric Evans, Domain-Driven Design

맥북에서 집 컴퓨터에 데이터 저장하는 법 (윈도우 PC를 NAS로)

Parse — Mon, 4 May 2026 07:00:03 +0900

목적

AI 작업으로 24시간 켜두는 윈도우 PC + 4TB HDD 활용
사진/영상 원본을 맥북에서 NAS로 분리 → 맥북 용량 확보
같은 와이파이뿐 아니라 외부에서도 접근 가능하게

️ 최종 구조

[맥북] ──── 와이파이 SMB ───→ [윈도우 PC + 4TB]
   │                              ↑
   └──── Tailscale SMB ───────────┘
         (외부에서도 접근)

⚙️ 셋업 절차

1. 윈도우: NAS 전용 사용자 계정 생성

설정 → 계정 → 다른 사용자 → 계정 추가

Microsoft 계정 없이 로컬 계정으로 생성
사용자명: nas (예시)

2. 윈도우: 공유 폴더 설정

폴더 우클릭 → 속성 → 공유 탭 → 고급 공유

이 폴더 공유 체크
공유 이름 지정 (예: NAS_Share)
권한 → Everyone 제거 → nas 계정 추가 → 모든 권한

보안 탭 (NTFS 권한, 둘 다 통과해야 접근됨)

편집 → nas 계정 추가 → 수정 권한

3. 윈도우: 네트워크 검색 활성화

설정 → 네트워크 → 고급 공유 설정

개인 네트워크: 네트워크 검색 ✅, 파일/프린터 공유 ✅
모든 네트워크: 암호 보호 공유 ✅

4. 맥: SMB 접속

Finder → Cmd + K

smb://[윈도우 IP]/NAS_Share

키체인 저장 체크해두면 다음부터 자동 인증

5. 외부 접속용: Tailscale 설정

윈도우, 맥 양쪽에 Tailscale 설치 (같은 계정)
윈도우 Tailscale IP 확인 (트레이 아이콘 → Copy address)
맥에서 smb://[Tailscale IP]/NAS_Share 로 접속

헤맸던 지점들

문제 1: WSL에서 `ipconfig` 안 됨

원인: WSL은 리눅스 환경이라 윈도우 명령어 직접 인식 X

해결:

ipconfig.exe   # WSL에서 윈도우 실행파일 호출

또는 그냥 PowerShell/cmd에서 ipconfig
WSL2의 hostname -I로 나오는 IP는 가상 네트워크 IP라 NAS 접속용으론 ❌

문제 2: SMB 접속 시도가 SSH 에러로 떨어짐

증상:

kex_exchange_identification: read: Connection reset by peer

원인: ssh 명령어로 시도함. SMB는 ssh가 아니라 별도 프로토콜

SSH: 포트 22 (원격 셸)
SMB: 포트 445 (파일 공유)

해결: Finder Cmd+K로 smb://... 형태로 접속

문제 3 ⭐: 로컬 SMB는 되는데 Tailscale SMB만 안 됨

증상: 같은 와이파이 IP(192.168.x.x)로는 접속 OK, Tailscale IP(100.x.x.x)로는 실패

원인: 윈도우 방화벽이 인터페이스마다 다른 규칙 적용

와이파이 인터페이스 → 개인 네트워크 → SMB 허용
Tailscale 인터페이스 → 공용 네트워크 → SMB 차단

해결: PowerShell 관리자 권한에서

# 현재 상태 확인
Get-NetConnectionProfile

# Tailscale을 Private으로 변경
Set-NetConnectionProfile -InterfaceAlias "Tailscale" -NetworkCategory Private

InterfaceAlias 이름은 환경마다 다름 (Tailscale, tailscale0 등)
Get-NetConnectionProfile 결과에 나온 그대로 입력

진단용 명령어 (맥에서)

# 연결 자체 확인
ping [윈도우 IP]

# SMB 포트(445) 열렸는지 확인
nc -zv [윈도우 IP] 445

succeeded → 포트 OK, 인증 문제일 가능성
Connection refused/타임아웃 → 방화벽 또는 SMB 서비스 문제

자주 쓰는 명령어 모음

맥에서 SMB 접속

GUI: Finder → Cmd + K

터미널 마운트:

mkdir -p ~/nas
mount_smbfs //nas@[윈도우 IP]/NAS_Share ~/nas

# 언마운트
umount ~/nas

자주 쓰는 IP:

와이파이(집): smb://192.168.x.x/NAS_Share
Tailscale(외부): smb://100.x.x.x/NAS_Share

맥 메타데이터 파일 안 만들게 하기

defaults write com.apple.desktopservices DSDontWriteNetworkStores true

윈도우에서 IP 확인

# PowerShell/cmd
ipconfig

# WSL에서
ipconfig.exe

# Tailscale IP만
tailscale ip -4

윈도우 방화벽 / 네트워크 프로필

# 현재 네트워크 프로필 확인
Get-NetConnectionProfile

# 특정 인터페이스를 Private으로 변경 (관리자 권한 필요)
Set-NetConnectionProfile -InterfaceAlias "Tailscale" -NetworkCategory Private

윈도우 SMB 서비스 상태 확인 (문제 생겼을 때)

# SMB 서버 서비스 상태
Get-Service -Name LanmanServer

# 재시작 (관리자 권한)
Restart-Service -Name LanmanServer -Force

알아둘 것

로컬 SMB가 항상 더 빠름: 같은 와이파이에선 1Gbps 풀 활용, Tailscale은 외부 라우팅이라 느림
Tailscale IP는 고정: 100.x.x.x 대역, 재부팅해도 안 바뀜
로컬 IP는 바뀔 수 있음: 공유기에서 고정 IP 예약 필수
3-2-1 백업 원칙: 사본 3개 / 매체 2종류 / 1개는 분리 보관

참고

Tailscale 관리 콘솔: https://login.tailscale.com/admin/machines
관련 노트: [[MCP]], [[Obsidian]]

터미널 마운트 트러블슈팅

인증 에러: `Authentication error`

원인: 윈도우 로컬 계정 SMB 인증 시 사용자명만 쓰면 거부될 수 있음

해결: 호스트명;사용자명 형식으로 입력 (백슬래시 대신 세미콜론)

mount_smbfs //'[사용자계정]'@[윈도우_IP]/storage ~/NAS

⚠️ 작은따옴표로 감싸기 필수 (세미콜론이 셸에서 명령 구분자로 해석되는 것 방지)

`File exists` 에러

원인: 마운트 포인트에 이미 마운트되어 있거나, 이전 마운트 흔적이 남음

해결 순서:

# 1. 현재 마운트 상태 확인
mount | grep smb

# 2. 좀비 마운트 모두 해제
mount | grep smb | awk '{print $3}' | xargs -I {} sudo umount "{}"

# 3. /Volumes 좀비 폴더 정리 (storage-1, storage-2 등 숫자 붙은 것)
ls /Volumes/
sudo rm -rf /Volumes/storage*

# 4. 마운트 포인트 재생성
rmdir ~/NAS
mkdir -p ~/NAS

# 5. 다시 마운트
mount_smbfs //'[사용자계정]'@[윈도우_IP]/storage ~/NAS

사이드바에 깨진 항목이 안 사라짐

증상: 이젝트했는데도 사이드바에 끈적하게 남거나, 클릭하면 "원본 항목을 찾을 수 없습니다" 에러

원인: Finder 사이드바 캐시 (plist)

해결 순서 (위에서부터 시도):

# 1. Finder 재시작 (대부분 이걸로 해결)
killall Finder

# 2. 그래도 남으면 — 서버 즐겨찾기 캐시 직접 삭제
rm ~/Library/Application\ Support/com.apple.sharedfilelist/com.apple.LSSharedFileList.FavoriteServers.sfl*
rm ~/Library/Application\ Support/com.apple.sharedfilelist/com.apple.LSSharedFileList.RecentServers.sfl*
killall Finder

GUI로도 정리: Finder → Cmd + K → 즐겨찾는 서버 목록에서 깨진 항목 선택 → - 버튼

마운트 폴더명 = Finder 사이드바 표시명

mount_smbfs //... ~/storage → 사이드바에 storage로 표시됨
mount_smbfs //... ~/NAS → 사이드바에 NAS로 표시됨
윈도우 공유 이름은 그대로 storage여도 OK, 맥에서 폴더명만 바꾸면 표시명이 바뀜

자동 마운트 스크립트

~/mount-nas.sh 작성:

#!/bin/bash
MOUNT_POINT="$HOME/NAS"
WIN_IP="[윈도우_IP]"      # 실제 IP로 변경
SHARE_NAME="storage"
USERNAME="[사용자계정]"

# 이미 마운트되어 있으면 종료
if mount | grep -q "$MOUNT_POINT"; then
    echo "이미 마운트되어 있음"
    exit 0
fi

mkdir -p "$MOUNT_POINT"
mount_smbfs "//${USERNAME}@${WIN_IP}/${SHARE_NAME}" "$MOUNT_POINT"

if [ $? -eq 0 ]; then
    echo "✅ NAS 마운트 성공: $MOUNT_POINT"
else
    echo "❌ 마운트 실패"
fi

실행 권한:

chmod +x ~/mount-nas.sh

사용:

~/mount-nas.sh

부팅 시 자동 마운트 (AppleScript 방식)

스크립트 편집기 열기

입력:

mount volume "smb://[윈도우_IP]/storage"

파일 → 내보내기 → 파일 형식 응용 프로그램으로 저장 (예: MountNAS.app)
시스템 설정 → 일반 → 로그인 항목 → + → MountNAS.app 추가

키체인에 자격증명 저장되어 있으면 묻지도 않고 자동 마운트됨.

보안 고려사항

Tailscale IP가 사이드바에 노출되는 게 신경쓰일 때

/Volumes/로 마운트하지 말고 ~/NAS로 마운트 → 사이드바에 IP 안 뜸
깔끔한 마운트 후 Finder에서 ~/NAS 폴더를 사이드바로 드래그하면 즐겨찾기에 NAS로 등록됨

노출 위험 정도

Tailscale IP (100.x.x.x): 본인 Tailnet 안에서만 의미 있음. 외부 노출돼도 직접 접근 불가
로컬 IP (192.168.x.x): 사설 IP, 인터넷에서 접근 자체 불가
진짜 위험한 건 공인 IP나 포트포워딩 — 안 했으니 OK

개인정보처리방침

Parse — Mon, 4 May 2026 00:18:32 +0900

개인정보 처리방침

본 블로그(return new Story();, 이하 "사이트")는 다음과 같이 개인정보를 처리합니다.

1. 광고 및 쿠키

본 사이트는 Google AdSense 를 통해 광고를 노출합니다. Google 및 협력 업체는 쿠키(cookies)를 사용하여 이용자의 방문 정보를 기반으로 맞춤형 광고를 제공할 수 있습니다.

방문자는 Google 광고 설정에서 맞춤형 광고를 끄거나 변경할 수 있으며, aboutads.info에서 일부 협력업체의 쿠키 사용을 옵트아웃할 수 있습니다.

2. 댓글 작성 시 수집 정보

비회원이 댓글을 작성하는 경우 닉네임 / 비밀번호 / 이메일(선택) 이 수집될 수 있습니다.

이 정보는 Tistory(주식회사 카카오)가 처리하며, 자세한 내용은 Tistory 개인정보 처리방침을 따릅니다.

3. 문의

개인정보 관련 문의는 본 블로그 방명록 또는 댓글로 남겨주시기 바랍니다.

본 처리방침은 2026-05-04 부터 적용됩니다.

맥북 아이폰 복사 붙여넣기 안 될 때 해결방법

Parse — Mon, 30 Mar 2026 20:08:32 +0900

맥↔아이폰 복사 붙여넣기 안 될 때 터미널 명령어 한 줄로 해결 (Universal Clipboard)

Handoff 켜져 있고, Wi-Fi·Bluetooth 정상인데도 맥-아이폰 간 복붙이 안 된다면 이 글이 답입니다.

증상

맥에서 복사한 텍스트가 아이폰에서 붙여넣기 안 됨
아이폰에서 복사한 내용이 맥에서 안 나옴
같은 Apple ID, 같은 Wi-Fi, Bluetooth ON, Handoff ON — 전부 정상인데 안 됨
"유니버설 클립보드" 자체가 죽어 있는 느낌

구글링하면 다 똑같은 해결법만 나옵니다. 저도 전부 따라해봤습니다.

심지어 AI한테 물었는데도 같은 답변만 반복합니다.

구글링해서 나오는 방법, 다 해봤습니다

1. Handoff 껐다 켜기

맥: 시스템 설정 → 일반 → AirDrop 및 Handoff → Handoff 끄고 → 10초 기다렸다가 → 다시 켜기

아이폰: 설정 → 일반 → AirPlay 및 Handoff → 똑같이 껐다 켜기

→ ❌ 안 됨

2. Bluetooth 껐다 켜기

양쪽 기기 Bluetooth 끄고 → 30초 기다렸다가 → 다시 켜기

→ ❌ 안 됨

3. Wi-Fi 껐다 켜기

혹시 Wi-Fi 문제인가 싶어서 양쪽 다 껐다 켜봄

→ ❌ 안 됨

4. iCloud 로그아웃 후 재로그인

맥에서 Apple ID 로그아웃하고 다시 로그인. 아이폰도 마찬가지.

→ ❌ 시간만 오래 걸리고 안 됨

5. 양쪽 기기 재부팅

맥 재시작, 아이폰 전원 껐다 켜기

→ ❌ 안 됨

여기까지 하면 보통 "아 그냥 에어드롭 쓰자..." 하고 포기하게 됩니다.

근데 터미널 명령어 2줄로 해결됐습니다.

진짜 해결법: 터미널 명령어 2줄

맥에서 터미널(Terminal.app)을 열고 아래 두 줄을 순서대로 실행합니다.

defaults delete ~/Library/Preferences/com.apple.coreservices.useractivityd.plist ClipboardSharingEnabled

defaults write ~/Library/Preferences/com.apple.coreservices.useractivityd.plist ClipboardSharingEnabled 1

끝입니다. 재시작 없이 바로 적용됩니다.

실행 후 맥에서 아무 텍스트나 복사(⌘+C)하고 아이폰에서 붙여넣기 해보세요.

이게 왜 되는 건가요?

useractivityd는 macOS에서 Handoff, Universal Clipboard 등을 담당하는 백그라운드 데몬(daemon)입니다.

이 데몬이 참조하는 plist(설정 파일)에 ClipboardSharingEnabled 값이 있는데, macOS 업데이트나 설정 충돌 등으로 이 값이 꼬이는 경우가 있습니다.

명령어 하는 일

defaults delete ... ClipboardSharingEnabled	기존의 꼬인 설정값을 삭제
defaults write ... ClipboardSharingEnabled 1	클립보드 공유를 활성화(1)로 새로 설정

시스템 설정 UI에서는 Handoff가 "켜짐"으로 보여도, 이 plist 값은 별도로 관리되기 때문에 UI상으로는 확인이 안 됩니다.

그래도 안 된다면 — 기본 체크리스트

위 명령어로 해결 안 되는 경우, 기본 조건이 안 맞는 건 아닌지 확인해보세요.

1. 같은 Apple ID인지 확인

맥: 시스템 설정 → Apple ID
아이폰: 설정 → 맨 위 프로필

2. Handoff 켜져 있는지 확인

맥: 시스템 설정 → 일반 → AirDrop 및 Handoff
아이폰: 설정 → 일반 → AirPlay 및 Handoff

3. Wi-Fi & Bluetooth 둘 다 ON

유니버설 클립보드는 Bluetooth로 기기를 인식하고, Wi-Fi로 데이터를 전송합니다
두 기기가 물리적으로 가까이 있어야 합니다

4. 양쪽 재부팅

단순하지만 효과적입니다

테스트 환경

macOS 26.3.1
iPhone (최신 iOS)
동일 iCloud 계정, 동일 Wi-Fi

마무리

"분명히 다 켜져 있는데 왜 안 되지?"라는 상황이라면, 십중팔구 useractivityd의 plist 설정이 꼬인 겁니다.

터미널 명령어 2줄이면 해결되니 한번 시도해보세요.

SSE | 실시간 결제 알림 시스템 개발기 (3) - SSE와 LoggingFilter 충돌 해결기

Parse — Sun, 18 Jan 2026 10:30:51 +0900

들어가며

이전 글에서는 로드밸런싱 환경에서의 문제를 Redis Pub/Sub으로 해결한 과정을 다뤘습니다. 기술적으로는 완성된 것처럼 보였지만, 실제 배포 전 테스트 환경에서 예상치 못한 문제가 발생했습니다.

SSE 연결은 성공하는데, 거래 알림이 제대로 전달되지 않거나 연결이 비정상적으로 종료되는 현상이었습니다. 로그를 확인해보니 사내에서 공통으로 사용하는 LoggingFilter가 원인이었습니다.

이번 글에서는 SSE와 LoggingFilter의 충돌 원인, 해결 과정, 그리고 그 과정에서의 기술적 고민을 공유합니다.

문제 발견

증상

테스트 환경에 배포 후 다음과 같은 문제들이 발생했습니다:

1. SSE 연결은 성공하지만 메시지가 전달되지 않음
2. 연결이 예상보다 빨리 종료됨
3. 간헐적으로 500 에러 발생

원인 분석

문제의 원인은 사내 공통 라이브러리의 LoggingFilter였습니다.

일반적인 HTTP 요청-응답 사이클은 이렇습니다:

Request → Filter → Controller → Response → Filter → Client
           ↑_____ 여기서 로깅 _____↑

LoggingFilter는 요청과 응답을 가로채서 로그를 남기는데, 이 과정에서:

Request body를 읽어서 로깅
Response body를 읽어서 로깅
연결 종료

그런데 SSE는 다릅니다:

Request → Filter → Controller → [Connection Held Open]
                                        ↓
                                   [Streaming...]
                                        ↓
                                   [Event 1, 2, 3...]
                                        ↓
                                   [Still Open...]

SSE는 연결을 계속 유지하면서 스트리밍 방식으로 데이터를 전송합니다. 하지만 LoggingFilter는:

Response를 즉시 읽으려고 시도 → SSE는 아직 데이터를 보내지 않았음
Connection을 빨리 종료 → SSE 스트림이 끊김
Buffering 시도 → 메모리 문제 발생 가능

해결 방안 검토

사내 공통 라이브러리는 여러 프로젝트에서 사용 중이므로 직접 수정할 수 없었습니다. 그래서 우회 방법을 찾아야 했습니다.

시도 1: URL 패턴 제외 (실패)

처음에는 Filter 등록 시 URL 패턴으로 제외하려고 했습니다.

java

@Bean
public FilterRegistrationBean<LoggingFilter> loggingFilter() {
    FilterRegistrationBean<LoggingFilter> registration = 
        new FilterRegistrationBean<>();
    
    registration.setFilter(loggingFilter);
    registration.addUrlPatterns("/*");
    // SSE 경로 제외 시도
    registration.addInitParameter("excludePattern", "/api/notifications/subscribe/*");
    
    return registration;
}

문제점: 사내 라이브러리의 LoggingFilter가 이미 @Component로 자동 등록되어 있었고, 제외 패턴 기능을 지원하지 않았습니다.

시도 2: Filter Order 조정 (부분적 성공)

SSE 요청만 먼저 처리하는 Filter를 추가했습니다.

java

@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class SseBypassFilter extends OncePerRequestFilter {
    
    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                   HttpServletResponse response,
                                   FilterChain filterChain) {
        String uri = request.getRequestURI();
        
        if (uri.contains("/subscribe")) {
            request.setAttribute("SKIP_LOGGING", true);
        }
        
        filterChain.doFilter(request, response);
    }
}

문제점: LoggingFilter가 SKIP_LOGGING 플래그를 체크하지 않았습니다. 사내 라이브러리를 수정할 수 없으므로 이 방법도 실패했습니다.

최종 해결: @Primary로 Bean 재정의

결국 @Primary 어노테이션을 사용하여 LoggingFilter를 재정의하는 방식으로 해결했습니다.

구현

LoggingFilter 래핑

java

@Configuration
public class FilterConfig {
    
    @Primary
    @Bean
    public OncePerRequestFilter customLoggingFilter(
            @Qualifier("loggingFilter") OncePerRequestFilter originalFilter) {
        
        return new OncePerRequestFilter() {
            
            @Override
            protected void doFilterInternal(
                    HttpServletRequest request,
                    HttpServletResponse response,
                    FilterChain filterChain) throws ServletException, IOException {
                
                // SSE 요청인지 확인
                if (isSseRequest(request)) {
                    // SSE는 원본 필터를 거치지 않고 바로 통과
                    filterChain.doFilter(request, response);
                    return;
                }
                
                // 일반 요청은 원본 로깅 필터 실행
                originalFilter.doFilter(request, response, filterChain);
            }
            
            private boolean isSseRequest(HttpServletRequest request) {
                String uri = request.getRequestURI();
                String accept = request.getHeader("Accept");
                
                // URL 패턴으로 확인
                if (uri.contains("/api/notifications/subscribe")) {
                    return true;
                }
                
                // Accept 헤더로 확인
                if (accept != null && accept.contains("text/event-stream")) {
                    return true;
                }
                
                return false;
            }
        };
    }
}

동작 원리

@Primary 어노테이션은 같은 타입의 Bean이 여러 개 있을 때 우선순위를 지정합니다.

[Before]
Application → LoggingFilter (사내 라이브러리) → Controller

[After]  
Application → CustomLoggingFilter (@Primary) → Controller
                      ↓
              SSE 요청? 
                ↙        ↘
             Yes          No
              ↓            ↓
          바로 통과    원본 Filter 실행

이 방식의 장점:

사내 라이브러리 코드 수정 불필요
기존 로깅 기능 유지 (일반 요청은 그대로)
SSE만 선택적으로 우회 가능

더 나은 대안은 없었을까?

프로젝트를 완료한 후, 더 나은 해결 방법은 없었는지 고민해봤습니다.

사내 라이브러리 팀에 개선 요청

가장 근본적인 해결책입니다.

java

// 사내 라이브러리에 추가 요청할 기능
@Component
public class LoggingFilter extends OncePerRequestFilter {
    
    @Value("${logging.filter.exclude-patterns:}")
    private String[] excludePatterns;
    
    @Override
    protected void doFilterInternal(...) {
        if (shouldSkip(request)) {
            filterChain.doFilter(request, response);
            return;
        }
        // 로깅 로직...
    }
    
    private boolean shouldSkip(HttpServletRequest request) {
        String uri = request.getRequestURI();
        
        for (String pattern : excludePatterns) {
            if (uri.matches(pattern)) {
                return true;
            }
        }
        
        return false;
    }
}

그러면 설정 파일에서 간단하게 제외할 수 있습니다:

yaml

logging:
  filter:
    exclude-patterns:
      - "/api/notifications/subscribe/.*"
      - "/api/streaming/.*"

장점:

모든 프로젝트에서 활용 가능
깔끔한 설정 기반 제어
유지보수성 향상

단점:

라이브러리 팀의 승인 및 배포 시간 필요
다른 팀의 일정에 의존

실무에서의 트레이드오프

우리가 선택한 이유

결국 @Primary 방식을 선택한 이유는:

시간 제약: 프로젝트 일정이 촉박했음
최소 영향: 기존 시스템에 영향 없이 빠르게 해결
실용성: 완벽하지 않지만 요구사항은 충족

기술 부채 관리

하지만 이 방식은 기술 부채를 남깁니다:

문제점:

사내 라이브러리 업데이트 시 동작 보장 안 됨
다른 개발자가 원본 Filter가 동작한다고 착각 가능
암묵적인 오버라이드로 디버깅 어려움

대응 방안:

코드 리뷰와 문서에 명확히 기록하고, 백로그에 개선 작업을 등록했습니다.

배운 점

1. 레거시 시스템과의 통합

모든 프로젝트가 그린필드는 아닙니다. 기존 시스템, 공통 라이브러리와의 충돌은 실무에서 흔한 일입니다.

완벽한 해결책을 고집하기보다, 현실적인 제약 속에서 최선의 선택을 하는 것이 중요합니다.

2. 문서화의 중요성

임시 해결책일수록 명확한 문서화가 필수입니다:

왜 이렇게 구현했는지
어떤 제약사항이 있었는지
향후 개선 방향은 무엇인지

6개월 후 다른 개발자(혹은 미래의 나)가 코드를 볼 때를 대비해야 합니다.

3. 기술 부채 관리

기술 부채는 나쁜 것이 아닙니다. 중요한 것은:

부채를 인지하고 있는가
부채를 관리하고 있는가
적절한 시점에 상환 계획이 있는가

우리는 백로그에 개선 작업을 등록하고, 사내 라이브러리 팀에 feature request를 제출했습니다.

마치며

실시간 결제 알림 시스템을 구축하면서 많은 것을 배웠습니다:

SSE vs WebSocket: 요구사항에 맞는 기술 선택의 중요성
분산 환경: 단일 서버와는 다른 고민과 해결책
레거시 통합: 현실적 제약 속에서의 의사결정
기술 부채: 인지하고 관리하는 자세

완벽한 시스템은 없습니다. 중요한 것은 비즈니스 요구사항을 만족시키면서, 기술적 품질과 현실적 제약 사이의 균형을 찾는 것입니다.

이 시리즈가 실시간 통신 시스템을 구축하거나, 분산 환경에서의 문제를 해결하는 분들에게 도움이 되길 바랍니다.

후속 개선 계획

프로젝트는 완료되었지만, 개선할 부분들이 남아있습니다:

SSE 재연결 처리: Last-Event-ID를 활용한 메시지 재전송
Circuit Breaker 패턴: Redis 장애 시 자동 복구
사내 라이브러리 개선: 공통 LoggingFilter에 exclude 기능 추가
성능 최적화: 대규모 동시 접속 시 메모리 사용량 개선

기술 부채를 인지하고 있으며, 우선순위에 따라 하나씩 개선해 나갈 예정입니다.

SSE | 실시간 결제 알림 시스템 개발기 (2) - 로드밸런싱 환경에서의 문제와 Redis Pub/Sub 해결

Parse — Sat, 17 Jan 2026 10:00:01 +0900

시작하며

이전 글에서는 SSE를 선택한 이유와 기본 구현 방법을 다뤘습니다. 단일 서버 환경에서는 모든 것이 완벽하게 동작했지만, 실제 운영 환경은 달랐습니다. 로드밸런서 뒤에 여러 서버 인스턴스가 배포된 환경에서 예상치 못한 문제가 발생했습니다.

이번 글에서는 분산 환경에서 마주한 문제와 Redis Pub/Sub을 활용한 해결 과정을 공유합니다.

로드밸런싱(다중서버) 환경에서 발견한 문제

문제 상황

운영 환경은 다음과 같은 구조였습니다:

              [Load Balancer]
                    |
        +-----------+-----------+
        |                       |
   [Server A]            [Server B]
        |                       |
        +----------+------------+
                   |
            [RabbitMQ]

두 대의 서버가 로드밸런서 뒤에서 동작하고, 하나의 RabbitMQ 인스턴스를 공유하는 구조였습니다.

문제는 이렇게 발생했습니다:

가맹점주가 Server A에 SSE로 연결됨
고객이 결제를 완료
RabbitMQ에 거래 메시지가 발행됨
Server B의 리스너가 메시지를 소비
Server B는 자신에게 연결된 클라이언트를 찾지만, 가맹점주는 Server A에 연결되어 있음
가맹점주는 거래 알림을 받지 못함

왜 이런 일이?

RabbitMQ의 기본 동작 방식 때문입니다. 여러 컨슈머가 같은 큐를 구독하면 라운드로빈 방식으로 메시지를 분배합니다. 즉, 메시지가 Server A와 Server B에 번갈아가며 전달되는데, 클라이언트가 어느 서버에 연결되어 있는지는 고려하지 않습니다.

거래 1: RabbitMQ → Server A (가맹점주는 Server B 연결) ❌
거래 2: RabbitMQ → Server B (가맹점주는 Server B 연결) ✅
거래 3: RabbitMQ → Server A (가맹점주는 Server B 연결) ❌

결과적으로 거래의 절반 정도만 가맹점주에게 전달되는 심각한 문제였습니다.

해결 방안 검토

이 문제를 해결하기 위해 여러 방안을 고민했습니다.

1. Sticky Session (검토 후 제외)

로드밸런서에서 특정 클라이언트를 항상 같은 서버로 라우팅하는 방식입니다.

문제점:

해당 서버가 재시작되면 모든 연결이 끊김
서버 간 부하 분산이 불균형해질 수 있음
RabbitMQ 메시지가 여전히 라운드로빈으로 분배됨

2. RabbitMQ Fanout Exchange (검토 후 제외)

모든 서버에 메시지를 브로드캐스트하는 방식입니다.

문제점:

각 서버가 별도의 큐를 가져야 함
기존에 있던 Exchange를 활용하는 것을 목표로 함
메시지가 중복 처리될 수 있음
RabbitMQ 구조를 변경해야 함 (기존 시스템과의 호환성)

3. Redis Pub/Sub (채택!)

RabbitMQ에서 받은 메시지를 Redis Pub/Sub으로 재전송하여 모든 서버에 브로드캐스트하는 방식입니다.

장점:

기존 RabbitMQ 구조 변경 불필요
모든 서버가 메시지를 받을 수 있음
Redis는 이미 캐시용으로 사용 중이었음
구현이 비교적 간단함

Redis Pub/Sub 구현

아키텍처 변경

[고객 결제]
     ↓
[결제 시스템]
     ↓
[RabbitMQ Queue]
     ↓
[Server A or B가 메시지 수신]
     ↓
[Redis Pub/Sub으로 재전송] ← 핵심 변경점
     ↓
[모든 서버가 Subscribe하여 수신]
     ↓
[각 서버가 자신의 SSE 클라이언트에게 전달]

이제 RabbitMQ에서 어느 서버가 메시지를 받든, Redis Pub/Sub을 통해 모든 서버에 전달됩니다.

Redis 설정

java

@Configuration
public class RedisConfig {
    
    @Bean
    public RedisMessageListenerContainer redisMessageListenerContainer(
            RedisConnectionFactory connectionFactory,
            MessageListenerAdapter listenerAdapter) {
        
        RedisMessageListenerContainer container = new RedisMessageListenerContainer();
        container.setConnectionFactory(connectionFactory);
        container.addMessageListener(listenerAdapter, 
            new PatternTopic("transaction.*"));
        
        return container;
    }
    
    @Bean
    public MessageListenerAdapter listenerAdapter(
            RedisSubscriber subscriber) {
        return new MessageListenerAdapter(subscriber, "onMessage");
    }
    
    @Bean
    public RedisTemplate<String, Object> redisTemplate(
            RedisConnectionFactory connectionFactory) {
        
        RedisTemplate<String, Object> template = new RedisTemplate<>();
        template.setConnectionFactory(connectionFactory);
        template.setKeySerializer(new StringRedisSerializer());
        template.setValueSerializer(new Jackson2JsonRedisSerializer<>(Object.class));
        
        return template;
    }
}

RabbitMQ 리스너 수정

RabbitMQ에서 메시지를 받으면 Redis로 재전송하도록 수정했습니다.

java

@Component
public class TransactionQueueListener {
    
    private final RedisTemplate<String, Object> redisTemplate;
    
    @RabbitListener(queues = "transaction.queue")
    public void handleTransaction(TransactionMessage message) {
        // Redis Pub/Sub으로 브로드캐스트
        String channel = "transaction." + message.getMerchantId();
        redisTemplate.convertAndSend(channel, message);
        
        log.info("Published transaction to Redis: merchantId={}, txId={}", 
            message.getMerchantId(), message.getTransactionId());
    }
}

Redis Subscriber 구현

모든 서버는 Redis 채널을 구독하여 메시지를 수신합니다.

java

@Component
@Slf4j
public class RedisSubscriber {
    
    private final ObjectMapper objectMapper;
    private final TransactionNotificationService notificationService;
    
    public void onMessage(String message, String pattern) {
        try {
            TransactionMessage transaction = 
                objectMapper.readValue(message, TransactionMessage.class);
            
            String merchantId = transaction.getMerchantId();
            
            log.info("Received transaction from Redis: merchantId={}, txId={}", 
                merchantId, transaction.getTransactionId());
            
            // 해당 가맹점에 연결된 SSE 클라이언트에게 전송
            notificationService.sendToMerchant(merchantId, transaction);
            
        } catch (JsonProcessingException e) {
            log.error("Failed to parse transaction message", e);
        }
    }
}

ConcurrentHashMap으로 가맹점별 필터링

각 서버는 자신에게 연결된 클라이언트 정보만 ConcurrentHashMap에 저장하고 있습니다.

java

@Service
@Slf4j
public class TransactionNotificationService {
    
    // 가맹점 ID → SSE Emitter 리스트 매핑
    private final ConcurrentHashMap<String, List<SseEmitter>> emitters = 
        new ConcurrentHashMap<>();
    
    public void sendToMerchant(String merchantId, TransactionMessage message) {
        List<SseEmitter> merchantEmitters = emitters.get(merchantId);
        
        // 이 서버에 해당 가맹점이 연결되어 있지 않으면 무시
        if (merchantEmitters == null || merchantEmitters.isEmpty()) {
            log.debug("No emitters found for merchant: {}", merchantId);
            return;
        }
        
        log.info("Sending to {} emitters for merchant: {}", 
            merchantEmitters.size(), merchantId);
        
        List<SseEmitter> deadEmitters = new ArrayList<>();
        
        for (SseEmitter emitter : merchantEmitters) {
            try {
                emitter.send(SseEmitter.event()
                    .name("transaction")
                    .data(message));
                    
                log.debug("Successfully sent transaction to emitter");
                
            } catch (IOException e) {
                log.warn("Failed to send to emitter, marking as dead", e);
                deadEmitters.add(emitter);
            }
        }
        
        // 전송 실패한 emitter 제거
        deadEmitters.forEach(emitter -> removeEmitter(merchantId, emitter));
    }
    
    // subscribe, removeEmitter 메서드는 1편과 동일
}

테스트 및 검증

로컬 테스트

로드밸런서 없이 두 개의 서버 인스턴스를 직접 실행하여 테스트했습니다:

bash

# Server 1
java -jar merchantApp.jar --server.port=8081

# Server 2
java -jar merchantApp.jar --server.port=8082

그리고 각 포트로 번갈아가며 SSE를 연결한 뒤, RabbitMQ에 메시지를 발행하여 모든 경우에 정상 동작하는지 확인했습니다.

결과는 성공적이었습니다. Redis Pub/Sub의 성능도 충분했고, 메시지 유실 없이 안정적으로 동작했습니다.

고려사항 및 트레이드오프

Redis Pub/Sub의 특징

장점:

매우 빠른 메시지 전달 (밀리초 단위)
간단한 구현
수평 확장 가능 (서버를 추가해도 동일하게 동작)

단점:

메시지 지속성 없음: Redis가 다운되면 메시지 유실 가능
구독자가 없으면 메시지 버려짐: 모든 서버가 다운된 상태에서 발행된 메시지는 사라짐

왜 이 트레이드오프를 수용했나?

거래내역 조회 기능 존재: 가맹점 포털에서 언제든지 거래내역을 조회할 수 있음
실시간 알림은 부가 기능: 실시간으로 못 받아도 조회하면 되므로 치명적이지 않음
사내 모니터링 알림: Redis 장애 시 즉시 감지하고 대응 가능
구현 복잡도 vs 비즈니스 가치: 완벽한 메시지 보장보다 빠른 출시가 우선

실무에서는 이런 비즈니스 요구사항과 기술적 완성도 사이의 균형을 찾는 것이 중요합니다.

마치며

로드밸런싱 환경에서의 실시간 통신은 단일 서버와 완전히 다른 접근이 필요합니다. 이번 프로젝트를 통해 분산 시스템의 특성과 메시지 브로드캐스팅의 중요성을 경험할 수 있었습니다.

Redis Pub/Sub은 완벽한 해결책은 아니지만, 우리 프로젝트의 요구사항과 제약사항을 고려했을 때 가장 실용적인 선택이었습니다.

하지만 구현 과정에서 또 다른 문제가 있었습니다. 사내에서 공통으로 사용하는 LoggingFilter가 SSE와 충돌하는 문제였죠.

다음 글에서는 LoggingFilter 충돌 문제와 그 해결 과정, 그리고 기술 부채에 대한 고민을 다루겠습니다.

return new Story();

회사에서 AI 에이전트 스킬 어떻게 관리할까? — skill-cli 개발 회고

배경 — 왜 만들었나

뭘 만들었나

핵심 구현

배운 것

마무리

Claude Code 워크플로우 (3) — Boris Cherny "Why Coding Is Solved" 강연 후기

시리즈 로드맵

TL;DR

영상을 보게 된 맥락 — Boris도 YC 출신이라니

강연의 골자 — 숫자로 보는 워크플로우

"loop"가 정확히 뭔가

"AI는 도구가 아니라 capacity다"

Plan Mode — Boris도 "계획 우선"

인쇄술 비유 — 가장 와닿았던 한 대목

"코딩이 solved 됐다"의 단서들

두 인사이트가 만나는 지점

한계와 남은 의문

핵심 정리

참고 자료

시리즈 마무리

Claude Code 워크플로우 (2) — gstack `/office-hours`로 AI에게 제품 인터뷰를 받아봤다

시리즈 로드맵

TL;DR

환경

/office-hours가 뭔가

인터뷰가 어떻게 진행되는가

강했던 질문 3개

1. "누군가가 이걸 정말 원한다는 가장 강한 근거는?"

2. "지금 이 문제를 어떻게 해결하고 있는가?"

3. "구체적으로 누가 이걸 가장 필요로 하는가?"

AI 인터뷰가 사람과 다른 점

첫째 — 답변하는 사람이 정리된다

둘째 — 결과물의 형식이 강하다

실제로 받은 과제

한계와 남은 의문

핵심 정리

참고 자료

다음 글

Claude Code 워크플로우 (1) — gstack + Superpowers 두 플러그인만 남긴 이유

시리즈 로드맵

TL;DR

환경

왜 두 개만 남았나

Claude Code의 초기 실패 패턴

두 플러그인의 역할 분담

gstack — 회의 & 품질 게이트

Superpowers — 실행 & 기록

실제 작업 순서 — 5단계

1단계 — /office-hours: "같이 생각해볼까"로 시작하기

2단계 — 문서화

3단계 — Brainstorming: 놓친 부분 검토

4단계 — Writing Plans: 설계 도면 만들기

5단계 — Git Worktrees + Sub-Agent Driven Development: 분업과 병렬

두 플러그인의 시너지

내가 정한 운영 규칙

한계와 남은 의문

핵심 정리

참고 자료

다음 글

AI와 개발할 때 자꾸 어긋나는 이유 — Matt Pocock 강연을 보고 다시 꺼낸 DDD

들어가며

"더 자세히 설명하면 되겠지"의 함정

DDD의 유비쿼터스 언어, AI에게 다시 적용되다

다시 내 경험으로

강연에서 같이 와닿았던 다른 포인트들

그런데 — 한 가지 의문: "회색지대" 처방은 정말 안전한가

그럼 어떻게 개선할 수 있을까

한계와 남은 의문

마무리

참고

맥북에서 집 컴퓨터에 데이터 저장하는 법 (윈도우 PC를 NAS로)

목적

️ 최종 구조

⚙️ 셋업 절차

1. 윈도우: NAS 전용 사용자 계정 생성

2. 윈도우: 공유 폴더 설정

3. 윈도우: 네트워크 검색 활성화

4. 맥: SMB 접속

`/office-hours`가 뭔가

1단계 — `/office-hours`: "같이 생각해볼까"로 시작하기

문제 1: WSL에서 `ipconfig` 안 됨

인증 에러: `Authentication error`

`File exists` 에러