pxd story

하네스 엔지니어링

doworld — Mon, 11 May 2026 07:50:18 +0900

들어가며

OpenAI의 엔지니어링 팀이 5개월 동안 약 100만 줄의 프로덕션 코드를 만들었다. 놀라운 건 규모가 아니다. 수동으로 작성한 소스코드가 단 한 줄도 없다는 점이다.

소수의 엔지니어가 Codex 에이전트에게 작업을 지시하고, PR을 검토하고, CI 파이프라인을 관리했을 뿐이다. 애플리케이션 로직, 문서, CI 설정, 모니터링 설정까지 전부 AI 에이전트가 만들었다.

이 실험에서 OpenAI가 얻은 가장 중요한 교훈은 이것이다:

"어려운 건 AI 에이전트가 아니다. 에이전트가 일할 환경(harness)이 어렵다."

이 환경을 설계하는 분야가 바로 하네스 엔지니어링(Harness Engineering)이다.

하네스 엔지니어링이란?

비유로 이해하기

"하네스(harness)"는 말에게 씌우는 마구(馬具)다. 말이 아무리 빠르고 강해도, 고삐 없이는 짐을 나를 수 없고 밭을 갈 수도 없다. 방향을 잡아주고, 힘을 전달하고, 안전하게 제어하는 것이 마구의 역할이다.

AI 에이전트도 마찬가지다.

- GPT-5든 Claude든, 에이전트 자체는 이미 충분히 강력하다

- 하지만 고삐 없이 풀어놓으면 엉뚱한 코드, 아키텍처 위반, 스타일 불일치가 쏟아진다

- 하네스 엔지니어링은 이 고삐를 설계하는 기술이다

정의

하네스 엔지니어링: AI 에이전트가 대규모로 안정적이고 일관된 결과물을 만들어내도록 환경, 제약, 피드백 루프를 설계하는 엔지니어링 분야

핵심은 에이전트를 바꾸는 것이 아니라 환경을 바꾸는 것이다.

왜 지금 필요한가?

2025년의 전형적인 실패 패턴

개발자: "결제 모듈 만들어줘"
에이전트: (코드 생성)


문제들:
- 프로젝트 코딩 컨벤션 무시
- 이미 있는 유틸 함수를 중복 생성
- 아키텍처 레이어 경계를 넘나듦
- 테스트는 통과하지만 기존 모듈과 스타일이 불일치
- 3일 후, 다른 에이전트가 같은 파일을 다른 방식으로 수정

에이전트 하나가 한 번 작업하는 건 어떻게든 된다. 문제는 규모가 커질 때다. 10개의 에이전트가 동시에 100개의 파일을 수정하면, 제약 없이는 카오스가 된다.

프롬프트 엔지니어링의 한계

"코딩 컨벤션을 지켜줘", "아키텍처 레이어를 위반하지 마" 같은 프롬프트를 아무리 정교하게 써도, 에이전트는 잊거나 무시한다. 프롬프트는 부탁이고, 하네스는 강제다.

프롬프트 엔지니어링: "이 규칙을 지켜주세요" (부탁)

하네스 엔지니어링: 규칙을 위반하면 CI가 실패한다 (강제)

LangChain 팀은 이를 정량적으로 증명했다. 에이전트 모델은 그대로 두고 하네스만 개선했더니, 벤치마크 성과가 52.8%에서 66.5%로 향상되었다. 순위로는 Top 30에서 Top 5로 뛰었다. 에이전트를 바꾸지 않고도, 환경을 바꾸는 것만으로 이 정도 차이가 난다.

하네스 엔지니어링의 3가지 핵심 기둥

1. 컨텍스트 엔지니어링 (Context Engineering)

"에이전트에게 추측시키지 말고, 읽게 하라"

AI 에이전트가 올바른 결과물을 만들려면, 프로젝트의 규칙과 상태를 알아야 한다. 컨텍스트 엔지니어링은 이 정보를 머신이 읽을 수 있는 형태로 구조화하는 것이다.

정적 컨텍스트: 규칙 파일

# AGENTS.md (또는 CLAUDE.md)

## 아키텍처 규칙
- 모든 API 엔드포인트는 /api/v1/ 하위에 위치
- 데이터베이스 접근은 반드시 Repository 레이어를 통해서만
- UI 컴포넌트에서 직접 API를 호출하지 않음

## 코딩 컨벤션
- 함수명: camelCase
- 파일명: kebab-case
- 테스트 파일: *.test.ts

## 금지 패턴
- console.log 사용 금지 (logger 사용)
- any 타입 사용 금지
- 인라인 스타일 금지

이 파일은 에이전트가 작업을 시작할 때 자동으로 로드된다. 사람에게 온보딩 문서를 주듯이, 에이전트에게도 "입사 첫날 읽어야 할 문서"를 주는 것이다.

동적 컨텍스트: 실시간 상태

CI/CD 파이프라인 상태
로그, 메트릭, 에러 추적
현재 진행 중인 PR과 이슈
최근 변경된 파일과 그 이유

핵심 원칙: 저장소가 단일 진실 소스(Single Source of Truth)

모든 정보는 코드 저장소 안에 있어야 한다. 위키, 노션, 슬랙 대화에 흩어진 정보는 에이전트가 읽을 수 없다. 저장소에 넣어야 에이전트의 컨텍스트가 된다.

2. 아키텍처 제약 (Architectural Constraints)

"자유롭게 코드를 쓰되, 정해진 경계 안에서만"

컨텍스트가 "무엇을 해야 하는가"라면, 아키텍처 제약은 "무엇을 해서는 안 되는가"다.

의존성 방향 강제

OpenAI는 코드베이스의 의존성 방향을 이렇게 정의했다:

Types → Config → Repository → Service → Runtime → UI

UI는 Service를 호출할 수 있지만, Service는 UI를 참조할 수 없다
Repository는 Config를 읽을 수 있지만, Config는 Repository를 모른다
이 규칙을 위반하는 import가 있으면 **빌드가 실패**한다

이것은 프롬프트로 "지켜줘"라고 부탁하는 것이 아니다. 린터와 구조 테스트가 자동으로 차단하는 것이다.

구현 예시

// architecture.test.ts — 아키텍처 제약 테스트

describe('Architecture constraints', () => {
  test('UI layer must not import from Repository', () => {
    const uiFiles = getFilesIn('src/ui/');

    for (const file of uiFiles) {
      const imports = getImports(file);
      expect(imports).not.toContainPath('src/repository/');
    }
  });

  test('Service layer must not import from UI', () => {
    const serviceFiles = getFilesIn('src/service/');

    for (const file of serviceFiles) {
      const imports = getImports(file);
      expect(imports).not.toContainPath('src/ui/');
    }
  });
});

에이전트가 아무리 "이렇게 하는 게 더 효율적인데"라고 생각해도, 이 테스트가 실패하면 코드는 머지되지 않는다.

Pre-commit 훅

# .husky/pre-commit
npx lint-staged          # 코드 스타일 강제
npm run test:architecture  # 아키텍처 규칙 검증
npm run test:types         # 타입 안전성 확인

커밋 자체가 되지 않으므로, 잘못된 코드가 저장소에 들어갈 수 없다.

3. 엔트로피 관리 (Entropy Management)

"AI가 만든 코드는 시간이 지나면 부패한다"

Martin Fowler는 이 현상을 "코드 부패(code rot)"에 비유하면서, 하네스 엔지니어링의 엔트로피 관리를 프로그래밍 언어의 가비지 컬렉션(GC)에 빗대었다.

가비지 컬렉션이 메모리 누수를 자동으로 정리하듯, 엔트로피 관리는 코드베이스의 일관성 붕괴를 자동으로 탐지하고 복구한다.

왜 엔트로피가 증가하는가?

에이전트 A가 유틸 함수를 만들고, 에이전트 B가 같은 기능의 함수를 또 만든다. 에이전트 C는 이전 버전의 패턴을 사용한다. 10개의 에이전트가 동시에 작업하면, 각각은 올바르더라도 전체적으로는 불일치가 쌓인다.

대응 방법

정리 에이전트(Cleanup Agent)를 주기적으로 실행:
  1. 문서와 코드의 불일치 탐지
  2. 중복 함수/모듈 발견
  3. 사용되지 않는 코드 식별
  4. 네이밍 패턴 위반 스캔
  5. 순환 의존성 감지

이것은 "한 번 설정하면 끝"이 아니다. 지속적이고 반복적인 프로세스다.

실제 사례로 보는 하네스 엔지니어링

OpenAI: 100만 줄의 무인 코드

구성:

소수의 엔지니어 + 다수의 Codex 에이전트
모든 아키텍처 규칙을 머신 가독형 문서로 명세
관찰성(observability) 데이터로 에이전트 성과 모니터링
구조화된 PR 리뷰 워크플로우

결과:

5개월, 약 100만 줄의 프로덕션 베타 제품
수동 작성 코드 0줄
애플리케이션 로직 + 문서 + CI + 모니터링 전부 포함

핵심 교훈:

에이전트에게 "좋은 코드를 써줘"라고 하지 않았다. 대신 좋은 코드만 통과할 수 있는 환경을 만들었다.

Stripe: 주당 1,000개 PR

Stripe의 "Minions" 에이전트 시스템:

Slack에서 작업 요청
  → 에이전트가 자동으로 코드 작성
  → CI 파이프라인 통과 확인
  → PR 자동 생성
  → 인간 엔지니어가 최종 리뷰
  → 머지

주당 1,000개 이상의 PR이 이 파이프라인을 통해 머지된다. 핵심은 에이전트가 만든 코드가 기존 코드와 동일한 품질 게이트를 통과해야 한다는 점이다.

LangChain: 하네스 변경만으로 벤치마크 점프

LangChain 팀은 에이전트 모델(Claude, GPT)은 전혀 바꾸지 않고, 미들웨어 구조만 개선했다:

LocalContextMiddleware: 코드베이스 매핑 자동 생성
LoopDetectionMiddleware: 에이전트 반복 루프 감지 및 중단
ReasoningSandwichMiddleware: 추론 단계 최적화
PreCompletionChecklistMiddleware: 완료 전 검증 강제

결과: 벤치마크 52.8% → 66.5%, 순위 Top 30 → Top 5

이 사례가 증명하는 것: "더 좋은 AI"보다 "더 좋은 환경"이 성과를 좌우한다.

도입 가이드: 3단계로 시작하기

Level 1: 개인 프로젝트

가장 가성비 좋은 시작점이다.

# 1. CLAUDE.md (또는 AGENTS.md) 작성
프로젝트 규칙, 컨벤션, 금지 패턴 정의

# 2. Pre-commit 훅 설정
코드 스타일과 기본 규칙 자동 검증

# 3. 테스트 작성
에이전트가 만든 코드가 기존 테스트를 깨뜨리지 않는지 확인

이것만으로도 에이전트의 결과물 품질이 체감될 정도로 달라진다.

Level 2: 소규모 팀

# 1. AGENTS.md 고도화
아키텍처 다이어그램, 모듈 경계, 의존성 규칙 포함

# 2. CI 파이프라인에 아키텍처 테스트 추가
레이어 위반, 순환 의존성 자동 탐지

# 3. PR 검토 체크리스트
에이전트 생성 코드에 대한 표준 리뷰 절차 수립

# 4. 린터 규칙 강화
프로젝트 전용 커스텀 린터 규칙 추가

Level 3: 조직 규모

# 1. 미들웨어 레이어 구축
에이전트 요청/응답 파이프라인에 검증 단계 삽입

# 2. 관찰성(Observability) 시스템
에이전트 성과 메트릭 수집 및 대시보드

