Simple is Best.

[AI Agent] Fable 5와 유사한 에이전트 지침 만들어보기

Super-Son — Mon, 13 Jul 2026 00:35:15 +0900

오늘은 Fable 5를 사용해 다른 모델로도 Fable 5처럼 사용할 수 있는 AI 에이전트 지침을 만드는 시도를 정리해 보려고 합니다. Fable 5가 성능이 워낙 좋다는 소식에 Fable 5가 너무 비싸니까 비슷한 걸 지침으로 만들 수 있을까? 라고 생각하고 시작했었습니다. 결론적으로 동일하게 동작하는 지침을 만드는 건 실패했지만, 기존에 사용하던 지침보다는 더 일을 잘하는 지침을 만드는 건 성공했습니다. (글 마지막 github link 첨부)

Fable 5와 유사하게 만들기 위해 사용한 방법

먼저 Fable 5에게 '다른 모델을 사용해도 Fable 5처럼 동작하는 지침을 만들어줘.'라고 요청했습니다.

Claude chat history

에이전트_사고행동_지침.md

0.01MB

Fable 5가 세세한 절차 지시를 기입하지 않아도 잘 한다고 했으니 그대로 사용해봤습니다. 원하는 목표만 주고 나온 결과물을 'Fable 5처럼 동작하게 잘 구성됐는지' 피드백 및 평가를 요청해 개선했습니다.

Fable 5로 초안 작성
→ 부족한 부분 피드백
→ 지침 수정
→ 실제 작업 상황을 대입해 검토
→ 다시 피드백
→ 구조와 표현 개선

에이전트 지침의 핵심 구성

완전하진 않지만 위와 같은 과정을 통해 완성한 지침은 목적과 예시를 제공하면 에이전트가 계획을 세우고 작업 및 검증까지 하도록 구현하는 것에 성공했습니다.

지침의 주요 구성

핵심 원칙	목적 파악, 모호함 처리, 불확실성 표시
작업 규율	범위 통제, 진행 상황 보고, 임의 수정 방지
분석 프로토콜	샘플 검증, 행 수 추적, 집계 결과 역산
설계 프로토콜	요구사항, 제약 조건, 대안과 트레이드오프 기록
Orchestrator	작업 분해, 위험도 판단, 실행 순서 계획
Reviewer	작성자와 별도 관점에서 결과물 검증
Memory	프로젝트에서 반복되는 교훈 저장
State	긴 작업의 단계와 검토 상태 기록

모호함을 처리하는 기준

에이전트가 모든 애매한 내용을 사용자에게 질문하면 작업 속도가 너무 느려집니다.

반대로 전부 임의로 판단하게 하면 결과물이 잘못된 방향으로 진행될 수 있습니다.

그래서 다음과 같이 지침이 만들어졌습니다.

가정이 틀렸을 때 결과물을 다시 만들어야 한다면 질문하고, 결과에 큰 영향이 없다면 합리적으로 가정한 뒤 가정 내용을 명시합니다.

예를 들어 날짜 컬럼이 생성일인지 수정일인지에 따라 분석 결과가 달라진다면 반드시 확인해야 합니다.

하지만 출력 파일 이름처럼 결과의 본질에 영향을 주지 않는 내용은 기본값을 사용해도 됩니다.

이 기준을 넣은 뒤에는 에이전트가 불필요한 질문을 반복하거나, 중요한 내용을 마음대로 판단하는 문제가 줄어들었습니다.

확인된 사실과 추정 구분하기

AI의 가장 위험한 문제 중 하나는 확실하지 않은 내용을 자연스럽게 사실처럼 작성한다는 점입니다.

이를 방지하기 위해 근거의 수준을 다음과 같이 구분했습니다.

확인됨	원본 파일이나 실행 결과로 직접 검증됨
추정	간접적인 근거를 바탕으로 판단함
가정	작업 진행을 위해 기본값으로 선택함
검증 필요	현재 자료만으로 확정할 수 없음

예를 들어 파일을 수정했다고 보고하려면 실제로 파일이 저장되었는지 확인해야 합니다.

테스트가 통과했다고 말하려면 테스트 명령어를 실행한 결과가 있어야 합니다.

도구로 확인하지 않은 작업은 완료했다고 보고하지 않도록 지침에 명시했습니다.

작성자와 검토자 분리하기

제가 기존에 사용하던 지침은 하나의 에이전트가 결과물을 만들고 스스로 다시 읽는 방식이었습니다.

이러면 에이전트가 자신이 만든 논리와 가정에 이미 영향을 받은 상태이기 때문에, 단순히 다시 읽는 것만으로는 문제를 찾기 어려워 다음과 같이 역할이 분리됐습니다.

Orchestrator
    ↓
Worker
    ↓
Reviewer
    ↓
수정 필요 여부 판단
    ↓
