흔한 컴공 출신 개발자

[postgres deep/shallow/wide dive] deep - vaccum과 autovacuum, vaccum full 1편 - vacuum과 dead tuple

Berno — Wed, 10 Dec 2025 14:27:07 +0900

postgres를 사용하다 보면 보이는 단어가 vaccum이다. 근데 이게 뭘 하는지 정확하게 잘 모르는 사람들이 있어서(보통 무지성 기술 선택의 결과로 postgres를 사용하거나 이미 잘 동작해서 알아볼 생각을 안해서) 정리를 해보려고 한다.(가끔 다른 RDBMS에 대한 비교나 삼천포로 빠질 확률 농후, 하지만 지식을 얻어갔죠?)

실은 이미 내 글 말고도
우아한형제들 기술블로그 와 같이 훌륭한 글들이 이미 있다.

내가 주로 참고할건 공식문서와 https://product.kyobobook.co.kr/detail/S000060603553 - postgresql 9.6 성능 이야기(광고아님. 광고였으면 좋겠음)
https://blog.ex-em.com/1667 - 우리나라에서 postgres관련 블로그 가히 원탑으로 저는 말합니다
기타 등등을 참고한다.

VACCUM?

우선 vaccum에 대한 공식 문서를 좀 봐보자.

VACUUM reclaims storage occupied by dead tuples. In normal PostgreSQL operation, tuples that are deleted or obsoleted by an update are not physically removed from their table; they remain present until a VACUUM is done. Therefore it's necessary to do VACUUM periodically, especially on frequently-updated tables.

처음부터 딱 핵심만 알려주는 너무 좋은 말이 나온다.
VACUUM을 사용해서 dead tuple이 차지한 공간을 회수한다. 일반적인 PostgreSQL이 동작하고 있는(운영되고 있는) 상황에서는 삭제되거나 업데이트 되어 더 이상 필요하지 않게 된 튜플이 '물리적으로' 제거 되지 않는다. VACUUM이 실행될때까지 남아있는다. 그래서 자주 업데이트 되는 테이블에서는 VACUUM을 특히 주기적으로 진행해야한다.

이러면 좀 궁금해진다. 왜 남아있지? 이건 이 시리즈에서 꼬리물기로 한번 다루어보겠다. 우선 하고자 하는 부분에 집중하자.

그 뒤에 글을 좀 더 읽어보면

Plain VACUUM (without FULL) simply reclaims space and makes it available for re-use. This form of the command can operate in parallel with normal reading and writing of the table, as an exclusive lock is not obtained. However, extra space is not returned to the operating system (in most cases); it's just kept available for re-use within the same table. It also allows us to leverage multiple CPUs in order to process indexes. This feature is known as parallel vacuum. To disable this feature, one can use PARALLEL option and specify parallel workers as zero. VACUUM FULL rewrites the entire contents of the table into a new disk file with no extra space, allowing unused space to be returned to the operating system. This form is much slower and requires an ACCESS EXCLUSIVE lock on each table while it is being processed.

Plain VACUUM(FULL 없이)은 단순히 공간을 회수해서 '재사용 가능'하게 만든다. 즉, 이 명령어는 기본적인 READ/WRITE와 병렬로 작동이 가능하다. 그러나 대부분의 케이스에서 추가 공간은 OS에 반환되지 않고 재사용 가능한 빈 공간으로 남아있다.

여기서 약간 단어적으로 혼동이 왔었는데 extra space라는건 VACUUM을 통해 재사용 가능하게 만들어진 공간(space)를 의미하고 있다.

만약 OS레벨에서, 새 디스크 파일로 재기록하여 사용되지 않는 공간을 반환하게 만들고 싶다면(물리적으로 하드디스크 용량을 확보하고 싶다면) VACUUM FULL을 사용하면 된다. 단, 이 작업은 각 테이블에 대해 ACCESS EXCLUSIVVE LOCK이 필요하다.(즉 병렬로 처리가 불가능하며 해당 작업을 하는 동안 해당 테이블에 접근을 못하니 함부로 돌리면 안된다는 뜻)

DEAD TUPLE?

어 근데 이제 슬슬 정말 의문을 해소할 순간이 왔다. 도대체 dead tuple은 왜 생기는가?
이걸 알기 위해 우리는 PostgreSQL의 MVCC에 대해 알아볼 필요가 있다.

우선 MVCC란 Multiversion Concurrency Control의 약자로 쉽게 말하면 DBMS상에서 여러 트랜잭션이 동시에 READ/WRITE를 해도 서로 간섭 없이 동작하도록 하는 동시성 제어 기법이다. PostgreSQL에서는 이 MVCC를 각 ROW에 대해 여러 버전(version = tuple)을 만드는 방식을 차용했다. 즉, 새로 row가 업데이트 된다면 없어지는게 아니라 tuple version update가 되는 것이다.

이미지 출처 : https://www.cs.cmu.edu/~pavlo/blog/2023/04/the-part-of-postgresql-we-hate-the-most.html

이제 우리는 하나의 row에 대해 여러 tuple이 생길 수 있다는 것을 알았다. 그러면 이제 이 tuple이 그 어디에서도 사용되지 않는 tuple이 생기게 되는데 이걸 dead tuple이라고 한다. 이 dead tuple은 자동으로 제거되지도 않고 회수되지도 않는다.(FSM에 대해서는 나중에 간략하게 정리해보도록 하자)

좋다. 이제 어느정도 VACUUM과 VACUUM FULL에 대해서 알았다. 그러면 AUTOVACUUM은 무엇인가?
GC가 있는 언어를 다루어보았다면 어느정도 heap space가 차거나 trigger되었을때 GC가 발생하는 것을 보았을 것이다. 비슷하게 trigger가 걸려 VACUUM이 자동 수행되는걸 AUTOVACUUM이라고 한다.(문제는 DB에서는 AUTOVACUUM 옵션을 꺼두어도 threshold를 넘어서면 강제로 DB에서 진행함)

2편에서 계속

velog에서 똑같은 글을 본다면 제 다른 블로그가 맞습니다.

