BasicLike

12강. Obsidian, Git 사용

BasicLike — Wed, 29 Jul 2026 03:33:21 +0900

12강 구현 중심 ⏱ 약 80분

0. 학습 목표

→ study-notes 폴더를 Git 저장소로 만들고 Obsidian 안에서 커밋을 남깁니다.

0.1 이번 글에서 다룰 내용

10강에서는 사본 저장의 불편을 확인하고, Git이 저장 시점을 기록하는 방식으로 이 불편을 처리한다는 점을 구분했습니다.

11강에서는 GitHub 계정과 토큰을 만들고 Obsidian에 Git 플러그인을 설치했습니다.

이번 12강은 내 컴퓨터 안에서 커밋을 쌓는 부분까지입니다.

study-notes 폴더를 실제로 Git 저장소로 만들고, 학습 기록을 커밋 단위로 남깁니다.

GitHub에 올리는 작업은 13강에서 합니다.

핵심: 되돌리기는 아직 커밋하지 않은 변경에만 적용되므로, 소스 제어 화면의 변경 목록이 판단 기준입니다.

0.2 이번 강의 실습 내용

작업은 모두 Obsidian 창을 벗어나지 않고 저장소 초기화, 커밋, 되돌리기를 모두 수행할 수 있습니다.

다음 직접 실습합니다.

① 저장소 초기화하기
→ ② 사용자 정보 등록과, 커밋 제외 파일 지정하기
→ ③ 소스 제어 화면에서 커밋 만들기
→ ④ 히스토리 화면에서 커밋 이력 확인하기
→ ⑤ 커밋하지 않은 변경 되돌리기
→ ⑤ 커밋한 이력도 되돌려 봅니다.

준비물은 두 가지입니다.

11강을 마친 상태. 플러그인 Git이 설치되어 있고 켜져 있어야 합니다
학습 단위 1에서 만들어 온 study-notes 폴더를 Vault로 연 Obsidian

1. Git 저장소를 만들기

→ Vault를 Git 저장소로 초기화합니다.

1.1 (study-notes 폴더에서) Git 저장소로 초기화하기

화면 캡처: 명령 팔레트에서 Git을 입력해 Initialize a new repo 항목이 표시된 화면]

Obsidian에서 Ctrl+P를 눌러 명령 팔레트(Command palette)를 열고 Git을 입력하면 이 플러그인의 명령만 걸러집니다. 목록에서 새 저장소를 만드는 항목(Initialize a new repo)을 고릅니다.

Initialized new repo 알림이 표시되면 성공입니다.

지금 Vault로 열어 둔 study-notes 폴더 안에 .git 폴더가 만들어졌고, 앞으로의 모든 커밋이 여기에 저장됩니다.

.git 폴더는 이름이 마침표로 시작해 Obsidian 화면에는 보이지 않습니다.

⚠ 주의: 이 명령은 지금 열려 있는 Vault 폴더를 대상으로 동작합니다. 다른 폴더를 Vault로 열어 두었다면 그 폴더가 저장소가 되므로, 실행 전에 Obsidian 창 왼쪽 아래에 표시된 Vault 이름이 study-notes인지 확인하세요.

이 단계에서 나올 수 있는 증상은 두 가지입니다.

증상	원인	해결 방법
Git을 찾을 수 없다는 메시지가 나온다	실습 PC에 Git이 없거나, Obsidian이 Snap으로 설치되어 Git을 실행할 수 없음	강사에게 알린다. 설치 방식과 Git 설치 상태를 함께 확인한다
저장소가 아니라는 메시지가 나온다	저장소 초기화를 하지 않았거나, 다른 폴더를 Vault로 열었음	Vault 이름이 `study-notes`인지 확인하고 저장소 초기화 항목을 실행한다

2. 사용자 정보, 커밋 제외 파일 등록

→ Git 사용자 정보를 등록하고, Git 커밋에 제외할 폴더를 지정합니다.

2.1 (플러그인 설정에서) Git 사용자 이름과 이메일 등록하기

Git은 커밋을 만들 때 사용자 이름과 이메일을 함께 기록합니다.

이 두 값은 Git의 user.name과 user.email 설정에서 가져옵니다.

11강에서 설정 화면을 열었을 때는 이 항목이 없었습니다. 이 플러그인의 값은 Vault 가 Git 저장소일 때만 저장소에 관계된 설정 항목을 표시하기 때문입니다. 앞 절에서 저장소를 만들었으므로 이제 화면에 나타납니다.

▶ 지금 해보세요

[설정](Settings) → 왼쪽 목록 아래쪽의 [Git]으로 이동합니다.
Commit author 절의 Author name for commit에 이름을 입력합니다.
Author email for commit에 11강에서 GitHub 가입에 사용한 이메일 주소를 입력합니다.

두 값을 GitHub 계정 정보와 같게 맞추면, 나중에 저장소 페이지에서 커밋을 볼 때 본인 계정이 만든 커밋으로 표시됩니다. 등록한 값이 실제로 커밋에 들어가는지는 오늘 첫 커밋을 만든 뒤 히스토리 화면의 작성자 이름으로 확인합니다.

여기 입력한 이메일 주소는 커밋에 그대로 기록되고, 저장소를 공개하면 다른 사람도 볼 수 있습니다.

공개하고 싶지 않은 주소라면 GitHub이 제공하는 공개용 대체 주소를 사용할 수 있습니다. GitHub의 [Settings] → [Emails] 화면에서 Keep my email addresses private 항목을 켜면 숫자+사용자이름@users.noreply.github.com 형식의 주소가 표시되고, 이 주소를 대신 입력하면 됩니다.

2.2 커밋 대상에서 제외할 파일 지정하기

Obsidian은 Vault 안에 .obsidian이라는 설정 폴더를 만듭니다. 여기에는 화면 배치, 설치한 플러그인, 플러그인이 만든 파일이 들어 있습니다.

학습 기록이 아니고 웹에 공개할 내용도 아니므로 커밋 대상에서 제외합니다.

명령 팔레트에서 제외 목록을 편집하는 항목(Edit .gitignore)을 고릅니다. 편집 창이 열리면 다음 한 줄을 입력하고 저장합니다.

.obsidian/

.gitignore는 Git에게 관리 대상에서 제외할 파일과 폴더를 알려 주는 파일입니다.

폴더 이름 뒤의 /는 그 폴더 전체를 제외한다는 뜻입니다.

이 파일 자체는 제외 대상이 아니므로 커밋에 포함됩니다.

지금까지 만든 저장소 상태

study-notes/
├── .git/              #   1.1에서 저장소 초기화
├── .gitignore         # ✏️ 이번 절에서 제외 목록 작성
├── notes/             #   학습 단위 1에서 작성한 노트
├── lectures/          #   배부받은 강의 요약본
└── .obsidian/         # X 제외 대상. 커밋에 포함하지 않음

⚠ 주의: 제외 목록은 커밋을 만들기 전에 지정해야 합니다. .obsidian 폴더를 이미 커밋한 뒤에 제외 목록에 넣으면 커밋 이력에는 그대로 남습니다.

3. 소스 제어 화면에서 커밋 만들기

→ 바뀐 파일과 변경된 줄을 확인하고 커밋 2개를 만듭니다.

3.1 소스 제어 화면 열고 변경 목록 확인하기

명령 팔레트에서 소스 제어 화면을 여는 항목(Open source control view)을 고릅니다.

오른쪽 사이드바에 화면이 열립니다.

[화면 캡처: 오른쪽 사이드바에 열린 소스 제어 화면의 Changes 목록]

Changes 목록에 지금까지 작성한 노트 파일과 방금 만든 .gitignore가 표시됩니다.

아직 커밋한 적이 없으므로 모든 파일이 변경 목록에 올라옵니다.

.obsidian 폴더의 파일은 목록에 없어야 정상입니다.

있다면 제외 목록이 저장되지 않은 것이므로 1.3을 다시 수행하세요.

3.2 첫 커밋 만들기

지금까지 작성한 노트 전체를 첫 커밋으로 남깁니다.

▶ 지금 해보세요

목록 위쪽 도구 모음에서 모든 변경을 커밋 대상으로 선택하는 항목(Stage all)을 누릅니다. 파일이 Staged Changes 목록으로 옮겨집니다.
커밋 메시지 입력란(Commit Message)에 학습 기록 시작을 입력합니다.
커밋하는 항목(Commit)을 누릅니다.

커밋이 끝나면 목록이 비워집니다. 마지막 커밋과 지금 폴더의 내용이 같아졌다는 뜻입니다.

커밋 메시지에는 이 시점에서 무엇을 했는지 적습니다. 10강에서 확인한 대로 되돌아갈 지점은 각 커밋에 붙여 둔 이 설명을 보고 고릅니다.

참고: 도구 모음에는 Commit-and-sync 항목도 있습니다. 이것은 선택, 커밋, 내려받기, 올리기를 한 번에 실행하는 항목입니다. 지금은 올릴 원격 저장소가 없고 단계를 구분해 확인해야 하므로 누르지 않습니다. 이 항목은 13강에서 다시 설명합니다.

이 단계에서 나올 수 있는 증상은 세 가지입니다.

증상	원인	해결 방법
설정 화면에 `Commit author` 절이 보이지 않는다	저장소를 만들기 전에 설정 화면을 열었음	저장소 초기화를 먼저 실행한 뒤 설정 화면을 다시 연다
커밋할 때 작성자 정보가 없다는 메시지가 나온다	`Commit author` 설정이 비어 있음	설정 화면에서 이름과 이메일을 입력한 뒤 다시 커밋한다
Commit을 눌러도 아무 변화가 없다	선택된 변경이 없음	Stage all을 먼저 눌러 파일을 `Staged Changes` 목록으로 옮긴다
변경 목록에 `.obsidian` 폴더의 파일이 보인다	제외 목록이 저장되지 않음	Edit .gitignore를 다시 실행해 `.obsidian/` 한 줄이 있는지 확인한다

3.3 두 번째 커밋 만들고 변경된 줄 확인하기

이력이 쌓이는 것과 변경 내용을 확인하는 방법을 함께 봅니다.

Obsidian에서 notes 폴더의 study-log 노트를 열고 다음을 추가한 뒤 저장합니다.

### 12강. Git 저장소 시작

- study-notes 폴더를 Git 저장소로 만들고 커밋을 남기기 시작했다.

소스 제어 화면을 다시 봅니다. notes/study-log.md가 변경 목록에 나타납니다.

파일 이름을 눌러 보세요. 마지막 커밋과 비교한 결과가 표시되고, 방금 추가한 줄이 추가 표시로 구분됩니다.

커밋하기 전에 무엇이 바뀌었는지 이 화면에서 확인하면 커밋 메시지를 정확하게 적을 수 있습니다.

▶ 지금 해보세요

Stage all을 누릅니다.
커밋 메시지에 12강 학습일지 추가를 입력합니다.
Commit을 누릅니다.

지금까지 쌓인 커밋 상태

study-notes/
├── .git/                     #   커밋 2개 저장
│   ├── 학습 기록 시작         #   2.2에서 생성
│   └── 12강 학습일지 추가      # ✏️ 이번 절에서 생성
└── notes/study-log.md         #   두 번째 커밋에 반영

노트를 고쳤는데 변경 목록에 나오지 않으면 소스 제어 화면의 새로 고침 항목(Refresh)을 누릅니다.

4. 커밋 이력 확인하고 커밋하지 않은 변경 되돌리기

→ 히스토리 화면으로 이력을 확인하고 잘못 고친 노트를 되돌립니다.

4.1 히스토리 화면에서 커밋 이력 확인하기

명령 팔레트에서 이력 화면을 여는 항목(Open history view)을 고릅니다. 지금까지 만든 커밋이 최신 순으로 표시됩니다.

[화면 캡처: 히스토리 화면에 커밋 두 개가 최신 순으로 표시된 목록]

맨 위에 12강 학습일지 추가, 그 아래에 학습 기록 시작이 있습니다. 각 줄에는 커밋 메시지와 함께 작성자와 시각이 표시됩니다.

작성자 이름이 비어 있거나 다른 이름으로 보이면 1.2에서 입력한 설정 화면의 Commit author 값을 확인하세요.

커밋 하나를 누르면 그 커밋에서 바뀐 파일 목록이 나오고, 파일을 누르면 그 시점의 변경 내용을 볼 수 있습니다. 며칠 전 노트를 어떻게 고쳤는지 확인할 때 사용하는 화면입니다.

3.2 커밋하지 않은 변경 되돌리기

커밋을 만들어 두면 그 시점의 상태로 돌아갈 수 있습니다. 노트를 잘못 고쳤을 때 쓰는 절차를 직접 확인합니다.

▶ 지금 해보세요

Obsidian에서 study-log 노트를 열고, 방금 추가한 ### 12강. Git 저장소 시작 절을 통째로 지웁니다.
소스 제어 화면을 봅니다. notes/study-log.md가 다시 변경 목록에 나타납니다. 마지막 커밋 이후 이 파일이 바뀌었고 아직 커밋되지 않았다는 뜻입니다.
그 파일 줄에 마우스를 올리면 나타나는 되돌리기 항목(Discard)을 누릅니다.
되돌릴지 확인하는 창이 뜹니다. 대상 파일이 study-log.md 하나인지 확인하고 진행합니다.
Obsidian의 노트 화면을 다시 봅니다. 지웠던 절이 그대로 돌아와 있습니다.

Obsidian은 파일이 바뀌면 화면을 자동으로 갱신하므로 결과가 바로 보입니다.

되돌리기는 아직 커밋하지 않은 변경만 마지막 커밋 상태로 되돌립니다. 판단 기준은 소스 제어 화면입니다.

변경 목록에 올라와 있는 파일은 되돌릴 수 있고, 목록에 없는 내용은 이미 커밋된 것이므로 이 방법으로 되돌아가지 않습니다. 이미 커밋된 내용을 되돌리는 방법은 13강에서 다룹니다.

⚠ 주의: 되돌린 내용은 다시 살릴 수 없습니다. 커밋하지 않은 변경이므로 Git에 기록이 남아 있지 않기 때문입니다. 그래서 되돌리기 전에는 변경 목록에서 대상 파일을 먼저 확인해야 합니다. 명령 팔레트의 모든 변경을 한 번에 되돌리는 항목(CAUTION: Discard all changes)은 저장소 전체의 커밋하지 않은 변경이 사라지므로 이 과정에서는 사용하지 않습니다.

되돌리기를 했는데 지우려던 내용이 그대로 있으면, 그 내용이 이미 커밋되어 마지막 커밋에 포함되어 있는 것입니다. 이때는 노트를 직접 고친 뒤 새 커밋을 만듭니다. 절차는 13강에서 확인합니다.

4. 정리 노트를 커밋하고 13강으로 넘기기

→ 오늘 사용한 절차를 노트로 정리해 커밋하고 상태를 확인합니다.

4.1 절차를 정리한 노트 만들어 커밋하기

오늘 사용한 절차를 노트로 정리하고 커밋합니다. 다음 강의부터 이 절차를 반복해서 사용합니다.

▶ 지금 해보세요

notes 폴더에 git-setup이라는 노트를 만듭니다.
다섯 가지를 적습니다. 저장소를 초기화한 명령 이름, 커밋 작성자 정보를 등록한 설정 항목 이름, 커밋 대상에서 제외한 폴더와 그 이유, 커밋을 만드는 순서(Stage all → 커밋 메시지 입력 → Commit), 커밋하지 않은 변경을 되돌리는 방법과 되돌릴 수 없는 경우입니다.
소스 제어 화면에서 변경 목록에 이 노트만 있는지 확인합니다.
커밋 메시지를 Git 저장소 설정 정리 노트 추가로 적고 커밋합니다.

완료 기준은 세 가지입니다. 히스토리 화면 맨 위에 직접 적은 커밋 메시지가 있고, 그 아래에 오늘 만든 커밋 2개가 남아 있으며, 소스 제어 화면의 변경 목록이 비어 있으면 완료입니다.

4.2 저장소 상태를 확인하고 13강으로 넘기기

다음 여섯 가지가 모두 확인되면 오늘 실습이 끝난 것입니다.

확인 항목	기대 결과	확인 방법
저장소 초기화	소스 제어 화면에 변경 파일 목록이 표시됨	소스 제어 화면 확인
제외 설정	변경 목록과 커밋에 `.obsidian` 폴더의 파일이 없음	소스 제어 화면과 히스토리 화면 확인
커밋 이력	커밋 3개(학습 기록 시작, 12강 학습일지 추가, 과제 노트 추가)가 최신 순으로 표시됨	히스토리 화면 확인
작성자 정보	각 커밋에 본인 이름이 표시됨	히스토리 화면에서 커밋 확인
변경 내용 확인	파일 이름을 눌렀을 때 추가된 줄이 구분되어 표시됨	소스 제어 화면에서 파일 선택
되돌리기	되돌리기 실행 후 지운 절이 노트에 복구됨	되돌리기 절차 직후 노트 확인

학습 기록이 커밋 단위로 남기 시작했습니다. 다만 이 커밋은 아직 실습 PC 안에만 있어서, PC가 고장 나면 함께 사라지고 다른 사람에게 보여줄 수도 없습니다.

→ 다음 개별 강의

13강에서는 11강에서 만든 계정으로 GitHub에 공개 저장소를 만들고, 오늘 만든 커밋을 그 저장소로 올립니다. 이때 11강에서 발급한 토큰을 사용합니다. 원격 저장소에서 바뀐 내용을 내 컴퓨터로 내려받는 절차와, 이미 커밋된 내용을 되돌리는 방법도 함께 확인합니다.

11. Obsidian, Git 환경 설정

BasicLike — Wed, 29 Jul 2026 03:29:39 +0900

11강 구현 중심 ⏱ 약 60분

0. 학습 목표

→ 12강과 13강의 저장소 작업에 필요한 계정과 도구를 준비합니다.

0.1 이번 글에서 다룰 내용

10강에서는 Git과 GitHub의 역할을 알아봤습니다.

Git은 내 컴퓨터에서 커밋이라는 저장 시점을 쌓는 프로그램이고,
GitHub은 그 저장소를 인터넷에 보관하는 서비스입니다.

Git과 GitHub를 실제로 사용 구조는 다음과 같습니다.

오늘은 Obsidian 노트에서 Git 과 GitHub 를 사용하기 위한 환경 설정을 진행합니다.

준비 과정:

① 실습 PC에 Git 설치하고 설정하기
→ ② GitHub 계정 만들기
→ ③ 개인 접근 토큰 발급하기
→ ④ Obsidian Git 플러그인 설치하기
→ ⑤ 12강에서 저장소 만들기, 13강에서 GitHub에 올리기

Git 커밋에 기록할 사용자 이름(username)과 이메일(email)은 오늘 등록하지 않습니다.

저장소를 만드는 작업은 실제 사용이고, 환결 설정과 섞으면 어느 단계에서 막혔는지 구분하기 어렵습니다.

그래서 이번 강의는 준비(환경 설정)만 따로 다룹니다.

주의: 오늘 정한 GitHub 사용자 이름은 18강에서 만드는 공개 사이트 주소가 되므로 지금 신중하게 정합니다.

0.2 이번 강의 실습 내용

오늘은 첫 절에서만 쉘 프롬프트(참고 링크)를 사용합니다.

나머지 작업은 웹 브라우저와 Obsidian에서 진행하고, 쉘 프롬프트를 사용하지 않습니다.

다음 네 가지를 직접 수행합니다.

Git 을 설치하고, 기본 설정을 진행합니다.
- 기본 브랜치 이름 수정
- 인증 정보 저장 위치 설정
GitHub 계정 생성
GitHub 계정에서 개인 접근 토큰(Personal Access Token)을 발급
Obsidian Git 플러그인 설치

준비물은 세 가지입니다.

웹 브라우저
본인이 확인할 수 있는 이메일 주소. GitHub이 보내는 인증 코드를 받아야 합니다
실습 PC의 관리자 비밀번호. Git 설치에 필요합니다. 실습실 PC의 비밀번호는 강사가 안내합니다
학습 단위 1에서 만들어 온 study-notes 폴더를 Vault로 연 Obsidian

저장소를 만들고 커밋을 남기는 작업은 12강에서, 커밋을 GitHub에 올리는 작업은 13강에서 다룹니다. 오늘 발급한 토큰도 13강에서 처음 사용합니다.

1. Git 설치하고 실습 환경 설정하기

→ 실습 PC에 Git을 설치하고 브랜치 이름과 인증 저장 위치를 지정합니다.

1.1 설치 여부 확인하기

Obsidian Git 플러그인은 Git 기능을 자체적으로 갖고 있지 않습니다.

Ubuntu Desktop 에는 Git이 포함되어 있지 않으므로 먼저 설치합니다.

이 절은 오늘 유일하게 쉘 프롬프트를 사용하는 부분입니다.

쉘 프롬프트(단축키: Ctrl+Alt+T)를 열고 다음을 실행합니다.

쉘 프롬프트

# Git 설치 여부와 버전 확인
git --version

bash: /usr/bin/git: No such file or directory 형식으로 메시지가 나오면 다음 절차로 설치합니다.

(*버전이 표시되면 이미 설치된 것이므로 1.3으로 넘어갑니다.)

1.2 Git과 자격 증명 저장에 필요한 패키지 설치하기

쉘 프롬프트

# Git과 자격 증명 저장에 필요한 패키지 설치
sudo apt update
sudo apt install build-essential libsecret-1-dev libglib2.0-dev -y
sudo apt install git libsecret-1-0 libsecret-1-dev make gcc

sudo는 관리자 권한으로 명령을 실행하라는 뜻입니다.

프로그램을 시스템에 설치하는 작업이므로 관리자 권한이 필요하고,

비밀번호를 입력할 때 화면에는 아무 글자도 표시되지 않습니다.

libsecret으로 시작하는 세 패키지는 뒤에서 발급할 개인 접근 토큰을 안전하게 보관하는 데 사용합니다. Ubuntu가 계정마다 관리하는 키링에 토큰을 저장해 두면, 13강부터 GitHub에 올릴 때 토큰을 다시 입력하지 않습니다.

쉘 프롬프트

# 자격 증명 도우미 프로그램 만들기
sudo make --directory=/usr/share/doc/git/contrib/credential/libsecret

실행하면 소스를 컴파일하는 줄이 여러 개 출력됩니다. 마지막 줄까지 오류 없이 끝나면 도우미 프로그램이 만들어진 것입니다. 아래 명령으로 만들어졌는지 파일로 확인합니다.

쉘 프롬프트

# 만들어진 자격 증명 도우미 파일 확인
ls /usr/share/doc/git/contrib/credential/libsecret/git-credential-libsecret

입력한 경로가 그대로 한 줄 출력되면 성공입니다.
여기서 확인한 경로를 1.4의 인증 정보 저장 위치 지정에 그대로 사용합니다.

(No such file or directory가 나오면 앞의 설치나 만들기 명령이 끝나지 않은 것이므로 두 명령을 다시 실행하고 화면에 표시된 오류 메시지를 확인하세요.)

1.3 새 저장소의 기본 브랜치 이름 지정하기

Git은 저장소를 만들 때 첫 브랜치의 이름을 정합니다. 지정하지 않으면 master라는 이름이 붙습니다.

쉘 프롬프트

# 새 저장소의 기본 브랜치 이름 지정
git config --global init.defaultBranch main

이 과정의 자료는 브랜치 이름이 main인 것을 전제로 작성되어 있습니다. 16강에서 Colab 노트북을 저장할 대상 브랜치와 18강에서 GitHub Pages 게시 브랜치를 고를 때 이 이름을 사용합니다.

--global은 지금 로그인한 계정에서 만드는 모든 저장소에 이 설정을 적용한다는 뜻입니다. 저장소마다 다시 지정하지 않아도 됩니다.

1.4 인증 정보를 저장할 위치 지정하기

앞에서 만든 자격 증명 도우미를 Git이 사용하도록 지정합니다.

쉘 프롬프트

# 인증 정보를 계정 키링에 저장하도록 지정
git config --global credential.helper \
   /usr/share/doc/git/contrib/credential/libsecret/git-credential-libsecret

이 설정이 없으면 GitHub에 올리고 내려받을 때마다 토큰을 다시 입력해야 합니다. 설정해 두면 처음 한 번만 입력하고, 이후에는 키링에 보관된 값을 Git이 가져다 씁니다.

⚠ 주의: 토큰을 파일에 그대로 적어 두는 방식도 있지만 이 과정에서는 사용하지 않습니다. 키링은 계정 암호로 보호되지만, 파일에 적어 두면 그 파일을 열어 볼 수 있는 사람이 토큰 값을 그대로 확인할 수 있기 때문입니다.

1.5 설정 결과 확인

설치와 설정이 잘 적용되었는지 확인합니다.

쉘 프롬프트

# 설치와 설정 결과 확인
git --version
git config --get init.defaultBranch
git config --get credential.helper

세 명령이 각각 Git 버전, main, 자격 증명 도우미의 경로를 출력하면 오늘 환경 설정이 끝난 것입니다.

이 설정은 지금 로그인한 계정에만 적용됩니다. 다른 PC나 다른 계정에서 실습할 때는 같은 절차를 다시 수행합니다.

1.6 Git 삭제하고 설정 되돌리기

지금은 수행하지 않습니다.

실습 PC를 반납하거나 이 환경을 정리해야 할 때 사용하는 절차이므로, 과정을 진행하는 동안에는 실행하지 마세요.

먼저 Obsidian을 종료합니다. 플러그인이 Git을 실행하고 있는 상태에서 제거하면 오류가 표시됩니다.

쉘 프롬프트

# 키링에 보관된 GitHub 자격 증명 삭제
printf "protocol=https\nhost=github.com\n\n" | git credential reject

쉘 프롬프트

# 계정에 지정한 Git 설정 삭제
git config --global --unset init.defaultBranch
git config --global --unset credential.helper

쉘 프롬프트

# 패키지 제거
sudo apt purge -y git libsecret-1-dev make gcc
sudo apt autoremove -y

순서를 지켜야 합니다. 자격 증명 삭제와 설정 삭제는 Git이 있어야 실행되므로 패키지 제거보다 먼저 합니다. Git 패키지를 제거하면 앞에서 만든 자격 증명 도우미 파일도 함께 지워집니다.

⚠ 주의: libsecret-1-0은 제거 목록에 넣지 않습니다. 이 패키지는 Ubuntu의 다른 프로그램들이 함께 사용하는 라이브러리여서, 지우면 바탕 화면 환경의 다른 기능이 동작하지 않을 수 있습니다. 우리가 추가로 설치한 것은 개발용 파일(libsecret-1-dev)과 빌드 도구(make, gcc)이므로 그 세 가지만 제거합니다.

이 절차는 study-notes 폴더의 노트와 커밋 이력을 지우지 않습니다. 폴더와 그 안의 .git 폴더는 그대로 남고, Git 프로그램만 없어져 이력을 다룰 수 없는 상태가 됩니다.

기록까지 없애려면 폴더를 따로 삭제해야 합니다. 자격 증명을 지운 뒤 다시 사용할 때는 첫 올리기에서 토큰을 다시 입력합니다. GitHub에 발급해 둔 개인 접근 토큰은 이 절차로 없어지지 않으므로, 더 이상 사용하지 않는다면 GitHub의 토큰 화면에서 폐기합니다.