# 3. 엔트로피 관리 자동화
정리 에이전트 주기적 실행, 코드 건강도 리포트

# 4. 버전 관리된 하네스 설정
하네스 자체를 코드로 관리, 변경 이력 추적

흔한 실수 5가지

1. 과도한 제어 흐름 설계

에이전트의 모든 행동을 미리 정의하려는 유혹이 있다. 하지만 LLM은 빠르게 진화한다. 너무 세밀한 제어 흐름은 모델이 업데이트될 때마다 깨진다. 큰 경계만 정하고, 경계 안에서는 자유를 주는 것이 더 견고하다.

2. 정적 하네스

한 번 만들어놓고 방치하는 하네스는 금방 쓸모없어진다. 모델이 진화하면 하네스도 함께 진화해야 한다. 하네스 자체를 코드로 관리하고 버전 관리해야 하는 이유다.

3. 문서화 경시

"AGENTS.md 대충 써도 되겠지"는 위험한 생각이다. 에이전트는 당신의 의도를 추론하지 않는다. 명확하지 않으면 추측하고, 추측은 틀린다. 규칙 파일의 품질이 곧 에이전트 결과물의 품질이다.

4. 피드백 루프 부재

에이전트가 성공했는지 실패했는지 모르면 개선할 수 없다. 어떤 에이전트가 어떤 작업에서 어떤 이유로 실패했는지를 추적하고 기록해야 한다. 이 데이터가 하네스를 개선하는 연료다.

5. 저장소 밖에 정보 저장

"이건 노션에 있어", "그건 슬랙에서 공유했어" — 에이전트는 이런 정보에 접근할 수 없다. 저장소 안에 없으면 존재하지 않는 것이다.

프롬프트 엔지니어링 → 하네스 엔지니어링으로의 전환

2023~2024년의 키워드가 "프롬프트 엔지니어링"이었다면, 2025~2026년의 키워드는 "하네스 엔지니어링"이다.

프롬프트 엔지니어링:

AI에게 무엇을 하라고 말하는 기술
한 번의 대화, 한 번의 결과물에 집중
개인 스킬에 의존

하네스 엔지니어링:

AI가 올바르게 작동하는 환경을 만드는 기술
수천 번의 반복 실행에서 일관된 품질을 보장
시스템적이고 팀 전체에 적용

프롬프트 엔지니어링이 "좋은 질문하는 법"이라면, 하네스 엔지니어링은 "좋은 답만 나올 수밖에 없는 구조를 만드는 법"이다.

마치며

하네스 엔지니어링은 결국 개발자의 역할에 대한 질문이다.

"당신은 코드를 쓰는 사람인가, 코드가 만들어지는 환경을 설계하는 사람인가?"

AI 에이전트가 코드를 작성하는 속도와 품질은 계속 좋아질 것이다. 하지만 아무리 좋은 에이전트도 잘못된 환경에서는 잘못된 결과를 낸다. 반대로, 적절한 하네스 안에서는 평범한 에이전트도 놀라운 결과를 만든다.

2026년의 시니어 엔지니어에게 기대되는 역량은 더 이상 "복잡한 알고리즘을 얼마나 잘 구현하느냐"가 아니다. "AI 에이전트가 복잡한 시스템을 안정적으로 구축할 수 있는 환경을 얼마나 잘 설계하느냐"로 무게중심이 옮겨가고 있다.

코드를 쓰는 시대가 끝나는 게 아니다. 코드를 쓰는 방식이 바뀌는 것이다. 그리고 그 변화의 중심에 하네스 엔지니어링이 있다.

이 글은 https://tech.pxd.co.kr/ 에서도 보실 수 있습니다.

참고 자료

- OpenAI — 하네스 엔지니어링: 에이전트 우선 세계에서 Codex 활용하기

- Martin Fowler — Harness Engineering

- NxCode — Harness Engineering: The Complete Guide

shadcn과 함께 UI 컴포넌트를 AI 에이전트와 더 잘쓰는 방법

doworld — Mon, 20 Apr 2026 07:50:18 +0900

들어가며

AI 코딩 에이전트에게 "로그인 폼 만들어줘"라고 했더니, 있지도 않는 props를 쓰고, import 경로를 틀리고, 프로젝트 테마와 전혀 안 맞는 결과물이 나온 경험이 있나요?

shadcn/ui가 더 확실하고 사용하기 쉽게 shadcn/cli v4로 업데이트 되었어요.

shadcn/ui가 AI 시대에 주목받는 이유

shadcn/ui는 이미 주목을 많이 받았던 UI 프레임워크이지만 AI시대가 되며 더더욱 많이 주목받고 활용되고 있습니다.

일반적인 컴포넌트 라이브러리와 다르죠. npm에서 패키지를 설치하는 방식이 아니라, 컴포넌트 코드를 직접 프로젝트에 복사하는 구조입니다.

npx shadcn@latest add button

# → src/components/ui/button.tsx 파일이 생성됨

이 "코드 소유" 방식이 AI와 합이 좋아요:

- AI가 컴포넌트 코드를 직접 읽고 이해할 수 있다

- 숨겨진 추상화 없이 모든 구현이 투명하다

- 프로젝트에 맞게 자유롭게 수정 가능하다

하지만 AI가 "shadcn/ui를 안다"고 해도, 내 프로젝트에서 어떻게 설정되어 있는지는 모른다는 점에서 문제가 종종 발생해요. CLI v4가 이 문제를 해결해줍니다.

CLI v4의 핵심: AI 에이전트를 위한 3가지 설정

1. Skills — "AI에게 내 프로젝트를 알려주는 법"

문제

Claude Code나 Codex 같은 AI 에이전트는 학습 데이터에 의존하죠. 하지만 shadcn/ui는 빠르게 업데이트되고, 프로젝트마다 설정이 다릅니다.

결과적으로:

- 컴포넌트 API를 잘못 사용

- 테마 토큰이 불일치

- import 경로 오류

- 올바른 props를 찾느라 시간 낭비

해결: shadcn/skills

npx skills add shadcn/ui

이 한 줄이면 AI 에이전트가 내 프로젝트에 대해 자동으로 파악을 합니다:

- components.json 설정 (프레임워크, CSS 변수, 경로 등)

- Tailwind 설정

- 설치된 컴포넌트 목록

- 아이콘 라이브러리 종류

- 프레임워크 타입과 버전

설정 전 vs 설정 후

# Skills 설정 전

// AI가 추측으로 생성한 코드
import { Button } from "shadcn/button"  // 경로 틀림
<Button variant="solid">              // 존재하지 않는 variant


# Skills 설정 후

// AI가 실제 설정을 읽고 생성한 코드
import { Button } from "@/components/ui/button"  // 정확한 경로
<Button variant="default">                       // 올바른 variant

Skills는 AI에게 "추측하지 말고 읽어라"를 가능하게 만듭니다.

2. MCP Server — "AI가 실시간으로 문서를 찾아보는 법"

문제

AI의 학습 데이터에는 시점이 있죠. shadcn/ui가 어제 업데이트 했다면 Data Table의 새로운 정렬 API를 AI는 모릅니다.

해결: shadcn MCP 서버

claude mcp add shadcn -- npx shadcn@latest mcp

MCP(Model Context Protocol)는 AI 에이전트가 실시간으로 shadcn/ui 레지스트리에 접근할 수 있게 해줍니다.

AI가 할 수 있게 되는 것:

- 컴포넌트 문서와 예제를 실시간 조회

- 최신 API와 props 확인

- 설치 명령어 자동 생성

- 커뮤니티 레지스트리 검색

실제 사용 예시

개발자: "Data Table에 정렬 기능 추가해줘"

AI (MCP 없이): 학습 데이터 기반으로 추측 → 구버전 API 사용 → 에러

AI (MCP 있음): shadcn 레지스트리에서 최신 Data Table 문서 조회
              → 현재 버전의 정확한 정렬 API 확인
              → 올바른 구현 코드 생성

VS Code에서 설정하기

.vscode/mcp.json 파일에 추가:

