코딩하는후운

[철권8] 미아리조 파훼, 딜캐 목록 (시즌2)

코딩하는후운 — Sun, 11 Jan 2026 10:28:01 +0900

미아리조 파훼, 딜캐 목록

안녕하세요 게임하면서 딜캐표도 같이 보려고 적습니다!
상 : 상단
중 : 중단
하 : 하단
숫자 : 상대 기술 막았을 때 딜캐 프레임

** 12딜캐

하 18, -12

** 13딜캐

중중 20, -13

중 18, -13

중중 15, -13

중중 13, -13

중 15, -13

중 17, -13

** 14딜캐

하 20, -14

상중 17, -14

** 15딜캐 이상

하 21, -15

중 19, -17

중중 18, -20

하중 18, -24

하 22, -26

하 18, -26

추가 의견 있으시면 언제든 남겨주세요!

도움이 되셨다면

프린스후운 구독 부탁드려요!!

프린스후운

철권8, 스파6 콤보·운영 꿀팁부터 신캐 공략까지, 격투게임 실력 올리고 싶다면 프린스후운 채널! ️ 앞으로 롤, 오버워치2, 이터널 리턴, 배그 등 다양한 게임 플레이와 꿀팁도 함께 다룹

www.youtube.com

[철권8] 아머킹 파훼, 딜캐 목록 (시즌2)

코딩하는후운 — Sun, 11 Jan 2026 10:18:05 +0900

아머킹 파훼, 딜캐 목록

안녕하세요 게임하면서 딜캐표도 같이 보려고 적습니다!
상 : 상단
중 : 중단
하 : 하단
숫자 : 상대 기술 막았을 때 딜캐 프레임

** 10딜캐

상 11, -10

** 12딜캐

중 22, -12

중 15, -12

상중 12, -12

중 15, -12

상중 11, -12

** 13딜캐

중 15, -13

하 19, -13

중 13, -13

하 17, -13

** 14딜캐

중 30, -14

** 15딜캐 이상

중 13, -19

하 22, -26

추가 의견 있으시면 언제든 남겨주세요!

도움이 되셨다면

Self-Reflection: AI가 스스로 실수를 잡아내는 시스템

코딩하는후운 — Thu, 8 Jan 2026 11:27:28 +0900

Self-Reflection: AI가 스스로 실수를 잡아내는 시스템

Self-Reflection은 AI가 응답할 때마다 자동으로 규칙 위반을 검사하고, 실패하면 스스로 원인을 분석해서 개선하는 자가 진화 시스템입니다.

왜 이게 필요했을까?

문제 1: "왜 자꾸 검색만 해?"

AI에게 "로그인 기능 구현해줘"라고 하면, 바로 코드를 짜면 될 것 같은데...

사용자: "kidsnote_test에 로그인 구현해줘"
AI 내부: "음... 안전하게 Master로 보내서 RAG 검색이나 하자"
결과: 토큰 15,000개 소비, 응답 8초

Worker로 바로 보냈으면 토큰 4,500개, 응답 3초면 끝났을 일이다.

원인을 파헤쳐 보니:

캐시 키에 프롬프트 변경이 반영 안 됨 → 10분간 이전 결과 사용
Worker 선택 기준이 1줄로 너무 모호 → "안전하게 Master" 선택
검증 시스템 없음 → 잘못된 라우팅 감지 불가

문제 2: "규칙 있어도 안 지켜지면 의미 없잖아"

블로그 규칙이 있다:

구분선은 하나만 (---)
표는 3열 이하
TL;DR 금지

근데 AI가 이걸 "잊어버린다". Rule Zero 문서에 적어놔도, 매번 읽지 않으면 소용없다.

AI: "블로그 작성 완료했습니다!"
결과: 구분선 2개 → 티스토리 레이아웃 깨짐
사용자: "...다시 해줘"

근본 원인: 검증 시점이 없다. 사용자가 직접 발견해야 한다.

어떻게 해결했나?

핵심 아이디어: AI가 응답할 때마다 자동으로 검증하게 만들자.

[AI 응답 완료]
      ↓
[Stop Hook 실행]  ← 여기서 Self-Reflection 시작
      ↓
[작업 유형 감지]  blog? code? jira?
      ↓
[규칙 검증]       구분선 개수, 표 열 수, TODO 금지...
      ↓
[위반 시 경고]    "❌ 구분선 2개 사용함!"

두 가지 선택지가 있었다:

LLM으로 검증 → 토큰 비용 발생, 느림
정규식/파일 체크 → 비용 0, 빠름 ✅

토큰 효율이 핵심이니까 2번을 선택했다. Lambda 함수로 규칙을 정의하면 끝:

BLOG_CHECKLIST = [
    {
        "id": "blog_separator_count",
        "description": "구분선은 하나만 사용",
        "validator": lambda content: content.count("\\n---\\n") <= 1,
    }
]

실제 흐름: AI가 블로그를 쓰면 어떻게 되나?

사용자: "MasterAgent 블로그 써줘"
          │
          ▼
    ┌─────────────┐
    │ BrainAgent  │  ← "Worker로 보내야겠다"
    └─────────────┘
          │
          ▼
    ┌─────────────┐
    │ AI 응답     │  ← 블로그 작성 완료
    └─────────────┘
          │
          ▼
    ┌─────────────┐
    │ Stop Hook   │  ← Self-Reflection 시작!
    └─────────────┘
          │
    ┌─────┴─────┐
    ▼           ▼
[작업 감지]  [신뢰도 확인]
"blog다"     "0.87이면 OK"
    │
    ▼
[블로그 규칙 검증]
- 구분선: 1개 ✅
- 표: 3열 ✅
- TL;DR: 없음 ✅
    │
    ▼
[통과] → 아무 일도 안 일어남 (토큰 0)

만약 위반했다면?

[블로그 규칙 검증]
- 구분선: 2개 ❌
    │
    ▼
[경고 출력]
❌ BLOG_RULE_VIOLATION: 구분선은 하나만 사용 (현재: 2개)
   See: common/guidelines/blog/README.md
    │
    ▼
[SYSTEM_INDEX 검증 트리거]
  Checking SYSTEM_INDEX.md consistency...

핵심: 문제 없으면 Skip, 문제 있을 때만 심층 검증. 이게 조건부 검증이다.

한 단계 더: 자가 고도화

검증만으로는 부족했다. 같은 실수를 반복하지 않게 만들고 싶었다.

[1주일 동안 실패 누적]
    │
    ▼
[매주 월요일, SessionEnd Hook]
"지난 7일간 실패 패턴 분석해볼까?"
    │
    ▼
[Gemini로 패턴 추출]
- 패턴 1: 로그 파일 확인 안 하고 버그 분석 (빈도: HIGH)
- 패턴 2: Jira 토큰 확인 안 함 (빈도: MEDIUM)
    │
    ▼