이 단계에서 나올 수 있는 증상은 세 가지입니다.

증상	원인	해결 방법
`git: command not found`	설치가 끝나지 않았거나 오류로 중단됨	설치 명령을 다시 실행하고 화면에 표시된 오류 메시지를 확인한다
`sudo` 명령에서 비밀번호를 입력해도 진행되지 않는다	관리자 권한이 없는 계정으로 로그인함	강사에게 알린다
`git: 'credential-libsecret' is not a git command`	자격 증명 도우미를 만드는 명령을 실행하지 않음	1.2의 마지막 명령을 다시 실행한다

2. GitHub 계정 만들기

→ 가입 절차를 수행하고 공개 주소가 되는 사용자 이름을 판단해 정합니다.

2.1 가입 절차 수행하기

10강에서 열어 본 공개 저장소 페이지와 같은 주소를 자기 계정 아래에 만들려면 GitHub 계정이 필요합니다.

(사용자 이름은 아래 2.2의 판단 기준을 먼저 읽고 정하세요.)

[화면 캡처: GitHub 첫 화면의 Sign up 버튼과 이메일 입력란]

▶ 지금 해보세요

브라우저에서 https://github.com을 열고 [Sign up]을 누릅니다.
이메일 주소를 입력합니다. 인증 코드를 받아야 하므로 지금 확인할 수 있는 주소를 씁니다.
비밀번호를 입력합니다.
사용자 이름(Username)을 입력합니다.
화면의 안내에 따라 사람 여부를 확인하는 절차를 수행합니다.
입력한 주소로 온 인증 코드를 입력해 가입을 마칩니다.

가입이 끝나면 오른쪽 위 프로필에서 [Your profile]을 눌러 https://github.com/사용자이름 주소가 열리는지 확인합니다. 이 주소가 앞으로 사용할 계정 주소입니다.

가입 과정이나 이후 로그인에서 2단계 인증(Two-factor authentication)을 설정하라는 안내가 표시될 수 있습니다. 설정하면 로그인할 때 휴대전화 인증이 추가되고, 오늘 발급하는 토큰 사용에는 영향을 주지 않습니다.

가입 과정에서 다음 두 가지가 자주 나타납니다.

증상	원인	해결 방법
가입 인증 코드가 오지 않는다	주소 오타 또는 메일이 스팸으로 분류됨	스팸함을 확인하고, 없으면 가입 화면에서 코드를 다시 요청한다
사용자 이름을 사용할 수 없다고 나온다	이미 사용 중인 이름임	다른 이름을 입력한다. 아래 세 가지 기준을 다시 확인한다

2.2 사용자 이름을 정하는 기준 판단하기

사용자 이름은 나중에 바꿀 수 있습니다.

다만 바꾸면 저장소 주소와 공개 사이트 주소가 함께 바뀌어 이미 공유한 주소가 동작하지 않습니다.

처음 정할 때 다음 세 가지를 확인하세요.

이 이름은 저장소 주소에 그대로 들어갑니다. 10강에서 본 twbs/bootstrap의 twbs 자리에 들어가는 이름입니다.
18강에서 만드는 공개 사이트의 주소가 사용자이름.github.io 형식이 됩니다. 이 주소는 19강에서 취업 준비 자료로 사용합니다.
이 이름은 누구나 볼 수 있습니다. 실명을 쓸지, 별도의 이름을 쓸지 지금 판단하세요. 생년월일이나 전화번호처럼 개인을 특정할 수 있는 정보는 넣지 않습니다.
[E] 깃허브 username, email 확인 방법

[E] 깃허브 username, email 확인 방법

basiclike.tistory.com

✔ 정리: 프로필 주소 https://github.com/사용자이름이 열리면 계정 준비가 끝난 것입니다.

3. GitHub 개인 접근 토큰 발급

→ 13강의 인증에 사용할 토큰을 발급하고 다루는 기준을 정합니다.

3.1 토큰과 계정 비밀번호의 용도 구분하기

Git 저장 정보를 GitHub에 올리려면 본인 계정임을 확인하는 인증이 필요합니다.

이때 GitHub 계정 비밀번호 대신 Personal Access Token 이라는 별도의 값을 사용합니다.

두 값의 차이를 먼저 구분해 두세요.

GitHub 계정 비밀번호는
>> 웹 사이트에 로그인할 때 사용하고, 사람이 직접 입력합니다.
토큰은
>> Git과 같은 프로그램이 GitHub에 접속할 때 사용합니다.
>> 허용할 작업 범위와 사용 기간을 정해서 발급합니다.

그래서 토큰이 유출되어도 정한 범위 안의 작업만 가능합니다.

해당 토큰만 폐기하면 계정 비밀번호는 그대로 사용할 수 있습니다.

3.2 GitHub 토큰 발급하기

▶ 지금 해보세요

GitHub 오른쪽 위 프로필 → [Settings] → 왼쪽 맨 아래 [Developer settings]로 이동합니다.
[Personal access tokens] → [Tokens (classic)] → [Generate new token] → [Generate new token (classic)]을 선택합니다.
[Note]에 study-notes-pc를 입력합니다. 이 토큰을 어디에 쓰는지 나중에 구분하기 위한 이름입니다.
[Expiration]은 90 days를 선택합니다. 사용 기간이 지나면 자동으로 사용할 수 없게 됩니다.
권한 목록에서 [repo]에 체크합니다. 저장소를 읽고 쓰는 작업에 필요한 범위입니다. 다른 항목은 선택하지 않습니다.
[Generate token]을 누릅니다.

ghp_로 시작하는 토큰이 화면에 한 번만 표시됩니다. 지금 복사해서 본인만 볼 수 있는 곳에 보관하세요.

화면을 벗어나면 다시 볼 수 없고, 잃어버리면 새로 발급해야 합니다.

발급 화면에서 다음 두 가지가 자주 나타납니다.

증상	원인	해결 방법
토큰 값을 복사하지 못하고 화면을 벗어났다	토큰은 한 번만 표시됨	같은 절차로 새 토큰을 발급한다. 사용하지 않는 이전 토큰은 폐기한다
권한 항목에 [repo]가 보이지 않는다	세분화된 토큰(Fine-grained tokens) 화면임	[Tokens (classic)] 화면인지 확인하고, 아니면 그 화면으로 이동해 다시 발급한다

3.3 토큰 주의점

토큰은 비밀번호와 같은 값입니다. 학습 노트, 저장소, 화면 공유 화면처럼 다른 사람이 볼 수 있는 곳에 적지 마세요.

이 과정에서 만드는 study-notes 저장소는 공개 저장소입니다. 노트에 적어 커밋하면 인터넷에 그대로 공개됩니다.

⚠ 주의: 실수로 노출했거나 과정이 끝나 더 이상 사용하지 않을 때는 발급 화면에서 해당 토큰을 [Delete]로 폐기합니다. 폐기한 토큰은 즉시 사용할 수 없게 되므로, 노출된 토큰을 그대로 두는 것보다 안전합니다. 폐기해도 계정과 저장소는 그대로 남습니다.

90일이 지나 토큰을 사용할 수 없게 되면 같은 절차로 새로 발급합니다. 다음에 올릴 때 새 토큰을 입력하면 됩니다.

4. Obsidian Git 플러그인 설치하고 동작 확인하기

→ 12강부터 사용할 플러그인을 설치하고 Git을 실행할 수 있는지 확인합니다.

4.1 커뮤니티 플러그인 Git 설치하기

12강부터 저장소 작업은 Obsidian 안에서 합니다. 이때 사용하는 것이 커뮤니티 플러그인 Git입니다.

이 플러그인은 실습 PC에 설치된 Git을 실행하고 그 결과를 Obsidian 화면에 표시합니다. Git을 새로 설치하는 것이 아니라, 이미 설치된 Git에 Obsidian 화면을 붙이는 것입니다.

[화면 캡처: 커뮤니티 플러그인 탐색 화면에서 Git을 검색해 제작자 Vinzent03을 확인한 목록]

▶ 지금 해보세요

Obsidian에서 [설정](Settings) → [커뮤니티 플러그인](Community plugins)으로 이동합니다.
[탐색](Browse)을 눌러 플러그인 목록을 엽니다.
검색창에 Git을 입력합니다. 제작자가 Vinzent03인 항목을 고릅니다. 이름이 짧아 비슷한 이름이 여럿 나오므로 제작자 이름으로 확인하세요.
[설치](Install)를 누르고, 설치가 끝나면 [사용](Enable)을 눌러 켭니다.

1강에서 확인한 대로 커뮤니티 플러그인은 개인이 만들어 공개한 것입니다. 설치하면 그 코드가 내 Vault 폴더 안에서 실행되므로, 설치 전에 이름과 제작자를 확인하는 절차를 여기서도 그대로 적용합니다.

4.2 설정 화면에서 지금 보이는 항목 확인하기

[설정](Settings) → 왼쪽 목록 아래쪽의 [Git]으로 이동합니다. 설정 화면이 열리고 Advanced 절의 항목들이 표시됩니다. Git 실행 파일 경로나 환경 변수를 지정하는 항목들입니다.

커밋 작성자 이름과 이메일을 입력하는 Commit author 절은 지금 화면에 없습니다. 이 플러그인은 Vault가 Git 저장소일 때만 저장소에 관계된 설정 항목을 표시하는데, 아직 저장소를 만들지 않았기 때문입니다.

12강에서 저장소를 만들고 나면 같은 화면에 그 절이 나타납니다. 이 화면에서 지금 바꿀 항목은 없습니다. 오늘은 설정 화면의 위치만 확인해 두면 됩니다.

참고: 이 설정 화면에 사용자 이름과 개인 접근 토큰을 입력하는 인증 항목이 보이는 경우가 있습니다. 이 항목은 모바일 앱에서 사용하는 값이고, 실습 PC와 같은 데스크톱에서는 인증에 사용되지 않습니다. 오늘 발급한 토큰은 여기 입력하지 않습니다. 데스크톱에서 토큰을 사용하는 방법은 13강에서 다룹니다.

4.3 플러그인 동작을 확인하고 제거 방법 알아 두기

4.3.1. 플러그인이 Git을 실행할 수 있는지 확인하기

Ctrl+P를 눌러 명령 팔레트(Command palette)를 열고 Git을 입력합니다. 이 플러그인의 명령 목록이 나타나면 플러그인이 켜진 것입니다.

목록에서 소스 제어 화면을 여는 항목(Open source control view)을 고릅니다.

오른쪽 사이드바에 화면이 열리고, 아직 저장소를 만들지 않았으므로 저장소가 아니라는 안내가 표시됩니다. 이 안내가 나오는 것이 정상입니다. 저장소 만들기는 12강에서 합니다.

지금까지 만든 준비 상태

GitHub 계정                     #   2절에서 생성
└── 개인 접근 토큰               #   3절에서 발급

study-notes/                     #   학습 단위 1에서 사용 중인 Vault
├── .obsidian/plugins/            # ✏️ 이번 절에서 Git 플러그인 설치
└── .git/                         # X 12강에서 저장소 초기화

이 단계에서 나올 수 있는 증상은 두 가지입니다.

증상	원인	해결 방법
명령 팔레트에 `Git` 명령이 없다	플러그인을 설치만 하고 켜지 않음	[커뮤니티 플러그인] 목록에서 `Git`이 켜져 있는지 확인한다
Git을 찾을 수 없다는 메시지가 나온다	1절의 설치가 끝나지 않았거나, Obsidian이 Snap으로 설치되어 Git을 실행할 수 없음	쉘 프롬프트에서 `git --version`으로 설치를 확인하고, 설치되어 있는데도 같은 메시지가 나오면 강사에게 알린다

✔ 정리: 명령 팔레트에서 Git 명령이 검색되고 소스 제어 화면이 열리면 12강 실습을 시작할 수 있는 상태입니다.

4.3.2. 설치한 플러그인 제거하기

이 절차도 지금은 수행하지 않습니다. 실습 환경을 정리할 때 사용합니다.

[설정](Settings) → [커뮤니티 플러그인](Community plugins) 목록에서 Git을 찾아 제거 항목을 누릅니다. 제거하면 Vault 안의 .obsidian/plugins/obsidian-git 폴더와 그 안에 저장된 플러그인 설정이 함께 지워집니다.

저장소와 커밋 이력은 .obsidian 폴더가 아니라 .git 폴더에 있으므로 플러그인을 제거해도 남습니다. 플러그인을 다시 설치하면 같은 저장소를 그대로 다룰 수 있습니다.

5. 계정 정보를 학습일지에 정리하고 12강으로 넘기기

→ 오늘 만든 계정 정보를 노트에 남기고 다음 강의에서 사용할 상태를 확인합니다.

5.1 학습일지에 계정 정보 정리하기

오늘 만든 계정 정보를 학습일지에 정리합니다.

▶ 지금 해보세요

Obsidian에서 notes 폴더의 study-log 노트를 엽니다.
### 11강. GitHub 계정 준비 절을 만들고 세 가지를 적습니다. 내 GitHub 계정 주소, 그 사용자 이름으로 18강에서 만들어질 공개 사이트 주소, 토큰의 이름과 만료 예정일입니다.
토큰 값 자체는 적지 않습니다. 이 노트는 13강에서 공개 저장소에 올라갑니다.

완료 기준은 두 가지입니다. study-log 노트에 세 항목이 적혀 있고, 그중 토큰 값이 포함되어 있지 않으면 완료입니다.

5.2 준비 상태를 확인하고 12강으로 넘기기

다음 여섯 가지가 모두 확인되면 오늘 준비가 끝난 것입니다.

확인 항목	기대 결과	확인 방법
Git 설치	`git --version`이 버전을 출력함	쉘 프롬프트에서 확인
환경 설정	`git config --get init.defaultBranch`가 `main`을 출력하고, `git config --get credential.helper`가 도우미 경로를 출력함	쉘 프롬프트에서 확인
계정 생성	`https://github.com/사용자이름` 주소로 프로필 페이지가 열림	브라우저에서 확인
토큰 발급	토큰 목록에 `study-notes-pc`가 있고 만료일이 표시됨	[Developer settings]의 토큰 목록 확인
토큰 보관	`ghp_`로 시작하는 값이 본인만 볼 수 있는 곳에 저장되어 있음	본인이 보관 위치 확인
플러그인 설치	명령 팔레트에서 `Git` 명령이 검색됨	`Ctrl+P`로 확인
플러그인 동작	소스 제어 화면이 열리고 저장소가 아니라는 안내가 표시됨	소스 제어 화면 확인

→ 다음 개별 강의

12강에서는 study-notes 폴더를 Git 저장소로 만들고, 저장소를 만든 뒤 화면에 나타나는 설정으로 커밋 작성자 이름과 이메일을 등록합니다. 이어서 Obsidian 화면 안에서 커밋을 남기고 잘못 고친 노트를 되돌립니다. 오늘 발급한 토큰은 13강에서 커밋을 GitHub에 올릴 때 사용합니다.

10. Git의 저장 방식과 GitHub의 공유 역할 구분하기

BasicLike — Wed, 29 Jul 2026 01:20:30 +0900

10강 결과 활용 ⏱ 약 20분

0. 학습 목표

→ 사본 저장의 불편을 직접 확인하고 Git과 GitHub의 역할을 구분합니다.

0.1 이번 글에서 다룰 내용

0.1.1. 문제점 확인

[학습 단위 1]에서 만든 노트는 실습 PC 한 대에만 저장되어 있습니다. 이 상태에서는 세 가지 문제가 생깁니다.

노트가 수정되면 이력이 남지 않아서, 지난 문서 내용을 되살릴 방법이 없습니다. (어제 지운 문장)
노트가 PC 한 곳에만 있어서, PC가 고장 나면 노트 전체를 잃어버리고,
다른 사람과 협업할 방법도 없습니다.

0.1.2. 해결책 살펴보기

개발 현장에서는 이 세 가지 문제를 Git과 GitHub이라는 두 도구로 해결합니다.

Git은 [1] 내 컴퓨터에 설치해서 사용하는 프로그램이고,
GitHub은 [2] 인터넷을 통해 이용하는 서비스입니다.

0.1.3. 최종 목표

복잡한 소프트웨어 개발에 Git과 GitHub 를 사용하기 전에,

이 과정에서는 Obsidian 학습 노트라는 간단한 프로그램을 연습 대상으로 Git, GitHub에서 자주 쓰는 기능 일부에만 먼저 익숙해지는 것을 목표로 합니다.

① 사본 파일로 저장하는 방식에서 불편 확인하기
→ ② Git이 저장 시점을 기록으로 남기는 방식 확인하기
→ ③ GitHub이 저장소를 인터넷에 보관하는 방식 확인하기
→ ④ 내 학습 기록을 공개할 때 지울 내용 판단하기

Obsidian 노트에서 익힌 Git과 GitHub 사용법을 나중에 소스코드를 관리로 자연스럽게 이어가시면 됩니다.

핵심: Git은 내 컴퓨터에서 저장 시점을 기록하는 프로그램이고, GitHub은 그 저장소를 인터넷에 보관하고 공유하는 서비스입니다.

0.2 이번 강의 실습 내용

오늘은 설치도 실습도 하지 않습니다.

다음 네 가지를 우선 살펴봅니다.

문서의 기본 저장 방식은 "덮어쓰기" 입니다.
그렇기 때문에 문서는 추가로 사본을 만드는 불편한 방법을 사용합니다.
Git 이 사본 파일을 만들지 않고 저장 시점의 기록한다는 점을 대조해 구분합니다.
GitHub 에 내 컴퓨터의 Git 저장 폴더를 인터넷에 보관하고 공유합니다.

그리고 Git과 GitHub 두 도구를 1)비교하며 2)역할을 이해합니다.

이 구분이 되어 있어야 12강에서 저장소를 만들고 13강에서 GitHub에 올릴 때 지금 어느 도구를 다루는지 알 수 있습니다.

준비물은 웹 브라우저만 있으면 됩니다. GitHub 계정은 오늘 필요하지 않습니다. 계정 만들기와 플러그인 설치는 11강에서 합니다.

1. 문서 저장과 불러오기 방식의 문제점

→ 지금 쓸 수 있는 유일한 방법인 사본 저장을 직접 해 보고 불편을 확인합니다.

1.1 사본 파일 만들고 원본 수정하기

문서의 기본 저장 방식은 "덮어쓰기" 입니다.

그렇기 때문에 과거 문서 내용을 불러오는 유일한 방법은 사본으로 별도 저장하는 불편한 작업입니다.

▶ 지금 해보세요

notes 폴더의 study-log 노트를 엽니다.
노트 내용 전체를 선택해 복사합니다.
notes 폴더에 study-log 0728이라는 새 노트를 만들고 붙여넣습니다.
오늘 날짜를 이름에 붙여 오늘 상태의 보관본을 만든 것입니다.
원본 study-log 노트로 돌아가 문장 하나를 수정합니다.

지금까지 만든 노트 상태

study-notes/
└── notes/
    ├── study-log.md        # ✏️ 방금 문장 하나 수정
    └── study-log 0728.md   #   오늘 상태의 사본

1.2 문서를 사본으로 저장할 때 불편 확인하기

이제 notes 폴더에는 이름이 비슷한 노트가 두 개 있습니다. 이 상태에서 세 질문에 답해 보세요.

두 노트 중 어느 것이 최신입니까? 일주일 뒤에도 파일 이름만 보고 알 수 있습니까?
두 노트는 정확히 어디가 다릅니까? 알아내려면 두 노트를 나란히 열고 직접 비교하는 방법뿐입니다.
사본을 만들기 전인 오늘 아침 상태로 돌아갈 수 있습니까? 그 시점의 사본이 없으므로 돌아갈 수 없습니다.

사본 저장의 불편은 크게 세 가지로 정리됩니다.

파일이 계속 쌓입니다.
사본끼리 비교하기 어렵습니다.
사본이 없는 시점으로는 돌아갈 수 없습니다.

"소스 코드로 쓰여진 문서"를 매일 고치는 개발자들에게는 이 불편이 훨씬 부담스러웠고, 그래서 만들어진 도구가 Git 입니다.

⚠ 주의: 확인이 끝났으면 체험용 study-log 0728 노트는 삭제하세요. 남겨 두면 12강에서 저장소를 만들 때 체험용 사본까지 함께 커밋됩니다.

2. Git 저장 방식 확인하기

→ 문서·게임의 저장 방식과 Git의 저장 방식을 대조합니다.

2.1 문서의 저장과 불러오기 방식

저장과 불러오기는 우리에게 매우 익숙한 기능입니다.

하지만 이 익숙한 기능에 대해 깊게 고민해 본 적은 아마 드물 것입니다.

Git과 GitHub를 제대로 이해하기 위해, 먼저 '저장'과 '불러오기'라는 기본 개념부터 차근차근 짚고 넘어가 봅시다.

2.1.1. 사본 저장과 불러오기 문제 확인

문서 편집기에서 "저장"은,

기본적으로 지금 보이는 내용을 하나의 파일에 덮어쓰는 동작입니다.

문서 편집기에는 "불러오기"는

별도의 동작이 없고, 사본 파일을 여는 것이 곧 불러오기입니다.

만약 이전 상태로 돌아가려면

미리 사본 파일로 만들어 두었어야 하고,

사본을 만들지 않은 시점은 다시 열 방법이 없습니다.

하지만 매번 작업할 때마다 일일이 사본을 만들어 두는 것은 번거로울 뿐만 아니라 결코 일반적인 방식이 아닙니다.

2.1.2. 게임 저장과 불러오기 비교

반면 게임의 "저장"은,

기본적으로 지금 시점의 상태를 새로운 파일로 만드는 동작입니다.

만약 보스전 앞에서 저장하면 게임은 그 순간의 상태(캐릭터 위치, 체력, 진행 상황)를 저장 지점 하나로 기록합니다.

보스전에서 패배한 뒤 "불러오기"를 실행하면 게임은 저장해 둔 시점의 상태로 되돌아갑니다. 저장 이후에 진행한 내용(패배로 끝난 전투)은 사라지고, 저장 지점의 상태에서 다시 시작합니다.

Git이 채택한 방식은 문서의 저장이 아니라, 게임의 저장 방식에 가까우면서, 하나의 파일에서 저장합니다.
다음 절에서 이 대응 관계를 Git의 실제 동작으로 확인합니다.

2.2 Git 의 저장 방식

Git은 내 컴퓨터에 설치해 문서를 저장하는 프로그램입니다.

문서 편집기이나 게임과 달리, 사본이라는 추가 파일을 별도로 저장하는 것이 아니라, 저장하고 싶은 시점마다 하나의 저장 지점으로 기록합니다.

이때 사본 파일은 생기지 않습니다.

마치 문서 편집기처럼 최신 파일 하나만 보이지만, 저장 지점의 기록은 Git이 폴더 안쪽에서 따로 관리합니다.

저장 지점을 식별하기 위해, 설명을 붙여 두고, 나중에 그 설명을 보고 되돌아갈 시점을 고릅니다.

구분	문서의 사본 저장	게임의 저장 지점 저장(Git)
저장할 때 생기는 것	새 파일이 하나 더 생긴다	저장 지점 기록이 한 건 남는다. 파일은 그대로 하나다
시점을 구분하는 방법	파일 이름에 붙인 날짜	저장 지점마다 붙인 한 줄 설명
과거로 돌아가기	사본을 만들어 둔 시점만 가능	기록을 남긴 모든 시점 가능
폴더의 상태	사본이 쌓여 최신 파일을 찾기 어렵다	최신 파일만 보인다

시점마다 기록을 남기면 사본 방식만큼 용량이 늘 것 같지만, 그렇지 않습니다. Git은 저장할 때 바뀐 파일만 새로 저장합니다.

바뀌지 않은 파일은 다시 복사하지 않고, 이전 기록에 저장해 둔 내용을 그대로 가리킵니다. 저장하는 내용은 압축해서 보관합니다.그래서 기록이 수천 건 쌓여도, 폴더 전체를 수천 번 복사한 것보다 훨씬 작은 용량을 차지합니다.

✔ 용어 : Git이 기록을 관리하는 폴더를 저장소(repository)라고 부릅니다. 저장 지점의 기록 한 건을 커밋(commit)이라고 부릅니다. 일반적인 파일 저장과 구분하기 위해 이처럼 별도의 용어를 사용하는 이유가 있습니다.

저장소(Repository)는 단순히 파일만 모아두는 곳이 아니라 프로젝트의 '모든 변경 시점'을 기억하는 공간이기 때문입니다.

또한, '저장(Save)'이 파일 하나를 덮어쓰는 작업이라면, '커밋(Commit)'은 프로젝트 전체의 특정 시점을 기록하는 일입니다.

3. GitHub 공유 방식 확인하기

→ 공개 저장소 페이지를 열어 화면 구성 세 가지를 찾습니다.

3.1 GitHub이 해결하는 문제 확인하기

Git 까지만 쓰면 기록은 여전히 내 컴퓨터 안에 있습니다.

문서를 과거 시점으로 되돌리기 문제는 해결되지만, PC 고장 문제와 공유 문제는 그대로 남습니다.

GitHub은 이 남은 두 문제를 해결하는 인터넷 서비스입니다. 내 컴퓨터의 Git 저장소를 인터넷 서버에 올려 보관합니다.

올린 저장소는 누구나 웹 브라우저로 볼 수 있는 페이지로 표시됩니다.

문서를 구글 드라이브에 올려 보관하고 공유하는 것과 같은 구조입니다.

다른 점은 올라가는 대상이 Git 저장소라는 것입니다.

파일만 올라가는 것이 아니라, 커밋이라는 시점이 저정된 기록까지 함께 올라갑니다.

전 세계 개발팀 대부분이 이 방식으로 소스코드를 보관하고 공유합니다.

3.2 GitHub 공개 저장소 살펴보기

실제 GitHub 모습을 하나만 열어 봅니다.

브라우저에서 다음 주소를 여세요. 웹 페이지 디자인에 널리 쓰이는 개발 프로젝트의 저장소입니다.

https://github.com/twbs/bootstrap

[화면 캡처: 브라우저에 연 twbs/bootstrap 저장소의 첫 화면]

페이지는 영어로 표시됩니다. 오늘 확인할 것은 글의 내용이 아니라 화면의 구성입니다.

▶ 지금 해보세요

주소와 화면 맨 위의 twbs/bootstrap을 찾습니다. 계정이름/저장소이름 형식입니다. GitHub에 올라온 저장소는 모두 이런 주소를 갖습니다.
화면 가운데의 파일과 폴더 목록을 찾습니다. 이 프로젝트를 만드는 개발자들 컴퓨터의 폴더가 그대로 인터넷에 올라와 있는 것입니다.
파일 목록 아래의 긴 소개 문서를 찾습니다. 폴더 안 README.md 파일의 내용이 첫 화면에 자동으로 표시된 것입니다. 학습 단위 1에서 작성해 온 마크다운 파일이 여기서 이렇게 쓰입니다.

지금 로그인을 하지 않았는데도 이 페이지가 전부 보입니다.

공개 저장소는 계정이 없는 사람을 포함해 누구나 볼 수 있습니다.

✔ 정리: 13강에서 자기 저장소를 공개로 만들 때 이 성질을 다시 판단하게 됩니다.

4. Obsidian, Git, GitHub 구조 확인