{
  "servers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}

3. Preset — "디자인 시스템을 한 줄로 전달하는 법"

문제

AI가 컴포넌트를 올바르게 생성해도, 색상이 프로젝트 테마와 안 맞고, 폰트가 다르고, border-radius가 일관성 없는 경우가 흔하게 일어납니다.

해결: 프리셋 코드

프리셋은 디자인 시스템 전체를 짧은 코드 한 줄로 압축합니다.

npx shadcn@latest init --preset a1Dg5eFl

이 코드 안에 담기는 것:

- 색상 팔레트 (라이트/다크 모드 포함)

- 테마 설정

- 아이콘 라이브러리

- 폰트

- Border radius

프리셋 만드는 법

1. shadcn/create에 접속

2. 시각적으로 색상, 폰트, 반경 등을 조정

3. 실제 UI 컴포넌트로 미리보기

4. 프리셋 코드 생성 (예: a1Dg5eFl)

5. 팀에 공유하거나 AI에게 전달

활용 시나리오

팀 프로젝트:

"이 프리셋 코드로 프로젝트 초기화해줘: a1Dg5eFl"
→ 모든 팀원이 동일한 디자인 시스템을 즉시 적용

AI에게 디자인 시스템 전달:

"이 프리셋 기반으로 대시보드 페이지 만들어줘"
→ AI가 프리셋의 정확한 색상, 폰트, 스타일을 사용하여 일관된 UI 생성

CLI v4의 그 외 유용한 기능들

--dry-run, --diff, --view: 변경 전 확인

AI 에이전트가 컴포넌트를 추가하기 전에, 어떤 파일이 어떻게 바뀌는지 미리 볼 수 있어요.

# 실제 변경 없이 미리보기
npx shadcn@latest add button --dry-run

# 기존 코드와 차이점 비교
npx shadcn@latest add button --diff

# 컴포넌트 코드만 보기
npx shadcn@latest add button --view

이것은 AI가 자율적으로 작업할 때 특히 중요해요. "일단 추가하고 보자"가 아니라, 확인 후 적용이 가능해지기 때문이죠.

shadcn docs: 터미널에서 문서 조회

npx shadcn@latest docs combobox

브라우저를 열 필요 없이 CLI에서 바로 컴포넌트 문서, 예제 코드, 사용법을 확인할 수 있어요. AI 에이전트도 이 명령어로 필요한 정보를 즉시 가져올 수 있고요.

shadcn info: 프로젝트 진단

npx shadcn@latest info

현재 프로젝트의 프레임워크, 버전, CSS 변수, 설치된 컴포넌트 등 전체 현황을 출력합니다. AI에게 "내 프로젝트 상태 알려줘"를 자동화한 것이에요.

shadcn init --template: 프로젝트 스캐폴딩

# Next.js 프로젝트 한 번에 생성
npx shadcn@latest init -t next

# 모노레포 구조
npx shadcn@latest init -t next --monorepo

Next.js, Vite, Laravel, React Router, Astro, TanStack Start를 지원합니다. 다크 모드 설정도 자동으로 포함되요.

shadcn init --base: 프리미티브 선택

npx shadcn@latest init --base radix    # Radix UI 기반
npx shadcn@latest init --base base-ui  # Base UI 기반

프로젝트에 맞는 headless UI 프리미티브를 선택할 수 있습니다.

실전 워크플로우: 처음부터 끝까지

Step 1: 프로젝트 초기화\

# 프리셋 포함 Next.js 프로젝트 생성
npx shadcn@latest init -t next --preset a1Dg5eFl

Step 2: AI 에이전트 연동

# Skills 설치 (프로젝트 컨텍스트)
npx skills add shadcn/ui

# MCP 서버 연결 (실시간 문서)
claude mcp add shadcn -- npx shadcn@latest mcp

Step 3: AI와 함께 개발

개발자: "사용자 프로필 페이지를 만들어줘.
        Avatar, Card, Badge, Tabs 컴포넌트를 써서."

AI 에이전트:
  1. Skills로 프로젝트 설정 확인
  2. MCP로 각 컴포넌트 최신 API 조회
  3. 프리셋 기반 테마에 맞는 코드 생성
  4. --diff로 변경사항 확인 후 적용

(물론 실제로 X만들어줘. 하진 않죠...)

Step 4: 검증

# 컴포넌트가 올바르게 추가되었는지 확인
npx shadcn@latest info

왜 이 조합이 좋을까요?

이전에는 AI에게 UI를 맡기면...?

AI가 코드 생성 → 에러 발생 → 수동으로 수정 → 다시 요청 → 또 에러
→ 결국 직접 작성 → "AI 쓰느니 직접 하는 게 낫다"

Skills + MCP + Preset 조합은...!

AI가 프로젝트 설정 읽음 (Skills)
→ 최신 문서 확인 (MCP)
→ 디자인 시스템에 맞게 생성 (Preset)
→ 변경 전 검증 (--diff)
→ 한 번에 올바른 결과물

핵심은 AI에게 컨텍스트를 주는 것이에요. 똑똑한 AI에게 정보를 안 주면 추측할 수밖에 없고, 추측은 항상 옳지는 않아요. 정보를 주면 그만큼 정확해지죠. 당연한 이야기지만, shadcn/cli v4는 이 "정보 전달"을 자동화했다는 점에서 의미가 큰 것 같아요.

기존 프로젝트에도 적용 가능한가?

가능합니다. components.json이 존재하는 프로젝트라면 Skills가 자동으로 감지해요. 새 프로젝트를 만들 필요 없이, 기존 shadcn/ui 프로젝트에 바로 적용할 수 있어요.

# 기존 프로젝트에서
npx skills add shadcn/ui              # Skills 추가
claude mcp add shadcn -- npx shadcn@latest mcp  # MCP 연결
# 끝. 바로 사용 가능.

registry:base와 registry:font

CLI v4에서 레지스트리도 크게 강화되었어요.

registry:base는 전체 디자인 시스템을 하나의 페이로드로 배포할 수 있게 해요. 컴포넌트, 의존성, CSS 변수, 폰트, 설정 파일을 한 번의 설치로 모두 가져옵니다.

registry:font는 폰트를 1급 레지스트리 타입으로 승격되었어요. 컴포넌트를 설치하듯이 폰트를 설치하고 관리할 수 있어요.

회사나 팀이 자체 디자인 시스템을 만들어 사내 레지스트리로 배포하면, 새 프로젝트를 시작할 때 명령어 하나로 전체 디자인 시스템으로 설정할 수 있어요. AI 에이전트도 이 레지스트리를 참조하여 일관된 코드를 생성할 수 있고요.

마치며

shadcn/ui의 철학은 처음부터 "코드를 소유하라(own the code)"였어요.

npm 패키지에 의존하지 말고, 컴포넌트 코드를 직접 가져와서 원하는 대로 수정하라는 것이죠.

CLI v4는 이 철학을 AI 시대에 맞게 확장했다고 볼 수 있어요.

이상 shadcn 업데이트 관련 소식을 마칩니다.

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

이 글은 https://tech.pxd.co.kr/ 에서도 보실 수 있습니다.

참고 자료

파이썬 기초 간단하게 살펴보기

ny.back — Mon, 13 Apr 2026 07:50:41 +0900

들어가며

저는 마크업과 프론트엔드 작업을 하고 있어서 파이썬을 사용할 일이 없었습니다. 그러다 팀 과제를 하면서 제가 작성한 코드가 제대로 동작하는지 테스트해보고 싶어졌고, 방법을 찾다가 파이썬을 알게 되었습니다. 처음엔 낯선 언어여서 AI의 도움을 받아 코드를 작성하고 테스트를 해봤는데 결과를 바로바로 확인할 수 있어서 정말 편하더라고요. 그러면서 파이썬이 궁금해져서 알아보기 시작했습니다.

작업하면서 저처럼 스쳐 지나가듯 파이썬을 경험해 보신 분들이나, 저처럼 아예 몰랐던 분들께 조금이나마 도움이 될까 싶어 공부한 내용을 정리해봤습니다.

(참고로 저는 "100 Days of Code: The Complete Python Pro Bootcamp"라는 강의를 듣고 있습니다.)

파이썬 설치하기

코드를 작성하려면 먼저 파이썬을 설치해야 하겠죠?

Mac을 쓰시는 분이라면 이미 파이썬이 깔려 있을 수 있습니다. 터미널을 열어서 아래 명령어를 입력했을 때,

python3 --version

Python 3.x.x 같은 버전 정보가 나오면 이미 설치되어 있는 겁니다. 나오지 않는다면 아래 단계를 따라 설치하면 됩니다.

설치 방법

python.org에 접속해서 운영체제에 맞는 최신 버전을 다운로드하면 됩니다. 설치 과정은 일반적인 프로그램 설치와 동일합니다.

Windows를 사용하시는 분은 설치할 때 "Add Python to PATH" 체크박스가 보이면 꼭 체크해 주세요. 이걸 빠뜨리면 터미널에서 파이썬을 실행할 수 없습니다.

코드 실행 해보기

에디터에서 파일을 하나 만들고 (예: hello.py) 아래 코드를 작성한 뒤에

print("Hello World")

터미널에서 다음과 같이 실행하면,

python3 hello.py

Hello World가 출력되는 것을 확인하실 수 있을 것입니다.

파이썬 시작하기

1. print와 input

print()

먼저 살펴볼 건 print()입니다. 코드를 작성하다 보면 "이 값이 지금 뭐지?", "여기까지 제대로 실행된 건가?" 같은 순간이 자주 오는데, 그때 print()로 값을 출력해 보면 바로 확인할 수 있습니다. 결과를 눈으로 확인하는 가장 기본적인 방법이라 제일 먼저 알아두면 좋습니다.

print("Hello World")

이렇게 쓰면 화면에 Hello World가 출력됩니다.

input()

input()은 프로그램 실행 중에 사용자로부터 값을 입력받는 함수입니다. 예를 들어 이름을 물어보고, 그 이름을 활용해서 인사를 출력하는 식으로 쓸 수 있습니다.

name = input("이름이 뭐예요? ")
print("안녕하세요, " + name + "!")

여기서 name은 변수인데, 입력받은 값을 담아두는 역할을 합니다. 나중에 name이라고 쓰면 그 안에 저장된 값을 꺼내 쓸 수 있습니다.

2. 타입과 연산

타입

파이썬에서 다루는 데이터에는 여러 타입(종류)이 있습니다. 숫자끼리 계산해야 할 때도 있고, 글자를 다뤄야 할 때도 있는데, 파이썬은 이걸 타입으로 구분합니다.

타입	설명	예시
문자열(String)	글자들의 모음	"Hello", "안녕"
정수(Integer)	소수점 없는 숫자	1, 42, 100
실수(Float)	소수점 있는 숫자	3.14, 0.5
불린(Boolean)	참 또는 거짓	True, False

지금 다루고 있는 데이터가 어떤 타입인지 확인하고 싶을 때는 type()을 사용하면 됩니다. 뭔가 타입을 보면 자바스크립트 같기도, 자바 같기도...

print(type("Hello")) # <class 'str'>
print(type(123)) # <class 'int'>
print(type(3.14)) # <class 'float'>
print(type(True)) # <class 'bool'>

문자열 다루기

저희에겐 너무 익숙한 문자열인데요. 스크립트와 사용법이 유사합니다.

"Hello"[0] # "H" - 첫 번째 글자
"Hello"[-1] # "o" - 마지막 글자
len("Hello") # 5 - 글자 수

예시 코드를 보면 len()이라는 내장 함수가 보이시나요? 자바스크립트의 .length와 같습니다.

그리고 문자열을 변환하는 메서드도 있는데요. 보시면 메서드들이 익숙하실 것 같습니다.

"hello".upper() # "HELLO" - 대문자로
"HELLO".lower() # "hello" - 소문자로
" hi ".strip() # "hi" - 앞뒤 공백 제거

.lower()는 위에 설명한 input()을 사용하여 사용자 입력을 받을 때 유용합니다. 예를 들어 "yes"를 입력받아야 하는데 사용자가 "YES"나 "Yes"라고 입력할 수도 있잖아요. 이럴 때 .lower()로 소문자로 통일하면 모든 경우를 처리할 수 있습니다.

answer = input("계속하시겠습니까? (yes/no) ").lower()
if answer == "yes":
    print("계속합니다!")

타입 변환하기

문자를 숫자로, 숫자를 문자로 바꿀 수 있습니다.

str(123) # "123" - 숫자를 문자로
int("456") # 456 - 문자를 정수로
float("3.14") # 3.14 - 문자를 실수로

이게 왜 필요하냐면... input()으로 받은 건 무조건 문자열이기 때문입니다.

예를 들어 숫자 123을 입력해도 "123"처럼 문자로 들어옵니다. 그래서 계산하려면 int()로 바꿔줘야 합니다.

연산자

파이썬에서는 기본적인 사칙연산 외에도 다양한 연산자를 지원합니다.

print(3 + 5) # 8 (더하기)
print(7 - 4) # 3 (빼기)
print(3 * 2) # 6 (곱하기)
print(6 / 3) # 2.0 (나누기 - 항상 소수점이 나옵니다!)
print(6 // 3) # 2 (나누기 - 정수만)
print(2 ** 3) # 8 (제곱 - 2의 3승)

참고로 /로 나누면 무조건 소수점이 나옵니다. 6 / 3을 해도 2.0이 나옵니다. 정수로 받고 싶으면 //를 써야 합니다.

그 외 유용한 함수들

round(3.14159, 2) # 3.14 (소수점 둘째 자리까지 반올림)
abs(-5) # 5 (절대값)

f-string

변수 값을 문자열 안에 넣고 싶을 때 +로 일일이 연결하면 코드가 길어지고 읽기도 불편합니다. f-string을 쓰면 f"..." 안에 {변수}를 바로 넣을 수 있어서 훨씬 깔끔합니다.

${} 와 같은 코드라고 보시면 될 것 같아요. (저는 이 부분이 조금 신기했습니다 ㅎ)

name = "혜름"
age = 25
print(f"제 이름은 {name}이고, 나이는 {age}살입니다.")

3. 조건문

if, elif, else

코드를 작성하다 보면 특정 조건에 따라 다른 동작을 하게 만들어야 할 때가 있습니다. 예를 들어 사용자의 입력값에 따라 다른 결과를 보여준다거나, 특정 값이 기준을 넘는지 확인하는 경우입니다.

height = int(input("키가 몇 cm예요? "))

if height >= 120:
    print("놀이기구 탑승 가능")
else:
    print("놀이기구 탑승 불가")

if 다음에 조건을 쓰고, 그게 맞으면(참이면) 아래 코드가 실행됩니다. 아니면 else 쪽이 실행됩니다

조건이 여러 개면 elif를 씁니다. (자바스크립트에 비해 축약이 된 느낌이에요.)

age = int(input("나이가 몇 살이에요? "))

if age < 20:
    print("미성년자입니다")
elif age < 65:
    print("성인입니다")
else:
    print("경로 우대 대상입니다")

파이썬에서는 들여쓰기가 정말 중요합니다. 해당 코드가 어디에 속하는지를 들여쓰기로 구분하기 때문에, 꼭 확인해주어야 할 부분이에요. (중요!!)

4. 리스트와 랜덤

리스트

여러 개의 데이터를 하나의 변수에 묶어서 관리하고 싶을 때 리스트를 사용합니다. 예를 들어 과일 이름 세 개를 각각 변수로 만들면 번거롭지만, 리스트로 묶으면 하나로 관리할 수 있습니다.

fruits = ["사과", "배", "포도"]
print(fruits[0]) # "사과" - 첫 번째
print(fruits[-1]) # "포도" - 마지막

[0]처럼 인덱스로 특정 위치의 값을 꺼낼 수 있고, -1을 쓰면 마지막 값을 바로 가져올 수 있습니다.

fruits.append("딸기") # 마지막에 추가
print(fruits) # ["사과", "배", "포도", "딸기"]

리스트에서 특정 값의 위치를 찾을 수도 있습니다.

fruits = ["사과", "배", "포도"]
fruits.index("배") # 1 - "배"가 몇 번째에 있는지

이건 암호화 같은 걸 만들 때 유용합니다. 알파벳 리스트에서 특정 글자의 위치를 찾고, 그 위치를 이동시켜서 다른 글자로 바꾸는 식으로요.

리스트 안에 리스트를 넣을 수도 있습니다 (중첩 리스트).

matrix = [
    [1, 2, 3],
    [4, 5, 6]
]
print(matrix[0][1]) # 2 - 첫 번째 리스트의 두 번째 값

random 모듈

무작위 값이 필요할 때 사용하는 모듈입니다. 비밀번호 생성기처럼 랜덤한 값을 뽑아야 하거나, 리스트의 순서를 섞어야 할 때 유용합니다. import random을 먼저 써야 사용할 수 있습니다.

import에 대한 부분은 8.모듈 쪽에 설명해두었습니다.

import random

random.randint(1, 10) # 1~10 중 무작위 정수
random.random() # 0~1 사이 무작위 실수
random.choice(fruits) # 리스트에서 무작위로 하나 선택
random.shuffle(fruits) # 리스트 순서를 섞기

5. for와 while

for

(아시는 것이겠지만...) 같은 작업을 여러 번 해야 할 때 일일이 코드를 반복해서 쓰면 비효율적입니다. for를 쓰면 리스트에 있는 값들을 하나씩 꺼내면서 같은 작업을 반복할 수 있습니다.

fruits = ["사과", "배", "포도"]

for fruit in fruits:
    print(fruit)
# 사과
# 배
# 포도

range()와 같이 쓰면 숫자로 반복할 수 있습니다.

for i in range(5):
    print(i)  # 0, 1, 2, 3, 4

for i in range(1, 11):
    print(i)  # 1부터 10까지

for i in range(1, 11, 2):
    print(i)  # 1, 3, 5, 7, 9 (2씩 증가)

while

for는 반복 횟수가 정해져 있을 때 쓰지만, while은 특정 조건이 만족되는 동안 계속 반복합니다. 예를 들어 사용자가 "종료"를 입력할 때까지 프로그램을 계속 실행시키고 싶을 때 사용할 수 있습니다.

count = 0
while count < 5:
    print(count)
    count += 1

다만 조건이 영원히 참이면 무한 반복에 빠지기 때문에, 반복이 끝나는 조건을 잘 설정해야 합니다.

6. 함수

함수 정의하기

같은 코드를 여러 곳에서 반복해서 쓰고 있다면, 함수로 만들어두면 한 번 정의해놓고 필요할 때마다 호출해서 쓸 수 있습니다.

def greet():
    print("안녕하세요!")
    print("반갑습니다!")

greet()  # 함수 호출
greet()  # 또 호출 가능

매개변수

함수를 호출할 때 값을 넘겨주면, 함수 안에서 그 값을 사용할 수 있습니다. 이때 넘겨주는 값을 매개변수라고 합니다. (어디에나 동일한 개념이죠.)

def greet(name):
    print(f"안녕하세요, {name}님!")

greet("혜름")  # "안녕하세요, 혜름님!"
greet("연주")  # "안녕하세요, 연주님!"

매개변수는 여러 개도 가능합니다.

def greet(name, time):
    print(f"{time}이에요, {name}님!")

# 위치로 구분 (positional arguments)
greet("혜름", "아침")

# 이름으로 지정 (keyword arguments)
greet(time="저녁", name="연주")

return

함수가 단순히 print()로 출력만 하는 게 아니라, 처리한 결과를 돌려줘야 할 때가 있습니다. 그때 return을 사용합니다. 돌려받은 값은 변수에 저장해서 다른 곳에서 활용할 수 있습니다.

def add(a, b):
    return a + b

result = add(3, 5)
print(result)  # 8

7. 딕셔너리

Key-Value 쌍

리스트는 데이터를 순서대로 저장하지만, 데이터에 의미 있는 이름을 붙여서 관리하고 싶을 때는 딕셔너리가 더 적합합니다. 딕셔너리는 키(key)와 값(value)을 쌍으로 저장합니다.

자바스크립트와 명칭이 다를 뿐, 오브젝트와 같다고 이해하시면 될 것 같아요.

student = {
    "이름": "혜름",
    "나이": 20,
    "성적": 85
}

print(student["이름"])  # "혜름"
print(student["나이"])  # 20

리스트는 [0], [1]처럼 순서로 접근하지만, 딕셔너리는 ["이름"]처럼 키로 접근합니다. 값을 추가하거나 수정하는 것도 간단합니다.

student["주소"] = "서울"  # 추가
student["나이"] = 21      # 수정

딕셔너리 안에 딕셔너리를 넣을 수도 있습니다 (중첩 딕셔너리).

users = {
    "혜름": {
        "나이": 20,
        "취미": ["필라테스", "게임"]
    },
    "연주": {
        "나이": 22,
        "취미": ["필라테스"]
    }
}
print(users["혜름"]["나이"])  # 20
print(users["연주"]["취미"][0])  # "필라테스"

딕셔너리 순회하기

for key in student:
    print(f"{key}: {student[key]}")

8. 모듈

import

파이썬에는 이미 만들어진 기능들이 많은데, 필요할 때 import로 가져다 쓸 수 있습니다. 앞에서 살펴본 random도 이런 식으로 불러온 모듈입니다.

import random
random.randint(1, 10)

파이썬이 기본으로 제공하는 모듈 외에, 직접 만든 파일도 모듈로 사용할 수 있습니다.

# my_data.py 파일
pi = 3.14159

# main.py 파일
import my_data
print(my_data.pi)  # 3.14159

# 또는 특정 변수/함수만 가져오기
from my_data import pi
print(pi)  # 3.14159

마치며

이번 글에서는 print, input부터 시작해서 데이터 타입, 조건문, 반복문, 함수, 딕셔너리, 모듈까지 파이썬의 기초적인 문법들을 살펴봤습니다. 공부를 계속하면서 새로 알게 되는 내용이 있으면 이어서 정리해보겠습니다.

부족한 글 읽어주셔서 감사합니다. ‍♀️

그럼 안녕히…

이 글은 https://tech.pxd.co.kr/ 에서도 보실 수 있습니다.

참고 자료

100 Days of Code: The Complete Python Pro Bootcamp

"AI에게 우리를 소개하고 싶었습니다", UX 전문 기업이 GEO 서비스를 만든 이유

GEONIQ — Tue, 7 Apr 2026 17:12:27 +0900

시작은 하나의 질문이었습니다

pxd는 대한민국에서 UX/UI 분야를 대표하는 사용자경험(UX) 디자인 전문 기업입니다. AI에게 "대한민국에서 UX/UI 컨설팅 잘하는 업체 추천해줘"라고 물으면, pxd는 빠지지 않고 언급됩니다.

그런데 한 가지 의문이 생겼습니다.

"화면 UI 개발을 잘하는 회사는?" — pxd, 언급 없음.

"프론트엔드 개발을 잘하는 회사는?" — pxd, 역시 언급 없음.

2002년에 설립된 pxd는 2019년부터 UX 컨설팅 및 리서치, 설계, 디자인 뿐만 아니라 UI개발 및 프론트엔드개발까지 수행하는 회사가 되었습니다. 그런데 AI는 그 사실을 모르고 있었습니다. 왜일까요?

이 질문을 파고들면서 저희는 GEO(Generative Engine Optimization)와 AIEO(AI Engine Optimization)라는 영역을 발견했습니다. AI에게 잘 인용되려면 단순히 좋은 콘텐츠를 만드는 것만으로는 부족하다는 것, AI가 이해하고 신뢰할 수 있는 구조로 콘텐츠를 제공해야 한다는 것을 알게 되었습니다.

그래서 생각했습니다.

"우리만 이 문제를 겪고 있는 건 아닐 거야. 좋은 서비스나 상품을 제공하고 있거나 만들고도 AI에게 제대로 소개되지 못하는 곳이 얼마나 많을까? 그렇다면, AI에게 잘 인용될 수 있는 방법을 알려주자."

이것이 GEONIQ(지오닉)의 시작이었습니다.

그리고 2025년 11월, 그 고민을 담아 "AI 검색 시대의 새로운 기준, GEONIQ(지오닉)을 소개합니다"라는 글과 함께 베타 서비스를 세상에 공개했습니다.

그로부터 약 4개월. 수많은 피드백과 개선을 거쳐, 오늘 GEONIQ이 정식 서비스로 오픈합니다.

베타 오픈 전 진행한 예비 사용자 조사에서 다음과 같은 피드백들을 받았습니다.

"국내에 GEO(AIEO)까지 포함한 통합 SEO 진단 도구가 없었는데, 한국어 환경에 맞게 최적화해 제공하는 점이 좋습니다." — 6년 경력 스타트업 퍼포먼스 마케터

"유사한 국내 서비스와 비교했을 때, UI·UX 완성도와 리포트 품질이 압도적으로 높습니다." — 10년 경력 대기업 퍼포먼스 마케터

이 목소리들이 정식 오픈을 준비하면서 저희가 가장 집중한 방향이기도 합니다.

베타에서 정식 오픈까지, 지오닉은 어떻게 달라졌을까?

스스로를 진단하며 성장했습니다

정식 오픈 전, 먼저 우리 자신부터 진단했습니다. geoniq.ai를 GEONIQ으로 지속적으로 분석하고, 개선 가이드를 따라 고치고, 다시 진단하는 과정을 반복했습니다. 그 결과를 숫자로 보여드립니다.

항목	베타 (2025.11)	현재 (2026.04)
종합 점수	60점	98점
기술 최적화	40점	100점
콘텐츠 품질	85점	100점
성능 및 사용자 경험	100점	100점
콘텐츠 신뢰성	26점	77점
보안 및 정책 준수	44점	95점
정상 항목	37개	62개
조치 필요 항목	24개	0개

진단하고, 가이드를 따라 고치고, 다시 진단하는 과정을 반복하며 조치가 필요한 항목을 모두 해결했습니다. 저희가 만든 도구로 저희 서비스를 직접 개선한 것, 이것이 실 검증된 GEONIQ의 가치입니다.

AI가 GEONIQ을 알아보기 시작했습니다

GEONIQ이 SEO/GEO 개선에 실제 효과가 있는지 확인하기 위해 "SEO, GEO(AIEO) 검증하는 국내 사이트 추천해줘"라는 질문을 다양한 AI에게 직접 던져봤습니다. 베타 초기에는 어떤 AI도 GEONIQ을 언급하지 않았습니다. 하지만 시간이 지나면서 변화가 시작됐습니다.

(아래 결과는 사용자 편향을 최소화하기 위해 각 플랫폼에서 신규 계정을 생성한 후, “SEO, GEO(AIEO) 검증이 가능한 국내 사이트를 추천해줘”라는 동일한 질문을 한 달 간격으로 반복하여 얻은 것입니다.)

ChatGPT의 답변 (2026년 1월)

gpt 답변 내용

ChatGPT는 GEONIQ을 국내 SEO+GEO 도구 추천 목록의 첫 번째로 소개했습니다.

Perplexity의 답변 (2026년 2월)

perplexity 답변 내용

Perplexity 역시 GEO 진단 도구를 추천하면서 GEONIQ을 가장 먼저 언급했습니다.

Gemini의 답변 (2026년 3월)

gemini 답변 내용

Gemini 또한 GEONIQ을 국내 GEO/AIEO 특화 진단 솔루션으로 첫 번째로 소개했습니다.

"AI에게 우리를 소개하고 싶다"는 바람에서 시작한 서비스가, 이제 AI로부터 직접 추천받고 있습니다. GEONIQ이 추구하는 가치가 실제로 작동하고 있음을 보여주는 결과입니다.

정식 오픈, 새로운 기능과 더 고도화된 분석

베타에서 정식 오픈까지, GEONIQ은 단순 수정이나 개선 가이드 제시를 넘어 서비스 전반을 한 단계 끌어올렸습니다.

1. 마이페이지: 내 사이트를 체계적으로 관리

베타에서는 분석 결과를 한 번 보고 끝이었습니다. 이제는 다릅니다.

대시보드: 주요 사이트를 고정하고 점수 변화를 한눈에 추적합니다. 이전 대비 몇 점이 올랐는지, 어떤 항목이 개선됐는지 시각적으로 확인할 수 있습니다.
점수 추이 차트: 시간에 따른 점수 변화를 라인 차트로 시각화합니다. 개선 작업의 효과를 데이터로 확인하세요.
사이트 비교: 경쟁 사이트와 나란히 비교합니다. 카테고리별 점수를 바 차트로 비교해 우리 사이트의 강점과 약점을 파악할 수 있습니다.
분석 이력 관리: 모든 분석 기록이 사이트별로 그룹핑되어 저장됩니다.

2. AI 개선 가이드 강화

베타에서도 제공하던 AI 기반 개선 제안이 더욱 정밀해졌습니다.

As-Is / To-Be 코드 비교: 현재 코드와 개선된 코드를 나란히 보여줍니다. 무엇을 어떻게 고쳐야 하는지 개발자가 아니어도 이해하고 수정할 수 있습니다.
연관 검사 안내: "이 항목을 개선하려면 먼저 이 항목을 확인하세요"와 같은 선행 개선 조건을 안내합니다.

3. PDF 리포트: 공유하고, 보고하고, 실행하는 보고서

진단 결과를 체계적인 PDF 보고서로 다운로드할 수 있습니다. 사내 보고나 고객 제안서에 바로 활용하세요.

즉시 프린트 가능한 보고서: 종합 점수, 카테고리별 분석, 개선 제안이 담긴 체계적인 PDF 보고서를 제공합니다.

4. 팀 협업: 같은 데이터를 함께 보며 함께 개선

혼자만 보는 리포트가 아니라, 팀과 함께 보는 리포트가 됩니다.

팀원을 이메일로 초대하여 분석 결과를 공유
마케터, 개발자, 기획자 등이 같은 데이터를 보며 개선 방향을 논의
외부 이해관계자에게도 URL로 간편하게 전달 공유 가능

5. 진단 정확도 & 성능 개선

GEONIQ만의 체크리스트 항목의 검증 로직을 지속적으로 고도화
분석 속도 최적화 (병렬 처리, 캐싱 전략 개선)
SPA/CSR 사이트 분석 정확도 향상
리포트 UI/UX 전면 개편으로 가독성 향상

플랜 안내

GEONIQ은 체험부터 기업 맞춤까지, 운영 규모에 맞는 4가지 플랜을 제공합니다.

Starter — GEONIQ을 처음 체험해보고 싶다면
Basic — 개인·실무 중심의 일반 운영
Pro — 전문가·팀 중심의 확장 운영
Enterprise — 기관·기업 전용 맞춤형 통합 플랜

무료 회원도 진단 기능을 이용할 수 있습니다. 단, 일부 제한이 있을 수 있으며, 유료 플랜 사용자에게 전체 개선 가이드, 대시보드, 사이트 비교, 팀 공유 기능 등이 제공됩니다.

각 플랜의 상세 내용은 geoniq.ai에서 확인하세요.

앞으로의 GEONIQ

정식 오픈은 끝이 아닌, 새로운 시작이라 생각합니다.

"AI에게 우리를 소개하고 싶다"는 하나의 질문에서 출발한 GEONIQ은, 이제 모든 서비스가 다양한 AI 엔진들에게 발견되고 신뢰받을 수 있도록 돕는 도구로 성장하려고 합니다. AI 검색 환경의 변화에 맞춰 분석 항목과 로직을 지속적으로 업데이트 하며 고도화해 나갈 예정입니다.

Google의 AI Overviews가 확대되고, ChatGPT와 Perplexity의 검색 기능이 고도화되면서, "AI에게 이해되고 인용되는 콘텐츠"의 중요성은 앞으로 더 커질 것입니다.

GEONIQ은 이 변화의 속도를 따라가며, 여러분의 사이트가 어디에서든 인용되고 신뢰받을 수 있도록 돕겠습니다.

지금 시작하세요

URL을 입력하는 것만으로 진단을 시작할 수 있습니다.

검색엔진과 생성형 AI가 이해하고 신뢰하는 콘텐츠 구조, 사람이 신뢰하는 경험, 그 연결의 기준을 GEONIQ이 제시합니다.

여러분의 사이트는 지금, AI에게 어떻게 보이고 있나요?

Next.js App Router에서 프록시 레이어를 둔 이유

seonju.lee — Mon, 6 Apr 2026 10:00:17 +0900

들어가며

GEONIQ(SEO/GEO(AI Engine Optimization)를 분석해주는 서비스) 개발에 저도 같이 참여하게 되었는데 프론트엔드는 Next.js의 App Router, 백엔드는 FastAPI로 구성되어 있어 프론트엔드에서 백엔드 API를 호출할 일이 많았습니다.

처음에는 프론트엔드에서 백엔드를 직접 호출하는 단순한 구조로 시작했지만, 개발을 진행하면서 CORS 문제라든지, 작업 환경에 따라 URL이 각각 바뀌는 것에 의해 필연적으로 ”중간에 서버인 Proxy 서버 ”가 필요해 졌습니다.

이 글은 Next.js API Routes를 활용해 API 프록시 레이어를 만들게 된 과정과, 만들고 나서 느낀 점을 이야기해 보려고 합니다

프론트엔드가 백엔드를 직접 호출하면 안 되나?

실제로 많은 프로젝트가 프론트엔드에서 백엔드 API를 직접 호출합니다. 하지만 직접 호출로는 해결하기 어려운 문제들이 하나둘 생기기 시작했습니다.

문제 1: CORS
프론트엔드(localhost:3000)에서 백엔드(localhost:8001)를 직접 호출하면 CORS 설정이 필요합니다. 백엔드에서 “Access-Control-Allow-Origin:*”와 같이 추가해서 관리하면 되지만, 환경이 늘어날 때마다 양쪽을 맞춰줘야 합니다. (별거 아닌 것 같지만, 개발 중에 CORS 오류로 시간을 쓰지 않아도 된다는 건 생각보다 편합니다 :-))

이런 필요들이 모여서 만들어진 API 라우트 구조는 이렇습니다.

app/api/
├─ [...path]/route.ts   ← catch-all 프록시
└─ auth/
├─ set-tokens/route.ts     ← 토큰 저장 (쿠키 관리)
├─ refresh/route.ts   ← 토큰 갱신
├─ me/route.ts     ← 사용자 정보 조회
└─ logout/route.ts     ← 로그아웃

async function proxyRequest(
  request: NextRequest,
  params: Promise<{ path: string[] }>,
  method: string,
) {
  const { path } = await params;
  const accessToken = request.cookies.get("access_token")?.value;
  if (!accessToken) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  // 경로 조합: /api/example/123 → 백엔드의 /test-api/example/123
  const { searchParams } = new URL(request.url);
  const queryString = searchParams.toString();
  const apiPath = path.join("/");
  const url = `${API_BASE}/admin/${apiPath}${queryString ? `?${queryString}` : ""}`;
  const body = method !== "GET" && method !== "DELETE" ? await request.text() : undefined;
  const response = await fetch(url, {
    method,
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body,
    signal: controller.signal,
  });

  const data = await response.json();
  return NextResponse.json(data, { status: response.status });
}
// 모든 HTTP 메서드를 동일한 함수로 처리
export async function GET(req, { params }) {
  return proxyRequest(req, params, "GET");
}

export async function POST(req, { params }) {
  return proxyRequest(req, params, "POST");
}

httpOnly 쿠키에서 access_token을 꺼낸다.
요청 경로 앞에 /test-api/을 붙여 백엔드 URL을 조합한다.
Authorization 헤더에 토큰을 실어 백엔드로 전달한다.

문제 2: 백엔드 URL이 환경마다 다르다

관리자 백엔드는 localhost:8001(개발)과 프로덕션 서버가 다릅니다. 클라이언트에서 직접 호출하면 이 URL이 브라우저에 그대로 노출되는데 관리자 API의 주소가 외부에 드러나는 건 보안상 좋지 않아 서버 사이드에서 URL을 결정하면, 보안상의 문제도 해결할 수 있습니다.

// 환경변수로 백엔드 URL 결정 (서버 사이드에서만 접근)

const API_BASE =
  process.env.API_BASE_URL ||
  process.env.NEXT_PUBLIC_API_BASE_URL ||
  "http://localhost:8001";

문제 3: 인증 토큰을 안전하게 관리해야 한다

관리자 사이트는 Google OAuth로 로그인합니다. 백엔드에서 받은 JWT 토큰을 어디에 저장할 것인가의 문제가 있었습니다. localStorage에 넣으면 XSS에 취약하고, 일반 쿠키는 JavaScript에서 접근 가능합니다.

결국 httpOnly 쿠키를 사용하게 되었는데 이 쿠키는 브라우저 JavaScript에서 읽을 수 없으므로, 서버에서 꺼내 백엔드로 전달하는 중간 레이어가 필요해졌습니다. 이것이 API 프록시 레이어가 필요한 가장 직접적인 이유였습니다.

프록시 서버를 이용한 장점 1 : 코드가 깔끔해진다.

클라이언트 코드의 단순함입니다. 백엔드 URL도 모르고, 토큰 관리도 신경 쓸 필요가 없습니다.토큰 전달도 없이 그냥 /api/로 호출하여 간단히 작성했습니다.

export const getTextAPI = async (params): Promise<TTextListResponse> => {
  const response = await fetch(`/test-api/test?${searchParams.toString()}`, {
    credentials: "include",  // 쿠키 자동 전송
  });
  return response.json();
};

export const patchTextAPI = async (id, data) => {
  const response = await fetch(`/test-api/test/${id}/`, {
    method: "PATCH",
    credentials: "include",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(data),

  });
  return response.json();
};

/api/test → catch-all이 /test-api/test로 변환 → 쿠키에서 토큰 꺼내서 Authorization 헤더에 주입 → 백엔드로 전달. 이 모든 과정이 프록시 레이어 안에서 자동으로 일어납니다. 새 기능이 추가될 때도 클라이언트에서 /api/test2를 호출하는 함수만 추가하면 되고 프록시 쪽은 건드릴 필요가 없어 좋습니다.

프록시 서버를 이용한 장점 2 : OAuth 콜백 흐름

인증 전체 흐름을 보면 프록시 레이어의 역할이 좀 더 명확졌던 것 같습니다.

사용자가 "Google 로그인" 클릭
백엔드(admin-api)의 OAuth URL로 이동
Google 인증 완료 → 백엔드가 콜백 처리
백엔드가 프론트엔드로 리다이렉트 (URL에 토큰 포함)
→ /auth/callback/google?access_token=xxx&refresh_token=yyy
콜백 페이지에서 /test-api/test-auth/tokens 호출 (BFF)
→ httpOnly 쿠키에 토큰 저장
/test-api/test-auth/is-admin 호출해서 관리자 권한 확인
대시보드로 이동

토큰이 URL 파라미터로 잠깐 노출되긴 하지만, 곧바로 httpOnly 쿠키에 저장되고 URL에서 사라집니다. 이후 모든 요청은 쿠키가 자동 전송되므로, 클라이언트 코드에서 토큰을 직접 다룰 일이 없습니다.

마치며

사실 이 API 프록시 레이어는 "좋은 아키텍처를 설계하겠다"는 의도보다, 보안이나 CORS 같은 실무적인 문제를 풀기 위해 자연스럽게 만들어진 결과물이었습니다.

Next.js App Router를 사용하고 계신다면, API Routes가 단순한 서버리스 함수가 아니라 프론트엔드와 백엔드 사이의 유용한 중간 레이어가 될 수 있다는 점을 한번 고려해 보시면 좋겠습니다. 특히 [...path] catch-all 라우트 하나로 일반 프록시를 처리하고, 보안이 필요한 라우트만 개별로 분리하는 패턴은 코드 양 대비 꽤 실용적이었다고 생각합니다.

읽어주셔서 감사합니다.

이 글은 https://tech.pxd.co.kr/ 에서도 보실 수 있습니다.

GEONIQ Integrated Insight Report — 여행·숙박 플랫폼 (Vol.3 선택이 이어지는 구조 조건 분석)

GEONIQ — Mon, 6 Apr 2026 07:50:27 +0900

리포트는 GEO(AIEO)와 SEO를 한 번에 통합 분석해주는 GEONIQ의 진단 기준에 따라 국내 주요 여행·숙박 플랫폼의 페이지 구조와 정보 구성 방식을 분석하고 AI·검색 환경에서 숙소 상품이 선택 단계로 이어지기 위해 필요한 구조적 조건을 관찰·정리한 분석 보고서이다.

좌측부터 우측 방향으로 네이버 여행, 야놀자, 여기어때 메인 페이지 이미지

1) 이번 분석의 관점과 범위