[kotlin deep/shallow/wide dive] deep - suspend가 정확히 뭐고 CPS는 뭐고 state machine이 뭐죠는 꼬리에 꼬리를 물고(2)

Berno — Tue, 2 Dec 2025 16:01:41 +0900

1편 : https://velog.io/@bernoyoun/kotlin-deepshallowwide-dive-deep-suspend-1

그러면 이제 state machine이 뭔지를 좀 알아보자.

혹시 state pattern(상태 패턴)이라는걸 design pattern 공부할때 본 적이 있는 사람이 있을 수 있다. 그래도 우리 같이 복습하는 의미로 다시 봐보자.

https://refactoring.guru/design-patterns/state

기본적으로는 FSM(finite-state machine)에서 컨셉을 상당히 가져온 것 같다.
간단히 요약해보면

각 상태에 대해서는 유한한 개수(finite)하게 존재함
각 상태에 따라서 행동이 달라지며 미리 결정됨
현재 상태에서 다른 상태로 전환을 할 수 있고 안할 수 도 있음

이 state의 transition을 관리하기 위해 state-machine이란게 존재함. 문제는 무작정 만들기 시작하면 무수한 if-else or switch-case 난타로 고통받을 수 있음. 그럴때 이 state pattern을 도입하면 숨을 좀 고를 수 있음.

이제 state-machine을 좀 봐보자.
https://developer.mozilla.org/en-US/docs/Glossary/State_machine
결과적으로 여기도 같은 말을 하고 있다.

상태에 대한 관리, transition에 대한 관리를 한다.

이제 coroutine state machine을 이해해보자.

https://kotlinlang.org/spec/asynchronous-programming-with-coroutines.html#coroutine-state-machine

약간 어질어질한 내용이 나온다.

Kotlin implements suspendable functions as state machines, since such implementation does not require specific runtime support. This dictates the explicit suspend marking (function colouring) of Kotlin coroutines: the compiler has to know which function can potentially suspend, to turn it into a state machine.

state-machine에서 관리를 하는게 아니라 suspendable function을 state machine으로 구현하고 runtime에서 뭔가 특별히 support할 필요가 없다고 한다. 지금 내가 상당히 편협한 생각을 가지고 있는가 해서 여러가지 문서들을 좀 찾아봤다.
https://github.com/Kotlin/KEEP/blob/master/proposals/coroutines.md#state-machines

여기를 보면

It is crucial to implement coroutines efficiently, i.e. create as few classes and objects as possible. Many languages implement them through state machines and Kotlin does the same. In the case of Kotlin this approach results in the compiler creating only one class per suspending lambda that may have an arbitrary number of suspension points in its body.
Main idea: a suspending function is compiled to a state machine, where states correspond to suspension points. Example: let's take a suspending block with two suspension points:

이런 내용이 있다.
즉 이게 메인 아이디어라는 건데..

suspend 함수는 상태 머신으로 컴파일된다,
여기서 “상태(state)”는 각 suspension point를 의미한다.

이미 잘 정리된 글 처럼 보이지만 다시 하나 하나 정리를 해가면서 머리에 넣어보자.
예를 들어 아래와 같은 코드가 있다.

val a = a()
val y = foo(a).await() // suspension point #1
b()
val z = bar(a, y).await() // suspension point #2
c(z)

여기에는 3개의 상태가 존재한다:
1. 초기 상태 (아직 어떤 suspension도 발생하기 전)
2. 첫 번째 suspension point 이후
3. 두 번째 suspension point 이후
각 상태는 이 블록의 실행을 이어서 진행할 “continuation에 대한 진입점(entry point)”이다.

이후 컴파일 단계에서 위 코드는 '한 개의 anonymous class'로 컴파일된다.

class <anonymous_for_state_machine> extends SuspendLambda<...> {
    // The current state of the state machine
    int label = 0

    // local variables of the coroutine
    A a = null
    Y y = null

    void resumeWith(Object result) {
        if (label == 0) goto L0
        if (label == 1) goto L1
        if (label == 2) goto L2
        else throw IllegalStateException()

      L0:
        // result is expected to be `null` at this invocation
        a = a()
        label = 1
        result = foo(a).await(this) // 'this' is passed as a continuation 
        if (result == COROUTINE_SUSPENDED) return // return if await had suspended execution
      L1:
        // external code has resumed this coroutine passing the result of .await() 
        y = (Y) result
        b()
        label = 2
        result = bar(a, y).await(this) // 'this' is passed as a continuation
        if (result == COROUTINE_SUSPENDED) return // return if await had suspended execution
      L2:
        // external code has resumed this coroutine passing the result of .await()
        Z z = (Z) result
        c(z)
        label = -1 // No more steps are allowed
        return
    }          
}

컴파일이 된 anonymous class는 다음을 포함한다:
• 상태 머신을 구현하는 메서드
• 현재 상태를 저장하는 필드 (label)
• suspension 사이에 공유되는 지역 변수들을 저장하는 필드들
• (필요하면) closure 캡처용 필드들, 여기는 없음
그리고 코루틴이 시작되면 이 state-machiine anonymous class는 아래와 같이 동작을 한다.
• 코루틴 시작 → resumeWith() 호출 → label = 0 → L0 실행
• L0에서 작업 수행 → label=1 → await 호출 → 만약 suspend되면 return
• 재개(resume)되면 다시 resumeWith() 호출 → label=1 → L1 실행
• L1에서 작업 수행 → label=2 → await 호출 → suspend되면 return
• 다시 재개되면 → label=2 → L2 실행 → 끝
즉, resumeWith()가 실행 재개 진입점이다.

그러면 만약 loop문 안에 suspension이 있다면?

var x = 0
while (x < 10) {
    x += nextNumber().await()
}

이런 코드가 있다.
컴파일 되면 단 하나의 state만 생성한다. 왜냐하면 because loops also work through (conditional) goto: -> 이미 loop문 자체가 compile단계에서 goto문으로 이루어지기 때문이다.