Worker 재작업
    ↓
Reviewer 재검증

여기서 실제 작업의 전체 흐름은 메인 에이전트가 관리합니다.

Orchestrator: 작업 분해와 실행 계획을 제안
Worker: 실제 분석, 코드 작성, 문서 작성 수행
Reviewer: 결과물만 보고 오류와 누락 검토
메인 에이전트: 검토 결과에 따라 수정과 재검증 진행

Reviewer는 단순히 문장을 자연스럽게 고치는 역할이 아닙니다.

다음과 같은 관점으로 결과물을 공격적으로 검토하도록 구성했습니다.

요청사항을 모두 충족했는가?
결론이 근거에서 실제로 도출되는가?
수치와 행 수가 서로 모순되지 않는가?
추정이나 가정을 사실처럼 표현하지 않았는가?
요청하지 않은 범위까지 수정하지 않았는가?
이 결론을 반박할 수 있는 사례는 없는가?

대규모 분석을 위한 검증 절차

저는 주로 데이터 분석에 에이전트를 사용하는데, 기존에는 에이전트가 작업한 결과물에 대해서 실제로 결과에 문제가 없는지 검수하는 데 시간을 오래 사용했었습니다. 특히 많은 데이터를 한 번에 처리하면 중간 과정에서 발생한 오류를 찾기 어려웠습니다.

만들어진 지침에서는 다음과 같은 절차를 기본 원칙으로 넣어 기본적인 검수를 에이전트가 하도록 구현됐습니다.

전체 데이터 구조 확인
→ 소규모 샘플로 로직 검증
→ 처리 단계별 행 수 기록
→ 전체 데이터에 적용
→ 집계 결과를 원본 데이터로 역추적
→ 이상 여부 확인

예를 들어 데이터가 다음과 같이 변했다면 각 단계의 원인을 확인합니다.

원본 데이터: 100,000행
필터 적용 후: 82,000행
조인 후: 125,000행
중복 제거 후: 81,500행

조인 후 행 수가 예상보다 늘어났다면 바로 다음 작업으로 넘어가는 것이 아니라, 조인 키의 중복이나 다대다 관계를 먼저 확인합니다. 이런 검증 절차로 속도는 조금 줄었지만, 잘못된 분석 결과를 에이전트가 1차로 먼저 잡아냈습니다.

Cursor와 Claude Code에 적용한 구조

만든 지침은 하나의 문서로만 관리하지 않고, Cursor와 Claude Code에서 각각 사용할 수 있도록 구성했습니다.

저는 주로 Cursor로만 작업을 하는데 주변에는 Claude Code를 쓰는 사람들도 많아서 둘다 만들었습니다.

agent-thinking-guidelines/
├── docs/
│   ├── agent-thinking-guidelines.md
│   ├── agent-system-overview.md
│   └── multi-agent-orchestration.md
├── cursor/
│   ├── .cursor/rules/
│   ├── .cursor/skills/
│   ├── .cursor/agents/
│   ├── .cursor/memory/
│   └── .cursor/state/
└── claude/
    ├── CLAUDE.md
    ├── skills/
    ├── agents/
    ├── .claude/memory/
    └── .claude/state/

docs/를 원본 지침으로 사용하고, 해당 내용을 Cursor와 Claude Code의 규칙 체계에 맞게 각각 변환했습니다.

원본 역할CursorClaude Code