Vol.1에서는 숙소 정보가 AI검색(GEO) 환경에서 어떤 단위로 인식되는지를 살펴봤다.
Vol.2에서는 그 인식이 왜 선택으로 이어지지 않는지를 선택 시도–비교–검증 흐름을 기준으로 관찰했다.

이번 Vol.3에서는 앞선 두 편의 관찰을 전제로 선택이 실제로 이어지기 위해 필요한 구조적 조건을 정리한다.
이 조건은 특정 기능이나 UI의 문제가 아니라 여러 플랫폼에서 반복적으로 확인되는 구조적 패턴을 기준으로 도출된다.

2) AI검색(GEO) 관점에서의 선택

이 리포트에서 말하는 선택은 단순한 예약 행위를 의미하지 않는다.
AI검색(GEO) 관점에서의 선택은 여러 숙소가 동일한 기준 위에서 연결되고, 그 중 하나가 상대적 맥락 안에서 판단되는 상태를 의미한다.

GEO(AIEO) 환경에서는 숙소 간 관계가 구조적으로 드러날 때 선택이 형성된다.

3) 핵심 발견 (Key Findings)

Key Finding 1

선택은 ‘후보 집합’이 형성될 때 시작된다.

현재 구조에서는 숙소가 개별 정보 단위로 분리되어 인식된다.
그 결과 여러 숙소가 존재하더라도 하나의 선택 후보 집합으로 묶이지 않는다.
선택은 개별 정보가 아니라 서로 비교 가능한 후보 집합이 형성될 때 시작된다.