class <anonymous_for_state_machine> extends SuspendLambda<...> {
    // The current state of the state machine
    int label = 0

    // local variables of the coroutine
    int x

    void resumeWith(Object result) {
        if (label == 0) goto L0
        if (label == 1) goto L1
        else throw IllegalStateException()

      L0:
        x = 0
      LOOP:
        if (x >= 10) goto END
        label = 1
        result = nextNumber().await(this) // 'this' is passed as a continuation 
        if (result == COROUTINE_SUSPENDED) return // return if await had suspended execution
      L1:
        // external code has resumed this coroutine passing the result of .await()
        x += ((Integer) result).intValue()
        label = -1
        goto LOOP
      END:
        label = -1 // No more steps are allowed
        return 
    }          
}

나는 여기까지만 하면 어느정도 될 줄 알았다. 근데 아래 이런 단락이 있다.
https://github.com/Kotlin/KEEP/blob/master/proposals/coroutines.md#compiling-suspending-functions

The compiled code for suspending function depends on how and when it invokes other suspending functions.

어? 좀 더 봐야겠다.

In the simplest case, a suspending function invokes other suspending functions only at tail positions making tail calls to them

이런 내용이 있다. tail position이 무엇인가? 말 그대로 맨 마지막에 호출되는 것을 말한다.
예를 들어

suspend fun g() {
... (더 이상 suspend function 호출이 없음)
}

suspend fun f() {
    ...
    return g()   <-- 마지막 호출
}

와 처럼 있을 때 return g() 부분이 tail position이다. 이러한 경우는 그냥 일반 함수처럼 compile된다고 한다. 단, CPS패턴에 의거하여 만들어진 continuation 파라미터를 그대로 다음 suspend함수에 넘긴다.(즉, state machine이 필요가 없다.)

이후 나오는 문장 중 non-tail position에 대한 내용이 나온다.

In a case when suspending invocations appear in non-tail positions, the compiler creates a state machine for the corresponding suspending function. An instance of the state machine object in created when suspending function is invoked and is discarded when it completes.

아까 우리가 봤던 state-machine으로 생성되는 패턴이다.

val a = qwer()   // qwer이 suspend function
println(a)
val b = poiu()   // poiu가 suspend function

이 경우 함수가 완료되면 state machine객체가 폐기된다(discarded로 되어있어서 직역했다)

Note: in the future versions this compilation strategy may be optimized to create an instance of a state machine only at the first suspension point

다행(?)스럽게도 나중에 최적화할 생각까지 가지고 계신다.

아까 state machine객체를 폐기한다고 했다. 그러면 어느정도 재사용할 여지가 있어야한다.

This state machine object instance is updated and reused when the function makes multiple invocations to other suspending functions.

진짜 재사용한다고 한다.
자랑스럽게 나오는 내용 중

Compare this to other asynchronous programming styles, where each subsequent step of asynchronous processing is typically implemented with a separate, freshly allocated, closure object.

요약 : 다른 언어는 계속 closure 객체 생성하지? 우리는 재사용해서 좋다.

즉 kotlin에서는

이는 다른 비동기 프로그래밍 스타일(예: callback-based)과 대비된다.
전통 방식에서는 각 비동기 단계마다 새로운 closure 객체를 계속 생성해야 한다.

이번 글 요약

velog에서 똑같은 글을 본다면 제 다른 블로그가 맞습니다.

[kotlin deep/shallow/wide dive] deep - suspend가 정확히 뭐고 CPS는 뭐고 state machine이 뭐죠는 꼬리에 꼬리를 물고(1)

Berno — Wed, 26 Nov 2025 19:42:20 +0900

ref: https://kotlinlang.org/docs/coroutines-basics.html#suspending-functions

이미 코루틴을 사용해봤고 약간 알고 있다고 가정하겠습니다.

다시 처음부터. suspend가 뭐라고?

그니까 멈추게 할 수 있다! 이거다. 그니까 만약

suspend fun foo(): Int {
    return 0;
}

와 같은 함수가 존재한다면 컴파일 되면서 요렇게 변한다.

fun foo(continuation: Continuation<Int>): Any?

??? : 파라미터가 있으면요?

suspend fun foo(param1: Param): Int {
    return 0;
}

와 같이 있었다면

fun foo(param1: Param, continuation:Continuation<Int>): Any?

처럼 변한다.

근데 도대체 이게 왜 필요한가? 이 질문부터 해보자.

Suspending functions
The most basic building block of coroutines is the suspending function. It allows a running operation to pause and resume later without affecting the structure of your code.

정확히는 stop이 아니라 pause이다. 즉 일시정지를 한다는거고 다시 시작한다는거다.
그리고 Thread에 대한 pause가 아니라 execution state에 대한 pause이다.

suspend는 thread에 대한 block이 아님
coroutine의 delay를 하게 되면 Thread의 sleep과는 다르게 Thread block없이 suspend/resume이 발생함

어? 그렇다면 이 상태를 어디선가 저장을 하고 있어야한다. 즉, state를 관리하는 machine이 필요하다는거다.

그니까 Thread에 대한 정지가 아니라 함수의 실행을 일시정지하고 thread는 그대로 진행됨.다시 재개했을때 동일 Thread가 아닐 수 있고 Thread의 stack frame이 유지되지 않고 Thread stack 또한 달라질 수 있음

그러면 이제 슬슬 뭔가 궁금해지는 것 중 하나로

왜 어째서 코루틴의 suspending은 concept에서 왜 thread stop으로 디자인되지 않았는가?

몇몇 자료를 좀 찾아보자.

coroutines can suspend their execution instead of blocking a thread.”

Coroutines are lightweight alternatives to threads. They can suspend without blocking system resources and are resource-friendly, making them better suited for fine-grained concurrency.

일단 스레드를 블로킹하지 않고 동시성 구현을 한다고 되어 있고 thread를 대신하기 위한 아주 가벼운 것으로 설명되고 있다. 리소스도 적게 먹고.
여기서 나온 문장들을 근거로 유추를 해보면 하드웨어 성능 상으로 thread가 돌아가기에 정말 이 thread에 상관 없는 다른 대체제를 생각하고 만들어진게 coroutine이 아닌가 싶다. 그러면 이제 state machine에서 이게 어떻게 관리되고 있는지를 봐야한다.

