6부 · 막혔을 때 빠져나오는 법

← 이전: 개발 도구 세팅 · 목차

개발에서 막히는 건 실패가 아니라 기본값입니다. 숙련된 개발자도 하루에 수십 번 막히고, 차이는 "막혔을 때 빠져나오는 속도"뿐입니다. 이 챕터는 오류를 두려워하지 않고 읽는 법, 똑똑하게 검색하는 법, 그리고 입문자가 반복해서 빠지는 함정 목록을 정리합니다. 이게 0번 챕터의 마지막이자, 앞으로 가장 자주 돌아올 챕터입니다.

6.1 오류 메시지는 적이 아니라 안내문이다

빨간 글씨가 잔뜩 쏟아지면 본능적으로 겁이 납니다. 하지만 오류 메시지는 "어디서, 왜 멈췄는지"를 알려주는 안내문입니다. 핵심은 전부 읽으려 하지 말고, 마지막 줄부터 보는 것입니다.

Python 오류(이를 트레이스백 traceback이라 부릅니다)의 전형적인 모습입니다.

Traceback (most recent call last):
  File "app.py", line 5, in <module>
    data = load_file("manual.pdf")
  File "app.py", line 2, in load_file
    return open(path).read()
FileNotFoundError: [Errno 2] No such file or directory: 'manual.pdf'

이걸 읽는 순서:

flowchart TB
    A["오류 발생"] --> B["맨 아래 줄을 먼저 읽는다<br/>= 오류의 '종류'와 '한 줄 설명'"]
    B --> C["그 위를 본다<br/>= '어느 파일 몇 번째 줄'에서 났는지"]
    C --> D{"무슨 뜻인지<br/>알겠나?"}
    D -->|예| E["해당 줄을 고친다"]
    D -->|아니오| F["오류 마지막 줄을<br/>그대로 검색"]

    classDef start fill:#FFF3B0,stroke:#C9A227,color:#000
    classDef read fill:#CDE7FF,stroke:#3B82C4,color:#000
    classDef good fill:#D7F2C8,stroke:#5BA63B,color:#000

    class A start
    class B,C,D,F read
    class E good

위 예에서 맨 아래 줄이 핵심입니다: FileNotFoundError ... No such file or directory: 'manual.pdf'. 해석하면 "manual.pdf라는 파일을 못 찾았다." 그 위 두 줄은 "app.py의 5번째 줄 → 2번째 줄에서 그 일이 났다"는 위치 안내입니다.

그리고 2부를 떠올리면 원인이 보입니다 — 이건 십중팔구 cwd(현재 위치)가 그 파일이 있는 폴더가 아니라서 상대경로로 못 찾은 것입니다. pwd와 ls로 확인하면 됩니다. 오류 메시지 + 앞 챕터 개념 = 해결.

콜아웃 · 오류 메시지를 "번역"하는 습관
영어 오류가 부담스러우면, 마지막 줄을 그대로 복사해 번역기나 검색에 넣으세요. 오류의 종류 이름(FileNotFoundError, ModuleNotFoundError, SyntaxError 등)은 거의 사람 말에 가깝게 지어져 있어, 이름만 읽어도 절반은 짐작됩니다.

한 번 끝까지 따라가 보기 (실전 디버깅)

오류 하나를 처음부터 끝까지 추적해 봅시다. RAG 첫 실습에서 흔히 나오는 상황입니다.

(.venv) PS C:\Users\me\rag-project> python app.py
Traceback (most recent call last):
  File "app.py", line 1, in <module>
    import requests
ModuleNotFoundError: No module named 'requests'

마지막 줄을 읽습니다: ModuleNotFoundError: No module named 'requests'. 4.3에서 본 그 오류 — "requests를 못 불러옴"입니다. 원인 후보는 둘: ① 아직 설치를 안 했거나, ② 가상환경이 엉뚱하거나. 프롬프트에 (.venv)가 보이니 환경은 켜져 있습니다. 그럼 ①이 유력합니다. 확인하고 고칩니다.

(.venv) PS C:\Users\me\rag-project> pip list        # requests가 목록에 없음을 확인
(.venv) PS C:\Users\me\rag-project> pip install requests
(.venv) PS C:\Users\me\rag-project> python app.py    # 다시 실행

이번엔 다른 오류가 납니다.

FileNotFoundError: [Errno 2] No such file or directory: 'data/manual.pdf'

오류가 "바뀌었다"는 건 앞 문제는 풀렸다는 신호입니다(좋은 진전!). 새 마지막 줄은 2.3의 그 문제 — 파일을 못 찾음. cwd부터 확인합니다.

(.venv) PS C:\Users\me\rag-project> pwd          # 지금 어디?
(.venv) PS C:\Users\me\rag-project> ls data      # data 폴더에 manual.pdf가 정말 있나?