Key Finding 2

선택은 ‘비교 기준이 구조로 드러날 때’ 형성된다.

가격, 평점, 위치와 같은 정보는 대부분 존재하지만, 이 정보들이 동일 기준 위에서 정렬된 구조로 표현되지 않으면 비교는 형성되지 않는다.
선택은 정보의 양이 아니라 비교 기준이 구조로 표현될 때 발생한다.

Key Finding 3

선택은 ‘흐름이 유지되는 구조’에서 이어진다.

사용자는 여러 숙소를 탐색하고 비교한다.
그러나 상세 페이지 진입 이후 다른 후보와의 연결이 단절되면 선택 과정은 반복적으로 끊긴다.
선택은 단일 페이지에서 완결되지 않는다.
후보 간 이동과 비교가 유지되는 흐름 안에서 이어진다.

4) 구조적 조건으로 본 선택 가능 상태

GEONIQ 진단 결과를 기준으로 보면 AI검색(GEO) 환경에서 선택이 형성되기 위해서는 다음 조건이 함께 충족되어야 한다.

① 후보 집합 구조

여러 숙소가 단순 나열이 아니라 동일 조건 기반의 후보 집합으로 묶여 있어야 한다.

동일 지역
동일 일정
동일 인원 조건

이 조건이 구조적으로 유지될 때 숙소는 비교 가능한 단위로 인식된다.