검색을 하던 중 이런 사이트를 보게 되었다.
https://kotlinlang.org/spec/asynchronous-programming-with-coroutines.html

여기서 좀 더 하위 칼럼 중 하나인 https://kotlinlang.org/spec/asynchronous-programming-with-coroutines.html#implementation-details 을 보면

Continuation Passing Style이라는게 나온다. 이게 뭔지를 좀 봐야겠다.
다행스럽게도 친절하게 클릭하면 설명이 나오게 되어있다.
https://kotlinlang.org/spec/asynchronous-programming-with-coroutines.html#continuation-passing-style

그니까.. 각 suspend 함수는 CPS형태로 변환된다. 그니까 Continuation을 넘긴다는 건데 정확히 Continuation에 어떤 정보가 있는지를 봐야한다.

상당히 심플하게 적혀있지만 결국 어디까지 진행했는지, 어디서 중단했는지에 대한 포인트 지점을 찍어둔거다. 아까 컴파일 된 결과에서 continuation 파라미터를 이용해 그 정보들을 계속해서 passing(전달)한다. 그래서 suspend 함수들은 원할때 pause/resume이 가능한거다.

2편에서 이어서...

velog에서 똑같은 글을 본다면 제 다른 블로그가 맞습니다.

[WIP] [kotlin deep/shallow/wide dive] wide - lateinit 과 lazy

Berno — Tue, 25 Nov 2025 16:47:06 +0900

https://velog.io/@bernoyoun/kotlin-deepshallowwide-dive-wide-lateinit-%EA%B3%BC-lazy

[kotlin deep/shallow/wide dive] wide - lateinit 과 lazy

kotlin을 사용하다 보면 나중에 초기화를 하기 위해 lateinit 과 lazy를 사용하곤 하는데 그래서 이게 뭐가 다르다고?일단 공식문서에서 다시 한번 lateinit과 lazy by에 대해서 슥 읽어보자.https://kotlinlang

velog.io

(WIP)바이브 코딩 프로세스 확립기

Berno — Fri, 14 Nov 2025 14:58:20 +0900

(가볍게 적은 글)
https://velog.io/@bernoyoun/%EB%82%B4%EA%B0%80-%EC%82%AC%EC%9A%A9%ED%95%98%EB%8A%94-%EB%B0%94%EC%9D%B4%EB%B8%8C-%EC%BD%94%EB%94%A9-%ED%94%84%EB%A1%9C%EC%84%B8%EC%8A%A4

내가 사용하는 바이브 코딩 프로세스

나는 초기에 바이브 코딩을 하면서 부터 문제가 최대한 덜 생기게 개발을 하는 방법을 고민해보았다.그냥 무턱대고 마! 개발해줘! 라고 하기엔 사이즈가 커지면서 온갖 문제가 발생할 것 같았다

velog.io

Infra 비용 절감을 행한 기록

Berno — Thu, 30 Oct 2025 19:26:31 +0900

가볍게 읽고 싶으신 분은 아래 글로

구두쇠식 서비스 인프라 운영법

"월 인프라 비용이 $45... 좀 더 절약한다. 쥐어짜면 뭐든 나온다.개인 서비스를 운영중이다. 혼자 개발하고 있다. 월 인프라 비용이 $45-50이 나온다. 줄일거다. 이거 줄일 수 있다.Cloud Run (백엔드):

velog.io

(이 글은 Claude와 합작으로 작성된 글임을 밝힙니다.)
개인 프로젝트에서 월 $45-50의 GCP 인프라 비용을 $15-20으로 70-85% 절감한 실제 최적화 사례를 다룹니다. 조건부 빌드, 의존성 기반 캐싱, 아키텍처 단순화, AI API 최적화를 통해 비용 절감과 동시에 성능 향상을 달성한 엔지니어링 과정을 상세히 분석합니다.

주의사항 : 약간의 비용적 과장, 타임라인 상 코드 상으로 예전에 해뒀는데 여기에 같이 버무리고 같이 한 것 처럼 진행한 부분 있음 주의.

약간 쉴 틈을 주기 위해 중간 중간 짤이 들어갈 수 있음을 알립니다.

1. 프로젝트 컨텍스트 및 문제 정리

1.1 비용 구조 분석

Initial Cost Breakdown (월 $45-50)

Cloud Run (Backend)     : $5-10 (44-50%)
├─ Memory: 2Gi, CPU: 1
├─ Min instances: 1 (Cold start 방지)
└─ Max instances: 10

Cloud Build (CI/CD)     : $20-25 (33-40%)
├─ 빌드 시간: 30분/회
├─ 빌드 빈도: 15-20회/일
└─ 무료 한도 초과: 120분/일

AI API (Gemini)         : $15-20 (33-40%)
├─ 토큰 사용: 비효율적 구조
├─ 캐싱: 미적용
└─ 프롬프트 최적화: 미적용

1.2 성능 병목점 식별

빌드 시간: 18분 (프론트엔드 변경 시에도 백엔드 빌드)
캐시 히트율: 30% (SHA 기반 캐시의 한계)
리소스 중복: API 변경 없는 상황에서도 전체 파이프라인 실행

2. 최적화 전략 설계

2.1 비용 최적화 우선순위 매트릭스

최적화 영역	구현 복잡도	예상 절감률	ROI 점수
조건부 빌드	낮음	60-80%	⭐⭐⭐⭐⭐
의존성 캐싱	중간	90%+	⭐⭐⭐⭐⭐
Redis 제거	높음	100%	⭐⭐⭐⭐
AI 최적화	중간	75%	⭐⭐⭐⭐
PDF 이전	높음	100%	⭐⭐⭐

2.2 무료 티어 활용 전략

Google Cloud 무료 한도 분석

Cloud Run:
  requests: 2,000,000/month  # 충분한 여유
  cpu_time: 400,000 vCPU-seconds/month
  memory: 800,000 GiB-seconds/month