ls data에 manual.pdf가 안 보이면 파일을 그 위치에 넣으면 되고, 이름이 Manual.PDF처럼 대소문자가 다르면 2.7대로 맞추면 됩니다. 이렇게 "마지막 줄 읽기 → 원인 후보 → 확인 → 고치기 → 다시 실행"을 오류가 사라질 때까지 반복하는 게 디버깅의 전부입니다.

flowchart LR
    A["실행"] --> B{"오류?"}
    B -->|"있음"| C["마지막 줄 읽기"]
    C --> D["원인 후보 확인<br/>(pwd·ls·pip list 등)"]
    D --> E["한 가지 고치기"]
    E --> A
    B -->|"없음 / 오류가 바뀜"| F["진전! 계속"]

    classDef step fill:#CDE7FF,stroke:#3B82C4,color:#000
    classDef good fill:#D7F2C8,stroke:#5BA63B,color:#000
    classDef q fill:#FFF3B0,stroke:#C9A227,color:#000
    class A,C,D,E step
    class B q
    class F good

핵심 습관 · 한 번에 하나씩만 바꾼다. 막히면 이것저것 동시에 손대고 싶어지지만, 그러면 무엇이 문제를 풀었는지(또는 새로 망가뜨렸는지) 알 수 없게 됩니다. 한 가지를 바꾸고 → 다시 실행해 확인하고 → 다음으로. 오류가 "바뀌는 것"도 진전이라는 걸 기억하세요.

6.2 흔한 오류 5종과 그 뜻

입문 단계에서 만나는 오류의 대부분은 아래 다섯 가지입니다. 각각이 "어느 층(1부)의 문제인지"를 함께 적었습니다.

특히 ModuleNotFoundError는 입문자가 거의 반드시 겪습니다. 원인 1순위는 가상환경을 안 켠 것((.venv)가 프롬프트에 없음), 2순위는 그 패키지를 아직 pip install 안 한 것입니다. 둘 다 5부 내용입니다. SyntaxError·IndentationError는 4.4의 들여쓰기·괄호 문제일 때가 많습니다.

6.3 print로 디버깅하기 — 가장 쉽고 강력한 도구

오류 메시지조차 안 나는데 결과가 이상할 때가 있습니다("답이 비어 있어요", "엉뚱한 게 나와요"). 이럴 때 입문자에게 가장 강력한 무기는 거창한 도구가 아니라 print로 중간 값을 찍어보는 것입니다. "지금 이 변수에 뭐가 들었지?"를 눈으로 확인하는 거죠.

docs = load_documents("data/")
print("불러온 문서 수:", len(docs))      # ← 진짜로 읽혔나?
print("첫 문서 앞부분:", docs[0][:100])  # ← 내용이 멀쩡한가?

chunks = split_into_chunks(docs)
print("청크 수:", len(chunks))           # ← 청킹이 됐나?

요령은 의심 가는 단계마다 값을 찍어, 어디서부터 어긋나는지 범위를 좁히는 것입니다. 예를 들어 "문서 수: 0"이 나오면 문제는 청킹·검색이 아니라 읽기 단계(1.7의 첫 동작)에 있는 겁니다 — 십중팔구 2.3의 경로 문제죠. 이렇게 "문제가 일어나는 가장 이른 지점"을 찾으면 고치기가 쉬워집니다.

flowchart LR
    A["읽기<br/>print(문서 수)"] --> B["청킹<br/>print(청크 수)"]
    B --> C["검색<br/>print(찾은 결과)"]
    C --> D["생성<br/>print(최종 답)"]

    A -.->|"0이면<br/>여기가 범인"| X["읽기/경로 문제"]
    B -.->|"이상하면"| Y["청킹 문제"]

    classDef step fill:#CDE7FF,stroke:#3B82C4,color:#000
    classDef bad fill:#FAD4D4,stroke:#C0392B,color:#000
    class A,B,C,D step
    class X,Y bad

다 고친 뒤에는 디버깅용 print를 지우거나 주석 처리하면 깔끔합니다. 나중에는 logging 같은 더 정돈된 방법을 쓰지만, 입문 단계에서는 print만으로 충분히 멀리 갈 수 있습니다.

6.4 똑똑하게 검색하는 법

막혔을 때 검색은 부끄러운 게 아니라 핵심 기술입니다. 잘 검색하는 요령:

오류 메시지를 그대로 붙여넣되, 내 개인 정보는 지웁니다. FileNotFoundError: 'C:\Users\홍길동\...'에서 홍길동 같은 내 경로·이름은 빼고 오류 종류와 일반적인 부분만 검색합니다. 예: python FileNotFoundError No such file or directory + 상황 키워드.

핵심 단어만 넣습니다. 문장 전체보다 "오류 종류 + 도구 이름 + 상황"이 잘 걸립니다. 예: ModuleNotFoundError requests venv windows.

최신 정보를 확인합니다. 도구·버전은 빠르게 바뀝니다. 너무 오래된 글의 해결책은 안 맞을 수 있으니, 가능하면 최근 글이나 공식 문서를 우선합니다.

