rootTiket

[시스템 설계] 커머스 도메인 주문-결제 분산 트랜잭션 설계

rootTiket — Sun, 26 Apr 2026 11:19:16 +0900

0. 설계 경계

설계하고자 하는 분산 트랜잭션 서비스는 글로벌 한정판 스니커즈 Drop 커머스다.

정오 오픈 시점 예상 동시 접속자 수는 100만 명이다.
판매 재고는 1,000족뿐이다.
선착순 공정성을 보장해야 한다.
1족도 초과 판매되면 안 된다.
주문서 진입 후 5분 안에 결제가 끝나지 않으면 재고를 돌려줘야 한다.
사용자는 최대 10분 안에 성공 또는 실패 피드백을 받아야 한다.

- 대기열이 100만 명을 그대로 주문 서버로 보내지 않고, 입장 순서와 트래픽을 제어한다고 본다. 즉, 주문 API에는 대기열을 통과한 사용자만 들어온다.

- 재고 서비스가 초과 판매를 막기 위해 재고를 먼저 선점한다고 본다. 내부 구현은 Redis 분산 락이든 DB 조건부 업데이트든 가능하지만, Part 3에서는 재고 서비스가 다음 명령을 원자적으로 처리할 수 있다고 가정한다.

ReserveInventory(orderId, skuId, ttl=5m)
ConfirmReservation(orderId)
ReleaseReservation(orderId)

이번 설계의 관심사는 그 다음이다.

주문 생성
→ 재고 예약
→ 외부 PG 결제 승인 요청
→ 재고 확정
→ 주문 성공 처리

이 흐름은 Order, Inventory, Payment, 외부 PG까지 걸쳐 있다. 모두 다른 서비스이고, 각자 다른 DB를 가진다. 여기서 "한 번에 모두 성공하거나 모두 실패하는 것처럼 보이게 만드는 것"이 이번 설계의 목표다.

1. 먼저 실패 시나리오부터 생각했다

처음에는 "Saga 패턴을 쓰면 되지 않을까?" 정도로 생각했다. 그런데 그렇게 시작하면 글이 너무 추상적이 된다.

그래서 먼저 뭐가 터질 수 있는지부터 적어봤다.

시나리오 1. 주문은 만들어졌는데 결제 요청 이벤트가 유실된다

주문 서비스가 Order DB에 주문을 저장했다. 그런데 Kafka에 PaymentApproveRequested 이벤트를 보내기 직전에 서버가 죽었다.

그럼 DB에는 주문이 있는데, 결제 서비스는 이 주문을 모른다. 사용자는 주문을 눌렀지만 결제는 시작되지 않는다. 이런 주문은 운영에서 가장 곤란하다. 실패도 아니고 성공도 아닌 상태로 남기 때문이다.

이 문제는 단순 재시도로 해결되지 않는다. 서버가 죽으면 재시도 로직도 같이 죽는다.

→ 그래서 Outbox가 필요하다.

시나리오 2. PG에서는 결제가 승인됐는데 우리 서버는 Timeout을 받는다

Payment Service가 PG에 승인 요청을 보냈다. PG 내부에서는 결제가 승인됐다. 그런데 네트워크 문제로 응답이 유실됐다.

우리 서버 입장에서는 Timeout이다. 하지만 이걸 실패로 처리하면 안 된다. 실제로는 돈이 빠져나갔을 수 있기 때문이다.

→ 그래서 FAILED가 아니라 UNKNOWN 상태가 필요하다.

시나리오 3. 사용자가 결제 버튼을 여러 번 누른다

한정판 구매 화면에서 사용자가 불안해서 결제 버튼을 여러 번 누를 수 있다. 브라우저 재시도, 앱 재시도, HTTP client retry, Kafka 재전달까지 생각하면 같은 요청은 여러 번 들어온다고 보는 게 맞다.

→ 그래서 모든 명령은 멱등해야 한다.

시나리오 4. 결제는 성공했는데 재고 확정이 실패한다

PG 결제는 성공했다. 그런데 Inventory Service가 일시 장애라 ConfirmReservation이 실패했다.

이때 바로 환불하면 안 된다. 이미 5분 TTL 안에 예약된 재고가 살아 있다면, 재고 확정을 재시도해서 주문 성공으로 처리시키는 게 맞다.

다만 예약이 이미 만료되어 다른 사용자에게 넘어갔다면, 그 결제는 취소 또는 환불해야 한다.

정리하면 이번 설계의 핵심은 "정상 흐름"이 아니라 "애매한 중간 상태를 어떻게 끝까지 책임질 것인가"다.

2. 왜 2PC를 선택하지 않았나

분산 트랜잭션을 들으면 가장 먼저 2PC가 떠오른다.

2PC는 Coordinator가 각 서비스에 먼저 준비 가능한지 묻고, 모두 가능하다고 하면 한 번에 커밋을 지시하는 방식이다.

1. Prepare
2. Commit or Rollback

이론적으로는 원자성이 강하다. 하지만 이번 도메인에는 맞지 않는다고 판단했다.

첫째, 외부 PG는 2PC에 참여하지 않는다

Order DB, Inventory DB는 우리가 통제할 수 있다. 하지만 PG사는 우리 트랜잭션 참여자가 아니다. "prepare만 해두고 기다려줘", "이제 commit 해줘", "rollback 해줘" 같은 식으로 지시할 수 없다. 결제 승인 이후 취소는 가능하지만, 그건 트랜잭션 롤백이 아니라 별도의 보상 트랜잭션이다. 이 지점에서 이미 2PC는 핵심 문제를 해결하지 못한다.

둘째, 느린 외부 요청이 내부 트랜잭션을 붙잡는다

2PC나 그와 비슷한 동기식 설계를 택하면, Order DB와 Inventory DB가 결제 응답을 기다리는 동안 리소스를 잡고 있을 가능성이 커진다.

그런데 이 시스템의 핵심 주문/결제 API 목표 응답 시간은 200ms 이하다. PG API가 1초만 느려져도 내부 트랜잭션, DB 커넥션, 애플리케이션 스레드가 같이 붙잡힌다. 100만 명이 몰리는 Drop 상황에서 이런 구조는 장애를 전파한다.

셋째, MSA의 독립성을 깨뜨린다

MSA에서는 각 서비스가 자기 데이터에 대한 로컬 트랜잭션을 짧게 끝내야 한다. 2PC는 여러 서비스의 커밋 결정을 하나의 Coordinator에 강하게 묶는다. 한 서비스의 지연이 전체 지연이 되고, 한 서비스의 장애가 전체 장애가 된다.

이번 설계에서는 실패를 보상하며 최종적으로 올바른 상태에 도달하는 구조가 더 적합하다고 봤다.

3. Saga 중에서도 Orchestration을 선택한 이유

Saga는 하나의 큰 트랜잭션을 여러 로컬 트랜잭션으로 나누고, 실패하면 보상 트랜잭션을 실행하는 방식이다.

Saga에는 두 가지 방식이 있다.

Choreography: 각 서비스가 이벤트를 보고 다음 행동을 스스로 결정한다.
Orchestration: 중앙 Orchestrator가 전체 진행 상태와 보상 순서를 관리한다.

나는 Orchestration을 선택했다.

왜 Choreography가 아니라 Orchestration인가

Choreography는 단순한 이벤트 흐름에는 잘 맞는다.

OrderCreated
→ InventoryReserved
→ PaymentApproved
→ OrderCompleted

각 서비스가 이벤트를 구독하고 다음 이벤트를 발행하면 된다. 중앙 제어자가 없어 결합도가 낮아 보인다.

하지만 이번 주문-결제 흐름에서는 애매한 상태가 많다.

결제 Timeout은 실패가 아니라 UNKNOWN일 수 있다.
5분 결제 제한 시간이 있다.
결제 승인 후 재고 확정 실패 시 재시도와 환불 중 하나를 선택해야 한다.
늦은 PG Webhook이 도착할 수 있다.
사용자는 10분 이내에 최종 상태를 알아야 한다.

이런 조건이 있으면 "이 주문이 지금 정확히 어느 단계인가"를 한 곳에서 추적하는 편이 낫다.

그래서 OrderSagaOrchestrator를 둔다. 이 컴포넌트는 주문별 Saga 상태를 관리하고, 다음 명령을 내리고, 보상 트랜잭션을 실행한다.

각 서비스는 자기 역할만 한다.

Order Service: 주문 상태와 Saga 진행 상태 관리
Inventory Service: 예약, 확정, 해제 로컬 트랜잭션 처리
Payment Service: PG 승인 요청, 상태 조회, 취소/환불 처리

4. 전체 구조

User → [Waiting Queue] → [API Gateway] → [Order Service / OrderSagaOrchestrator]
                                                     │
                              ┌──────────────────────┼──────────────────────┐
                              ↓                      ↓                      ↓
                         [Order DB]              [Kafka]              [Client Polling/SSE]
                                                /        \
                                    [Inventory Service]  [Payment Service]
                                        │    │                │    │
                                   [Inv DB] [Redis]      [Pay DB] [External PG]

흐름을 한 문장으로 말하면 이렇다.

대기열이 구매 기회를 제한하고, 재고 서비스가 5분 동안 재고를 예약하고, 주문 Orchestrator가 결제와 재고 확정을 끝까지 추적한다.

여기서 가장 중요한 하게 생각한 것은 외부 PG 호출은 절대 내부 DB 트랜잭션 안에서 하지 않는다는 것이다.

5. 재고는 먼저 예약하고, 결제 후 확정한다

결제 전에 재고를 전혀 잡아두지 않으면 문제가 생긴다. 사용자가 결제창에서 카드 정보를 입력하는 동안 다른 사용자들이 같은 재고를 가져갈 수 있다.

반대로 주문서 진입 시점에 바로 판매 확정으로 차감해버리면, 결제 실패나 이탈 때 재고 복구가 복잡해진다.

그래서 중간 상태가 필요하다.

AVAILABLE → RESERVED → SOLD
RESERVED  → RELEASED

주문서에 들어온 사용자는 재고를 5분 동안 점유한다. 이 5분 안에 결제에 성공하면 SOLD로 확정한다. 결제 실패, 결제 포기, 만료가 발생하면 RELEASED로 되돌린다.

사용자는 결제하는 동안 구매 기회를 보장받는다.
시스템은 결제 실패 시 재고를 다음 대기자에게 넘길 수 있다.
초과 판매는 Inventory Service의 예약 원자성으로 막는다.

6. 정상 흐름