② 비교 기준 구조

각 숙소의 정보는 개별적으로 존재하는 것이 아니라 동일 기준 위에서 정렬 가능한 형태로 표현되어야 한다.

가격
평점
위치
예약 가능 여부

이 기준이 구조로 드러날 때 비교는 자연스럽게 형성된다.

③ 흐름 유지 구조

하나의 숙소를 확인한 이후에도 다른 후보와의 관계가 유지되는 흐름이 필요하다.

유사 숙소 연결
동일 조건 기반 후보 이동
이전 후보 집합으로의 복귀 흐름

이 흐름이 유지될 때 선택은 단절되지 않고 이어진다.

5) 구조 관점에서의 정리

이번 분석을 통해 확인된 것은 여행·숙박 플랫폼의 기능 부족이 아니다.

다음 요소들은 이미 충분히 갖춰져 있다.

숙소 정보는 충분히 제공된다
사용자 탐색 흐름은 안정적으로 설계되어 있다
SEO 관점에서의 노출 구조도 확보되어 있다

그러나 동시에 다음 조건이 함께 나타난다.

숙소가 후보 집합으로 묶이지 않는다
비교 기준이 구조로 표현되지 않는다
탐색 이후 흐름이 유지되지 않는다

이 구조에서는 정보는 충분하지만 선택은 이어지지 않는다.

지오닉 검증 결과 바로가기
네이버 여행 메인	야놀자 메인	여기어때 메인이자 목록
네이버 여행 목록	야놀자 목록	-
네이버 여행 상세	야놀자 상세	여기어때 상세

pxdAX 관찰 노트 (종합)

이번 여행·숙박 플랫폼 연재에서 확인된 것은 정보의 부족이 아니다.

Vol.1에서는 숙소가 어떻게 인식되는지를 살펴봤다.
숙소는 분명히 보이고 있었다.

Vol.2에서는 그 다음 단계를 확인했다.
선택은 시작되지만 구조적으로 이어지지 않았다.

Vol.3에서는 그 이유를 구조의 관점에서 정리했다.
선택은 정보의 양이 아니라 구조적 조건이 형성될 때 비로소 발생한다.

숙소는 이미 충분히 설명되어 있다.
그러나 그 정보는 사람의 탐색을 기준으로 배열되어 있을 뿐, AI검색(GEO) 환경에서 선택으로 이어지는 구조로 정리되어 있지는 않다.
그 결과 보이는 것과 선택되는 것 사이에는 간극이 남는다.

그 간극은 기능으로 채워지지 않는다.
그 간극은 구조로만 연결된다.

정보는 이미 충분하다.
보이는 것과 선택되는 것의 차이는 정보의 양이 아니라 구조의 문제이다.
선택은 더 많은 정보를 통해 만들어지는 것이 아니라 비교와 흐름이 가능한 구조가 형성될 때 비로소 발생한다.

이제 필요한 것은 정보를 더하는 것이 아니라
선택이 이어지는 구조를 만드는 일이다.

GEONIQ 서비스 바로가기

GEONIQ Integrated Insight Report는 GEONIQ, pxd story, xe group tech blog 에서 동시 발행 됩니다.

GEONIQ Integrated Insight Report — 여행·숙박 플랫폼 (Vol.2 선택 구조와 비교 흐름 분석)

GEONIQ — Thu, 2 Apr 2026 07:50:54 +0900

본 리포트는 GEO(AIEO)와 SEO를 한 번에 통합 분석해주는 GEONIQ의 진단 기준에 따라 국내 주요 여행·숙박 플랫폼의 페이지 구조와 정보 구성 방식을 분석하고 AI·검색 환경에서 숙소 상품이 선택 단계로 어떻게 이어지거나 단절되는지를 관찰·정리한 분석 보고서이다.

좌측부터 우측 방향으로 네이버 여행, 야놀자, 여기어때 메인 페이지 이미지

1) 이번 분석의 관점과 범위

Vol.1에서는 SEO 이후 단계인 GEO(AIEO) 환경에서 숙소 정보가 어떤 단위로 인식되는지를 살펴봤다.
숙소 정보는 충분히 존재하지만, 상품 단위로 구조화되어 있지 않다는 점이 확인되었다.

이번 Vol.2에서는 그 다음 단계인 선택 구조를 다룬다.
즉, 인식 이후 사용자의 선택 시도가 어떤 흐름을 거쳐 이어지거나 끊기는지를 구조적으로 살펴본다.

분석은 다음 흐름을 기준으로 진행한다.

선택 시도
비교 형성
검증 및 확정

이 세 단계가 웹 구조 내에서 어떻게 연결되거나 단절되는지를 GEONIQ 진단 기준으로 관찰한다.

2) 선택 시도는 어떻게 시작되는가

사용자는 일정, 인원, 지역, 가격과 같은 조건을 기반으로 숙소 탐색을 시작한다.

이 조건들은 플랫폼 내에서 잘 반영되어 있으며, SEO 유입 이후에도 자연스럽게 탐색 흐름으로 이어진다.
검색 결과에서 특정 숙소나 지역 페이지로 유입된 이후에도 탐색은 중단되지 않는다.
즉, 선택 시도 자체는 구조적으로 문제없이 발생하나, 이 흐름은 다음 단계에서 구조적 제약을 받는다.

3) 비교는 어떻게 제한되는가

선택이 이어지기 위해서는 여러 후보를 동일 기준 위에 놓고 비교할 수 있어야 한다.
GEONIQ 진단 결과, 다음과 같은 구조가 반복적으로 관찰된다.

숙소 목록은 존재하지만 비교 기준이 명시적으로 정렬된 구조로 표현되지 않는다
가격, 평점, 위치 등의 정보는 존재하지만 동일 기준으로 배열된 비교 구조는 제한적이다
유사 숙소 또는 대체 선택지로 이어지는 관계 구조가 명확히 드러나지 않는다

그 결과 사용자는 여러 숙소를 확인할 수는 있지만 동일 기준 위에서 후보를 비교하는 구조는 형성되지 않는다.

SEO 관점에서는 다양한 숙소 페이지가 노출되지만,
GEO(AIEO) 환경에서는 이 숙소들이 비교 가능한 집합으로 묶이지 않는다.

4) 검증 단계에서 흐름이 끊기는 이유

비교 이후에는 선택을 확정하기 위한 검증 단계가 이어져야 한다.
이 단계에서 사용자는 다음과 같은 정보를 확인한다.