→ 오늘 확인한 내용의 사용 구조를 확인해봅니다.

5. 내 학습 기록에 대입해 보고 11강으로 넘기기

→ 오늘 확인한 내용을 자기 상황에 옮겨 적고 공개 범위를 판단합니다.

5.1 study-log 노트에 세 가지 적기

오늘 확인한 내용을 자기 상황에 옮겨 적습니다.

▶ 지금 해보세요

study-log 노트에 ### 10강. Git과 GitHub 확인 절을 만듭니다.
지금까지 만든 노트 중에서, 며칠 전 상태로 되돌리고 싶었던 적이 있는 파일이 있는지 적습니다. 있었다면 어느 노트인지 함께 적습니다.
Git과 GitHub 중 어느 것이 내 컴퓨터에서 동작하고, 어느 것이 인터넷 서비스인지 한 줄로 구분해 적습니다.
내 study-notes 폴더가 방금 본 저장소처럼 인터넷에 공개된다면, 먼저 지워야 할 내용이 있는지 적습니다.

⚠ 주의: 세 번째 질문은 13강 실습 전에 반드시 답해 두세요. 저장소를 공개로 만들면 올린 내용은 누구나 볼 수 있습니다. 나중에 파일을 지워도 커밋 기록에는 남습니다.

5.2 확인한 내용 정리하고 11강으로 넘기기

다음 세 가지가 확인되면 오늘 학습이 끝난 것입니다.

확인 항목	기대 결과	확인 방법
사본 저장 체험	문제와 해결책에 각각 답할 수 있고 체험용 사본 노트가 삭제되어 있음	Obsidian 파일 목록 확인
두 도구 구분	Git과 GitHub 중 어느 것이 내 컴퓨터에서 동작하는지 한 줄로 적혀 있음	`study-log` 노트 확인
공개 범위 판단	공개 전에 지울 내용이 있는지 판단한 결과가 적혀 있음	`study-log` 노트 확인

→ 다음 개별 강의

11강에서는 오늘 구분한 두 도구를 사용하기 위한 준비를 합니다. GitHub 계정을 만들고, 인증에 사용할 개인 접근 토큰을 발급하고, Obsidian에 Git 플러그인을 설치합니다. 12강에서는 study-notes 폴더를 저장소로 만들어 지금까지 작성한 노트를 첫 커밋으로 남기고, 13강에서 그 커밋을 GitHub에 올립니다. 오늘 본 것과 같은 구성의 페이지가 자기 계정 아래에 생깁니다.

9강. Obsidian 안에서 Claude 사용하기

BasicLike — Tue, 28 Jul 2026 13:50:20 +0900

9강 구현 중심 ⏱ 약 60분

0. 학습 목표

→ Claude Code와 Claudian 플러그인을 설치해, Obsidian 노트 화면 안에서 선택한 내용으로 질문합니다.

0.1 이번 글에서 다룰 내용

설치 명령이 무엇을 하는지 실행 전에 확인하는 절차를 거친 뒤 Ubuntu에 Claude Code를 설치하고 로그인
Obsidian에 Claudian 커뮤니티 플러그인을 설치하고, 노트에서 선택한 문장과 @로 지정한 다른 노트를 근거로 질문
질문 결과를 8강의 대조 절차 다섯 단계로 검토해 받아들일 부분만 자기 노트에 반영하고, 두 가지 사용 방식을 상황별로 비교해 study-log 노트에 기록

8강에서는 Claude 앱으로 이동해서 질문했습니다. 노트를 읽다가 궁금한 것이 생길 때마다 앱을 오가는 것은 번거롭습니다. 오늘은 7강에서 비교한 세 가지 방식 중 마지막 방식을 사용합니다. Obsidian 안에 Claude 대화 패널을 띄워, 화면을 옮기지 않고 읽던 자리에서 질문합니다.

Claudian은 Obsidian의 확장 기능(플러그인)으로, 노트 화면 안에 Claude 대화 패널을 띄워 줍니다. 노트에서 문장을 마우스로 선택해 바로 질문할 수 있고, @를 입력해 폴더 안의 다른 노트를 참조로 붙일 수도 있습니다. 이 플러그인은 Claude Code라는 프로그램을 통해 동작하므로, 먼저 Claude Code를 설치하고 그다음 플러그인을 설치합니다.

Claude Code는 원래 개발자가 쉘에서 사용하는 AI 도구입니다. 오늘은 Claudian을 동작시키는 데 필요한 설치와 로그인까지만 다루고, Claude Code 자체의 사용법은 뒤의 Claude 소주제에서 본격적으로 배웁니다.

0.2 이번 강의 실습 내용

8강까지 마친 상태. notes 폴더에 study-plan, study-log, obsidian-setup 세 노트가 있어야 합니다.
8강에서 사용한 Claude 구독 계정. Claude Code 로그인에 같은 계정을 사용합니다.
쉘 프롬프트(Ctrl+Alt+T)

1. 설치 명령을 확인한 뒤 Claude Code를 설치하고 로그인하기

→ 받자마자 실행하는 설치 명령의 내용을 먼저 확인한 뒤, Claude Code를 설치하고 로그인합니다.

1.1 실행할 명령이 무엇을 하는지 확인하기

이 절에서 설치 명령의 내용을 먼저 확인하고, 그다음 설치와 로그인을 진행합니다. 확인 절차를 먼저 두는 이유는 이 설치 방식이 8강과 다르기 때문입니다.

설치 명령은 다음과 같습니다. 아직 실행하지 마세요.

curl -fsSL https://claude.ai/install.sh | bash

이 한 줄은 두 가지 일을 이어서 합니다. curl이 앞의 주소에서 설치 스크립트 파일을 내려받고, 세로줄 뒤의 bash가 그 내용을 곧바로 실행합니다. 파일로 저장해 열어 보는 단계 없이 받자마자 실행하는 방식입니다.

8강에서 Claude 앱을 설치할 때는 이렇게 하지 않았습니다. 서명 키를 먼저 등록하고, 그 키로 확인된 저장소에서만 설치했습니다. 받은 것이 배포처가 만든 것이 맞는지 시스템이 확인해 주는 방식입니다.

이번 방식에는 그 확인 단계가 없습니다. 그래서 실행하기 전에 사람이 직접 확인해야 하는 것이 두 가지 있습니다.

주소가 제품의 공식 도메인인가. 여기서는 claude.ai입니다. 검색 결과나 다른 사람이 알려 준 주소를 그대로 쓰지 않고, 제품 공식 문서에 적힌 주소인지 확인합니다.
내려받는 내용이 무엇인가. 다음 명령은 실행 부분을 빼고 화면에 내용만 보여 줍니다.

쉘 프롬프트

# 설치 스크립트 내용만 화면에 표시
curl -fsSL https://claude.ai/install.sh | less

전체를 읽을 필요는 없습니다. 첫 화면에서 설치 대상과 설치 위치가 적힌 부분을 확인하고 q를 눌러 나옵니다. 여기서 확인하려는 것은 스크립트를 해석하는 능력이 아니라, 받자마자 실행하는 명령을 만나면 실행 전에 내용을 한 번 보는 절차입니다. 실무에서도 출처가 분명하지 않은 주소에 이 방식을 쓰지 않습니다.

증상	원인	해결 방법
설치 내용을 확인하는 명령에서 아무것도 나오지 않는다	네트워크 연결 또는 주소 오타	주소를 다시 확인하고, 반복되면 강사에게 알린다. 내용을 확인하지 못한 상태로 설치 명령을 실행하지 않는다

1.2 설치하고 로그인하기

1.2.1. 설치하고 버전 확인하기

확인이 끝났으면 설치 명령을 실행합니다.

쉘 프롬프트

# Claude Code 설치
curl -fsSL https://claude.ai/install.sh | bash

설치가 끝나면 쉘 프롬프트를 닫았다가 새로 연 뒤, 버전을 확인합니다.

쉘 프롬프트

# 설치된 버전 확인
claude --version

버전 번호가 표시되면 설치 성공입니다.

증상	원인	해결 방법
`claude: command not found`	설치 후 쉘을 새로 열지 않음	쉘 프롬프트를 닫고 새로 연다

1.2.2. 로그인하기

이어서 로그인합니다.

쉘 프롬프트

# Claude Code 로그인
claude

처음 실행하면 로그인 안내가 나오고 웹 브라우저가 열립니다. 8강에서 사용한 Claude 계정으로 로그인하고 승인하면, 쉘 프롬프트에 로그인 완료 표시가 나타납니다. 확인 후 Ctrl+C 또는 /exit 입력으로 종료합니다. Claudian이 사용하는 것은 이 로그인 상태이므로, 프로그램을 종료해도 됩니다. 여기까지가 첫 번째 학습 목표입니다.

증상	원인	해결 방법
로그인 브라우저가 열리지 않는다	기본 브라우저 설정 문제	쉘에 표시된 주소를 복사해 브라우저에 직접 붙여넣는다

2. Claudian 플러그인을 설치하고 노트에서 선택한 내용으로 질문하기

→ 플러그인을 설치하고, 선택한 문장과 @로 지정한 노트를 근거로 각각 질문합니다.

2.1 Claudian 플러그인 설치하기

Obsidian의 커뮤니티 플러그인은 다른 개발자들이 만들어 공유하는 확장 기능입니다. 편리하지만 제3자가 만든 프로그램이므로, 이 과정에서는 수업에서 안내하는 플러그인만 설치합니다.

Obsidian에서 왼쪽 아래 톱니바퀴 [Settings]를 누릅니다.
[Community plugins] 항목을 선택합니다.
처음이라면 커뮤니티 플러그인 사용을 켜는 버튼([Turn on community plugins])을 누릅니다. 보안 안내가 나오면 내용을 읽고 진행합니다.
[Browse] 버튼을 누르고 검색창에 Claudian을 입력합니다.
Claudian을 선택하고 [Install]을 누른 뒤, 설치가 끝나면 [Enable]을 누릅니다.
설정 창을 닫습니다. 화면 가장자리의 리본 메뉴에 Claudian 아이콘이 생긴 것을 확인합니다.

아이콘을 누르면 화면 옆에 Claude 대화 패널이 열립니다. 패널이 열리지 않거나 로그인 오류가 표시되면, 앞 절의 Claude Code 로그인이 완료되었는지부터 다시 확인하세요. 화면 구성은 플러그인 버전에 따라 다를 수 있으므로, 다른 부분은 강사의 시연을 따라 합니다.

증상	원인	해결 방법
플러그인 검색 결과에 Claudian이 없다	커뮤니티 플러그인이 꺼져 있거나 검색어 오타	[Community plugins]가 켜져 있는지, 철자가 맞는지 확인한다
패널에서 로그인 오류가 표시된다	Claude Code 로그인이 안 된 상태	쉘에서 `claude`를 실행해 로그인부터 완료한다

2.2 선택한 문장을 그 자리에서 질문하기

6강에서 작성한 notes 폴더의 obsidian-setup 노트를 엽니다.

노트에서 궁금한 문장 하나를 마우스로 드래그해 선택합니다.
Claudian 패널의 입력창에 질문을 입력합니다. 선택한 내용이 함께 전달됩니다.

클로드 프롬프트

# 선택한 문장의 표현 검토 요청
지금 선택한 부분을 더 정확한 표현으로 고쳐줘.
바뀐 이유도 한 줄로 알려줘.

제안된 수정안을 읽고 8강의 대조 절차 다섯 단계를 그대로 적용합니다. 제안이 원래 의미를 바꾸지는 않았는지, 사실과 다른 내용이 들어가지는 않았는지 확인한 뒤, 받아들일 부분만 자기 손으로 노트에 반영하세요. 도구가 문장을 생성하고, 채택 여부를 결정하고 그 결과에 책임지는 것은 여러분입니다.

2.3 @로 다른 노트를 지정해 질문하기

이번에는 다른 노트를 대상으로 합니다. 4강에서 만든 notes 폴더의 study-plan 노트를 엽니다. 이 노트에는 무엇을 남기고 무엇을 남기지 않을지 자기가 정한 기준이 적혀 있습니다.

패널에서 @를 입력해 보세요. Vault 안의 파일 목록이 나타납니다. obsidian-setup을 선택해 참조로 붙이고, 다음과 같이 질문합니다.

클로드 프롬프트

# study-plan 기준으로 obsidian-setup 검토 요청
@notes/obsidian-setup.md 는 내가 1강 내용을 정리한 노트야.
지금 열려 있는 study-plan의 "남길 것" 기준으로 봤을 때,
obsidian-setup에 빠져 있는 항목이 있으면 알려줘.
어느 기준에 해당하는지 함께 적어줘.

앞의 질문은 지금 열어 둔 노트의 선택한 문장을 대상으로 했고, 이번에는 열어 둔 노트와 @로 지정한 다른 노트 두 개를 함께 다룹니다. 지적받은 항목을 두 노트에서 직접 확인한 뒤, 맞는 지적이면 obsidian-setup에 내용을 보완합니다. 수정 후 읽기 모드(Ctrl+E)로 결과를 확인하세요. 여기까지가 두 번째 학습 목표입니다.

3. 두 가지 사용 방식을 비교해 자기 기준 정하기

→ 8강의 폴더 연결 방식과 오늘의 패널 방식을 상황별로 비교해 study-log 노트에 기록합니다.

3.1 상황별 사용 방식을 표로 정리해 기록하기

8강의 방식(앱에 폴더 연결)과 오늘 방식(Obsidian 안 패널)을 모두 써 봤습니다. notes 폴더의 study-log 노트에 다음을 기록하세요.

### 9강. 두 가지 Claude 사용 방식 비교

| 상황 | 내가 쓸 방식 | 이유 |
|---|---|---|
| (예: 노트 읽다가 문장 하나가 궁금할 때) | | |
| (예: 여러 노트에 걸친 내용을 물을 때) | | |

표의 상황 두 개 이상을 자기 경험으로 채우고, 각 상황에서 어느 방식을 쓸지 이유와 함께 적습니다. 정답이 있는 문제가 아니라, 도구를 목적에 맞게 선택하는 연습입니다. 이것이 세 번째 학습 목표입니다.

4. 오늘 만든 상태를 확인하고 로그인 정리하기

→ 네 가지 확인 항목을 점검하고, Claude Code에서 로그아웃해 오늘 설치한 로그인 상태를 정리합니다.

4.1 네 가지 확인 항목 점검하기

다음 네 가지가 모두 확인되면 9강에서 만들어야 할 상태가 갖춰진 것입니다.

쉘 프롬프트에서 claude --version을 실행하면 버전 번호가 표시됩니다.
Obsidian 리본 메뉴에 Claudian 아이콘이 있고, 눌렀을 때 대화 패널이 열립니다.
obsidian-setup 노트에 선택한 문장의 수정과 @ 질문으로 지적받은 항목의 보완이 반영되어 있습니다.
study-log 노트에 ### 9강. 두 가지 Claude 사용 방식 비교 표가 두 행 이상 채워져 있습니다.

패널의 답변을 그대로 붙여 넣기만 했다면 3번은 아직 확인되지 않은 것입니다. 원본과 대조한 뒤 받아들일 부분을 직접 고쳐 넣으세요.

4.2 Claude Code 로그아웃으로 로그인 정리하기

확인이 끝나면 로그인을 정리합니다. 오늘 로그인한 것은 Claude Code 하나이고 Claudian 플러그인은 그 로그인 상태를 그대로 사용하므로, Claude Code에서 로그아웃하면 둘 다 정리됩니다.

쉘 프롬프트에서 다음을 실행합니다.

쉘 프롬프트

# Claude Code 실행
claude

실행된 화면에서 /logout을 입력하고 Enter 키를 누릅니다. 로그아웃되었다는 표시가 나오면 /exit으로 나옵니다.

정리되었는지 확인합니다. Obsidian에서 Claudian 패널을 열고 질문을 하나 보내 보세요. 로그인 오류가 표시되면 로그아웃된 것입니다. 답변이 생성되면 아직 로그인 상태이므로 위 절차를 다시 수행합니다.

증상	원인	해결 방법
`/logout`을 입력했는데 명령을 찾을 수 없다고 나온다	쉘 프롬프트에 직접 입력함	`claude`를 먼저 실행해 Claude Code 화면에 들어간 뒤 입력한다

⚠ 주의: 이 절차를 빼먹으면 다음 사용자가 내 계정으로 질문을 보낼 수 있습니다. 웹 화면과 달리 브라우저를 닫는 것으로는 정리되지 않습니다. Claude Code의 로그인 정보는 홈 폴더에 남기 때문입니다.

✔ 정리: 설치 명령의 내용을 실행 전에 확인한 뒤 Claude Code를 설치하고 로그인했고, Claudian 플러그인을 설치해 선택한 문장과 @로 지정한 노트를 근거로 질문했으며, 8강과 오늘의 두 방식을 상황별로 비교해 study-log 노트에 기록하고 로그인 상태를 정리했습니다.

여기까지가 이 학습 단위의 마지막 강의입니다. 지금까지 노트를 만들고(1강~6강) AI 도구와 함께 학습하는 방법(7강~9강)을 갖췄습니다. 그런데 이 노트들은 아직 내 컴퓨터에만 있습니다. 컴퓨터가 고장 나면 전부 사라지고, 다른 사람에게 보여줄 방법도 없습니다.

→ 다음 주제

다음 학습 단위 Git·Colab·GitHub Pages로 학습 기록 저장하고 공개하기로 넘어갑니다. 그 단위의 첫 강의인 Git과 GitHub의 역할을 구분하고 공개 저장소의 커밋 이력 읽어 보기에서 두 도구가 각각 무엇을 하는지 구분하고 공개 저장소의 커밋 이력을 읽어 본 뒤, 그다음 강의인 Git과 GitHub 기초 명령으로 학습 기록 저장소 만들기에서 내 학습 기록을 저장소로 만들어 인터넷에 올립니다.

8강. 학습 자료 폴더와 Claude 사용하기

BasicLike — Tue, 28 Jul 2026 13:19:23 +0900

8강 구현 중심 ⏱ 약 60분

0. 학습 목표

→ Claude 데스크톱 앱에 학습 자료 폴더를 연결해 질문하고, 답변을 원본과 대조하는 절차를 익힙니다.

0.1 이번 글에서 다룰 내용

Ubuntu에 Claude 데스크톱 앱을 저장소 등록 방식으로 설치하고, 수업용 구독 계정으로 로그인
study-notes 폴더를 Claude에 연결하고, 근거로 삼을 파일과 답변 범위를 지정한 질문을 작성
답변을 원본 노트와 다섯 단계 절차로 대조하고, 대조 결과와 자기 노트에서 고친 부분을 study-log 노트에 기록

7강에서 Claude 웹에 로그인해 첫 질문을 보내고 답변을 받아 봤습니다. 그때 확인한 것처럼 웹 화면의 질문은 입력한 문장만 근거로 답변이 생성되기 때문에, 우리 수업 자료와 다른 내용이 나올 수 있고 그럴듯하지만 틀린 부분이 섞여도 알아차리기 어렵습니다.

오늘은 이 문제를 줄이는 사용 방법을 배웁니다. Claude 데스크톱 앱에 내 학습 자료 폴더를 통째로 연결하면, Claude가 폴더 안의 노트를 실제로 읽고 그 내용을 근거로 답변을 생성합니다. 여러분이 할 일은 두 가지입니다. 근거로 삼을 자료를 지정해 질문하는 것, 그리고 답변을 원본 노트와 대조해 맞는지 직접 확인하는 것입니다. 이 두 가지가 앞으로 7개월 동안 AI 도구를 학습에 사용하는 기본 방법이 됩니다.

0.2 이번 강의 실습 내용

6강까지 마친 study-notes 폴더. notes 폴더에 study-plan, study-log, obsidian-setup 세 노트가 있어야 합니다. obsidian-setup은 6강에서 1강 내용을 정리해 직접 작성한 노트이며, 만들지 못했으면 강사가 배부하는 예시 노트를 notes 폴더에 넣고 시작합니다.
7강에서 웹으로 로그인해 본 Claude 구독 계정
관리자 비밀번호(앱 설치에 필요합니다)
쉘 프롬프트(Ctrl+Alt+T)

Claude 데스크톱 앱의 Linux 버전은 베타 버전으로 제공됩니다. 베타는 정식 출시 전 시험 단계라는 뜻으로, 화면 구성과 메뉴 이름이 수업 자료와 다를 수 있습니다. 다른 부분이 있으면 강사의 시연 화면을 기준으로 따라 하세요.

1. Claude 데스크톱 앱을 설치하고 로그인하기

→ 저장소 등록 방식으로 앱을 설치하고, 유료 구독 계정으로 로그인되었는지 확인합니다.

1.1 저장소 등록 방식으로 앱 설치하기

1. Claude Desktop .deb 파일 설치

1. Claude Desktop 설치

1강 실습 중심 ⏱ 약 20분 0. 학습 목표→ 우분투 24.04에서 Claude 데스크톱 앱을 직접 설치하고, 로그인해 첫 화면까지 열어봅니다.더보기0.1 이번 글에서 다룰 내용이번 글은 실습 중심 강의입니다.

basiclike.tistory.com

설치는 쉘 프롬프트에서 명령을 순서대로 실행합니다. 이번에는 1강의 방법 B(.deb 파일 설치)와 달리 저장소 등록이라는 방식을 사용합니다. 프로그램 제공처의 주소를 내 컴퓨터에 등록해 두면, 이후 시스템 업데이트 때 이 프로그램도 함께 최신으로 유지되는 방식입니다.

1.1.1. 서명 키 등록하기

내려받을 프로그램이 진짜 Anthropic이 배포한 것인지 확인하는 데 쓰는 키를 등록합니다.

쉘 프롬프트

# Claude 데스크톱 앱 서명 키 등록
sudo curl -fsSLo /usr/share/keyrings/claude-desktop-archive-keyring.asc https://downloads.claude.ai/claude-desktop/key.asc

curl 명령이 없다는 메시지가 나오면 먼저 sudo apt install curl로 curl을 설치한 뒤 다시 실행합니다.

1.1.2. 저장소 등록하기

Claude 데스크톱 앱의 제공 주소를 시스템에 등록합니다. 긴 명령이므로 한 글자씩 입력하지 말고, 수업 자료에서 복사해 쉘 프롬프트에 붙여넣으세요(Ctrl+Shift+V).

쉘 프롬프트

# 앱 저장소 등록
echo "deb [signed-by=/usr/share/keyrings/claude-desktop-archive-keyring.asc] https://downloads.claude.ai/claude-desktop/apt/stable stable main" | sudo tee /etc/apt/sources.list.d/claude-desktop.list

증상	원인	해결 방법
2단계 명령 후 `apt update`에서 오류가 난다	저장소 등록 명령이 잘못 입력됨	수업 자료에서 명령을 다시 복사해 붙여넣고, `/etc/apt/sources.list.d/claude-desktop.list` 내용이 한 줄인지 확인한다

1.1.3. 설치하고 로그인하기

등록한 저장소에서 앱을 설치합니다.

쉘 프롬프트

# 저장소 목록 갱신 후 앱 설치
sudo apt update
sudo apt install claude-desktop

설치가 끝나면 앱 목록에서 Claude를 검색해 실행하고, 안내에 따라 본인 계정으로 로그인합니다. 채팅 입력창이 있는 화면이 나타나면 설치와 로그인이 완료된 것입니다. 여기까지가 첫 번째 학습 목표입니다.

증상	원인	해결 방법
앱은 설치됐는데 로그인이 안 된다	네트워크 또는 계정 문제	브라우저에서 claude.ai 로그인이 되는지 먼저 확인하고, 되면 앱을 재시작한다

1.2 유료 구독 계정으로 로그인되었는지 확인하기

로그인한 계정이 폴더 연결을 쓸 수 있는 유료 구독 계정인지 먼저 확인합니다. 앱의 계정 메뉴에서 현재 요금제 이름을 확인하세요.

참고: 무료 계정으로 로그인되어 있으면 다음 절의 폴더 연결 기능이 나타나지 않습니다. 수업용으로 안내받은 계정과 다른 계정으로 로그인되어 있으면 로그아웃한 뒤 다시 로그인합니다.

2. 학습 자료 폴더를 연결하고 근거를 지정해 질문하기

→ study-notes 폴더를 연결해 연결 상태를 확인하고, 근거를 지정한 질문과 그렇지 않은 질문을 비교합니다.

2.1 폴더 연결하고 연결 상태 확인하기

이제 Claude가 내 노트를 읽을 수 있도록 폴더를 연결합니다.

Claude 앱에서 새 대화(작업)를 시작합니다.
폴더 연결 기능을 열고 홈 폴더의 study-notes를 선택합니다. 기능의 위치는 앱 버전에 따라 다르므로 강사의 시연을 따라 하세요.
연결이 되었는지 확인하기 위해 첫 질문을 입력합니다.

클로드 프롬프트

# 폴더 연결 상태 확인
연결된 폴더에 어떤 파일들이 있는지 목록으로 보여줘.

답변에 index.md, notes/study-log.md, notes/obsidian-setup.md, reference/markdown-syntax.md 같은 실제 파일 이름이 나오면 연결 성공입니다. 엉뚱한 파일 이름이 나오거나 폴더를 읽을 수 없다는 답이 나오면, 연결한 폴더가 study-notes가 맞는지 다시 확인하세요.

증상	원인	해결 방법
폴더 연결 기능이 보이지 않는다	계정 요금제 또는 앱 버전 문제	강사에게 알린다. 수업은 강사 시연 화면을 보며 질문 작성 연습으로 진행한다
답변이 내 자료와 무관한 일반 설명이다	폴더가 연결되지 않은 대화에서 질문함	폴더가 연결된 대화인지 확인하고, 파일 목록 질문으로 연결 상태부터 다시 확인한다

2.2 근거를 지정해 질문하는 방법 확인하기

같은 것을 물어도 질문에 따라 답의 신뢰도가 달라집니다. 두 질문을 비교해 보세요.

근거를 지정하지 않은 질문입니다.

클로드 프롬프트

# 근거를 지정하지 않은 질문
마크다운 링크가 뭐야?

근거를 지정한 질문입니다.

클로드 프롬프트

# 근거를 지정한 질문
reference/markdown-syntax.md의 9번 링크 절을 읽고,
표준 마크다운 링크와 위키링크의 차이를 내 자료에 있는 내용만 근거로 설명해줘.
근거로 사용한 파일명을 답변에 함께 적어줘.

차이는 세 가지입니다. 어떤 파일을 근거로 할지 지정했고, 자료에 있는 내용만 쓰라고 범위를 제한했고, 근거 파일명을 밝히라고 요구했습니다. 이렇게 물으면 답변이 우리 수업 자료 기준으로 만들어지고, 원본과 대조하기도 쉬워집니다.

증상	원인	해결 방법
답변이 참조한 파일명을 적어 주지 않는다	질문에 파일명을 밝히라는 요구가 빠짐	질문 마지막 줄에 근거 파일명을 함께 적어 달라는 문장을 넣어 다시 묻는다

여기까지가 두 번째 학습 목표입니다.

3. 답변을 원본과 대조해 study-log 노트에 기록하기

→ 대조 절차 다섯 단계를 확인하고, 두 번의 질문으로 그 절차를 직접 적용합니다.

3.1 대조 절차 다섯 단계 확인하기