공식 문서를 두려워하지 않습니다. Python·VS Code·각 패키지의 공식 문서가 가장 정확합니다. 처음엔 어렵게 느껴져도, 검색 결과 중 공식 사이트(예: docs.python.org)를 클릭하는 습관을 들이세요.

콜아웃 · AI에게 물을 때의 요령
Claude 같은 AI에게 물을 때도 같은 원칙입니다. ① 오류 메시지 전체를 그대로 붙여넣고(마지막 줄이 특히 중요), ② 무엇을 하려다 그랬는지(어떤 명령을 어떤 폴더에서 실행했는지), ③ OS와 도구 버전을 함께 알려주면 훨씬 정확한 답을 받습니다. "안 돼요"보다 "이 명령을 이 폴더에서 쳤더니 이 오류가 났어요"가 백배 낫습니다.

질문을 잘 만들기 어렵다면, 아래 틀을 복사해 빈칸만 채워도 좋습니다.

[하려던 일] RAG 실습에서 문서를 읽어 출력하려고 했습니다.
[실행한 것] rag-project 폴더에서 `python app.py`를 실행했습니다.
[기대한 결과] 문서 내용이 출력되길 기대했습니다.
[실제 결과/오류] 아래 오류가 났습니다:
ModuleNotFoundError: No module named 'requests'
[환경] Windows 11, Python 3.14, 가상환경(.venv) 활성화 상태입니다.
[이미 해본 것] pip list로 봤더니 requests가 목록에 없었습니다.

이 여섯 줄만 채워도, 검색이든 AI든 사람이든 훨씬 정확한 도움을 받습니다. "무엇을 / 어떻게 / 무엇을 기대했고 / 무엇이 났는지"를 분리해 적는 습관 자체가 디버깅 실력입니다.

6.5 입문자 함정 카탈로그

지금까지 챕터 곳곳에서 경고한 함정을 한곳에 모았습니다. 막히면 이 표부터 훑어보세요. 대부분 여기에 답이 있습니다.

6.6 막혔을 때의 전체 흐름

마지막으로, 무엇이든 막혔을 때 따라갈 한 장의 흐름도입니다. 인쇄해 책상에 붙여둬도 좋습니다.

flowchart TB
    A["막혔다 / 오류가 났다"] --> B["오류 마지막 줄을 읽는다"]
    B --> C{"6.5 함정 표에<br/>있는 증상인가?"}
    C -->|예| D["표의 처방대로 해결"]
    C -->|아니오| E{"위치·환경이<br/>맞나?"}
    E -->|확인| F["pwd / ls / (.venv) 확인"]
    F --> G{"그래도 안 되면"}
    E -->|모르겠음| F
    G --> H["오류 마지막 줄 +<br/>상황을 검색하거나 AI에 질문"]
    H --> I["공식 문서·최신 글 우선 확인"]
    D --> Z["해결 → 다시 진행"]
    I --> Z

    classDef start fill:#FFF3B0,stroke:#C9A227,color:#000
    classDef step fill:#CDE7FF,stroke:#3B82C4,color:#000
    classDef good fill:#D7F2C8,stroke:#5BA63B,color:#000

    class A start
    class B,C,E,F,G,H,I step
    class D,Z good

마음가짐 하나

막히는 것 자체에 좌절하지 마세요. 환경 설정과 오류는 모든 개발자가 거쳐 가는 길이고, 한 번 손에 익으면 점점 빨라집니다. 처음엔 한 줄 오류에 30분이 걸려도, 곧 같은 오류를 5초 만에 알아보게 됩니다. 이 0번 챕터에서 쌓은 감각 — 층으로 생각하기, 경로 확인하기, 가상환경 켜기, 오류 마지막 줄 읽기 — 은 RAG 안내서뿐 아니라 앞으로의 모든 개발에 그대로 쓰입니다.

이 챕터 한 줄 정리

오류는 안내문이니 마지막 줄부터 읽고, 6.5 함정 표를 먼저 확인하고, 안 되면 오류 + 상황을 검색하거나 AI에 물어라 — 막힘은 실패가 아니라 개발의 기본값이다.

0번 챕터를 마치며

이제 다음 문장이 더 이상 막막하지 않을 것입니다.

터미널을 열고, 프로젝트 폴더로 이동한 뒤,
가상환경을 켜고, 필요한 패키지를 설치하고, 코드를 실행한다.

각 단어가 어느 챕터의 어떤 개념인지 짚어볼까요 — 터미널(3부), 폴더 이동(2부), 가상환경·패키지(5부), 코드 실행(4부). 그리고 무엇이 잘못되든 6부가 빠져나오는 길을 알려줍니다.

이제 RAG 안내서로 넘어갈 준비가 됐습니다. 그 가이드의 첫 줄에서 더는 멈추지 않을 것입니다.

← 이전: 개발 도구 세팅 · 목차