실제 예약 가능 여부
가격 및 조건
객실 유형
리뷰 및 평점

이 정보들은 각 숙소 상세 페이지에 충분히 제공된다.
그러나 구조적으로 다음과 같은 흐름이 나타난다.

특정 숙소 상세 페이지 진입 이후 다른 후보와의 연결이 약화된다
상세 페이지는 단일 숙소 중심의 정보 소비 구조로 완결된다
이전에 탐색하던 후보 집합으로 다시 연결되는 흐름이 제한된다

그 결과 하나의 숙소를 깊게 이해할 수는 있지만 여러 후보를 비교한 상태에서 선택을 확정하는 흐름은 유지되기 어렵다.

5) 선택은 어디에서 완결되는가

이러한 구조에서 선택은 플랫폼 내부에서 자연스럽게 이어지지 않는다.
사용자는 다음과 같은 방식으로 선택을 이어간다.

여러 숙소 페이지를 반복적으로 이동하며 비교한다
별도의 비교 환경(앱, 검색 결과, 개인 메모 등)을 활용한다
개인 기준으로 정보를 재정리한다

즉, 선택은 플랫폼 내부의 구조가 아니라 사용자의 외부 판단 과정에서 완결되는 흐름을 보인다.

6) 구조 점검 관점에서 본 Actionable Signals

GEONIQ 진단 결과를 종합하면 선택이 이어지지 않는 이유는 선택 기준의 부족이 아니라 선택 흐름이 구조적으로 연결되지 않은 상태로 관찰되기 때문이다.

아래 항목은 GEO(AIEO) 관점에서 구조가 어디에서 끊기는지를 점검하기 위한 포인트이다.

숙소가 선택 후보 집합으로 묶이지 않고 개별 정보 단위로 분리되어 있다
후보 간 비교 기준이 명시적으로 정렬된 구조로 표현되지 않는다
유사 숙소 또는 대체 선택지로 이어지는 관계 구조가 제한적이다
상세 페이지 진입 이후 다른 후보로 이어지는 흐름이 단절된다
SEO 유입 이후 정보 소비 단계에서 흐름이 종료된다

이러한 조건에서 선택은 플랫폼 내부가 아니라 사용자 판단 과정에서 완결되는 경향을 보인다.

지오닉 검증 결과 바로가기
네이버 여행 메인	야놀자 메인	여기어때 메인이자 목록
네이버 여행 목록	야놀자 목록	-
네이버 여행 상세	야놀자 상세	여기어때 상세

pxdAX 관찰 노트

Vol.1에서는 숙소가 어떻게 인식되는지를 살펴봤다.
정보는 충분하지만, 상품 단위로 구조화되어 있지는 않았다.

Vol.2에서는 그 다음 흐름을 확인했다.
선택은 시작되지만 구조적으로 이어지지 않는다.

문제는 사용자가 기준을 갖고 있지 않아서가 아니다.
문제는 그 기준을 적용할 수 있는 구조가 형성되어 있지 않다는 점이다.

숙소는 나열되어 있지만 비교는 구조로 정리되어 있지 않다.
정보는 충분하지만 선택은 이어지지 않는다.

이 지점에서 하나의 차이가 드러난다.
보이는 것과 선택되는 것은 동일한 문제가 아니다.

그리고 그 사이에는 비교를 가능하게 만드는 구조가 필요하다.
이 구조는 다음 단계에서 더 명확히 드러난다.

선택은 기준이 많아서 발생하는 것이 아니라 비교가 가능한 구조가 형성될 때 비로소 이어진다.
다음 Vol.3에서는 이 선택이 실제로 이어지기 위해 어떤 구조적 조건이 필요한지를 정리한다.

GEONIQ 서비스 바로가기

GEONIQ Integrated Insight Report는 GEONIQ, pxd story, xe group tech blog 에서 동시 발행 됩니다.

[pxd talks] 계산기 말고 엑셀처럼... AI와 함께 일하는 ‘언러닝’의 기술

seulgeekim — Mon, 30 Mar 2026 07:50:01 +0900

pxd talks는 여러 분야의 연사님을 초빙해 인사이트를 나누는 시간입니다. pxd 구성원들이 더 넓은 시야로 무언가를 새롭게 발견하거나 자신을 성장시킬 수 있는 기회를 얻을 수 있도록 말이죠. 그리고 그 경험은 [pxd talks] 아티클로 기록합니다. pxd 구성원들이 함께 보고 듣고 느끼고 배운 것들이 사라지지 않고 pxd story에 남아 더 넓은 세상으로 뻗어갈 수 있기를 바랍니다.

다들 일할 때 AI 많이 사용하시나요? 이제 AI 없는 일터는 상상하기 어려운데요. 새로운 아이디어를 얻고 싶거나 참고자료를 찾을 때, 중요하지 않지만 손이 많이 가는 작업이 필요할 때 AI를 찾곤 하죠. 단순히 ‘일할 때 AI를 쓴다’를 넘어, AI 중심으로 업무 방식을 재구성하고 조직 문화, 운용 구조에 반영하는 ‘AI 전환(AI Transformation. AX)’을 목표로 하는 기업도 늘어나고 있어요.

그중 삼양라운드스퀘어 DXT팀은 성공적인 AX 사례를 보여주는 조직이에요. 올해 성과를 내야 하는데 개발자는 없고, 채용도 외주도 어렵다면? 막막한 상황에 처한 DXT팀이 선택한 건 바로 'AI 주도 개발(AI-Driven Development)'이었어요. 기존의 성공 방정식을 과감히 버리고 AI와 함께 전 팀원이 바이브 코더(Vibe Coder)가 된 DXT팀의 실험과 도전, 그 생생한 이야기를 PM 최동운 님과 pxd talks로 만나볼게요.

용기로 뗀 첫걸음 “일단 해보자!”

‘불닭볶음면’으로 전 세계 입맛을 사로잡은 삼양스퀘어라운지의 다음 스텝은 IT 신사업이었어요. 하지만 추가 채용이나 적절한 외주 업체를 찾는 건 쉽지 않은 일이었죠. 소수의 팀원이 단기간에 성과를 보여야 하는 상황에서 DXT팀은 ‘바이브 코딩’이라는 돌파구를 발견했다고 해요.

“모두가 코딩을 해보자는 마음으로 시작했어요. 힘들겠지만, 어쩌면 기회일 수도 있다고 생각했죠.”

DXT팀은 ‘우리의 아이디어를 프로토타이핑해 보자’를 목표로 챗GPT와 레플릿(Replit)를 적극 활용했어요. 챗GPT로 요구사항을 정리하고 레플릿으로 배포하기까지, 단 4시간이면 충분했죠.

노션(Notion), PPT, 피그마(Figma)를 동원해 자료를 공유하고 관계자를 설득해야 했던 기존 방식과 비교하면 획기적인 효율이었어요. 최동운 님은 이 프로토타입 덕분에 경영진과 수월하게 소통할 수 있었고 빠르게 다음 단계로 진입할 수 있었다고 해요.

코딩을 AI가 하면, 사람은?

실제 제품 개발에 들어가면서 DXT팀의 개발 풍경은 완전히 달라졌어요. 실험적 성격의 프로토타입과 달리 높은 완성도를 확보해야 했거든요. 개발 초기에는 모든 팀원이 AI 에이전트 클로드 코드(Claude Code)와 커서(Cursor)를 활용해 코드를 썼죠.

이러한 환경에서 사람의 역할은 ‘실행’에서 ’결정’으로 옮겨갔어요. 최동운 님은 “마치 주니어와 일할 때처럼” AI가 만든 결과에 대해 취향과 판단력을 발휘해 좋고 싫음, 맞고 틀림을 정해야 한다고 강조했어요.

문제는 작업량이 늘어나서면서 발생했는데요. 팀원 각자가 AI와 쓴 코드들이 서로 충돌하고, 맥락을 놓친 AI가 “헛소리”를 늘어놓으면서 점점 결과의 품질이 하락하기 시작했다고 해요.

“AI 천국인 줄 알았는데 지옥이었어요. 다시 피그마, 지라(Jira)로 돌아가고 싶은 유혹에 시달렸습니다.”

‘바이브 코더’인 팀원들은 코드를 꼼꼼히 살펴보며 AI에 피드백을 줄 수 없었고, 방대한 코드를 매번 다른 동료나 제미나이, 챗GPT에 물어볼 수도 없는 노릇이었어요. 이때 최동운 님의 머릿속에 불현듯 한 단어가 떠올랐어요. 바로 ‘맥도날드’!

전 세계 어디서든 같은 맛을 내는 맥도날드처럼

맥도날드가 전 세계 매장에서 동일한 품질을 유지하듯, DXT팀에도 ‘일관성’과 ‘예측가능성’이 필요했다고, 최동운 님은 설명했어요. 그러기 위해서는 일의 기준을 명확히 정의하고 동일한 방식으로 실행하게 만드는 시스템과 규칙을 갖춰야 했죠. 최동운 님은 맥도날드의 본사, 지점장, 알바생의 역할을 아래와 같이 정의하고 DXT팀에 내재화했어요.

- 본사(테크 리드): 운영 매뉴얼과 레시피 (워크플로, 콘텍스트, 프롬프트)를 정의. 위생 관리처럼 반드시 지켜야할 항목은 프롬프트 대신 자동화된 스크립트로 관리.

- ‍ 지점장 (프로덕트 빌더): 본사 레시피와 규칙 안에서 각자 직원들에게 작업을 지시하고 관리. 메뉴 또는 레시피에 대한 피드백 본사에 제공.

- 직원 (코딩 에이전트): 표준화된 지시에 따라 성실하게 코드를 짜고 작업을 수행.

먼저, 모든 회의를 녹음하고 녹취록을 노트북LM(Notebook LM)에 저장했어요. 문서화 과정에서 왜곡 가능성을 줄이고 모두와 일관된 콘텍스트를 공유했죠. 가이드와 프롬프트 등은 깃허브(Github)에 업로드해 모두가 확인할 수 있도록 했고요.

콘텍스트를 바탕으로 요구사항을 정의할 때도 AI를 적극 활용했어요. 여러 AI에 사용자, 디자이너, 임원 등 다양한 관점에서 어떻게 생각할지를 질문해 토론 시뮬레이션을 돌려보고 논리적 허점을 발견해 보완하거나 인사이트를 도출했죠. 최종적으로는 사람이 직접 컨펌했고요.

템플릿을 만들어 디자인을 표준화할 때는 아스키 아트와 같은 로우파이 와이어프레임을 그려 AI 코딩 에이전트에 학습시켰어요. 커서, 클로드 코드 등 AI가 생성한 코드는 또 다른 AI인 코드 래빗(CodeRabbit)이 검토해 사람의 부담을 덜어줬고요.

이러한 방식 덕에 DXT팀은 불필요한 의사소통을 줄이고, 일관된 품질 기준을 유지하며 빠르게 합의하고 실행하는 AI 기반 업무 문화를 구축할 수 있었다고 해요.

새로움을 가능케 한 ‘언러닝’

최동운 님은 과거의 경험, 작업 방식을 잊는 ‘언러닝(Unlearning)’이 필요하다고 강조했어요. DXT팀이 시행착오를 감수하며 실험을 이어간 결과, 이전에는 상상할 수 없었던 변화와 성과를 얻을 수 있었던 것처럼요. 최동운 님은 ‘AI가 나보다 더 나을 수 있다’는 생각으로, 막히는 부분이 생긴다면 주저 말고 AI에 물어보는 태도가 중요하다고 전했어요.

”우리가 두려워해야 할 것은 실패가 아니라, 망설이다 기회를 놓치는 것입니다.”