Cloud Build:
  build_time: 2500 minutes/month  # 현재 초과 중
  storage: 10GB

Secret Manager:
  secret_versions: 6  # 현재 사용량: 7개 (1개 초과)

3. 구현 상세: 기술적 솔루션

3.1 조건부 빌드 시스템 구현

3.1.1 turbo-ignore 기반 변경 감지

# cloudbuild.yaml
steps:
  - name: 'gcr.io/cloud-builders/npm'
    id: 'check-changes'
    entrypoint: 'bash'
    args:
      - '-c'
      - |
        echo "  Checking if API changes require rebuild..."
        npm install -g pnpm@8
        pnpm add -g turbo@latest

        # API 앱 변경 감지 (turbo-ignore: 변경 없을 때 exit 1)
        if npx turbo-ignore apps/api; then
          echo "⏭️ No API changes detected, skipping build"
          echo "false" > /workspace/should_build
          exit 0
        else
          echo "✅ API changes detected, proceeding with build"
          echo "true" > /workspace/should_build
        fi
    timeout: '300s'

3.1.2 조건부 실행 로직

  - name: 'gcr.io/cloud-builders/npm'
    id: 'prepare-build'
    entrypoint: 'bash'
    args:
      - '-c'
      - |
        # 빌드 필요성 체크
        if [ ! -f /workspace/should_build ] || [ "$(cat /workspace/should_build)" != "true" ]; then
          echo "⏭️ Skipping build - no API changes detected"
          exit 0
        fi

        echo "  Installing dependencies..."
        # 실제 빌드 로직 실행

3.2 의존성 기반 캐싱 시스템

3.2.1 해시 기반 캐시 키 생성

# 기존: SHA 기반 (소스 변경마다 무효화)
CACHE_KEY="v1-${SHORT_SHA:0:8}"

# 개선: 의존성 기반 (안정적)
DEPS_HASH=$(cat package.json pnpm-lock.yaml | sha256sum | cut -d' ' -f1 | cut -c1-8)

3.2.2 다층 캐시 복원 전략

# 의존성 기반 캐시 복원 (우선순위별)
- name: 'gcr.io/cloud-builders/gsutil'
  entrypoint: 'bash'
  args:
    - '-c'
    - |
      # 1순위: 정확한 의존성 해시 매치
      gsutil -m cp gs://cache-bucket/pnpm-store-deps-$$DEPS_HASH.tar.gz . 2>/dev/null || \
      # 2순위: 최신 의존성 캐시 (폴백)
      gsutil -m cp gs://cache-bucket/pnpm-store-deps-*.tar.gz . 2>/dev/null || \
      echo "No dependency cache found"

      # 캐시 유효성 검증
      if [ -f "node_modules/.pnpm-lock.yaml" ]; then
        if diff -q pnpm-lock.yaml node_modules/.pnpm-lock.yaml >/dev/null 2>&1; then
          echo "✅ Cache dependencies match current lockfile"
        else
          echo "⚠️ Cache dependencies differ - will reinstall"
          rm -rf node_modules .pnpm-store
        fi
      fi

성과: 캐시 히트율 30% → 90%+ 향상

3.3 아키텍처 단순화: Redis 제거

3.3.1 PostgreSQL 큐 시스템 마이그레이션

// AS-IS: Redis SSE
class RedisProgressService {
  async publishProgress(userId: string, progress: ProgressData) {
    await this.redis.publish(`progress:${userId}`, JSON.stringify(progress));
  }

  async subscribeProgress(userId: string): Promise<EventEmitter> {
    return this.redis.subscribe(`progress:${userId}`);
  }
}

// TO-BE: PostgreSQL 큐 (pg-boss)
import PgBoss from 'pg-boss';

class PostgresProgressService {
  private boss: PgBoss;

  constructor() {
    this.boss = new PgBoss({
      connectionString: process.env.DATABASE_URL,
      retryLimit: 3,
      retryDelay: 30,
      expireInSeconds: 300, // 5분 후 만료
    });
  }

  async publishProgress(userId: string, progress: ProgressData) {
    await this.boss.send('progress-update', {
      userId,
      documentId: progress.documentId,
      step: progress.step,
      progress: progress.percentage,
      timestamp: new Date().toISOString()
    });
  }

  async startProgressWorker() {
    await this.boss.work('progress-update', async (job) => {
      const { userId, ...progressData } = job.data;

      // WebSocket 또는 폴링 엔드포인트로 전달
      await this.notificationService.notify(userId, progressData);
    });
  }
}

3.3.2 적응형 폴링 클라이언트

// 클라이언트 측 적응형 폴링
class AdaptivePollingClient {
  private pollInterval = 1000; // 초기 1초
  private maxInterval = 5000;   // 최대 5초
  private minInterval = 500;    // 최소 0.5초

  async startPolling(documentId: string) {
    while (!this.isComplete) {
      try {
        const progress = await this.fetchProgress(documentId);

        if (progress.changed) {
          // 변화 있으면 폴링 간격 단축
          this.pollInterval = Math.max(this.minInterval, this.pollInterval * 0.8);
        } else {
          // 변화 없으면 폴링 간격 연장
          this.pollInterval = Math.min(this.maxInterval, this.pollInterval * 1.2);
        }

        await this.sleep(this.pollInterval);
      } catch (error) {
        // 에러 시 폴링 간격 연장
        this.pollInterval = Math.min(this.maxInterval, this.pollInterval * 2);
      }
    }
  }
}

트레이드오프 분석:

❌ 완벽한 실시간성 손실 (500ms ~ 5초 지연)
✅ 인프라 비용 완전 제거 ($0)
✅ 모바일 브라우저 호환성 60% 개선
✅ 시스템 복잡도 감소

3.4 AI API 비용 최적화

3.4.1 Gemini Implicit Caching 활용

interface PromptOptimization {
  // ❌ 캐시 비효율적 구조 (변수가 앞에)
  inefficient: string;
  // ✅ 캐시 효율적 구조 (공통 부분이 앞에)
  optimized: string;
}