한 가지 원칙을 기억하세요. 생성된 답변은 검토하기 전까지 확인되지 않은 정보입니다. Claude는 자료를 읽고 답변을 생성할 뿐이고, 그 답이 맞는지 판단하는 것은 여러분의 몫입니다.

아래 다섯 단계가 이 과정에서 답변을 대조하는 기준 절차입니다. 9강에서 도구가 바뀌어도 같은 순서를 씁니다.

답변에서 근거로 제시된 파일명을 확인한다.
Obsidian에서 그 파일을 직접 연다.
답변의 핵심 내용이 원본에 실제로 있는지 확인한다.
원본에 없는 내용이 답변에 섞여 있으면, "그 내용은 어느 파일의 어느 부분에 있어?"라고 되물어 근거를 요구한다.
대조 결과를 study-log 노트에 기록한다.

3.2 내 정리 노트 검토를 요청하고 대조하기

6강에서 작성한 obsidian-setup 노트를 Claude에게 검토 요청합니다. 다음 질문을 입력하세요.

클로드 프롬프트

# obsidian-setup 노트 검토 요청
notes/obsidian-setup.md는 내가 1강 내용을 정리한 노트야.
index.md와 reference/markdown-syntax.md의 내용과 비교해서,
사실과 다르게 적었거나 빠뜨린 부분이 있으면 원본의 해당 내용과 함께 알려줘.
근거로 사용한 파일명을 답변에 함께 적어줘.

답변이 오면 위의 대조 절차대로 확인합니다. 지적받은 부분이 실제로 원본과 다른지 원본 파일을 열어 확인하고, 맞는 지적이면 자기 노트를 직접 수정하세요. 수정까지가 실습입니다. Claude가 지적했다는 이유만으로 고치지 말고, 원본을 확인한 뒤에 고치는 것이 순서입니다.

확인이 끝나면 notes 폴더의 study-log 노트에 다음 형식으로 기록합니다.

### 8강. Claude 질의응답 기록

- 사용 모델: (입력창 아래 화면에 표시된 이름을 그대로)
- 질문: obsidian-setup 노트 검토 요청
- 답변 요지: (한두 줄로 요약)
- 근거 파일: (답변이 참조한 파일명)
- 대조 결과: (원본과 일치했는지, 내 노트에서 고친 부분은 무엇인지)

사용 모델을 함께 적는 이유는 7강에서 확인한 것과 같습니다. 같은 질문이라도 모델에 따라 답변의 길이와 설명 방식이 달라지므로, 나중에 기록을 다시 볼 때 어떤 조건에서 나온 답변인지 알 수 있어야 합니다. 모델 이름은 Claude 앱의 입력창 아래에서 확인하고 바꿀 수 있습니다.

3.3 내가 만든 질문으로 같은 절차 반복하기

이번에는 질문을 직접 만듭니다. 1강부터 7강까지 배우며 실제로 궁금했던 것을 하나 고르세요. 조건은 세 가지입니다.

근거로 삼을 파일을 질문에 지정한다.
근거 파일명을 답변에 포함하도록 요구한다.
답변을 원본과 대조하고, 앞의 기록과 같은 형식으로 study-log 노트에 기록한다.

질문거리가 떠오르지 않으면 이런 것도 좋습니다. "index.md의 사용 규칙 중 개인정보를 적지 말라는 이유를 폴더 안 자료를 근거로 설명해줘."

두 기록이 끝났으면 study-log 노트를 읽기 모드로 열어 확인하세요. 각 기록에 근거 파일명이 적혀 있고, 대조 결과 칸에 "원본과 일치" 또는 "어느 부분을 어떻게 고쳤다"가 쓰여 있으면 세 번째 학습 목표를 확인한 것입니다. 답변 요지만 옮겨 적고 대조 결과가 비어 있다면, 아직 확인하지 않은 정보를 기록해 둔 것이므로 원본 파일을 열어 대조부터 마치세요.

4. 오늘 만든 상태를 확인하고 로그아웃하기

→ 네 가지 확인 항목을 점검하고, 데스크톱 앱과 폴더 연결을 정리한 뒤 로그아웃합니다.

4.1 네 가지 확인 항목 점검하기

다음 네 가지가 모두 확인되면 8강에서 만들어야 할 상태가 갖춰진 것입니다.

앱 목록에서 Claude를 실행하면 채팅 입력창이 있는 화면이 열립니다.
폴더를 연결한 대화에서 파일 목록을 물었을 때 study-notes 폴더의 실제 파일 이름이 답변에 나왔습니다.
study-log 노트에 ### 8강. Claude 질의응답 기록이 두 건 있고, 각 기록에 근거 파일명과 대조 결과가 적혀 있습니다.
obsidian-setup 노트에서 대조 결과에 따라 고친 부분이 있으면 그 내용이 반영되어 있습니다.

오늘 강의를 마친 뒤의 Claude 연결 상태

Claude 데스크톱 앱
└── 연결된 폴더 study-notes/   # ✏️ 이번 강의에서 연결하고 질의응답에 사용

study-notes/notes/
├── study-log.md         # ✏️ 8강 질의응답 기록 두 건 추가
└── obsidian-setup.md     # ✏️ 대조 결과에 따라 수정

4.2 로그아웃 절차 수행하기

확인이 끝나면 로그아웃합니다. 7강에서 웹 화면을 로그아웃한 것과 같은 이유로, 오늘 설치한 앱에서도 로그아웃해야 합니다. 앱 로그인은 웹 로그인과 별개이므로 브라우저를 닫아도 앱의 로그인 상태는 남습니다.

연결한 폴더 목록에서 study-notes 연결을 해제합니다. 남겨 두면 다음 사용자가 그 목록에서 내 폴더 경로를 볼 수 있습니다.
Claude 앱의 계정 메뉴에서 로그아웃을 선택합니다.
앱을 완전히 닫습니다.
앱을 다시 실행해 로그인 화면이 나오는지 확인합니다. 대화 화면이 바로 열리면 아직 로그아웃되지 않은 것입니다.

앱 자체는 설치된 상태로 두어도 됩니다. 9강에서 다시 사용하지는 않지만, 다음 시간에 같은 PC를 쓰는 학습자가 설치 단계를 건너뛸 수 있습니다.

✔ 정리: Claude 데스크톱 앱을 저장소 등록 방식으로 설치해 로그인하고, study-notes 폴더를 연결해 근거를 지정한 질문을 작성했으며, 답변을 원본과 다섯 단계 절차로 대조해 결과와 수정 내용을 study-log 노트에 기록했습니다.

오늘은 Claude 앱으로 이동해서 질문했습니다. 이번에는 반대로 Obsidian 안으로 Claude를 가져옵니다.

→ 다음 개별 강의

9강에서는 Claudian이라는 확장 기능을 설치합니다. 노트를 읽다가 궁금한 문장을 마우스로 선택해 그 자리에서 바로 질문할 수 있습니다. 오늘 배운 근거 지정과 대조 절차는 도구가 바뀌어도 똑같이 적용됩니다.

7강. Claude 학습 사용

BasicLike — Tue, 28 Jul 2026 12:10:57 +0900

7강 구현 중심 ⏱ 약 30분

0. 학습 목표

→ Claude 웹에 로그인해 질문을 보내고, 근거를 준 질문과 주지 않은 질문의 답변을 대조해 사용 규칙을 정합니다.

0.1 이번 글에서 다룰 내용

Claude 웹 화면에 로그인하고 입력창, 새 대화 시작, 지난 대화 목록, 모델 선택 항목의 위치를 화면에서 확인
질문을 보내고, 같은 대화에서 이어 묻고, 새 대화에서 같은 질문을 다시 보내, 답변이 저장된 항목에서 꺼내 오는 것이 아니라 매번 생성된다는 것을 확인
근거를 주지 않은 질문과 근거를 함께 준 질문의 답변을 대조하고, 이 과정에서 Claude를 어떤 질문에 쓰고 어떤 질문에는 쓰지 않을지 규칙을 정해 study-log 노트에 기록
Obsidian과 함께 쓰는 세 가지 방식이 근거를 전달하는 방법에서 어떻게 다른지 구분하고, 각 방식에 필요한 준비물을 확인

6강까지 노트를 정리하면서, 자기가 쓴 내용이 맞는지 확신하기 어려운 부분이 생겼을 것입니다. 8강과 9강에서 이런 부분을 확인할 때 Claude를 사용합니다.

오늘 하나의 소개 강의로 두 실습을 함께 준비하는 이유는 8강과 9강이 같은 도구를 서로 다른 방법으로 사용하는 강의이기 때문입니다.

오늘은 그 준비 단계로 웹 화면에서 직접 조작해 봅니다.

로그인하고, 질문을 보내고, 답변을 받고, 같은 질문을 다시 보내 결과를 비교합니다. 오늘의 목적은 조작을 익히는 것보다, 조작한 결과를 보고 이 도구를 어디에 쓸지 판단하는 것입니다.

마지막에는 8강과 9강에서 사용할 두 방식까지 함께 놓고 무엇이 다른지 확인합니다.

Claude는 Anthropic이 제공하는 대화형 AI 서비스입니다. 입력한 문장을 바탕으로 답변 문장을 생성합니다. 문장을 생성하는 것이지 사실을 조회하는 것이 아니므로, 생성된 내용이 맞는지는 사람이 확인해야 합니다. 오늘 실습의 세 번째 절에서 이 차이를 직접 보게 됩니다.

0.2 이번 강의 실습 내용

6강까지 마친 study-notes Vault. notes 폴더에 study-plan, study-log, obsidian-setup 세 노트가 있어야 합니다. obsidian-setup은 6강에서 직접 작성한 노트이며, 만들지 못했으면 강사가 배부하는 예시 노트를 notes 폴더에 넣고 시작합니다.
웹 브라우저
강사가 안내하는 Claude 구독 계정. 8강의 폴더 연결과 9강의 Claude Code는 이 계정으로 진행합니다.

⚠ 주의: 실습실 PC는 여러 사람이 함께 쓰는 컴퓨터입니다. 오늘 로그인한 계정은 수업이 끝날 때 반드시 로그아웃하세요. 마지막 절에서 절차를 안내합니다.

1. Claude 웹에 로그인하고 화면 구성 확인하기

→ claude.ai에 로그인하고, 질문을 보내기 전에 화면에서 네 곳의 위치를 확인합니다.

1.1 claude.ai에 로그인하기

브라우저에서 다음 주소를 엽니다.

https://claude.ai

안내에 따라 로그인합니다. 로그인 방식은 계정을 만든 방법에 따라 다르므로, 자기 계정에 맞는 방식을 고르세요. 로그인이 끝나면 대화 화면이 열립니다.

증상	원인	해결 방법
로그인 화면에서 더 진행되지 않는다	인증 메일 또는 인증 번호를 확인하지 않음	계정을 만들 때 사용한 메일함을 확인한다

1.2 화면 네 곳의 위치 확인하기

질문을 보내기 전에 화면에서 네 곳을 찾아 두면 이후 조작이 수월합니다.

찾을 것	대략적인 위치	하는 일
입력창	화면 가운데 아래	질문을 입력하고 보낸다
새 대화 시작	화면 왼쪽 위	이전 내용과 이어지지 않는 새 대화를 만든다
지난 대화 목록	화면 왼쪽	이전에 나눈 대화를 다시 연다
모델 선택	입력창 근처	답변 생성에 사용할 모델을 고른다

모델 선택 항목을 눌러 지금 선택되어 있는 모델 이름을 화면에서 확인하고 적어 두세요. 모델은 시기와 요금제에 따라 추가되거나 이름이 바뀌므로, 이 자료에는 특정 모델 이름을 적어 두지 않습니다. 앞으로 7강·8강·9강에서 실습 결과를 노트에 기록할 때는 그때 자기 화면에 표시된 이름을 그대로 적습니다. 같은 질문이라도 모델에 따라 답변의 길이와 상세함이 달라지므로, 나중에 기록을 다시 볼 때 어떤 조건에서 나온 답변인지 알 수 있어야 합니다.

화면 구성은 서비스가 갱신되면서 바뀔 수 있습니다. 위 표의 이름과 다르게 보이면 강사의 시연 화면을 기준으로 하세요.

증상	원인	해결 방법
모델 선택 항목이 보이지 않는다	화면 폭이 좁아 항목이 접혀 있음	브라우저 창을 넓히거나 입력창 근처의 접힌 메뉴를 펼친다
지난 대화가 목록에 없다	다른 계정으로 로그인함	화면 왼쪽 아래에서 로그인된 계정을 확인한다

네 곳을 모두 찾았으면 첫 번째 학습 목표를 확인한 것입니다.

2. 질문을 보내고 답변이 매번 생성되는 것 확인하기

→ 질문을 세 번 보내, 같은 대화에서 이어 묻는 경우와 새 대화에서 다시 묻는 경우를 비교합니다.

2.1 첫 질문을 보내고 답변 형식 확인하기

입력창에 다음 질문을 그대로 입력하고 보냅니다.

클로드 프롬프트

# 마크다운 표 문법 질문
마크다운에서 표를 만드는 문법을 알려줘.
예시도 한 개 보여줘.

답변이 생성되는 동안 화면에 글자가 이어져 나타납니다. 답변이 끝나면 다음 세 가지를 확인하세요.

첫째, 답변 안의 예시가 코드 블록으로 표시되어 있습니다. 5강에서 확인한 대로 답변도 마크다운 구조로 생성됩니다.

둘째, 코드 블록 오른쪽 위에 복사 버튼이 있습니다. 눌러서 복사한 뒤 Obsidian의 아무 노트에 붙여 넣으면 그대로 표가 됩니다. 두 도구가 같은 형식을 쓰기 때문에 변환 과정이 필요 없습니다.

셋째, 6강에서 입력한 표 문법과 답변의 예시를 비교해 보세요. 같은 문법인지 확인하는 것이 이 조작의 핵심입니다. 답변을 읽고 넘어가는 것이 아니라, 이미 아는 내용과 맞춰 보는 것입니다.

2.2 같은 대화에서 이어 묻기

대화를 닫지 말고 같은 입력창에 이어서 다음을 입력합니다.

클로드 프롬프트

# 앞 답변에 이어서 질문
방금 예시에서 두 번째 줄은 왜 필요해?

앞 질문에서 "예시"가 무엇인지 다시 설명하지 않았는데도 그 내용을 이어받은 답변이 생성됩니다. 한 대화 안에서는 앞서 주고받은 문장이 함께 전달되기 때문입니다.

이 성질은 두 가지를 뜻합니다. 관련된 질문은 한 대화 안에서 이어서 하는 편이 편리하고, 반대로 주제가 다른 질문을 같은 대화에 계속 이어 붙이면 앞의 내용이 뒤 답변에 영향을 줍니다. 주제가 바뀌면 새 대화를 시작하세요.

2.3 새 대화에서 같은 질문 다시 보내 비교하기

왼쪽 위의 새 대화 시작을 눌러 새 대화를 만들고, 앞에서 보냈던 첫 질문을 그대로 다시 입력해 보냅니다.

두 답변을 나란히 놓고 비교하세요. 문법 설명의 핵심은 같더라도 문장 표현, 예시에 쓰인 낱말, 설명 순서가 달라질 수 있습니다. 똑같은 답변이 나올 수도 있습니다.

여기서 확인할 것은 어느 답변이 더 좋은가가 아닙니다. 답변이 미리 정해진 항목에서 꺼내 오는 것이 아니라 매번 생성된다는 점입니다. 그래서 어제 받은 답변과 오늘 받은 답변이 다를 수 있고, 옆자리 학습자의 화면과 내 화면이 다를 수 있습니다. 답변 자체를 근거 자료로 저장해 두는 것이 아니라, 답변을 확인한 결과를 자기 노트에 기록해야 하는 이유가 여기에 있습니다. 이것이 두 번째 학습 목표입니다.

3. 근거를 주지 않은 답변과 근거를 준 답변을 대조해 사용 규칙 정하기

→ 근거 없이 물은 질문과 근거를 함께 준 질문의 답변을 대조하고, 사용 규칙을 study-log 노트에 기록합니다.

3.1 근거 없이 물었을 때의 답변 확인하기

앞 절에서는 마크다운 문법처럼 널리 알려진 내용을 물었습니다. 이번에는 우리 수업 자료에만 있는 내용을 물어 무엇이 달라지는지 확인합니다.

새 대화를 하나 더 만들고 다음을 입력합니다.

클로드 프롬프트

# 근거 없이 5강 내용 질문
내가 듣는 과정의 5강에서 무엇을 배웠는지 알려줘.

답변을 읽고, 5강에서 실제로 한 것과 맞는지 대조하세요. 5강에서 우리가 한 것은 세 가지입니다. CommonMark 변환기에 예시를 입력해 #이 <h1>으로 -가 <li>로 바뀌는 것을 HTML 결과에서 확인했고, 같은 입력의 표가 표로 변환되지 않는 것을 확인해 그 원인이 오타가 아니라 규칙 범위 차이라고 판단했으며, 이 과정이 GitHub이 쓰는 범위를 기준으로 삼는다고 정했습니다.

이 질문에는 답변에 필요한 정보가 들어 있지 않습니다. 어느 기관의 어떤 과정인지, 5강 자료에 무엇이 적혀 있는지가 전달되지 않았기 때문입니다. 그런데도 답변은 생성됩니다. 문장이 자연스럽게 이어지기 때문에 읽는 사람이 그럴듯하다고 느끼기 쉽지만, 우리 수업 자료와 일치하는지는 자료를 직접 대조해야 알 수 있습니다.

3.2 근거를 함께 준 질문으로 다시 물어보기

같은 대화에 질문을 다시 보냅니다. 이번에는 5강에서 실제로 확인한 내용을 질문에 함께 적습니다.

클로드 프롬프트

# 근거를 포함한 5강 내용 검증 질문
내가 5강에서 확인한 것은 다음 세 가지야.
1. CommonMark 변환기에 넣은 표가 표로 변환되지 않았다.
2. 그 이유는 CommonMark 규칙에 표 문법이 없기 때문이다.
3. GFM은 CommonMark에 표와 체크리스트를 더한 규칙이다.
이 세 문장에 틀린 부분이 있으면 지적해줘.

두 답변의 차이를 보세요. 앞의 질문은 확인할 근거가 없는 상태에서 답변이 생성되었고, 뒤의 질문은 확인할 대상이 질문 안에 들어 있습니다. 뒤쪽이 학습에 쓸 수 있는 형태입니다.

8강에서는 이 방식을 한 단계 더 진행합니다. 질문에 근거를 일일이 적어 넣는 대신 학습 자료 폴더를 통째로 연결해서, 폴더 안의 노트를 근거로 답변이 생성되도록 합니다.

3.3 study-log 노트에 사용 규칙 적기

오늘 조작한 결과를 근거로 자기 규칙을 정합니다. Obsidian에서 notes 폴더의 study-log 노트를 열고 다음 형식으로 기록하세요.

### 7강. Claude 사용 규칙

- 사용한 모델:
- 근거를 주지 않은 질문의 답변에서 우리 수업 내용과 달랐던 문장:
- 근거를 함께 준 질문에서 달라진 점:
- 앞으로 Claude에 물을 것:
- 앞으로 Claude에 묻지 않을 것:

다섯 줄을 채웁니다. 두 번째 줄은 근거 없이 물었을 때의 답변에서 5강에서 실제로 한 것과 다른 문장을 찾아 그대로 옮겨 적습니다. 다른 문장이 없었다면 "없었음"이라고 적고, 대신 답변에 우리 수업 자료에 없는 내용이 들어 있었는지 한 줄로 적습니다.

핵심: 이 과정에서 AI 도구는 답을 받는 곳이 아니라 내가 정리한 것을 검토하는 데 쓰는 도구입니다. 답변을 채택할지 판단하고 그 결과에 책임지는 것은 사람입니다.

마지막 두 줄은 특히 자기 문장으로 정리해 두세요. 생성된 답변을 확인 없이 과제로 제출하면 두 가지 문제가 생깁니다. 내용이 실제와 다를 때 그것을 알아차릴 방법이 없고, 무엇보다 확인하는 과정 자체가 학습이므로 그 부분을 건너뛰면 남는 것이 없습니다. 여기까지가 세 번째 학습 목표입니다.

4. Obsidian과 함께 쓰는 세 가지 방식 비교하기

→ 오늘 방식과 8강·9강에서 쓸 두 방식을 근거 전달 방법 기준으로 비교합니다.

4.1 세 방식을 조작 화면과 근거 기준으로 표로 비교하기

오늘 사용한 방식은 세 가지 중 하나입니다. 나머지 두 가지는 8강과 9강에서 각각 사용합니다. 지금 셋을 나란히 놓고 무엇이 다른지 확인해 두면, 다음 두 강의에서 설치하는 것이 무엇이고 왜 필요한지 알 수 있습니다.

방식	조작하는 화면	답변의 근거가 되는 것	준비물	다루는 강의
노트 내용을 웹 화면에 붙여넣기	브라우저의 claude.ai	내가 대화창에 직접 붙여 넣은 문장	브라우저와 Claude 계정	7강(오늘)
데스크톱 앱에 폴더 연결	Ubuntu에 설치한 Claude 데스크톱 앱	연결한 `study-notes` 폴더 안의 노트 파일	데스크톱 앱 설치, 유료 구독 계정	8강
Obsidian 안의 대화 패널	Obsidian 화면 오른쪽 패널	지금 열어 둔 노트에서 마우스로 선택한 부분과 `@`로 지정한 노트	Claude Code 설치와 로그인, Claudian 커뮤니티 플러그인 설치	9강

세 방식의 차이는 성능이 아니라 근거를 전달하는 방법에 있습니다.

4.2 방식별 장단점 판단하기

오늘 한 방식은 내가 무엇을 근거로 줄지 직접 고르므로 통제하기 쉽지만, 노트가 늘어나면 매번 찾아서 붙여 넣는 시간이 길어집니다. 폴더 연결 방식은 폴더 전체가 대상이 되므로 붙여 넣을 필요가 없지만, 어느 노트가 근거로 쓰였는지 답변에 표시된 파일 이름을 열어서 확인하는 절차가 필요합니다. Obsidian 안의 패널 방식은 읽던 노트에서 곧바로 물을 수 있어 흐름이 끊기지 않지만, 설치할 것이 가장 많습니다.

어느 방식을 쓰든 답변을 원본 자료와 대조해 확인하는 절차는 똑같이 필요합니다. 세 방식은 근거를 전달하는 방법만 다를 뿐, 생성된 답변이 확인 전까지 확정되지 않은 정보라는 점은 달라지지 않습니다. 대조를 실제로 어떤 순서로 하는지는 8강에서 절차로 정리하고, 9강도 같은 절차를 씁니다.

study-log 노트의 오늘 기록 아래에 이 표에서 확인한 것을 한 줄로 적으세요. 8강과 9강을 마친 뒤 세 방식 중 자기 학습에 어느 것을 주로 쓸지 판단하게 됩니다. 이것이 네 번째 학습 목표입니다.

5. 오늘 확인한 것을 점검하고 로그아웃하기

→ 네 가지 확인 항목을 점검하고, 실습실 공용 PC에서 반드시 로그아웃합니다.

5.1 네 가지 확인 항목 점검하기

다음 네 가지가 모두 확인되면 7강에서 확인해야 할 것을 확인한 것입니다.

화면에서 입력창, 새 대화 시작, 지난 대화 목록, 모델 선택 네 곳의 위치를 찾았습니다.
새 대화에서 같은 질문을 다시 보냈을 때 답변이 앞의 것과 어떻게 달랐는지 말할 수 있습니다.
study-log 노트에 ### 7강. Claude 사용 규칙 항목이 있고 다섯 줄이 모두 채워져 있습니다.
세 가지 사용 방식이 근거를 전달하는 방법에서 어떻게 다른지 한 줄로 적었습니다.

5.2 로그아웃 절차 수행하기

확인이 끝나면 로그아웃합니다. 실습실 PC는 여러 사람이 함께 쓰는 컴퓨터이므로 이 절차를 빼먹지 마세요.

화면 왼쪽 아래 계정 항목에서 로그아웃을 선택합니다.
브라우저를 닫았다가 다시 열어 https://claude.ai에 접속합니다.
로그인 화면이 나오면 로그아웃된 것입니다. 대화 화면이 바로 열리면 아직 로그인 상태이므로 1번부터 다시 합니다.

증상	원인	해결 방법
로그아웃했는데 다시 접속하니 대화 화면이 열린다	브라우저에 다른 탭이 열려 있거나 로그아웃이 적용되지 않음	브라우저를 완전히 닫았다가 다시 열어 확인한다

⚠ 주의: 대화 내용에 전화번호, 주소, 다른 사람의 개인정보를 입력하지 않는 것도 함께 지킵니다. 공용 PC에 로그인 상태를 남기면 다음 사용자가 내 대화 목록을 그대로 볼 수 있습니다.

✔ 정리: Claude 웹 화면의 네 위치를 확인하고, 답변이 저장된 항목이 아니라 매번 생성된다는 것을 확인했으며, 근거를 준 질문과 주지 않은 질문의 답변을 대조해 Claude 사용 규칙을 study-log 노트에 정리했습니다.

오늘은 질문에 필요한 근거를 문장으로 직접 적어 넣었습니다. 노트가 늘어나면 이 방식은 곧 한계에 부딪힙니다.

→ 다음 개별 강의

8강에서는 Claude 데스크톱 앱을 설치해 study-notes 폴더를 통째로 연결하고, 폴더 안의 노트를 근거로 질문합니다. 답변에 어느 노트를 근거로 삼았는지가 함께 표시되므로, 원본과 대조하는 절차까지 함께 배웁니다. 9강에서는 앞의 표에서 확인한 세 번째 방식을 사용해 Obsidian 안에 대화 패널을 열고 질문합니다.

6. 마크다운 기본 문법

BasicLike — Tue, 28 Jul 2026 11:47:55 +0900

6강 구현 중심 ⏱ 약 60분

0. 학습 목표

→ 5강에서 확인한 마크다운 문법을 직접 입력하고, 배운 문법을 모두 사용해 노트를 직접 작성합니다.

0.1 이번 글에서 다룰 내용

제목, 문단, 강조, 목록, 체크리스트, 코드 블록, 표 문법을 study-log 노트에 직접 입력하고 읽기 모드에서 표시 결과를 확인
위키링크 설정을 끄고 첨부 파일 폴더를 assets로 지정한 뒤, 표준 마크다운 링크로 노트를 연결하고 화면 사진을 노트에 삽입
빠른 전환(Ctrl+O)과 전체 검색(Ctrl+Shift+F)으로 원하는 노트와 문장을 찾고, 파일 이름을 영문 소문자와 붙임표로 짓는 규칙의 이유를 15강과 연결해 설명
배운 문법을 모두 사용해 1강 내용을 정리한 노트 obsidian-setup을 예시 없이 직접 작성

4강에서 study-log 노트를 만들 때 #을 붙인 줄이 제목이 되고 -를 붙인 줄이 목록이 되는 것을 봤습니다. 5강에서는 이 기호 규칙이 마크다운이라는 이름으로 문서에 정의되어 있고, GitHub을 비롯한 여러 서비스가 이 형식을 그대로 사용한다는 것을 확인했습니다.