핵심 원칙	.cursor/rules/*.mdc	CLAUDE.md
상황별 프로토콜	.cursor/skills/	.claude/skills/
서브에이전트	.cursor/agents/	.claude/agents/
프로젝트 기억	.cursor/memory/	.claude/memory/
작업 상태	.cursor/state/	.claude/state/

이렇게 구성한 이유는 도구별 파일 구조는 달라도, 에이전트가 따라야 하는 핵심 원칙은 하나의 원본에서 관리하기 위해서입니다. 한쪽 지침만 수정하고 다른 쪽을 놓치지 않도록 docs/를 SSOT(Single Source of Truth)로 사용했습니다.

세션 간 기억을 추가한 이유

AI와 작업하다 보면 이전 세션에서 이미 해결한 문제를 다음 세션에서 다시 설명해야 하는 경우가 많습니다.

이를 줄이기 위해 프로젝트에서 반복되는 교훈을 파일로 저장하도록 구성했습니다.

.cursor/memory/
└── timestamp-column.md

예시 내용은 다음과 같습니다.

요약: created_at은 데이터 생성일이 아니라 동기화 시점이므로 기간 분석 기준으로 사용하지 않습니다.

프로젝트의 기간 분석에서는 service_date를 기준으로 사용합니다.
created_at은 적재 및 동기화 상태를 확인하는 용도로만 사용합니다.

메모리는 한 파일에 모든 내용을 누적하지 않고, 한 가지 교훈을 하나의 파일로 관리하도록 했습니다. 세션 시작 시 모든 파일의 본문을 읽는 대신 첫 번째 요약 문장만 확인하고, 현재 작업과 관련된 메모만 자세히 읽게 구성했습니다.

직접 사용해 본 후기

현재까지 사용해 본 결과는 만족스럽습니다.

가장 크게 달라진 부분은 결과물 뿐만 아니라 작업 설계 편의성과 작업 과정의 안정성, 그리고 가성비였습니다.

설계 편의성

세세하게 지시하지 않고 작업 목표만 줘도 설계를 하고 애매한 건 물어봄

안정성

애매한 내용을 임의로 채우는 경우가 줄어듦
작업 범위를 벗어난 수정이 줄어듦
긴 작업에서도 현재 단계와 남은 작업을 확인하기 쉬워짐
데이터 분석 결과를 한 번 더 검증하는 흐름이 생김
완료했다고 보고한 내용과 실제 작업 결과가 비교적 잘 일치함
수정 요청 시 처음부터 다시 만드는 일이 줄어듦

가성비

Composer 2.5로도 충분히 만족스러운 결과가 나옴

Fable 5와 같게 만들 수 있었는가?

결론적으로 Fable 5와 완전히 같게 만드는 것은 불가능했습니다.

지침을 잘 작성한다고 해서 모델 자체의 추론 능력이나 판단 능력이 올라가는 것은 아니기 때문입니다.

지침으로 개선할 수 있는 것은 주로 다음과 같은 행동 패턴입니다.

작업 전 요구사항 확인
모호함을 처리하는 방식
검증 절차 수행
불확실성 표시
작업 범위 통제
결과물 자체 검토
진행 상황과 오류 보고

반면 다음과 같은 부분은 사용하는 모델의 성능에 영향을 많이 받습니다.

복잡한 문제를 분해하는 능력
긴 문맥을 유지하는 능력
미묘한 오류를 발견하는 능력
새로운 상황에 규칙을 적절히 적용하는 능력
여러 도구와 에이전트를 안정적으로 조율하는 능력

따라서 이번 지침은 Fable 5를 복제한 결과물이라기보다는, Fable 5에서 만족스러웠던 작업 방식을 일반적인 에이전트 환경에 적용해 본 결과물에 가깝습니다. 완전히 동일하지는 않지만, 제가 원했던 방향에는 어느 정도 유사하게 만들어진 것 같습니다.

마무리

Fable 5와 완전히 같게 만들 수는 없었지만, Fable 5로 초안을 만들고 피드백과 개선을 반복하면서 그나마 유사한 방향으로 다듬어 본 결과 현재는 꽤 만족스럽게 사용하고 있습니다. 앞으로 사용해보면서 지속적으로 개선해볼 생각입니다.

에이전트 지침으로 뭘 써야하나 이것저것 테스트해보시거나, 직접 만들어보려고 시도 중이신 분들에게 도움이 되면 좋을 것 같습니다. 감사합니다.

GitHub: https://github.com/geunsu-son/agent-thinking-guidelines

[Cursor] 실사용 내역 기준 모델 비용 분석 (feat. Composer 2.5 Fast 끄기)

Super-Son — Fri, 10 Jul 2026 00:44:47 +0900

Cursor를 업무에 쓰면서 모델을 선택하고 사용하는데 크게 생각하지 않았었는데 최근 Opus 4.8가 발표된 뒤 사용해보다가, 이번에 비용이 크게 나왔으니 원인 보고를 하도록 지시를 받았습니다.

2026년 5월 초부터 6월 말까지 2개월 치의 토큰 사용량을 확인했는데 이벤트는 900건이 조금 넘었으며 토큰은 대략 6억 3천만 정도였습니다. 이번 사용 내역을 분석해보면서 생각한 것과 그래서 앞으로 저는 어떻게 쓸지를 정리해보았습니다.

처음엔 그냥 골라 썼습니다

처음에는 Auto, Composer, Opus가 각각 뭔지 잘 모른 채로, 필요할 때마다 그냥 골라가며 썼습니다. 새로 나왔다고 하면 써보고, 대규모 작업에 좋다고 하면 좋겠거니 하고 고르는 식이었습니다. 그래서 비용이 나중에야 눈에 들어왔습니다.

숫자가 말해 준 것

사용 내역을 모델별로 나눠 보니, 토큰 대비 비용이 아래처럼 나왔습니다.

모델	이벤트	토큰 비중	On-Demand	1M 토큰당 비용	이벤트당 평균 토큰
Opus 4.8	201	47%	$298.60 (79%)	$1.24	1.53M
auto	508	35%	$36.67 (10%)	$0.36	0.67M
composer-2.5-fast	191	17%	$44.45 (12%)	$1.05	0.78M

이벤트 수는 Auto가 더 많았는데, 토큰의 절반 가까이와 On-Demand 비용의 약 80%는 Opus에서 나왔습니다.
Auto는 건수도 많고 1M 토큰당 비용도 $0.36으로 가장 낮았습니다. 반면 composer-2.5-fast는 1M 토큰당 $1.05로, Auto보다 토큰 대비 비용이 꽤 높았습니다. Composer 2.5가 저렴하다고 생각해서 사용했는데 왜 이렇게 비용이 크게 나왔는지를 확인해보니 Fast Mode를 쓰면 Standard Mode 보다 6배정보 비싸더라구요..? (링크)

단순 모델의 문제는 아니었겠으나 기본적으로 모델 비용이 비싼걸 사용하면 비용이 눈에 띄게 차이가 난다는걸 깨달았습니다. 애초에 비용이 10배 차이였으니 말해뭐해...

Cursor Docs: https://cursor.com/ko/docs/models-and-pricing

지금은 이렇게 씁니다.

대부분의 작업은 Auto

일상적인 SQL 작성·검수, ETL 점검, Git·PR, 짧은 수정은 거의 Auto만 둡니다. 생각보다 Agent 구현도 Auto에 맡겨 두면 Composer 쪽으로 라우팅되는 경우가 많았습니다. “구현이니까 무조건 Composer”로 시작하지 않아도 되는 날이 더 많았습니다.

에이전트를 복잡하게 사용할건데 싸게 쓰고 싶으면 Composer 2.5

Agent로 파일을 오래 만지거나, Auto 라우팅에만 맡기기 애매할 때입니다. (Standard 기준입니다.)

기본값이 Fast으로 되어있어서 별도로 변경해줘야 합니다.

Composer 2.5 Fast 끄는 방법

Composer 2.5의 성능이 제 기준에서는 매우 만족스러워서 굳이 다른 모델을 고르지는 않고 있습니다.

제가 분석한 결과와 사용하는 방법이 완벽하다고 할 수는 없습니다. 업무 종류와 요금제, Cursor 버전마다 체감이 다를 수 있습니다. 그래도 혹시 모델을 뭘 써야 하는지 고민하는 분들에게 도움이 되면 좋겠습니다.

읽어주셔서 감사합니다.

[tmux] 내가 나중에 보려고 정리한 주요 단축키 및 사용법

Super-Son — Sun, 28 Jun 2026 15:34:25 +0900

안녕하세요! 오늘은 tmux(Terminal Multiplexer) 사용법과 주요 단축키에 대한 정리 글입니다. 서버에서 장시간 스크립트를 실행하거나, SSH 접속이 끊겨도 작업을 유지하고 싶을 때 tmux를 쓰면 편하다는 추천을 받았습니다만, 단축키가 익숙해지기 전까지는 계속 사용해버릇해야 될 것 같아 언제든 찾아볼 수 있게 주로 사용하는 단축키만 골라 정리해 보았습니다.

tmux란 무엇이며 왜 쓰는가?

tmux는 하나의 터미널 안에서 여러 작업 공간을 만들고, 그 작업을 백그라운드에 계속 유지할 수 있게 해주는 도구입니다.

용도: 서버에서 장시간 실행되는 스크립트, 크롤러, 자동매매 봇, 백테스트 등을 돌리거나, 터미널 화면을 분할해서 쓰고 싶을 때 유용합니다.
Prefix(접두어): tmux 명령의 시작은 [Ctrl + b]입니다. 이 키를 먼저 누르고 손을 뗀 다음, 다른 키를 입력하는 방식인데, 익숙해지려면 자주 사용해 봐야겠습니다.
주의: window OS는 WSL 로만 사용 가능하다고 합니다. (제가 잘 모르는 걸 수도 있지만...)

세션(Session) 관리

세션은 tmux 작업 공간의 전체 단위입니다. 세션 이름을 지정해 관리하는 것이 나중에 찾기 훨씬 수월합니다.

작업	명령어 / 단축키
새 세션 생성	`tmux new -s [세션명]`
세션 목록 확인	`tmux ls`
세션 밖으로 나가기 (Detach)	[Ctrl + b] → [d]
기존 세션 재접속 (Attach)	`tmux a -t [세션명]`
특정 세션 종료	`tmux kill-session -t [세션명]`

Detach 기능을 사용하면 터미널을 닫아도 서버 작업은 계속 살아있게 됩니다. 개인적으로는 이것이 tmux를 쓰는 가장 중요한 이유라고 생각합니다.

윈도우(Window)와 패널(Pane) 단축키

하나의 세션 안에서 탭(Window)을 나누거나, 화면(Pane)을 분할할 때 사용하는 단축키입니다.

윈도우(Window) - 브라우저 탭 개념

새 윈도우 생성: [Ctrl + b] → [c]
다음/이전 윈도우 이동: [Ctrl + b] → [n] / [p]
윈도우 이름 변경: [Ctrl + b] → [,]

패널(Pane) - 화면 분할 개념

좌우 분할: [Ctrl + b] → [%]
위아래 분할: [Ctrl + b] → ["]
패널 간 이동: [Ctrl + b] → [방향키]
패널 전체 화면/복귀: [Ctrl + b] → [z]

스크롤 모드 및 실전 팁

tmux 안에서는 마우스 스크롤이 바로 되지 않을 수 있습니다. 이때는 아래 모드를 활용하면 됩니다.

스크롤 모드 진입: [Ctrl + b] → [[]
스크롤 모드 종료: [q]

실제로는 아래 흐름만 익혀도 충분히 자주 사용할 수 있습니다.

tmux new -s work

위 명령어로 세션을 열고 작업을 시작합니다.

python main.py

작업을 돌려둔 뒤에는 아래 단축키로 세션 밖으로 빠져나옵니다.

Ctrl + b → d

나중에 다시 확인하고 싶을 때는 아래 명령어로 접속합니다.

tmux a -t work

처음에는 단축키가 낯설지만, 위의 최소 암기 세트만 익혀도 웬만한 서버 작업은 충분히 가능합니다. 저처럼 단축키를 자주 잊어버리는 분들께 이 정리 글이 도움이 되었으면 좋겠습니다.

해당 기능을 사용하는 분들께 도움이 되면 좋겠습니다. 감사합니다.

[python] 디버깅 방법 정리 (try~except, raise, from e)

Super-Son — Sun, 18 Jan 2026 22:27:12 +0900

파이썬으로 작업하다 보면 try~except를 자주 사용하게 된다. 에러가 발생하더라도 전체 작업이 중단되지 않게 하기 위해서인데, 문제는 이걸 여기저기 덕지덕지 사용하다 보니 나중에 디버깅을 할 때 도대체 어디서 문제가 생겼는지 한 번에 파악하기가 어려워졌다는 점이었다.

이 글에서는 내가 실제로 겪었던 방식들을 기준으로, 디버깅 과정에 조금이나마 도움이 되었던 예외 처리 방법을 정리해봤다.

try~except + print(e)

에러가 발생해도 코드는 계속 동작하게 두고, 어떤 에러가 발생했는지만 로그로 남기는 방법이다.

def convert_to_int(value):
    try:
        return int(value)
    except ValueError as e:
        print(e)
        return None

# 출력 예시
invalid literal for int() with base 10: 'abc'
# 함수 정상 종료

장점

코드 흐름이 끊기지 않는다.
콘솔 로그를 통해 에러 원인을 바로 확인할 수 있다

단점

함수 실패 여부를 놓치지 쉽다. (함수 정상 리턴)

try~except + raise, from e

전체 흐름에 치명적인 문제가 발생할 여지가 있는 경우 예외를 발생시켜 실패시키는 방법이다.

def convert_to_int(value):
    try:
        return int(value)
    except ValueError as e:
        raise RuntimeError("숫자 변환 실패") from e

# 출력 예시 - from e 미사용
Traceback (most recent call last):
  File "example.py", line 12, in <module>
    convert_to_int("abc")
  File "example.py", line 8, in convert_to_int
    raise RuntimeError("숫자 변환 실패")
RuntimeError: 숫자 변환 실패


# 출력 예시 - from e 사용
Traceback (most recent call last):
  File "example.py", line 6, in convert_to_int
    int("abc")
ValueError: invalid literal for int() with base 10: 'abc'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "example.py", line 12, in <module>
    convert_to_int("abc")
  File "example.py", line 8, in convert_to_int
    raise RuntimeError("숫자 변환 실패") from e
RuntimeError: 숫자 변환 실패

장점

해당 지점에서 코드 흐름이 명확하게 중단되고
호출한 쪽에서도 “이건 실패한 작업이다”라는 걸 바로 알 수 있다.
from e 덕분에 실제 원인이 된 에러(ValueError)도 함께 남는다.

단점

우선 코드가 완전히 끝나야 하는 경우에는 적합하지 않다.

[Python] raise를 활용해 의도적으로 예외 처리하기

Super-Son — Sun, 18 Jan 2026 21:56:38 +0900

파이썬으로 작업하던 중 “이 상황에서는 그냥 진행하면 안 되는데…” 싶은 순간에 의도적으로 에러를 발생시키는 게 필요해져서 알아보니 raise라는 문법을 발견했다. 이번 글에서는 raise의 사용 예시와 상황에 맞는 예외들을 정리해봤다

raise는 언제 쓰는 게 좋을까?

raise는 “이 상태는 정상 흐름이 아니다” 라는 것을 코드로 명확히 표현할 수 있는 방법이다.
입력값이 잘못됐거나, 필수 데이터가 없거나, 더 이상 처리를 진행하면 안 되는 경우에 특히 유용했다.

raise 사용 예시

def validate_age(age):
    if age < 0:
        raise ValueError("나이는 0 이상이어야 합니다.")
    if age > 150:
        raise ValueError("나이는 150 이하여야 합니다.")
    return age

조건을 만족하지 않으면 즉시 ValueError를 발생시켜 함수 실행을 중단한다.

try:
    validate_age(-5)
except ValueError as e:
    print(e)
    raise

except에서 로그만 남기고 다시 raise 하면, 에러 메시지를 유지한 채 프로그램을 종료할 수 있다.

상황에 맞는 예외 타입 선택하기

raise를 쓰면서 느낀 점은 예외 타입 자체가 설명서 역할을 한다는 것이다.

값이 잘못된 경우 → ValueError
타입이 다른 경우 → TypeError
딕셔너리 키 누락 → KeyError
리스트 범위 초과 → IndexError
파일 문제 → FileNotFoundError, PermissionError

예외 타입과 메시지만 봐도 어떤 문제가 발생했는지 바로 파악할 수 있다.

실전 활용 예시

ETL 과정에 아래와 같은 검증용 매서드를 정의하여 이후 문제가 되는 상황을 잘 잡아냈었다.

def validate_dataframe(df, required_columns=None):
    if df is None:
        raise ValueError("입력 데이터가 None입니다.")

    if not isinstance(df, pd.DataFrame):
        raise TypeError("DataFrame이 필요합니다.")

    if df.empty:
        raise ValueError("데이터프레임이 비어있습니다.")

    if required_columns:
        missing = [c for c in required_columns if c not in df.columns]
        if missing:
            raise KeyError(f"필수 컬럼 누락: {missing}")

마무리

저는 평소 if, print를 사용해서 문제가 되는 부분들을 다 찍어보면서 처리했었는데 raise를 사용하면서 횟수가 상대적으로 줄어들었었습니다. 처음 raise를 알게 된 분들에게 도움이 되었길 바랍니다.

[Cursor] Possible Fixes to Try When Jupyter Kernel Errors Occur After the Agent Update

Super-Son — Fri, 21 Nov 2025 16:34:36 +0900

* Translated by ChatGPT

It’s been over half a year since I switched from VSCode to Cursor. Although Cursor is still slightly less stable compared to VSCode at times, I’ve generally been quite satisfied with it. However, after the agent feature update in early November, I ran into an issue where the Jupyter Notebook kernel stopped being recognized.

It turned out I wasn’t the only one experiencing this — there was a bug report on the Cursor Forum, and the suggested workaround was to reinstall an older version. I followed that for a while, but recently I stumbled upon a simple attempt that surprisingly resolved the issue. It was almost nothing… yet it worked.

Kernel Selection doesn't work

Where does the bug appear (feature/product)? Cursor IDE Describe the Bug I cannot select any of my Kernels for my Jupyter notebook. In vs studio code it is working. It may be a problem with the extension Python Environments, which cannot be installed in th

forum.cursor.com

Reinstalling the Jupyter extension fixed it (somehow)

For a moment, I genuinely considered switching back to VSCode, so I’m relieved that this resolved the issue. Since I haven’t tested this on other machines, I can’t say for sure that this will work for everyone.

Still, I’m sharing this in hopes that it helps someone else who’s been struggling with Jupyter kernel issues on Cursor.

[Cursor] 에이전트 업데이트 후 주피터 커널 오류 발생 시 시도해볼만한 해결법

Super-Son — Fri, 21 Nov 2025 16:32:28 +0900

VSCode에서 Cursor로 넘어온 지도 벌써 반년이 지났습니다. 아직은 VSCode에 비해 가끔 불안정한 모습을 보이지만, 개인적으로는 꽤 만족하며 잘 사용 중인데요. 그런데 11월 초 에이전트 기능이 업데이트된 이후로 주피터 노트북 커널이 인식되지 않는 문제가 발생했습니다.

저만의 문제는 아니었는지 Cursor 포럼에도 동일한 버그 제보가 올라와 있었고, 임시 해결책으로는 “이전 버전을 다시 설치하라”는 조언이 있었습니다. 그래서 그동안은 그렇게 사용하고 있었는데, 최근 이것저것 만지다가 우연히 해결이 되어 기록을 남겨봅니다. 정말 별거 아닌 시도였는데… 의외로 됐습니다.

Kernel Selection doesn't work

forum.cursor.com

익스텐션에서 주피터를 다시 설치했더니 됐습니다. (?)

한때는 “다시 VSCode로 돌아가야 하나?” 싶을 정도로 불편했는데, 다행히 이렇게 간단히 해결돼서 마음이 놓였어요. 다만 다른 PC 환경에서는 테스트해보지 않아 이 방법이 보편적인 해결책이라고는 장담하기 어렵습니다.

그래도 저처럼 Cursor에서 주피터 커널 인식 문제로 고생하는 분들이 계시다면, 조금이나마 도움이 되기를 바라며 글을 남깁니다.

[Pandas] Series.get(key, default)

Super-Son — Tue, 14 Oct 2025 19:03:32 +0900

DataFrame의 특정 열에 접근할 때 보통 row['col_name']을 사용하지만, 전처리 과정이나 외부 데이터 병합 이후 컬럼이 조건부로 생성될 수 있는 경우에는 get()이 훨씬 안전할 수 있습니다. 이번 글에서는 .get()을 사용하는 방법과 장단점을 정리해보았습니다.

함수 설명

Series.get(key, default)메서드는 존재하지 않는 키(열 이름)에 접근할 경우 오류를 발생시키지 않고, 대신 기본값(default)을 반환하는 안전한 접근 방식입니다.

예시 코드

import pandas as pd

# 예제 데이터
df = pd.DataFrame({
    'name': ['홍길동', '이몽룡', '성춘향'],
    'age': [25, 27, 22]
})

# 존재하지 않는 컬럼을 조회할 때
for _, row in df.iterrows():
    try:
        print(row['address'])   # KeyError 발생
    except KeyError:
        print('KeyError 발생!')

# 안전하게 접근
for _, row in df.iterrows():
    print(row.get('address', '주소 없음'))

KeyError 발생!
KeyError 발생!
KeyError 발생!
주소 없음
주소 없음
주소 없음

row['address'] → 존재하지 않는 컬럼이면 KeyError
row.get('address', '주소 없음') → 기본값 '주소 없음'을 반환

즉, get()을 쓰면 예상치 못한 컬럼 누락에도 코드가 멈추지 않고 기본값으로 처리할 수 있습니다.

장단점 비교

✅ 장점

예외 처리 불필요: 존재하지 않는 컬럼에 접근하더라도 오류 발생 X
기본값 설정 가능: 결측 컬럼에 대한 기본값을 쉽게 지정 가능해 전처리 유용

⚠️ 단점

성능 저하 가능성: 내부적으로 추가적인 확인 과정을 거치므로, 대규모 데이터 반복 시 성능 차이 가능성 有
명시적 에러 감지 불가: 잘못된 컬럼명을 실수로 입력해도 오류가 발생하지 않아 디버깅 시 문제 발견 어려움
일부 Pandas 객체에서 미지원: 특정 상황(예: itertuples())에서는 .get() 메서드 사용 불가

정리

정상적인 컬럼 존재를 보장할 때는 row[key]
컬럼 존재가 불확실할 때는 row.get(key, default)

을 사용하는 것이 좋습니다.

[Pandas] 다른 컬럼의 값으로 결측값 채우기 (feat. combine_first)

Super-Son — Wed, 8 Oct 2025 10:06:18 +0900

데이터 정제 작업 중, 두 컬럼을 비교해서 한쪽이 비어 있으면 다른 값으로 채워야 할 때가 있습니다. 이때 fillna()를 주로 사용하지만, 인덱스가 다른 상황에서는 combine_first()가 더 안전한 선택입니다. 이번 글에서는 두 메서드의 차이를 예제로 비교하면서, 어떤 상황에 어떤 함수를 쓰면 좋은지 정리해보겠습니다.

combine_first() 기본 개념

combine_first()는 두 Series(DataFrame 포함)를 결합하여, 앞쪽 값이 결측치(NaN)일 경우 뒤쪽 값으로 채워주는 메서드입니다. 즉, "왼쪽 값을 우선 사용하고, 비어 있으면 오른쪽 값으로 보충"하는 방식으로 작동합니다.

예제 코드

import pandas as pd

df = pd.DataFrame({
    '고객명': ['홍길동', None, '이몽룡'],
    '이름':   ['길동이', '성춘향', None]
})

df['고객명'].combine_first(df['이름'])

0    홍길동
1    성춘향
2    이몽룡
Name: 고객명, dtype: object

0번: '고객명' 값이 있으므로 그대로 유지
1번: '고객명'이 비었으므로 '이름'의 값으로 채움
2번: '고객명' 유지

fillna와의 차이점

비교 항목	fillna	combine_first
기본 동작	NaN만 채움	NaN 채움 + 인덱스 합집합 고려
인덱스 다를 때	무시	자동 정렬 후 병합
반환 결과	원본 인덱스 기준	두 Series의 union 인덱스 기준

예제 코드

s1 = pd.Series(['홍길동', None, '이몽룡'], index=[0, 1, 2])
s2 = pd.Series(['길동이', '성춘향'], index=[1, 3])

print("fillna 결과:\n", s1.fillna(s2))
print("\ncombine_first 결과:\n", s1.combine_first(s2))

fillna 결과:
0    홍길동
1     NaN
2    이몽룡
dtype: object

combine_first 결과:
0    홍길동
1    길동이
2    이몽룡
3    성춘향
dtype: object

fillna: 같은 인덱스만 채우므로 1번은 비어 있음
combine_first: 인덱스 합집합으로 병합해 3번 인덱스까지 반영

정리

인덱스가 완전히 동일한 Series끼리는 fillna()와 combine_first() 결과가 동일
하지만 인덱스가 다를 수 있는 경우에는 combine_first()가 더 안전
일반적인 DataFrame 내부 컬럼 결합이라면 인덱스가 일치하므로 fillna()로 충분하며 속도도 더 빠릅니다.

[Pandas] int, int64, Int64의 차이와 변환 시 주의점

Super-Son — Mon, 6 Oct 2025 17:27:04 +0900

Pandas에서 데이터를 다룰 때 결측치가 섞여있는 데이터를 정수형으로 변경해 사용하고자 할 때 어떤 방법을 사용하는게 좋을까요? 저는 평소 .astype(int)를 쓰다가 숫자가 크면 제대로 변환이 되지 않아 .astype('int64')를 사용했었는데요. 결측치가 있을 때는 오류가 나서 알아보고 .astype('Int64')를 사용해서 해결했습니다. 이 글에서는 세 가지 타입의 차이와 함께 사용하면서 제가 만났던 오류를 피하는 팁을 간단한 예제를 통해 정리해보겠습니다.

int, int64, Int64 비교 — 결측치 수용

import pandas as pd

# 예제1
values = [None, 2, 7]
df = pd.DataFrame(values, columns=['values']) 

# 1-1. int로 변환 - 에러: 결측치
print(df['values'].astype('int'))

# 1-2. int64로 변환 - 에러: 결측치
print(df['values'].astype('int64'))

# 1-3. Int64로 변환 - 성공
print(df['values'].astype('Int64'))

int와 'int64'는 결측치를 허용하지 않기 때문에 None이나 NaN 값이 있으면 변환 오류가 발생합니다. 반면 'Int64'는 Pandas의 nullable integer 타입으로 결측치(pd.NA)를 허용합니다.

타입	결측치 허용	특징
int	❌	Python 기본 타입, 크기 제한 없음
'int64'	❌	NumPy dtype, NaN 불가
'Int64'	✅	Pandas 전용 nullable integer

int형의 한계 — 큰 숫자 변환 문제

# 예제2
values = [2, 7, '2160378724']
df = pd.DataFrame(values, columns=['values'])

# 2-1. int로 변환 - 에러: int로 변환하기에는 너무 큼.
df['values'].astype(int)

# 2-2. int64로 변환 - 성공
df['values'].astype('int64')

# 2-3. Int64로 변환 - 성공
df['values'].astype('Int64')

Python의 int는 내부적으로 크기 제한이 없지만, Pandas에서 사용하는 astype(int) 변환 과정에서는 C 기반 정수형(int32)이 기본으로 사용될 수 있어 32비트 한계를 넘어가면 오류가 발생할 수 있습니다. int32의 범위 아래와 같이 약 ±21억이며, 이를 초과하면 OverflowError 또는 음수 변환이 일어날 수 있습니다. 따라서 큰 숫자를 다루려면 int64나 Int64를 사용하는 것이 안전합니다.

타입	표현 가능 범위
int32	±21억 (-2,147,483,648 ~ 2,147,483,647)
int64 / Int64	약 ±9경 (-9,223,372,036,854,775,808 ~ 9,223,372,036,854,775,807)

Int64 형 사용 시 주의할 점 — float 변환 불가

# 예제3
values = [2, 7, 10.3]
df = pd.DataFrame(values, columns=['values'])

# 3-1. int로 변환 - 성공
df['values'].astype(int)

# 3-2. int64로 변환 - 성공
df['values'].astype('int64')

# 3-3. Int64로 변환 - 에러: float 데이터 변환 불가
df['values'].astype('Int64')

Int64는 결측치를 허용하는 대신 부동소수(float) 값은 허용하지 않습니다. 실수 값이 포함된 데이터는 'int64'로 변환하거나, 필요에 따라 pd.to_numeric(..., errors='coerce')를 사용해 NaN으로 처리한 뒤 변환해야 합니다.

정리

결측치가 포함된 정수열 → Int64 사용
큰 숫자(±21억 이상)를 포함한 데이터 → int64 또는 Int64 사용
실수(float) 포함 시 → int64 또는 float 유지

이 세 가지 타입의 차이를 이해하면 결측치나 큰 값이 섞인 데이터를 변환할 때 발생하는 오류를 쉽게 해결할 수 있습니다.