[리포트 생성]
knowledge_base/reports/failure_analysis_20260113.md
    │
    ▼
[MetaLearner 실행]
"brain_agent.py 프롬프트에 이거 추가할까요?"
    │
    ▼
[사용자 승인]
y
    │
    ▼
[다음 세션부터 자동 적용]

결과:

# Before (실패)
사용자: "앱이 크래시 나는데 원인 찾아줘"
AI: "코드를 분석해보면..." (로그 확인 안 함)

# After (성공)
사용자: "앱이 크래시 나는데 원인 찾아줘"
AI: "먼저 로그 파일을 확인합니다.
     $ ls -la logs/
     $ tail -100 logs/error.log
     에러 메시지: NullPointerException at line 42
     원인: ..."

실패 → 분석 → 개선 → 다음 성공. 이 사이클이 자동화된 것이다.

또 한 단계: 코드-문서 자동 동기화

라우팅 개선

지표 Before After

Worker 선택률	20%	80%
평균 토큰	15,000	4,500
응답 시간	8초	3초

규칙 준수

지표 Before After

블로그 위반율	30%	0%
코드 TODO 잔존	15%	0%
추가 토큰 비용	-	0

추가 토큰 비용이 0인 이유:

정규식/파일 체크만 사용 (LLM 호출 없음)
문제 없으면 SYSTEM_INDEX 안 읽음 (조건부 검증)
10일 측정 결과, 평균 추가 토큰 0

효과: 숫자로 보는 변화

컴포넌트 역할 트리거

ChecklistValidator	블로그/코드 규칙 검증	매 응답
RoutingValidator	신뢰도 0.75 이상 검증	매 응답
SystemIndexValidator	Hook 동기화 등 검증	위반 시에만
FailureAnalyzer	실패 패턴 추출	매주 월요일
MetaLearner	프롬프트 자동 개선	사용자 승인

Self-Reflection의 철학은 단순하다:

"AI도 실수한다. 중요한 건 같은 실수를 반복하지 않는 것."

이제 우리는:

블로그 규칙 위반을 사용자가 발견하기 전에 자동으로 잡아낼 수 있다
정규식/파일 체크만 사용 (LLM 호출 없음)
문제 없으면 SYSTEM_INDEX 안 읽음 (조건부 검증)

더 이상 "규칙 있어도 안 지켜지면 의미 없잖아"라고 할 필요가 없다. AI가 알아서 지킨다.

정리하면

컴포넌트 역할 트리거

ChecklistValidator	블로그/코드 규칙 검증	매 응답
RoutingValidator	신뢰도 0.75 이상 검증	매 응답
DocSyncChecker	코드-문서 동기화 경고	코드 수정 시
FailureAnalyzer	실패 패턴 추출	매주 월요일
MetaLearner	프롬프트 자동 개선	사용자 승인

Self-Reflection의 철학은 단순하다:

"AI도 실수한다. 중요한 건 같은 실수를 반복하지 않는 것."

이제 우리는:

블로그 규칙 위반을 사용자가 발견하기 전에 자동으로 잡아낼 수 있다
토큰 비용을 70% 절감하면서도 더 정확한 라우팅을 할 수 있다
AI가 실패하면 스스로 원인을 분석하고 다음엔 같은 실수를 안 하게 만들 수 있다
코드 수정하면 관련 문서 업데이트가 자동으로 리마인드된다

더 이상 "규칙 있어도 안 지켜지면 의미 없잖아"라고 할 필요가 없다. AI가 알아서 지킨다.

MasterAgent: AI가 파이프라인을 실행하는 방법

코딩하는후운 — Thu, 8 Jan 2026 10:08:49 +0900

MasterAgent: "판단은 끝났어, 이제 실행만 해"

BrainAgent가 "어떤 파이프라인을 쓸지" 결정했다면, MasterAgent는 그걸 실제로 실행하는 역할이다. 판단? 안 한다. 그냥 시킨 대로 한다.

왜 실행만 하는 컴포넌트를 따로 뒀을까?

처음에는 하나의 Agent가 모든 걸 했다. 질문 분석도 하고, 파이프라인 실행도 하고, 답변도 생성하고.

근데 문제가 생겼다.

"PK-123 관련 과거 논의 찾아줘" 같은 질문이 들어오면:

Jira에서 티켓 정보 가져와야 하고
RAG에서 과거 대화 검색해야 하고
두 결과를 조합해서 답변해야 한다

이걸 하나의 Agent가 순차적으로 하니까 느리고, 중간에 "어떤 거 먼저 하지?" 판단이 계속 필요했다.

그래서 역할을 나눴다:

BrainAgent: 뭘 할지 결정 (빠른 판단)
MasterAgent: 결정된 거 실행 (병렬 처리)
CLI: 결과 받아서 최종 답변 (리랭킹)

실행 흐름: 질문이 들어오면 어떻게 되나?

사용자: "PK-123 관련 과거 논의 찾아줘"
          │
          ▼
    ┌─────────────┐
    │ BrainAgent  │  ← "jira + rag 파이프라인 필요하겠다"
    └─────────────┘
          │
          │ pipelines: ["jira", "rag"]
          ▼
    ┌─────────────┐
    │ MasterAgent │  ← "알겠어, 병렬로 돌릴게"
    └─────────────┘
          │
    ┌─────┴─────┐
    ▼           ▼
 [Jira API] [RAG 검색]   ← 동시에 실행 (ThreadPool)
    │           │
    └─────┬─────┘
          ▼
    ┌─────────────┐
    │    CLI      │  ← 결과 받아서 리랭킹 + 답변 생성
    └─────────────┘

핵심은 MasterAgent가 판단하지 않는다는 것이다. BrainAgent가 "jira, rag 써"라고 하면 그냥 둘 다 실행한다. "jira 먼저 할까 rag 먼저 할까?" 고민 안 한다. 그냥 동시에 돌린다.

Worker는 또 뭔데?

파이프라인 말고 Worker라는 개념도 있다. "기획 관점에서 분석해줘" 같은 요청이 들어오면:

BrainAgent: "PM 관점이 필요하네" → workers: ["pm"]
                │
                ▼
         ┌─────────────┐
         │ MasterAgent │
         └─────────────┘
                │
                ▼
         ┌─────────────┐
         │  PM Worker  │ → 자동으로 jira, notion, rag 실행
         └─────────────┘

Worker는 전문가 페르소나다. PM, Dev, QA, Design 각각 자기 분야에 맞는 파이프라인을 기본으로 가지고 있다.

Worker 기본 파이프라인 관점

PM	jira, notion, rag	기획, 요구사항
Dev	rag, jira	기술, 구현
QA	jira, rag, notion	테스트, 품질
Design	figma, notion, jira	UI/UX

중요한 건 Worker도 LLM을 호출하지 않는다는 것이다. Worker는 그냥 "나는 PM이고, 이 파이프라인들 결과야"라는 컨텍스트만 제공한다. 최종 통합은 CLI가 한다.