오늘은 그 문법을 직접 입력합니다. 배부받은 예시 노트를 보면서 문법을 하나씩 입력해 표시 결과를 확인하고, 마지막에 배운 문법을 모두 사용해 1강 내용을 정리한 노트를 스스로 작성합니다. 오늘 작성하는 노트는 8강에서 Claude에 질문할 때 근거 자료로 사용합니다.

0.2 이번 강의 실습 내용

5강까지 마친 상태의 Obsidian과 study-notes Vault
notes 폴더의 study-log 노트(4강에서 만든 노트입니다. 없다면 4강의 학습일지 노트를 만드는 절부터 다시 진행하세요)
reference 폴더의 markdown-syntax 노트(배부 자료에 들어 있습니다)

이 강의에서 study-log는 파일 이름이고, 그 노트의 첫 줄에 적힌 제목은 "학습일지"입니다. 파일 이름과 문서 제목이 다른 이유는 세 번째 절에서 설명합니다.

1. study-log 노트에 markdown 기본 문법 사용하기

→ 제목, 문단, 강조, 목록, 체크리스트, 코드 블록, 표 일곱 가지를 직접 입력하고 결과를 확인합니다.

1.1 예시 노트를 보며 연습하는 순서 확인하기

reference 폴더의 markdown-syntax 노트(제목: 마크다운 기본 문법 예시)를 사용합니다. 이 노트에는 오늘 다루는 문법이 번호가 붙은 절로 전부 정리되어 있습니다.

연습은 세 단계를 반복합니다.

markdown-syntax 노트에서 해당 번호의 절을 편집 모드로 봅니다. 기호가 그대로 보이는 상태입니다.
Ctrl+E로 읽기 모드로 바꿔 그 기호가 어떤 모양으로 표시되는지 확인합니다.
study-log 노트로 돌아가 같은 문법을 직접 입력하고 결과를 확인합니다.

눈으로 읽기만 하면 문법은 익혀지지 않습니다. 반드시 3단계까지 직접 입력하세요.

1.2 제목, 문단, 강조, 목록, 체크리스트를 study-log 노트에 입력하기

markdown-syntax 노트의 1번(제목), 2번(문단과 줄바꿈), 3번(강조), 4번(목록), 5번(체크리스트) 절을 차례로 확인한 뒤, study-log 노트 맨 아래에 오늘 분량을 직접 입력합니다.

## 6강. 마크다운 문법

마크다운은 텍스트 파일에 기호로 구조를 표현하는 형식이다.

문단을 나누려면 **빈 줄**이 필요하다. 명령은 `git --version`처럼 백틱으로 감싼다.

### 이번 주 할 일

- [x] 1강 Obsidian 설치
- [ ] 6강 마크다운 문법 연습
- [ ] 1강 정리 노트 작성

입력한 뒤 Ctrl+E로 읽기 모드에서 확인할 것이 세 가지입니다. ##로 시작한 줄이 중간 크기 제목으로 표시되는지, 두 문장이 서로 다른 문단으로 나뉘는지, 체크박스가 네모 모양으로 표시되는지입니다.

확인이 끝나면 두 가지를 일부러 바꿔 보세요. 첫째, 문단 사이의 빈 줄을 지우면 두 문장이 한 문단으로 붙습니다. 둘째, 읽기 모드에서 체크박스를 마우스로 누른 뒤 편집 모드로 돌아가면 [ ]가 [x]로 바뀌어 있습니다. 화면 조작이 결국 텍스트 기호를 바꾸는 일이라는 것을 확인할 수 있습니다.

증상	원인	해결 방법
제목이 제목 모양으로 표시되지 않는다	`#`과 글자 사이에 공백이 없음	`#` 뒤에 공백 한 칸을 넣는다