User          OrderSagaOrchestrator    Inventory Service    Payment Service    External PG
 │                    │                       │                   │               │
 │─ POST /orders ────▶│                       │                   │               │
 │                    │─ Local TX: Order(CREATED)                 │               │
 │                    │─ ReserveInventory ───▶│                   │               │
 │                    │                       │─ Local TX: RESERVED               │
 │                    │◀─ InventoryReserved ──│                   │               │
 │                    │─ Local TX: Order(WAITING_PAYMENT)         │               │
 │◀─ orderId, expiresAt ─│                    │                   │               │
 │                    │                       │                   │               │
 │─ POST /payments/confirm ▶│                 │                   │               │
 │                    │─ Local TX: Order(PAYMENT_IN_PROGRESS) + Outbox            │
 │◀─ 202 Accepted ───│                       │                   │               │
 │                    │─ PaymentApproveRequested ────────────────▶│               │
 │                    │                       │                   │─ Approve() ──▶│
 │                    │                       │                   │◀─ Approved ───│
 │                    │                       │                   │─ Local TX: APPROVED + Outbox
 │                    │◀─ PaymentApproved ────────────────────────│               │
 │                    │─ ConfirmReservation ─▶│                   │               │
 │                    │                       │─ Local TX: RESERVED → SOLD        │
 │                    │◀─ InventoryConfirmed ─│                   │               │
 │                    │─ Local TX: Order(PAID)                    │               │
 │◀─ SSE: success ───│                       │                   │               │

여기서 POST /payments/confirm은 결제 완료를 기다리지 않는다. 결제 승인 요청을 접수하고 202 Accepted를 반환한다.

왜냐하면 PG 호출은 느릴 수 있기 때문이다. PG가 느려졌다고 해서 주문 API의 스레드와 DB 트랜잭션이 같이 느려지면 안 된다.

사용자는 이후 주문 상태 조회나 SSE를 통해 최종 결과를 받는다.

GET /orders/{orderId}
{
  "orderId": "ord_123",
  "status": "PAYMENT_IN_PROGRESS",
  "message": "결제 승인 처리 중입니다."
}

최종적으로는 다음 중 하나로 끝난다.

성공: PAID, COMPLETED
실패: CANCELLED, EXPIRED, PAYMENT_FAILED, REFUNDED

7. 외부 PG 호출을 내부 트랜잭션에서 분리한다

이번 설계에서 가장 경계한 코드는 이런 형태다.

@Transactional
fun confirmPayment(orderId: String) {
    orderRepository.updateStatus(orderId, PAYMENT_IN_PROGRESS)

    val result = pgClient.approve(orderId)   // ← 위험

    paymentRepository.save(result)
    inventoryClient.confirm(orderId)
}

문제: pgClient.approve()가 3초 동안 응답하지 않으면 DB 트랜잭션도 3초 동안 열린다. PG Timeout은 내부 DB 커넥션, row lock, 애플리케이션 스레드를 같이 잡아둔다.

그래서 다음처럼 나눈다.

Local TX:    Order status update + outbox insert      ← 짧게 끝냄
No TX:       External PG HTTP call                   ← 트랜잭션 밖
Local TX:    Payment result update + outbox insert   ← 짧게 끝냄

Order DB에 결제 진행 상태를 저장한다.
같은 트랜잭션에서 Outbox에 PaymentApproveRequested를 저장한다.
트랜잭션을 커밋한다.
Outbox Relay가 Kafka로 이벤트를 발행한다.
Payment Service Consumer가 PG를 호출한다.
PG 결과를 Payment DB에 저장하고 다시 이벤트를 발행한다.

이렇게 하면 PG가 느려져도 Order DB 트랜잭션은 영향을 받지 않는다.

8. PG 승인 Timeout은 실패가 아니라 UNKNOWN이다

가장 중요하게 다룬 케이스다.

Payment Service → PG 승인 요청
PG 내부 승인 성공
PG → Payment Service 응답 유실
Payment Service: Timeout 발생

이때 우리 서버가 받은 건 Timeout이다. 하지만 PG에서는 결제가 승인됐을 수 있다.

Timeout을 PAYMENT_FAILED로 처리하면 안 된다. 재고를 풀어버리고 주문을 취소했는데, 실제로는 고객 카드에서 돈이 빠져나간 상태가 될 수 있다.

이 케이스는 반드시 PAYMENT_UNKNOWN으로 두고, 다음 흐름으로 처리한다.

이 흐름에서 핵심은 세 가지다.

Timeout은 실패가 아니라 UNKNOWN이다.
승인 요청에는 반드시 idempotencyKey를 붙인다.
PG 상태 조회 API로 실제 승인 여부를 확인한 뒤 다음 단계로 간다.

9. 5분 제한 시간이 지나면 어떻게 할까

비즈니스 요구사항은 명확하다. 주문서 진입 후 5분 이내에 결제가 완료되지 않으면 재고를 환원한다.

그런데 Payment가 UNKNOWN이면 고민이 생긴다. 나는 이 정책을 선택했다.

5분 안에 PG 조회로 APPROVED가 확인되면 주문 성공 처리한다.
5분이 지났고 승인 내역이 확인되지 않으면 주문은 EXPIRED 처리하고 재고를 해제한다.
이후 늦게 승인 사실이 확인되면 상품 제공이 아니라 결제 취소/환불로 보상한다.

"5분은 결제 완료 시간이 아니라 구매 권리의 유효 시간"이다. 5분이 지난 뒤 결제가 확인되었다고 해서 이미 해제된 재고를 다시 뺏어오면 안 된다. 그 재고는 다음 대기자에게 넘어갔을 수 있다.

이 정책은 구매 전환율만 보면 아쉬울 수 있다. 하지만 이 도메인에서는 초과 판매 방지가 더 중요하다. 1,000족 한정 판매에서 이미 해제된 재고를 다시 성공 처리하면 다른 사용자의 선착순 기회를 침해할 수 있다.

보수적 정책: 기한 내 확정되지 않은 결제는 구매 성공으로 인정하지 않는다. 늦게 결제가 확인되면 환불로 보상한다.

10. 상태 모델

Orchestration Saga를 쓰려면 상태가 명확해야 한다. 상태가 흐릿하면 장애 복구 시 "이 주문을 다시 진행해야 하는지, 취소해야 하는지, 환불해야 하는지" 판단할 수 없다.

Order 상태

CREATED
→ WAITING_PAYMENT
→ PAYMENT_IN_PROGRESS
→ PAID
→ COMPLETED

WAITING_PAYMENT → EXPIRED
PAYMENT_IN_PROGRESS → PAYMENT_FAILED → CANCELLED
PAYMENT_IN_PROGRESS → PAYMENT_UNKNOWN → PAID or EXPIRED
EXPIRED + LatePaymentApproved → REFUND_REQUESTED

Payment 상태

READY
→ APPROVAL_REQUESTED
→ APPROVED

APPROVAL_REQUESTED → FAILED
APPROVAL_REQUESTED → UNKNOWN
UNKNOWN → APPROVED / FAILED / REFUND_REQUIRED

APPROVED → CANCEL_REQUESTED → CANCELLED or REFUNDED

Inventory Reservation 상태

RESERVED → SOLD
RESERVED → RELEASED
RESERVED → EXPIRED

상태를 이렇게 쪼개는 이유는 운영 복구 때문이다. 장애가 난 뒤 재처리 Job이 돌 때도 상태만 보고 다음 행동을 결정할 수 있어야 한다.

11. 보상 트랜잭션 정리

실패 상황	처리
재고 예약 실패	주문 취소, 결제 요청 안 함
결제 명시적 실패	재고 예약 해제, 주문 취소
결제 Timeout	Payment UNKNOWN, PG 상태 조회
Timeout 후 5분 내 승인 확인	재고 확정, 주문 성공
Timeout 후 5분 내 승인 미확인	재고 해제, 주문 만료
주문 만료 후 늦은 승인 확인	결제 취소/환불
결제 승인 후 재고 확정 실패	재고 예약이 살아 있으면 재시도
재고 예약 만료 후 결제 승인 확인	결제 취소/환불

중요: 모든 실패를 똑같이 취소하지 않는다.
결제 승인 후 재고 확정 실패는 바로 환불하면 안 된다. 재고 예약이 아직 살아 있으면 재시도해서 성공으로 수렴시키는 게 맞다.

12. 멱등성

Kafka는 같은 메시지를 두 번 전달할 수 있다. PG Webhook도 중복으로 올 수 있다. 사용자의 결제 요청도 중복으로 들어올 수 있다.

그래서 이 설계에서는 "같은 요청이 여러 번 들어온다"를 기본값으로 둔다.

-- 중복 방지
orders:
  UNIQUE(drop_id, user_id)

inventory_reservations:
  UNIQUE(order_id)

payment_attempts:
  UNIQUE(order_id, attempt_no)
  UNIQUE(idempotency_key)

inbox_events:
  UNIQUE(event_id)

outbox_events:
  PRIMARY KEY(event_id)

PG 승인 요청에도 idempotency key를 붙인다.

idempotencyKey = payment:{orderId}:{attemptNo}

상태 전이도 조건부로 처리한다.

UPDATE inventory_reservation
SET status = 'SOLD'
WHERE order_id = :orderId
  AND status = 'RESERVED';   ← 이미 SOLD면 UPDATE 안 됨

이미 SOLD인 상태에서 같은 요청이 한 번 더 와도 결과는 달라지지 않아야 한다. 이것이 Saga를 운영 가능한 구조로 만드는 핵심이다.

13. 사용자에게는 어떻게 보여줄까

핵심 주문/결제 API는 평균 200ms 이하를 목표로 한다. 따라서 결제 승인과 재고 확정까지 한 API에서 모두 기다리면 안 된다. API 응답은 접수와 완료를 분리한다.

주문서 진입

POST /orders
→ 200 OK
{
  "orderId": "ord_123",
  "status": "WAITING_PAYMENT",
  "expiresAt": "2026-04-26T12:05:00+09:00"
}

결제 승인 요청

POST /orders/{orderId}/payments/confirm
→ 202 Accepted
{
  "orderId": "ord_123",
  "status": "PAYMENT_IN_PROGRESS",
  "message": "결제 승인 처리 중입니다."
}

상태 조회 (Polling / SSE)

GET /orders/{orderId}
→ 200 OK
{
  "orderId": "ord_123",
  "status": "PAID",
  "paymentStatus": "APPROVED",
  "inventoryStatus": "SOLD"
}

사용자는 중간에 PAYMENT_IN_PROGRESS 또는 PAYMENT_UNKNOWN을 볼 수 있다. 다만 10분 안에는 성공 또는 실패 계열의 최종 상태로 안내한다.

만약 PG 확인이 계속 지연된다면, 구매는 실패로 확정하고 이후 결제 승인 사실이 확인될 경우 자동 환불한다.

14. 최종적으로 내가 선택한 설계

대기열을 통과한 사용자만 주문서에 진입한다.
주문 생성 시 Inventory Service가 재고를 5분간 RESERVED 처리한다.
결제 승인 요청 API는 PG 응답을 기다리지 않고 202로 반환한다.
PG 호출은 Payment Service가 비동기로 수행한다.
PG Timeout은 FAILED가 아니라 UNKNOWN으로 저장한다.
UNKNOWN은 PG 상태 조회와 Webhook으로 확정한다.
5분 안에 승인 확인 시 주문 성공, 확인 실패 시 주문 만료와 재고 해제.
만료 이후 늦은 승인 확인은 주문 성공이 아니라 환불로 보상한다.
모든 이벤트와 명령은 Outbox, Inbox, Idempotency Key로 중복과 유실을 방어한다.