왜 LLM 호출을 안 할까?

이게 핵심 설계 철학이다.

처음에는 Worker마다 LLM을 호출해서 각자 분석하게 했다. PM Agent가 분석하고, Dev Agent가 분석하고, 마지막에 Master가 통합하고...

토큰 비용이 미쳤다.

생각해봐:

PM 분석: 1000 토큰
Dev 분석: 1000 토큰
QA 분석: 1000 토큰
통합: 2000 토큰
총 5000 토큰 (Worker 3개 케이스)

지금은?

파이프라인 실행: 0 토큰 (API 호출일 뿐)
Worker 컨텍스트: 0 토큰 (문자열 조합일 뿐)
CLI 최종 답변: 1500 토큰 (한 번만 호출)
총 1500 토큰

70% 토큰 절감. 이게 MasterAgent가 "컨텍스트 수집만 하고 판단 안 하는" 이유다.

결과는 어떻게 전달되나?

MasterAgent는 실행 결과를 태그로 감싸서 반환한다:

파이프라인 실행 결과:

<context>
  <rag>과거 대화 3건 검색됨...</rag>
  <jira>PK-123: 로그인 기능 구현...</jira>
</context>

Worker 실행 결과:

<worker-contexts>
  <worker role="pm">
    <persona>PM 관점에서 분석...</persona>
    <pipelines>jira, notion 결과...</pipelines>
  </worker>
</worker-contexts>

CLI(Claude/Gemini)는 이 태그를 받아서:

결과 리랭킹 (중요도 정렬)
통합 (중복 제거, 요약)
최종 답변 생성

정리하면

컴포넌트 역할 LLM 호출

BrainAgent	뭘 할지 결정	Flash (가벼운 모델)
MasterAgent	결정된 거 실행	없음
Worker	페르소나 + 파이프라인	없음
CLI	리랭킹 + 최종 답변	Opus/Sonnet

MasterAgent의 철학은 단순하다: "판단은 BrainAgent가 했어. 난 그냥 빠르게 실행만 할게."

이 분리 덕분에:

파이프라인 병렬 실행으로 속도 향상
LLM 호출 최소화로 비용 절감
각 컴포넌트가 한 가지만 해서 유지보수 용이

BrainAgent(라우터): AI가 0.01초 만에 질문을 분석하는 교통경찰

코딩하는후운 — Thu, 8 Jan 2026 09:38:46 +0900

BrainAgent: AI가 0.01초 만에 질문을 분석하는 교통경찰

BrainAgent는 질문이 들어오면 "검색이 필요한가? Jira를 봐야 하나? 바로 답해도 되나?"를 0.01초 만에 판단하는 AI 라우터입니다.

문제 상황

AI에게 "안녕"이라고 인사했는데 무거운 검색 엔진이 돌아가면 시간 낭비입니다. 반대로 "지난주 뭐 했지?"라고 물었는데 검색 없이 "모르겠어요"라고 하면 답답하죠.

더 큰 문제:

단순 인사에도 LLM 호출 → 비용 낭비
복잡한 질문인데 도구 선택 못 함 → 엉뚱한 답변
어떤 파이프라인을 써야 할지 매번 수동 지시 → 불편

해결책: BrainAgent

BrainAgent = 질문 분석 + 경로 결정 (판단만, 실행 안 함)

질문이 들어오면 BrainAgent가 먼저 분석하고, 어디로 보낼지 결정합니다. 실행은 MasterAgent가 담당합니다.

동작 방식: 2단계 라우팅

1단계: 규칙 기반 (80%)

패턴 매칭으로 LLM 호출 없이 즉시 결정합니다.

┌─ 규칙 기반 라우팅 ──────────────────────┐
│                                     │
│  질문: "PK-1234 봐줘"                 │
│           ↓                         │
│  [패턴 매칭] "PK-숫자" 감지             │
│           ↓                         │
│  결과: jira 파이프라인                  │
│                                     │
│  비용: $0, 시간: 10ms 미만             │
│                                     │
└─────────────────────────────────────┘

패턴 결정

"안녕", "ㅎㅎ"	direct (바로 응답)
"PK-123 봐줘"	jira 파이프라인
"@planning 읽어"	notion 파이프라인

2단계: LLM 기반 (20%)

규칙으로 판단 어려우면 Gemini Flash를 호출합니다.

┌─ LLM 기반 라우팅 ───────────────────┐
│                                  │
│  질문: "지난주 작업 중 코드 관련된 것"   │
│           ↓                      │
│  [Gemini Flash 호출]              │
│           ↓                      │
│  결과: rag + jira 파이프라인         │
│                                  │
│  비용: Flash 1회, 시간: ~500ms      │
│                                  │
└──────────────────────────────────┘

5가지 exec_type

BrainAgent가 결정하는 실행 타입입니다.

exec_type 언제? 예시

direct	일반 대화	"안녕", "고마워"
tool	명시적 명령	"jira get PK-123"
master	검색 필요	"저번에 뭐했지?"
worker	전문가 필요	"로그인 기획해줘"
speckit	기획→구현	"speckit 시작"

실제 출력 예시

  [08:14·670db96] | claude/opus | work |  rag

┌─ 라우팅 분석 ────────────────────┐
│ 실행 타입  : master             │
│ 파이프라인 : rag                 │
│ 신뢰도     : 92%                │
│ 이유       : 과거 대화 검색 필요    │
└───────────────────────────────┘

핵심 포인트

80% 질문은 규칙으로 즉시 라우팅 (비용 $0)
BrainAgent는 판단만, MasterAgent가 실행
신뢰도 낮으면 사용자에게 재질문

"이거 Jira에서 찾아", "RAG로 검색해" 안 해도 됩니다. BrainAgent가 알아서 판단합니다.

Hook: AI가 알아서 다 해주는 마법의 비밀

코딩하는후운 — Wed, 7 Jan 2026 10:32:53 +0900

Hook 시스템: AI가 모든 대화를 자동으로 기억하는 비밀

Hook은 질문하면 자동 검색, 답변하면 자동 저장, 종료하면 자동 요약하는 Claude Code 이벤트 시스템입니다.

Hook이 뭔가요?

Hook은 LLM 이벤트에 자동 반응하는 쉘 스크립트입니다.

쉽게 말해:

사용자가 질문하면 → Hook이 먼저 실행됨
AI가 답변하면 → Hook이 자동 저장함
세션 끝나면 → Hook이 요약함

사용자는 아무것도 안 해도 됩니다. 전부 자동입니다.