class GeminiPromptOptimizer {
  // 캐시 친화적 프롬프트 구조 설계
  buildOptimizedPrompt(userInput: string): string {
    const staticContext = this.getLegalContext();      // 95% 재사용
    const documentTemplate = this.getDocumentTemplate(); // 80% 재사용  
    const a4Guidelines = this.getA4Guidelines();        // 100% 재사용

    // 공통 부분을 앞에, 변수 부분을 뒤에 배치
    return `
${staticContext}

${documentTemplate}

${a4Guidelines}

---
사용자 요청사항:
${userInput}
    `.trim();
  }
}

3.4.2 토큰 사용량 분석 및 최적화

// 최적화 전후 토큰 사용량 비교
const tokenAnalysis = {
  before: {
    avgTokensPerRequest: 2750,
    cacheHitRate: 0.05,
    monthlyCost: 68.75, // 5000 requests/month
  },
  after: {
    avgTokensPerRequest: 2750, // 동일한 품질 유지
    cacheHitRate: 0.75,        // 75% 캐시 히트
    monthlyCost: 17.19,        // 75% 절감
  }
};

3.5 PDF 생성 엔진 진화

3.5.1 3단계 PDF 엔진 비교 분석

Phase	엔진	위치	메모리	처리시간	장점	단점
1	wkhtmltopdf	서버	20-30MB	0.1s	빠른 처리	한국어 폰트 이슈
2	Puppeteer	서버	250-500MB	3-5.5s	완벽 렌더링	높은 서버 부하
3	react-to-print	클라이언트	0MB	즉시	서버 부하 0	브라우저 의존성

3.5.2 react-to-print 구현

// PDF 생성 클라이언트 이전
import { useReactToPrint } from 'react-to-print';

interface A4DocumentProps {
  content: DocumentContent;
  template: DocumentTemplate;
}

const A4Document: React.FC<A4DocumentProps> = ({ content, template }) => {
  const componentRef = useRef<HTMLDivElement>(null);

  const handlePrint = useReactToPrint({
    content: () => componentRef.current,
    pageStyle: `
      @page {
        size: A4;
        margin: 20mm;
      }
      @media print {
        html, body {
          height: initial !important;
          overflow: initial !important;
        }
      }
    `,
    onBeforePrint: () => {
      return Promise.resolve();
    },
    onAfterPrint: () => {
      console.log('PDF generation completed');
    }
  });

  return (
    <div>
      <button onClick={handlePrint}>PDF 다운로드</button>
      <div ref={componentRef} className="a4-document">
        <DocumentRenderer content={content} template={template} />
      </div>
    </div>
  );
};

성과: 서버 CPU/메모리 부하 완전 제거, CSS 스타일 100% 보존

4. 성능 측정 및 벤치마킹

4.1 비용 분석 결과

Before/After 상세 비교

┌─────────────────┬────────────┬────────────┬───────────┐
│ Cost Category   │ Before ($) │ After ($)  │ Savings   │
├─────────────────┼────────────┼────────────┼───────────┤
│ Cloud Run       │ 20-25      │ 8-10       │ 60%       │
│ Cloud Build     │ 15-20      │ 3-5        │ 75-80%    │
│ AI API (Gemini) │ 15-20      │ 4-5        │ 75%       │
│ Storage         │ 2-3        │ 2-3        │ 0%        │
│ Networking      │ 1-2        │ 1-2        │ 0%        │
├─────────────────┼────────────┼────────────┼───────────┤
│ Total Monthly   │ 45-50      │ 15-20      │ 70-85%    │
└─────────────────┴────────────┴────────────┴───────────┘

5. 아키텍처 영향 분석

5.1 시스템 복잡도 변화

Before: Frontend → Backend → Redis → Database → AI API → PDF Engine
After:  Frontend → Backend → Database → AI API
                      ↓
               PostgreSQL Queue → PDF (Client)

5.3 개발자 경험(DX) 향상

로컬 개발: Redis 의존성 제거로 설정 단순화
배포: 실패 지점 감소

6. 장기적 확장성 고려사항

6.1 트래픽 증가 시나리오

// 예상 트래픽별 비용 추정
interface CostProjection {
  users: number;
  requests: number;
  estimatedCost: number;
}

const projections: CostProjection[] = [
  { users: 100,   requests: 10000,   estimatedCost: 15 },   // 현재
  { users: 1000,  requests: 100000,  estimatedCost: 45 },   // 10배 증가
  { users: 10000, requests: 1000000, estimatedCost: 150 },  // 100배 증가
];

7. 결론 및 권장사항

비용 절감: 70-85% (월 $45-50 → $15-20)
성능 향상: 빌드 시간 50-67% 단축
권장사항: 일단 모르겠다면 캐싱을 먼저 도입하자.

References

조만간 정리할 글

Berno — Fri, 5 Sep 2025 11:53:31 +0900

https://velog.io/@bernoyoun/%EC%9D%B4%EC%A0%9C-Langchain%EC%9D%84-%EA%B3%B5%EB%B6%80%ED%95%A0-%EC%8B%9C%EC%A0%90%EC%9D%B4-%EC%99%80%EB%B2%84%EB%A6%B0-%EB%B0%80%EB%A6%BC%EC%9D%98-%EC%99%95%EC%9D%80-%EC%82%AC%EC%9E%90%EC%9E%85%EB%8B%88%EB%8B%A4.-%EA%B7%B8%EB%9E%98%EC%84%9C-%EC%9D%BC%EB%8B%A8-ollama%EC%97%90%EC%84%9C-LLM-%EB%AA%A8%EB%8D%B8-%EB%A8%BC%EC%A0%80-%EC%84%A4%EC%B9%98%ED%96%88%EC%8A%B5%EB%8B%88%EB%8B%A4

이제 Langchain을 공부할 시점이 와버린 밀림의 왕은 사자입니다. 그래서 일단 ollama에서 LLM 모델 먼

맥북에서 이미 여러 잡일을 돌리고 있던 터라 최대한 리소스가 적게 드는 놈으로 찾던 중deepseek-r1:1.5b라는 놈을 발견했다.