이 설계는 즉시 일관성을 포기한다. 대신 최종 일관성을 선택한다.

하지만 이 도메인에서 더 중요한 조건은 지킨다.

초과 판매를 막는다.
외부 PG 장애가 내부 트랜잭션을 붙잡지 않는다.
결제 Timeout을 섣불리 실패로 처리하지 않는다.
주문은 최종적으로 성공 또는 실패로 수렴한다.
사용자는 제한 시간 안에 결과를 받는다.

Claude Code를 모니터링 해보자!: claude-analytics 개발기

rootTiket — Sat, 7 Mar 2026 19:11:50 +0900

들어가며

지난 글에서는 초기 창업 팀이 파편화된 AI 사용에서 벗어나기 위해 manifest.md와 YAML 기반의 명세서를 도입하고, 팀의 컨벤션에 맞게 Claude Code를 통제하는 '컨텍스트 엔지니어링' 과정을 공유했습니다.

그렇게 나름의 규칙을 세우고 매번 수정하며 '컨텍스트 엔지니어링 회고'를 진행하고 있습니다. 하지만 회고를 진행할 때마다 /resume 으로 대화 흐름을 보고 피드백하기를 반복하는 과정이 불편했고, 생산성을 위해 오히려 더 번거로운 일을 하는 것은 아닌가? 하는 의문이 들었습니다. 이 글은 claude code의 대화 내용을 웹으로 직접 보기위한 대시보드를 만들기까지의 회고 입니다.

1. 터미널 창을 벗어나고 싶다는 단순한 귀찮음

Claude Code는 기본적으로 CLI 기반으로 동작합니다. 그러다 보니 지난주 대화 기록을 보며 리뷰를 하려면 까만 터미널 창에서 마우스 휠을 한참 올리며 맥락을 파악해야 했습니다.

게다가 대화 효율을 측정할 수 있는 유일한 단서인 토큰 사용량은 그저 "제한량의 몇 %를 사용했다" 정도로만 표기되었습니다. 매 세션마다 이 퍼센티지를 따로 기록하고 추적하는 건 Agent 도입으로 얻은 생산성을 되려 깎아먹는다고 생각했습니다.

"터미널에 갇힌 대화 기록과 애매한 토큰 사용량을 웹에서 좀 편하게 볼 수 없을까?" 하는 개발자 같은 귀찮음과 불편함이 이 프로젝트의 시작이었습니다.

2. 백엔드 개발자의 Antigravity 찍어 먹어보기

저는 주로 Java와 Spring Boot 생태계에서 백엔드 개발을 해왔습니다. 그렇다 보니 Node.js 생태계나 IDE 환경에서 AI 에이전트가 코드를 직접 작성해 주는 워크플로우를 써볼 기회가 거의 없었습니다.

프론트엔드 개발하시는 분들이 Cursor로 편하게 작업하시는 걸 항상 부럽게만 생각했는데, 이렇게 아이디어가 나온 김에 저도 Antigravity를 써보고자 했습니다. 학생 신분이기 때문에 추가 과금이 필요 없었고, Opus도 제약적이게나마 사용할 수 있다는 점이 매력적이었습니다.

개발 자체는 수월했습니다. 대화 로그 포맷을 알려주고 룰을 잡아주니 에이전트가 훌륭하게 파싱 코드를 짜주었습니다.

처음 개발했을때 모습입니다

생각보다 너무 빠르게 만들어줘서 놀랐습니다. 2시간도 걸리지 않고 만들었다는게 참 놀라웠습니다.

그런데 오히려 의외로 문제가 됐던 것이 '파일 경로'였습니다. 프로토타입을 만들자마자 지인에게 배포를 했었는데, 다른 PC에서는 .claude 폴더를 찾지 못해서 실행이 안 되는 이슈가 있었습니다. AI가 아무리 로직을 잘 짜준다고 한들, 결국 실행 환경을 제어하고 보장하는 것은 온전히 인간 개발자의 몫이라는 걸 다시금 깨달았던 순간이었습니다. (이 경로 문제는 어찌저찌 잘 해결했습니다.)

3. 컨텍스트가 짧으면 효율적인 걸까?

완성된 대시보드를 처음 로컬에 띄웠을 때, 대시보드에서 가장 먼저 보려고 했던 지표는 '컨텍스트의 크기'였습니다. 우리가 컨텍스트 엔지니어링을 잘했다면 불필요한 토큰 낭비가 줄었을 테니, 전체 컨텍스트 길이가 짧게 나올 것이라는 단순한 가설이었습니다.

하지만 데이터를 시각화해서 보다 보니 이 지표에 치명적인 허점이 있었습니다. Claude가 생성해 내는 결과물(Output) 역시 컨텍스트 길이에 포함된다는 사실이었습니다.

가령 AI가 요구사항을 한 번에 완벽하게 이해하고 수백 줄의 훌륭한 코드를 반환했다면 전체 컨텍스트 길이는 길어집니다. 길이는 길지만 효율은 좋은 상태죠. 반대로 대화는 짧게 끝났지만 엉뚱한 코드만 뱉어냈다면 수치상으로는 '효율적'인 것으로 오해할 수 있습니다.

결국 단순히 '숫자가 적다 = 효율적이다'라는 1차원적인 지표로는 이 복잡한 대화를 평가할 수 없다는 것을 깨달았습니다. 애매한 지표를 넣고 나니, 오히려 "우리가 진짜 집중해야 할 지표가 무엇인가?"를 다시 생각하게 된 경험이었습니다.

4. 점수표 대신 워크플로우 시각화하기

하지만 이 툴을 만든 원래의 목적은 충분히 달성하고 있었습니다. 바로 '시각화'입니다.

고심해서 만든 CLAUDE.md 문서에 적힌 대로 잘 로드되고 있는지, /feature나 /fix 같은 Skill들이 의도한 타이밍에 정확하게 워크플로우를 타고 작동하고 있는지. 이전에는 까만 터미널 창에서 ctrl + o를 눌러가며 일일이 확인해야 했던 것들을 이제는 대시보드를 통해 눈으로 직접 확인할 수 있게 되었습니다.

이 프로젝트는 무조건적인 효율을 숫자로 쾅 찍어주는 절대적인 평가 도구가 아닙니다. 그보다는 우리가 주입한 컨텍스트들이 대화 속에서 어떻게 흘러가는지 궤적을 보여주는 시각화 도구에 가깝습니다.

최근에는 Anthropic에서 공개한 Claude Skill Building Guide 를 보며 턴 수를 줄이거나, 자율적으로 실행하는 시간의 비율을 측정하는 방식으로 지표를 업데이트 해 나가고 있습니다. 하지만 정량적인 측정 방식이 상대적으로 효율을 대변하기에는 어렵다고 생각하여 의도한대로 동작하는지 판단하는 모니터링 용도에 초점을 두고 개발해 나가고자 합니다.

마치며

사실 이 프로젝트를 깃허브에 퍼블릭으로 공개하고 이 글을 쓰는 지금도 마음 한편에는 불안함과 머쓱함이 있습니다.

저는 AI 프롬프트 전문가도 아니고, 데이터를 전문적으로 공부해보지도 않은 그냥 대학생이기 때문입니다. 개발을 하다가 "이거 너무 불편한데?"라는 생각에 AI의 힘을 빌려 뚝딱 만들어본 툴입니다.

하지만 이 툴을 공개해보는 이유는, 저희 팀과 똑같은 고민을 하고 있을 누군가에게 작은 도움이 되길 바라기 때문입니다. AI 코딩 어시스턴트를 실무에 도입하며 "우리 팀, 지금 잘 쓰고 있는 걸까?" 막막해하던 분들이 계신다면, 이 툴을 통해 여러분의 대화 로그를 한 번쯤 시각화해 보시길 추천합니다.

긴 글 읽어주셔서 감사합니다!

GitHub - rootTiket/claude-analytics (직접 써보시고 많은 피드백을 남겨주시면 큰 힘이 될 것 같습니다!)

초기 창업 팀에서 Claude Code 를 도입한 방법

rootTiket — Sun, 15 Feb 2026 18:16:27 +0900

1. 들어가며: 바이브 코딩의 유행과 현실적인 고민

2025년 개발 생태계를 뒤흔든 가장 뜨거운 화두는 단연 바이브 코딩이었을 것입니다. 초기 창업팀에서 프로젝트를 시작하는 개발자이자 본격적인 커리어를 준비하는 취업준비생 입장에서, 코드를 뚝딱 만들어내는 AI의 발전 속도는 경이로움을 넘어 일견 채용에 대한 두려움으로 다가오기도 했습니다.

하지만 막연한 불안감에 빠져있기보다는 시각을 조금 바꿔보기로 했습니다. "어떻게 하면 이 강력한 AI를 활용해 우리 팀의 개발 생산성을 극대화할 수 있을까?"

실무에 AI를 도입하며 마주한 현실은 단순히 코드를 복사하는 것만큼 간단하지 않았습니다. 팀원 각자가 파편화된 방식으로 AI를 사용하다 보니, 오히려 팀의 코드 컨벤션을 맞추고 프로젝트 전체의 통일성을 유지하는 데 더 많은 리뷰와 수정 비용이 들 것 같다는 우려가 생겼습니다.

신뢰할 수 있는 서비스를 만들기 위해서, AI의 결과물을 그대로 수용하기보다는 AI가 우리 조직의 언어와 프레임워크 구조 안에서 '제대로' 동작하도록 규칙을 잡아주는 과정이 필요하다는 결론을 내렸습니다.

즉, 단순한 툴 사용을 넘어 조직 차원에서의 체계적인 AI Co-Work 환경이 필요했습니다. 이 글에서는 우리 팀이 Claude Code를 활용해 어떻게 팀 컨벤션에 맞춘 컨텍스트 엔지니어링을 수행했고, 파편화된 AI 사용의 한계를 극복하며 개발 생산성을 어떻게 끌어올리고 있는지 그 과정을 공유하고자 합니다.

2. 컨텍스트 엔지니어링의 목표

팀이 함께 사용할 수 있도록 해야한다.

아직 학생이거나, AI툴을 도입하기 시작한 초기 조직은 조직내 개인이 룰을 정하고 코드를 작성합니다. 이렇게 되면 같은 프로덕트를 만들더라도, 내리는 명령의 종류가 제각각이게 됩니다.

저희는 지금까지 컨벤션이라는 이름아래 동일한 규칙을 지키며 코드를 작성해 왔습니다. AI의 컨텍스트 문서 또한 팀의 규칙을 따르고 이를 일관되게 적용할 수 있어야 합니다.