제한적인 조건 안에서 다소 무모하게 보일 수 있었던 DXT 팀의 실험은, AI와 함께 일하는 새로운 업무 방식을 가능하게 만들었어요. DXT팀의 경험은 지금 많은 조직이 고민하고 있는 ‘미래의 일’에 대한 실마리를 보여준다고 볼 수 있어요. 기술 변화를 기민하게 받아들이고 AI를 적극 활용해 새로운 일 문화를 구축해 낸 DXT팀의 이야기가 pxd를 비롯한 여러 회사 또는 팀에 많은 영감을 줄 것이라고 확신해요.

글. 김슬기

편집. 임현경

GEONIQ Integrated Insight Report — 여행·숙박 플랫폼 (Vol.1 숙소 상품 인식 구조 분석)

GEONIQ — Mon, 23 Mar 2026 14:00:38 +0900

본 리포트는 GEO(AIEO)와 SEO를 한 번에 통합 분석해주는 GEONIQ의 진단 기준에 따라 국내 주요 여행·숙박 플랫폼의 페이지 구조와 정보 구성 방식을 분석하고 AI·검색 환경에서 숙소 상품이 어떤 단위로 인식되는지를 관찰·정리한 분석 보고서이다.

좌측부터 우측 방향으로 네이버 여행, 야놀자, 여기어때 메인 페이지 이미지

1) 이번 분석의 관점과 범위

본 분석은 네이버 여행, 야놀자, 여기어때 3개 플랫폼을 대상으로 진행하였다.
각 플랫폼은 다음 3개 유형의 페이지를 기준으로 GEONIQ 진단을 수행하였다.

메인 및 숙소 탐색 페이지
숙소 목록 페이지
숙소 상세 페이지

Vol.1에서는 이 구조를 기준으로 숙소가 AI검색(GEO) 환경에서 어떤 단위로 인식되는지를 중심으로 살펴본다.
선택과 비교, 판단 흐름은 Vol.2에서 다룬다.

2) 숙소 ‘상품’의 정의

여행·숙박 플랫폼에서 숙소는 단순한 장소 정보가 아니라 예약 가능한 단위로 구성된다.

실제 선택이 발생하는 기준은 객실 유형, 일정(체크인·체크아웃), 인원 수가 결합된 상태이다.
즉 하나의 숙소는 단일 상품이 아니라 조건에 따라 분기되는 다수의 상품 집합으로 구성된다.

본 리포트에서는 이 결합 단위를 기준으로 숙소를 ‘상품 단위’로 정의한다.

3) AI검색(GEO) 관점에서의 ‘인식’이란 무엇인가

이 리포트에서 말하는 인식은 사람이 정보를 읽고 이해하는 과정을 의미하지 않는다.

AI검색(GEO) 관점에서의 인식이란 특정 대상이 독립된 단위로 구분되고, 그 속성과 상태가 구조적으로 해석 가능한 상태를 의미한다.
SEO 관점에서는 개별 페이지 단위의 노출이 가능하나, GEO(AIEO) 환경에서는 다음 조건이 함께 충족되어야 한다.

대상이 명확한 단위로 정의되어야 한다
해당 단위의 속성이 구조화되어 있어야 한다
다른 대상과 구분 가능한 형태로 표현되어야 한다

이 조건이 충족되지 않으면 정보는 존재하더라도 인식 가능한 단위로 해석되기 어렵다.

4) 핵심 발견 (Key Findings)

Key Findings 1

숙소 정보는 존재하지만, AI검색(GEO)이 상품 단위로 인식할 수 있도록 구조화되어 있지는 않다.

Product schema가 존재하지 않거나 Hotel·장소 단위 중심으로만 구조화되어 있으며,
객실·일정·인원과 같은 실제 예약 단위가 독립된 상품으로 분리되어 표현되지 않는다.

그 결과 숙소는 개별 정보로는 인식되지만, 예약 가능한 상품 단위로 구분되는 구조는 형성되지 않는다.

Key Findings 2

숙소 간 관계를 통해 비교 대상으로 묶는 구조는 형성되지 않는다.

숙소 목록은 존재하지만 비교를 전제로 한 정렬 기준이나 리스트·표 형태의 구조는 제한적으로 나타나며,
유사 숙소 간 관계나 대체 선택지로 이어지는 연결 또한 구조적으로 명시되지 않는다.

그 결과 개별 숙소 정보는 인식되지만, 상품 간 상대적 위치를 판단하는 비교 맥락은 형성되지 않는다.

Key Findings 3

가격·재고·날짜와 같은 변동 정보의 기준 시점이 구조적으로 명시되지 않는다.

여행·숙박 상품은 시간에 따라 상태가 변화하는 특성을 가진다.
그러나 대부분의 페이지에서 정보의 기준 시점이나 업데이트 흐름이 구조적으로 드러나지 않는다.

그 결과 동일한 정보라도 어떤 시점을 기준으로 한 것인지 판단하기 어려우며,
AI검색(GEO) 환경에서 상태 정보를 안정적으로 해석하기 위한 조건은 형성되지 않는다.

5) 플랫폼별 구조 관찰 요약

네이버 여행

정보 탐색 중심 구조가 강하게 나타난다
콘텐츠 구성은 풍부하지만 상품 단위 구조화는 제한적이다
비교 관계를 드러내는 구조는 확인되지 않는다

야놀자

숙소 목록과 상세 정보는 명확하게 제공된다
개별 페이지 단위 완결성은 높다
그러나 상품 단위 구조화와 비교 구조는 형성되지 않는다

여기어때

성능 및 사용자 경험 측면에서는 안정적인 구조를 보인다
메인과 목록이 통합된 구조로 탐색 흐름은 단순하다
그러나 상품 단위 정의, 비교 구조, 상태 정보 표현은 제한적으로 나타난다

6) 구조 점검 관점에서 정리

이번 분석에서 확인된 것은 특정 플랫폼의 기능적 완성도 문제가 아니다.

여행·숙박 플랫폼 전반에서 공통적으로 나타나는 구조는 다음과 같다.

숙소 정보는 충분히 제공된다
개별 페이지 단위의 완결성은 높다
사용자 탐색 흐름은 잘 설계되어 있다

동시에 다음 조건이 함께 나타난다.

상품 단위 구조가 명확히 정의되지 않는다
숙소 간 관계를 통한 비교 구조가 형성되지 않는다
시간 기반 상태 정보가 구조적으로 드러나지 않는다

이 구조에서 숙소는 선택 가능한 상품이라기보다 정보 단위에 가까운 형태로 표현된다.

지오닉 검증 결과 바로가기
네이버 여행 메인	야놀자 메인	여기어때 메인이자 목록
네이버 여행 목록	야놀자 목록	-
네이버 여행 상세	야놀자 상세	여기어때 상세

pxdAX 관찰 노트

이번 분석에서 확인된 것은 정보의 부족이 아니다.

여행·숙박 플랫폼은 이미 충분한 정보를 제공하고 있으며 사용자는 필요한 내용을 대부분 확인할 수 있다.
그러나 그 정보는 사람의 탐색과 이해를 기준으로 배열되어 있을 뿐 AI검색(GEO) 환경에서 상품 단위로 인식될 수 있도록 구성되어 있지는 않다.
그 결과 숙소는 보이지만 하나의 선택 가능한 단위로 분리되거나 다른 상품과 비교 가능한 관계로 묶이지 않는다.

이 지점에서 하나의 질문이 남는다.

숙소를 ‘정보로 충분히 설명되는 대상’으로 유지할 것인가,
아니면 ‘선택 가능한 상품 단위’로 구조화할 것인가.

GEONIQ 서비스 바로가기

GEONIQ Integrated Insight Report는 GEONIQ, pxd story, xe group tech blog 에서 동시 발행 됩니다.

AI 에이전트의 시대, 우리는 어떤 개발자가 되어야 할까?

doworld — Mon, 16 Mar 2026 07:50:38 +0900

들어가며

개발 생태계의 변화가 무섭습니다.
이제는 단순한 '도구의 진화'를 넘어섰죠.
AI 에이전트가 코드를 짜는 수준을 넘어 직접 PR을 올리고 작업을 수행하는 모습을 보며, 바이브 코딩을 곁들인 대'딸깍'의 시대가 된 것 같아요.

이제 개발자가 고민해야 하는 것은 "어떻게 코드를 짤 것인가"가 아니라 "어떤 문제를 정의하고, AI가 내놓은 답을 어떻게 검증할 것인가"라는 본질적인 질문에 대한 답일거에요.

좁아진 취업문

요즘 시장은 기묘한 양극화를 보이고 있습니다. 하버드 연구에 따르면 AI 도입 이후 주니어 채용은 약 10% 감소한 반면, 시니어 수요는 여전하다고 해요. "가르쳐야 하는 신입보다 AI 에이전트가 가성비 좋다"는 냉혹한 논리가 현장을 지배하기 시작한 것 같아요.

이제는 문턱이 매우 높아졌어요.
이제는 '배우러 온 신입'이 아니라, AI를 동료 삼아 1인분 이상의 생산성을 즉각 증명하는 '실전형 엔지니어'만이 살아남는 시대가 되었습니다.

'코드 작성자'에서 '시스템 지휘자'로

과거에는 알고리즘을 얼마나 효율적으로 구현하느냐가 실력이었습니다.
하지만 개발자의 84%가 AI를 쓰는 지금, 단순 구현 능력은 더 이상 희소 가치가 없습니다.
생산성 또한 이젠 더이상 경쟁력이 아니에요. 더 좋은 품질을 만들어내야 합니다.

오히려 AI가 쏟아내는 수많은 코드 속에서 미묘한 보안 취약점을 찾아내고, 전체 아키텍처의 정합성을 맞추는 판단력이 핵심이 되었습니다.
이제 개발자는 벽돌을 쌓는 조적공보다, 여러 AI 워커들에게 업무를 배분하고 조율하는 '총괄 감독'이나 '오케스트라 지휘자'에 가까워지고 있습니다. 창작의 즐거움이 리스크 관리의 압박으로 바뀔 수도 있겠지만, 이는 우리 역할이 더 가치 있는 전략적 영역으로 이동하고 있다는 신호이기도 합니다.

T자형 인재와 학습의 재정의

이런 환경에서 가장 강력한 생존 모델은 'T자형 인재'입니다.
자신만의 깊은 전문성(Depth)을 하나 갖추되, AI를 활용해 인접 분야까지 유연하게 넘나드는 확장성을 가진 분들이죠.

백엔드 개발자가 AI 도움으로 UI를 뚝딱 만들고, 프론트엔드 개발자가 인프라를 직접 만지는 것이 일상이 되었습니다.
학벌이나 학위는 이제 크게 중요하지 않다고 생각해요. "어디서 배웠나"보다 "무엇을 해결해봤나"가 더 중요한 증명 수단입니다.

마치며

미래가 어떻게 변하든 변하지 않는 본질이 있습니다. 바로 비판적 사고와 도메인에 대한 깊은 이해입니다.
AI는 웹 앱을 눈 깜짝할 새 만들어낼 순 있지만, 그 서비스가 사용자에게 정말 필요한지, 윤리적으로 문제는 없는지 판단하지 못합니다.

실제 문제 해결에 기술을 적용하는 엔지니어에 대한 수요는 항상 존재해왔고 기술을 지속적으로 업데이트하고 역량을 확장하며, 창의성·비판적 사고·협업 같은 인간 고유의 강점에 집중할수록 흐름에서 이탈하지 않을 수 있을거에요.

감사합니다.

이 글은 https://tech.pxd.co.kr/ 에서도 보실 수 있습니다.