velog.io

SSE vs Long Polling vs WebSocket

Berno — Sat, 30 Aug 2025 18:57:43 +0900

https://velog.io/@bernoyoun/SSE-Long-Polling-WebSocket

SSE? Long Polling? WebSocket?

오늘도 딸깍딸깍하며 바이브 코딩을 즐기던 중, SSE로 개발되었던 기능에서 문제가 터졌다.

velog.io

이 글은 왠지 올리긴 하지만 velog가 더 적절해보이긴 한다..

CLAUDE-CODE의 토큰을 절약하기 - tasks.md의 문서 구조 개편

Berno — Wed, 27 Aug 2025 00:50:52 +0900

이 글은 제 경험기를 GPT와 함께 작성한 글임을 밝힙니다.

Case Study

Token Limit로 막힌 2,000+라인 태스크 파일을 구조화해 76.1% 토큰 절감한 방법

Executive Summary

문제: 단일 tasks.md(2,247라인)를 모델에 로딩할 때 token limit exceed로 AI 워크플로우 불능 상태 발생.
해결: 마스터 인덱스(180라인) + 6개 전문 파일 + 완료 아카이브로 정보 아키텍처 재설계.
성과(정량)
- 평균 토큰 사용량 76.1% 절감 (42,000 → 10,100)
- 응답 시간 평균 75% 단축 (질의 유형별 73~83%)
- 탐색 시간 70% 단축, 개발 효율성 4배
- API 비용 연간 $8,731 절감, 개발 시간 절감 ROI 연간 ~$80,000
성과(정성)
- 개발자 만족도 및 정보 적합성 유의미 개선(예: 정보 적합성 3.1/5 → 4.6/5, +48%)

1) 문제 정의: 단일 파일 + Token Limit의 복합 병목

단일 파일 규모: 2,247 라인, 추정 38k~42k tokens.
구성 혼재: 완료·진행·계획·결제·보안·메타데이터가 한 문서에 공존 → 컨텍스트 노이즈 급증.
직접 영향
- 모델 호출 시 token limit exceed → AI 기반 검색/요약/연결 자동화 중단.
- 사람 입장에서도 원하는 태스크를 찾기 위해 분 단위 탐색이 상시 발생.
- 협업(병렬 편집·책임 분리)과 진행률 가시성 모두 저하.

2) 설계 원칙: Separation of Concerns + 선택적 로딩

핵심은 “파일을 자르는 것”이 아니라 “컨텍스트를 설계”하는 것입니다.

도메인 중심 분류(Domain-Driven Organization)
- 태스크를 기능적 도메인 기준으로 재배치(코어 개발, 결제/구독, 품질/국제화, 인프라/보안, 프로젝트 운영, 미래 확장).
계층적 참조(Hierarchical References)
- 마스터 인덱스(180라인) = 한눈에 조망 + 내비게이션 허브.
- 세부 작업은 전문화 파일에서만 읽음 → 선택적 로딩.
스마트 참조(Smart Referencing)
- 일반 질의는 인덱스만, 특정 업무는 인덱스 + 해당 1개 파일, 완료 검토는 아카이브만.

3) 최종 구조: 인덱스 + 전문 파일 + 아카이브

/development
├─ tasks.md                         # Master Index (180 lines)
├─ completed-tasks-archive.md       # 완료 아카이브 (371 lines, 23건)
└─ /current-tasks
   ├─ 01-core-development.md        # 260 lines
   ├─ 02-payments-subscriptions.md  # 273 lines
   ├─ 03-quality-testing.md         # 227 lines
   ├─ 04-infrastructure-security.md # 259 lines
   ├─ 05-project-management.md      # 221 lines
   └─ 06-future-expansion.md        # 262 lines

4) 구현 프로세스(Phase별)

Phase 1: 분석/분류

wc -l, grep -c 등으로 라인·섹션·태스크 정량 진단
완료 23, 진행 15, 계획 25, 메타데이터 247+ 라인
교차 관심사(Cross-cutting) 식별 → Primary 배치 + Cross-reference

Phase 2: 구조화/분리

Master Index 초안 작성
전문 파일 6종 생성, 파일명/순서 규칙화

Phase 3: 완료 아카이브

완료 23건을 독립 파일로 이동
활성 컨텍스트에서 완료 이력 제거 → 현재 작업의 신선도 유지

5) 성과(정량): 토큰·응답·비용·시간

5.1 토큰 절감

Before: 질의 유형 무관 42,000 tokens 평균
After(평균 10,100 tokens, 가중 평균)
- 일반 현황(40%): 2,800
- 도메인 작업(35%): 7,300
- 우선순위 확인(15%): 800
- 종합 분석(10%): 11,800
절감률: 76.1%

5.2 응답 시간(실측)

단순 질의: 15~~25s → 3~~5s (75~83%↓)
복합 분석: 35~~50s → 8~~12s (76~77%↓)
도메인 특정: 20~~30s → 5~~8s (73~75%↓)

5.3 API 비용 절감(예시)

가격: $15 / 1M tokens
Before: $31.50/day
After : $7.58/day
연간 절감: ~$8,731

5.4 개발 시간 ROI(예시)

연간 ~$80,000 절감 (탐색 시간 단축 기반)

6) 성과(정성)

정보 적합성: 3.1/5 → 4.6/5 (+48%)
태스크 발견 만족도: 4.2/5 → 4.8/5 (+14%)
컨텍스트 전환 스트레스: 3.8/5 → 2.1/5 (–45%)
체감 생산성: 3.5/5 → 4.7/5 (+34%)
투명성: 완료 23건 vs 진행 항목 명확 구분

7) 통합 가이드

일반 질의: 인덱스만 로딩
특정 업무: 인덱스 + 해당 파일
우선순위 확인: 인덱스 부분만
완료 검토: 아카이브만
Prompt/에이전트 룰: 인덱스→파일 선택적 로딩

8) 도전과 극복