Before: 개별 팀원이 각자의 스타일로 프롬프팅 -> 결과물의 일관성 부족
After: 팀이 합의한 아키텍처, 네이밍 규칙, 기술 스택을 담은 '공통 컨텍스트' 주입 -> 누가 요청해도 동일한 규격의 코드 생성

또한 이와 같은 컨텍스트 문서를 작성하기 위한 규칙이 마련하여 이 역시 팀에서 지키며 수정할 수 있도록 구성했습니다.

토큰을 최대한 아끼면서 구현의 일관성을 가져야 한다.

흔히 LLM을 사용할 때 채팅하듯 여러 번 대화를 주고받으며 수정하는 방식을 사용합니다. 하지만 이 방식은 맥락을 잃고 효율적이지 못합니다.

맥락의 휘발: 대화가 길어질수록 AI는 초기 요구사항이나 전체 구조를 놓칠 가능성이 큽니다.
비용 문제: 수정 요청을 반복할수록 누적된 토큰 양이 늘어나 비용과 시간이 낭비됩니다.

따라서 미리 정의된 맥락을 주입하고, 필요할 때 마다 어떤 문서를 주입해야할지 명시하여 구현의 일관성과, 토큰 효율을 극대화 시키고자 했습니다.

3. AI를 팀원으로 만들기

글에 들어가기 전 해당 글은 Toss의 소프트웨어 3.0 시대를 맞이하며 라는 글이 큰 도움이 됐습니다. 초기에 구성하신다면 읽어보시길 추천드립니다.

아키텍처 설계: Toss의 레이어드 구조 적용

Slash Command = Controller 역할
Sub-agent = Service Layer (여러 기능 조합)
Skills = 단일 책임 원칙을 따르는 컴포넌트
MCP = 외부 시스템과의 Adapter
CLAUDE.md = 프로젝트 설정 파일 (package.json 역할)

이 개념을 프로젝트에 다음과 같이 적용했습니다.

1. Boot Sequence: manifest.md가 부트로더 역할

AI는 매 대화마다 어디서부터 읽어야 할지 모릅니다. 따라서 우리는 manifest.md를 부트로더로 설계했습니다.

# manifest.md
boot_sequence:
  - order: 1
    file: .claude/core/essential-rules.yaml
    purpose: Load constraints & stack
  - order: 2
    file: .claude/memory.md
    purpose: Load context
  - order: 3
    file: .claude/CLAUDE.md
    purpose: Load index

AI는 실행 시 항상 manifest.md를 먼저 읽고, 정해진 순서대로 문서를 로드합니다. 이는 마치 애플리케이션의 main() 함수처럼 작동합니다.

2. Lazy Loading: 필요한 것만 로드시키기

CLAUDE.md는 변하지 않는 정보만 담아야 합니다.

이를 적용하여 문서를 세 단계로 분류했습니다:

Index

1. Core (Must Read): 반드시 읽어야 하는 변하지 않는 규칙
- core/essential-rules.yaml: Non-negotiable Rules & Tech Stack
- memory.md: Current Context & Status
2. Design (Read on Demand): 설계/구현 시에만 필요한 문서
- core/system-design.yaml: Architecture, API, Entity Rules
3. References (Lazy Load): 필요할 때 사용하는 상세 가이드
- references/conventions/coding-style.md: 코딩 스타일 가이드
- references/data-model/domains/: 도메인 엔티티 정보

이를 통해 불필요한 토큰 소비를 줄이고, AI가 핵심 컨텍스트에 집중할 수 있도록 했습니다.

3. Skills: 단일 책임 원칙

반복적인 작업을 Skills로 정의했습니다:

Skills

/feature: 새로운 기능 구현
/fix: 버그 수정
/refactor: 리펙토링
/docs: 문서화

각 Skill은 명확한 책임을 가지며, 사용자는 /feature라고 입력하는 것만으로 정해진 워크플로우를 실행할 수 있습니다.

Ask Protocol 정의하기

AI 에이전트는 구현, 혹은 수정 중 불확실한 상황에서 질문할 수 있습니다.

이를 적용하여 "Ask Protocol"을 정의했습니다:

Agent Behavior (Protocol)

Ask Protocol: If requirements are ambiguous, risky (e.g., deletion), or deviate from conventions, STOP and ASK the user immediately.

AI는 다음 상황에서 반드시 사용자에게 질문해야 합니다:

요구사항이 애매할 때
데이터 삭제와 같이 위험한 작업일 때
기존 컨벤션을 벗어나는 작업일 때

이는 모든 분기를 미리 정의할 필요 없이, 중요한 순간에 사용자 판단을 요청하는 방식으로 작동합니다.

Feature Spec: Docs First 워크플로우

Toss 블로그에서는 "변하지 않는 정보만 문서화하라"고 했지만, 우리는 한 가지를 추가했습니다: Feature Spec입니다.

각 기능은 구현 전에 YAML 형식의 명세서를 먼저 작성합니다

예를들어:

# create_remote_waiting.yaml
meta:
  id: FEAT-WAITING-002
  title: 원격 웨이팅 등록 (Remote Waiting Registration)
  type: Feature

overview:
  summary: >
    앱 사용자가(Member)가 직접 특정 부스에 원격으로 웨이팅을 신청하는 기능입니다.
  user_story: >
    As a Member, I want to register for waiting remotely via the app,
    so that I can enjoy the festival without physically standing in line.

technical_spec:
  api:
    - method: POST
      path: /api/v1/booths/{boothId}/waitings
      auth: MEMBER

  validation_rules:
    - "요청자는 로그인한 회원(MEMBER)이어야 한다."
    - "부스가 존재하며, 운영 상태가 'OPEN'이어야 한다."
    - "동일한 부스에 이미 'WAITING' 상태인 내역이 존재하면 안 된다."

  testing_strategy:
    happy_path:
      - "로그인한 멤버가 원격 줄서기가 허용된 OPEN 부스에 웨이팅 등록 성공"
    edge_cases:
      - "부스가 CLOSED 상태일 때 예외 발생 (BOOTH_NOT_OPEN)"
      - "이미 웨이팅 중인 회원이 중복 등록 시도 시 예외 발생"

이 문서는 기본적으로 구현 중 변경하지 않는 것을 원칙으로 합니다. 만약 문서를 구현 중간에 수정해야 한다면 AI의 구현을 멈추고, 문서를 수정 후 새 대화를 열어 다시 구현할 수 있도록 합니다.

문서 포맷은 yml로

AI는 구조화 된 포맷일 수록 맥락을 이해하기 쉽고, 토큰 효율적으로 구성할 수 있습니다. 흔히 AI 친화적인 포맷으로 md, xml 등을 꼽습니다.

초기에는 claude는 xml 형식을 잘 이해한다는 글을 읽고, xml 형식으로 spec 문서를 작성했습니다. 하지만 xml 포맷은 치명적인 단점이 있었는데요.

1. XML은 인간에게 친화적이지 못하다.

문서는 기본적으로 인간이 작성할 수 있어야 한다고 생각했습니다. code first가 아닌 docs first로 요구사항을 문서에 먼저 반영하고 이를 구현하게 하는 것이 기본 흐름이기 때문입니다.

문서는 편집하기 쉽고, 빠르게 변경해야 하기에 인간에게 친화적이지 못한 XML 포맷은 적절하지 못하다고 생각하여 다른 포맷으로 변경하기로 했습니다.

초기 XML로 작성한 에러처리 spec

2. 마크다운은 자칫 컨텍스트를 나열할 수 있다.

다음으로 AI가 선호하는 포맷은 마크다운이 있었습니다. 실제로 많은 프로젝트에서 마크다운을 사용하고 있는것으로 알고있었습니다. 또한 수정하기 용이하기 때문에 사용을 고려했으나, 모든 상황에서 사용하기에는 어려움이 있다고 판단했습니다.

그 이유는 다음과 같습니다.

1. 불필요한 컨텍스트가 포함될 수 있다.

마크다운은 익숙하게 사용해 왔기 때문에, 문서를 작성하게 되면 서술하는 방식으로 사용되기 쉬울 것이라고 생각했습니다.

맥락을 규격화 해야하는 상태에서 무분별하게 서술하는 방식은 애매한 표현, 그리고 불필요하게 사용되는 연결어 등으로 인해 할루시네이션과 토큰 사용량 면에서 불리할 것이라고 생각했습니다.

2. 위계를 한눈에 보기에 다소 어렵다.

마크다운은 보통 # 을 이용해서 글의 맥락을 나타냅니다. 하지만 이 역시 3계층만 표현할 수 있다는 점에서 위계 표현에 제한이 있다고 생각했습니다.

또한 위계를 한눈에 보기에 다소 불편하다고 생각했습니다.

3. 그래서 최종 선택은 YAML(yml)

앞선 XML과 마크다운의 단점을 보완하면서도, AI와 팀원 모두에게 가장 효율적인 포맷을 고민한 끝 YAML을 컨텍스트 문서의 표준으로 도입하기로 결정했습니다. 그 이유는 다음과 같습니다.

1. 강제되는 구조화와 압도적인 토큰 효율

YAML은 Key-Value 형태를 기반으로 합니다. 이는 문서를 작성하는 팀원으로 하여금 자연스럽게 '줄글 형태의 서술'이 아닌, 핵심 키워드와 '조건(명세)' 위주로 작성하도록 유도합니다. 불필요한 조사나 연결어가 배제되므로 토큰 사용량을 획기적으로 줄일 수 있고, AI 역시 애매한 문장 대신 명확한 속성값으로 맥락을 파악하기 때문에 할루시네이션이 크게 줄어듭니다.

2. 한눈에 들어오는 직관적인 위계(Hierarchy) 표현

마크다운이 # 기호를 통해 다소 평면적인 계층 구조를 가졌다면, YAML은 들여쓰기(Indentation)만으로 복잡한 비즈니스 로직이나 엣지 케이스의 Depth를 무한하고 시각적으로 깔끔하게 표현할 수 있습니다. 덕분에 문서의 전체적인 뼈대와 세부 조건을 한눈에 파악하기 쉬워, 'Docs First'를 실천하며 문서를 리뷰하고 수정하는 과정이 훨씬 수월해졌습니다.

As-Is

To-Be

4. 성과

성과: 모델 1회 요청당 토큰 사용량을 최대 25% 절감 (제한량 기준 20% → 15% 수준으로 최적화)

실제 구현 단계에서 적용했을 때, 기존에 컨벤션이 맞지 않아 자주 변경해야 했던 것에 비해 확실히 컨벤션에 맞게 잘 작성해줍니다.

아키텍처 설계 단계에서 의도했던 manifest 를 통한 라우팅도 적절히 이루어지고 있어요

엄밀하지 않지만 단순한 API 구현 기준으로 1회당, 20%이상 사용된 토큰 사용량이 10% 대에서 안정적으로 구현이 가능해졌습니다.