┌─────────────────────────────────────────────┐
│  사용자 질문 입력                               │
│       ↓                                     │
│  [UserPromptSubmit Hook] ← 라우팅 + 파이프라인  │
│       ↓                                     │
│  Claude/Gemini 응답 생성                      │
│       ↓                                     │
│  [Stop Hook]             ← 저장 + 검증 + 고도화 │
│       ↓                                     │
│  세션 종료 (exit)                             │
│       ↓                                     │
│  [SessionEnd Hook]       ← 세션 요약          │
└─────────────────────────────────────────────┘

3가지 Hook

Hook 트리거 역할

UserPromptSubmit	질문 입력	라우팅 + 파이프라인
Stop	응답 완료	저장 + 검증 + 고도화
SessionEnd	세션 종료	전체 대화 요약

1️⃣ UserPromptSubmit Hook

사용자가 질문을 입력하는 순간 실행됩니다.

실행 흐름

[1] 사용자 질문 받음
       ↓
[2] BrainAgent가 분석 (라우팅 결정)
       ├─ 규칙 기반 (80%) → $0, <10ms
       └─ LLM 기반 (20%) → Flash 호출
       ↓
[3] 파이프라인 실행 (RAG, Jira, Notion 등)
       ↓
[4] 결과를 Claude에게 전달
       ↓
[5] Claude가 답변 생성

라우팅 방식

규칙 기반 (80%): 키워드 매칭, 비용 $0, 10ms 이내

"Jira" → jira 파이프라인
"노션" → notion 파이프라인
"코드 분석" → rag 파이프라인

LLM 기반 (20%): Gemini Flash 호출, 복잡한 의도 분석

"지난주 했던 작업 알려줘" → 맥락 분석 필요

exec_type 5가지

exec_type 설명 파이프라인

direct	Claude 자체 지식	없음
tool	단일 도구 실행	단일
master	Master가 직접 처리	복수 가능
worker	Worker 병렬 실행	Worker별 할당
speckit	기획→구현 자동화	전체

Status Line (상태 표시줄)

Hook 실행 결과를 한 줄로 요약해서 보여줍니다.

  [08:14·670db96] | claude/opus | work |  rag

각 부분의 의미

요소 설명 예시

시간·세션ID	현재 시각 + 세션 ID	08:14·670db96
LLM/모델	사용 중인 LLM	claude/opus
경로	작업 디렉토리	work
exec_type	실행 타입	rag

아이콘 의미

	direct (자체 지식)
	rag (지식 검색)
	graph (관계 분석)
	jira (이슈 조회)
	notion (문서 조회)
	figma (디자인 분석)

이 한 줄만 봐도 지금 AI가 뭘 하고 있는지 알 수 있습니다.

실행 로그

더 자세한 정보가 필요하면 실행 로그를 봅니다.

┌─ 라우팅 분석 ─────────────────────┐
│ 실행 타입  : master              │
│ 파이프라인 : rag                  │
│ 신뢰도     : 90%                 │
│ 이유       : 지식베이스 검색 필요    │
└────────────────────────────────┘

신뢰도: BrainAgent가 얼마나 확신하는지 (0~100%)
이유: 왜 이 경로를 선택했는지

2️⃣ Stop Hook

AI가 답변을 완료할 때마다 실행됩니다. 단순 저장만 하는 게 아니라, 자가 검증과 자가 고도화까지 자동으로 수행합니다.

하는 일 3가지

[1] 대화 저장
    transcript → chat_logs 테이블

[2] 자가 검증
    ├─ 라우팅 신뢰도 체크 (0.75 미만이면 경고)
    └─ 작업별 규칙 검증 (블로그/코드)

[3] 자가 고도화 (에러 감지 시)
    Tool Error/Traceback 발견 → 즉시 분석

1. 대화 저장

메시지 최대 10,000자 (초과 시 truncate)
user, assistant 둘 다 있을 때만 저장

2. 자가 검증

매 응답마다 AI가 스스로 검증합니다.

라우팅 검증:

BrainAgent 신뢰도가 0.75 미만이면 경고
"라우팅이 불확실합니다" 알림

작업별 규칙 검증:

블로그: 구분선 1개, 표 3열, TL;DR 금지
코드: TODO/pass 금지, rm -rf/DROP 금지

위반 발견 시 즉시 경고 메시지가 표시됩니다.

3. 자가 고도화

Tool Error, Traceback, HTTP 4xx/5xx 에러가 발생하면 즉시 자동 분석합니다.

Tool Error 감지!
       ↓
failure_analyzer 실행 (패턴 분석)
       ↓
개선 제안 생성 (승인 후 적용)

더 이상 8일을 기다릴 필요 없습니다. 실패 발생 즉시 분석합니다.

저장 제한

메시지 최대 10,000자 (초과 시 truncate)
user, assistant 둘 다 있을 때만 저장

3️⃣ SessionEnd Hook

세션이 정상 종료될 때 실행됩니다.

실행 조건

reason = "exit" 일 때만 실행
clear, logout 등은 스킵

하는 일

[1] 해당 세션의 모든 chat_logs 조회
       ↓
[2] Gemini Flash로 전체 대화 요약 생성
       ↓
[3] session_summary 테이블에 저장

Two-Tier 검색 전략

사용자: "지난주 뭐 했지?"
       ↓
[Tier 1] session_summary 검색 (요약본)
       → "지난주 GameLoungeK UI 작업, Jira PK-123 해결"
       ↓
[Tier 2] 필요시 chat_logs 상세 조회 (원본)
       → 전체 대화 내용

데이터 보존 정책

데이터 보존 기간

chat_logs (원본)	30일
session_summary (요약)	30일

30일 후: chat_logs 삭제, session_summary만 유지

→ "3개월 전에 뭐 했지?" 도 요약본으로 검색 가능

파일 위치

Claude Code:

.claude/hooks/user-prompt-hook.sh
.claude/hooks/save-conversation.sh
.claude/hooks/session-end.sh

Gemini CLI:

~/.gemini/hooks/ (동일 구조)

원본 (Git 관리):