경계 모호 → Primary+Cross-ref 규칙 확립
정보 중복 → Essential Duplication 최소화
팀 적응 기간 → 2~3주 온보딩 가이드
초기 혼란 → 인덱스 상단 “파일 결정표” 제공
파일 동기화 → 리뷰 시 인덱스 무결성 확인

9) 재현 체크리스트

Week 1: 진단 (라인 수·태스크 수 분석)
Week 2: 도메인 그룹핑
Week 3~4: 파일화 & 인덱싱
Month 2: 운영 정착 & 리뷰 자동화

10) 요약 인사이트

엔지니어: Token limit은 입력 제약이자 설계 요구사항.
PM/리더: 문서 구조 최적화는 ROI를 만들어내는 전략적 행위.

부록 A. 시나리오별 절감률

일반 현황: 42,000 → 2,800 (–93.3%)
도메인 작업: 42,000 → 7,300 (–82.6%)
완료 검토: 42,000 → 6,500 (–84.5%)
종합 분석: 42,000 → 11,800 (–71.9%)

부록 B. 파일/라인 요약

인덱스 180 / 아카이브 371 / 전문 6개(227~273, 평균 250±)
활성 태스크: 진행 15 / 계획 25 / 완료 23

https://velog.io/@bernoyoun/CLAUDE-CODE%EC%9D%98-%ED%86%A0%ED%81%B0%EC%9D%84-%EC%A0%88%EC%95%BD%ED%95%98%EA%B8%B0-tasks.md%EC%9D%98-%EB%AC%B8%EC%84%9C-%EA%B5%AC%EC%A1%B0-%EA%B0%9C%ED%8E%B8

CLAUDE-CODE의 토큰을 절약하기 - tasks.md의 문서 구조 개편

CLAUDE-CODE의 토큰을 절약하기

velog.io

조금 가벼워진 글은 VELOG에 올라갑니다.

CLAUDE.md 구조 개편 - 왜 기억을 못하니

Berno — Sat, 16 Aug 2025 16:35:31 +0900

본 글은 CLAUDE + GPT와 함께 작성한 글임을 밝힙니다.
CLAUDE-CODE에서 왜 자꾸 너는 CLAUDE.md에 있는 내용을 까먹는거야? 와 같은 내용으로 질문을 하였을때 알려준 내용을 토대로 나온 글입니다.

필자는 왜 CLAUDE.md의 명세를 제대로 기억 못하는지 한동안 이 표정으로 불만이었음

CLAUDE.md의 내용을 자꾸 까먹는다니까요.

반복된 실패 사례

사용자 요청: "PR 머지해"
기대 동작: 문서 4개 자동 업데이트 (status.md, tasks.md, README.md, dev-notes/)
실제 동작: PR만 머지 → 문서 업데이트 누락
결과: 상태 불일치, 뒤늦게 수동 작업

비즈니스 임팩트

자동화 도입 효과 상실 → 수동 부담 증가
프로젝트 문서와 실제 상태 불일치
인지 부하 증가 → 개발자 경험(DevEx) 악화
규칙 준수율 저하 → 품질 저하

원인 분석

1. 과도한 정보량

기존 CLAUDE.md: 약 1,000줄, 6개 대섹션 + 수많은 규칙 혼재
정보 과잉으로 실시간 의사결정 불가

2. 우선순위 불명확

실행 규칙과 참고 정보가 동일한 위상으로 배치
Critical 규칙(예: PR 머지)이 묻혀 있음

3. 인지 부하

매번 문서를 스캔해야 함
키워드 기반 빠른 접근 불가

4. 실행 vs 참조 혼재

명령어 키워드와 관련 액션 매핑 불투명
문서 업데이트 절차가 여러 군데에 흩어져 있음

해결책: 3-Tier 문서 아키텍처

철학

Just-In-Time Information Access
→ 필요한 순간, 필요한 정보만. 나머지는 계층적으로 뒤로 배치.

구조

Tier 1: CLAUDE.md (허브)
- 사용자 요청별 즉시 실행 규칙 테이블
- 핵심 참조 문서 링크
- SuperClaude 프레임워크 요약
- 길이: 100줄 내외
Tier 2: 실행 가이드 문서
- AUTO-DOC-UPDATE.md: PR 머지 후 자동화 절차 상세
- GIT-WORKFLOW-RULES.md: Git 전략 및 워크플로우 규칙
- MAGIC-UI-GUIDE.md: UI 컴포넌트 생성 규칙
Tier 3: 참고 문서
- A4LAB-DESIGN-PRINCIPLES.md: 설계 철학과 아키텍처 패턴
- PROJECT-CONTEXT.md: 비즈니스 맥락, 기술 스택 설명
- SuperClaude 프레임워크 전역 설정 (~/.claude)

키워드 매핑 예시

키워드	즉시 액션	참조
"PR 머지해"	4개 문서 자동 업데이트	AUTO-DOC-UPDATE.md
"UI 만들어"	컴포넌트 생성 절차 실행	MAGIC-UI-GUIDE.md

벤치마킹: 외부 유사 사례

Stripe API 문서
- Quick Start와 API Reference 분리
- 초심자와 숙련자를 동시에 만족시키는 구조
VS Code 확장 문서
- 개요 → 가이드 → API로 계층화
- Progressive Disclosure 적용 사례
AWS 문서
- Getting Started와 Deep Dive 이원화
- 온보딩과 심화 학습을 분리해 정보 과부하를 방지

기대 효과

즉시 효과 (도입 직후)

문서 길이 100줄 이하 달성
핵심 규칙 테이블화
참조 문서 4개 이상 분리 완료

결론

CLAUDE.md 개편은 단순한 문서 구조 조정이 아님
개발자 경험(DevEx) 개선 프로젝트이며, 인지 부하를 줄이고 규칙 준수율을 높이는 전략적 투자
Stripe, VS Code, AWS 사례와 같은 정보 설계(Information Architecture) 원칙을 실무에 적용한 사례

조금 가벼워진 글은 velog에 올라갑니다.

CLAUDE.md 문서가 너무 길다고 못읽겠다잖아요!