추가적으로 한 세션에서 한번의 slach command(Skill)을 사용하는것으로

- 이전보다 수정 요청 빈도 감소 (평균 5회 -> 3회미만)

- 컨텍스트가 늘어지지 않아 할루시네이션 감소

하는 효과도 얻을 수 있었습니다.

5. 회고

회고는 매주 하기

매주 저는 컨텍스트 엔지니어링 회고를 진행하고 있습니다.

현재 구현에서 불만족 스러운 부분은 있는가, spec 문서 중 중복되거나, 혹은 명확하지 않은 부분이 있는지 등을 회고하고 있어요

이렇게 매주 새로운 정보가 있다면 적용해보고 어땠는지 고민하며 수정을 거듭하고 있습니다:

부족한 점이 아직 많다

현재 문서를 기반으로 한 엔지니어링에 초점이 되어있으나, hook, mcp같은 고차원 적인 기능을 바로 도입하고 있지는 않습니다.

최근 알게된 클로드 코드 해커톤 우승자의 글을 바탕으로 더욱 고도화 시키기 위해 노력중이에요

더불어 엔지니어링을 위한 툴도 만들면서 더 좋은 환경을 만들기 위해 노력중입니다.

https://github.com/rootTiket/claude-analytics 에서 완성된 프로덕트가 있으니 관심있으시다면 둘러봐주세요 :)

GitHub - rootTiket/claude-analytics

Contribute to rootTiket/claude-analytics development by creating an account on GitHub.

github.com

spec문서 사이의 관계를 시각화 해주는 웹

세션 별 내용을 볼 수 있는 웹

마치며

지금처럼 AI 와 human in loop으로 작업하기 시작한지 3주가 지나가고 있습니다.

이를 통해 저희 팀은 다음과 같이 변화했어요

1. 명확한 문서 작성을 통한 기획 - 개발 간 도메인 지식 격차 해소

2. 토큰 사용량 감소 및 팀원 모두 AI를 통한 생산성 향상

부족하지만 긴 글 읽어주셔서 감사합니다!

NCP Finance 환경에서 GitHub Actions로 CI/CD 구축하기

rootTiket — Sat, 31 Jan 2026 17:28:03 +0900

인턴때 진행한 NCP Finance 환경에서 Bastion Host를 따로 두지 않고, Cloud Functions을 활용해 CI/CD 파이프라인을 구축한 과정을 공유해보고자 합니다. 어쩌다가 NCP Finance 환경을 사용하게 되신 분들은 도움이 되셨으면 좋겠습니다.

NCP 뿐 만 아니라 private subnet 환경에서 CICD를 구축해보고 싶으신 분들도 한번 참고해보시면 좋을 것 같습니다.

1. 구축 배경

프로젝트의 인프라 환경은 다음과 같은 제약이 있었습니다.

환경: NCP Finance
네트워크: 모든 애플리케이션 서버는 Private Subnet에 위치
접근 제어: 외부 인터넷에서 내부 서버로의 SSH(22번 포트) 접근 불가

보통 이런 환경에서 자동 배포를 구성하려면 두 가지 방법 중 하나를 선택합니다.

Bastion Host 사용: Public Subnet에 중계 서버를 띄워두고 터널링으로 접근합니다.
- 이 방법이 가장 정석적인 방법이 아닐까 생각합니다. 하지만 비용문제로 인해 사용할 수 없었습니다.
NCP SourcePipeline 사용: 클라우드 벤더가 제공하는 CI 도구를 사용합니다.
- 문제: 확인해 보니 빌드 환경이 Ubuntu 16.04 기반이었습니다. 최신 라이브러리와 Python 3.10 이상을 사용해야 하는 우리 프로젝트와 호환되지 않았고, 코드 저장소를 별도로 관리해야 하는 번거로움이 있었습니다.

우리는 익숙한 GitHub Actions를 그대로 쓰면서, 추가 비용 없이 내부망에 배포할 방법이 필요했습니다.

2. 해결 아이디어: Serverless를 트리거로 사용하기

해결책으로 떠올린건 Cloud Functions를 활용하는 것이었습니다(Cloud Functions 란?). Cloud Functions는 VPC 내부 리소스에 접근할 권한을 가질 수 있고, 호출될 때만 과금되므로 Bastion 서버보다 훨씬 경제적입니다.

전체적인 아키텍처 흐름은 다음과 같습니다.

GitHub Actions (빌드/Push) -> API Gateway -> Cloud Functions (VPC 내부) -> Private Server (SSH 명령)

3. 구축 과정

Step 1. 배포 대상 서버(VM) 설정

먼저 배포 대상 서버에 배포 스크립트(deploy.sh)를 작성해 둡니다. 외부에서 복잡한 명령어를 주입하는 것보다, 내부 스크립트를 실행만 하는 방식이 관리하기 편하고 오류 가능성도 적습니다.

무엇보다 외부에서 명령어를 직접 운영서버에 injection 할 경우 보안적으로 위협이 된다고 생각했기에 Cloudfunctions는 최대한 단순한 행위만 할 수 있도록 구성했습니다.

/home/ubuntu/deploy.sh

#!/bin/bash
set -e

# 1. 최신 이미지 Pull 
docker pull <레지스트리 주소>

# 2. 기존 컨테이너 종료 및 정리
echo "Stopping containers..."
cd <docker compose 파일 위치>
docker compose down

# 3. 서비스 재시작
echo "Deploying new version..."
docker compose up -d 

# 4. 불필요한 이미지 정리
docker image prune -a -f

Step 2. Cloud Functions 생성

Cloud Functions가 Private Server와 통신하려면 반드시 동일한 VPC에 배치되어야 합니다.

Subnet 생성: Cloud Functions용 Subnet을 생성할 때, 배포 대상 서버와 통신 가능한 대역(Private)을 선택합니다.
Action 생성: Python 등의 런타임을 선택하고 코드를 작성합니다. 이 함수는 SSH로 대상 서버에 접속해 sh deploy.sh를 실행하는 역할만 수행합니다.

설정 체크포인트:

VPC: Target Server와 동일한 VPC
ACG 설정: 배포 대상 VM의 AGC에서 Cloud Functions의 주소로 22번 포트를 열어주어야 합니다.
cloudfunctions-vpc<VPC_ID> 형식으로, Cloud Functions를 만들었다면 자동완성 추천이 나오는 걸로 설정해줍니다.
Zone은 KR-2로 설정합니다.

Step3. Action 코드 작성 및 패키징

SSH 접속을 위해 Python의 paramiko 라이브러리를 사용합니다. NCP Cloud Functions는 기본 라이브러리 외의 외부 라이브러리(pip install 필요 항목)를 사용할 경우, 반드시 로컬에서 패키징하여 Zip 파일로 업로드해야 합니다.

디렉토리 구조:

deploy-function/
├── __main__.py      # 메인 실행 코드
├── requirements.txt # 의존성 목록
└── package/         # pip install로 설치된 라이브러리 폴더

__main__.py 작성 예시:

import sys
import os
# 패키지 경로 추가
sys.path.append(os.path.join(os.path.dirname(__file__), 'package'))

import paramiko

def main(args):
    host = "10.0.x.x"  # Target Server의 Private IP
    port = 22
    username = "root"
    password = args.get("SERVER_PASSWORD") # 혹은 SSH Key 방식 사용

    client = paramiko.SSHClient()
    client.set_missing_host_key_policy(paramiko.AutoAddPolicy())

    try:
        # 1. SSH 접속
        client.connect(host, port=port, username=username, password=password)
        
        # 2. 배포 스크립트 실행
        stdin, stdout, stderr = client.exec_command("sh /home/ubuntu/deploy.sh")
        
        # 3. 결과 리턴
        result = stdout.read().decode()
        error = stderr.read().decode()
        
        if error:
             return {"payload": {"status": "error", "log": error}}
        return {"payload": {"status": "success", "log": result}}
        
    except Exception as e:
        return {"error": str(e)}
    finally:
        client.close()

Step 4. API Gateway 연결: 외부 트리거 생성

Cloud Functions를 만들었다면, 이제 GitHub Actions가 이 함수를 호출할 수 있도록 해야합니다.

API Gateway 콘솔에서 처음부터 세팅할 수도 있지만, Cloud Functions의 [트리거] 탭을 이용하면 훨씬 간편하게 연동할 수 있습니다.

1. 트리거 생성 (Cloud Functions Console)

작성한 Action의 상세 화면에서 [트리거] 탭으로 이동해 + 트리거 추가 버튼을 클릭합니다.

타입: API Gateway
동작: 신규 생성 (기존에 만들어둔 Product가 있다면 선택해도 됩니다)
옵션:
- 인증: '사용(API Key 필요)' 체크
- 스테이지: v1 또는 real 등 식별 가능한 이름 입력

2. 경로(Path) 설정과 /{type+}

URL 경로를 설정할 때 주의할 점이 있습니다. 단순히 /deploy로 끝내는 것이 아니라, 뒤에 /{type+}를 붙여주어야합니다.

설정 예시: /deploy/{type+}
이유: API Gateway가 Cloud Functions로 데이터를 넘길 때, JSON 포맷(Body)을 온전히 전달받기 위한 예약어 설정입니다. 이 설정을 하지 않으면 GitHub Actions에서 보낸 Payload가 함수 내부로 제대로 전달되지 않는 경우가 발생할 수 있습니다.

3. API 배포 (Publish)

NCP 콘솔 > API Gateway 메뉴로 이동합니다.
방금 생성된 Product를 선택하고 [API 배포] 버튼을 클릭합니다.
앞서 설정한 스테이지를 선택하여 배포를 완료합니다.

4. API Key 및 URL 확인

GitHub Actions에 등록할 두 가지 정보를 확보합니다.

Invoke URL: API Gateway 콘솔의 [스테이지] 메뉴에서 배포된 URL을 확인합니다.
- 형식: https://{random-id}.apigw.ntruss.com/deploy/v1/json
- (참고: /{type+}를 설정했으므로 호출 시 끝에 /json 등을 명시해야 데이터가 정상 바인딩됩니다.)
API Key:
- [API Gateway > API Keys] 메뉴로 이동하여 API Key 생성을 클릭합니다.
- 생성된 키를 복사해 둡니다.
- API Key들은 별도 탭에서 삭제도 가능하므로, 혹시 유출되었다면, 변경 혹은 삭제 후 재생성을 할 수 있습니다.

Step 4. API Gateway 및 GitHub Actions 연동

Cloud Functions는 기본적으로 내부망에 숨어있기 때문에, 외부에서 호출할 수 있도록 API Gateway와 연결합니다. 그리고 GitHub Actions 워크플로우 마지막 단계에서 이 API를 호출하도록 설정합니다.

.github/workflows/deploy.yml