knowledge_base/providers/claude/hooks/*.sh
knowledge_base/providers/gemini/hooks/*.sh

핵심 포인트

완전 자동: 사용자가 신경 쓸 거 없음
비용 효율: 라우팅 80%는 $0
데이터 보존: 30일 후 요약만 유지
자가 검증: 규칙 위반 즉시 감지
자가 고도화: 실패 즉시 분석

사용자는 질문만 하면 됩니다. 나머지는 Hook이 알아서 합니다.

상세 기술 문서: knowledge_pillars/04-hook.md

Setup 시스템: 새 컴퓨터에서 5분 안에 AI 환경 완성하기

코딩하는후운 — Wed, 7 Jan 2026 10:26:52 +0900

Setup: AI 에이전트 환경을 5분 만에 완성하는 7단계 설정법

/setup 한 번이면 API 키, DB 연결, Hook 파일까지 모두 자동 설정됩니다. 3-Tier 아키텍처로 비밀 정보도 안전하게 분리됩니다.

해당 Setup은 제가 컴퓨터나 다른 사람에게 저의 시스템을 빠르게 설정 시켜주기 위한 설정입니다.(참고)

문제 상황

새 프로젝트 시작할 때마다 이런 경험 있으신가요?

"API 키 어디다 넣지?", "환경 변수 설정 또 해야 하나?", "DB 연결은 어떻게 하더라?"

매번 검색하고, 복붙하고, 에러 나면 또 찾아보고... 설정에만 30분-1시간이 날아갑니다.

더 심각한 문제:

API 키를 코드에 넣었다가 Git에 푸시 → 보안 사고
팀원마다 설정이 달라서 "내 컴퓨터에선 되는데?"
설정 파일이 여기저기 흩어져서 관리 불가

해결책: /setup 명령어

"한 번의 명령어로 모든 설정을 자동화"합니다.

PYTHONPATH=/Users/days/Desktop/work \\
  ./knowledge_base/venv/bin/python3 -m knowledge_base.cli setup

이 명령어 하나면:

✅ Python 가상환경 생성
✅ Docker 컨테이너 확인
✅ 파일 동기화
✅ API 키 설정 안내
✅ 사용자 설정 입력
✅ MCP 서버 연결

5분이면 끝납니다.

동작 방식: 3-Tier 보안 아키텍처

설정을 3계층으로 분리해서 보안과 편의성을 동시에 잡습니다.

┌─────────────────────────────────────┐
│ Tier 1: 비밀 정보 (~/.zshenv)         │
│ → API 키, 토큰 (Git과 완전 분리)        │
├─────────────────────────────────────┤
│ Tier 2: 사용자 설정 (user_settings.py) │
│ → 개인 정보, 경로 (.gitignore 등록)      │
├─────────────────────────────────────┤
│ Tier 3: 설정 허브 (config.py)         │
│ → 단일 진입점 (Single Source of Truth) │
└─────────────────────────────────────┘

왜 3계층인가?

Tier 보안 Git 예시

1	최고	❌ 제외	API 키, 토큰
2	중간	❌ 제외	이메일, 경로
3	공개	✅ 포함	DB 설정, 포트

핵심: 비밀 정보는 Git에 절대 올라가지 않습니다.

7단계 설정 프로세스

단계 동작 소요 시간

1	Python venv 생성	~30초
2	Docker 컨테이너 확인	~5초
3	파일 동기화	~5초
4	API 키 설정 확인	~10초
5	사용자 정보 입력	~30초
6	user_settings.py 저장	~1초
7	.mcp.json 생성	~1초

실제 실행 예시

1단계: Python 환경

  Python 환경 설정 중...
✅ knowledge_base/venv 생성됨 (Python 3.10+)
✅ requirements.txt 설치 완료

2단계: Docker 확인

  Docker 컨테이너 상태 확인...
✅ Milvus: Running (localhost:19530)
✅ Neo4j: Running (localhost:7687)

3단계: 파일 동기화

  Claude Code 설정 파일...
  ❓ CLAUDE.md 이미 존재합니다. 덮어쓸까요? (y/n): n
  ✅ .claude/hooks/*.sh 복사됨 (항상 덮어쓰기)

4단계: API 키 확인

  API 키 설정 상태...
✅ ANTHROPIC_API_KEY: 설정됨
✅ GOOGLE_API_KEY: 설정됨
❌ JIRA_TOKEN: 설정 안 됨 → ~/.zshenv에 추가 필요

7단계: 완료

  모든 설정이 완료되었습니다!
  Notion 별명 설정: services/notion/page_map.json 직접 편집
  변경사항 적용: 에이전트 재시작

핵심 장점

1. Claude + Gemini 동시 지원

이전에는 LLM을 선택해야 했지만, 이제는 둘 다 자동 설정됩니다.

work/
├── CLAUDE.md      # Claude Code 규칙
├── GEMINI.md      # Gemini CLI 규칙
├── .claude/       # Claude 설정
│   ├── hooks/     # Hook 스크립트
│   └── commands/  # 커스텀 명령어
└── .gemini/       # Gemini 설정
    ├── hooks/
    └── commands/

2. 기존 설정 보호

❓ CLAUDE.md 이미 존재합니다. 덮어쓸까요? (y/n): n
ℹ️ CLAUDE.md 유지
✅ .claude/hooks/*.sh 복사됨 (항상 덮어쓰기)

파일 유형 정책 이유

CLAUDE.md / GEMINI.md	y/n 질문	사용자 커스텀 보존
Hook 파일	항상 덮어쓰기	시스템 필수 파일
Commands	항상 덮어쓰기	템플릿

→ 파일별로 선택할 수 있어서 기존 커스텀 설정이 날아가지 않습니다!

3. API 키 나중에 설정 가능

  API 키 설정 상태...
❌ JIRA_TOKEN: 설정 안 됨

→ Enter로 패스하고 나중에 ~/.zshenv 직접 편집해도 됩니다.

기술 상세

Tier 1: ~/.zshenv (Git 외부)

# API Keys (절대 Git에 넣지 마세요!)
export ANTHROPIC_API_KEY="sk-ant-..."
export GOOGLE_API_KEY="AIza..."
export JIRA_TOKEN="..."
export NOTION_TOKEN="secret_..."

Tier 2: user_settings.py (상세 항목)

# 사용자 정보 (Git 제외)
USER_EMAIL = "gihyun@example.com"      # Jira 담당자 이메일
WORK_ROOT = "/Users/days/Desktop/work"  # 작업 루트 경로

# DB 설정
KNOWLEDGE_DB_NAME = "agent_brain.db"    # SQLite 파일명

# 모델 설정
GEMINI_MODEL_FLASH = "gemini-2.0-flash" # 빠른 작업용
GEMINI_MODEL_PRO = "gemini-2.5-pro"     # 복잡한 작업용
DEFAULT_MODEL_TIER = "flash"            # 기본 티어

# Vector DB 접속 정보
MILVUS_HOST = "localhost"
MILVUS_PORT = 19530

Tier 3: config.py (진입점)

# 모든 설정을 여기서 import
ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")  # Tier 1
USER_EMAIL = getattr(user_settings, "USER_EMAIL", "")  # Tier 2
MILVUS_HOST = "localhost"  # Tier 3 (하드코딩)

DB 연결 정보

DB 용도 포트

SQLite	대화 기록, 요약	파일
Milvus	벡터 검색	19530
Neo4j	그래프 관계	7687

실제 사용

# Clone 후 Setup 실행 (이게 전부!)
git clone <repo-url> work && cd work
PYTHONPATH=$(pwd) ./knowledge_base/venv/bin/python3 -m knowledge_base.cli setup

5분 후 바로 사용 가능:

# Claude Code 시작
claude

# 또는 Gemini CLI
gemini

결론

Setup 덕분에:

✅ 5분 만에 전체 환경 구성 (7단계 자동화)
✅ 3-Tier 구조로 API 키 보안 (Git 사고 방지)
✅ 팀원 누구나 동일한 환경 (재현 가능)

/setup 한 번이면 AI 에이전트 개발 준비 완료입니다.

AI Agent, 왜 지금 배워야 할까?

코딩하는후운 — Wed, 7 Jan 2026 10:12:37 +0900

AI Agent: 2026년 개발자 생산성을 5배 높이는 새로운 패러다임

AI Agent = LLM + Tools + Memory + Planning. 단순 챗봇과 달리 외부 시스템과 연동하고, 과거를 기억하며, 복잡한 작업을 스스로 계획합니다.

문제 상황

"Jira 티켓 만들고, Notion에 정리하고, GitHub PR 올리고..."

하루에 몇 번이나 이런 반복 작업을 하시나요?

ChatGPT에게 질문하면 답은 잘 해주는데, 실제로 뭔가 해주진 않습니다. 복사해서 붙여넣고, 다시 질문하고, 또 복사하고... 결국 사람이 다 해야 합니다.

더 큰 문제:

"어제 뭐 물어봤더라?" → 대화 기록 찾기
"이 코드 왜 이렇게 짰지?" → 맥락 없이 다시 설명
"Jira에 이거 반영해줘" → "죄송합니다, 외부 시스템 접근이 불가능합니다"

해결책: AI Agent란?

"스스로 생각하고, 도구를 사용하고, 기억하는 AI"입니다.

AI Agent = LLM(두뇌) + Tools(도구) + Memory(기억) + Planning(계획)

구성 요소 역할 예시

LLM	상황 판단, 의사결정	Claude, GPT, Gemini
Tools	외부 시스템 연동	Jira, Notion, GitHub, Figma
Memory	과거 대화/지식 저장	RAG, Vector DB
Planning	복잡한 작업 분해	멀티스텝 실행

단순 챗봇 vs AI Agent

구분 챗봇 AI Agent

외부 시스템	❌ 접근 불가	✅ Jira, Notion, GitHub 연동
기억력	❌ 대화마다 리셋	✅ 과거 대화 검색 (30일+)
실행력	❌ 답변만	✅ 직접 파일 수정, 티켓 생성
복잡한 작업	❌ 한 번에 하나	✅ 멀티스텝 자동 실행

동작 방식: 우리의 Knowledge Base 시스템

왜 직접 만들었나?

맞춤형 워크플로우: 우리 팀의 Jira, Notion, Figma에 최적화
비용 효율: 80%는 규칙 기반 (LLM 호출 $0)
완전한 통제: 데이터 흐름, 프롬프트 모두 커스터마이징

핵심 아키텍처

┌─ Knowledge Base 시스템 ──────────────────────┐
│                                            │
│  [Hook] → 사용자 질문 자동 감지                 │
│     ↓                                      │
│  [BrainAgent] → 라우팅 결정(80% 규칙, 20% LLM) │
│     ↓                                      │
│  [Pipelines]                               │
│     ├─ RAG: 지식 검색 (Milvus + SQLite)      │
│     ├─ Jira: 이슈 조회/생성                   │
│     ├─ Notion: 문서 읽기/쓰기                 │
│     ├─ Graph: 파일 관계 분석 (Neo4j)          │
│     └─ Figma: 디자인 분석                     │
│     ↓                                      │
│  [Workers] → 전문가 에이전트 협업               │
│     ├─ PM: 기획, Jira 관리                   │
│     ├─ Dev: 코드 분석, 구현                   │
│     ├─ QA: 테스트, 버그 리포트                 │
│     └─ Design: UI/UX, Figma 연동            │
│                                            │
└────────────────────────────────────────────┘

실제 사용 예시

질문: "지난주에 PK-1234 어떻게 처리했지?"

  [09:14·a3b2c1d] | claude/opus | work |  rag

┌─ 라우팅 분석 ─────────────────────────┐
│ 실행 타입  : master                   │
│ 파이프라인 : rag, jira                │
│ 신뢰도     : 92%                     │
│ 이유       : 과거 대화 + Jira 조회      │
└─────────────────────────────────────┘

→ 자동으로 과거 대화에서 검색 + Jira에서 티켓 조회 후 답변

기술 상세: 핵심 원칙 3가지

1. 토큰 효율성 (비용 80% 절감)

┌─ 라우팅 전략 ─────────────────────────────────────────┐
│                                                    │
│  80% 규칙 기반 (비용 $0, <10ms)                        │
│    ├─ "안녕" → direct (검색 불필요)                    │
│    ├─ "PK-1234" → jira (패턴 매칭)                   │
│    └─ "@planning" → notion (별명 감지)               │
│                                                    │
│  20% LLM 기반 (복잡한 판단)                            │
│    └─ "지난번 그거 어떻게 했더라?" → rag                 │
│                                                    │
└────────────────────────────────────────────────────┘

2. Two-Tier 메모리 (30일 + 영구)

Tier 보관 내용

원본	30일	전체 대화 기록
요약	영구	세션별 요약본

→ "3개월 전에 뭐했지?" 도 검색 가능

3. Single Source of Truth

정보는 파일에 → DB는 검색용만

CLAUDE.md, GEMINI.md에 규칙 정의
Hook, Pipeline 코드가 실제 동작
DB는 인덱스 역할만

시작하기: 학습 로드맵

단계 주제 기간 핵심

Step 1	LLM API 기초	1주	프롬프트, 토큰, 비용
Step 2	Tool 연동	2주	Function Calling, 외부 API
Step 3	RAG 구축	2주	Vector DB, Embedding
Step 4	Agent 아키텍처	2주	ReAct, Multi-Agent, MCP

결론

AI Agent는 더 이상 미래 기술이 아닙니다:

✅ 도구 사용: Jira, Notion, GitHub 직접 연동
✅ 기억력: 30일 원본 + 영구 요약으로 맥락 유지
✅ 비용 효율: 80% 규칙 기반으로 토큰 절감

"AI를 사용하는 사람과 사용하지 않는 사람의 생산성 차이는 점점 벌어질 것이다."

다음 글: Setup - 5분 만에 AI 에이전트 환경 구축하기

AI 코드 에디터, Cursor란?

코딩하는후운 — Mon, 25 Aug 2025 09:57:12 +0900

Cursor는 기존의 VS Code를 기반으로, AI 기능을 매우 강력하게 통합한 코드 에디터입니다.

안드로이드 개발에 사용하면 다음과 같은 장점들이 있습니다.

지능적인 코드 생성 및 수정: 간단한 명령만으로 클래스, 함수, UI 레이아웃 등 복잡한 코드를 생성하거나 기존 코드를 리팩토링할 수 있습니다.
프로젝트 전체 컨텍스트 이해: 내 프로젝트의 다른 파일이나 폴더 구조를 AI가 이해하고, 그에 맞는 코드를 추천하고 작성해 줍니다.
에러 해결 및 디버깅 지원: 발생한 에러 메시지를 붙여넣고 해결 방법을 물어보면, 프로젝트 상황에 맞는 해결책을 제시해 줍니다.
문서 검색: 웹 브라우저를 열지 않고도 에디터 내에서 공식 문서나 라이브러리 문서를 찾아 코드에 바로 적용할 수 있습니다.

Cursor로 안드로이드 개발 시작하기

1. 필수 환경 설정 (가장 중요!)

Cursor는 '코드 에디터'일 뿐, 안드로이드 개발에 필요한 모든 도구(SDK, 컴파일러, 에뮬레이터 등)를 포함하고 있지는 않습니다. 따라서 반드시 기존의 안드로이드 개발 환경이 컴퓨터에 설치되어 있어야 합니다.

Android Studio 설치: 가장 쉬운 방법입니다. Android Studio를 설치하면 안드로이드 SDK, JDK, 커맨드 라인 도구, 에뮬레이터 등 모든 필수 요소가 한 번에 설치됩니다. 이미 설치되어 있다면 이 단계는 넘어가세요.
환경 변수 설정: 안드로이드 SDK 경로(ANDROID_HOME 또는 ANDROID_SDK_ROOT)가 시스템 환경 변수에 제대로 등록되어 있는지 확인하세요.

2. Cursor 설치 및 프로젝트 열기

Cursor 다운로드: 공식 홈페이지(cursor.sh)에서 자신의 운영체제에 맞는 버전을 다운로드하여 설치합니다.
안드로이드 프로젝트 열기: Cursor에서 File > Open Folder... 메뉴를 통해 기존에 만들었던 안드로이드 프로젝트 폴더를 엽니다. (Gradle 빌드 파일인 build.gradle.kts가 있는 폴더입니다.)

3. 추천 확장 프로그램(Extensions) 설치

Cursor는 VS Code 기반이므로, 확장 프로그램을 설치해야 안드로이드 개발이 훨씬 편해집니다. 왼쪽 사이드바에서 Extensions 탭(네모 블록 모양 아이콘)을 열고 다음을 검색하여 설치하세요.

필수:
- Kotlin: Kotlin 언어 지원 (구문 강조, 자동 완성 등)
- Extension Pack for Java: Java 언어 지원
추천:
- Gradle for Java: Gradle 빌드 스크립트 지원
- Jetpack Compose: 컴포즈 코드 스니펫 및 유용한 기능 제공

Cursor의 핵심 AI 기능 사용법

1. AI와 대화하기 (Ctrl + L)

에디터 어디서든 Ctrl + L (Mac: Cmd + L)을 눌러 채팅창을 열 수 있습니다.

질문: "Jetpack Compose에서 LazyColumn 사용법 알려줘", "MVVM 아키텍처란 뭐야?"
에러 해결: 빌드 실패 시 출력된 에러 로그를 복사해서 붙여넣고 "이 에러 해결해줘"라고 요청

2. 코드 생성 및 편집 (Ctrl + K) - 가장 강력한 기능!

코드를 수정하거나 새로 만들고 싶을 때 사용하는 기능입니다.

새 코드 생성: 빈 줄에 커서를 두고 Ctrl + K (Mac: Cmd + K)를 누른 후 원하는 기능을 지시합니다.
- "이메일과 비밀번호 입력 필드, 로그인 버튼을 포함하는 로그인 화면 Composable 함수 만들어줘"
- "Retrofit을 사용해서 'https://api.example.com/'에 GET 요청을 보내는 함수 만들어줘"
기존 코드 수정: 수정하고 싶은 코드 블록을 선택(드래그)한 후 Ctrl + K를 누릅니다.
- (네트워크 함수를 선택하고) "이 코드에 try-catch로 예외 처리 추가해줘"
- (복잡한 함수를 선택하고) "이 코드를 더 읽기 쉽게 리팩토링해줘"

3. 컨텍스트(@)를 활용한 정확한 지시

AI에게 더 정확한 맥락을 알려주기 위해 @ 기호를 사용합니다.

@파일이름: 특정 파일의 내용을 참고하라고 AI에게 알려줍니다.
- @UserViewModel.kt 파일을 참고해서 @UserScreen.kt 에 필요한 UI 코드를 작성해줘.
@docs: 공식 문서를 참고하여 답변하게 합니다.
- @docs/kotlin-coroutines 내용을 기반으로 비동기 처리 코드 작성해줘.

'룰 설정'의 의미와 방법

'룰 설정'은 Cursor AI가 내 프로젝트에 대해 따라야 할 전반적인 규칙이나 가이드라인을 설정하는 것을 의미합니다. 프로젝트 루트 폴더에 .cursor 라는 숨김 폴더를 만들고 그 안에 설정 파일을 두어 관리할 수 있습니다.

.cursor/ide.json 파일 생성 및 규칙 설정

프로젝트의 루트 디렉터리에 .cursor 폴더를 만들고, 그 안에 ide.json (또는 context.json) 파일을 생성하여 다음과 같이 AI에게 지시사항을 내릴 수 있습니다.

{
  "directives": [
    "우리는 모든 UI를 Jetpack Compose를 사용해서 개발해.",
    "상태 관리는 ViewModel과 StateFlow를 사용해줘.",
    "네트워크 통신은 Retrofit과 OkHttp 라이브러리를 사용하고 있어.",
    "새로운 코드를 작성할 때는 항상 코틀린 코딩 컨벤션을 지켜줘.",
    "모든 클래스와 함수에는 KDoc 주석을 추가해줘."
  ]
}

이렇게 '룰'을 설정해두면, Ctrl + K로 코드를 생성하거나 수정할 때 AI가 이 규칙들을 먼저 고려하여 결과물을 만들어줍니다. 덕분에 프로젝트의 일관성을 유지하기가 매우 용이해집니다.

요약: Android Studio vs Cursor

Android Studio: UI 디자인, 에뮬레이터 연동, 빌드 및 배포 등 안드로이드 개발의 전반적인 관리와 실행에 있어서는 여전히 필수적이고 가장 강력합니다.
Cursor: 코드 작성, 리팩토링, 디버깅 단계에서 AI의 도움을 받아 생산성을 폭발적으로 높이는 데 특화되어 있습니다.

추천 워크플로우: 프로젝트 생성, 빌드, 실행, 디버깅은 Android Studio를 메인으로 사용하고, 코드 작성 및 수정이 필요할 때 Cursor를 열어 AI의 도움을 받는 방식으로 함께 사용하면 최고의 효율을 낼 수 있습니다.

Gson vs Kotlinx Serialization — 누락 키·null·추가 키·예외 한 번에 끝내기

코딩하는후운 — Mon, 18 Aug 2025 16:26:32 +0900

문제 : Kotlinx Serialization 에서 MissingFieldException가 발생 하였다.

DTO에 키가 있는데 Response에 key가 없어서 발생한 사례입니다.

안드로이드 개발에서 많이 쓰이는 Gson과 Kotlinx Serialization, 두 라이브러리는 이 과정에서 눈에 띄는 차이를 보입니다.
특히 JSON에 특정 키가 없거나 null 값이 올 때 어떻게 동작하는지 이해하는 것이 중요합니다.
잘못하면 앱이 죽는(크래시) 원인이 될 수 있거든요.

그리고, 추가키(정의되지 않는 키)가 내려와도 UnknownFieldException이 발생한다.

왜 예외가 나나? (kotlinx.serialization의 규칙)

1. 필드가 빠지면: MissingFieldException

DTO에 정의된 프로퍼티(필드)가 JSON 응답에 아예 없으면 MissingFieldException이 발생합니다.
[❌ 가장 많이 혼동하는 부분] val name: String? 처럼 타입을 널러블(?)로 선언하는 것만으로는 충분하지 않습니다.
- val name: String? : "이 필드는 null 값을 허용한다"는 뜻이지, "이 필드가 없어도 된다(Optional)"는 뜻이 아닙니다. 이 필드는 **여전히 필수(Required)**입니다. JSON에 name 키가 아예 없으면 MissingFieldException이 발생합니다.
- val name: String? = null : "이 필드는 null 값을 허용하며, JSON에 키가 없어도 된다"는 뜻입니다. 키가 없으면 기본값인 null이 할당됩니다.
결론: 필드를 '옵션(Optional)'으로 만들고 싶다면, 반드시 = null 이나 = -1 같은 명시적인 기본값을 할당해야 합니다.

2. 추가(모르는) 키가 있으면: UnknownFieldException

Gson은 DTO에 정의되지 않은 키(e.g., "new_ad_field": "...")가 JSON에 있어도 조용히 무시하고 파싱을 성공시킵니다.
하지만 kotlinx.serialization은 기본적으로 DTO에 정의되지 않은 키가 오면 "이건 내가 모르는 필드"라며 UnknownFieldException 예외를 발생시킵니다.
이는 서버 API 명세가 바뀌었음을 개발자에게 알려주는 안전장치 역할을 하기도 합니다.

해결 방법 : ignoreUnknownKeys 추가. 아래 방법 있습니다.

Gson은 왜 안 터지지?

Gson은 기본적으로 관대(lenient) 합니다.
없는 항목은 각 타입의 기본값으로 채우고(객체=null, 숫자=0, 불린=false), 파싱을 이어갑니다.
그래서 “파싱 시점”엔 잘 지나가고, 나중에 그 값을 쓸 때 NPE가 날 수 있죠.

Gson = 관대: 누락/null/추가 키가 와도 파싱은 대체로 성공. 대신 값이 기본값/null로 들어가고, 나중 사용 시 NPE가 터질 수 있음.
kotlinx.serialization = 엄격: 기본값 없는 프로퍼티는 필수로 취급 → 누락/null이면 즉시 예외. 대신 DTO 기본값이나 옵션을 명시하면 안전.

JSON 상황	Gson 결과	kotlinx.serialization 결과(기본설정)	이유	실무 해결
키가 없음 ("order" 자체 없음)	파싱 성공. 프리미티브는 기본값(0/false), 레퍼런스는 null	예외: MissingFieldException (기본값이 없으면 필수 필드)	Gson은 관대/리플렉션, Kotlinx는 생성자기반+옵셔널 판정	DTO에 기본값 넣어 옵션화 val order: Int = -1
값이 null ("order": null)	프리미티브(비-null Int/Boolean)는 기본값(0/false), 레퍼런스/nullable은 null (파싱 성공)	예외: JsonDecodingException (non-null에 null 불가)	non-null은 null 불허	1. explicitNulls=false로 null을 ‘부재’처럼 처리 → 기본값 적용, 2. 또는 Int?로 받고 매퍼에서 ?: -1
추가(모르는) 키	보통 무시	예외 (기본값)	엄격 모드라 미정의 키 오류	Json { ignoreUnknownKeys = true }
타입 불일치 ("order":"5")	케이스에 따라 시도/실패	예외: JsonDecodingException	타입 안 맞음	서버 수정 or 커스텀 시리얼라이저로 보정

- Kotlinx에서 non-null이면 예외를 “던진다”(자동 예외처리 X). DTO 기본값이 없고 키가 없으면 예외를 “던진다”.

설정/코드로 안전하게 쓰는 법 (kotlinx.serialization)

1) “키 없음”에 안전해지는 가장 쉬운 방법

@Serializable
data class HomeSectionDto(
  @SerialName("order") val order: Int = -1,    // 기본값 → 옵션 필드로 간주
  @SerialName("section") val section: String = "",
  // 하위 DTO도 기본값 제공 필요
)

- 기본값이 있으면 → 그 프로퍼티는 옵셔널이라 키가 없어도 통과.

2) "order": null도 예외 없이 받으려면
옵션 A — 전역 설정 완화

val json = Json {
  explicitNulls = false   // null을 '없는 것'처럼 취급 → 기본값 사용
}

- explicitNulls = false → 명시적 null을 부재처럼 취급해 기본값/nullable 로 대입.

옵션 B — 프로퍼티를 nullable로 받고 매퍼에서 보정

@Serializable
data class HomeSectionDto(@SerialName("order") val order: Int? = null)

fun HomeSectionDto.asDomain() = HomeSection(order = order ?: -1)

- 전역 설정을 건드리지 않고 명시적으로 제어할 수 있음.

3) 추가 키가 와도 무시하고 싶다면 UnknownFieldException

val json = Json { ignoreUnknownKeys = true }

Retrofit 설정 전역 Kotlinx 설정 예

@OptIn(ExperimentalSerializationApi::class)
@Provides
fun provideResponseJsonConverterFactory(): Converter.Factory =
    Json {
        ignoreUnknownKeys = true  // 추가 키 무시
        explicitNulls = false     // "null"을 부재 취급 → 기본값/nullable로
    }.asConverterFactory("application/json".toMediaType())

궁금했던 것

Q. Gson이면 null-safe 안 해도 되나요?
A. 아니요. 파싱은 통과하지만 레퍼런스 타입에 null이 들어오면 사용 시 NPE로 죽습니다.

Q. Kotlinx에서 non-null 프로퍼티면 null은?
A. 예외를 던집니다. 자동 예외처리(흡수) 아닙니다.

Q. "order": null을 기본값으로 바꾸고 싶어요.
A. explicitNulls=false + val order: Int = -1 or val order: Int? = null + 매퍼 보정.

LLM	Claude Opus, Gemini Flash	성능 + 비용 밸런스
Vector DB	Milvus	오픈소스, 확장성
Graph DB	Neo4j	관계 분석에 최적
Framework	Python + CLI	유연성, 디버깅 용이