강조가 적용되지 않는다면 백틱과 작은따옴표를 혼동한 경우가 가장 많습니다. 백틱(`)은 숫자 1 왼쪽, Esc 아래에 있는 키이고 작은따옴표(')는 Enter 왼쪽에 있는 키입니다.

1.3 코드 블록과 표 입력하기

markdown-syntax 노트의 6번(코드 블록)과 8번(표) 절을 확인합니다. 이 두 문법은 앞으로 모든 과목에서 명령과 정리 내용을 기록할 때 계속 사용합니다.

study-log 노트에 1강에서 사용한 설치 명령과 오늘 배운 기호를 이어서 입력합니다.

### 1강에서 사용한 설치 명령

```bash
sudo snap install obsidian --classic
```

### 오늘 배운 기호

| 기호 | 역할 |
|---|---|
| `#` | 제목 |
| `-` | 목록 |
| `**` | 굵게 |

코드 블록은 백틱 세 개로 감싸고 첫 줄에 언어 이름(bash, python 등)을 적습니다. 언어 이름을 적어야 읽기 모드에서 문법에 맞는 색이 입혀집니다.

표가 그려지지 않으면 두 번째 줄(|---|---|)이 빠졌거나 줄마다 | 개수가 다른 경우가 대부분입니다. 두 번째 줄을 일부러 지워 표가 깨지는 것을 확인한 뒤, 되돌려서 다시 그려지는 것까지 확인하세요.

증상	원인	해결 방법
표가 그려지지 않는다	구분 줄이 없거나 줄마다 세로줄 개수가 다름	두 번째 줄과 각 줄의 세로줄 개수를 대조한다

여기까지가 첫 번째 학습 목표입니다.

2. 표준 마크다운 링크로 노트를 연결하고 화면 사진 삽입하기

→ 위키링크 설정을 끄고 첨부 파일 폴더를 지정한 뒤, 노트 링크와 화면 사진을 실제로 삽입합니다.

2.1 위키링크 설정을 끄고 첨부 파일 폴더 지정하기

노트가 늘어나면 관련된 노트끼리 연결해 두어야 찾아다니기 쉽습니다. 링크와 이미지를 입력하기 전에 설정 두 가지를 먼저 바꿉니다.

Obsidian에는 두 가지 링크 형식이 있습니다.

[[노트이름]] 형식(위키링크)은 입력이 편하지만 Obsidian 안에서만 동작합니다. [표시할 글자](경로) 형식(표준 마크다운 링크)은 어떤 프로그램에서나 동작하고, 15강에서 노트를 웹 사이트로 게시할 때도 이 형식만 링크로 변환됩니다. 그래서 이 과정에서는 표준 마크다운 링크를 사용합니다.

왼쪽 아래 톱니바퀴 모양의 [Settings](설정) 버튼을 누릅니다.
왼쪽 목록에서 [Files and links](파일 및 링크)를 선택합니다.
[Use [[Wikilinks]]](위키링크 사용) 항목의 스위치를 끕니다.
같은 화면에서 [Default location for new attachments](새 첨부 파일 기본 위치) 항목을 [In the folder specified below](아래에 지정한 폴더)로 바꿉니다.
바로 아래에 나타나는 [Attachment folder path](첨부 파일 폴더 경로)에 assets를 입력합니다.
설정 창을 닫습니다.

⚠ 주의: 위키링크 설정을 켠 채로 두면 링크와 이미지가 모두 위키링크 형식으로 만들어집니다. 반드시 끄고 진행하세요. 첨부 파일 폴더를 지정하지 않으면 이미지가 Vault 최상위 폴더에 흩어져 쌓입니다.

assets 폴더는 아직 없어도 됩니다. 첫 이미지를 넣는 순간 Obsidian이 그 이름으로 폴더를 만듭니다.

2.2 표준 마크다운 링크 입력하기

study-log 노트에 예시 노트로 가는 링크를 입력합니다. 괄호 안의 경로는 지금 편집 중인 파일의 위치를 기준으로 적습니다.

문법이 기억나지 않으면 [마크다운 문법 예시](../reference/markdown-syntax.md)를 참조한다.

읽기 모드에서 이 링크를 누르면 예시 노트가 열립니다. ../는 한 단계 위 폴더로 올라간다는 뜻입니다. study-log는 notes 폴더에 있고 예시 노트는 reference 폴더에 있으므로, 위로 한 단계 올라갔다가 reference로 내려가는 경로가 됩니다.

편집 모드에서는 링크를 그냥 클릭해도 이동하지 않습니다. Ctrl 키를 누른 채 클릭하거나 Ctrl+E로 읽기 모드로 바꾼 뒤 클릭하세요.

2.3 화면 사진을 노트에 삽입하기

설치 화면이나 오류 메시지는 글로 옮겨 적는 것보다 화면 사진을 그대로 붙여 두는 편이 정확합니다. markdown-syntax 노트의 10번(이미지) 절을 확인한 뒤 직접 해 봅니다.

obsidian-screen.png

0.03MB

Obsidian 본 화면이 보이는 상태에서 PrtSc 키를 눌러 화면 사진을 찍습니다. Ubuntu의 화면 사진 도구가 열리면 영역을 선택하고 저장합니다. 사진은 홈 폴더의 [사진] 폴더에 저장됩니다.
파일 관리자에서 방금 저장된 파일의 이름을 obsidian-screen.png로 바꿉니다. 파일 이름에 한글이나 공백이 들어가면 노트에 삽입될 때 주소가 %EC%82%AC... 같은 문자로 바뀌므로, 지금 영문으로 바꿔 두는 것입니다.
Obsidian에서 study-log 노트를 편집 모드로 열고, 파일 관리자에서 obsidian-screen.png 파일을 노트의 원하는 위치로 끌어다 놓습니다.

편집 모드에서 삽입된 문장을 확인하세요. 다음과 같은 형태여야 합니다.

![](../assets/obsidian-screen.png)

느낌표로 시작하면 링크가 아니라 이미지 삽입입니다. 대괄호 안은 비어 있거나 파일 이름이 들어가 있을 수 있습니다. 이 자리는 이미지가 표시되지 않을 때 대신 나타나는 설명이므로 Obsidian 본 화면처럼 알아볼 수 있는 말로 고쳐 적습니다. 괄호 안의 경로가 ../assets/로 시작하면 앞에서 지정한 첨부 폴더 설정이 적용된 것입니다.

왼쪽 파일 목록에 assets 폴더가 새로 생기고 그 안에 obsidian-screen.png가 들어 있으면 첨부 폴더 설정이 적용된 것입니다.

증상	원인	해결 방법
링크를 눌러도 이동하지 않는다	경로 오타 또는 편집 모드에서 클릭함	괄호 안 경로와 실제 파일 이름을 대조한다. 편집 모드에서는 `Ctrl`을 누른 채 클릭한다
링크나 이미지가 대괄호 두 개 형식으로 만들어진다	위키링크 설정이 켜져 있음	[Settings] → [Files and links]에서 위키링크 사용 항목을 껐는지 다시 확인한다
이미지가 `assets` 폴더가 아닌 곳에 저장된다	첨부 파일 폴더 경로를 지정하지 않음	[Files and links]에서 첨부 파일 폴더 경로가 `assets`인지 확인한다

여기까지가 두 번째 학습 목표입니다.

3. 노트가 늘어난 뒤 원하는 내용을 찾는 방법과 파일 이름 규칙 확인하기

→ 빠른 전환과 전체 검색으로 노트를 찾고, 파일 이름을 영문 소문자로 짓는 이유를 확인합니다.

3.1 빠른 전환과 전체 검색으로 노트 찾기

오늘까지는 노트가 몇 개뿐이라 파일 목록에서 눈으로 찾을 수 있습니다. 그러나 7개월 동안 노트가 쌓이면 목록을 훑는 방식은 곧 한계에 부딪힙니다.

파일 이름을 알고 있을 때는 빠른 전환을 사용합니다. Ctrl+O를 누르고 study를 입력하면 이름에 그 글자가 들어간 노트 목록이 나타나며, 방향키로 선택하고 Enter를 누르면 해당 노트가 열립니다. 파일 목록에서 폴더를 펼쳐 찾는 것보다 빠릅니다.

파일 이름은 기억나지 않고 내용의 한 구절만 기억날 때는 전체 검색을 사용합니다. Ctrl+Shift+F를 누르면 왼쪽에 검색 창이 열립니다. 마크다운을 입력해 보세요. Vault 안의 모든 노트에서 그 낱말이 포함된 줄이 파일별로 표시되고, 결과 줄을 누르면 해당 위치로 이동합니다.

두 기능을 구분해 두면 좋습니다. Ctrl+O는 파일 이름으로 찾고, Ctrl+Shift+F는 노트 내용으로 찾습니다. 지금 두 기능을 각각 한 번씩 사용해 markdown-syntax 노트를 열어 보세요.

3.2 파일 이름을 영문 소문자로 짓는 이유 확인하기

배부받은 폴더의 index 노트에 적힌 규칙 중 하나가 파일 이름 규칙입니다. 내가 만드는 노트의 파일 이름은 영문 소문자와 붙임표(-)로만 짓습니다.

이 규칙이 필요한 이유는 15강에 있습니다. 이 폴더가 웹 사이트로 게시되면 파일 이름이 그대로 웹 주소가 됩니다. 한글 파일 이름도 동작은 하지만 주소가 %EB%A7%88%ED%81%AC... 같은 알아볼 수 없는 문자로 바뀌어 길어지고, 다른 사람에게 주소를 전달하기 어려워집니다.

파일 이름과 문서 제목은 서로 다르게 지어도 됩니다. 파일 이름은 웹 주소가 되므로 영문으로 짓고, 문서 첫 줄의 1단계 제목은 사람이 읽는 이름이므로 한국어로 적습니다. study-log 노트의 제목이 "학습일지"인 것이 그 예입니다. 여기까지가 세 번째 학습 목표입니다.

4. 배운 문법으로 1강 정리 노트 obsidian-setup 직접 작성하기

→ 예시를 보지 않고 배운 문법을 모두 사용해 1강 내용을 정리한 노트를 작성합니다.

4.1 작성 조건에 맞춰 obsidian-setup 노트 작성하기

이제 배운 문법을 모두 사용해, 예시를 보지 않고 자기 노트를 작성합니다.

notes 폴더에 obsidian-setup이라는 이름으로 새 노트를 만들고, 1강에서 배운 내용(Obsidian 설치와 학습 자료 폴더를 Vault로 여는 과정)을 다음 조건에 맞게 정리하세요. 내용은 옮겨 적지 말고 자기 말로 씁니다.

1단계 제목 1개와 2단계 제목 2개 이상을 사용한다.
목록 또는 체크리스트를 1개 이상 사용한다.
굵은 글씨와 인라인 코드를 각각 1회 이상 사용한다.
1강에서 사용한 설치 명령을 코드 블록으로 1개 이상 기록한다.
표를 1개 이상 사용한다.
앞에서 삽입해 본 화면 사진을 이 노트에도 1개 삽입한다.
study-log 노트에 이 노트로 가는 표준 마크다운 링크를 추가한다. 두 파일이 같은 notes 폴더에 있으므로 경로는 (obsidian-setup.md)입니다.

이 노트는 8강과 9강에서 Claude에 검토를 요청할 때 근거 자료로 사용합니다. 성의 있게 쓸수록 그때 대조할 수 있는 내용이 많아집니다. 이것이 네 번째 학습 목표입니다.

5. 오늘 만든 상태를 확인하고 7강 학습으로 연결하기

→ 오늘 만든 노트의 상태를 점검하고, 7강에서 이어질 Claude 활용 학습을 확인합니다.

5.1 오늘 만든 상태 점검하기

다음 다섯 가지가 모두 확인되면 6강에서 만들어야 할 상태가 갖춰진 것입니다.

study-log 노트를 읽기 모드로 열었을 때 제목, 문단, 강조, 목록, 체크리스트, 코드 블록, 표가 모두 의도한 모양으로 표시됩니다.
왼쪽 파일 목록에 assets 폴더가 있고 그 안에 obsidian-screen.png가 있습니다.
obsidian-setup 노트를 읽기 모드로 열었을 때 작성 조건 1~6의 요소가 모두 의도한 모양으로 표시됩니다.
study-log의 링크를 읽기 모드에서 누르면 obsidian-setup 노트가 열리고, 편집 모드에서 그 링크가 [글자](경로) 형식으로 되어 있습니다.
파일 관리자에서 홈 폴더의 study-notes/notes 폴더를 열면 obsidian-setup.md 파일이 실제로 있습니다.

하나라도 확인되지 않으면 해당 문법을 다룬 절로 돌아가 다시 진행하세요.

오늘 강의를 마친 뒤의 학습 자료 폴더 상태

study-notes/notes/
├── study-plan.md         #   4강에서 작성 완료
├── study-log.md           # ✏️ 이번 강의에서 문법 입력과 링크 추가
└── obsidian-setup.md      # ✏️ 이번 강의에서 새로 작성

study-notes/assets/
└── obsidian-screen.png    # ✏️ 이번 강의에서 삽입

✔ 정리: 제목, 문단, 강조, 목록, 체크리스트, 코드 블록, 표를 study-log 노트에 직접 입력해 확인했고, 표준 마크다운 링크와 화면 사진을 노트에 삽입했으며, 배운 문법을 모두 사용해 obsidian-setup 노트를 직접 작성했습니다.

오늘 작성한 obsidian-setup 노트를 다시 읽어 보면 정리가 정확한지 스스로 확신하기 어려운 부분이 남아 있을 것입니다. 이런 부분을 확인할 때 AI 도구를 사용합니다.

→ 다음 개별 강의

7강에서는 Claude 웹 화면에 직접 로그인해 첫 질문을 보내고, 근거를 주지 않은 답변과 근거를 함께 준 답변이 어떻게 다른지 확인한 뒤 이 과정에서 사용할 규칙을 정합니다. 8강에서는 이 학습 자료 폴더를 Claude 데스크톱 앱에 연결해 오늘 만든 노트를 근거로 질문하고, 답변을 원본과 대조하는 절차를 배웁니다.

5강. 마크다운이란?

BasicLike — Tue, 28 Jul 2026 10:08:17 +0900

5강 구현 중심 ⏱ 약 15분

0. 학습 목표

→ 마크다운 기호가 문서 구조로 바뀌는 과정을 확인하고, 이 과정에서 사용할 문법 범위를 정합니다.

0.1 이번 글에서 다룰 내용

4강에서 첫 노트를 만들 때 #을 붙인 줄이 제목이 되고 -를 붙인 줄이 목록이 되는 것을 봤습니다.

그 기호 규칙의 이름이 마크다운입니다.

3강에서는 워드 문서의 서식 정보가 word/styles.xml이라는 별도 파일에 들어 있고, 그것을 읽어 화면에 조립하는 프로그램이 있어야 문서를 볼 수 있다는 것을 확인했습니다. 마크다운은 서식을 별도 파일에 두지 않고 글자 사이에 기호로 적습니다. 그러면 그 기호를 누가 문서 구조로 바꿔 주는가가 오늘의 확인 대상입니다.

오늘은 브라우저에서 변환 결과를 두 번 확인하고, 그 결과를 근거로 이 과정에서 쓸 문법의 범위를 정합니다. 문법을 직접 입력해 노트를 쓰는 것은 6강에서 합니다.

0.2 이번 강의 실습 내용

웹 브라우저
3강에서 확인한 내용(워드 문서에 unzip -l을 실행했을 때 나온 파일 목록)
4강에서 만든 study-log 노트(마지막 과제 기록에 사용합니다)

설치할 프로그램은 없습니다.

1. CommonMark 변환기로 마크다운 기호가 HTML 구조로 바뀌는 것 확인하기

→ 변환기에 예시 문서를 입력해 #과 -가 각각 어떤 HTML 태그로 바뀌는지 확인합니다.

1.1 확인용 문서를 변환기에 입력해 HTML 결과 확인하기

CommonMark에서 제공하는 변환기를 사용합니다. 마크다운을 입력하면 변환 결과를 보여 주는 웹 페이지입니다.

브라우저에서 https://spec.commonmark.org/dingus/를 엽니다.
입력 칸에 다음 내용을 그대로 입력합니다. 화면은 왼쪽이 입력, 오른쪽이 변환 결과이며 결과를 HTML로 볼지 화면 모양으로 볼지 선택하는 탭이 있습니다. 화면 배치는 바뀔 수 있으므로 다르게 보이면 강사의 안내를 따르세요.

# 확인용 문서

- 첫 번째 항목
- 두 번째 항목

| 기호 | 역할 |
|---|---|
| # | 제목 |

결과를 HTML로 보는 탭을 선택합니다. #이 붙은 줄이 <h1>으로, -가 붙은 줄이 <li>로 바뀌어 있습니다. <h1>은 문서의 큰 제목을, <li>는 목록의 한 항목을 뜻하는 표시입니다.

여기서 확인할 것은 이 변환이 무엇을 근거로 이루어졌는가입니다. 이 페이지를 열기 위해 아무것도 설치하지 않았고, 변환기가 받은 것은 입력한 글자뿐입니다. 서식 정보가 든 별도 파일도 없었는데 제목과 목록이 구분되었습니다. 양식과 형식이 문서 밖의 프로그램이 아니라 문서 안의 글자로 들어 있기 때문입니다.

1.2 워드 문서와 마크다운의 서식 처리 방식을 표로 비교하기

3강에서 확인한 것과 나란히 놓으면 다음과 같습니다.

구분	워드 문서	마크다운
서식 정보가 있는 곳	압축 묶음 안의 별도 파일	본문 글자 사이의 기호
구조를 알아보려면	그 형식을 해석하는 프로그램이 필요하다	기호 규칙만 알면 된다
확인한 방법	`unzip -l`로 내부 파일 목록을 봐야 했다	설치 없이 웹 페이지에 붙여 넣으니 바로 구조가 나왔다

4강에서 만든 노트를 Obsidian에서 Ctrl+E로 읽기 모드로 바꿨을 때 화면 뒤에서 일어난 일도 이 변환입니다. Obsidian은 이 변환을 하는 여러 프로그램 중 하나일 뿐입니다.

2. 표 문법이 다르게 처리되는 이유를 확인하고 사용할 문법 정하기

→ 표가 변환되지 않는 이유를 규칙 범위의 차이로 판단하고, 이 과정에서 기준으로 삼을 문법 범위를 정합니다.

2.1 표가 변환되지 않는 이유 확인하기

같은 결과에서 표 부분을 봅니다. 제목과 목록과 달리 표는 표로 변환되지 않고, 세로줄 기호가 그대로 있는 문단으로 처리됩니다.

문법을 틀리게 쓴 것이 아닙니다. 이 변환기는 CommonMark 규칙만 따르는데 CommonMark에는 표 문법이 없기 때문입니다. 같은 내용을 GitHub에 올리면 표로 표시됩니다. GitHub은 표 문법이 추가된 규칙을 쓰기 때문입니다.

마크다운 규칙은 세 단계로 정리되어 왔고, 지금은 이름과 표 처리 여부만 구분해 두면 됩니다.

이름	역할	표와 체크리스트
원문 사양(2004년)	존 그루버(John Gruber)가 처음 공개한 규칙	없음
CommonMark	해석이 갈리던 부분을 없앤 규칙	없음
GitHub Flavored Markdown(GFM)	CommonMark를 그대로 포함하고 문법을 추가한 규칙	있음

앞에서 표가 변환되지 않은 이유가 이 표에 있습니다. 사용한 변환기가 CommonMark 규칙을 따랐기 때문입니다. GFM은 CommonMark에 표, 체크리스트, 취소선, 주소 자동 링크를 더한 것입니다.

2.2 이 과정에서 사용할 문법 범위를 GitHub Flavored Markdown으로 정하기

여기서 판단 하나가 나옵니다. 앞으로 "내 화면에서는 표로 보이는데 다른 데서는 안 보인다"는 상황을 만나면, 오타를 찾기 전에 그 화면이 어느 범위의 규칙을 쓰는지를 먼저 확인하면 됩니다.

핵심: 표 표시가 화면마다 다르면 오타를 찾기 전에 그 화면이 어느 범위의 마크다운 규칙을 쓰는지부터 확인합니다.

이 과정에서 작성하는 노트는 10강에서 GitHub에 올라가고 15강에서 GitHub Pages로 게시됩니다. 그래서 이 과정은 표와 체크리스트가 포함된 범위, 즉 GitHub Flavored Markdown을 기준으로 삼습니다. Obsidian도 표와 체크리스트를 표시하므로 편집 화면과 게시 결과가 어긋나지 않습니다.

2.3 참고 자료 확인하기

마크다운은 존 그루버가 2004년에 공개했고, 공식 페이지는 이 형식을 "a text-to-HTML conversion tool for web writers"(웹에 글을 쓰는 사람을 위한, 텍스트를 HTML로 바꾸는 도구)로 설명합니다. 규칙이 적어 여러 서비스가 그대로 채택했고, 이 과정에서도 6강의 Obsidian 노트, 7강부터 9강까지의 Claude 질문과 답변, 10강의 저장소 소개 문서, 12강과 13강의 Colab 텍스트 셀, 15강의 GitHub Pages 게시에서 같은 표기를 계속 사용합니다.

참고

CommonMark 변환기: https://spec.commonmark.org/dingus/
마크다운 원문 사양: https://daringfireball.net/projects/markdown/
CommonMark와 이 규칙을 사용하는 서비스 목록: https://commonmark.org
GitHub 작성 안내 문서(문법이 기억나지 않을 때 찾아볼 곳): https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax

3. 오늘 확인한 내용을 점검하고 스스로 확인할 과제 수행하기

→ 세 가지 질문으로 오늘 확인한 것을 점검하고, 과제로 study-log 노트에 결과를 기록합니다.

3.1 세 가지 질문으로 오늘 확인한 내용 점검하기

다음 세 질문에 답할 수 있으면 5강에서 확인해야 할 것을 확인한 것입니다. 답이 막히면 해당 절에서 다시 확인하세요.

아무것도 설치하지 않은 웹 페이지가 #을 제목으로 바꿀 수 있었던 이유는 무엇입니까? 3강에서 워드 문서를 열 때와 무엇이 다릅니까?
같은 표 문장이 어떤 화면에서는 표로 보이고 어떤 화면에서는 그렇지 않은 이유는 무엇입니까?
이 과정에서 기준으로 삼는 문법 범위는 어느 것이고, 그렇게 정한 이유는 무엇입니까?

3.2 스스로 확인할 과제로 study-log 노트에 결과 기록하기

강의에서 확인한 것은 #과 - 두 기호입니다. 나머지는 직접 확인해 보세요.

참고 자료의 GitHub 작성 안내 문서를 열어 아직 써 보지 않은 기호를 하나 고릅니다.
그 기호를 사용한 문장을 변환기(https://spec.commonmark.org/dingus/)에 입력하고 HTML 결과에서 어떤 표시로 바뀌는지 확인합니다.
4강에서 만든 study-log 노트에 다음 한 줄을 추가합니다. 고른 기호, 바뀐 HTML 표시, 변환되었는지 여부를 적습니다.

- 5강 과제: `>`를 입력했더니

로 바뀌었다. CommonMark 변환기에서 변환되었다.

지금까지 만든 study-log 노트 상태

study-notes/notes/
├── study-plan.md   #   4강에서 작성 완료
└── study-log.md    # ✏️ 5강 과제 한 줄 추가

변환되지 않는 기호를 골랐다면 그것도 확인 결과입니다. 그 기호가 GFM에만 있는 문법인지 앞의 표를 근거로 판단해 함께 적으세요.

✔ 정리: 아무것도 설치하지 않은 변환기가 #과 -를 각각 <h1>과 <li>로 바꾸는 것을 확인했고, 표가 변환되지 않은 이유가 오타가 아니라 CommonMark와 GFM의 규칙 범위 차이라는 것을 판단했으며, 이 과정에서 쓸 문법 범위를 GitHub Flavored Markdown으로 정했습니다.

오늘 확인한 것은 기호가 바뀌는 원리와 기준 범위입니다. 그 기호를 직접 입력해 노트를 완성하는 것은 다음 강의에서 합니다.

→ 다음 개별 강의

6강에서는 오늘 확인한 문법을 직접 입력합니다. 배부받은 reference 폴더의 markdown-syntax 노트에 문법이 절별로 정리되어 있으므로, 그 노트를 보면서 하나씩 입력하고 읽기 모드에서 표시 결과를 확인합니다. 마지막에는 배운 문법을 모두 사용해 1강 내용을 정리한 노트를 직접 작성합니다.

4강. 학습 기록 시작하기

BasicLike — Tue, 28 Jul 2026 00:29:42 +0900

4강 구현 중심 ⏱ 약 65분

0. 학습 목표

→ 폴더의 사용 순서를 확인하고, 기록 계획 노트와 학습일지 노트를 만들어 학습 기록을 시작합니다.

0.1 이번 글에서 다룰 내용

study-notes 폴더가 16강까지 사용되는 순서를 확인하고, 이 폴더에 적지 않을 내용을 판단 기준과 함께 제시
이 폴더가 16강에서 도착하는 곳을 기준으로 학습 기록에 남길 내용과 적지 않을 내용을 판단하고, 그 판단을 notes/study-plan.md에 자기 문장으로 적은 뒤 파일 관리자에서 같은 이름의 .md 파일이 실제로 생겼는지 확인
강의마다 한 일을 적는 학습일지 노트 notes/study-log.md를 만들고, 어느 내용을 어느 노트에 적을지 두 노트의 역할 구분
배부받은 강의 요약본 네 편을 lectures 폴더에 저장해, 안내 노트의 목록 링크로 각각 열리는 것을 확인

오늘 만드는 노트는 두 개입니다. 기록 계획 노트와 학습일지 노트이며, 두 노트 모두 16강까지 계속 사용합니다. 마지막으로 배부받은 1강부터 4강까지의 강의 요약본을 lectures 폴더에 저장합니다.

0.2 이번 강의 실습 내용

1강에서 설치한 Obsidian과 study-notes Vault가 열린 상태
홈 폴더의 study-notes 폴더
3강에서 확인한 내용(워드 문서와 마크다운 파일에 같은 명령을 실행했을 때 화면에 나온 것)
강사가 배부하는 강의 요약본 파일 네 개(01-obsidian-install.md, 02-text-file-check.md, 03-markdown-format.md, 04-study-notes.md)

Obsidian이 닫혀 있으면 다시 실행합니다. 마지막에 연 Vault가 그대로 열립니다. 시작 화면이 나오면 1강과 같은 방법으로 홈 폴더의 study-notes를 다시 엽니다.

1. study-notes 폴더의 사용 순서와 기록 원칙 확인하기

→ 폴더가 16강까지 사용되는 순서를 확인하고, 첫 노트를 만들기 전에 지킬 원칙 두 가지를 정합니다.

1.1 폴더가 16강까지 사용되는 순서 확인하기

1강에서 압축을 푼 study-notes 폴더 하나가 16강까지 계속 사용됩니다. 새 폴더를 만들거나 다른 곳으로 옮기지 마세요.

강의	이 폴더에서 하는 일
4강	기록 계획 노트와 학습일지 노트를 만들고, 배부받은 요약본을 `lectures` 폴더에 저장한다
6강	마크다운 문법으로 `notes` 폴더에 학습 노트를 작성한다
8강, 9강	이 폴더를 Claude에 연결해 자료를 근거로 질문한다
10강	이 폴더를 Git 저장소로 만들어 GitHub에 올린다
15강	이 폴더를 주소로 접속할 수 있는 공개 사이트로 만든다
16강	그 주소를 면접이나 평가에서 제시할 수 있는 상태로 정리한다

이 순서에서 지켜야 할 원칙이 두 가지 나옵니다. 첫 노트를 만들기 전에 확인합니다.

증상	원인	해결 방법
Obsidian을 실행했는데 시작 화면이 나온다	마지막에 연 Vault 정보가 남아 있지 않음	1강과 같은 방법으로 [Open folder as vault]에서 홈 폴더의 `study-notes`를 다시 연다

1.2 인터넷에 공개되는 폴더에 적지 않을 내용 확인하기

15강에서 만드는 사이트는 주소를 아는 사람이면 누구나 볼 수 있습니다. 10강에서 GitHub에 올리는 시점부터 이미 공개 상태가 됩니다. 그러므로 다음 내용은 이 폴더 안의 어떤 파일에도 적지 않습니다.

전화번호, 주소, 주민등록번호 같은 개인정보
계정 아이디와 비밀번호
GitHub 개인 접근 토큰(10강에서 만듭니다. 비밀번호와 같은 것으로 취급합니다)

6강부터 화면 사진을 노트에 넣게 되는데, 사진 안에 위 내용이 찍혀 있는 경우가 있습니다. 넣기 전에 확인하는 습관이 필요합니다.

⚠ 주의: 한 번 GitHub에 올린 내용은 나중에 파일에서 지우더라도 이전 기록에 남습니다. 지우기보다 처음부터 적지 않는 것이 확실합니다.

3강에서 만든 format-test.docx를 홈 폴더에 둔 것도 같은 이유입니다. 확인용으로 한 번 쓰고 마는 파일이 공개 대상 폴더에 남지 않게 하려는 것입니다. 그 파일은 이후 강의에서 다시 사용하지 않으므로 그대로 두거나 삭제해도 됩니다.

1.3 AI 도구가 생성한 문장을 확인 없이 기록에 옮기지 않는 원칙 확인하기

7강부터 9강까지 Claude에 질문하며 학습합니다. 이때 받은 답변은 참고 자료이지 확인된 사실이 아닙니다. 명령 이름이나 경로가 실제와 다른 경우가 있습니다.

답변을 노트에 남길 때는 다음 순서를 따릅니다. 답변에 나온 명령이나 설명을 직접 실행하거나 원본 자료와 대조해 확인하고, 확인한 결과를 자기 문장으로 적습니다. 확인하지 않고 옮긴 문장은 나중에 자기 기록을 믿을 수 없게 만듭니다.

핵심: 폴더의 사용 순서와 두 가지 원칙(개인정보·계정 정보를 적지 않는다, AI 도구가 생성한 문장을 확인 없이 옮기지 않는다)을 확인했습니다. 이 원칙을 실제 기록 기준으로 만드는 작업을 지금 이어서 합니다.

2. 무엇을 기록할지 정해 기록 계획 노트 만들기

→ 남길 내용과 적지 않을 내용을 판단하고, 그 판단을 study-plan 노트로 작성한 뒤 실제 파일인지 확인합니다.

2.1 남길 내용과 적지 않을 내용 판단하기

앞의 표에서 이 폴더가 도착하는 곳은 면접이나 평가에서 제시하는 공개 주소입니다. 그렇다면 무엇을 적어야 그때 쓸모가 있는지가 오늘의 판단 대상입니다.

완성된 코드와 정리된 결론만 적어 둔 기록은 그 시점에 설명할 거리가 적습니다. 같은 결과는 누구나 만들 수 있기 때문입니다. 남는 것은 다음과 같은 내용입니다.

실제로 실행한 명령과 그때 화면에 나온 결과
실패했을 때 나온 오류 메시지의 원문
그 오류를 어떻게 확인하고 무엇을 고쳐서 해결했는지
두 가지 방법 중 하나를 골랐다면 무엇을 근거로 골랐는지

2강과 3강에서 한 작업이 이 네 가지에 그대로 해당합니다. 2강에서는 같은 파일을 마우스로도 열고 명령으로도 열어 두 방법의 결과가 같은 것을 확인했고, 3강에서는 unzip -l을 두 파일에 각각 실행해 한쪽에서는 목록이 나오고 다른 쪽에서는 오류가 나오는 것을 확인했습니다. 오류가 나온 것이 정상이라는 판단도 함께 했습니다. 이런 내용이 남아 있으면 나중에 "마크다운 파일에는 글자만 들어 있다"는 문장 하나보다 설명할 거리가 많습니다.

반대로 적지 않을 것도 정해 두는 편이 낫습니다. 배부받은 강의 요약본에 이미 있는 설명을 노트에 다시 옮겨 적는 것이 대표적입니다. 같은 내용이 두 파일에 나뉘어 있으면 나중에 어느 쪽이 맞는지 판단해야 하고, 옮겨 적는 시간만큼 실습 시간이 줄어듭니다. 요약본의 어느 부분을 봤는지만 적고 넘어가면 됩니다.

앞 절에서 확인한 두 원칙도 여기에 함께 들어갑니다. 개인정보와 계정 정보를 적지 않는다는 것, 그리고 AI 도구가 생성한 문장을 확인 없이 옮기지 않는다는 것입니다.

2.2 기록 계획 노트 작성하기

정한 내용을 노트로 남깁니다. 1강부터 3강까지는 파일을 열어 보기만 했고, 이번이 Obsidian에서 노트를 직접 만드는 첫 작업입니다.

[화면 캡처: notes 폴더를 오른쪽 클릭했을 때 나오는 [New note] 메뉴]

왼쪽 파일 목록에서 notes 폴더를 마우스 오른쪽 버튼으로 누르고 [New note](새 노트)를 선택합니다.
노트 이름을 study-plan으로 입력하고 Enter 키를 누릅니다. 파일 이름은 1강에서 확인한 규칙대로 영문 소문자와 붙임표만 사용합니다. 확장자 .md는 입력하지 않아도 자동으로 붙습니다.
편집 영역에 다음 틀을 입력한 뒤 각 항목을 자기 문장으로 채웁니다. 파일 이름은 영문이지만 문서 안의 제목은 한국어로 적습니다. 첫 줄의 #은 제목을 표시하는 마크다운 기호이고 -는 목록을 표시하는 기호입니다. 문법은 5강과 6강에서 다루므로 지금은 이 형태 그대로 적으면 됩니다.

작성 예시는 다음과 같습니다. 그대로 베끼지 말고 3강에서 자기 화면에 나온 내용으로 고쳐 적습니다.

# 나의 학습 기록 계획

## 3강에서 확인한 것

- 워드 문서에 file, gnome-text-editor, unzip -l을 실행했을 때: file은 Microsoft Word 형식으로
  판정했고, 편집기에서는 입력한 문장이 안 보였고, unzip -l 목록에는 word/document.xml을
  포함해 XML 파일이 다섯 개 넘게 나왔다.
- 마크다운 파일에 같은 세 명령을 실행했을 때: file은 UTF-8 text로 판정했고, 편집기에서
  내용이 그대로 보였고 #과 - 기호도 글자로 보였다. unzip -l은 압축 파일이 아니라는 오류가 나왔다.
- 학습 기록의 원본을 마크다운으로 두는 이유 중 내가 가장 먼저 쓰게 될 것:
  10강에서 Git이 어느 줄이 바뀌었는지 기록하려면 글자만 있는 파일이어야 한다는 점

## 남길 것

- 직접 실행한 명령과 화면에 나온 결과
- 오류 메시지는 요약하지 않고 나온 문장 그대로
- 오류를 해결한 방법과 그때 확인한 것
- 두 방법 중 하나를 고른 경우 그 근거

## 적지 않을 것

- 강의 요약본에 이미 있는 설명. 어느 부분을 봤는지만 적는다
- 개인정보와 계정 정보. 이 폴더는 10강부터 공개된다
- 확인하지 않은 AI 도구의 답변

## 적는 시점

- 실습이 끝난 뒤가 아니라 오류가 났을 때 바로 적는다

Ctrl+E로 읽기 모드로 전환합니다. #을 붙인 줄이 제목으로, -를 붙인 줄이 점 목록으로 표시되면 올바르게 입력된 것입니다.
오른쪽 사이드바의 [Outline] 탭을 봅니다. 방금 입력한 ## 제목 네 개가 목록으로 표시됩니다. 1강에서 켜 둔 개요 기능이 내가 만든 노트에도 그대로 동작하는지 확인하는 것입니다.

Obsidian은 별도의 저장 버튼 없이 입력하는 즉시 파일에 자동 저장됩니다. Ctrl+S를 누를 필요가 없습니다.

증상	원인	해결 방법
새 노트가 `notes` 폴더가 아니라 다른 곳에 만들어졌다	오른쪽 클릭한 대상이 다른 폴더이거나 파일 목록의 빈 곳임	왼쪽 목록에서 그 노트를 `notes` 폴더 위로 끌어다 놓아 옮긴다
노트 이름을 바꾸고 싶다	—	왼쪽 목록에서 노트를 오른쪽 클릭하고 [Rename]을 선택한다
한글 입력이 안 된다	Ubuntu 입력기가 영문으로 되어 있음	입력기 전환 키는 실습실 PC 설정에 따라 다르므로 강사가 안내하는 키를 사용한다. 해결되지 않으면 강사에게 알린다
`#`을 붙였는데 읽기 모드에서 제목으로 표시되지 않는다	`#`과 글자 사이에 공백이 없음	`#제목`이 아니라 `# 제목`처럼 기호 뒤에 공백을 하나 넣는다
오른쪽 사이드바의 [Outline] 탭이 비어 있다	노트에 `#` 제목이 아직 없거나 개요 기능이 꺼져 있다	제목 줄을 먼저 입력한다. 그래도 비어 있으면 설정 → [Core plugins]에서 [Outline]이 켜져 있는지 확인한다
코드 블록 안의 예시를 그대로 붙여 넣었더니 뒤 내용이 이상해진다	예시 안의 세 개짜리 기호까지 함께 복사함	예시는 보고 직접 입력한다. 이 기호의 뜻은 6강에서 다룬다

2.3 만든 노트가 실제 파일인지 확인하기

파일 관리자로 홈 폴더의 study-notes/notes를 열어 보면 방금 만든 study-plan.md 파일이 실제로 생겨 있습니다.

1강과 2강에서는 파일 관리자에 이미 있던 파일을 Obsidian으로 열어 확인했고, 이번에는 반대 방향입니다. Obsidian에서 만든 노트가 곧 내 컴퓨터의 마크다운 파일이라는 것이 양쪽 방향으로 확인됩니다.

2강에서 확인한 것을 여기에도 적용할 수 있습니다. 쉘 프롬프트에서 다음 두 명령을 실행하면 방금 Obsidian에서 입력한 내용이 그대로 보이고, 파일 종류도 텍스트로 판정됩니다.

쉘 프롬프트

# 만든 노트의 파일 종류와 내용 확인
file ~/study-notes/notes/study-plan.md
gnome-text-editor ~/study-notes/notes/study-plan.md

Obsidian이 만든 파일도 특별한 형식이 아니라 글자만 담긴 텍스트 파일이라는 확인입니다. 확인이 끝나면 수정하지 말고 창을 닫습니다.

3. 학습일지 노트를 만들고 기록 계획 노트와 역할 구분하기

→ 강의마다 한 일을 적는 study-log 노트를 만들고, 두 노트를 나누어 쓰는 기준을 정합니다.

3.1 학습일지 노트 작성하기

두 번째 노트는 강의마다 한 일을 적는 학습일지입니다. 기록 계획 노트와 같은 방법으로 만듭니다.

notes 폴더를 마우스 오른쪽 버튼으로 누르고 [New note]를 선택합니다.
노트 이름을 study-log로 입력하고 Enter 키를 누릅니다.
다음 내용을 입력합니다. 1강부터 3강까지의 항목은 자기 화면에 나온 내용으로 고쳐 적습니다.

# 학습일지

## 1강. Obsidian 설치와 Vault 열기

- Obsidian을 설치하고 study-notes 폴더를 Vault로 열었다.
- 파일 관리자에서 본 폴더 세 개와 index 파일이 Obsidian 목록과 같았다.
- Minimal 테마와 Minimal Theme Settings를 적용하고 Colorful active states를 켜서
  파일 목록에서 열려 있는 파일이 강조 색으로 보이게 했다.
- 코어 플러그인 Outline을 켜서 오른쪽 사이드바에 제목 목록을 띄웠다.

## 2강. 노트 파일이 텍스트 파일인지 확인

- markdown-syntax.md를 파일 관리자에서 오른쪽 클릭해 텍스트 편집기로 열었더니
  읽을 수 없는 문자 없이 내용이 그대로 보였다.
- 같은 파일을 gnome-text-editor 명령으로도 열었고 결과가 같았다.
- file 명령의 출력은 UTF-8 text였다.
- 텍스트 편집기에서 한 줄을 추가했더니 Obsidian 화면에도 나타났다.
  두 프로그램이 같은 파일 하나를 열고 있었다.

## 3강. 워드 문서와 마크다운 파일의 저장 방식 비교

- format-test.docx를 만들어 텍스트 편집기로 열었더니 입력한 문장이 보이지 않았다.
- unzip -l 출력에 word/document.xml이 있었다. 서식은 word/styles.xml에 따로 있었다.
- 같은 명령을 markdown-syntax.md에 실행하니 압축 파일이 아니라는 오류가 나왔다.
- 학습 기록의 원본을 마크다운으로 두는 이유 세 가지를 정리했다.

## 4강. 학습 기록 시작

- study-notes 폴더가 16강까지 쓰이는 순서와 기록 원칙 두 가지를 확인했다.
- 기록 계획 노트 study-plan을 만들었다.
- 학습일지 노트 study-log를 만들었다.

Ctrl+E로 읽기 모드에서 표시 결과를 확인합니다.

3.2 두 노트의 역할 구분하기

노트 두 개의 용도가 다릅니다. 앞으로 어느 노트에 적을지 판단해야 하므로 구분해 둡니다.

노트	적는 내용	고치는 시점
`study-plan`	무엇을 남기고 무엇을 남기지 않을지에 대한 기준	기준을 바꿀 때만
`study-log`	강의마다 실제로 한 일, 실행한 명령, 나온 결과와 오류	강의마다

study-plan에 적은 기준을 study-log에 다시 옮겨 적지 않습니다. 같은 내용이 두 파일에 나뉘어 있으면 나중에 어느 쪽이 최신인지 판단해야 하기 때문입니다. 학습일지를 쓸 때 기준이 기억나지 않으면 study-plan 노트를 함께 열어 두면 됩니다.

4. 배부받은 강의 요약본을 lectures 폴더에 저장하기

→ 요약본 파일 네 개를 lectures 폴더에 넣고, 안내 노트의 목록 링크로 각각 열리는지 확인합니다.

4.1 요약본 네 파일을 옮기고 목록 링크로 확인하기

강사가 1강부터 4강까지의 강의 요약본 파일 네 개를 배부합니다.

요약본.zip

0.01MB

01-obsidian-install.md, 02-text-file-check.md, 03-markdown-format.md, 04-study-notes.md입니다. 요약본에는 그 강의의 학습 목표, 실습 절차, 명령, 확인 항목이 정리되어 있고 맨 아래에 내 메모 절이 있습니다.

[화면 캡처: lectures 폴더의 index 노트 읽기 모드에서 받은 요약본 목록이 링크로 표시된 화면]

파일 관리자에서 배부받은 네 파일을 홈 폴더의 study-notes/lectures 폴더로 옮깁니다.
Obsidian 화면으로 돌아가 왼쪽 파일 목록의 lectures 폴더를 펼칩니다. 방금 옮긴 네 파일이 나타납니다. 파일 관리자에서 폴더에 넣은 파일이 Obsidian 목록에 바로 나타나는 것도, Obsidian이 폴더 자체를 보여 준다는 1강의 확인 결과와 같은 내용입니다.
lectures 폴더의 index 노트를 누르고 Ctrl+E로 읽기 모드로 전환합니다. ## 받은 요약본 목록에 요약본 이름이 미리 적혀 있습니다.
목록의 각 줄을 차례로 눌러 요약본이 각각 열리는지 확인합니다.

목록의 링크가 모두 열리면 됩니다. 이 목록은 배부 시점에 미리 적혀 있던 것이고, 파일을 넣지 않은 상태에서 눌렀다면 페이지를 찾을 수 없다는 화면이 나왔을 것입니다.

앞으로 5강부터는 요약본을 받을 때마다 이 목록에 한 줄씩 직접 추가합니다. 추가하는 방법은 링크 문법을 다루는 6강에서 배웁니다.

증상	원인	해결 방법
`lectures` 폴더에 파일을 넣었는데 Obsidian 목록에 안 보인다	다른 폴더에 넣었거나 파일 확장자가 `.md`가 아님	파일 관리자에서 홈 폴더의 `study-notes/lectures` 경로를 다시 확인한다. Obsidian은 `.md` 파일만 노트로 표시한다
요약본 목록의 링크를 눌러도 아무 일도 없다	읽기 모드가 아니라 편집 모드임	`Ctrl+E`로 읽기 모드로 전환한 뒤 다시 누른다
요약본 목록의 링크를 눌렀는데 페이지를 찾을 수 없다고 나온다	넣은 파일의 이름이 목록에 적힌 이름과 다르다	파일 관리자에서 파일 이름을 목록에 적힌 이름과 같게 맞춘다. 이름이 다르면 링크가 그 파일을 찾지 못한다

5. 오늘 만든 상태를 확인하고 5강 학습으로 연결하기

→ 오늘 만든 노트와 요약본의 상태를 점검하고, 5강에서 이어질 마크다운 문법 학습을 확인합니다.

5.1 오늘 만든 상태 점검하기

다음 다섯 가지가 모두 확인되면 4강에서 만들어야 할 상태가 갖춰진 것입니다.

Obsidian의 notes 폴더에 study-plan과 study-log 두 노트가 있습니다.
study-plan 노트의 ## 3강에서 확인한 것 세 항목과 ## 남길 것, ## 적지 않을 것이 자기 문장으로 채워져 있습니다.
파일 관리자에서 홈 폴더의 study-notes/notes를 열면 index.md, study-plan.md, study-log.md 세 파일이 있습니다.
lectures 폴더의 index 노트를 읽기 모드로 열어 목록의 각 줄을 눌렀을 때 요약본이 각각 열립니다.
이 폴더에 개인정보와 계정 정보를 적지 않는 이유를 강의 번호(10강, 15강)와 함께 설명할 수 있습니다.

3번이 확인되지 않으면 노트를 다른 폴더에 만든 것입니다. 쉘 프롬프트에서 다음 명령으로 파일의 위치를 확인합니다.

쉘 프롬프트

# notes 폴더의 파일 목록 확인
ls ~/study-notes/notes/

index.md, study-plan.md, study-log.md 세 이름이 출력되어야 합니다. 빠진 파일이 있으면 Obsidian 왼쪽 목록에서 그 노트를 notes 폴더로 끌어다 놓아 옮깁니다.

오늘 강의를 마친 뒤의 학습 자료 폴더 상태

study-notes 4강5절.zip

1.60MB

study-notes/
├── index.md                     #   1강에서 확인 완료
├── lectures/
│   ├── index.md                 #   목록 링크 확인 완료
│   ├── 01-obsidian-install.md   # ✏️ 이번 강의에서 저장
│   ├── 02-text-file-check.md    # ✏️ 이번 강의에서 저장
│   ├── 03-markdown-format.md    # ✏️ 이번 강의에서 저장
│   └── 04-study-notes.md        # ✏️ 이번 강의에서 저장
├── notes/
│   ├── index.md                 #   1강에서 확인 완료
│   ├── study-plan.md            # ✏️ 이번 강의에서 작성
│   └── study-log.md             # ✏️ 이번 강의에서 작성
└── reference/
    ├── index.md                 #   1강에서 확인 완료
    └── markdown-syntax.md       #   원래 상태 유지. 6강 실습에 사용

✔ 정리: study-notes 폴더의 사용 순서와 기록 원칙 두 가지를 확인하고, 기록 계획 노트 study-plan과 학습일지 노트 study-log를 만들었으며, 강의 요약본 네 편을 lectures 폴더에 저장해 목록 링크로 열리는 것을 확인했습니다.

오늘 만든 두 노트에서 #과 - 기호가 제목과 목록으로 바뀌는 것을 봤습니다. 이 기호 규칙의 이름이 마크다운입니다.

→ 다음 개별 강의

5강에서는 마크다운 기호가 화면에서 문서 구조로 바뀌는 것을 확인하고 이 과정에서 사용할 문법의 범위를 정합니다. 6강 실습에는 2강에서 열어 본 reference 폴더의 markdown-syntax 노트를 그대로 사용하니 따로 준비할 것은 없습니다.

3강. 질문으로 근거 문서를 찾아 답변기

BasicLike — Mon, 27 Jul 2026 08:26:56 +0900

3강 실습 중심 ⏱ 약 70분

0. 학습 목표

→ 저장한 문서를 질문으로 찾고, 찾은 문서를 근거로 답변을 만들고, 근거가 없으면 답하지 않게 만듭니다.

0.1 이번 글에서 다룰 내용

2강 9절 마지막에서 명령 하나를 실행해 봤습니다. 같은 명령을 다시 실행합니다.

쉘 프롬프트

# 질문과 가까운 문서 한 건 찾기
cd ~/rag-basic
python3 -c "
import chromadb

from config import get_settings
from embedder import embed

settings = get_settings()
client = chromadb.PersistentClient(path=str(settings.chroma_path))
collection = client.get_collection(settings.collection_name)

question_vector = embed(['무료로 대리인을 지원받는 제도가 있나요?'])[0]
result = collection.query(query_embeddings=[question_vector], n_results=1)
print('1위 문서 :', result['ids'][0][0])
print('거리     :', round(result['distances'][0][0], 4))
"

1위 문서 : ip-004
거리     : 0.xxxx

첫 줄은 기대한 결과입니다. 질문에 쓴 "무료"와 "제도"가 문서에 한 번도 나오지 않는데도 ip-004 국선대리인 규칙 문서를 찾아냈습니다. 2강에서 벡터로 바꿔 저장한 결과입니다.

문제는 두 번째 줄입니다. 이 상태로 프로그램을 만들면 사용자에게 다음과 같은 화면을 보여 주게 됩니다.

질문: 무료로 대리인을 지원받는 제도가 있나요?
1위 문서: ip-004
거리: 0.xxxx

사용자가 이 화면으로 할 수 있는 일이 없습니다. 세 가지가 빠져 있습니다.

빠진 것	지금 상태	사용자가 못 하는 일
답변 문장	문서 번호만 나온다	문서 번호를 보고 원문을 직접 찾아 읽어야 한다
값을 읽는 기준	`거리`가 얼마면 관련 있는 것인지 정해지지 않았다	이 결과를 믿어도 되는지 판단할 수 없다
관련 없을 때의 처리	관련 없는 질문에도 1위가 나온다	엉뚱한 문서가 1위로 나와도 알 수 없다

세 번째를 직접 확인해 봅니다. 데이터와 아무 관계없는 질문을 같은 명령에 넣습니다.

쉘 프롬프트

# 데이터와 관계없는 질문으로 같은 검색 실행
python3 -c "
import chromadb

from config import get_settings
from embedder import embed

settings = get_settings()
client = chromadb.PersistentClient(path=str(settings.chroma_path))
collection = client.get_collection(settings.collection_name)

question_vector = embed(['오늘 점심 메뉴로 뭐가 좋을까요?'])[0]
result = collection.query(query_embeddings=[question_vector], n_results=1)
print('1위 문서 :', result['ids'][0][0])
print('거리     :', round(result['distances'][0][0], 4))
"

1위 문서 : ip-0xx
거리     : 0.xxxx

점심 메뉴를 물었는데도 1위 문서가 나옵니다.

벡터 저장소는 "관련 있는 문서가 없습니다"라고 답하지 않습니다. 10건 중에서 가장 가까운 것을 고를 뿐입니다. 이 결과를 그대로 LLM에 근거로 건네면, 지식재산권 문서를 근거로 점심 메뉴에 대한 그럴듯한 답변이 만들어집니다.

이것이 문제입니다. 그렇기 때문에 이번 강의는 거리 값을 사람이 읽을 수 있는 기준으로 바꾸고, 그 기준을 넘지 못하면 답하지 않는 규칙을 만듭니다. 1강 3절에서 확인한 다섯 단계 중 남은 두 개, 검색과 근거 기반 생성이 여기에 해당합니다.

만들 파일은 두 개입니다.

파일	하는 일	다루는 절
`search.py`	질문을 벡터로 바꿔 가까운 문서를 찾고, 거리를 유사도로 바꿔 보여 준다	1절~3절
`ask.py`	근거를 붙여 답변을 만들고, 근거가 없으면 LLM을 부르지 않는다	4절~5절

이번 강의를 마치면 프로젝트 폴더가 다음 상태가 됩니다.

rag-basic/
├── .venv/                     0강
├── .env                       0강
├── config.py                  0강
├── build_docs.py              2강
├── embedder.py                2강
├── store.py                   2강
├── search.py                ✏️ 이번 강의 1절
├── ask.py                   ✏️ 이번 강의 4절
├── data/
│   ├── ip_qa_basic.json       0강
│   └── 출처.md                 0강
├── docs/
│   └── qa_documents.jsonl     2강, 10줄
└── chroma_db/                 2강, ip_docs 컬렉션 10건

이번 강의가 이 과정의 마지막 강의입니다. 마치면 명령 한 줄로 질문하고 근거와 함께 답변을 받는 프로그램이 완성됩니다.

0.2 이번 강의 실습 내용

학습자가 직접 하는 작업은 1절부터 6절까지 이어집니다. 1절에서 만든 search.py를 2절과 3절에서 고쳐 완성하고, 4절의 ask.py가 그 결과를 받아 씁니다. 각 절이 무엇을 받아 무엇을 넘기는지 먼저 확인합니다.

1절에서는 search.py의 첫 형태를 만듭니다.

0.1의 명령을 파일로 옮기고, 결과를 여러 건 받아 보기 좋게 출력합니다. 이 시점의 출력에는 아직 거리 값이 그대로 나옵니다.

2절에서는 그 거리 값을 유사도로 바꿉니다.

1강 7절에서 "거리와 유사도는 방향이 반대"라고 예고한 부분입니다. 일부러 뒤집어 읽어 보고 어떤 증상이 나오는지 확인한 뒤 올바른 계산으로 되돌립니다.

3절에서는 범위 안 질문과 범위 밖 질문의 유사도를 나란히 비교합니다.

0강 5.2에서 .env에 적어 둔 MIN_SIMILARITY=0.35가 두 경우를 가르는지 값으로 확인합니다. 이 확인이 4절 이후의 분기 조건이 됩니다.

4절에서는 ask.py를 만들어 근거를 프롬프트로 조립하고 답변을 받습니다.

검색으로 고른 문서에 번호를 붙여 LLM에게 건네고, 답변과 함께 출처를 표시합니다.

5절에서는 근거가 없을 때 LLM을 호출하지 않게 만듭니다.

3절에서 확인한 기준을 조건으로 씁니다. 호출하지 않았다는 것을 응답 시간 차이로 확인합니다.

6절에서는 5절의 규칙을 지우면 무엇이 나오는지 확인합니다. 확인이 끝나면 반드시 되돌리고 같은 질문으로 다시 검증합니다.

절	하는 일	앞 절에서 받는 것	다음 절에 넘기는 것
1	`search.py` 첫 형태 작성	2강의 `ip_docs` 컬렉션, `embed()`	거리 값이 붙은 검색 결과
2	거리를 유사도로 변환	1절의 검색 결과	`similarity` 값이 붙은 검색 결과
3	범위 안·밖 질문의 유사도 비교	2절의 유사도	근거로 쓸지 판단하는 기준값
4	`ask.py`로 근거를 붙여 답변 생성	3절의 기준, `search()` 함수	답변과 출처
5	근거 없을 때 호출하지 않는 분기	4절의 `ask.py`	완성된 프로그램
6	분기를 지웠을 때의 증상 확인	5절의 `ask.py`	근거 없음 정책이 필요한 이유

이번 강의를 마치면 다음을 할 수 있습니다.

질문을 문서와 같은 모델로 벡터화해야 하는 이유를 설명하고, 그 처리를 코드로 옮긴다.
거리 값을 유사도로 바꿔 읽고, 두 값의 방향이 반대라는 것을 실행 결과로 보인다.
범위 안 질문과 범위 밖 질문의 유사도를 비교해 기준값이 두 경우를 가르는지 판단한다.
검색으로 고른 문서를 번호가 붙은 근거로 조립해 LLM에 전달하고, 답변에 출처를 함께 표시한다.
근거가 없을 때 LLM을 호출하지 않도록 만들고, 호출하지 않았다는 것을 응답 시간으로 확인한다.

선수 지식은 2강에서 만든 ip_docs 컬렉션 10건입니다. 2강을 실행하지 않았으면 이번 강의를 시작할 수 없습니다. 1강 6절에서 확인한 두 실행 경로 중 저장 경로를 한 번도 실행하지 않으면 질문 경로가 아무것도 찾지 못합니다.

이번 강의에서는 최소 유사도 값을 데이터에서 측정해 정하는 방법을 다루지 않습니다. 문서가 10건뿐이라 유사도의 분포를 잴 표본이 부족하기 때문이며, 그 이유는 3.2에서 값과 함께 설명합니다. 문서 종류로 검색 범위를 좁히는 조건 검색과, 만든 프로그램을 다른 사람이 화면으로 쓸 수 있게 감싸는 작업도 다루지 않습니다. 각각 8. RAG 강좌 2단계와 4단계에서 이어집니다.

시작하기 전에 2강의 결과가 남아 있는지 확인합니다.

쉘 프롬프트

# 2강에서 저장한 컬렉션이 그대로 있는지 확인
python3 -c "
import chromadb

from config import get_settings

settings = get_settings()
client = chromadb.PersistentClient(path=str(settings.chroma_path))
print('건수:', client.get_collection(settings.collection_name).count())
"

건수: 10

10이 아니거나 오류가 나면 2강 4.5의 python3 store.py --reset을 먼저 실행합니다.

1. 질문으로 가까운 문서 찾기

→ 0.1의 명령을 파일로 옮기고 결과를 여러 건 받아 봅니다.

0.1에서 실행한 명령은 한 건만 찾고 문서 번호와 거리만 보여 줬습니다. 여러 건을 받아 무엇이 나왔는지 내용까지 확인할 수 있게 만듭니다.

1.1 질문도 같은 모델로 벡터로 바꿔야 하는 이유

코드를 쓰기 전에 하나를 확인합니다. 질문을 벡터로 바꿀 때도 문서를 바꿀 때와 같은 모델을 써야 합니다.

2강 3절에서 만든 embed() 함수를 그대로 씁니다. 이 함수는 .env의 EMBEDDING_MODEL 값을 읽으므로, 저장할 때와 검색할 때가 자동으로 같아집니다.

다른 모델을 쓰면 어떻게 되는지는 숫자로 설명할 수 있습니다. 임베딩 모델마다 벡터의 차원이 다르고, 차원이 같더라도 각 자리의 숫자가 뜻하는 바가 다릅니다.

상황	결과
저장과 검색이 같은 모델	두 벡터를 비교할 수 있다
차원이 다른 모델	저장소가 오류를 돌려준다. 잘못된 것을 바로 알 수 있다
차원은 같고 종류가 다른 모델	오류가 나지 않는다. 비교는 되지만 결과가 뒤죽박죽이 된다

세 번째가 위험합니다. 오류가 없으므로 검색 결과가 이상해도 원인을 찾기 어렵습니다. 1강 6절에서 embedder.py가 저장 경로와 질문 경로에 모두 등장하는 이유가 이것입니다. 같은 함수를 쓰면 모델이 어긋날 수 없습니다.

1.2 search.py 첫 형태 만들기

VSCode에서 rag-basic 폴더에 search.py를 만들고 아래 내용을 넣습니다. 이 코드는 이번 절의 형태이며 2절에서 한 부분을 고칩니다.

"""질문과 가까운 문서를 벡터 저장소에서 찾는다."""

from __future__ import annotations

import argparse

import chromadb

from config import get_settings
from embedder import embed


def get_collection():
    """2강에서 만든 컬렉션을 연다."""
    settings = get_settings()
    if not settings.chroma_path.exists():
        raise SystemExit("벡터 저장소가 없습니다. 2강의 store.py를 먼저 실행하십시오.")

    client = chromadb.PersistentClient(path=str(settings.chroma_path))
    return client.get_collection(settings.collection_name)


def search(question: str, top_k: int | None = None) -> list[dict]:
    """질문을 벡터로 바꿔 가까운 문서를 가까운 순서로 돌려준다."""
    question = question.strip()
    if not question:
        raise ValueError("질문이 비어 있습니다.")

    settings = get_settings()
    collection = get_collection()
    question_vector = embed([question])[0]

    result = collection.query(
        query_embeddings=[question_vector],
        n_results=top_k or settings.top_k,
        include=["documents", "metadatas", "distances"],
    )

    hits = []
    for doc_id, document, metadata, distance in zip(
        result["ids"][0],
        result["documents"][0],
        result["metadatas"][0],
        result["distances"][0],
    ):
        hits.append(
            {
                "id": doc_id,
                "document": document,
                "metadata": metadata,
                "distance": distance,
            }
        )
    return hits


def main() -> None:
    parser = argparse.ArgumentParser(description="질문과 가까운 문서를 찾는다.")
    parser.add_argument("question", help="검색할 질문 한 줄")
    parser.add_argument("--top-k", type=int, default=None, help="가져올 문서 수")
    args = parser.parse_args()

    try:
        hits = search(args.question, args.top_k)
    except ValueError as error:
        raise SystemExit(f"입력 오류: {error}")

    print(f"질문: {args.question}")
    print()

    for rank, hit in enumerate(hits, start=1):
        preview = hit["document"].replace("\n", " ")[:60]
        print(f"{rank}위 [{hit['id']}] 거리 {hit['distance']:.4f}")
        print(f"    {hit['metadata']['type']} / {hit['metadata']['title']} / {hit['metadata']['date']}")
        print(f"    {preview}...")
        print()


if __name__ == "__main__":
    main()

1.3 코드가 하는 일 확인하기

get_collection()이 저장소를 여는 부분을 따로 떼어 두었습니다. 4절의 ask.py도 같은 컬렉션을 쓰는데, 그때는 search()를 통해 쓰므로 이 함수를 다시 만들 필요가 없습니다. 저장소가 없으면 2강을 먼저 실행하라고 알리고 멈춥니다.

search()가 질문을 받아 결과 목록을 돌려줍니다. main()이 아니라 함수로 분리한 이유는 4절에서 ask.py가 이 함수를 그대로 불러 쓰기 때문입니다. 화면에 출력하는 일과 결과를 만드는 일을 나누어 두면, 같은 결과를 다른 형식으로 쓸 수 있습니다.

n_results=top_k or settings.top_k가 가져올 건수를 정합니다. 명령에서 --top-k를 주지 않으면 .env의 TOP_K 값인 3이 쓰입니다. 0강 5.2에서 적어 둔 값이 여기에서 처음 쓰입니다.

include=[...]가 무엇을 함께 받을지 정합니다. 지정하지 않으면 벡터까지 돌려받는데, 1024개 실수를 10건 받아 봐야 화면에서 할 일이 없습니다. 필요한 것만 받습니다.

result["ids"][0]처럼 [0]이 붙는 이유는 query()가 질문 여러 개를 한 번에 처리할 수 있게 만들어져 있기 때문입니다. 질문을 하나만 보냈으므로 첫 번째 묶음을 꺼냅니다.

zip()으로 네 목록을 나란히 묶습니다. ids, documents, metadatas, distances가 각각 같은 순서의 목록으로 오므로, 같은 자리끼리 묶으면 문서 한 건이 됩니다.

1.4 실행하고 결과 확인하기

쉘 프롬프트

# 0.1과 같은 질문으로 검색
python3 search.py "무료로 대리인을 지원받는 제도가 있나요?"

질문: 무료로 대리인을 지원받는 제도가 있나요?

1위 [ip-004] 거리 0.xxxx
    법령 / 특허심판원국선대리인의선임및운영에관한규칙 / 2021-11-11
    질문: 국선대리인의 선임 기준은 무엇인가요? 답변: 국선대리인의 선임 기준은 특허심판원장이...

2위 [ip-0xx] 거리 0.xxxx
    ...

3위 [ip-0xx] 거리 0.xxxx
    ...

세 건이 나오고 1위가 ip-004이면 정상입니다. .env의 TOP_K가 3이므로 세 건입니다.

▶ 지금 해보세요

세 건의 거리 값을 적습니다. 1위와 3위의 차이가 얼마인지 봅니다.
--top-k 10을 붙여 다시 실행하고, 10건 전체의 거리 값이 어떻게 퍼져 있는지 봅니다.
빈 질문으로 실행해 봅니다. python3 search.py ""를 실행하면 어떤 메시지가 나오는지 적습니다.

세 번째를 실행하면 다음과 같이 나옵니다.

입력 오류: 질문이 비어 있습니다.

파이썬 오류 메시지가 아니라 우리가 쓴 문장이 나옵니다. search() 안의 raise ValueError와 main()의 except ValueError가 짝을 이룬 결과입니다. 이 처리가 없으면 빈 질문이 그대로 임베딩 요청으로 나가고, 서버가 돌려주는 오류 메시지를 사용자가 보게 됩니다.

2. 거리를 유사도로 바꿔 읽기

→ 1절의 출력에 나온 거리 값을 사람이 판단할 수 있는 값으로 바꿉니다.

1.4에서 세 건의 거리 값을 적었습니다. 그 숫자를 보고 "관련 있다"고 판단할 수 있습니까? 아직 할 수 없습니다. 거리가 얼마면 관련 있는 것인지 정해지지 않았기 때문입니다.

2.1 거리와 유사도의 방향

1강 7절의 용어표에서 두 값을 이렇게 정리했습니다.

값	방향	이 컬렉션에서의 범위
거리 (distance)	작을수록 관련이 크다	0에 가까울수록 가깝다
유사도 (similarity)	클수록 관련이 크다	1에 가까울수록 가깝다

2강 4.2에서 컬렉션의 거리 공간을 코사인으로 지정했습니다. 코사인 거리 공간에서는 두 값이 다음 관계입니다.

유사도 = 1 - 거리

같은 내용이면 거리가 0에 가깝고 유사도가 1에 가깝습니다. 관련이 없으면 거리가 커지고 유사도가 작아집니다.

이 계산은 거리 공간이 코사인일 때만 성립합니다. 2강 6절에서 거리 공간을 지정하지 않은 컬렉션의 거리 값이 다르게 나온 것을 확인했습니다. 그 컬렉션에 같은 계산을 하면 다른 숫자가 나오고, 오류는 나지 않습니다.

2.2 뒤집어 읽으면 어떤 결과가 나오는지 확인하기

계산을 반대로 하면 어떻게 되는지 먼저 봅니다. 유사도 = 거리로 잘못 읽었다고 가정하고 두 방식의 순위를 나란히 출력합니다.

쉘 프롬프트

# 거리를 그대로 유사도로 읽었을 때와 1에서 뺐을 때를 비교
python3 -c "
from search import search

hits = search('무료로 대리인을 지원받는 제도가 있나요?', top_k=5)

print('[제대로 읽은 순서] 유사도 = 1 - 거리, 큰 것부터')
for hit in sorted(hits, key=lambda h: 1 - h['distance'], reverse=True):
    print('   ', hit['id'], round(1 - hit['distance'], 4), hit['metadata']['title'][:20])

print()
print('[뒤집어 읽은 순서] 거리를 그대로 유사도로 보고 큰 것부터')
for hit in sorted(hits, key=lambda h: h['distance'], reverse=True):
    print('   ', hit['id'], round(hit['distance'], 4), hit['metadata']['title'][:20])
"

[제대로 읽은 순서] 유사도 = 1 - 거리, 큰 것부터
    ip-004 0.xxxx 특허심판원국선대리인의선임및...
    ...

[뒤집어 읽은 순서] 거리를 그대로 유사도로 보고 큰 것부터
    ...
    ip-004 0.xxxx 특허심판원국선대리인의선임및...

두 목록의 순서가 정확히 반대입니다. 뒤집어 읽으면 가장 관련 있는 문서가 마지막에 오고, 가장 관련 없는 문서가 1위가 됩니다.

이 실수가 위험한 이유는 오류가 나지 않기 때문입니다. 프로그램은 정상 종료하고 화면에는 숫자가 나옵니다. 관련 없는 문서를 근거로 답변이 만들어지고, 사용자는 그 답변이 왜 이상한지 알 수 없습니다.

검색 결과가 이상할 때 이 계산을 먼저 확인합니다. 1위로 나온 문서가 눈으로 봐도 관련이 없고 오히려 마지막 문서가 관련 있어 보인다면, 방향이 뒤집힌 것입니다.

2.3 search.py에 유사도 추가하기

search.py의 search() 함수에서 hits.append(...) 부분에 한 줄을 추가합니다.

        hits.append(
            {
                "id": doc_id,
                "document": document,
                "metadata": metadata,
                "distance": distance,
                "similarity": 1.0 - distance,
            }
        )

main()의 출력 부분도 유사도를 함께 보여 주도록 바꿉니다. .env에 적어 둔 기준값과 비교한 결과도 같이 표시합니다.

def main() -> None:
    parser = argparse.ArgumentParser(description="질문과 가까운 문서를 찾는다.")
    parser.add_argument("question", help="검색할 질문 한 줄")
    parser.add_argument("--top-k", type=int, default=None, help="가져올 문서 수")
    args = parser.parse_args()

    try:
        hits = search(args.question, args.top_k)
    except ValueError as error:
        raise SystemExit(f"입력 오류: {error}")

    settings = get_settings()
    print(f"질문           : {args.question}")
    print(f"최소 유사도 기준: {settings.min_similarity}")
    print()

    for rank, hit in enumerate(hits, start=1):
        judgement = "근거로 사용" if hit["similarity"] >= settings.min_similarity else "기준 미만"
        preview = hit["document"].replace("\n", " ")[:60]
        print(f"{rank}위 [{hit['id']}] 거리 {hit['distance']:.4f} / 유사도 {hit['similarity']:.4f} ({judgement})")
        print(f"    {hit['metadata']['type']} / {hit['metadata']['title']} / {hit['metadata']['date']}")
        print(f"    {preview}...")
        print()

쉘 프롬프트

# 유사도를 함께 표시하도록 고친 뒤 다시 실행
python3 search.py "무료로 대리인을 지원받는 제도가 있나요?"

질문           : 무료로 대리인을 지원받는 제도가 있나요?
최소 유사도 기준: 0.35

1위 [ip-004] 거리 0.xxxx / 유사도 0.xxxx (근거로 사용)
    법령 / 특허심판원국선대리인의선임및운영에관한규칙 / 2021-11-11
    질문: 국선대리인의 선임 기준은 무엇인가요? 답변: 국선대리인의 선임 기준은 특허심판원장이...

2위 [ip-0xx] 거리 0.xxxx / 유사도 0.xxxx (기준 미만)
    ...

3위 [ip-0xx] 거리 0.xxxx / 유사도 0.xxxx (기준 미만)
    ...

각 줄 끝에 근거로 사용인지 기준 미만인지 표시됩니다. 아직 이 판단이 답변에 반영되지는 않습니다. 지금은 화면에 표시만 하고, 실제로 걸러 내는 것은 5절입니다.

거리와 유사도를 더하면 1이 되는지 확인해 보십시오. 2.1의 관계가 실제로 성립하는지 값으로 확인하는 방법입니다.

3. 범위 안 질문과 범위 밖 질문의 유사도 비교하기

→ 0강에서 정한 기준값 0.35가 두 경우를 실제로 가르는지 확인합니다.

2.3에서 근거로 사용과 기준 미만이 화면에 표시되기 시작했습니다. 그 기준이 되는 0.35는 어디에서 온 값입니까? 0강 5.2에서 .env에 적어 둔 값이고, 그때 "지금 시점에서는 가정값"이라고 했습니다.

이 절에서는 그 가정값이 이 데이터에서 쓸 만한지 확인합니다.

3.1 성격이 다른 질문 네 개로 비교하기

질문을 네 종류로 나눠 실행합니다.

구분	질문	기대하는 결과
A. 문서의 말을 그대로 쓴 질문	`국선대리인의 선임 기준은 무엇인가요?`	유사도가 가장 높다
B. 뜻은 같고 표현이 다른 질문	`무료로 대리인을 지원받는 제도가 있나요?`	기준을 넘는다
C. 같은 분야지만 데이터에 없는 내용	`특허 출원 수수료는 얼마인가요?`	판단이 갈릴 수 있다
D. 분야가 아예 다른 질문	`오늘 점심 메뉴로 뭐가 좋을까요?`	기준을 넘지 못한다

쉘 프롬프트

# 네 질문의 1위 유사도를 나란히 비교
python3 -c "
from config import get_settings
from search import search

questions = [
    ('A. 문서의 말 그대로', '국선대리인의 선임 기준은 무엇인가요?'),
    ('B. 표현이 다름    ', '무료로 대리인을 지원받는 제도가 있나요?'),
    ('C. 같은 분야·없는 내용', '특허 출원 수수료는 얼마인가요?'),
    ('D. 분야가 다름    ', '오늘 점심 메뉴로 뭐가 좋을까요?'),
]
threshold = get_settings().min_similarity
print('기준값:', threshold)
print()
for label, question in questions:
    top = search(question, top_k=1)[0]
    mark = '넘음' if top['similarity'] >= threshold else '못 넘음'
    print(label, '1위', top['id'], '유사도', round(top['similarity'], 4), '->', mark)
"

기준값: 0.35

A. 문서의 말 그대로 1위 ip-004 유사도 0.xxxx -> 넘음
B. 표현이 다름     1위 ip-004 유사도 0.xxxx -> 넘음
C. 같은 분야·없는 내용 1위 ip-0xx 유사도 0.xxxx -> 넘음 또는 못 넘음
D. 분야가 다름     1위 ip-0xx 유사도 0.xxxx -> 못 넘음

0.xxxx와 ip-0xx 자리에는 실행하면 실제 값이 나옵니다. C는 데이터에 없는 내용을 같은 분야의 말로 물은 것이라 어느 쪽으로 나올지 정해져 있지 않습니다. 그 결과를 보는 것이 이 실습의 목적입니다.

▶ 지금 해보세요

네 줄의 유사도를 모두 적으십시오. A와 B가 기준을 넘고 D가 넘지 못하면 이 기준값을 그대로 쓸 수 있습니다. C는 어느 쪽으로 나오는지 적고, 어느 쪽이 맞는 처리라고 생각하는지 한 문장으로 적습니다.

3.2 이 값을 이 과정에서 측정하지 않는 이유

3.1의 결과로 0.35가 A·B와 D를 가른다는 것은 확인할 수 있습니다. 그런데 이 값이 이 데이터에 맞는 값이라고 말하려면 표본이 더 필요합니다.

문서가 10건뿐이므로 범위 안 질문과 범위 밖 질문의 유사도가 각각 어느 범위에 퍼져 있는지 잴 수 없습니다. 질문 네 개로 확인한 것은 "이 기준이 이 네 질문을 가른다"이지 "0.35가 이 데이터에 맞는 값이다"가 아닙니다.

이 과정에서 하는 일	실제 도입할 때 해야 하는 일
기본값 `0.35`로 두 경우가 갈리는 것을 확인	범위 안 질문 수십 개와 범위 밖 질문 수십 개의 유사도를 모아 분포를 본다
값을 `.env`에서 바꿀 수 있게 만들어 둠	두 분포가 갈리는 지점을 찾아 값을 정하고 근거를 문서에 남긴다

값을 재어 정하는 작업은 8. RAG 강좌 2단계에서 다룹니다. 지금 확인해 둘 것은 이 값이 코드가 아니라 .env에 있다는 사실입니다. 값이 바뀌어도 코드를 고칠 필요가 없습니다.

.env의 값을 바꿔 실행해 보면 화면의 판단이 달라지는지 확인할 수 있습니다.

쉘 프롬프트

# 기준값을 잠시 높여 실행하고 판단이 달라지는지 확인
MIN_SIMILARITY=0.9 python3 search.py "무료로 대리인을 지원받는 제도가 있나요?" | head -4

질문           : 무료로 대리인을 지원받는 제도가 있나요?
최소 유사도 기준: 0.9

1위 [ip-004] 거리 0.xxxx / 유사도 0.xxxx (기준 미만)

같은 질문, 같은 검색 결과인데 판단만 바뀌었습니다. 명령 앞에 붙인 MIN_SIMILARITY=0.9는 그 한 번의 실행에만 적용되며 .env 파일은 바뀌지 않습니다. 다음 실행부터는 다시 0.35가 쓰입니다.

4. 근거를 프롬프트로 조립해 답변 만들기

→ 검색으로 고른 문서를 LLM에게 근거로 건네 답변 문장을 받습니다.

3절까지 만든 것은 문서를 찾아 유사도를 보여 주는 프로그램입니다. 사용자는 여전히 문서를 직접 읽어야 합니다. 0.1의 표에서 빠져 있다고 한 세 가지 중 첫 번째, 답변 문장을 만듭니다.

4.1 무엇을 어떤 형식으로 보낼지 정하기

1강 4.1에서 확인했듯 답변을 만드는 것은 Ollama의 /api/chat 경로이고 모델은 qwen3.5:4b입니다. 이 요청에는 두 종류의 내용을 보냅니다.

보낼 내용	역할	이 과정에서의 내용
지시문 (system)	어떻게 답할지 정하는 규칙	근거 안에서만 답하고, 근거 번호를 표시하고, 단정하지 않는다
사용자 입력 (user)	근거와 질문	검색으로 고른 문서 + 사용자의 질문

지시문에 넣을 규칙은 다섯 가지입니다. 각 규칙이 무엇을 막으려는 것인지가 중요합니다.

규칙	막으려는 것
근거에 적힌 내용만 사용	모델이 학습한 내용으로 답해 1강에서 본 상태로 돌아가는 것
근거에 없으면 없다고 밝힘	근거를 조금 벗어난 질문에 추측으로 답하는 것
문장 끝에 근거 번호 표시	어느 문장이 어느 문서에서 나왔는지 알 수 없게 되는 것
법적 판단을 단정하지 않음	문서를 전달하는 답변이 법률 자문처럼 읽히는 것
한국어로 답변	질문과 다른 언어로 답이 나오는 것

네 번째가 이 데이터에서 특히 중요합니다. 지식재산권 자료를 근거로 만든 답변이 "침해에 해당합니다" 같은 단정으로 읽히면, 그 문장을 그대로 업무 판단에 쓰게 됩니다. 1강 2.3에서 정리했듯 답변을 검토하고 업무에 쓸지 결정하는 것은 사람의 몫입니다. 지시문은 그 구분이 문장에 드러나게 하는 장치입니다.

근거는 다음과 같은 형식으로 조립합니다.

[근거]
[근거 1] 종류: 법령 / 제목: 특허심판원국선대리인의선임및운영에관한규칙 / 날짜: 2021-11-11
질문: 국선대리인의 선임 기준은 무엇인가요?
답변: 국선대리인의 선임 기준은 특허심판원장이 설정하며, ...

[근거 2] 종류: ... / 제목: ... / 날짜: ...
질문: ...
답변: ...

[질문]
무료로 대리인을 지원받는 제도가 있나요?

번호를 붙이는 이유는 답변에서 그 번호를 다시 쓰게 하기 위해서입니다. 번호가 없으면 모델이 어느 근거를 썼는지 표시할 방법이 없습니다.

2강 2.3에서 문서 본문에 질문: 과 답변: 표시를 붙여 둔 것이 여기에서 쓰입니다. 표시가 없으면 근거 안에서 어디까지가 질문이고 어디부터가 답변인지 구분되지 않습니다.

4.2 ask.py 만들기

VSCode에서 rag-basic 폴더에 ask.py를 만들고 아래 내용을 넣습니다. 이 코드에는 5절에서 다룰 분기가 이미 들어 있습니다. 4절에서는 근거가 있는 질문으로 먼저 확인하고, 5절에서 분기 부분을 자세히 봅니다.

"""근거 문서를 찾아 답변을 만들고, 근거가 없으면 답하지 않는다."""

from __future__ import annotations

import argparse
import time

import requests

from config import get_settings
from search import search

SYSTEM_PROMPT = (
    "당신은 지식재산권 질의응답 자료를 찾아 정리하는 도우미입니다.\n"
    "아래 [근거]에 적힌 내용만 사용해 한국어로 답하십시오.\n"
    "근거에 없는 내용은 추측하지 말고 근거 문서에 없다고 밝히십시오.\n"
    "답변에 사용한 근거를 문장 끝에 [근거 1] 형태로 표시하십시오.\n"
    "법적 판단을 단정하지 말고 문서에 적힌 내용을 그대로 전달하십시오."
)

REFUSAL_MESSAGE = (
    "가지고 있는 문서에서 이 질문과 관련된 근거를 찾지 못했습니다.\n"
    "질문을 다르게 표현하거나, 해당 내용을 담은 문서를 추가한 뒤 다시 시도하십시오."
)


def build_prompt(question: str, hits: list[dict]) -> str:
    """검색으로 고른 문서를 번호가 붙은 근거 목록으로 만들어 질문과 합친다."""
    blocks = []
    for number, hit in enumerate(hits, start=1):
        metadata = hit["metadata"]
        blocks.append(
            f"[근거 {number}] 종류: {metadata['type']} / "
            f"제목: {metadata['title']} / 날짜: {metadata['date']}\n"
            f"{hit['document']}"
        )
    evidence = "\n\n".join(blocks)
    return f"[근거]\n{evidence}\n\n[질문]\n{question}"


def call_llm(prompt: str) -> str:
    """조립한 프롬프트를 Ollama에 보내 답변 문장을 받는다."""
    settings = get_settings()
    response = requests.post(
        f"{settings.ollama_base_url}/api/chat",
        json={
            "model": settings.llm_model,
            "stream": False,
            "messages": [
                {"role": "system", "content": SYSTEM_PROMPT},
                {"role": "user", "content": prompt},
            ],
        },
        timeout=300,
    )
    response.raise_for_status()
    return response.json()["message"]["content"].strip()


def ask(question: str) -> dict:
    """검색 결과를 최소 유사도로 거르고, 남은 것이 있을 때만 LLM을 호출한다."""
    settings = get_settings()
    hits = search(question)
    grounded = [hit for hit in hits if hit["similarity"] >= settings.min_similarity]

    if not grounded:
        return {"answer": REFUSAL_MESSAGE, "sources": [], "llm_called": False}

    answer = call_llm(build_prompt(question, grounded))
    sources = [
        {
            "id": hit["id"],
            "type": hit["metadata"]["type"],
            "title": hit["metadata"]["title"],
            "similarity": round(hit["similarity"], 4),
        }
        for hit in grounded
    ]
    return {"answer": answer, "sources": sources, "llm_called": True}


def main() -> None:
    parser = argparse.ArgumentParser(description="근거 문서를 찾아 답변한다.")
    parser.add_argument("question", help="질문 한 줄")
    args = parser.parse_args()

    started = time.perf_counter()
    try:
        result = ask(args.question)
    except ValueError as error:
        raise SystemExit(f"입력 오류: {error}")
    except requests.exceptions.ConnectionError:
        raise SystemExit("Ollama 서버에 연결하지 못했습니다. sudo systemctl start ollama 로 시작한 뒤 다시 실행하십시오.")
    elapsed = time.perf_counter() - started

    called = "예" if result["llm_called"] else "아니오"
    print(f"[LLM 호출: {called} / 소요 {elapsed:.1f}초]")
    print()
    print(result["answer"])
    print()

    if result["sources"]:
        print("근거:")
        for source in result["sources"]:
            print(
                f"  - {source['type']} / {source['title']} "
                f"(유사도 {source['similarity']:.4f}, 문서번호 {source['id']})"
            )
    else:
        print("근거: 없음")


if __name__ == "__main__":
    main()

4.3 코드가 하는 일 확인하기

from search import search가 3절까지 만든 것을 그대로 씁니다. 검색 코드를 다시 쓰지 않습니다. 검색 방식을 고치면 search.py 한 곳만 고쳐도 ask.py의 동작이 함께 바뀝니다.

SYSTEM_PROMPT와 REFUSAL_MESSAGE를 파일 위쪽에 상수로 두었습니다. 이 두 문자열은 답변의 성격을 정하는 부분이라 자주 고치게 됩니다. 함수 안에 흩어져 있으면 어디를 고쳐야 하는지 찾기 어렵습니다.

ask()가 판단하고 main()이 출력합니다. ask()는 화면에 아무것도 쓰지 않고 결과를 사전으로 돌려줍니다. 그래서 나중에 이 함수를 화면 프로그램이나 HTTP API에서 그대로 쓸 수 있습니다. 8. RAG 강좌 4단계에서 이 구조가 쓰입니다.

llm_called 값을 결과에 넣었습니다. 이 값이 없으면 화면만 보고는 LLM을 불렀는지 알 수 없습니다. 5절에서 이 값이 판단의 근거가 됩니다.

time.perf_counter()로 걸린 시간을 잽니다. 5절에서 근거가 없을 때 응답이 빨라지는 것을 확인하는 데 씁니다.

stream: False를 보냅니다. 이 값이 없으면 Ollama가 답변을 조각조각 나눠 보내고, response.json()이 그 응답을 읽지 못합니다. 답변이 다 만들어진 뒤 한 번에 받으려면 이 값이 필요합니다.

4.4 근거가 있는 질문으로 실행하기

쉘 프롬프트

# 근거가 있는 질문으로 실행
python3 ask.py "무료로 대리인을 지원받는 제도가 있나요?"

[LLM 호출: 예 / 소요 xx.x초]

특허심판원은 국선대리인을 선임해 줄 수 있으며, 대상은 수급자와 국가유공자,
장애인 등 지원이 필요한 사람과 산업재산권 분쟁 중인 소기업·중기업입니다. [근거 1]

근거:
  - 법령 / 특허심판원국선대리인의선임및운영에관한규칙 (유사도 0.xxxx, 문서번호 ip-004)

답변 문장은 실행할 때마다 달라집니다. LLM은 같은 입력에도 같은 문장을 돌려주지 않습니다. 확인할 것은 문장이 같은지가 아니라 다음 세 가지입니다.

확인 항목	통과 기준
근거 표시	답변 문장에 `[근거 1]` 형태의 표시가 있다
출처 목록	답변 아래 `근거:`에 종류·제목·유사도·문서번호가 나온다
내용 대조	답변에 나온 대상(수급자, 국가유공자, 장애인, 소기업·중기업)이 `ip-004` 원문과 맞는다

세 번째가 이 과정에서 가장 중요한 확인입니다. 답변이 그럴듯한지가 아니라 근거 원문과 맞는지를 봅니다. 원문은 근거:에 표시된 문서번호로 찾을 수 있습니다.

쉘 프롬프트

# 답변에 표시된 문서번호로 원문 확인
python3 -c "
import json

records = [json.loads(line) for line in open('docs/qa_documents.jsonl', encoding='utf-8')]
for record in records:
    if record['id'] == 'ip-004':
        print(record['document'])
"

1강 1절에서 확인한 것과 비교해 봅니다. 그때는 답변만 나오고 출처가 없어 맞는지 확인할 방법이 없었습니다. 이제는 답변 아래에 문서번호가 있고, 그 번호로 원문을 찾아 대조할 수 있습니다.

다만 답변이 원문을 잘못 요약할 가능성은 남아 있습니다. 1강 2.3에서 정리한 세 번째 한계입니다. RAG는 답변의 정확성을 보장하지 않고, 근거를 밝혀 사람이 검토할 수 있게 할 뿐입니다.

⚠ 자주 겪는 오류

답변이 나오지 않고 오래 멈춰 있으면 모델을 처음 메모리에 올리는 중일 수 있습니다. qwen3.5:4b는 약 3.4GB이므로 첫 호출이 오래 걸립니다.

KeyError: 'message'가 나오면 stream 값을 빠뜨린 것입니다. 4.2 코드의 "stream": False 줄을 확인합니다.

답변이 한국어가 아닌 언어로 나오면 SYSTEM_PROMPT의 첫 부분이 제대로 전달되지 않은 것입니다. messages의 role이 system인지 확인합니다.

5. 근거가 없을 때 LLM을 호출하지 않게 만들기

→ 0.1에서 확인한 문제, 관련 없는 질문에도 문서가 나오는 상황을 처리합니다.

0.1에서 "오늘 점심 메뉴로 뭐가 좋을까요?"를 넣었더니 지식재산권 문서가 1위로 나왔습니다. 3.1에서 그 질문의 유사도가 기준을 넘지 못하는 것도 확인했습니다. 이제 그 판단을 프로그램의 동작으로 옮깁니다.

5.1 걸러 내는 부분 확인하기

4.2의 코드에서 그 일을 하는 부분은 다음 네 줄입니다.

    hits = search(question)
    grounded = [hit for hit in hits if hit["similarity"] >= settings.min_similarity]

    if not grounded:
        return {"answer": REFUSAL_MESSAGE, "sources": [], "llm_called": False}

grounded는 기준을 넘은 문서만 남긴 목록입니다. search()가 세 건을 돌려줘도 그중 기준을 넘는 것이 하나뿐이면 근거는 하나입니다.

if not grounded: 다음 줄에서 함수가 끝납니다. 아래에 있는 call_llm()까지 가지 않습니다. 이것이 이 절의 핵심입니다.

거르지 않으면 무엇이 달라지는지 정리하면 다음과 같습니다.

처리	범위 밖 질문일 때의 동작
거르지 않음	가장 가까운 문서 세 건을 근거로 붙여 LLM 호출. 관련 없는 문서를 근거로 답변이 만들어진다
기준으로 거름	남는 근거가 없으므로 LLM을 부르지 않고 거부 문구를 돌려준다

세 가지가 함께 달라집니다. 잘못된 답변이 나오지 않고, 응답이 빨라지고, 사용자가 "이 질문은 이 문서 묶음의 범위 밖"이라는 것을 알게 됩니다.

5.2 범위 밖 질문으로 실행하기

쉘 프롬프트

# 데이터와 관계없는 질문으로 실행
python3 ask.py "오늘 점심 메뉴로 뭐가 좋을까요?"

[LLM 호출: 아니오 / 소요 x.x초]

가지고 있는 문서에서 이 질문과 관련된 근거를 찾지 못했습니다.
질문을 다르게 표현하거나, 해당 내용을 담은 문서를 추가한 뒤 다시 시도하십시오.

근거: 없음

세 가지를 확인합니다.

확인 항목	통과 기준
`LLM 호출`	`아니오`
소요 시간	4.4의 실행보다 눈에 띄게 짧다
`근거:`	`없음`

두 번째가 이 강의에서 가장 중요한 관찰입니다. 화면의 LLM 호출: 아니오는 우리가 만든 표시일 뿐이지만, 응답 시간 차이는 실제로 호출하지 않았다는 증거입니다. LLM은 문장을 만드는 데 수 초에서 수십 초가 걸리고, 검색과 임베딩만 하면 1초 안팎입니다.

▶ 지금 해보세요

4.4의 질문과 5.2의 질문을 각각 실행하고 소요 시간을 적습니다. 몇 배 차이인지 계산합니다.
3.1의 C 질문(특허 출원 수수료는 얼마인가요?)을 ask.py로 실행하고, LLM 호출이 어느 쪽으로 나오는지 확인합니다.
2번에서 LLM이 호출되었다면 답변을 읽고, 답변이 근거 문서의 내용을 벗어나지 않는지 확인합니다.

두 번째와 세 번째가 이 과정에서 판단이 갈리는 자리입니다. 데이터에 없는 내용인데 유사도가 기준을 넘으면 LLM이 호출되고, 그때 지시문의 "근거에 없으면 없다고 밝히라"는 규칙이 남은 방어선이 됩니다. 기준값과 지시문 두 가지가 함께 작동합니다.

6. 최소 유사도 필터를 지웠을 때의 증상 확인하고 되돌리기

→ 5절에서 만든 규칙을 잠시 지우고 무엇이 나오는지 봅니다.

5.2에서 범위 밖 질문이 거부되는 것을 확인했습니다. 그런데 그 규칙이 없으면 어떤 답변이 나오는지는 아직 보지 않았습니다. 규칙이 무엇을 막고 있는지는 막지 않았을 때를 봐야 알 수 있습니다.

6.1 필터를 지우고 실행하기

ask.py를 고치지 않고, 필터를 뺀 동작을 명령으로 확인합니다. 원본 파일은 그대로 두는 방법입니다.

쉘 프롬프트

# 최소 유사도로 거르지 않고 검색 결과를 그대로 근거로 써 본다
python3 -c "
from ask import build_prompt, call_llm
from search import search

question = '오늘 점심 메뉴로 뭐가 좋을까요?'
hits = search(question)

print('근거로 쓰게 되는 문서:')
for hit in hits:
    print('   ', hit['id'], round(hit['similarity'], 4), hit['metadata']['title'][:20])
print()

answer = call_llm(build_prompt(question, hits))
print(answer)
"

근거로 쓰게 되는 문서:
    ip-0xx 0.xxxx ...
    ip-0xx 0.xxxx ...
    ip-0xx 0.xxxx ...

(지식재산권 문서를 근거로 만들어진 답변 문장)

유사도가 기준에 한참 못 미치는 문서 세 건이 근거로 들어갔습니다. 그 상태에서 나온 답변이 화면에 있습니다.

▶ 지금 해보세요

화면에 나온 답변을 그대로 적어 두고 다음 세 가지를 판단합니다.
답변이 질문에 대한 답인가, 아니면 근거 문서의 내용을 설명하고 있는가?
답변이 "근거 문서에 없습니다"라고 밝히는가, 아니면 그냥 답하는가?
이 답변을 처음 보는 사용자가 잘못된 답이라는 것을 알아차릴 수 있는가?

답변 내용은 실행할 때마다 다르지만, 세 번째 질문의 답은 대체로 같습니다. 화면에는 답변과 근거 문서가 함께 나오므로 형식은 정상으로 보입니다. 무엇이 잘못되었는지 알려면 사용자가 근거 문서를 열어 읽어야 합니다.

4.1에서 지시문에 "근거에 없으면 없다고 밝히라"는 규칙을 넣어 둔 것이 이 상황에서 얼마나 작동하는지도 함께 확인합니다. 지시문만으로는 충분하지 않습니다. 근거로 들어간 문서가 애초에 관련이 없으면, 그 문서를 설명하는 답변이 만들어질 수 있습니다.

6.2 원래 상태로 돌아왔는지 확인하기

6.1은 ask.py를 고치지 않고 함수를 직접 불러 확인한 것이므로 되돌릴 것이 없습니다. 그래도 파일이 그대로인지 확인하고 다음으로 넘어갑니다.

쉘 프롬프트

# ask.py의 필터 부분이 그대로인지 확인하고 다시 실행
grep -n "min_similarity" ask.py
python3 ask.py "오늘 점심 메뉴로 뭐가 좋을까요?" | head -1

70:    grounded = [hit for hit in hits if hit["similarity"] >= settings.min_similarity]
[LLM 호출: 아니오 / 소요 x.x초]

LLM 호출: 아니오가 다시 나오면 정상입니다. 줄 번호는 편집 상태에 따라 다를 수 있습니다.

이 절에서 확인한 것을 한 문장으로 정리하면 다음과 같습니다. 검색은 언제나 무언가를 돌려주므로, 돌려받은 것을 쓸지 말지는 검색 밖에서 판단해야 합니다.

7. 자주 만나는 오류와 해결 방법

→ 1절부터 6절까지에서 나오는 오류를 원인별로 정리합니다.

증상	원인	해결
`벡터 저장소가 없습니다`로 멈춤	2강의 `store.py`를 실행하지 않음	2강 4.5를 실행한 뒤 다시 시도
`Collection ip_docs does not exist`	저장 폴더는 있는데 컬렉션이 없음	`python3 store.py --reset` 실행
검색 결과가 0건	컬렉션이 비어 있음	`collection.count()`로 건수 확인. 0이면 2강 4.5 다시
1위 문서가 눈으로 봐도 관련이 없음	거리와 유사도를 뒤집어 계산	2.2의 비교 명령으로 방향 확인
모든 질문의 유사도가 비슷하게 낮음	저장할 때와 검색할 때 모델이 다름	`.env`의 `EMBEDDING_MODEL`을 바꾼 적이 있으면 `store.py --reset`으로 다시 저장
`KeyError: 'message'`	요청에 `"stream": False`가 없음	4.2 코드의 해당 줄 확인
`requests.exceptions.ConnectionError`	Ollama가 실행 중이 아님	`sudo systemctl start ollama`
답변에 `[근거 1]` 표시가 없음	모델이 지시문을 따르지 않음	오류가 아님. 8절의 남는 한계에 해당한다
응답이 매우 느림	모델을 처음 메모리에 올리는 중	두 번째 실행부터 빨라진다

다섯 번째가 원인을 찾기 가장 어렵습니다. 오류가 나지 않고 결과만 이상하기 때문입니다. 1.1에서 정리한 세 번째 상황이 이것입니다. .env의 모델 이름을 바꿨다면 저장한 벡터를 반드시 다시 만들어야 합니다.

8. 이 과정에서 정하지 않은 것 확인하기

→ 이 과정에서 쉬웠던 이유와 다음 단계에서 만날 것을 정리합니다.

프로그램이 완성되었습니다. 그런데 이 과정에서 우리가 정하지 않고 넘어간 것들이 있습니다.

1강 8절에서 같은 표를 미리 봤습니다. 이번에는 직접 만든 코드를 놓고 다시 봅니다. 각 항목이 어느 파일의 어느 부분에 해당하는지 함께 적었습니다.

이번 과정에서는	실제 데이터에서는	해당하는 코드	다루는 단계
파일 하나에 10건이 들어 있었다	폴더 다섯 개에 나뉜 파일 25개를 찾아 읽어야 한다	`build_docs.py`의 `INPUT_PATH` 한 줄	2단계
모든 건의 키가 같았다	문서 종류마다 키 이름이 다르다	`build_docs.py`의 `REQUIRED_KEYS`	2단계
제목이 모든 건에 있었다	심결례에는 제목 키가 없다	`build_record()`의 `row["title"]`	2단계
날짜 형식이 하나였다	네 가지 형식이 섞여 있다	`build_record()`의 `row["date"]`	2단계
임계값을 기본값 그대로 썼다	자기 데이터에서 재어 정해야 한다	`.env`의 `MIN_SIMILARITY`	2단계
문서 종류로 범위를 좁히지 않았다	종류를 지정해 좁혀야 한다	`search()`의 `collection.query()`	2단계
문서 하나가 최대 419자였다	사례 하나가 3만 5천 자가 넘는다	`build_record()`의 문서 조립	3단계
파일이 모두 정상이었다	일부 파일이 깨져 있다	`build_docs.py`의 `json.load()`	3단계
만든 사람이 쉘에서 혼자 썼다	다른 사람이 화면으로 쓸 수 있어야 한다	`ask()`가 사전을 돌려주는 구조	4단계
결과를 눈으로 확인했다	고칠 때마다 자동으로 확인해야 한다	이 과정의 모든 확인 절차	4단계

왼쪽 칸이 이 과정에서 쉬웠던 이유입니다. 데이터가 정리되어 있어서 쉬웠던 것이지 RAG가 원래 쉬운 것이 아닙니다.

표의 오른쪽 두 칸을 함께 보십시오. 열 개 항목 중 여섯 개가 build_docs.py와 .env에 몰려 있습니다. 검색과 답변을 만드는 search.py와 ask.py는 실제 데이터를 만나도 크게 달라지지 않습니다. RAG에서 데이터를 읽어 들이는 부분이 가장 많이 바뀌는 곳입니다.

이 표는 8. RAG 강좌 2단계 1강에서 다시 사용합니다. 그때는 미리 채워진 표를 보는 것이 아니라, 이번 과정에서 만든 build_docs.py를 실제 데이터 폴더에 그대로 실행해 보고 어디에서 멈추는지를 학습자가 직접 적습니다.

9. 실습 과제

→ 안내대로 따라 한 것을 조건을 바꿔 스스로 해 봅니다.

9.1 과제

과제 1. 자기 질문 다섯 개 만들기

데이터의 다섯 종류(판결문·법령·심결례·심결문·유권해석)에서 한 건씩 골라, 문서에 적힌 문장을 그대로 베끼지 말고 다른 표현으로 질문을 만듭니다. 각 질문에 대해 어느 문서가 1위로 나올지 미리 적어 둔 다음 search.py로 실행하고, 예상과 실제를 비교합니다.

과제 2. 답하면 안 되는 질문 다루기

"제가 만든 로고가 다른 회사 상표를 침해한 건가요?"처럼 판단을 요구하는 질문을 만들어 ask.py로 실행합니다. 답변이 단정적인 판단으로 읽히면 SYSTEM_PROMPT를 고쳐 다시 실행하고, 고치기 전과 후의 답변을 함께 남깁니다.

과제 3. 기준값을 바꿔 경계 찾기

3.1의 C 질문(특허 출원 수수료는 얼마인가요?)에 대해 MIN_SIMILARITY 값을 바꿔 가며 실행해, 거부와 답변이 갈리는 지점을 찾습니다. 3.2의 방법으로 명령 앞에 값을 붙여 실행하고 .env 파일은 고치지 않습니다.

과제 4. 질문을 빼고 답변만 저장했을 때의 순위 비교하기

2강 1.3에서 검토한 세 가지 안 중 "답변만"을 실제로 확인합니다. build_docs.py의 문서 본문을 답변만으로 바꾸고, 컬렉션 이름을 answer_only로 하여 따로 저장합니다. 과제 1에서 만든 질문 다섯 개로 두 컬렉션의 순위와 유사도를 비교합니다. 비교가 끝나면 build_docs.py를 되돌리고 answer_only 컬렉션을 지웁니다.

9.2 과제를 마쳤는지 판단하는 기준

과제	확인할 것
1	다섯 질문 중 예상과 실제가 다른 것이 있으면, 왜 다른 문서가 1위가 되었는지 두 문서의 본문을 놓고 설명할 수 있다
2	고치기 전과 후의 답변을 나란히 놓고, `SYSTEM_PROMPT`의 어느 문장이 어떤 변화를 만들었는지 짚을 수 있다
3	갈리는 지점의 값을 소수 둘째 자리까지 적을 수 있고, 그 값이 3.1에서 적은 C 질문의 유사도와 같다는 것을 확인했다
4	두 컬렉션의 순위가 달라진 질문이 어떤 것인지 적고, 질문과 답변을 합치기로 한 2강의 결정이 이 데이터에서 타당했는지 판단해 적었다

과제 4가 이 과정의 판단을 되짚는 과제입니다. 2강 1.3에서 세 가지 안 중 하나를 골랐고 그때는 근거가 설명뿐이었습니다. 검색을 만든 지금은 그 선택이 옳았는지 값으로 확인할 수 있습니다.

10. 다음 단계에서 확인할 것 — 실제 데이터로 같은 코드 실행하기

→ 이 과정을 마친 뒤 무엇으로 이어지는지 봅니다.

이 과정에서 파일 여섯 개를 만들어 RAG 한 벌을 완성했습니다. 1강 3절의 다섯 단계가 모두 코드가 되었습니다.

단계	만든 파일	이 과정에서 확인한 것
1. 문서 준비	`build_docs.py`	JSONL 10줄, 종류별 2건
2. 임베딩	`embedder.py`	벡터 차원 1024
3. 저장	`store.py`	컬렉션 10건, 거리 공간 `cosine`
4. 검색	`search.py`	글자가 겹치지 않는 질문으로 `ip-004`가 1위
5. 근거 기반 생성	`ask.py`	범위 안에서는 근거와 함께 답변, 범위 밖에서는 호출 없이 거부

8. RAG 강좌의 다음 단계는 같은 내용의 실제 데이터를 다룹니다. 내용이 같고 구조만 다르므로, 2단계 1강은 다음과 같이 시작합니다.

이 과정에서 만든 build_docs.py를 실제 데이터 폴더에 그대로 실행한다
        ↓
동작하지 않는다
        ↓
왜 동작하지 않는지가 곧 2단계에서 배울 목록이 된다

8절의 표를 그때 다시 꺼내 직접 채우게 됩니다. 이번에는 예고가 아니라 실행 결과로 채웁니다.

마지막으로 이 과정에서 만든 것이 남아 있는지 확인해 둡니다. 다음 단계에서 이 코드를 그대로 가져다 쓰기 때문입니다.

쉘 프롬프트

# 이 과정에서 만든 파일 여섯 개와 산출물 확인
cd ~/rag-basic
ls *.py
wc -l docs/qa_documents.jsonl
python3 -c "
import chromadb

from config import get_settings

settings = get_settings()
client = chromadb.PersistentClient(path=str(settings.chroma_path))
print('컬렉션 건수:', client.get_collection(settings.collection_name).count())
"

ask.py  build_docs.py  config.py  embedder.py  search.py  store.py
10 docs/qa_documents.jsonl
컬렉션 건수: 10

파일 여섯 개, 문서 10줄, 컬렉션 10건이면 이 과정이 끝난 상태입니다. 0강 7절의 삭제 절차는 다음 단계를 마친 뒤에 실행하십시오. Ollama와 모델은 다음 단계에서도 그대로 씁니다.