YAML

  deploy:
    needs: build-and-push
    runs-on: ubuntu-latest

    steps:
      - name: Trigger Deployment via API
        run: |
          curl -X POST \
            -H "x-ncp-apigw-api-key: ${{ secrets.NCP_APIGW_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{}' \
            ${{ secrets.NCP_APIGW_API_URL }}

보안을 위해 API Key와 URL은 GitHub Secrets에 저장하여 관리합니다.

4. 마무리

정석적인 방법의 인프라 구축과는 조금 거리가 있어보였지만, 제약된 상황에서 얻은 성과는 다음과 같았습니다.

비용 절감: 상시 운영해야 하는 Bastion 서버 비용을 아끼고, 배포 시에만 실행되는 Serverless 비용으로 운영이 가능합니다.
개발 생산성: SourcePipeline의 제약에서 벗어나, 최신 Ubuntu 환경의 GitHub Actions를 자유롭게 사용할 수 있었습니다.

금융 클라우드나 보안이 엄격한 환경에서 CI/CD 구축을 고민하고 있다면, 별도의 서버 증설 없이 Serverless 리소스를 활용해 연결 고리를 만들어보는 방식을 추천합니다.

[Recap] CRAYON를 재출시하며

rootTiket — Mon, 10 Feb 2025 01:05:42 +0900

CRAYON?

CRAYON은 동아리 모집 올인원 솔루션이다.

동아리 원을 모집하고, 평가를 관리하는 과정에서 생기는 불편함을 해결하자는 목표로 기획되었다.

이제 회고를 해?

나는 CRAYON에 24년 여름부터 참여해왔다.

9월 1차 출시, 그리고 현재 2차 출시를 해오며 매번 회고해야겠다는 생각을 했지만 회고의 방향을 잡기 어려워 미뤄왔었다.

2차 출시를 한 지금 CRAYON에는 많은 이야기가 쌓였고, 개발자로서, 이야기를 공유하고 함께 공감했으면 하는 생각으로 회고를 작성하기로 했다.

1. CRAYON 시작
2. 1차 출시, 그리고 실패
3. 변화
4. 현재
5. 회고를 마무리하며

CRAYON 시작

정말 잘 가꿔진 화원인줄 알았는데...

이미 개발이 진행중인 CRAYON에 참여하기 시작하며 처음에는 잘 개발되고 있는 서비스겠지? 하는 막연한 기대가 있었다.

하지만 기획이 변경되면서 바꿔야 할 구조와, 뒤죽박죽 서버 아키텍처 등.. 새로 갖춰야 할 부분 투성이였다.

아 !구조를 새로짜면 되겠다!

그대로 진행하기 보다 db구조를 다시 정리하고, 아키텍처에 필요한 세팅을 문서화 해 두고 시작하는게 좋겠다고 생각했다.

상당 부분 개발되어 있었기 때문에 너무 많은 수정보다는 기능 개발에 초점을 두고, 이해하기 어려운 부분만 정리하고 개발하기 시작했다.

우리 잘 가고 있는거 맞겠지?

CRAYON은 "완벽보다 완성" 이었다.

우리가 생각한 완벽보다, 빠르게 완성해서 사용자들에게 직접 피드백을 받고 수용하는 것이 우리의 목표였다.

타협하더라도 동아리 모집기간에 늦지 않게 완성하고, 실제로 서비스하며 개선할 생각이었다.

이를 위한 7,8월은 정말 몰입 몰입 몰입이었다.

하루에 6시간 이상 개발에 몰두했고 기획과 서비스 방향성에 대해 고민했다.

완벽과 완성 사이에서 줄타기를 이어갔던 것 같다.

그 결과 모집 시즌에 맞춰 무사히 출시 할 수 있었다.

1차출시, 그리고 실패

냉정하게 말하자면 CRAYON의 1차출시는 실패였다고 생각한다.

기회가 아닌 위기였던 것

우리가 생각한 모집 시즌에 간과한 것은 생각보다 동아리 모집은 일찍 시작한다는 것이었다.

많은 동아리가 모집 중 == 기회라고 생각했지만 사실은 그렇지 않았다.

CRAYON은 모집 기간이 아닌 모집 전 미리 배포가 이루어졌어야 했다.

왜냐하면 동아리 모집은 사전에 준비가 필요하고, 그 과정에서 CRAYON의 필요성이 빛을 발할 수 있다.

동아리 모집이 이미 시작해버린 시점에서 기존의 모집 방식을 버리고 CRAYON을 선택 할 수 있는 동아리는 없었다.

생각하지 못한 버그들

기간 안에 완성하기 위해 기능을 줄이는 과정에서 많은 버그가 있었다.

주요 기능에서 발생했기에 빠르게 대처했지만 홍보가 마저 늦어진 시점에서 사용자를 모으기 어려웠다.

변화

다시 도전하면 그만이야

다시 도전하면 되지

25년 1월 2차 출시라는 새로운 목표를 세웠다.

1차출시에서 생각한 CRAYON의 부족한 점은 다음과 같다.

1. 어려운 UX

2. 안정성

3. 느린 기능

정말 모든 것을 자동화 할 수 있게 하기 위해 전체 메일 전송 기능도 추가하기로 결정했다.

성공적인 재단장

UX개선

우선 통일되지 않은 어려운 용어를 정리했다.

기존의 폼, 랜딩페이지 등 생소하고 어려운 단어를 지원서 양식, 홍보페이지 처럼 쉬운 단어로 변경하였다.

회원가입 과정도 간소화 했다.

CRAYON의 회원가입은 로그인 -> 동아리 생성 -> 홍보페이지 생성 으로 꽤 많은 단계를 거쳐야 했다.

이 부분은 사용자가 가입과정에서 이탈할 수도 있다는 생각이 들어 로그인 -> 동아리 생성만 해도 서비스를 이용할 수 있도록 개선했다.

실제로 "이거 만들어야 하는거야?(홍보페이지)" 같은 질문은 많이 줄어들었다.

그럼 다시 홍보해볼까?

동아리 하나부터 잡아보자

이전에는 여러 동아리에 콜드메일을 보내고, 최대한 이름을 알리는데에 집중했다.

하지만 이런 방식은 관심을 끌지 못했고, 차라리 실 사용 동아리를 만드는 것에 초점을 두기로 했다.

주변 동아리 운영하는 사람부터 시작해서 한개 동아리의 편안한 사용후기를 시작으로 넓혀가는 것이 가장 이상적이라고 생각한다.

우리의 스토리를 공유하기

이 회고를 본격적으로 쓰게 된 이유이다.

서비스에 대한 고민들을 공유하고 의견을 나눌 수 있다면, CRAYON은 더 발전할 수 있다고 믿는다.

회고를 마무리하며

그래서 앞으로 뭐해?

서비스 홍보

교내동아리부터 연합동아리까지 다양한 사용자를 구하고 있고 개발만큼이나 홍보에도 열을 올리고 있다!

개선 또 개선

그렇다고 개발을 쉴 수는 없다!

아직 성능 개선할 부분이 많이 남아있고 안정성 부분에서도 개선할 부분이 남아있다.

현재도 지속적으로 개발중이며, 중단없는 안정적인 서비스를 위해 노력하고 있다.

끝으로 처음으로 서비스에 대해 깊게 고민하며 참여해 본 프로젝트인 만큼 CRAYON은 내게 의미가 깊은 프로젝트이다.

아직 부족한 부분도 많지만, 부족한 만큼 더 열심히 채워나가고자 한다.

[Recap] 2024년 회고 : 방황하고 넘어지고, 다시일어나기

rootTiket — Fri, 3 Jan 2025 22:00:07 +0900

2024년은 어떤 한 해였어?

2024년을 한마디로 정의하자면 “성장통 가득한 한 해”라고 답하고 싶다.

성공보다 실패가 많았고, 웃기보다는 눈물이 더 많았던 한 해였다.

열심히 방황하고 넘어지고 다시 일어난 한 해를 회고해 보고자 한다.

1. 첫 서비스 출시
2. 갑자기 맞이한 휴식기
3. 넘어지기
4. 다시 일어서기
5. 그래서 2025년에는

첫 서비스 출시 : Fling

2024 2월에 2023년 1월부터 약 두 달간 진행한 프로젝트 Fling을 출시했다.

나에게 있어서는 처음으로 주 기능을 담당해서 개발하던 프로젝트 였기 때문에 큰 의미를 가진다.

지금 돌아보면 JPA나 자바의 기초도 잘 안되어 있어 메인 기능을 담당하기 꺼리고 있던 내게 첫 도전이었기 때문이다.

서비스 자체로는 조금 아쉬웠다

많은 사용자를 유치하고 싶다는 생각에 입학, 졸업시즌에 출시했으나 사용자가 많이 없어서 아쉬웠던 프로젝트 였다.

호기롭게 많은 트래픽을 받아보자는 계획이었지만 성공하지 못해 아쉬웠다.

무엇보다도 약 한 달 동안 서비스 한 이후 보수없이 서비스를 마무리 한것도 아쉬움으로 다가온다.

그래도 소중한 경험

비록 트래픽을 많이 받아보지 못했으나, 백엔드 네 명, 프론트엔드 세 명, 디자이너 세 명인 제법 규모있는 서비스를 경험할 수 있었다.

커뮤니케이션의 중요성과, 약간의 프론트엔드 지식의 도움을 받아 원활히 서비스를 마무리했던 경험은 이후 프로젝트에서도 도움이 되었다고 생각한다.

깃허브 링크 : https://github.com/Leets-Official/Fling-BE

GitHub - Leets-Official/Fling-BE: 꽃다발을 통한 추억 공유 서비스, Fling

꽃다발을 통한 추억 공유 서비스, Fling . Contribute to Leets-Official/Fling-BE development by creating an account on GitHub.

github.com

갑자기 맞이한 휴식기

2023 하반기 부터 시작했던 개발은 초반에는 즐거움의 연속이었다.

하지만 학기내 토이프로젝트 두개, 학업 병행, 그리고 이어진 정규 프로젝트 Fling을 거치며 즐거움 보다는 부담감, 막막함만 남기 시작했다.

"내가 정말 백엔드 개발로 나아가는게 맞는것인가?" "프론트엔드로 다시 넘어가서 제대로 개발해볼까?" 하는 생각에 사로잡혀서 무엇하나 제대로 시작하지 못한 3개월이었다.

실제로 Fling이후로 많은것을 하지는 않았다..

꼭 필요했던 시간

아까운 시간이었다는 생각이 들었다.

내가 정말 하고 싶어 하는 일인가, 아니면 지금까지 해온 것이 아까워서 지속하고 싶은 것일까 라는 생각 사이에서 스스로를 생각하는 시간이 반드시 필요했다.

이 시간이 있었기에 다시 개발에 몰입할 수 있었다고 생각한다.

마냥 쉬지는 않았다

개발을 멈춘 이 시간을 그냥 보내고 싶지는 않았다.

시간이 생긴 만큼 하고 싶던것, 그리고 몰입하고 싶은것에 몰입해보기로 했다.

1. 취미생활 다시 시작하기

취미생활이었던 사진을 다시 시작하고 마음의 여유가 생기기 시작했다.

그 덕에 내가 좋아하던 것을 하고 있을 때의 감정과, 원동력이 생기는 기쁨을 느낄 수 있었다.

2. 학업에 열중하기

학업에 열중하기는 일단 개발을 하지 않는다면? 본업인 학업에 집중해보자! 라는 생각으로 제대로 했던 것 같다.

이 당시에 공부법과 몰입하는 방법에 대한 고민을 많이 했고 스스로 시행착오를 겪어가며 나만의 공부 방법을 적립해 나갔던 시간이었다.

기록과 정리, 그리고 몰입의 중요성을 몸소 체험할 수 있었다.

결과도 좋았다

3. 자바 공부하기

자바공부도 멈추지 않았다. 이전 Fling에서 깨달았던 것은 나는 자바와 스프링을 정말 모르고 개발하고 있다는 사실이었다.

스터디를 만들고, 모던 자바 인 액션을 읽으며 내가 기존에 사용하지 않던 문법을 공부하며 내실을 다지는 기간으로 삼았다.

넘어지기

백엔드 개발을 지속하고 싶다고 결정한 이후에는 교내에 머물고 싶지 않다고 생각했다.

더 넓은 곳에서 다양한 사람들과 많은 것을 경험해보고 싶어 외부 활동에 지원하고자 했다.

1. 단기현장실습

지원 당시에는 빈약한 포트폴리오 이지만 나름 개발을 경험했다고 생각했다.(기획 - 출시를 한번 경험한 주제에)

학점 또한 낮지 않아 면접까지는 볼 수 있을것이라 생각했으나 내 오만이었다.

면접은 커녕 서류에서 탈락했다.

2. 연합동아리

연합동아리는 기업은 아니지만, 다양한 개발자들과 함께 개발하며 새로운 인사이트를 얻을 수 있다는 점이 매력적으로 다가와 지원을 결심했다.

무엇보다 "실제로 사용하는 서비스"를 만들고 싶다는 열망이 컸다.

이전 프로젝트들을 통해 깨달은 점은 단순히 서비스를 출시하는 것을 넘어 실제로 서비스를 유지보수하는 경험이 필요하다는 것이었다.

실제 사용자들을 위한 서비스에는 디자인과 탄탄한 기획이 핵심이라고 판단했고, 이에 디자이너와의 협업이 가능한 NEXTERS와 DND에 관심을 갖고 지원하게 되었다.

하지만 탈락

포트폴리오를 정리하고 지원했으나 서류도 통과하지 못했다.

열정만 가지고는 안된다는 것을 느꼈다. 자존감이 떨어지기 시작했던 시기였다.

3. ICT 인턴십

문을 계속 두드리면 언젠가 열리지 않을까 하는 생각에 지원하는 것을 멈추지 않았다.

현장실습과 마찬가지로 학점과 동시에 실무 경험을 할 수 있는 ICT 인턴십을 다음 목표로 정했다.

ICT인턴십은 총 세개의 기업에 지원 할 수 있고 앞에 두 활동과는 다르게 코딩테스트가 존재한다.

특이하게 기업에서 각각 다른 코딩테스트를 보는 것이 아니라 ICT인턴십 공통 코딩테스트를 진행한다.

하나의 코딩테스트만 보면 모든 기업에서 해당 결과를 반영하는 식이다.

코딩테스트 경험이 없어 자신 없었지만 해커랭크 라는 사이트에서 진행한다는 것을 확인하고 해당 사이트의 문제를 몇개 풀어보며 준비했다. (왜냐하면 코딩테스트 반영을 안하는 기업 두개, 반영하는 기업은 하나였기 때문에..)

좀 꾸준히 코딩테스트를 준비해야할 필요성을 느꼈다.

문제 다섯개 중에 결과는 4솔, 네 번째 문제에서 히든케이스를 통과하지 못해 완벽한 5솔은 하지 못했다.

아니 또 탈락이라고?

지금 회고해 보자면 포트폴리오의 문제가 컸다고 생각한다.

지금까지 해 온 것의 나열보다, 어떤 것을 이루어냈고 또 무엇을 개선했가에 대한

이야기가 담겨있지 않았기 때문이다.

하지만 그와 별개로 점점 자신감을 잃는 것은 어쩔 수 없었다.

제대로 된 분석 없이, 큰 개선 없이 여러번 반복해서 지원하고 실패한 것이 누군가에게는 미련한 일 처럼 보이겠지만

나에게는 넘어지는 연습과도 같았다.

어쩌면 성공보다도 더 값진 실패였다고 생각한다.

다시 일어나기

초여름부터 시작된 도전들이 모두 결실을 맺지 못했었다.

자신감은 낮아져가고 정말 이대로 괜찮은 것인지 고민하던 시기였다.

혼란함과 우울함을 잊기위해서라도 더 많은 것을 시도하고자 했다.

라인업지

친한 형과 헬스장에서 나눈 우연한 대화로 시작된 프로젝트.
"주점 웨이팅 서비스는 없을까?"라는 질문에서 출발했다.

이 프로젝트는 정말 많은 회고거리를 남겼다.
하나의 프로덕트가 많은 사용자에게 쓰이기까지 얼마나 어려운 과정을 거쳐야 하는지 뼈저리게 깨달았다.
세상에 날로 먹는 건 없었다.. 좋은 아이디어 였음에도 사용확정이 되기까지 너무나 많은 어려움이 있었다.

초반에는 호기롭게 시작한 프로젝트였다. 하지만 제대로 시작하기 위해서는 학생회의 사용 의사가 정말 중요했고,
5월에 기획을 시작한 프로젝트의 본격적인 개발은 7월이 되어서야 궤도에 올랐다.
그 시기는 정말로 어려웠다. 그런데도 "이 프로젝트가 그렇게 어려운 건 아니겠지?"라는 안일한 생각을 했던 것 같다.

라인업지를 진행하며 가장 크게 얻은 것은 단연 팀워크였다.
팀이 정말 잘 뭉치기가 얼마나 어려운지, 그리고 실제 사용자를 위한 프로덕트를 만들어내기 위해
고려해야 할 요소들이 얼마나 많은지 알게 된 시간이었다.

성공? 적인 출시

5월에 시작하며 "과연 잘 끝낼 수 있을까?" 걱정이 많았던 라인업지를 성공적으로 서비스했다.

엄청난 서버비용을 남기고 말이다...

처음으로 많은 트래픽을 경험하는 것이기 때문에 서버 성능에 대한 감이 없었다.
결국 오버스펙의 서버를 사용해 과도한 비용이 발생했다.
더 많이 공부했더라면, 더 세심하게 신경 썼더라면 하는 후회가 남았지만,
다음에는 이런 실수를 반복하지 않겠다는 다짐을 하게 되었다. 교육비라고 생각하기로 했다.

바쁜 시기였다는 핑계로 라인업지에 충분히 신경 쓰지 못한 스스로를 반성하게 된다.

https://github.com/Gachon-Table/GachonTable-BE

GitHub - Gachon-Table/GachonTable-BE: 가천대학교 가을 축제 주점 웨이팅 서비스

가천대학교 가을 축제 주점 웨이팅 서비스. Contribute to Gachon-Table/GachonTable-BE development by creating an account on GitHub.

github.com

Crayon 시작

7월, Crayon 이라는 서비스의 합류 제안을 받았다.

자존감이 낮아있었지만 잘 할 수 있을까? 하는 걱정이 앞섰다.

하지만 다른 사람의 코드를 받아 읽고, 이를 개선할 수 있는 경험을 할 수 있을것이라는 생각에 합류를 결정했다.

다시 몰입하기

어느정도 개발이 되어 있었고, 처음부터 빌드하는 과정 보다 여름 동안 개발하고

이후 출시하여 유저 피드백과 함께 개선할 수 있겠다는 생각에 여름방학 두달을 몰입할 수 있었다.

프로젝트에 대한 자세한 회고는 따로 작성하려 한다. 정말 할 이야기가 많다.

방향 바로 잡기

Crayon을 통해 스스로의 방향성을 다시 정립할 수 있었다.
특히 협업 과정에서 "어떻게 하면 좋은 팀원이 될 수 있을까?"에 대해 고민하기 시작했다.
작은 배려와 세심함 덕분에 동료들에게 "너랑 같이 작업하니까 편하다."라는 말을 들었을 때,
다른 사람과 일하기 좋은 개발자가 되고 싶다는 새로운 목표를 가지게 되었다.

첫 동아리 운영진과 컨퍼런스 개최

1년 동안 몸담아온 동아리 Leets의 운영진으로 합류했다.
애정이 깊은 첫 동아리에 기여하고 싶었고, 미숙하지만 새로운 도전에 나서고 싶었다.

동아리 운영은 정말 쉬운 일이 하나도 없었다.
개인보다는 팀과 동아리 전체를 우선으로 생각해야 했고, 넓은 시야와 책임감이 필요했다.
정기 활동이 모두 마무리된 지금, 나는 개인적인 관점을 넘어 팀 단위로 사고할 수 있는 사람이 되었다고 생각한다.

새로운 시도 : 마일스콘

이번 동아리 기수에서는 많은 새로운 시도가 있었다.
그중 가장 큰 예시는 GDG on Campus와 공동 기획한 컨퍼런스 마일스콘

주니어 개발자와 시니어 개발자의 이야기를 듣는 컨퍼런스는 외부에 많지만,
작은 공간에서 연사님들의 이야기를 가까이에서 듣고 질문할 수 있는 자리를 마련하는 것은 쉬운 일이 아니었다.
연사 섭외부터 장소 준비, 케이터링 규모와 시간 조정까지 고려할 것이 많았지만,
각 동아리에서 참여해준 모든 분들과 하나씩 해나가며 성공적으로 마무리할 수 있었다.

이 행사를 통해 가천대학교의 학생 개발자들에게 조금이나마 기여할 수 있었기를 바란다.

우아한 테크코스 도전

2023년에는 도전하지 않았던 우아한 테크코스에 도전했다.
프리코스를 진행하는 것만으로도 많은 것을 얻을 수 있다는 지인들의 평가에 급히 지원했다.

나쁜 습관 때려잡기

프리코스에서의 4주는 정말 유익했다고 단언할 수 있다.
이 시간은 그동안 개발하면서 생긴 나쁜 습관들을 고칠 수 있는 기회였기 때문이다.

생각하며 코드를 짜는 습관은 프리코스 이후에도 실천하고 있고
단일 책임 원칙, 올바른 메서드 이름 작성, 객체를 일하게 하는 코드 스타일 등을 Crayon에 적용하며 개선할 수 있었다.
이는 개발자로서 큰 자산이 될 것이라고 믿는다.

메타인지

또한, 메타인지에 대해서도 고민하게 되었다.
내가 정말 하고 싶은 것은 무엇인지, 부족한 점은 무엇인지, 잘하는 것은 무엇인지 깊이 생각해봤다.
이는 개발자로서뿐만 아니라 "나"라는 인간에 대해 고찰하며, 반년 넘게 해오던 고민을 조금이나마 해결할 수 있는 계기가 되었다.

비록 7기에 합격하지는 못했지만, 앞으로 나아갈 길을 더 단단히 다질 수 있었던 소중한 4주였다.

그래서 2025년에는

이전과는 더 깊은 공부, 개발을 하려한다.

1. 그냥 작동하는 코드 보다는 깊이있는 개발

2. 한번 보고 끝내는 것이 아닌 적용하고 문서로 남기는 공부

3. 개발하고 방치하는 것이 아니라 유지보수하는 경험

4. 제발 이제는 합격해보기

인프런에 남겨둔 자바 강의는 개강 전에 모두 듣고, 더 깊은 수준의 책과 강의를 공부할 것이다.

2024는 도전과 실패의 연속이었다면 2025년에는 과정이 아닌 결과를 남기고 싶다.

[Recap] 모던 자바 인 액션 스터디 회고

rootTiket — Sat, 27 Jul 2024 16:34:03 +0900

들어가면서

3개월간 진행한 모던 자바 인 액션 스터디가 종료됐다.
새 스터디 준비를 위해 회고를 해보려고 한다.

스터디 진행방식과 어떤 것들을 공부했는지는 여기로

https://github.com/Leets-Official/modern-java-in-action

GitHub - Leets-Official/modern-java-in-action: Leets 3기 자바 스터디

Leets 3기 자바 스터디. Contribute to Leets-Official/modern-java-in-action development by creating an account on GitHub.

github.com

왜 모던 자바 인 액션이었지?

모던 자바 인 액션을 고른 이유는 이 당시 스트림과 람다를 전혀 사용할 줄 몰랐기 때문이다.
심지어 스트림과 람다를 쓴 코드를 거의 이해하지도 못했다. 스스로 사용 못하는 것 보다도 다른 사람의 코드를 읽지 못하는 것은 코드 리뷰나 앞으로 진행할 프로젝트에서 큰 걸림돌이라고 생각했고 고민도 없이 모던 자바 인 액션을 선택했다. 다행히 팀원들도 모두 동의해서 무사히 모던 자바 인 액션을 읽을 수 있었다

스터디.. 어떻게 해야 하지?

스터디의 시작이 동아리 스터디였던 만큼 다른 스터디 팀들과 비슷한 방식으로 스터디를 진행하려 했다.
초기 방식은 이랬다.

1. 정해진 챕터 읽어오기

2. 챕터들 안에서 문제를 만들어 이슈로 올리기

3. 정기 모임에서 다 같이 풀어보기

위 방식이 우선 채택된 이유는 기존에 진행해 왔던 스터디들이 시작할 때는 열정 넘치게 시작했으나 텐션이 풀어지면서 점점 흐지부지 되는 경우가 많았던 것이 주요했다.

그러나 나는 이 방식보다 더 나은 방식을 고민했다. 이유는 다음과 같다.

1. 책을 읽기보다 문제를 찾기 위해 집중하게 되지 않을까?

2. 결국 공부는 혼자 하는 것, 정기모임이 공부의 주가 되면 안 될 것 같다.

3. 아는 것으로 문제를 만들기보다 모르는 것을 질문하는 것이 더 유익하다.

4. 결국 숙제처럼 느껴진다면 혼자 읽는 것보다 좋은 방법이라고 생각하지 않는다.

무엇보다 자신이 아는 것을 기록으로 남기기에는 문제를 만드는 것으로는 부족했다.

노션에 제안서 까지 적었다..

스터디 가이드라인

https://pumped-marquess-04e.notion.site/42201c8659584c11acc92f45e1a6b7cd?pvs=74

스터디 학습 가이드라인 | Notion

✏️ 스터디… 시작했는데 어떻게 정리해요?

pumped-marquess-04e.notion.site

좋았던 점

회고록 방식은 좋았다!

강제성이 있는 회고록 작성이 책을 읽는 데에 더 도움이 되었고 몰입하는 데에 도움이 되었다는 반응이 많았다.

회고를 작성하면서 자신이 모르는 것을 스스로 공부하고 질문할 수 있는 분위기가 만들어지는 부분이 긍정적이게 다가왔다.

기획 당시 내가 원하는 스터디 또한 "각자 공부하고 편하게 질문하자! " 였기에 이 부분들이 잘 실현된 거 같아 뿌듯했다.

하지만 아쉬움이 더 많았던 스터디

후순위로 밀려버려 아쉬워요

맞는 말이다.. 어쨌는 1주일에 회고록 한 개를 작성한다는 건 시험기간, 개인 프로젝트가 겹치는 시기를 지나며 점점 후순위로 밀려났다. 여유 있는 시기에는 즐거웠으나 시간이 지나며 점점 짐과 숙제처럼 다가왔다.

솔직히 재미없어요

공부가 항상 재미가 있을 수는 없다. 하지만 이번 스터디는 정확히 중반 이후로 책에 대한 흥미가 떨어지는 것이 눈에 보였다.

초반은 각자 부족함이 눈에 보여 책을 읽을 때 즐거웠으나 시간이 지날수록 당장의 이슈, 그리고 흥미 있는 분야가 변하면서 자연스럽게 흥미가 떨어진 것으로 보인다.

책이 루즈한 것도 한몫했다. 아무래도 스트림, 람다에 대한 깊이 있는 내용을 다루다 보니 한정적인 범위의 이야기가 반복되어 등장하니 자연스럽게 지루해졌다.

그래서 이대로 끝내려고?

위와 같은 이유들로 모던 자바 인 액션은 더 이상 읽지 않기로 했다.

대신 새로운 스터디를 위해 앞으로 어떤 것을 바라는지 함께 회고해 보았다.

재밌는 스터디를 하고 싶어요!

즐거운 스터디를 위해서는 모두 흥미 있는 주제여야 할 것이다.

그러나 6명이 되는 인원이 모두 흥미 있을만한 주제를 어떻게 찾기는 쉽지 않다.

앞으로 바라는 점

스터디에서 스터디메이트로

그러면 각자 목표를 정하고 결과를 확인해 보고 과정을 이야기해보는 스터디는 어떨까?

일주일 간 각자의 목표를 이야기하고 한 주의 과정을 함께 이야기하는 스터디를 진행해보려 한다.

1. 각자의 일주일간 목표 정하기

2. 목표 피드백 해주기

3. 결과도 함께 확인하기

4. 실패 시 벌금(일정 금액이 모이면 다 같이 회식하기)

비록 같은 공부를 하는 스터디는 아니지만 공부할 때 서로 공유할 것이 많은 게 진정한 스터디의 장점이라고 생각한다.

언제 까지라고 기한은 정하지 않았지만 위처럼 스터디를 진행해 보면서 얻은 경험을 나중에 회고해 보도록 하자.

[Spring] MapStruct, Mapper 가 제대로 작동하지 않음

rootTiket — Fri, 26 Jul 2024 13:56:32 +0900

Mapper가 제대로 작동이 안되어 팀원이 4시간이 넘는 트러블 슈팅을 겪었다

문제 상황

분명 Mapper 문법에 맞게 작성했는데 구현체가 생성되지 않고, 코드가 제대로 실행되지 않음

결론부터 말하자면 Target 에 Setter가 누락되어서 생기는 오류였다.

Mapper가 어떻게 작동하는지 부터 다시 되짚어보며 문제를 해결해봤다.

Mapper, 그럼 어떻게 구현되는가?

@Mapper
public interface TestMapper{
    void updateHuman(TestDto testDto, @MappingTarget Test test);
}

이렇게 코드를 작성하면 testDto 의 내용이 Test 객체로 매핑된다!

어떻게 작동되는 것일까?

공식 문서를 보자

Mapper는 구현될 때 target에 setter를 이용하여 매핑을 해준다는 것을 알 수 있다.

즉 직접 setter를 이용해서 필드의 값을 하나씩 매핑하는 과정을 생략해주는 것이라고 볼 수 있다!

코드로 확인해보자
코드로 DTO를 target(엔티티)로 매핑하는 과정을 보면서 Setter가 있는경우와 없는 경우를 비교해 보자

testUse(Target이 될 클래스)

@Getter
public class TestUse {
    private String f1;
    private String f2;
}

DTO

public record Dto (
    String f1, 
    String f2
){}

Mapper Interface 정의

@Mapper
public interface TestMapper {
    TestMapper INSTANCE = Mappers.getMapper(TestMapper.class);
    TestUse toTestUse(Dto dto);
}

테스트코드

public class UserMapperTest {
    @Test
    public void testEntityToDTOWithoutSetters() {
        Dto dto = new Dto("f1","f2");
        TestUse testUse = TestMapper.INSTANCE.toTestUse(dto);
        System.out.println(testUse.getF1());
    }
}

dto 를 생성해주고 TestUse와 매핑, 그 결과를 출력해보자

결과

null

예상처럼 null이 반환된다.

Setter를 정의해주지 않아 객체에 값을 넣어주지 못해 null을 반환하는 것.

구현체도 확인해보자

public class TestMapperImpl implements TestMapper {

    @Override
    public TestUse toTestUse(Dto dto) {
        if ( dto == null ) {
            return null;
        }

        TestUse testUse = new TestUse();

        return testUse;
    }
}

구현체에 TestUse를 설정하는 코드가 생성되지 않는다!

즉 setF1, setF2를 해 주지 못해 빈 객체를 반환하게 된다.

Setter 대신 Builder로도 확인해볼까?

@Override
    public TestUse toTestUse(Dto dto) {
        if ( dto == null ) {
            return null;
        }

        TestUse.TestUseBuilder testUse = TestUse.builder();

        testUse.f1( dto.f1() );
        testUse.f2( dto.f2() );

        return testUse.build();
    }

Builder 어노테이션이 있다면 이를 감지하여 자동으로 구현체를 생성해준다.

생성자를 정의해 주어도 이렇게 잘 감지해서 동작하는 것을 알 수 있다.

@Override
    public TestUse toTestUse(Dto dto) {
        if ( dto == null ) {
            return null;
        }

        String f1 = null;
        String f2 = null;

        f1 = dto.f1();
        f2 = dto.f2();

        TestUse testUse = new TestUse( f1, f2 );

        return testUse;
    }

마무리

MapStruct 사용하면 편하게 객체사이를 매핑 할 수 있지만 이 또한 자동이라고 생각하지 말자.

MapStruct의 역할은 객체의 Setter, Builder, 생성자를 이용해 매핑을 자동화 해 주는 것이므로 매핑이 제대로 되지 않는것 같다면

클래스에 Setter, Builder가 선언되어있는지 확인해 보면 좋을것 같다.