티발자랩

라즈베리파이5 AI 머신 세팅 1: 우분투 서버 설치와 SSD 부팅

Fri, 10 Jul 2026 00:00:00 GMT

라즈베리파이5로 홈서버를 만들고, 나중에는 외부에서 접속해 AI 도구를 실행하는 원격 머신으로 확장해 보려고 합니다. 첫 번째 단계는 라즈베리파이가 부팅할 수 있도록 운영체제가 담긴 저장 장치를 만드는 것입니다.

보통 microSD 카드에 운영체제를 설치하지만, 저는 홈서버로 계속 사용할 것을 생각해 SSD를 별도로 준비했습니다. SSD에 Ubuntu 이미지를 바로 기록하는 방법도 있지만, 이번 연재에서는 다음 순서로 진행합니다.

USB 메모리에 Ubuntu Server 이미지를 기록합니다.
USB 메모리로 라즈베리파이5를 먼저 부팅합니다.
정상 동작을 확인한 뒤 Ubuntu 시스템을 SSD로 복사합니다.
이후 SSD를 주 저장 장치로 사용합니다.

이번 글에서는 USB 이미지 만들기 → USB 첫 부팅 → NVMe SSD 복사 → SSD 재부팅 확인까지 한 번에 진행합니다.

라즈베리파이는 어떤 컴퓨터인가

라즈베리파이(Raspberry Pi)는 신용카드 정도 크기의 기판에 CPU, 메모리, USB, HDMI, 네트워크 같은 주요 부품과 단자를 모아 놓은 소형 싱글보드 컴퓨터입니다.

아두이노처럼 단순히 센서와 모터만 제어하는 보드와 달리, 라즈베리파이는 Ubuntu나 Raspberry Pi OS 같은 운영체제를 설치해 사용할 수 있습니다. 모니터와 키보드를 연결하면 작은 데스크톱 PC처럼 쓸 수 있고, 화면 없이 네트워크에 연결해 두면 웹 서버·파일 서버·개발 서버·자동화 머신처럼 운영할 수도 있습니다.

이번에 사용할 라즈베리파이5도 같은 구조입니다. 작은 크기와 비교적 낮은 소비전력 덕분에 계속 켜 두는 홈서버 입문 장비로 활용하기 좋습니다. 다만 일반 데스크톱 PC와 달리 저장 장치와 전원 공급 장치, 케이스와 냉각 장치 등을 사용 목적에 맞게 준비해야 합니다.

✍️ 운영자 한마디

저는 최종적으로 SSD를 사용할 예정이지만, 처음부터 SSD에 바로 기록하지 않았습니다. USB로 먼저 부팅 환경을 만든 뒤 정상 동작을 확인하고 SSD로 복사하는 방식으로 진행했습니다. 설치 과정에서 문제가 생겨도 USB 부팅 장치를 다시 활용할 수 있다는 점도 고려했습니다.

이번 설치에 준비한 것

Raspberry Pi 5
라즈베리파이5에 맞는 전원 공급 장치
Ubuntu Server 이미지를 기록할 USB 메모리
최종 저장 장치로 사용할 SSD와 라즈베리파이5 연결 장치
Raspberry Pi Imager를 실행할 윈도우 PC
유선 네트워크 또는 Wi-Fi 접속 정보

USB 메모리에는 중요한 파일이 없어야 합니다. 이미지를 기록하면 기존 파티션과 파일이 삭제됩니다. 비슷한 이름의 외장 SSD나 다른 USB가 PC에 연결되어 있다면 잠시 분리해 두는 것도 실수를 줄이는 방법입니다.

1. Raspberry Pi Imager 설치하기

Raspberry Pi Imager는 라즈베리파이용 운영체제 이미지를 저장 장치에 기록해 주는 공식 프로그램입니다. 단순히 이미지 파일을 복사하는 것이 아니라, 부팅에 필요한 파티션 구조까지 만들어 줍니다.

Raspberry Pi 공식 소프트웨어 페이지에 접속해 현재 사용하는 운영체제에 맞는 설치 파일을 내려받습니다. 저는 윈도우 PC에서 진행했기 때문에 Download for Windows를 선택했습니다.

설치가 끝나면 Raspberry Pi Imager를 실행합니다. 이 글의 캡처는 Raspberry Pi Imager v2.0.10 기준입니다. 프로그램 버전에 따라 메뉴 이름이나 화면 배치는 조금 달라질 수 있습니다.

2. 장치와 Ubuntu Server 선택하기

Imager를 실행하면 먼저 설치 대상 장치를 고릅니다.

장치: Raspberry Pi 5
운영 체제: Ubuntu Server 24.04.4 LTS (64-bit)
저장소: 준비한 USB 메모리

운영 체제 목록에서 Ubuntu 항목을 찾아 **Ubuntu Server 24.04.4 LTS (64-bit)**를 선택했습니다. 캡처 화면에는 Ubuntu Desktop과 Ubuntu Core도 함께 보이지만, 홈서버가 목적이므로 Server 이미지를 사용합니다.

Ubuntu Desktop은 그래픽 화면을 포함한 일반 PC 사용에 가깝습니다. Ubuntu Server는 그래픽 데스크톱이 기본으로 설치되지 않고 터미널과 네트워크 서비스 중심으로 시작합니다. 모니터를 계속 연결하지 않고 SSH로 관리할 홈서버에는 Server 쪽이 더 단순합니다.

화면에 표시되는 최신 세부 버전은 글을 보는 시점에 달라질 수 있습니다. 같은 24.04 LTS 계열이라도 Imager 업데이트에 따라 24.04.4보다 새로운 유지보수 버전이 표시될 수 있으므로, 화면의 설명과 지원 장치를 확인한 뒤 선택하세요.

3. 저장소에서 USB 메모리 선택하기

다음은 이미지를 기록할 저장 장치를 선택하는 단계입니다. 저는 microSD 카드가 아니라 SanDisk Ultra USB 3.0 USB Device를 선택했습니다.

여기가 가장 주의해야 할 화면입니다. 쓰기를 시작하면 선택한 저장 장치의 기존 내용이 삭제됩니다.

장치 이름이 준비한 USB 메모리와 일치하는지 확인합니다.
표시된 용량이 USB 메모리의 실제 용량과 맞는지 확인합니다.
외장 SSD나 백업 디스크를 잘못 선택하지 않았는지 다시 확인합니다.

SSD에 이미지를 바로 기록하고 싶다면 이 단계에서 USB 대신 PC에 연결한 SSD를 선택할 수도 있습니다. 하지만 이번 글에서는 USB로 첫 부팅한 뒤 SSD로 복사할 예정이므로 USB 메모리를 선택합니다.

4. 호스트 이름 정하기

운영체제와 저장 장치를 고르면 사용자 지정 단계가 이어집니다. 먼저 호스트 이름을 정합니다. 호스트 이름은 같은 네트워크에서 라즈베리파이를 구분하는 컴퓨터 이름입니다.

캡처에서는 pi-office를 입력했습니다. 그대로 복사할 필요는 없으며, 용도를 알아보기 쉬운 이름으로 정하면 됩니다.

예를 들면 다음과 같습니다.

pi-home
pi-server
raspi5-ai

호스트 이름은 영문 소문자, 숫자, 하이픈을 조합해 짧게 만드는 편이 관리하기 쉽습니다. 나중에 같은 네트워크에서 호스트이름.local 형태로 접근할 때 쓰일 수 있지만, 공유기와 운영체제의 이름 해석 환경에 따라 동작하지 않을 수도 있습니다. 접속이 안 되면 공유기에서 할당된 IP 주소를 확인하면 됩니다.

5. 지역·시간대·키보드 설정하기

지역화 화면에서는 시간대와 키보드 배열을 설정합니다.

캡처에서는 다음과 같이 선택했습니다.

수도 도시: Seoul (South Korea)
시간대: Asia/Seoul
키보드 레이아웃: kr

시간대가 맞지 않으면 서버 로그와 예약 작업 시간이 실제 시간과 다르게 기록될 수 있습니다. 홈서버에서 자동화 작업을 예약할 예정이라면 Asia/Seoul 설정을 확인해 두는 것이 좋습니다.

6. 사용자 이름과 비밀번호 만들기

다음은 Ubuntu에 로그인할 사용자 계정을 만드는 단계입니다.

캡처에서는 사용자 이름을 calvin으로 설정했지만, 이 이름도 각자 원하는 값으로 바꾸면 됩니다. 사용자 이름은 소문자 영문, 숫자, 밑줄과 하이픈만 사용하는 것이 안전합니다.

비밀번호는 원격 SSH 접속에 사용될 수 있으므로 추측하기 어려운 값으로 정합니다. 블로그나 커뮤니티에 설정 화면을 공유할 때는 비밀번호가 보이지 않는지 꼭 확인하세요. 이 글의 캡처에서는 비밀번호가 점으로 가려져 있습니다.

사용자 이름과 비밀번호는 첫 부팅 후 필요합니다. 잊지 않도록 안전한 암호 관리 도구에 보관하세요.

7. Wi-Fi 미리 설정하기

무선 네트워크를 사용할 경우 Imager의 Wi-Fi 단계에서 공유기 이름(SSID)과 비밀번호, 국가를 설정합니다. 쓰기 완료 화면에서 Wi-Fi 설정이 적용된 것을 확인할 수 있습니다.

다만 홈서버는 가능하면 유선 LAN 연결이 더 단순하고 안정적입니다. 처음 부팅할 때 유선 네트워크를 사용할 예정이라면 Wi-Fi 설정을 건너뛰어도 됩니다. 무선을 사용할 경우 다음을 확인하세요.

SSID와 비밀번호의 대소문자가 정확한지
숨김 네트워크인지
Wi-Fi 국가가 대한민국으로 설정되어 있는지
라즈베리파이가 공유기 신호를 안정적으로 받을 위치인지

Wi-Fi 비밀번호가 보이는 화면은 캡처해서 공개하지 않는 것이 좋습니다.

8. SSH 원격 접속 켜기

이번 홈서버는 모니터와 키보드를 계속 연결하지 않고 다른 PC에서 원격으로 관리할 예정입니다. 그래서 Imager의 원격 접근 단계에서 SSH를 사용하도록 설정합니다.

캡처에서는 다음과 같이 선택했습니다.

SSH 사용: 켬
인증 방식: 비밀번호 인증 사용

비밀번호 인증은 처음 연결할 때 이해하기 쉽다는 장점이 있습니다. 하지만 서버를 외부 인터넷에 직접 노출할 계획이라면 비밀번호 인증만으로 끝내지 말고, 이후 공개 키 인증과 방화벽, VPN 또는 별도의 안전한 원격 접속 방식을 함께 검토해야 합니다.

이번 단계에서는 먼저 같은 집 안의 로컬 네트워크에서 접속하는 것을 목표로 합니다. 공유기의 포트포워딩을 바로 켜거나 SSH 22번 포트를 인터넷에 그대로 공개하지는 않습니다.

9. 이미지 쓰기와 완료 확인

설정을 마쳤다면 선택 내용을 마지막으로 확인한 뒤 쓰기를 시작합니다. 이 과정에서 Ubuntu 이미지 다운로드, USB 기록, 검증이 차례로 진행됩니다. 네트워크 속도와 USB 메모리 성능에 따라 시간이 걸릴 수 있습니다.

쓰기 전에 반드시 확인할 항목은 세 가지입니다.

장치가 Raspberry Pi 5인지
운영체제가 Ubuntu Server 24.04 LTS 64-bit인지
저장소가 지워도 되는 USB 메모리인지

완료 화면에서는 이번에 적용된 내용을 한 번에 확인할 수 있습니다.

캡처 기준으로 다음 설정이 적용되었습니다.

장치: Raspberry Pi 5
운영체제: Ubuntu Server 24.04.4 LTS (64-bit)
저장소: SanDisk Ultra USB 3.0 USB Device
호스트 이름 설정 완료
지역화 설정 완료
사용자 계정 설정 완료
Wi-Fi 설정 완료
SSH 활성화 완료

저장 장치가 자동으로 꺼졌습니다라는 안내가 보이면 운영체제에서 안전하게 제거할 수 있는 상태입니다. 완료를 누르고 USB 메모리를 PC에서 분리합니다.

10. USB와 SSD를 연결해 첫 부팅하기

USB 이미지 기록이 끝났다면 라즈베리파이5의 전원을 끈 상태에서 USB 메모리와 SSD를 연결합니다. 제가 사용한 케이스에서는 아래쪽 USB 메모리가 임시 부팅 장치이고, 내부 NVMe SSD가 최종 저장 장치입니다.

처음 부팅할 때는 모니터와 키보드를 연결해 두면 진행 상황을 직접 확인하기 쉽습니다. 가능하면 유선 LAN도 함께 연결합니다.

전원을 넣기 전에 USB와 SSD가 단단히 연결됐는지 확인합니다.
첫 부팅은 파일시스템 확장과 초기 설정 때문에 평소보다 오래 걸릴 수 있습니다.
부팅 중에는 전원을 뽑지 않습니다.
USB로 부팅되지 않으면 전원 부족, USB 포트, 이미지 기록 상태와 부트 순서를 확인합니다.

정상 부팅되면 Imager에서 설정한 호스트 이름과 함께 Ubuntu 로그인 프롬프트가 나타납니다. 캡처에서는 Ubuntu 24.04.4 LTS pi-office tty1과 pi-office login:이 표시됐습니다.

Imager에서 만든 사용자 이름과 비밀번호로 로그인합니다. 비밀번호를 입력해도 화면에는 글자가 표시되지 않지만 정상 동작입니다.

11. `lsblk`로 USB와 SSD 구분하기

SSD에 복사하기 전에 가장 중요한 단계는 원본 USB와 대상 SSD를 정확히 구분하는 것입니다.

lsblk

제 환경에서는 다음과 같이 표시됐습니다.

sda — 14.3G, 이동식 장치(RM 1)
sda1 — /boot/firmware에 마운트
sda2 — /에 마운트
nvme0n1 — 238.5G, 아직 파티션과 마운트 지점이 없는 SSD

현재 루트(/)가 sda2에 마운트되어 있으므로 sda가 USB 부팅 원본이고, 용량이 큰 nvme0n1이 복사 대상 SSD라는 것을 확인할 수 있습니다.

여기서 반드시 멈추고 확인하세요

화면의 sda와 nvme0n1을 그대로 복사하지 않습니다.
내 환경에서 현재 /가 마운트된 장치가 원본입니다.
대상 SSD의 모델과 용량이 준비한 제품과 일치해야 합니다.
대상 SSD는 원본 USB보다 커야 합니다.
대상 SSD에 필요한 자료가 있다면 먼저 백업합니다.

장치 이름은 연결 방식과 환경에 따라 달라질 수 있습니다. 원본과 대상을 반대로 지정하면 USB 시스템을 SSD로 복사하는 것이 아니라, 빈 SSD 내용으로 현재 부팅 USB를 덮어써 데이터가 사라질 수 있습니다.

12. SSD의 기존 서명 지우기

대상 SSD를 다시 확인한 다음, 기존에 남아 있을 수 있는 파일시스템과 파티션 서명을 지웁니다. 제 환경의 대상은 /dev/nvme0n1이었습니다.

sudo wipefs -a /dev/nvme0n1

wipefs -a는 지정한 장치의 파일시스템 서명을 제거합니다. 이 명령부터는 되돌리기 어렵습니다. 자신의 lsblk 결과에서 확인한 SSD 장치 이름으로 바꿔야 하며, 현재 /가 마운트된 USB 장치를 지정하면 안 됩니다.

명령을 실행하기 직전에 한 번 더 확인하려면 다음처럼 장치의 모델과 용량까지 함께 봅니다.

lsblk -o NAME,SIZE,MODEL,TRAN,RM,MOUNTPOINTS

13. `dd`로 USB 전체를 SSD에 복사하기

이제 USB 디스크 전체를 NVMe SSD로 복사합니다. 캡처 환경에서는 원본이 /dev/sda, 대상이 /dev/nvme0n1이었습니다.

sudo dd if=/dev/sda of=/dev/nvme0n1 bs=4M status=progress conv=fsync

옵션의 의미는 다음과 같습니다.

if=/dev/sda — 읽어 올 원본 USB 디스크
of=/dev/nvme0n1 — 덮어쓸 대상 SSD
bs=4M — 4MB 단위로 복사
status=progress — 복사한 용량과 속도를 화면에 표시
conv=fsync — 종료 전에 기록 내용을 저장 장치에 반영

dd는 확인 질문 없이 바로 복사를 시작합니다. if와 of가 뒤바뀌면 원본이 손상되므로 명령을 실행하기 전에 반드시 소리 내어라도 원본 USB → 대상 SSD 순서를 다시 확인하세요.

실행 중인 시스템 자체를 복사하는 방식이므로 복사하는 동안 패키지 설치, 파일 다운로드, 로그를 많이 만드는 서비스 등 쓰기 작업은 하지 않는 편이 안전합니다. 홈서버 서비스를 설치하기 전, 첫 부팅 직후에 복사한 이유도 변경되는 파일을 최소화하기 위해서입니다.

복사가 끝나면 records in, records out과 함께 전체 복사 용량이 표시되고 프롬프트가 다시 나타납니다. 제 환경에서는 약 15GB가 복사됐습니다. 시간과 속도는 USB와 SSD 성능에 따라 달라집니다.

마지막으로 대기 중인 쓰기 내용을 저장 장치에 반영합니다.

sync

14. 전원을 끄고 USB 제거 후 재부팅하기

복사 직후 USB와 SSD에는 같은 파티션 정보가 들어 있습니다. 두 장치를 연결한 채 바로 재부팅하면 어느 장치로 부팅했는지 판단하기 어렵거나 같은 식별자 때문에 혼동될 수 있습니다.

먼저 정상 종료합니다.

sudo poweroff

화면이 꺼지고 라즈베리파이의 동작이 멈춘 것을 확인한 뒤 다음 순서로 진행합니다.

전원 케이블을 분리합니다.
Ubuntu를 담았던 USB 메모리를 제거합니다.
NVMe SSD는 연결된 상태로 둡니다.
전원을 다시 연결해 부팅합니다.

로그인 화면이 다시 나타나면 기존 사용자 이름과 비밀번호로 로그인합니다.

15. SSD로 부팅됐는지 확인하기

로그인 화면이 보인다는 사실만으로는 SSD 부팅을 확정할 수 없습니다. 실제 루트 파일시스템(/)이 NVMe SSD에 올라왔는지 확인해야 합니다.

df -h

캡처에서는 다음 결과를 확인했습니다.

/dev/nvme0n1p2 — /에 마운트, 약 235G
/dev/nvme0n1p1 — /boot/firmware에 마운트, 약 505M

즉 USB가 아니라 NVMe SSD의 두 파티션으로 부팅된 상태입니다. 복사 직후 원본 USB의 루트 파티션은 약 13.8G였지만, 이번 환경에서는 SSD 첫 부팅 과정에서 루트 파티션과 파일시스템이 확장되어 약 235G로 표시됐습니다.

조금 더 명확히 확인하려면 다음 명령도 사용할 수 있습니다.

findmnt /
lsblk

findmnt / 결과의 소스가 NVMe 파티션을 가리키고, lsblk에서 같은 파티션이 /에 마운트되어 있으면 SSD 전환이 완료된 것입니다. 용량이 여전히 USB와 비슷하게 작게 나온다면 자동 확장이 되지 않은 것이므로, 데이터를 저장하기 전에 파티션과 파일시스템 확장 상태를 별도로 점검해야 합니다.

Ubuntu Server SSD 설치 완료 체크리스트

USB로 Ubuntu Server 로그인 화면까지 부팅했다
lsblk로 현재 루트가 USB에 마운트된 것을 확인했다
원본 USB와 대상 NVMe SSD의 이름·용량을 구분했다
wipefs와 dd의 대상을 실행 전에 다시 확인했다
복사 완료 후 sync와 sudo poweroff로 정상 종료했다
USB를 제거하고 SSD만 연결한 상태로 다시 부팅했다
df -h에서 NVMe 파티션이 /와 /boot/firmware에 마운트된 것을 확인했다

정리

이번 글에서는 라즈베리파이의 기본 개념부터 Raspberry Pi Imager로 USB 메모리에 Ubuntu Server 이미지를 기록하는 과정, USB 첫 부팅, NVMe SSD 복사와 재부팅 확인까지 진행했습니다.

핵심은 명령 자체보다 lsblk로 원본과 대상을 정확히 구분하는 것입니다. wipefs와 dd는 장치를 잘못 지정하면 데이터를 즉시 지울 수 있으므로 화면의 장치 이름을 무작정 따라 입력하면 안 됩니다. 복사가 끝난 뒤에는 USB를 제거하고 재부팅한 다음, df -h나 findmnt /로 루트 파일시스템이 실제 NVMe SSD에 올라왔는지 확인해야 설치가 끝난 것입니다.

이제 SSD 기반 Ubuntu Server가 준비됐습니다. 다음 글부터는 같은 네트워크의 다른 PC에서 SSH로 접속하고, 홈서버와 원격 AI 머신으로 사용하기 위한 기본 업데이트와 원격 관리 환경을 구성해 보겠습니다.

공식 자료

터미널 반복 작업을 자동화 흐름으로 나누는 법

Thu, 09 Jul 2026 08:55:52 GMT

터미널에서 반복해서 하는 일이 생기면 “이거 자동화하면 좋겠다”는 생각이 듭니다. 예전 같으면 셸 스크립트 문법을 하나씩 배워야 했지만, 지금은 AI에게 자동화 스크립트 초안을 맡길 수 있습니다.

다만 “이 작업 자동화해줘”라고만 말하면 결과가 애매해집니다. AI가 어떤 파일을 처리해야 하는지, 실패하면 멈춰야 하는지, 원본을 건드려도 되는지 모르기 때문입니다.

그래서 입문자에게 더 중요한 것은 스크립트 문법을 다 외우는 것이 아니라, AI에게 맡길 자동화 흐름을 정확히 설명하고 결과를 검수하는 것입니다.

1단계: 자동화할 작업을 한 문장으로 좁힌다

먼저 자동화할 일을 작게 정합니다.

너무 넓은 요청은 좋지 않습니다.

문서 업무 자동화하기
블로그 운영 자동화하기
자료 정리 자동화하기

AI에게 맡기려면 이렇게 좁히는 편이 좋습니다.

docs 폴더의 PDF 파일을 텍스트로 변환한다
변환된 텍스트가 비어 있지 않은지 확인한다
문제가 없을 때만 ai-inputs 폴더로 복사한다
원본 PDF는 삭제하지 않는다

이 정도까지 좁히면 AI가 만들 결과도 훨씬 안전해집니다.

2단계: 손으로 하던 일을 단계로 나눈다

자동화는 보통 아래 다섯 칸으로 나눌 수 있습니다.

단계	AI에게 설명할 내용	예시
입력	어떤 파일이나 폴더를 받을지	`./docs` 안의 PDF
처리	무엇을 할지	PDF를 텍스트로 변환
검증	결과가 정상인지 어떻게 볼지	텍스트 파일이 비어 있지 않은지 확인
출력	어디에 결과를 둘지	`./ai-inputs` 폴더로 복사
금지/실패	하지 말아야 할 일	원본 삭제 금지, 실패 시 중단

이 표가 사실상 자동화 설계도입니다. 이걸 먼저 만들면 AI에게 훨씬 정확히 요청할 수 있습니다.

3단계: AI에게 줄 작업 정의서를 만든다

위 표를 바탕으로 AI에게 줄 요청을 문장으로 만듭니다.

WSL Ubuntu에서 실행할 자동화 스크립트를 만들어줘.

목표:
- ./docs 폴더 안의 PDF 파일을 텍스트 파일로 변환한다.
- 변환 결과가 비어 있지 않으면 ./ai-inputs 폴더로 복사한다.

조건:
- 원본 PDF는 삭제하지 않는다.
- 기존 txt 파일을 덮어쓰기 전에 경고하거나 다른 이름을 사용한다.
- 처음 버전은 처리 대상 목록을 먼저 보여주는 안전한 방식으로 만든다.
- 각 명령이 무엇을 하는지 주석으로 설명한다.
- 실패했을 때 어떤 메시지를 확인해야 하는지도 알려준다.

이렇게 요청하면 AI는 단순한 명령 나열보다 더 안전한 초안을 만들 가능성이 큽니다.

4단계: AI가 만든 결과에서 볼 것

AI가 스크립트나 명령을 만들어오면 바로 실행하지 말고 아래 순서로 확인합니다.

입력 경로가 맞는가

AI가 ./docs, /home/user/docs, /mnt/c/... 같은 경로를 임의로 만들 수 있습니다. 내가 실제로 쓰는 폴더인지 확인해야 합니다.

확인할 명령은 이 정도면 충분합니다.

pwd
ls

출력 위치가 안전한가

결과 파일을 어디에 두는지도 봅니다. 원본 파일과 같은 위치에 덮어쓰는지, 별도 폴더에 저장하는지 확인합니다.

입문 단계에서는 별도 출력 폴더를 쓰는 편이 안전합니다.

./ai-inputs
./output
./converted

실패 조건이 있는가

변환 결과가 비어 있거나 입력 파일이 없을 때 그냥 다음 단계로 넘어가면 안 됩니다. AI가 만든 코드 안에 이런 확인이 있는지 봅니다.

완벽히 이해할 필요는 없지만, 아래처럼 “없으면 멈춘다”, “비어 있으면 멈춘다”는 조건이 있는지 확인하면 됩니다.

test -f 파일명
test -s 결과파일

위험 명령이 있는가

처음 버전에는 아래 명령이 들어가면 한 번 멈추는 것이 좋습니다.

rm
mv
chmod -R
chown -R
sudo

이 명령들이 무조건 나쁜 것은 아닙니다. 하지만 삭제, 이동, 권한 변경, 관리자 권한이 들어가므로 AI에게 “왜 필요한지 설명해줘”라고 다시 물어보는 편이 안전합니다.

5단계: 처음에는 확인 모드로 요청한다

처음부터 실제 파일을 바꾸게 하지 말고 확인 모드로 요청하세요.

AI에게 이렇게 말하면 됩니다.

첫 번째 버전은 실제 변환이나 복사를 하지 말고,
처리 대상 파일 목록과 생성될 결과 파일 경로만 보여주는 dry-run 버전으로 만들어줘.

대상 목록이 맞는지 확인한 뒤에 다음 요청을 합니다.

대상 목록이 맞아. 이제 실제 변환을 하되 원본 삭제는 하지 않는 버전으로 바꿔줘.

이렇게 단계별로 넓히면 실수해도 되돌리기 쉽습니다.

6단계: AI에게 다시 물어볼 로그를 남긴다

자동화가 실패하면 AI에게 다시 보여줄 정보가 필요합니다. “안 돼요”보다 아래처럼 정리하면 좋습니다.

실행한 명령:
./pdf-to-ai-input.sh ./docs/report.pdf

나온 에러:
[에러 메시지 붙여넣기]

확인한 것:
- ./docs/report.pdf 파일은 있음
- ./ai-inputs 폴더는 있음
- 결과 txt 파일은 0바이트임

원하는 것:
왜 txt가 비어 있는지 확인하는 다음 점검 순서를 알려줘.

이렇게 주면 AI가 원인을 훨씬 잘 좁혀줍니다.

7단계: AI 워크플로우를 붙일 때도 중간 파일을 남긴다

AI 요약이나 분류를 붙일 때도 중간 결과를 남기는 편이 좋습니다.

01-original.pdf
02-extracted.txt
03-cleaned.txt
04-ai-summary.md

요약이 이상할 때 원인을 나눠 볼 수 있습니다.

PDF 추출이 잘못됐는가
전처리에서 내용이 사라졌는가
AI 프롬프트가 모호했는가
저장 단계에서 깨졌는가

AI 결과만 보면 그럴듯해 보여서 원인을 놓치기 쉽습니다. 그래서 자동화 흐름 안에 검증 지점을 남기는 것이 중요합니다.

AI에게 자동화 작업을 맡기기 전 체크리스트

자동화할 작업을 한 문장으로 좁혔다
입력, 처리, 검증, 출력, 금지 조건을 적었다
원본 삭제와 덮어쓰기는 하지 말라고 명시했다
처음에는 dry-run 또는 대상 목록 확인 버전으로 요청했다
AI가 만든 결과에서 경로, 출력 위치, 실패 조건, 위험 명령을 확인했다
실패했을 때 AI에게 다시 보여줄 로그 형식을 정했다

정리

터미널 반복 작업을 자동화 흐름으로 만든다는 것은 명령어를 하나하나 외워서 직접 스크립트를 완성하는 일이 아닙니다. 입력, 처리, 검증, 출력, 금지 조건을 정리해 AI에게 맡길 수 있는 형태로 만드는 일입니다.

입문자는 스크립트 문법을 모두 이해하지 않아도 됩니다. 대신 AI가 만든 결과에서 어떤 파일을 건드리는지, 어디에 저장하는지, 실패하면 멈추는지, 위험한 명령이 들어갔는지를 확인할 수 있어야 합니다.

첫 CLI 자동화 전에 점검할 5가지

Thu, 09 Jul 2026 08:55:52 GMT

첫 CLI 자동화는 직접 스크립트를 잘 짜지 못해서 실패하기보다, AI에게 맡길 조건을 제대로 정리하지 않아서 실패하는 경우가 많습니다. “이 작업 자동화해줘”라고만 요청하면 AI는 입력 파일, 출력 위치, 실패 조건, 금지할 동작을 추측할 수밖에 없습니다.

입문자가 해야 할 일은 셸 문법을 전부 외우는 것이 아닙니다. AI에게 무엇을 맡길지 좁히고, AI가 만든 결과에서 위험한 부분을 확인하는 것입니다.

1. 자동화할 작업을 한 문장으로 좁힌다

처음에는 하나만 골라야 합니다.

너무 넓은 요청은 좋지 않습니다.

개발 작업을 자동화하기
블로그 운영을 자동화하기
파일 관리를 자동화하기

AI에게는 이렇게 좁혀서 말하는 편이 좋습니다.

drafts 폴더의 마크다운 파일 목록을 보여줘
PDF 파일에서 텍스트를 뽑아 같은 이름의 .txt로 저장해줘
빌드 전에 현재 브랜치와 변경 파일을 확인해줘
오래된 로그 파일을 삭제하지 말고 목록만 보여줘

한 문장으로 좁히기 어렵다면 아직 자동화할 준비가 덜 된 것입니다.

2. 입력과 출력 예시를 적는다

AI에게 자동화를 맡길 때는 입력과 출력이 분명해야 합니다.

예를 들어 PDF 변환 자동화라면 이렇게 적습니다.

입력: ./docs/report.pdf
출력: ./docs/report.txt

빌드 전 확인 자동화라면 이렇게 적을 수 있습니다.

입력: 현재 git 저장소
출력: 현재 브랜치, 변경 파일 목록, 빌드 성공/실패

이 정도만 적어도 AI가 훨씬 덜 추측합니다.

3. 하지 말아야 할 일을 먼저 적는다

첫 자동화에서 가장 중요한 것은 “무엇을 할지”보다 “무엇을 하지 말아야 할지”입니다.

처음 요청에는 이런 조건을 넣는 편이 좋습니다.

주의:
- 원본 파일을 삭제하지 마.
- 기존 파일을 덮어쓰지 마.
- 외부로 메일이나 API 요청을 보내지 마.
- 먼저 대상 목록만 보여주는 버전으로 만들어줘.

AI가 만든 스크립트에 아래 명령이 보이면 바로 실행하지 말고 한 번 멈추세요.

rm
mv
sudo
chmod -R
chown -R
curl ... | sh

이 명령들이 항상 나쁜 것은 아닙니다. 하지만 삭제, 이동, 관리자 권한, 권한 변경, 외부 스크립트 실행과 연결될 수 있으니 이유를 확인해야 합니다.

4. 처음에는 확인 모드로 요청한다

첫 버전은 실제로 파일을 바꾸지 않는 것이 좋습니다. 처리 대상과 예상 결과만 보여주는 버전으로 요청하세요.

AI에게 이렇게 말할 수 있습니다.

첫 번째 버전은 dry-run으로 만들어줘.
실제 파일을 변경하지 말고,
처리 대상 파일 목록과 생성될 결과 경로만 출력해줘.

그 결과가 맞으면 다음 단계로 넘어갑니다.

대상 목록이 맞아.
이제 실제 변환을 하되 원본 파일은 삭제하지 않는 버전으로 바꿔줘.

이렇게 두 단계로 나누면 실수했을 때 되돌리기가 쉽습니다.

5. 실패했을 때 AI에게 보여줄 정보를 정한다

자동화는 언젠가 실패합니다. 실패했을 때 “안 돼요”라고만 말하면 AI도 추측하게 됩니다.

아래처럼 정리해서 다시 물어보는 편이 좋습니다.

실행한 명령:
[명령 붙여넣기]

나온 에러:
[에러 메시지 붙여넣기]

확인한 것:
- 입력 파일은 존재함
- 출력 폴더는 존재함
- 결과 파일은 생성되지 않음

원하는 것:
다음 점검 순서를 알려줘.

이 형식을 미리 정해두면 문제가 생겨도 당황하지 않습니다.

AI에게 바로 줄 수 있는 요청 예시

아래처럼 요청하면 첫 자동화 초안으로 충분합니다.

WSL Ubuntu에서 실행할 간단한 자동화 스크립트를 만들어줘.

목표:
- ./docs 폴더 안의 PDF 파일 목록을 확인한다.
- 나중에 텍스트 변환으로 확장할 예정이다.

조건:
- 첫 버전은 dry-run으로 만든다.
- 파일 삭제, 덮어쓰기, 외부 전송은 하지 않는다.
- 각 명령이 무엇을 하는지 주석으로 설명한다.
- 실행 후 내가 확인해야 할 결과도 알려준다.

이 정도면 AI가 만든 결과를 검수하기도 쉽습니다.

첫 CLI 자동화 체크리스트

자동화할 작업을 한 문장으로 좁혔다
입력 예시와 출력 예시를 적었다
삭제·덮어쓰기·외부 전송 금지를 명시했다
첫 버전은 dry-run 또는 대상 목록 확인으로 요청했다
AI가 만든 결과에서 위험 명령을 확인했다
실패했을 때 AI에게 보여줄 명령·에러·확인 내용을 정했다

정리

첫 CLI 자동화는 셸 스크립트를 직접 완성하는 일이 아닙니다. AI에게 맡길 작업을 작게 정의하고, 입력과 출력, 금지 조건, 확인 방법을 정하는 일입니다.

입문자는 문법을 모두 외우지 않아도 됩니다. 대신 AI가 만든 결과에서 어떤 파일을 건드리는지, 삭제나 덮어쓰기가 있는지, 실패했을 때 어떤 로그를 다시 보여줘야 하는지는 확인할 수 있어야 합니다.

AI 코딩 도구에 코드 올리기 전 확인할 것들

Thu, 09 Jul 2026 06:35:11 GMT

AI 코딩 도구를 쓰다 보면 파일을 통째로 읽히거나, 오류 로그를 그대로 붙여 넣고 싶을 때가 많습니다. Claude Code, Codex, Gemini CLI처럼 프로젝트 안에서 동작하는 도구는 특히 편합니다. 대신 편한 만큼 “무엇을 넘기고 있는지”를 놓치기도 쉽습니다.

코드 자체보다 더 위험한 것은 코드 주변에 붙어 있는 값입니다. API 키, 토큰, 쿠키, 접속 문자열, 개인 이메일, 내부 서버 주소 같은 것들입니다. 이 글은 AI 코딩 도구에 자료를 넘기기 전에 확인할 최소한의 기준과 실제 점검 순서를 정리합니다.

먼저 “AI에게 필요한 정보”를 좁힌다

AI에게 질문하기 전에 먼저 범위를 줄입니다. 대부분의 코딩 질문에 필요한 것은 프로젝트 전체가 아니라 아래 네 가지입니다.

실행한 명령
에러 메시지
관련 파일 일부
기대한 결과와 실제 결과

예를 들어 “빌드가 안 돼요”라고 프로젝트 전체를 넘기는 대신, 먼저 이렇게 정리합니다.

git status --short --branch
npm run build

그다음 빌드 로그 중 실제 오류 부분과 관련 파일 일부만 공유합니다. 이렇게 하면 보안상 안전할 뿐 아니라 AI의 답도 더 정확해집니다.

비밀값이 들어갈 수 있는 파일을 먼저 분리한다

AI 도구가 프로젝트를 읽게 하기 전에 조심해야 할 파일을 먼저 떠올려야 합니다.

대표적으로 아래 파일은 바로 공유하지 않는 편이 좋습니다.

.env
.npmrc
.pypirc
credentials.json
config.json
SSH private key
배포 서비스 설정 파일

특히 .env에는 API 키, DB 접속 문자열, 토큰이 들어가는 경우가 많습니다. AI에게 에러를 물어보는 데 이 값들이 꼭 필요한 경우는 드뭅니다.

프로젝트 안에서 의심 단어를 검색한다

비밀값은 파일명만으로 찾기 어렵습니다. 로그나 설정 파일 안에 섞여 있을 수 있습니다.

점검할 때는 이런 단어가 들어간 줄을 먼저 찾아봅니다.

rg -n "API_KEY|TOKEN|SECRET|PASSWORD|DATABASE_URL|PRIVATE_KEY" .

rg가 없다면 grep -R로도 비슷하게 찾을 수 있습니다.

검색 결과에 실제 값이 보이면 그대로 복사하지 말고 [REDACTED]처럼 가립니다.

OPENAI_API_KEY=[REDACTED]
DATABASE_URL=[REDACTED]
Authorization: Bearer [REDACTED]

이렇게 바꿔도 오류 맥락은 대부분 유지됩니다.

로그에서 가릴 정보를 확인한다

에러 로그는 단순히 실패 이유만 담지 않습니다. 실행 위치, 사용자 이름, 프로젝트 경로, 서버 주소, 요청 헤더, 환경변수가 같이 찍히기도 합니다.

특히 아래 값은 가리는 편이 좋습니다.

/home/사용자명/... 같은 개인 경로
내부 도메인이나 사설 IP
이메일 주소
요청 헤더의 Authorization 값
쿠키 문자열
고객명이나 실제 데이터 샘플

가릴 때는 완전히 지우기보다 의미만 남기면 됩니다.

/home/[USER]/project/src/app.ts
https://internal-api.example/[REDACTED]
customer_email=[REDACTED]

AI에게 넘길 최소 묶음을 만든다

점검이 끝나면 AI에게 넘길 정보를 하나의 작은 묶음으로 만듭니다.

예를 들어 Node 프로젝트 빌드 오류라면 이런 식입니다.

실행 명령:
npm run build

오류 요약:
TypeError: Cannot read properties of undefined ...

관련 파일:
src/lib/config.ts 일부

이미 확인한 것:
환경변수 이름은 문서와 맞춰봤음

이 정도면 AI가 답하기에 충분한 경우가 많습니다. 전체 저장소를 넘기기 전에 먼저 이 최소 묶음으로 질문해 보세요.

회사·고객 자료는 내 판단만으로 올리지 않는다

개인 연습 프로젝트라면 스스로 판단하면 됩니다. 하지만 회사 코드, 고객 데이터, 외부 계약 자료는 다릅니다. 내가 접근 권한이 있어도 AI 도구에 넣을 권한까지 있는 것은 아닐 수 있습니다.

이 경우에는 조직 규칙을 먼저 확인해야 합니다. 어떤 AI 도구를 써도 되는지, 어떤 데이터는 금지되는지, 익명화하면 되는지 같은 기준이 있을 수 있습니다.

AI 코딩 도구에 넘기기 전 체크리스트

AI가 꼭 봐야 할 명령, 오류, 파일만 골랐다
`.env`, 토큰, 접속 문자열이 포함되지 않았는지 확인했다
`rg`나 검색으로 SECRET, TOKEN, PASSWORD 같은 단어를 점검했다
로그에서 개인 경로, 이메일, 내부 주소를 가렸다
회사·고객 자료는 조직 규칙을 확인했다

정리

AI 코딩 도구는 개발 속도를 올려주지만, 입력을 아무 생각 없이 넘기면 곤란해질 수 있습니다. 핵심은 어렵지 않습니다. 필요한 범위를 좁히고, 비밀값을 검색하고, 로그를 가리고, 회사나 타인의 자료는 규칙을 확인하는 것입니다.

이 습관을 들이면 AI 도구를 더 안전하게 쓸 수 있고, 질문 자체도 더 명확해집니다. 결국 좋은 AI 사용은 좋은 입력 정리에서 시작합니다.

AI 코딩 도구를 쓰기 전에 알아두면 좋은 기본기

Thu, 09 Jul 2026 06:05:28 GMT

AI 코딩 도구는 “알아서 해주는” 인상이 강하지만, 실제로 써보면 결과를 이해하고 다룰 수 있는 사람과 그렇지 않은 사람의 차이가 꽤 큽니다. 도구가 무엇을 했는지 모르면, 잘 됐는지 잘못됐는지조차 판단하기 어렵기 때문입니다.

이 글에서는 도구를 본격적으로 쓰기 전에 미리 갖춰두면 좋은 기본기를, 우선순위 순서대로 짚어 봅니다.

1. 터미널에 익숙해지기

AI 코딩 도구 상당수는 터미널에서 동작합니다. 폴더를 이동하고, 파일 목록을 보고, 명령을 실행하는 정도의 기본 동작만 익숙해도 “지금 어디서 무엇을 하고 있는지” 따라갈 수 있습니다. 화려한 명령을 외울 필요는 없고, 길 잃지 않을 정도면 충분합니다.

2. 파일·폴더와 경로 개념 잡기

도구는 결국 특정 폴더 안의 파일을 읽고 고칩니다. 프로젝트가 어떤 폴더 구조로 되어 있는지, 내가 지금 어떤 폴더에서 작업 중인지 감을 잡고 있으면, 도구가 “어디에” 변경을 가했는지 이해할 수 있습니다.

여기서 같이 익혀두면 좋은 것이 경로(path) 개념입니다. 경로는 “어떤 파일이 어디에 있는지 가리키는 주소”라고 보면 됩니다. 지금 위치를 기준으로 적는 상대 경로와, 최상위부터 전부 적는 절대 경로의 차이만 알아도 도구가 말하는 위치를 헷갈리지 않습니다. 현재 위치와 폴더 안 목록은 아래 정도로 확인합니다.

pwd
ls

pwd는 지금 내가 서 있는 폴더의 전체 경로를 보여 주고, ls는 그 폴더 안에 무엇이 있는지 보여 줍니다. 도구에게 “이 파일을 고쳐줘”라고 할 때, 그 파일이 실제로 어느 경로에 있는지 스스로 짚을 수 있으면 의사소통이 훨씬 정확해집니다.

✍️ 운영자 한마디

처음엔 ‘알아서 다 해주겠지’ 하는 마음으로 막연하게 시켰다가 결과가 영 엉뚱했습니다. 요청을 구체적으로, 작은 단위로 나눠 시키니 결과가 확 좋아지더군요.

3. Git 기초 익히기

AI 도구가 코드를 바꿨을 때, 무엇이 어떻게 바뀌었는지 확인하고 마음에 들지 않으면 되돌릴 수 있어야 합니다. Git의 기본 개념(변경 사항 확인, 기록 남기기, 이전 상태로 되돌리기)만 알아도 든든한 안전망이 생깁니다. 처음에는 명령 몇 개로 충분합니다.

4. 요청을 구체적으로 적는 습관

같은 도구라도 어떻게 요청하느냐에 따라 결과가 크게 달라집니다. “이거 고쳐줘”보다 “어떤 파일의, 어떤 동작을, 어떤 방향으로 바꾸고 싶은지”를 구체적으로 적을수록 의도에 가까운 결과가 나옵니다. 맥락과 조건을 함께 적는 연습이 곧 도구를 잘 쓰는 기술입니다.

구체적으로 적는다는 것은 길게 쓰라는 뜻이 아니라, 빠지기 쉬운 정보를 채운다는 뜻입니다. 예를 들면 이런 항목들입니다.

무엇을 — 어떤 파일, 어떤 함수, 어떤 화면인지
어떻게 — 지금 동작과 바라는 동작이 어떻게 다른지
조건 — 건드리면 안 되는 부분, 지켜야 할 규칙이 있는지

5. 작은 단위로 시키기

큰 일을 한 번에 통째로 맡기면, 결과가 마음에 들지 않을 때 어디서부터 잘못됐는지 짚기 어렵습니다. “전체를 다 만들어줘”보다 “먼저 이 한 부분만 해보자”처럼 작게 쪼개서 시키면, 매 단계마다 결과를 눈으로 확인하며 방향을 잡을 수 있습니다. 작은 단위는 검토도 쉽고, 잘못됐을 때 되돌리기도 쉽습니다. 익숙해지기 전까지는 “한 번에 하나씩”을 기본값으로 삼는 편이 안전합니다.

6. 결과를 확인하는 습관

도구가 코드를 바꿨다면, 그 자리에서 끝내지 말고 정말 의도대로 됐는지 확인하는 습관을 들이세요. 바뀐 부분을 직접 읽어 보거나, 실제로 한 번 실행해 보거나, 무엇이 달라졌는지 변경 사항을 비교(diff)해 보는 식입니다. AI의 결과는 그럴듯해 보여도 항상 맞는 것은 아니므로, 확인 없이 다음 단계로 넘어가면 작은 오류가 쌓여 나중에 원인을 찾기 어려워집니다. 이 습관은 뒤에서 다룰 “코드를 그대로 믿지 않는 태도”의 출발점이기도 합니다.

초보자가 자주 막히는 부분

결과를 그대로 받아들이기 — 도구가 무엇을 했는지 모른 채 넘어가면, 문제가 생겨도 원인을 찾기 어렵습니다.
되돌릴 방법이 없음 — Git 없이 작업하다 변경이 꼬이면 처음으로 돌아가기 막막해집니다.
요청이 너무 막연함 — 모호한 요청은 모호한 결과를 부릅니다. 조건을 빼먹지 마세요.
한 번에 너무 큰 작업 — 작게 나눠 요청하고 확인하는 편이 통제하기 쉽습니다.

시작 전 점검 체크리스트

터미널에서 폴더 이동·파일 확인 정도는 할 수 있다
내가 지금 어떤 폴더에서 작업 중인지 안다
Git으로 변경을 확인하고 되돌리는 기본을 익혔다
요청을 구체적으로(무엇·어떻게·조건) 적는 연습을 하고 있다
큰 일을 작은 단위로 쪼개 시키고 있다
도구가 바꾼 결과를 그때그때 확인하는 습관이 있다

정리

AI 코딩 도구는 기본기를 대신해 주지 않고, 오히려 기본기가 있을 때 더 잘 활용됩니다. 터미널·파일 개념으로 상황을 이해하고, Git으로 안전망을 만들고, 요청을 구체적으로 적는 습관까지 갖추면 도구의 결과를 통제할 수 있게 됩니다. 다음으로는 도구가 만든 코드를 그대로 믿지 않고 검토하는 습관을 함께 익혀 두길 권합니다.

Claude Code 처음 설치하고 실행해보기

Thu, 09 Jul 2026 06:05:28 GMT

AI 코딩 도구를 한번 써보고 싶은데, 첫 화면이 “터미널에 무언가를 입력하라”는 것이라면 거기서부터 막히기 쉽습니다. Claude Code 같은 도구는 그래픽 화면 대신 터미널에서 동작하기 때문에, 설치와 첫 실행의 흐름을 미리 알아두면 훨씬 덜 당황하게 됩니다.

이 글에서는 특정 버전이나 명령을 단정하기보다, 처음 설치할 때 거치는 일반적인 단계와 확인할 점을 순서대로 정리합니다.

Claude Code가 어떤 도구인가

Claude Code는 터미널에서 실행하는 AI 코딩 보조 도구입니다. 그래픽 앱처럼 창을 띄우는 대신, 작업하려는 폴더 안에서 명령을 입력해 대화하듯 코드를 다루는 방식입니다. 그래서 설치도 일반 프로그램보다는 개발 도구를 설치하는 흐름에 가깝습니다.

도구의 정확한 기능·요금·지원 범위는 환경과 시점에 따라 달라질 수 있으니, 세부 사양은 공식 안내를 기준으로 보는 것이 좋습니다. 이 글의 목적은 “정확한 명령을 외우게 하는 것”이 아니라, 설치라는 과정 전체가 어떤 단계로 이루어지는지 그림을 그려 두는 데 있습니다. 흐름을 알고 있으면, 공식 문서의 명령이 조금 달라져도 어디에 해당하는 단계인지 바로 알아볼 수 있습니다.

설치 전에 갖춰야 할 것

대부분의 터미널 기반 도구처럼, Claude Code도 실행 환경이 먼저 준비되어 있어야 합니다. 환경이 갖춰지지 않은 상태에서 설치 명령부터 입력하면 “명령을 찾을 수 없다”거나 “이런 프로그램이 없다”는 오류가 나기 쉬운데, 이는 도구의 문제가 아니라 토대가 빠진 경우가 대부분입니다.

터미널 접근 — 리눅스, macOS의 터미널, 또는 윈도우라면 WSL을 통한 리눅스 터미널이면 됩니다. 윈도우만 써왔다면 먼저 WSL로 리눅스 터미널을 마련해 두는 편이 흐름이 깔끔합니다.
Node.js와 npm — 많은 터미널 도구가 Node.js 환경 위에서 설치·실행됩니다. npm은 Node.js를 설치하면 보통 함께 들어오는 패키지 매니저로, 다른 도구를 내려받아 설치하는 통로 역할을 합니다.

Node.js가 준비됐는지 확인하기

설치를 시작하기 전에, Node.js와 npm이 이미 동작하는지 한 번 확인해 두면 좋습니다. 버전을 출력해 보는 명령으로 간단히 점검할 수 있습니다.

node -v
npm -v

두 명령이 버전 숫자를 출력하면 준비가 된 것이고, “명령을 찾을 수 없다”는 메시지가 나오면 아직 Node.js가 없는 상태입니다. 이때는 무작정 설치 명령을 찾기보다, 버전을 깔끔하게 관리할 수 있는 버전 매니저로 Node.js를 들이는 방법을 함께 살펴보는 편이 이후가 편합니다. 시스템 전체에 한 버전만 박아 두기보다, 프로젝트마다 다른 버전을 오갈 수 있게 해 두면 나중에 충돌이 줄어듭니다.

✍️ 운영자 한마디

터미널에서 AI 도구를 쓴다는 게 처음엔 낯설었습니다. Node 같은 사전 준비가 안 돼 있으면 설치가 막히는데, 저도 그 단계에서 한 번 멈췄다가 환경부터 정리하고 나서 수월해졌습니다.

설치와 첫 실행의 흐름

1. 공식 안내에서 설치 방법 확인

가장 먼저 할 일은 임의의 명령을 따라 치는 것이 아니라, 공식 문서에서 설치 방법을 확인하는 것입니다. 도구는 자주 갱신되어 패키지명이나 권장 설치 방식이 바뀔 수 있기 때문입니다.

2. 패키지 매니저로 설치

보통은 npm 같은 패키지 매니저로 설치합니다. 일반적인 흐름은 “패키지 매니저에게 특정 패키지를 설치하라고 한 줄로 지시”하는 형태인데, 정확한 패키지명과 옵션은 시점에 따라 바뀔 수 있으므로 이 글에서 단정하지 않습니다. 공식 안내에 나온 명령을 그대로 복사해 쓰는 것이 가장 안전합니다. 설치 도중 권한 오류가 난다면, 관리자 권한으로 무리하게 강제하기보다 설치 위치나 권한 설정을 점검하는 편이 안전합니다.

설치 명령을 한 줄 한 줄 직접 따라 하고 싶다면, 이 블로그 글에 설치 과정이 캡처와 함께 꽤 자세히 설명되어 있더라구요. 터미널이 익숙하지 않아도 그대로 따라 하기 좋으니, 한번 보고 진행하시면 됩니다.

3. 작업 폴더로 이동해서 실행

설치가 끝났다면, 아무 곳에서나 실행하지 말고 작업하려는 프로젝트 폴더 안으로 먼저 이동한 뒤 도구를 실행합니다. 이 도구는 “지금 위치한 폴더”를 작업 대상으로 삼는 경우가 많기 때문에, 어디서 실행하느냐가 곧 어떤 파일을 다루게 되느냐로 이어집니다. 폴더 이동은 cd 명령으로 합니다.

cd ~/projects/my-app

4. 첫 인증(로그인)

처음 실행할 때는 대개 한 번 인증(로그인) 절차를 거칩니다. 보통 화면에 안내 링크나 절차가 표시되고, 그것을 따라가면 계정과 도구가 연결됩니다. 한 번 인증해 두면 이후에는 매번 로그인하지 않아도 되는 경우가 많지만, 구체적인 방식과 유효 기간은 환경·버전에 따라 다를 수 있으니 화면 안내를 그대로 따르는 것이 정확합니다.

도구가 파일을 다룰 때 거치는 확인 절차

AI 코딩 도구가 단순한 챗봇과 다른 점은, 대화에 그치지 않고 실제로 파일을 만들거나 고치고, 명령을 실행할 수 있다는 데 있습니다. 그만큼 통제가 중요합니다. 그래서 이런 도구들은 보통, 파일을 바꾸거나 명령을 실행하기 전에 사용자에게 “이대로 진행해도 되는지” 확인을 거치는 장치를 둡니다.

처음 쓸 때는 이 확인이 번거롭게 느껴질 수 있지만, 무엇을 바꾸려는지 미리 보고 승인하는 과정이라 안전망 역할을 합니다. 도구에 따라 확인을 건너뛰고 더 자동으로 동작하게 하는 옵션을 제공하기도 하는데, 구체적인 플래그 이름이나 동작은 도구·버전마다 다르므로 여기서 단정하지 않겠습니다. 입문 단계에서는 자동화 옵션을 켜기보다, 무엇을 바꾸는지 한 번씩 확인하며 쓰는 기본 동작에 익숙해지길 권합니다.

초보자가 자주 막히는 부분

사전 준비를 건너뜀 — Node.js/npm이 없으면 설치 자체가 진행되지 않습니다. 먼저 환경을 갖춰야 합니다.
명령을 검색으로 베껴 옴 — 오래된 글의 명령은 지금과 다를 수 있습니다. 공식 문서의 최신 안내를 우선하세요.
권한 오류 — 설치 중 권한 문제가 나오면 무리하게 강제하기보다 권한·설치 경로 설정을 점검하는 편이 안전합니다.
엉뚱한 폴더에서 실행 — 작업하려는 프로젝트 폴더 안에서 실행해야 의도한 파일을 다룰 수 있습니다.
확인 절차를 귀찮아서 꺼버림 — 파일을 바꾸기 전 확인하는 단계는 안전망입니다. 처음에는 켜둔 채로 쓰며 익히세요.

설치 점검 체크리스트

터미널을 열 수 있는 환경(리눅스/macOS/WSL)이 준비됐다
Node.js와 npm이 설치되어 동작한다
공식 문서에서 최신 설치 방법을 확인했다
작업할 프로젝트 폴더로 이동한 뒤 도구를 실행했다
설치 후 첫 실행과 인증 절차를 마쳤다
파일 변경 전 확인 절차의 의미를 이해하고 기본값으로 쓰고 있다

정리

Claude Code 같은 터미널 도구의 설치는 “명령 한 줄”보다, 환경을 먼저 갖추고 공식 안내를 따르는 흐름이 핵심입니다. 버전과 환경에 따라 세부 절차는 달라질 수 있으니 단정하지 말고 공식 문서를 기준으로 삼으세요. 실제 설치 명령은 이 블로그 글에 단계별로 자세히 나와 있더라구요. 막히는 부분이 있으면 같이 보면서 따라 하면 한결 수월합니다. 설치를 마쳤다면, 도구를 더 잘 활용하기 위한 기본기를 함께 점검해 두면 도움이 됩니다.

bash와 zsh, 입문자는 무엇부터 쓰면 좋을까

Thu, 09 Jul 2026 06:05:28 GMT

터미널을 처음 열면 검은 화면에 글자만 깜빡입니다. 그런데 자료를 찾다 보면 누군가는 bash를 말하고, 누군가는 zsh를 말합니다. 둘 다 셸이라는데, 무엇이 다르고 입문자는 어느 쪽을 써야 할까요. 이 질문에 답하려면 먼저 '셸'이라는 단어부터 풀어야 합니다.

셸이란 무엇인가

셸(shell)은 우리가 입력한 명령을 받아 운영체제에 전달하고, 그 결과를 다시 보여 주는 프로그램입니다. 터미널이 명령을 입력하고 출력을 보는 '창'이라면, 셸은 그 안에서 실제로 명령을 해석하는 '통역사'에 가깝습니다.

그래서 같은 터미널 창이라도 어떤 셸이 동작하느냐에 따라 자동완성 방식이나 프롬프트 모양이 조금씩 달라집니다. bash와 zsh는 바로 이 통역사의 두 가지 종류입니다. 한 가지 안심할 점은, 셸을 바꿔도 ls·cd·cp 같은 기본 명령은 시스템 명령이라 그대로 쓸 수 있다는 것입니다. 바뀌는 것은 통역사의 '버릇'이지, 명령 자체가 아닙니다.

bash와 zsh는 어떻게 다른가

기본 제공 여부

bash는 오랫동안 리눅스 배포판의 기본 셸이었습니다. 우분투를 비롯한 많은 환경에서 별도 설치 없이 바로 동작하기 때문에, 인터넷에서 찾는 예제 대부분이 bash를 기준으로 쓰여 있습니다. zsh는 환경에 따라 기본으로 깔려 있기도 하고, 직접 설치해야 하기도 합니다. WSL의 우분투는 보통 bash가 기본입니다.

자동완성과 테마

zsh가 매력적으로 느껴지는 큰 이유는 편의 기능입니다. 명령이나 경로를 입력하다 Tab을 누를 때의 자동완성이 더 똑똑하고, 후보를 화살표로 골라 넣을 수도 있습니다. 또 프롬프트(명령 입력 줄 앞에 보이는 부분)의 모양을 꾸미는 테마 기능도 풍부합니다. bash도 자동완성을 지원하지만, 기본 상태에서는 zsh 쪽이 더 손에 잘 붙는다는 평이 많습니다.

플러그인 생태계

zsh는 플러그인을 더해 기능을 확장하는 생태계가 잘 갖춰져 있습니다. 명령 오타를 바로잡아 주거나, 입력하는 동안 과거 명령을 흐리게 제안해 주는 식의 확장이 대표적입니다. 다만 이런 확장은 설정 파일을 손봐야 하므로, 터미널 자체가 아직 낯선 단계에서는 오히려 진입 장벽이 될 수 있습니다.

설정 파일

두 셸은 설정 파일도 다릅니다. bash는 .bashrc, zsh는 .zshrc 를 읽습니다. 셸을 바꾸면 alias나 환경 변수 같은 개인 설정을 새 파일에 옮겨 적어야 한다는 점을 기억해 두는 것이 좋습니다.

✍️ 운영자 한마디

남들이 zsh에 플러그인을 잔뜩 얹은 화면을 보고 따라 했다가, 정작 기본 동작도 모른 채 설정만 복잡해진 적이 있습니다. 입문 때는 기본 bash로 충분했고, 익숙해진 뒤 천천히 바꿔도 늦지 않더군요.

지금 내 셸을 확인하고 바꾸는 법

현재 셸 확인

지금 어떤 셸을 쓰는지는 다음 명령으로 확인할 수 있습니다. 출력 끝이 /bash 면 bash, /zsh 면 zsh입니다.

echo $SHELL

기본 셸 변경

기본 셸을 바꾸는 명령은 chsh(change shell)입니다. 예를 들어 zsh로 바꾸려면 다음처럼 합니다. 변경은 보통 터미널을 새로 열었을 때 적용됩니다.

chsh -s /bin/zsh

기본 셸을 바꾸기 전에 가볍게 맛만 보고 싶다면, 굳이 chsh 까지 가지 않고 터미널에서 zsh 라고 입력해 잠깐 그 셸로 들어가 볼 수도 있습니다. 마음에 들지 않으면 exit 로 빠져나오면 됩니다.

zsh     # 잠깐 zsh로 들어가 보기
exit    # 원래 셸로 돌아오기

입문자에게는 무엇을 권할까

결론부터 말하면, 입문 단계에서는 bash로 시작하기를 권합니다. 이유는 화려함이 아니라 '자료의 양'입니다. 막혔을 때 검색하면 나오는 글, 강의, 답변 대부분이 bash를 전제로 합니다. 같은 문제라도 답을 찾기가 훨씬 수월합니다.

zsh는 터미널 작업이 어느 정도 손에 익은 뒤에 시도해도 늦지 않습니다. 그때쯤이면 자동완성이나 테마 같은 편의 기능의 가치가 더 분명하게 느껴지고, 설정을 만지는 일도 덜 부담스러워집니다. 셸을 바꾸는 일은 언제든 되돌릴 수 있으니, 조급해할 필요가 없습니다.

초보자가 자주 막히는 부분

'셸을 바꾼다'는 말의 의미를 오해 — 운영체제를 바꾸는 것이 아니라, 명령을 해석하는 프로그램만 바뀝니다. 기본 명령은 그대로 동작합니다.
설정 파일을 혼동 — bash는 .bashrc, zsh는 .zshrc를 씁니다. 셸을 바꾸면 손봐야 할 파일도 달라집니다.
검색 결과가 안 맞아 당황 — zsh를 쓰는데 bash 기준 예제를 그대로 붙여 넣어 오류가 나는 경우가 있습니다. 어느 셸 기준인지 먼저 확인하는 습관이 도움이 됩니다.
처음부터 너무 많이 꾸미기 — 입문 단계에서 테마와 플러그인부터 손대다 설정이 꼬이는 경우가 흔합니다.
chsh 후 바로 안 바뀐다고 당황 — 기본 셸 변경은 보통 터미널을 새로 열어야 적용됩니다.

셸 선택 점검 체크리스트

echo $SHELL 로 지금 내 셸이 bash인지 zsh인지 확인했다
당장은 자료가 많은 bash로 시작하기로 정했다
셸마다 설정 파일이 다르다(.bashrc / .zshrc)는 점을 안다
chsh 로 기본 셸을 바꾸고 되돌릴 수 있음을 안다
나중에 편의 기능이 필요해지면 zsh를 시도해 볼 생각이다

정리

bash와 zsh는 우열을 가리는 관계가 아니라, 쓰임이 조금 다른 두 통역사입니다. 입문 단계에서는 자료가 풍부한 bash로 기초를 다지고, 작업이 손에 익은 뒤 zsh의 편의 기능을 천천히 들여다보는 흐름이 가장 부담이 적습니다. 현재 셸은 echo $SHELL 로 확인하고, 바꾸고 싶을 때는 chsh 로 언제든 조정할 수 있다는 점만 알아 두면 됩니다. 어떤 셸을 쓰든 다음 단계는 같습니다. 설정 파일을 안전하게 다루는 법과, 자주 쓰는 명령을 짧게 줄이는 법을 익히는 것입니다.

WSL에서 Docker 시작하기: 컨테이너 첫걸음

Thu, 09 Jul 2026 06:05:28 GMT

“이 도구를 쓰려면 도커가 필요합니다”라는 안내를 만나면, 입문자는 보통 두 가지에서 막힙니다. 도커가 대체 무엇을 하는 물건인지, 그리고 윈도우에서 어떻게 시작해야 하는지입니다. 이 글은 컨테이너와 이미지 개념을 먼저 풀고, WSL2 위에서 도커를 시작해 hello-world로 동작을 확인하는 데까지를 순서대로 따라갑니다. 정확한 설치 패키지나 버전은 시점에 따라 달라지므로, 세부 명령은 공식 문서 확인을 함께 권합니다.

컨테이너와 이미지, 쉽게 풀기

도커를 이해하는 핵심은 컨테이너와 이미지 두 단어입니다.

컨테이너는 프로그램 하나와 그 프로그램이 돌아가는 데 필요한 환경(필요한 라이브러리, 설정 등)을 하나로 묶어 격리된 상자 안에서 실행하는 방식입니다. 내 컴퓨터에 이것저것 직접 깔아 환경을 어지럽히지 않고, 상자 안에서만 돌리고 끝나면 상자를 치우는 식이라고 생각하면 쉽습니다.

이미지는 그 컨테이너를 찍어내는 틀입니다. 같은 이미지로 컨테이너를 여러 개 만들 수 있고, 이미지를 받아 두면 어느 컴퓨터에서든 같은 환경을 재현할 수 있습니다.

이미지: 실행 환경이 통째로 담긴 “설계도 겸 스냅샷”.
컨테이너: 그 이미지를 실제로 띄워 돌리고 있는 “실행 중인 인스턴스”.
“내 컴퓨터에서는 됐는데 다른 데서는 안 된다”는 문제를 줄이는 것이 도커의 큰 장점입니다.

✍️ 운영자 한마디

컨테이너라는 말이 처음엔 추상적으로만 들렸는데, hello-world 이미지 하나 돌려보고 나니 ‘아, 격리된 작은 환경이 뜨는 거구나’ 하고 감이 왔습니다. 권한 문제로 명령이 처음에 막혀서 잠깐 헤맸습니다.

WSL2와 도커의 관계

도커는 본래 리눅스 환경에서 동작하는 기술입니다. 윈도우에서 도커를 쓸 수 있는 이유는, WSL2가 윈도우 안에서 진짜 리눅스 커널을 띄워 주기 때문입니다. 즉 윈도우용 도커는 그 WSL2 리눅스 환경을 바탕 삼아 동작하는 구조입니다.

그래서 도커를 시작하기 전에 WSL2가 먼저 준비되어 있어야 합니다. 아직 WSL이 설치되어 있지 않다면, 도커보다 WSL 설치를 먼저 마쳐 두는 편이 순서상 자연스럽습니다.

설치 방식 두 갈래

WSL에서 도커를 쓰는 길은 크게 두 갈래로 나뉩니다. 개념만 먼저 잡아 두고, 실제 설치 절차는 공식 문서를 따르는 것이 안전합니다.

1. Docker Desktop의 WSL 통합

윈도우에 Docker Desktop을 설치하고, 그 설정에서 WSL 배포판과의 통합을 켜는 방식입니다. 윈도우 쪽 앱으로 도커를 관리하면서, WSL 안의 터미널에서 docker 명령을 그대로 쓸 수 있습니다. 그래픽 화면으로 상태를 보거나 관리하는 데 익숙한 입문자에게 진입이 편합니다.

2. 리눅스 안에 도커 엔진 직접 설치

Docker Desktop 없이, WSL 우분투 안에 도커 엔진을 직접 설치해 명령으로만 다루는 방식입니다. 리눅스 환경에 더 가깝게 다루고 싶거나, 그래픽 앱 없이 가볍게 쓰고 싶을 때 선택합니다. 설치 패키지 이름과 절차는 배포판·시점에 따라 달라지므로 공식 문서의 안내를 그대로 따르는 것을 권합니다.

어느 쪽이든 결국 WSL 안에서 docker 명령을 쓰게 된다는 점은 같습니다. 처음이라면 관리가 직관적인 Docker Desktop 통합으로 시작해도 무방합니다.

기본 명령 익히기

설치가 끝났다면, 자주 쓰는 기본 명령부터 손에 익혀 두면 좋습니다.

동작 확인: hello-world

가장 먼저 할 일은 도커가 제대로 도는지 확인하는 것입니다.

docker run hello-world

이 명령은 hello-world라는 작은 이미지를 내려받아 컨테이너로 실행합니다. 안내 메시지가 출력되면 설치와 기본 동작이 정상이라는 뜻입니다. 여기서 run은 “이미지를 받아(필요하면) 컨테이너로 실행”하는 명령입니다.

상태와 목록 보기

docker ps
docker images

docker ps는 지금 실행 중인 컨테이너 목록을, docker images는 내 컴퓨터에 받아 둔 이미지 목록을 보여 줍니다. hello-world는 잠깐 실행되고 끝나는 종류라, 실행이 끝난 뒤에는 docker ps 목록에 보이지 않을 수 있습니다.

컨테이너 멈추기

계속 떠 있는 컨테이너를 멈추려면 아래처럼 합니다.

docker stop <컨테이너이름또는ID>

멈출 대상의 이름이나 ID는 docker ps 결과에서 확인할 수 있습니다.

권한(docker 그룹) 주의

리눅스 안에 도커 엔진을 직접 설치한 경우, 처음에는 docker 명령을 쓸 때 권한 오류가 나거나 매번 sudo를 붙여야 할 수 있습니다. 이는 도커가 시스템 권한과 맞닿아 동작하기 때문입니다. 보통은 현재 사용자를 docker 그룹에 넣어 sudo 없이 쓰도록 설정하는데, 그룹 변경은 다시 로그인하거나 환경을 새로 켜야 적용되는 경우가 많습니다.

다만 권한 설정은 보안과도 연결되는 부분이라, 정확한 절차와 주의점은 공식 문서를 따르는 것을 권합니다. 막연히 모든 권한을 여는 식으로 접근하지 말고, 안내된 방법을 그대로 따라가는 편이 안전합니다.

초보자가 자주 막히는 부분

WSL2 준비 없이 도커부터 설치 — 도커는 WSL2 리눅스 환경 위에서 동작하므로, WSL이 먼저 준비돼 있어야 합니다.
두 설치 방식을 동시에 섞음 — Docker Desktop과 엔진 직접 설치를 한 환경에 뒤섞으면 어느 쪽이 동작하는지 헷갈릴 수 있습니다. 하나를 정해 시작하세요.
권한 오류에 무작정 sudo만 반복 — 매번 sudo를 붙이기보다 docker 그룹 설정을 공식 문서대로 한 번 정리하는 편이 깔끔합니다.
그룹 설정 후 바로 적용되길 기대 — 그룹 변경은 다시 로그인하거나 환경을 새로 켜야 반영되는 경우가 많습니다.
이미지와 컨테이너를 같은 것으로 혼동 — 이미지는 틀, 컨테이너는 그 틀로 만든 실행 중인 인스턴스로 구분하면 명령이 이해됩니다.

도커 첫걸음 체크리스트

컨테이너와 이미지의 차이를 한 줄로 설명할 수 있다
도커가 WSL2 리눅스 환경 위에서 동작한다는 점을 이해했다
설치 방식이 Docker Desktop 통합과 엔진 직접 설치 두 갈래임을 안다
docker run hello-world 로 동작을 확인했다
docker ps / docker images 로 상태와 목록을 볼 수 있다
권한 오류 시 docker 그룹 설정이 필요할 수 있음을 알고, 공식 문서를 확인한다

정리

도커의 핵심은 “환경을 통째로 묶어 격리해 실행한다”는 발상이고, 그 단위가 컨테이너이며 틀이 이미지입니다. 윈도우에서는 WSL2가 리눅스 커널을 띄워 주기 때문에 그 위에서 도커를 자연스럽게 쓸 수 있습니다. 설치는 Docker Desktop의 WSL 통합과 리눅스 엔진 직접 설치 두 갈래가 있고, 어느 쪽이든 결국 docker 명령으로 다룬다는 점은 같습니다. 먼저 docker run hello-world로 동작을 확인하고, ps·images·stop 같은 기본 명령부터 손에 익혀 보세요. 정확한 설치 패키지와 권한 설정은 시점에 따라 달라질 수 있으니 공식 문서를 함께 확인하는 습관을 들이면 좋습니다.

터미널 작업을 빠르게: 별칭(alias)과 히스토리 활용

Thu, 09 Jul 2026 06:05:28 GMT

터미널에 어느 정도 익숙해지고 나면 새로운 불편이 보이기 시작합니다. 어제 친 그 긴 명령을 오늘 또 처음부터 입력하고, 비슷한 명령을 하루에도 몇 번씩 반복합니다. 다행히 셸에는 이런 반복을 줄여 주는 장치가 이미 들어 있습니다. 이 글에서는 alias, 히스토리, Tab 자동완성 세 가지로 입력량을 덜어 내는 방법을 차례로 다룹니다.

자주 쓰는 명령을 alias로 줄이기

alias는 길고 자주 쓰는 명령에 짧은 별명을 붙이는 기능입니다. 예를 들어 파일을 자세히 보기 위해 매번 옵션을 붙여 치는 명령이 있다면, 짧은 별명 하나로 대신할 수 있습니다.

alias ll='ls -al'

이렇게 해 두면 이제 ll만 쳐도 같은 결과가 나옵니다. 형태는 alias 별명='실제 명령'이며, 등호 양옆에 공백을 넣지 않는 것이 규칙입니다. 지금 등록된 alias 목록이 궁금하면 인자 없이 alias만 입력하면 됩니다.

임시 alias와 영구 alias

같은 alias라도 어디에 적느냐에 따라 수명이 다릅니다.

임시(세션 한정) — 터미널에서 alias ll='ls -al'을 바로 입력하면 그 창에서만 유효합니다. 터미널을 닫으면 사라집니다. 잠깐 시험해 볼 때 좋습니다.
영구 — 같은 줄을 .bashrc 같은 셸 설정 파일에 적어 두면, 새 터미널을 열 때마다 자동으로 적용됩니다. .bashrc를 안전하게 손보는 방법은 셸 설정 파일 글에서 따로 다룹니다.

유용한 alias 예시

처음 등록해 볼 만한 별명 몇 가지입니다. 손에 익은 명령이 있다면 그것부터 줄여 보세요.

alias ll='ls -al'
alias la='ls -A'
alias ..='cd ..'
alias gs='git status'

마지막 gs처럼 자주 치는 git 명령을 줄여 두면 체감 차이가 큽니다. 다만 별명은 짧되 기존 명령과 겹치지 않는 이름을 고르는 편이 안전합니다.

✍️ 운영자 한마디

처음엔 긴 명령을 매번 다 쳤는데, 같은 걸 하루에도 몇 번씩 치다 보니 영 번거로웠습니다. alias로 줄이고 Ctrl+R로 지난 명령을 불러오기 시작하면서 작업이 한결 가벼워졌습니다.

히스토리로 이전 명령 다시 쓰기

셸은 지금까지 입력한 명령을 기억해 둡니다. 이를 히스토리라고 합니다. 가장 손쉬운 활용은 키보드 위쪽 화살표입니다. 누를 때마다 직전에 친 명령이 차례로 거슬러 올라오므로, 방금 친 명령을 살짝 고쳐 다시 실행하기에 좋습니다.

지금까지의 명령 목록을 한 번에 보고 싶다면 다음 명령을 씁니다.

history

목록 왼쪽에는 명령마다 번호가 붙어 있습니다. 이 번호를 활용하는 단축 표기가 따로 있습니다.

!! 와 !n 으로 다시 실행하기

!로 시작하는 표기를 쓰면 이전 명령을 번호나 위치로 곧장 불러올 수 있습니다.

!! — 바로 직전에 실행한 명령을 그대로 다시 실행합니다. sudo를 빠뜨렸을 때 sudo !!로 앞 명령에 권한만 붙여 재실행하는 식으로 자주 씁니다.
!n — history 목록에서 본 n번 명령을 다시 실행합니다. 예를 들어 42번이면 !42입니다.

sudo !!

역방향 검색(Ctrl+R)

화살표로 한참 거슬러 올라가기 번거로울 때는 Ctrl+R이 훨씬 빠릅니다. Ctrl+R을 누른 뒤 기억나는 단어 일부만 입력하면, 그 단어가 포함된 가장 최근 명령을 찾아 줍니다. 같은 키를 한 번 더 누르면 그 이전에 일치하는 명령으로 넘어갑니다. 원하는 명령이 보이면 엔터로 실행하고, 명령을 조금 고쳐 쓰려면 화살표 키로 빠져나오면 됩니다.

Tab 자동완성으로 입력 줄이기

명령이나 파일 경로를 끝까지 다 칠 필요는 없습니다. 앞부분만 입력하고 Tab 키를 누르면 나머지를 셸이 채워 줍니다.

후보가 하나면 곧바로 끝까지 완성됩니다.
후보가 여럿이면 Tab을 한 번 더 눌러 목록을 볼 수 있습니다.

긴 폴더 이름을 한 글자씩 정확히 치다 오타를 내는 일이 줄고, 입력 속도도 함께 빨라집니다. 자동완성은 익숙해질수록 손이 먼저 Tab을 찾게 되는 기능입니다.

히스토리와 자동완성을 함께 쓰기

세 가지는 따로 노는 기능이 아닙니다. Ctrl+R로 예전 명령의 뼈대를 불러온 뒤, 경로 부분만 지우고 Tab으로 새 경로를 채워 넣는 식으로 조합하면 입력이 한층 더 줄어듭니다. 위쪽 화살표로 직전 명령을 띄운 다음 Tab으로 파일명만 바꿔 실행하는 흐름도 자주 쓰게 됩니다.

초보자가 자주 막히는 부분

alias가 새 터미널에서 사라짐 — 바로 친 alias는 그 세션 한정입니다. 계속 쓰려면 .bashrc 같은 설정 파일에 적어 두세요.
alias 등호 양옆에 공백 — alias ll = '...'처럼 띄우면 동작하지 않습니다. 공백 없이 alias ll='...'로 적어야 합니다.
Ctrl+R을 한 번만 누름 — 원하는 명령이 아니면 Ctrl+R을 다시 눌러 그 이전 일치 항목으로 넘어가야 합니다.
자동완성이 안 먹힘 — 철자를 틀리게 입력했거나, 그 위치에 해당하는 파일이 없으면 완성되지 않습니다.
alias 이름이 기존 명령과 겹침 — 흔히 쓰는 명령 이름을 별명으로 덮어쓰면 혼란을 줍니다. 짧지만 겹치지 않는 이름을 고르세요.

터미널 속도 올리기 체크리스트

자주 쓰는 긴 명령을 alias로 하나 이상 만들어 봤다
계속 쓸 alias는 .bashrc 같은 설정 파일에 적어 뒀다
위쪽 화살표·!!·Ctrl+R 로 이전 명령을 불러올 수 있다
명령과 경로 입력에 Tab 자동완성을 쓰고 있다

정리

터미널이 번거롭게 느껴지는 이유의 상당수는 '같은 입력의 반복'에 있습니다. alias로 자주 쓰는 명령을 줄이고, 히스토리와 !!·Ctrl+R로 지난 명령을 다시 불러오고, Tab으로 입력을 덜면 그 반복이 눈에 띄게 줄어듭니다. 세 가지 모두 거창한 설정 없이 오늘 바로 써 볼 수 있습니다. 만든 alias를 오래 쓰고 싶다면, 셸 설정 파일을 안전하게 손보는 방법을 함께 익혀 두면 좋습니다.

apt로 프로그램 설치·삭제·업데이트 이해하기

Thu, 09 Jul 2026 06:05:28 GMT

우분투에서 프로그램을 설치하려고 검색하다 보면 sudo apt install ... 같은 명령을 자주 만나게 됩니다. 윈도우처럼 설치 파일을 내려받아 더블클릭하는 방식이 아니라, 명령 한 줄로 처리하는 것이 낯설 수 있습니다. 하지만 이 방식에 한 번 익숙해지면, 프로그램을 찾고 깔고 지우는 일이 오히려 더 빠르고 깔끔해집니다.

이 글에서는 그 중심에 있는 apt가 무엇이고, 어떤 순서로 쓰는지, 그리고 자주 헷갈리는 update·upgrade, remove·purge의 차이까지 단계별로 따라갑니다. 명령은 실제로 한 번씩 입력해 보는 것을 권합니다.

1단계. apt가 하는 일 이해하기

apt는 우분투의 패키지 관리자입니다. 패키지란 프로그램과 그 프로그램이 동작하는 데 필요한 부속(의존성)들을 하나로 묶어 둔 꾸러미를 말합니다. apt는 이 꾸러미들을 정리된 저장소에서 가져와 설치하고, 필요 없어지면 깔끔하게 지워 줍니다.

덕분에 설치 파일을 일일이 찾아다닐 필요 없이, 이름만 알면 명령 한 줄로 설치할 수 있습니다. 더 나아가, 어떤 프로그램이 다른 프로그램을 필요로 한다면 apt가 그 부속까지 알아서 함께 챙겨 줍니다. 윈도우에서 설치 파일을 따로따로 내려받던 경험과 가장 크게 다른 점입니다.

✍️ 운영자 한마디

update와 upgrade가 같은 건 줄 알고 한참 헷갈렸습니다. 목록을 새로 받아오는 것과 실제로 새 버전을 설치하는 것이 다르다는 걸 알고 나서야 머릿속이 정리됐습니다.

2단계. 패키지는 어디서 오는가 — 저장소 개념

apt로 설치하는 프로그램들은 인터넷 어딘가에 정리되어 있는 **저장소(repository)**에서 옵니다. 저장소는 우분투 측이 관리하는, 신뢰할 수 있는 프로그램 창고라고 생각하면 됩니다. 어떤 저장소를 바라보는지는 시스템에 미리 설정되어 있어서, 입문 단계에서는 따로 손댈 일이 거의 없습니다.

여기서 중요한 점 하나. 내 컴퓨터는 저장소에 어떤 프로그램의 어떤 버전이 있는지를 목록으로 들고 있는데, 이 목록은 시간이 지나면 낡습니다. 그래서 다음 단계의 update가 필요합니다.

3단계. update 와 upgrade 구분하기

입문자가 가장 많이 헷갈리는 부분입니다. 둘은 이름이 비슷하지만 하는 일이 다릅니다.

apt update — 저장소에 어떤 프로그램의 최신 버전이 나와 있는지, 목록(정보)을 새로 받아오는 단계입니다. 실제로 설치된 프로그램이 바뀌지는 않습니다.
apt upgrade — update 로 받아온 정보를 바탕으로, 이미 설치된 프로그램을 실제로 최신 버전으로 올리는 단계입니다.

그래서 보통 이 둘을 이어서 실행합니다.

sudo apt update
sudo apt upgrade

순서를 기억하면 쉽습니다. 먼저 목록을 갱신(update)하고, 그다음에 실제 업그레이드(upgrade)입니다. 비유하자면 update는 “마트 전단지를 새로 받아 보는 것”이고, upgrade는 “전단지를 보고 실제로 장을 보는 것”입니다.

4단계. 프로그램 검색하고 정보 확인하기

설치할 프로그램의 정확한 이름을 모를 때는 먼저 검색합니다.

apt search 키워드

검색 결과에서 후보를 찾았다면, 설치 전에 그 패키지가 정확히 무엇인지 자세히 들여다볼 수 있습니다.

apt show 패키지이름

apt show 는 패키지 설명, 버전, 어떤 부속을 필요로 하는지 등을 보여 줍니다. 이름만 보고 헷갈릴 때 한 번 확인해 두면 엉뚱한 프로그램을 까는 실수를 줄일 수 있습니다.

5단계. 설치하기

이름을 확인했다면 설치합니다.

sudo apt install 패키지이름

설치 중에 “계속하시겠습니까?”를 물으면 y 를 입력하고 엔터를 누르면 됩니다. 앞서 말한 의존성, 즉 이 프로그램이 필요로 하는 부속들도 이때 함께 설치됩니다.

6단계. 삭제하기 — remove · purge · autoremove

설치한 프로그램이 더 필요 없다면 지웁니다. 여기서 세 가지 명령의 차이를 알아 두면 좋습니다.

sudo apt remove 패키지이름

remove 는 프로그램 본체를 지우되, 설정 파일은 남겨 둡니다. 나중에 같은 프로그램을 다시 깔 때 설정을 이어 쓰고 싶다면 이쪽이 편합니다.

sudo apt purge 패키지이름

purge 는 설정 파일까지 함께 지워, 더 깔끔하게 흔적을 정리합니다.

sudo apt autoremove

autoremove 는 어떤 프로그램을 설치할 때 딸려 왔던 부속들 중, 이제 아무도 쓰지 않는 것들을 정리합니다. 프로그램을 몇 번 지운 뒤 한 번씩 실행해 두면 디스크가 깔끔해집니다.

7단계. sudo가 필요한 이유

위 명령들에는 대부분 sudo 가 붙습니다. 프로그램 설치·삭제·목록 갱신은 시스템 전체에 영향을 주는 작업이기 때문입니다. 아무 계정이나 시스템 영역을 마음대로 바꿀 수 있으면 위험하므로, 관리자 권한을 잠깐 빌려오는 sudo 를 요구하는 것입니다.

반대로 단순히 검색하거나 정보만 보는 apt search, apt show 는 시스템을 바꾸지 않으므로 sudo 없이도 됩니다. “시스템을 바꾸는가”를 기준으로 sudo가 필요한지 가늠해 보면 대체로 들어맞습니다.

초보자가 자주 막히는 부분

update 만 하고 끝냄 — update 는 목록만 갱신합니다. 실제 최신화는 upgrade 까지 해야 합니다.
sudo 를 빼서 권한 오류 — install·remove·update 는 시스템을 바꾸므로 sudo 가 필요합니다.
remove 했는데 설정이 남아 헷갈림 — 흔적까지 지우려면 remove 대신 purge 를 쓰세요.
패키지 이름을 잘못 입력 — 설치가 안 되면 먼저 apt search 로 정확한 이름을 확인하세요.
설치 직후 update 를 건너뜀 — 새로 설치한 환경은 목록이 오래됐을 수 있어, 먼저 sudo apt update 를 한 번 해 두면 안전합니다.

apt 사용 체크리스트

apt update 가 '목록 갱신'이라는 것을 안다
apt upgrade 로 실제 프로그램을 최신화한다
apt search / apt show 로 패키지를 찾고 확인할 수 있다
sudo apt install 로 설치할 수 있다
remove · purge · autoremove 의 차이를 안다
시스템을 바꾸는 명령에 sudo 가 필요한 이유를 안다

정리

apt는 우분투에서 프로그램을 다루는 가장 기본적인 도구입니다. 패키지가 저장소에서 온다는 점을 알고, 목록을 갱신하는 update 와 실제로 올리는 upgrade 를 구분하고, install·remove·purge·autoremove 의 역할과 search·show 의 쓰임을 익혀 두면, 새 프로그램이 필요할 때 명령 한 줄로 해결할 수 있습니다. 명령 앞의 sudo 는 시스템을 보호하기 위한 안전장치라는 점도 함께 기억해 두세요. 여기까지 익혔다면, 이제 버전 관리가 까다로운 도구를 다루는 방법으로 넘어가도 좋습니다.

셸 설정 파일(.bashrc) 안전하게 손보기

Thu, 09 Jul 2026 06:05:28 GMT

"이 줄을 .bashrc에 추가하세요." 입문자가 자주 만나는 안내입니다. 그런데 막상 그 파일을 열려고 하면 망설여집니다. 잘못 건드리면 터미널이 이상해지는 건 아닐까. 결론부터 말하면, 백업하는 법과 되돌리는 법만 알면 .bashrc는 전혀 무서운 파일이 아닙니다. 이 글에서는 그 두 가지를 중심으로, 무엇을 넣고 어떻게 적용하는지까지 안전하게 다루는 순서를 따라갑니다.

.bashrc는 어떤 파일인가

.bashrc는 bash 셸이 켜질 때마다 자동으로 한 번씩 읽어 들이는 개인 설정 파일입니다. 파일 이름 앞에 점이 붙어 있어 평소 파일 목록에는 숨겨져 있지만, 사용자 홈 디렉터리(~)에 자리합니다.

여기에 적어 둔 내용은 새 터미널을 열 때마다 자동으로 적용됩니다. 그래서 '매번 똑같이 설정하기 귀찮은 것'을 한 번 적어 두는 용도로 쓰입니다. 파일이 있는지부터 확인하려면 홈 디렉터리에서 숨김 파일까지 함께 보면 됩니다.

ls -al ~ | grep bashrc

파일을 열어 직접 살펴보려면 평소 쓰는 편집기를 쓰면 됩니다. 터미널 안에서 간단히 본다면 nano ~/.bashrc 정도로 충분합니다. 처음에는 내용을 바꾸지 말고, 어떤 줄들이 들어 있는지 눈으로만 훑어 보는 것을 권합니다.

무엇을 넣는가

.bashrc에 흔히 넣는 것은 크게 네 가지입니다. 각각 한 줄이 어떤 모양인지 함께 보면 감이 빨리 잡힙니다.

환경변수 export

환경변수는 여러 프로그램이 공통으로 참고하는 설정값입니다. export를 붙여 적어 두면 그 값을 이후 실행되는 프로그램들이 읽을 수 있습니다. 예를 들어 기본 편집기를 지정하는 식입니다.

export EDITOR=nano

PATH 추가

PATH는 명령을 어느 폴더에서 찾을지 알려 주는 목록입니다. 직접 설치한 도구가 인식되지 않을 때, 그 도구가 있는 폴더를 기존 PATH 뒤에 더해 줍니다. 기존 값을 지우지 않도록 $PATH를 함께 적는 것이 핵심입니다.

export PATH="$HOME/.local/bin:$PATH"

alias

길고 자주 쓰는 명령에 짧은 별명을 붙이는 설정입니다. 자세한 활용은 별칭과 히스토리 글에서 따로 다룹니다.

alias ll='ls -al'

프롬프트(PS1)

명령 앞에 표시되는 안내 부분을 프롬프트라고 하며, PS1 값으로 모양을 바꿀 수 있습니다. 처음에는 손대지 않아도 되지만, "이런 것도 여기서 정한다" 정도만 알아 두면 됩니다.

✍️ 운영자 한마디

설정 파일을 잘 모르고 고쳤다가 터미널이 이상해져서 당황한 적이 있습니다. 그 뒤로는 손대기 전에 꼭 복사본부터 만들어 둡니다. 백업 하나가 마음의 평화를 주더군요.

수정 전, 먼저 백업하기

가장 중요한 습관은 '고치기 전에 사본 만들기'입니다. 아래 명령은 현재 .bashrc를 .bashrc.bak이라는 이름으로 복사해 둡니다.

cp ~/.bashrc ~/.bashrc.bak

이 한 줄이면, 나중에 무엇이 꼬여도 돌아갈 자리가 생깁니다. 백업을 만들어 두면 마음 편히 수정할 수 있습니다. 여러 번 고칠 예정이라면 백업 이름에 날짜를 붙여 두는 것도 방법입니다.

고친 내용 적용하기

.bashrc는 새 셸이 시작될 때 읽힙니다. 그래서 이미 열려 있는 터미널에서는 방금 고친 내용이 바로 보이지 않습니다. 다음 명령으로 지금 이 터미널에 즉시 적용할 수 있습니다.

source ~/.bashrc

source는 파일을 지금 이 셸에서 다시 읽어 오라는 명령입니다. 터미널을 새로 열어도 같은 효과가 납니다. 적용 직후 오류 메시지가 보이면, 방금 추가한 줄에 오타가 없는지부터 확인하세요.

실수했을 때 되돌리기

설정을 고친 뒤 오류 메시지가 뜨거나 동작이 이상하다면, 아까 만들어 둔 백업으로 되돌리면 됩니다.

cp ~/.bashrc.bak ~/.bashrc
source ~/.bashrc

백업을 미리 만들어 두는 습관이 있다면, 설정을 자유롭게 실험해 볼 수 있습니다. 망쳐도 되돌릴 수 있다는 사실 자체가 가장 든든한 안전장치입니다. 백업조차 없는 상황에서 새 터미널이 아예 안 열린다면, 추가한 마지막 줄을 지우는 것만으로 풀리는 경우가 많습니다.

.bashrc·.bash_profile·.profile은 무엇이 다른가

비슷해 보이는 파일이 여럿이라 헷갈리기 쉽습니다. 핵심만 구분하면 이렇습니다.

.bashrc — 새 터미널 창을 열 때처럼, 매번 새로 시작되는 셸에서 읽힙니다. 평소 설정은 대부분 여기에 둡니다.
.bash_profile — 로그인할 때 한 번 읽히는 파일입니다. 그래서 많은 환경에서 .bash_profile 안에 .bashrc를 불러오는 줄을 넣어, 결국 .bashrc가 함께 적용되도록 해 둡니다.
.profile — bash 전용이 아니라 더 일반적인 로그인 설정 파일입니다. .bash_profile이 있으면 보통 그쪽이 우선합니다.

입문 단계에서는 "내 설정은 일단 .bashrc에 적는다"는 원칙만 지켜도 충분합니다. WSL의 우분투처럼 기본 환경에서는 .bashrc가 적용되도록 이미 연결돼 있는 경우가 많습니다.

초보자가 자주 막히는 부분

백업 없이 수정 — 문제가 생겼을 때 돌아갈 자리가 없어 당황합니다. 고치기 전 cp로 사본부터 만드세요.
수정 후 반영이 안 됨 — 새 셸에서만 읽히기 때문입니다. source로 적용하거나 터미널을 새로 여세요.
파일이 안 보임 — 점으로 시작하는 숨김 파일이라 기본 목록에 안 나옵니다. ls -a로 확인할 수 있습니다.
PATH를 통째로 덮어씀 — export PATH="..."에서 $PATH를 빼먹으면 기존 명령들이 갑자기 안 먹힐 수 있습니다. 항상 $PATH를 함께 적으세요.
셸을 착각 — zsh를 쓰면서 .bashrc를 고치면 적용되지 않습니다. 셸에 맞는 파일(zsh는 .zshrc)을 손봐야 합니다.

.bashrc 수정 점검 체크리스트

고치기 전에 cp ~/.bashrc ~/.bashrc.bak 으로 백업했다
내가 쓰는 셸이 bash가 맞는지 확인했다
PATH를 더할 때 $PATH 를 함께 적어 기존 값을 지키도록 했다
수정 후 source ~/.bashrc 로 적용했다
문제가 생기면 백업으로 되돌리는 방법을 알고 있다

정리

.bashrc는 셸을 내 손에 맞게 길들이는 첫 단추입니다. 어렵게 느껴지는 이유는 파일 자체가 위험해서가 아니라, 되돌리는 법을 몰라서일 때가 많습니다. 무엇을 넣는지(환경변수·PATH·alias·프롬프트)를 알고, 백업을 만들고, source로 적용하고, 막히면 백업으로 돌아가는 흐름만 몸에 익히면 됩니다. 비슷한 파일들의 차이까지 한 번 정리해 두면 다른 안내를 만나도 헷갈리지 않습니다. 다음 단계로는 이 파일에 자주 쓰는 명령을 짧게 줄여 주는 alias를 더해 보면 작업이 한결 빨라집니다.

Git 처음 설정하기: 이름·이메일·기본 브랜치·SSH 키

Thu, 09 Jul 2026 06:05:28 GMT

Git을 설치하고 나면 바로 코드를 저장하고 싶어지지만, 그 전에 한 번만 해두면 두고두고 편한 설정이 있습니다. 바로 “나는 누구인가”를 Git에 알려주는 일입니다. Git은 변경 사항을 저장(커밋)할 때마다 누가 했는지를 함께 기록하기 때문에, 이 정보가 비어 있으면 경고가 뜨거나 커밋이 막힐 수 있습니다.

이 글에서는 설치 확인부터 이름·이메일·기본 브랜치 설정, 첫 저장소를 만드는 개념, 그리고 원격 저장소와 안전하게 연결하는 SSH 키 흐름까지 순서대로 짚어 봅니다.

먼저 Git이 설치됐는지 확인하기

설정에 들어가기 전에, Git이 제대로 깔렸는지부터 확인합니다.

git --version

버전 정보가 한 줄 출력되면 설치가 된 것입니다. 명령을 찾을 수 없다는 메시지가 나오면 아직 설치가 안 됐거나 경로 인식이 안 된 상태이니, 운영체제에 맞는 설치를 먼저 끝내야 합니다.

이름과 이메일 설정하기

Git은 커밋마다 작성자의 이름과 이메일을 함께 남깁니다. 아래 두 줄로 이 값을 정합니다.

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

따옴표 안의 값은 본인 것으로 바꾸면 됩니다. 잘 설정됐는지는 다음 명령으로 확인할 수 있습니다.

git config --global --list

✍️ 운영자 한마디

Git 설정만 해두고 SSH 키는 미뤄뒀다가, 매번 비밀번호 묻는 게 귀찮아 결국 키를 만들었습니다. 공개키·비밀키 개념이 처음엔 막연했는데, 한 번 해보니 별게 아니더군요. 진작 할 걸 싶었습니다.

--global이 뜻하는 것

위 명령에 붙은 --global은 “이 컴퓨터의 내 계정 전체에 적용한다”는 의미입니다. 한 번만 설정해 두면 이후 만드는 모든 저장소가 이 값을 기본으로 씁니다.

--global 을 붙이면: 사용자 계정 전체의 기본값이 됩니다.
--global 을 빼고 저장소 폴더 안에서 실행하면: 그 저장소에만 적용됩니다.

대부분의 입문자는 우선 --global로 한 번 정해 두는 것으로 충분합니다. 회사 계정과 개인 계정을 한 컴퓨터에서 나눠 써야 한다면, 그때 저장소별 설정을 따로 둘 수 있다는 점만 기억해 두면 됩니다.

기본 브랜치 이름 정하기

새 저장소를 만들면 첫 브랜치가 자동으로 생깁니다. 이 기본 브랜치의 이름을 미리 정해 둘 수 있습니다.

git config --global init.defaultBranch main

이렇게 해 두면 앞으로 만드는 저장소의 첫 브랜치가 main이라는 이름으로 시작합니다. 이름 자체는 취향과 협업 규칙에 따라 달라질 수 있으니, 함께 일하는 곳이 있다면 그쪽 관례를 따르는 편이 좋습니다.

첫 저장소 만들기 개념

설정을 마쳤다면 이제 실제 저장소를 만들 수 있습니다. 프로젝트로 쓸 폴더로 이동한 뒤 아래 명령을 실행합니다.

git init

이 명령은 현재 폴더를 Git이 관리하는 저장소로 바꿉니다. 이 순간부터 그 폴더 안의 변경 사항을 기록할 수 있게 되고, 앞서 정한 이름·이메일이 커밋에 함께 남게 됩니다. 변경을 기록으로 확정하는 것이 커밋이며, 처음엔 git add 로 기록할 파일을 고르고 git commit 으로 확정한다는 큰 흐름만 알아 두면 충분합니다.

SSH 키로 원격 저장소와 연결하기

코드를 GitHub 같은 원격 저장소에 올리려면, 내 컴퓨터가 그 서비스에 “나는 권한이 있는 사람”임을 증명해야 합니다. 이때 매번 비밀번호를 치는 대신, 더 안전하고 편한 방식이 SSH 키입니다.

SSH 키는 한 쌍이다

SSH 키는 항상 **비밀키(private)**와 공개키(public) 두 개가 한 쌍으로 만들어집니다.

비밀키 — 내 컴퓨터에만 두는 열쇠입니다. 절대 외부에 공유하면 안 됩니다.
공개키 — 원격 서비스에 등록하는, 공개해도 되는 자물쇠 짝입니다.

원격 서비스에 등록된 공개키와 내 비밀키가 한 쌍으로 맞을 때만 연결이 허용됩니다. 비밀번호를 주고받지 않으므로 더 안전합니다.

키 생성하기

키 한 쌍은 아래 명령으로 만듭니다.

ssh-keygen -t ed25519 -C "you@example.com"

-C 뒤의 값은 키를 알아보기 쉽게 적는 메모이며, 보통 이메일을 넣습니다. 명령을 실행하면 저장 위치와 암호 구문(passphrase)을 물어봅니다. 위치는 기본값을 그대로 써도 되고, 암호 구문은 키를 한 번 더 보호하는 비밀번호이니 정해 두면 더 안전합니다. ed25519 가 권장되는 방식이지만, 환경에 따라 다른 방식이 필요할 수도 있으니 애매하면 공식 문서를 확인하세요.

공개키를 원격 서비스에 등록하기

키를 만들면 보통 홈 폴더 아래 .ssh 폴더에 비밀키와 .pub 으로 끝나는 공개키가 생깁니다. 등록할 때는 공개키의 내용이 필요합니다.

cat ~/.ssh/id_ed25519.pub

이 명령으로 출력된 한 줄 전체를 복사한 뒤, 사용하는 원격 서비스의 설정 화면에서 “SSH 키 추가” 항목에 붙여 넣습니다. 등록 메뉴의 정확한 위치와 이름은 서비스마다 다르므로, 해당 서비스의 공식 문서를 확인하는 것을 권합니다. 핵심 흐름은 공개키만 등록하고 비밀키는 내 컴퓨터에 둔다는 것입니다.

초보자가 자주 막히는 부분

이름·이메일 없이 커밋 시도 — 설정을 건너뛰고 바로 커밋하면 작성자 정보가 없다는 경고가 나올 수 있습니다.
따옴표 빠뜨림 — 이름에 공백이 있는데 따옴표로 감싸지 않으면 값이 잘려 들어갈 수 있습니다.
--global의 범위 오해 — --global은 폴더 단위가 아니라 사용자 계정 전체에 적용된다는 점을 헷갈리기 쉽습니다.
비밀키를 등록하려 함 — 원격 서비스에는 .pub 공개키만 등록합니다. 비밀키를 올리면 안 됩니다.
설정 확인을 안 함 — 값이 제대로 들어갔는지 git config --global --list로 한 번 확인하지 않아 오타를 늦게 발견하는 경우가 있습니다.

초기 설정 체크리스트

git --version 으로 설치를 확인했다
user.name 과 user.email 을 --global 로 설정했다
init.defaultBranch 로 기본 브랜치 이름을 정했다
git config --global --list 로 값이 맞는지 확인했다
ssh-keygen 으로 SSH 키 한 쌍을 만들었다
공개키(.pub)만 원격 서비스에 등록했고, 비밀키는 그대로 둔다

정리

Git의 첫 설정은 길어 보이지만 사실 명령 몇 줄로 끝납니다. 이름과 이메일을 정해 두면 커밋 기록이 깔끔하게 남고, 기본 브랜치 이름까지 미리 정해 두면 새 저장소를 만들 때마다 신경 쓸 일이 줄어듭니다. 여기에 SSH 키 한 쌍을 만들고 공개키만 원격 서비스에 등록해 두면, 비밀번호 없이도 안전하게 코드를 주고받을 수 있습니다. 한 번 해두면 오래가는 설정이니, 코드를 본격적으로 다루기 전에 마무리해 두는 것을 권합니다.

파일 경로와 권한, 입문자가 가장 헷갈리는 부분

Thu, 09 Jul 2026 06:05:28 GMT

리눅스를 배우다 보면 명령어 자체보다 "지금 내가 어디 있는지"와 "이 파일을 만질 권한이 있는지"에서 더 자주 막힙니다. 파일을 분명히 만들었는데 못 찾겠고, 명령을 쳤더니 권한이 없다며 거부당하는 식입니다. 이 글은 그렇게 헷갈리는 지점을 질문과 답변으로 하나씩 풀어 봅니다.

Q. 절대경로와 상대경로는 뭐가 다른가요?

경로는 파일이나 폴더의 "주소"입니다. 같은 위치라도 표현 방식이 두 가지입니다.

절대경로는 맨 위(루트, /)에서부터 끝까지 다 적은 전체 주소입니다. 예: /home/사용자/문서/메모.txt. 어디서 실행하든 항상 같은 곳을 가리킵니다.
상대경로는 지금 내가 서 있는 위치를 기준으로 적은 주소입니다. 예: 문서/메모.txt. 현재 위치가 바뀌면 가리키는 곳도 달라집니다.

상대경로에서 자주 쓰는 약속이 두 가지 더 있습니다. . 은 현재 폴더, .. 은 상위 폴더입니다. 그래서 cd .. 는 한 단계 위로, ./스크립트.sh 는 "지금 이 폴더의 그 파일"을 뜻합니다. 헷갈릴 때는 항상 현재 위치부터 확인합니다.

pwd

Q. ~ 와 / 는 각각 무슨 뜻인가요?

둘 다 자주 보이지만 의미가 정반대에 가깝습니다.

/ 하나만 있으면 시스템 전체의 최상위(루트) 를 뜻합니다. 모든 경로의 출발점이며, 시스템 파일이 모여 있는 영역입니다.
~ 는 내 홈 디렉터리 를 가리키는 약자입니다. 보통 /home/내이름 같은 위치이며, 내가 자유롭게 쓸 수 있는 개인 공간입니다.

그래서 cd ~ 는 "내 집으로 돌아가기", cd / 는 "시스템 꼭대기로 가기"라고 이해하면 쉽습니다. 학습용 파일을 만들 때는 권한 문제가 적은 홈 디렉터리(~) 안에서 작업하는 편이 안전합니다.

cd ~
ls

✍️ 운영자 한마디

물결표(~)와 슬래시(/)를 헷갈려서 엉뚱한 위치에 파일을 만든 적이 여러 번 있습니다. 권한 오류가 나면 무작정 sudo부터 붙이던 버릇도 있었는데, 지금은 왜 막혔는지부터 보려고 합니다.

Q. ls -l 앞에 보이는 rwx 는 무엇인가요?

ls -l 로 파일 목록을 보면 줄 맨 앞에 -rwxr-xr-- 같은 글자가 나옵니다. 맨 앞 한 글자(- 또는 d)는 파일인지 폴더인지를 뜻하고, 그 뒤의 r, w, x 가 권한입니다.

r (read) — 읽기
w (write) — 쓰기(수정·삭제)
x (execute) — 실행

이 세 글자가 세 묶음으로 반복되는데, 순서대로 소유자 / 그룹 / 그 외 모두 에 대한 권한을 뜻합니다. 즉 -rwxr-xr-- 는 소유자는 읽기·쓰기·실행 모두 가능, 그룹은 읽기·실행만, 그 외는 읽기만 가능하다는 의미입니다. 같은 파일이라도 누구냐에 따라 할 수 있는 일이 다릅니다.

ls -l

Q. chmod 는 숫자와 기호 중 무엇으로 쓰나요?

chmod 는 파일의 권한 자체를 바꾸는 명령이고, 표기 방식이 두 가지입니다.

기호 방식은 기존 권한에 더하거나(+) 빼는(-) 방식입니다. 예를 들어 스크립트에 실행 권한만 더하고 싶을 때 직관적입니다.

chmod +x 스크립트.sh    # 실행 권한 추가
chmod -w 메모.txt        # 쓰기 권한 제거

숫자 방식은 권한 전체를 한 번에 지정합니다. r=4, w=2, x=1 을 더한 값을 소유자·그룹·기타 순으로 세 자리로 씁니다. 755 는 rwxr-xr-x, 644 는 rw-r--r-- 에 해당합니다.

chmod 755 스크립트.sh
chmod 644 메모.txt

입문 단계에서는 필요한 권한만 더하는 기호 방식(+x)이 이해하기 쉽고, 숫자 방식은 "한 번에 표준 권한을 맞춘다"는 정도로 익혀 두면 됩니다.

Q. 소유자나 그룹은 어떻게 바꾸나요? (chown)

권한이 "무엇을 할 수 있는가"라면, 소유자·그룹은 "누구의 것인가"입니다. 이걸 바꾸는 명령이 chown 입니다. 보통 다른 사용자가 만든 파일이나 시스템 영역의 파일 소유를 바꿀 때 쓰며, 대개 관리자 권한이 필요하므로 sudo 와 함께 씁니다.

sudo chown 내이름 파일.txt           # 소유자만 변경
sudo chown 내이름:내그룹 파일.txt    # 소유자와 그룹 변경

다만 학습 초기에 내 홈 디렉터리 안에서만 작업한다면 소유자는 이미 나로 되어 있어 chown 을 쓸 일은 많지 않습니다.

Q. sudo 는 언제 쓰는 건가요?

sudo 는 관리자 권한이 필요한 작업을 잠깐 빌려서 실행하는 명령입니다. 시스템 영역을 바꾸거나 프로그램을 설치할 때처럼, 일반 권한으로는 거부되는 작업에만 씁니다. 처음 실행하면 비밀번호를 묻는데, 이는 WSL이나 우분투를 설치할 때 정한 리눅스 계정 비밀번호입니다.

sudo apt update

습관처럼 모든 명령 앞에 sudo 를 붙이는 것은 권하지 않습니다. 내 파일에서 생긴 권한 문제는 대개 sudo 가 아니라 chmod 로 푸는 것이 맞습니다.

Q. WSL에서 윈도우 파일은 어디 있나요?

WSL을 쓰면 리눅스 경로와 윈도우 경로가 함께 보입니다. 윈도우의 드라이브는 /mnt 아래에 연결됩니다.

리눅스 영역: /home/내이름 같은 경로
윈도우 C 드라이브: /mnt/c/...

즉 윈도우 바탕화면의 파일을 리눅스에서 다루고 싶다면 /mnt/c/Users/... 같은 경로로 접근합니다. 다만 /mnt/c 아래는 윈도우 파일 시스템이라 리눅스의 rwx 권한이 그대로 적용되지 않습니다. chmod 를 걸어도 기대대로 동작하지 않거나, 권한이 일괄로 보이는 경우가 있습니다. 또 이 영역은 읽고 쓰는 속도가 리눅스 영역보다 느린 편입니다. 그래서 학습용·작업용 파일은 가급적 홈 디렉터리(/home)에 두는 편이 권한도 깔끔하고 속도도 빠릅니다.

초보자가 자주 막히는 부분

만든 파일을 못 찾음 — 보통 상대경로로 만든 뒤 다른 위치로 이동해 헤매는 경우입니다. pwd 로 현재 위치부터 확인하세요.
권한 거부를 무조건 sudo 로 해결 — 내 파일이라면 sudo 가 아니라 chmod 로 권한을 조정하는 게 맞을 때가 많습니다.
chmod 숫자를 외우려 함 — 처음에는 +x 같은 기호 방식으로 충분합니다. 숫자는 r=4·w=2·x=1 의 합이라는 원리만 기억해 두세요.
~ 와 / 혼동 — cd / 는 시스템 꼭대기, cd ~ 는 내 홈입니다. 정반대 방향입니다.
/mnt/c 에서 권한이 이상함 — 윈도우 영역은 리눅스 권한이 그대로 적용되지 않습니다. 권한이 중요한 작업은 /home 에서 하세요.

경로·권한 이해 체크리스트

절대경로(/ 로 시작)와 상대경로의 차이를 설명할 수 있다
~ 가 내 홈 디렉터리를 뜻한다는 것을 안다
ls -l 의 rwx 가 소유자·그룹·기타의 읽기·쓰기·실행 권한임을 안다
chmod(권한)와 chown(소유자), sudo(관리자 권한)의 역할 차이를 안다
WSL에서 윈도우 파일이 /mnt/c 아래에 있고 권한 처리가 다름을 안다

정리

경로와 권한은 리눅스를 쓰는 내내 따라다니는 개념입니다. 지금 내 위치(pwd)와 경로의 종류, 권한 표시(rwx), 그리고 chmod·chown·sudo 의 역할만 손에 익혀 두면, "못 찾겠다"와 "권한이 없다"는 오류를 스스로 해석할 수 있게 됩니다. WSL을 쓴다면 윈도우 파일과 리눅스 파일의 차이까지 알아 두면, 어디에 파일을 두어야 할지 판단하기가 한결 수월해집니다.

터미널이 처음이라면: 꼭 알아야 할 기본 명령

Thu, 09 Jul 2026 06:05:28 GMT

터미널을 처음 열면 검은 화면에 깜빡이는 커서만 보입니다. 마우스로 클릭하던 것에 익숙한 사람에게는 이 화면이 낯설고, 무엇을 쳐야 할지 막막합니다. 하지만 매일 쓰는 명령은 생각보다 적습니다. 아래 명령들이 손에 익으면 대부분의 기본 작업을 할 수 있고, 여기에 파이프와 단축키를 더하면 작업 속도가 눈에 띄게 빨라집니다.

지금 내가 어디에 있는가

터미널은 항상 "지금 어떤 폴더 안에 있는지"를 기준으로 동작합니다. 그래서 가장 먼저 익혀야 할 것은 위치를 확인하고 이동하는 명령입니다.

pwd — 현재 위치 확인

pwd(print working directory)는 지금 내가 어느 폴더에 있는지 전체 경로로 보여 줍니다. 파일이 안 보이거나 명령이 엉뚱하게 동작할 때 가장 먼저 쳐 봐야 할 명령입니다.

pwd

ls — 무엇이 있는지 목록 보기

현재 폴더 안에 어떤 파일과 폴더가 있는지 봅니다. 자세한 정보(권한·크기·수정 시각)를 보려면 ls -l, 숨김 파일까지 보려면 ls -a, 둘을 합쳐 ls -la 처럼 쓸 수 있습니다.

ls
ls -l
ls -la

cd — 폴더 이동

원하는 폴더로 들어갑니다. 상위 폴더로 가려면 cd .., 홈으로 한 번에 가려면 cd ~, 바로 직전 위치로 돌아가려면 cd - 를 씁니다.

cd projects
cd ..
cd ~

✍️ 운영자 한마디

개발을 오래 했어도 마우스에 익숙하다 보니, 터미널에서 cd로 옮기고 ls로 확인하는 단순한 흐름이 처음엔 의외로 손에 안 붙었습니다. Tab 자동완성을 알게 된 뒤로 오타가 확 줄었습니다.

파일과 폴더 다루기

mkdir — 폴더 만들기

새 폴더를 만듭니다. 중간 경로까지 한 번에 만들고 싶으면 -p 옵션을 붙입니다.

mkdir my-folder
mkdir -p projects/web/src

touch — 빈 파일 만들기

빈 파일을 즉석에서 만듭니다. 이미 있는 파일이면 수정 시각만 갱신됩니다.

touch notes.txt

cp / mv — 복사와 이동

cp는 복사, mv는 이동입니다. mv는 같은 위치에서 이름만 바꿀 때도 씁니다. 폴더째 복사하려면 cp -r 처럼 재귀 옵션을 붙입니다.

cp notes.txt backup.txt   # 복사
cp -r src/ src-backup/    # 폴더째 복사
mv notes.txt archive/     # 이동
mv old.txt new.txt        # 이름 바꾸기

rm — 삭제 (주의)

rm은 파일을 지웁니다. 리눅스에서 이 명령은 휴지통을 거치지 않고 바로 삭제하는 경우가 많아, 실행 전에 경로를 한 번 더 확인해야 합니다. 폴더를 지울 때 쓰는 rm -r 은 특히 신중해야 합니다.

rm draft.txt
rm -r old-folder/    # 폴더와 그 안의 내용까지 삭제 — 주의

내용 보기와 검색

cat / less — 파일 내용 보기

cat은 파일 내용을 화면에 한 번에 출력합니다. 내용이 길어 화면을 넘어가면 less로 한 페이지씩 넘겨 보는 편이 편합니다. less에서는 화살표나 스페이스로 넘기고, q로 빠져나옵니다.

cat notes.txt
less long-log.txt

grep — 내용 안에서 찾기

grep은 파일 안에서 특정 단어가 들어간 줄을 찾아 줍니다. 로그에서 원하는 부분만 추리거나, 설정 파일에서 한 줄을 찾을 때 매우 자주 씁니다. -i는 대소문자 무시, -r은 폴더 전체를 뒤지는 옵션입니다.

grep "error" server.log
grep -ri "todo" src/

find — 파일 자체 찾기

grep이 내용을 찾는다면, find는 이름이나 조건으로 파일 자체를 찾습니다.

find . -name "*.txt"

man / --help — 사용법 확인

명령 사용법이 궁금할 때는 외우기보다 직접 찾아보는 습관이 좋습니다.

ls --help
man ls

파이프와 리디렉션으로 명령 잇기

기본 명령에 익숙해지면, 명령끼리 연결하는 두 가지 개념이 작업을 크게 넓혀 줍니다.

파이프(|) 는 앞 명령의 출력을 뒤 명령의 입력으로 넘깁니다. 예를 들어 목록이 너무 길면 less로 받아 한 페이지씩 보고, 특정 줄만 추리고 싶으면 grep으로 넘깁니다.
리디렉션(>, >>) 은 화면에 나올 출력을 파일로 보냅니다. >는 새로 덮어쓰고, >>는 기존 내용 뒤에 덧붙입니다.

ls -l | less              # 긴 목록을 한 페이지씩
ls -la | grep ".txt"      # 목록 중 .txt 만 추리기
ls -l > files.txt          # 출력을 파일로 저장(덮어쓰기)
echo "메모" >> notes.txt   # 파일 끝에 한 줄 덧붙이기

손을 빠르게 만드는 단축키

명령 자체만큼이나 입력 습관도 중요합니다. 다음 세 가지만 알아도 체감 속도가 달라집니다.

Tab — 자동완성: 폴더·파일·명령 이름을 일부만 치고 Tab을 누르면 나머지를 채워 줍니다. 후보가 여러 개면 두 번 눌러 목록을 볼 수 있습니다. 오타와 시간을 크게 줄여 줍니다.
Ctrl+C — 실행 중단: 명령이 멈추지 않거나 잘못 입력했을 때 현재 동작을 중단합니다.
Ctrl+R — 명령 기록 검색: 예전에 쳤던 긴 명령을 다시 칠 필요 없이, Ctrl+R을 누르고 일부 단어만 입력하면 과거 명령을 찾아 줍니다.

초보자가 자주 막히는 부분

rm을 가볍게 사용 — 되돌리기 어렵습니다. 특히 rm -r 이나 경로가 긴 명령은 실행 전에 다시 읽어보세요.
대소문자 혼동 — 리눅스는 Notes.txt와 notes.txt를 다른 파일로 봅니다.
공백이 있는 이름 — 이름에 공백이 있으면 따옴표로 감싸거나 백슬래시를 써야 합니다. 예: cd "My Folder".
> 와 >> 혼동 — >는 기존 내용을 덮어쓰므로, 덧붙이려던 것이라면 >>를 써야 합니다.
자동완성을 안 씀 — Tab 자동완성을 쓰지 않고 긴 이름을 직접 치다 오타로 막히는 경우가 흔합니다.

기본 명령 체크리스트

pwd·ls·cd 로 위치를 확인하고 이동할 수 있다
mkdir·touch·cp·mv·rm 의 차이를 안다
cat·less·grep·find 로 내용을 보고 찾을 수 있다
파이프(|)와 리디렉션(>)의 개념을 안다
Tab 자동완성·Ctrl+C·Ctrl+R 을 활용하고 있다

정리

기본 명령은 외워서 쓰는 것이 아니라 손에 익혀 쓰는 것입니다. 처음에는 위치를 확인하고 이동하는 것만 반복해도 충분합니다. 익숙해지면 파일을 다루고, grep·find로 찾고, 파이프와 리디렉션으로 명령을 잇고, 단축키로 속도를 높이는 흐름이 자연스럽게 이어집니다. 다음 단계로는 파일 경로와 권한 개념을 함께 이해해 두고, 자주 쓰는 명령을 짧게 줄이는 방법까지 익히면 좋습니다.

MCP 처음 연결하기: AI 코딩 도구에 도구를 붙이는 법

Thu, 09 Jul 2026 06:05:28 GMT

AI 코딩 도구를 쓰다 보면 한 가지 한계를 만납니다. 코드는 잘 만들어 주는데, 정작 내 데이터베이스나 사내 문서, 외부 서비스의 정보에는 닿지 못한다는 점입니다. 그때마다 내용을 복사해 붙여 넣는 것도 한두 번이지, 반복되면 번거롭습니다. MCP(Model Context Protocol)는 바로 이 "AI 도구를 외부 세계에 연결하는 방식"을 표준화하기 위한 규약입니다. 이 글은 특정 도구의 설정 화면을 따라가는 안내가 아니라, 처음 연결할 때 알아 두면 좋은 개념과 흐름을 정리한 것입니다.

MCP가 무엇인가

MCP는 Model Context Protocol의 약자로, AI 모델(정확히는 AI 도구)이 외부 도구·데이터 소스와 통신하는 방법을 정해 둔 공통 규약입니다. 핵심 아이디어는 단순합니다. 도구마다 제각각인 연결 방식을 매번 새로 만들지 말고, 하나의 표준 인터페이스로 주고받자는 것입니다.

비유하자면 USB 같은 표준 단자에 가깝습니다. 예전에는 기기마다 전용 케이블이 필요했지만, 표준 단자가 생기면서 어떤 기기든 같은 방식으로 연결됩니다. MCP도 마찬가지로, AI 도구(클라이언트)와 외부 기능을 제공하는 쪽(MCP 서버) 사이를 표준화된 약속으로 잇습니다.

클라이언트와 서버

클라이언트: Claude Code 같은 AI 코딩 도구. 사용자가 직접 다루는 쪽입니다.
MCP 서버: 특정 기능이나 데이터를 표준 방식으로 노출하는 작은 프로그램. 파일 검색, 데이터베이스 조회, 외부 API 호출 등을 담당합니다.

클라이언트가 서버에게 "어떤 도구를 제공하니?"라고 묻고, 서버가 목록을 내려 주면, AI가 필요할 때 그 도구를 골라 쓰는 구조입니다.

왜 쓰는가

MCP를 쓰는 이유는 결국 연결의 재사용입니다. 한번 표준에 맞춰 만들어 두면, 그 서버를 지원하는 여러 AI 도구에서 같은 방식으로 붙여 쓸 수 있습니다. 도구를 바꿔도 연결 자산이 통째로 사라지지 않습니다.

또 하나는 맥락의 확장입니다. AI가 내 작업 환경의 실제 데이터를 참조할 수 있으면, 막연한 일반론 대신 내 상황에 맞는 답을 내놓기 쉬워집니다. 다만 이 장점은 곧 권한 문제와 직결되므로, 뒤에서 다시 짚겠습니다.

일반적인 연결 흐름

도구마다 화면과 명령은 다르지만, 큰 흐름은 비슷합니다.

연결할 MCP 서버를 고른다. 공식·공개된 서버인지, 무엇을 할 수 있는지 먼저 확인합니다.
설정 파일에 서버를 등록한다. 보통 AI 도구의 설정 파일에 서버 이름과 실행 방식을 적어 두는 형태입니다.
AI 도구를 재시작하거나 다시 불러온다. 등록한 내용을 도구가 읽어 들이게 합니다.
연결을 확인한다. 도구가 그 서버와 제공 도구 목록을 정상 인식하는지 봅니다.

# 개념 예시일 뿐 — 실제 키 이름·플래그는 도구/버전마다 다릅니다.
# 반드시 사용 중인 AI 도구의 공식 문서를 기준으로 하세요.
your-ai-tool mcp list      # 등록된 MCP 서버 목록 확인(개념)
your-ai-tool mcp status    # 연결 상태 확인(개념)

위 명령은 형식을 단정하는 것이 아니라 "이런 단계가 있다"는 개념 예시입니다. your-ai-tool 자리에 실제 도구 이름이 들어가며, 하위 명령과 설정 파일의 구조는 도구마다 다릅니다.

연결이 됐는지 확인하기

등록만 하고 끝내면 안 됩니다. 도구가 그 서버를 실제로 인식하는지, 서버가 제공한다고 한 기능 목록이 보이는지 확인해야 합니다. 대개 AI 도구에는 연결된 MCP 서버와 사용 가능한 도구를 보여 주는 화면이나 명령이 있습니다. 여기서 서버가 보이지 않거나 오류로 표시된다면, 설정 파일의 경로·이름·실행 방식 중 하나가 어긋난 경우가 많습니다.

권한과 범위를 의식해야 하는 이유

MCP 서버는 종종 내 파일, 데이터베이스, 외부 서비스에 접근할 수 있는 권한을 갖습니다. 이는 편리함의 원천이자 동시에 위험의 원천입니다.

최소 권한 원칙: 서버에 꼭 필요한 만큼만 접근 범위를 주세요. 모든 디렉터리, 모든 데이터에 닿게 할 이유는 없습니다.
출처 확인: 신뢰할 수 없는 곳에서 받은 서버는 신중히 다루세요. 외부 코드를 내 환경 권한으로 실행하는 셈입니다.
AI의 행동 검토: AI가 MCP 도구를 통해 파일을 바꾸거나 외부에 요청을 보낼 수 있습니다. 자동 실행 범위를 어디까지 허용할지 스스로 정해 두세요.

인증과 포트포워딩에서 자주 막힌다

원격 환경(예: WSL이나 서버)에서 MCP 서버를 붙일 때 가장 흔한 막힘 지점이 인증입니다.

OAuth 흐름: 외부 서비스에 OAuth로 로그인하는 서버라면, 브라우저로 인증 페이지가 열리는 단계가 있습니다. 그런데 원격·헤드리스 환경에서는 그 브라우저 창이 자동으로 열리지 않아 멈춘 것처럼 보일 수 있습니다. 안내에 나온 URL을 직접 열어 인증을 마쳐야 할 때가 많습니다.
포트포워딩: 인증 과정이 특정 로컬 포트로 콜백을 받는 경우, 원격 환경의 그 포트가 내 PC로 전달되지 않으면 마지막 단계에서 실패합니다. SSH 포트포워딩 등으로 해당 포트를 연결해 주어야 합니다.
토큰·자격증명 보관: 인증 후 발급된 토큰이 어디에 저장되는지, 어떻게 만료·갱신되는지 알아 두면 "어제는 됐는데 오늘은 안 되는" 상황을 덜 겪습니다.

이 부분은 서비스와 도구마다 절차가 크게 다르므로, 막혔다면 추측으로 설정을 바꾸기보다 해당 도구·서버의 공식 문서에서 인증 절차를 다시 확인하는 편이 빠릅니다.

초보자가 자주 막히는 부분

설정 파일 형식을 다른 도구 기준으로 베낌 — 도구·버전마다 키 이름이 달라 그대로 쓰면 인식되지 않습니다.
재시작을 빼먹음 — 등록 후 도구를 다시 불러오지 않으면 새 서버가 반영되지 않습니다.
연결 확인을 건너뜀 — 등록만 하고 실제 인식 여부를 안 봐서, 안 되는 줄도 모른 채 시간을 씁니다.
인증 단계에서 멈춘 걸 오류로 오해 — 원격 환경에서 브라우저 인증이 안 열린 것을 설정 오류로 착각합니다.
권한 범위를 과하게 줌 — 편하다는 이유로 모든 접근을 허용해 두는 것은 위험합니다.

MCP 연결 체크리스트

붙일 MCP 서버의 출처와 기능을 확인했다
설정 파일 형식을 사용 중인 도구의 공식 문서로 확인했다
등록 후 AI 도구를 재시작/재로딩했다
도구에서 서버와 제공 기능이 정상 인식되는지 확인했다
접근 권한을 필요한 범위로만 제한했다
원격 환경이라면 인증·포트포워딩 절차를 공식 문서로 확인했다

✍️ 운영자 한마디

MCP라는 말이 처음엔 거창하게 들렸는데, 결국 ‘AI 도구에 외부 도구를 표준 방식으로 붙이는 것’이라고 정리하니 한결 이해가 쉬웠습니다. 인증·포트포워딩 쪽에서 한 번 막혀 공식 문서를 꼼꼼히 다시 읽었던 기억이 납니다.

정리

MCP는 AI 코딩 도구를 외부 도구·데이터에 표준 방식으로 잇는 규약입니다. 연결의 흐름은 서버를 고르고, 설정 파일에 등록하고, 재시작한 뒤, 인식 여부를 확인하는 것으로 요약됩니다. 여기에 더해 권한 범위를 좁게 잡고, 원격 환경에서는 인증과 포트포워딩을 미리 챙기면 대부분의 초기 문제를 피할 수 있습니다. 다만 구체적인 설정 형식과 명령은 도구·버전마다 다르므로, 이 글의 개념을 바탕으로 반드시 사용 중인 도구의 공식 문서를 기준으로 실제 연결을 진행하세요.

WSL 네트워크·DNS가 안 될 때 점검하기

Thu, 09 Jul 2026 06:05:28 GMT

WSL을 쓰다 보면 apt 업데이트가 멈추거나, 브라우저는 되는데 터미널에서만 도메인 접속이 안 되는 일이 생깁니다. 이때 무작정 설정 파일을 뜯어고치면 오히려 멀쩡하던 것까지 망가지기 쉽습니다. 네트워크 문제는 특히 한 번에 하나씩 점검하는 원칙이 중요합니다. 이 글에서는 연결 자체인지 DNS인지부터 가른 다음, 순서대로 원인을 좁히는 방법을 정리합니다.

먼저: 연결 문제인지 DNS 문제인지 가른다

가장 먼저 할 일은 “인터넷 자체가 안 되는 것”과 “이름을 주소로 못 바꾸는 것”을 나누는 일입니다. 이 둘은 해결 방법이 완전히 다릅니다. 구분하는 방법은 간단합니다. 숫자 IP로 ping 과 도메인으로 ping 을 따로 해 보는 것입니다.

ping -c 3 1.1.1.1        # 숫자 IP로 직접 연결 확인
ping -c 3 google.com     # 도메인(이름)으로 연결 확인

결과를 다음과 같이 읽으면 됩니다.

둘 다 안 됨 → 연결 자체 문제일 가능성이 큽니다. WSL이 바깥으로 나가는 길이 막힌 상태입니다.
IP는 되는데 도메인은 안 됨 → 연결은 살아 있고, 이름을 주소로 바꾸는 DNS 단계에서 막힌 것입니다.
둘 다 됨 → 네트워크 기본은 정상이니, 문제는 특정 프로그램이나 프록시·인증 쪽일 수 있습니다.

이 한 번의 구분만으로도 이후 점검 범위가 절반으로 줄어듭니다.

✍️ 운영자 한마디

인터넷이 안 되면 무작정 재설치부터 떠올렸는데, ping으로 연결 자체와 DNS를 나눠 확인하는 법을 알고 난 뒤로는 원인을 훨씬 빨리 좁히게 됐습니다.

DNS가 무엇이고 왜 따로 막히나

DNS(Domain Name System)는 google.com 같은 사람이 읽는 이름을 컴퓨터가 통신할 수 있는 숫자 주소(IP)로 바꿔 주는 일종의 주소록입니다. 인터넷 연결이 살아 있어도 이 주소록을 못 보면, 이름으로는 어디에도 닿지 못합니다. 앞에서 “IP는 되는데 도메인은 안 됨”이 나왔다면 바로 이 단계의 문제입니다.

리눅스에서 어떤 네임서버(주소록 서버)를 쓸지는 보통 /etc/resolv.conf 파일에 적혀 있습니다. 현재 어떤 값을 쓰는지 확인해 봅니다.

cat /etc/resolv.conf

nameserver 줄에 적힌 주소가 비어 있거나 닿지 않는 값이면 도메인 해석이 실패합니다.

WSL의 resolv.conf 자동 생성 동작 이해하기

여기서 WSL만의 특징을 알아 둬야 합니다. WSL은 많은 경우 /etc/resolv.conf 를 자동으로 생성합니다. 즉, 손으로 네임서버를 고쳐도 WSL을 다시 켜면 원래 자동 생성된 내용으로 덮어쓸 수 있습니다.

그래서 “resolv.conf 를 고쳤는데 재부팅하면 되돌아간다”는 일이 흔합니다. 이는 고장이 아니라 자동 생성 동작이 살아 있다는 신호입니다. 자동 생성을 끄고 직접 관리하는 설정 방법도 있지만, 환경마다 적절한 값이 다르고 잘못 끄면 더 헷갈리므로 입문 단계에서는 무리해서 바꾸기보다 아래의 가벼운 재시도부터 권합니다.

wsl --shutdown 후 다시 시도하기

WSL의 네트워크 상태가 꼬였을 때, 가장 부작용이 적고 효과가 큰 첫 시도는 WSL을 완전히 껐다 켜는 것입니다. 윈도우 쪽 터미널(PowerShell 등)에서 실행합니다.

wsl --shutdown

이 명령은 실행 중인 WSL을 모두 종료합니다. 잠시 기다린 뒤 다시 WSL을 켜면, 네트워크 구성과 resolv.conf 가 새로 만들어지며 일시적인 꼬임이 풀리는 경우가 많습니다. 설정 파일을 손대기 전에 이 단계를 먼저 거치는 것을 권합니다.

VPN·회사 네트워크·방화벽을 의심하기

집에서는 멀쩡하던 WSL이 회사나 특정 네트워크에서만 안 된다면, 원인이 WSL 바깥에 있을 수 있습니다.

VPN — VPN을 켜면 네트워크 경로와 DNS가 바뀌어, WSL이 쓰던 네임서버로는 닿지 않게 될 수 있습니다. VPN을 켠/끈 상태를 각각 시험해 보면 영향 여부를 알 수 있습니다.
회사 네트워크·프록시 — 사내망은 정해진 프록시를 거치도록 강제하는 경우가 있습니다. 이때는 프록시 설정 없이 직접 나가려는 요청이 막힙니다.
방화벽·보안 프로그램 — 윈도우의 방화벽이나 보안 소프트웨어가 WSL의 통신을 차단할 수 있습니다.

이 항목들은 환경마다 정책이 크게 다르므로, 구체 설정을 바꾸기 전에 “언제 되고 언제 안 되는지”의 패턴부터 관찰하는 편이 안전합니다. 가능하면 네트워크 관리자나 보안 정책 안내를 함께 확인하세요.

시계가 어긋나면 인증이 깨질 수 있다

겉보기엔 네트워크 문제 같지만 실제로는 시간 문제인 경우도 있습니다. 보안 연결(HTTPS 등)은 인증서의 유효 기간을 검사하는데, WSL 안의 시계가 크게 어긋나 있으면 “인증서가 아직 유효하지 않다” 또는 “만료됐다”는 식의 오류가 날 수 있습니다. 연결은 되는데 특정 사이트나 패키지 서버에서 인증 오류가 반복된다면 시간을 확인해 보세요.

date   # 현재 시각이 실제와 크게 다르지 않은지 확인

시각이 많이 어긋나 있다면, 앞서 소개한 wsl --shutdown 후 재시작으로 시계가 다시 맞춰지는지부터 확인하는 것이 가볍습니다. 타임존이나 시간 동기화를 더 손봐야 한다면 한글·로케일·시간 설정 글을 함께 참고하세요.

초보자가 자주 막히는 부분

연결과 DNS를 구분하지 않고 설정부터 고침 — ping IP 와 ping 도메인 으로 먼저 나누면 헛수고를 크게 줄입니다.
resolv.conf 를 고치고 끝났다고 생각 — WSL이 자동 생성하면 재시작 때 덮어써집니다. 되돌아가는 건 정상 동작일 수 있습니다.
한 번에 여러 가지를 바꿈 — VPN, 방화벽, resolv.conf 를 동시에 손대면 무엇이 효과였는지 알 수 없습니다.
VPN·사내망 영향을 빼먹음 — “집에선 되는데 여기선 안 됨”이면 네트워크 환경 자체를 의심해야 합니다.
시간 문제를 네트워크 문제로 오해 — 인증서 관련 오류가 반복되면 date 로 시계부터 확인하세요.

네트워크·DNS 점검 체크리스트

ping 1.1.1.1 과 ping google.com 으로 연결과 DNS를 구분했다
cat /etc/resolv.conf 로 네임서버 값을 확인했다
resolv.conf 가 WSL 자동 생성 대상일 수 있음을 이해했다
윈도우에서 wsl --shutdown 후 다시 켜 봤다
VPN·회사 네트워크·방화벽의 영향을 확인했다
인증 오류가 있으면 date 로 시계를 점검했다

정리

WSL 네트워크 문제는 원인이 여러 층에 걸쳐 있어 막막해 보이지만, 점검 순서를 정해 두면 의외로 빨리 좁혀집니다. 먼저 ping 으로 연결인지 DNS인지 가르고, 자동 생성되는 resolv.conf 의 동작을 이해한 뒤, wsl --shutdown 같은 가벼운 재시도부터 합니다. 그래도 안 되면 VPN·사내망·방화벽 같은 바깥 요인과 시계 어긋남까지 의심하면 됩니다. 핵심은 한 번에 하나씩 바꾸며 결과를 확인하는 것, 그 원칙만 지켜도 대부분의 문제는 침착하게 풀립니다.

Node.js와 버전 관리 도구, 입문자 기준으로 정리

Thu, 09 Jul 2026 06:05:28 GMT

웹 관련 도구를 설치하다 보면 “Node.js가 필요합니다”라는 안내를 자주 만나게 됩니다. 막상 설치하려고 보면 버전이 여러 갈래로 나뉘어 있고, 어떤 글은 특정 버전을 콕 집어 요구하기도 합니다. 처음에는 “그냥 하나 깔면 되지 않나” 싶지만, 곧 버전 차이로 막히는 순간이 옵니다. 이 글은 그 배경을 입문자 눈높이에서 풀어 봅니다.

Node.js가 무엇인가

자바스크립트는 원래 웹 브라우저 안에서 동작하는 언어였습니다. Node.js는 그 자바스크립트를 브라우저 밖, 즉 일반 프로그램처럼 실행할 수 있게 해 주는 런타임입니다. 덕분에 자바스크립트로 서버를 돌리거나, 명령줄 도구를 만들거나, 개발에 필요한 각종 보조 도구를 실행할 수 있게 됩니다.

많은 개발 도구가 Node.js 위에서 동작하기 때문에, 웹 쪽을 다루다 보면 자연스럽게 설치를 요구받게 됩니다.

npm은 무엇인가

Node.js를 설치하면 보통 npm(Node Package Manager)이 함께 따라옵니다. npm은 다른 사람이 만들어 공개한 자바스크립트 코드 묶음(패키지)을 내려받아 프로젝트에 더해 주는 도구입니다. 직접 모든 기능을 만들지 않고, 이미 잘 만들어진 부품을 가져다 쓰는 셈입니다.

가장 자주 만나는 명령은 다음 정도입니다.

npm install
npm install <패키지이름>
npm run <스크립트이름>

npm install을 인자 없이 실행하면 프로젝트의 package.json에 적힌 의존성을 한꺼번에 내려받습니다. 여기서 중요한 점은, npm 자체도 Node.js 버전에 묶여서 함께 바뀐다는 것입니다. 즉 Node.js 버전을 전환하면 그에 딸린 npm 버전도 같이 따라오는 경우가 많습니다. 그래서 “버전 관리”는 사실상 Node.js와 npm을 한 묶음으로 다루는 일에 가깝습니다.

왜 버전 관리가 필요한가

Node.js는 꾸준히 새 버전이 나옵니다. 그런데 프로젝트나 도구마다 “이 버전 이상”, 혹은 “이 버전대에서 동작”처럼 요구 사항이 다를 수 있습니다. 컴퓨터에 한 가지 버전만 깔려 있으면, 어떤 프로젝트는 잘 되는데 다른 프로젝트는 버전이 맞지 않아 오류가 나는 상황이 생깁니다.

프로젝트 A는 비교적 최신 버전을 요구할 수 있습니다.
프로젝트 B는 더 낮은 버전대에서 동작하도록 맞춰져 있을 수 있습니다.
이 둘을 같은 컴퓨터에서 오가려면 버전을 바꿔 가며 써야 합니다.

이때 버전을 매번 지우고 다시 까는 것은 번거롭습니다. 그래서 여러 버전을 깔아 두고 필요할 때 전환하는 도구가 등장합니다.

✍️ 운영자 한마디

프로젝트마다 요구하는 Node 버전이 달라 한 번 환경이 꼬였던 적이 있습니다. 버전 매니저를 쓰기 시작하면서 그런 충돌 스트레스가 많이 줄었습니다.

버전 관리 도구의 개념

nvm처럼 흔히 쓰이는 버전 관리 도구는 “Node.js 버전을 골라서 깔고, 필요에 따라 바꿔 쓰게” 해 줍니다. 한 컴퓨터에 여러 버전을 보관해 두고 명령 한 줄로 지금 쓸 버전을 바꾸는 식입니다. 도구에 따라 이름과 사용법은 조금씩 달라도, 핵심 목적은 버전 전환을 쉽게 만드는 것으로 같습니다.

일반적인 사용 흐름은 대체로 다음과 같습니다.

사용할 버전을 설치합니다(보통 LTS 표시가 붙은 버전을 권장).
현재 사용할 버전을 선택해 전환합니다.
지금 어떤 버전이 활성화돼 있는지 확인합니다.

활성화된 버전이 무엇인지 확인할 때는 보통 아래 같은 명령을 씁니다.

node --version

nvm의 일반적인 사용 흐름

nvm을 예로 들면, 대체로 아래 같은 흐름으로 사용합니다. 명령 형태는 도구·시점에 따라 달라질 수 있으니 정확한 설치와 사용법은 공식 문서를 확인하세요.

nvm install --lts
nvm use --lts
nvm ls

nvm install --lts 는 현재 LTS로 표시된 버전을 내려받아 설치합니다.
nvm use --lts 는 지금 셸에서 사용할 버전을 그 LTS로 전환합니다.
nvm ls 는 내 컴퓨터에 설치된 버전 목록과 지금 활성화된 버전을 보여 줍니다.

여기서 자주 헷갈리는 점은, 버전 전환이 지금 열려 있는 터미널 기준으로 적용된다는 것입니다. 새 터미널을 열거나 환경을 다시 켜면 기본 버전으로 돌아갈 수 있어, 의도한 버전이 맞는지 node --version으로 다시 확인하는 습관이 안전합니다.

시스템 직접 설치 vs 버전 관리 도구

Node.js를 쓰는 길은 크게 두 갈래입니다. 하나는 패키지 매니저(apt 등)나 설치 파일로 시스템에 한 버전을 직접 설치하는 방식이고, 다른 하나는 nvm 같은 버전 관리 도구로 여러 버전을 얹어 두는 방식입니다.

시스템 직접 설치: 한 버전만 쓰면 간단하고 깔끔합니다. 다만 버전을 바꾸려면 지우고 다시 까는 번거로움이 있고, 권한(sudo)이 얽혀 꼬이기 쉽습니다.
버전 관리 도구: 여러 버전을 보관하고 명령 한 줄로 전환할 수 있어 프로젝트가 늘수록 편합니다. 대신 처음에 도구를 한 번 설치·설정하는 단계가 더 필요합니다.

입문 단계에서 프로젝트를 여럿 다룰 가능성이 보인다면, 처음부터 버전 관리 도구로 시작하는 편이 나중의 충돌을 줄여 줍니다.

LTS를 기본으로 두는 이유

버전을 고를 때 입문자에게 가장 무난한 선택은 LTS(장기 지원) 표시가 붙은 버전입니다. LTS는 비교적 오래 안정적으로 유지되는 흐름이라 잦은 변화로 인한 혼란이 적습니다. 다만 특정 프로젝트가 정해진 버전을 요구한다면 그 버전에 맞춰야 하니, 정답이 하나로 고정된 것은 아니라는 점을 기억하면 좋습니다.

초보자가 자주 막히는 부분

버전이 하나면 충분하다고 가정 — 프로젝트가 늘어나면 요구 버전이 갈려서 충돌이 생기기 쉽습니다.
특정 글의 버전 번호를 그대로 맹신 — 버전 번호는 시점에 따라 달라지므로, 숫자 자체보다 LTS 개념과 프로젝트 요구를 기준으로 삼는 편이 안전합니다.
활성 버전을 확인하지 않음 — 전환했다고 생각했는데 실제로는 다른 버전이 활성화돼 있어 오류가 나는 경우가 있습니다.
도구별 명령 혼용 — 버전 관리 도구마다 명령이 달라서, 다른 도구의 명령을 그대로 입력하면 동작하지 않을 수 있습니다.

버전 관리 점검 체크리스트

Node.js가 무엇을 하는 도구인지 한 줄로 설명할 수 있다
왜 프로젝트마다 버전이 갈릴 수 있는지 이해했다
버전 관리 도구가 여러 버전을 전환하는 역할임을 안다
입문 단계에서는 LTS 버전을 기본으로 고르면 된다는 점을 기억한다
node --version 으로 현재 버전을 확인할 수 있다

정리

Node.js는 자바스크립트를 브라우저 밖에서도 실행하게 해 주는 도구이고, 프로젝트마다 요구 버전이 달라질 수 있어 버전 관리가 필요해집니다. nvm 같은 도구는 여러 버전을 깔아 두고 손쉽게 전환하도록 도와줍니다. 입문 단계에서는 특정 숫자에 매달리기보다 LTS를 기본으로 두면 충분하며, 세부 명령은 도구와 시점에 따라 달라질 수 있으니 공식 안내를 확인하는 습관을 들이세요.

WSL에서 Python 개발환경 깔끔하게 만들기

Thu, 09 Jul 2026 06:05:28 GMT

우분투에서 파이썬을 시작하려고 보면 의외로 첫 단계부터 헷갈립니다. 어떤 글은 python, 어떤 글은 python3라고 하고, “시스템 파이썬은 건드리지 말라”는 경고도 자주 보입니다. 이 글은 그 혼란을 입문자 눈높이에서 정리하고, 시스템 파이썬을 안전하게 둔 채 프로젝트별 가상환경으로 깔끔하게 개발을 시작하는 흐름을 따라갑니다. 정확한 버전 번호는 환경마다 다르니 단정하지 않고, 확인 명령 위주로 안내합니다.

우분투에는 이미 파이썬이 있다

WSL 우분투에는 보통 python3가 이미 설치되어 있습니다. 운영체제 자체가 내부적으로 파이썬을 쓰는 부분이 있기 때문입니다. 그래서 첫걸음은 설치가 아니라 “있는지 확인”입니다.

python3 --version

버전 번호가 출력되면 이미 파이썬을 쓸 수 있는 상태입니다. 어떤 버전이 깔려 있는지는 우분투 버전과 시점에 따라 다르므로, 특정 숫자를 단정하기보다 위 명령으로 직접 확인하는 편이 정확합니다.

python과 python3 명령의 차이

입문자가 가장 먼저 부딪히는 벽이 이 부분입니다. 우분투에서는 파이썬을 python3라는 이름으로 부르는 경우가 많고, 환경에 따라 python이라고만 입력하면 “명령을 찾을 수 없다”는 오류가 날 수 있습니다.

python3 — 우분투에서 파이썬을 부르는 일반적인 이름입니다.
python — 환경에 따라 아예 없거나, 다른 것을 가리킬 수 있습니다.

그래서 입문 단계에서는 항상 python3로 명확히 부르는 것을 권합니다. 인터넷의 예시가 python으로 되어 있다면, 동작하지 않을 때 python3로 바꿔 보면 풀리는 경우가 많습니다.

✍️ 운영자 한마디

예전에 시스템 파이썬에 패키지를 막 깔다가 환경이 꼬인 적이 있어서, 지금은 프로젝트마다 가상환경부터 만드는 습관이 생겼습니다. 처음엔 번거로워 보여도 결국 이게 속 편하더군요.

pip 설치하기

pip은 파이썬 패키지(다른 사람이 만들어 공개한 코드 묶음)를 내려받아 설치해 주는 도구입니다. 환경에 따라 pip이 기본으로 들어 있지 않을 수 있는데, 그럴 때는 아래처럼 설치합니다.

sudo apt update
sudo apt install python3-pip

설치 후에는 보통 pip3 또는 python3 -m pip 형태로 사용합니다. 설치가 됐는지 확인하려면 아래처럼 버전을 출력해 보면 됩니다.

python3 -m pip --version

여기서 한 가지만 기억하면 좋습니다. pip으로 패키지를 시스템 전체에 마구 설치하는 것은 피하는 편이 좋다는 점입니다. 그 이유를 다음 절에서 다룹니다.

시스템 파이썬은 직접 건드리지 말 것

우분투에 이미 깔린 파이썬은 운영체제의 여러 도구가 함께 쓰는 공용 파이썬입니다. 여기에 패키지를 함부로 설치하거나 버전을 강제로 바꾸면, 파이썬과 무관해 보이던 시스템 도구까지 영향을 받아 꼬일 수 있습니다.

그래서 원칙은 단순합니다.

시스템 파이썬에 직접 이것저것 설치하지 않습니다.
내 프로젝트에 필요한 패키지는 프로젝트별 가상환경 안에 담습니다.

이 원칙만 지켜도 “파이썬을 건드렸더니 시스템이 이상해졌다”는 흔한 사고를 대부분 피할 수 있습니다.

가상환경(venv)으로 프로젝트 격리하기

가상환경은 프로젝트마다 독립된 파이썬 작업 공간을 만드는 기능입니다. 프로젝트 A의 패키지와 프로젝트 B의 패키지가 서로 섞이지 않게 칸막이를 치는 셈입니다. 파이썬에는 venv라는 표준 도구가 있어 별도 설치 없이 쓸 수 있는 경우가 많습니다.

가상환경 만들기

프로젝트 폴더 안에서 아래처럼 가상환경을 만듭니다. 여기서는 .venv라는 이름으로 만들었습니다.

python3 -m venv .venv

이 명령은 현재 폴더에 .venv라는 디렉터리를 만들고, 그 안에 프로젝트 전용 파이썬 환경을 꾸려 둡니다.

활성화와 비활성화

만든 가상환경을 “켜는” 단계가 활성화입니다.

source .venv/bin/activate

활성화되면 프롬프트 앞에 보통 (.venv) 같은 표시가 붙습니다. 이 상태에서 pip으로 설치하는 패키지는 시스템이 아니라 이 가상환경 안에만 담깁니다. 작업이 끝나면 아래로 빠져나옵니다.

deactivate

이렇게 프로젝트마다 가상환경을 따로 두면, 한 프로젝트의 패키지 버전이 다른 프로젝트를 망가뜨리는 일을 막을 수 있습니다. 가상환경 폴더(.venv)는 보통 버전 관리(git)에 올리지 않고 제외해 두는 것이 일반적입니다.

초보자가 자주 막히는 부분

python 명령이 없다고 당황 — 우분투에서는 python3가 일반적인 이름입니다. python이 안 되면 python3로 바꿔 보세요.
시스템 파이썬에 패키지를 직접 설치 — 공용 파이썬을 어지럽히면 시스템 도구까지 꼬일 수 있습니다. 가상환경 안에 설치하세요.
가상환경을 만들기만 하고 활성화를 안 함 — source .venv/bin/activate로 켜지 않으면 패키지가 엉뚱한 곳에 설치될 수 있습니다.
터미널을 새로 열면 비활성화됨 — 가상환경은 켜 둔 터미널 기준이라, 새 터미널에서는 다시 활성화해야 합니다.
버전 번호를 글마다 단정 — 깔린 파이썬 버전은 환경에 따라 다르니, 숫자를 외우기보다 python3 --version으로 직접 확인하세요.

파이썬 환경 점검 체크리스트

python3 --version 으로 이미 설치된 파이썬을 확인했다
입문 단계에서는 python 대신 python3로 부른다는 점을 안다
필요하면 python3-pip 로 pip을 설치하고 확인했다
시스템 파이썬에 직접 패키지를 설치하지 않기로 했다
python3 -m venv .venv 로 가상환경을 만들 수 있다
source .venv/bin/activate / deactivate 로 켜고 끌 수 있다

정리

우분투에는 보통 python3가 이미 들어 있으니 첫걸음은 설치가 아니라 확인입니다. 입문 단계에서는 python 대신 python3로 명확히 부르고, pip이 필요하면 python3-pip로 설치합니다. 가장 중요한 원칙은 시스템 파이썬을 직접 어지럽히지 않는 것이며, 그 답이 바로 프로젝트별 가상환경입니다. python3 -m venv로 만들고 activate로 켜는 흐름만 손에 익히면, 프로젝트가 늘어도 의존성 충돌 없이 깔끔하게 관리할 수 있습니다. 버전 같은 세부 사항은 환경마다 다르니, 단정하기보다 확인 명령과 공식 문서를 함께 활용하세요.

AI가 만든 코드를 그대로 믿지 않는 습관

Thu, 09 Jul 2026 06:05:28 GMT

AI가 내놓는 코드는 문장처럼 매끄럽고 자신감 있게 보입니다. 그래서 “이게 맞겠지” 하고 바로 실행하기 쉽습니다. 하지만 그럴듯함과 정확함은 다른 문제입니다. AI는 맥락을 일부만 알고 답하기도 하고, 의도와 다른 코드를 자연스럽게 써내기도 합니다.

이 글은 구체적인 명령 모음이 아니라, AI 결과물을 대하는 태도에 관한 이야기입니다. 핵심은 “그대로 믿지 않되, 활용은 한다”입니다.

먼저 무엇을 하는 코드인지 이해한다

검토의 출발점은 실행이 아니라 이해입니다. 받은 코드나 명령이 무엇을 읽고, 무엇을 바꾸고, 무엇을 지우는지 한 번 짚어 보세요. 모르겠으면 도구에게 “이 명령이 정확히 무엇을 하나요?”라고 다시 물어도 됩니다. 이해하지 못한 것을 실행하지 않는 것만으로도 큰 사고를 막을 수 있습니다.

✍️ 운영자 한마디

AI가 준 명령을 이해 없이 그대로 붙여 넣었다가 한 번 식겁한 뒤로는, 무슨 동작인지 먼저 읽어보는 습관이 생겼습니다. 특히 파일을 지우는 종류의 명령은 꼭 두 번 봅니다.

작은 단위로 확인한다

한 번에 수많은 파일을 바꾸는 변경을 통째로 적용하면, 무언가 잘못됐을 때 원인을 찾기 어렵습니다. 가능하면 변경을 작게 나눠 적용하고, 그때마다 의도대로 동작하는지 확인하세요. 작은 단위는 검토도 쉽고, 되돌리기도 쉽습니다.

위험한 명령은 특히 신중하게

같은 “실행”이라도 위험도는 다릅니다. 파일을 지우거나, 전체를 한꺼번에 덮어쓰거나, 외부에서 무언가를 받아 바로 실행하는 류의 명령은 특히 조심해야 합니다. 무엇을 지우는지, 되돌릴 수 있는지 확인하기 전에는 실행을 미루는 편이 안전합니다.

특히 파일을 지우는 rm 같은 명령은 한 번 더 멈춰서 봐야 합니다. 예를 들어 아래 같은 명령은 짧지만, 어떤 폴더에서 실행하느냐에 따라 지우는 대상이 완전히 달라집니다.

rm -rf build

이 명령은 build 폴더를 통째로, 되묻지 않고 지웁니다. 의도한 임시 폴더라면 괜찮지만, 위치를 착각했거나 폴더 이름이 비슷하면 원치 않는 것까지 사라질 수 있습니다. AI가 이런 명령을 제안했을 때는 “지금 어느 폴더에서, 무엇을 지우는가”를 반드시 먼저 확인하세요. 모르겠으면 실행 전에 도구에게 “이 명령이 정확히 무엇을 지우나요?”라고 되물어도 됩니다.

되돌릴 수 있게 만들어 둔다

아무리 신중해도 실수는 생깁니다. 그래서 검토만큼 중요한 것이 “되돌릴 수단”입니다. 버전관리(Git)로 변경 전 상태를 기록해 두면, 무언가 꼬여도 이전으로 되돌아갈 수 있습니다. 작업을 시작하기 전에 한 번 기록해 두고, 의미 있는 변경마다 다시 기록해 두면 “여기로 돌아가면 된다”는 지점이 생깁니다. 안전망이 있으면 더 과감하게 시도하면서도 사고를 줄일 수 있습니다.

테스트와 실행으로 검증한다

읽어서 이해하는 것과, 실제로 동작하는 것은 다른 문제입니다. 그래서 변경을 적용했다면 가능한 범위에서 직접 돌려 보는 것이 가장 확실한 검토입니다. 프로그램을 한 번 실행해 의도한 화면이나 결과가 나오는지 보고, 테스트가 있다면 테스트를 돌려 통과하는지 확인합니다. “AI가 그렇다고 했으니 맞겠지”가 아니라, 내 환경에서 실제로 그런지 눈으로 확인하는 한 단계가 오류를 크게 줄여 줍니다. 작은 단위로 바꿔 왔다면, 이 검증도 그만큼 가볍고 빠릅니다.

출처와 라이선스를 의식한다

AI가 만들어 준 코드라도, 그 안에는 특정 라이브러리나 외부 코드의 사용 방식이 섞여 있을 수 있습니다. 어떤 라이브러리를 새로 끌어다 쓰는 제안이라면, 그것이 무엇이고 어떤 라이선스를 가지는지 한 번 의식하는 편이 좋습니다. 특히 다른 사람과 공유하거나 공개하는 프로젝트라면, 출처가 불분명한 코드나 조건이 까다로운 라이선스가 섞여 들어오는 일을 피해야 뒤탈이 없습니다. 입문 단계에서 모든 라이선스를 외울 필요는 없지만, “이 코드가 어디서 왔고 써도 되는가”라는 질문을 던지는 습관만으로도 충분히 가치가 있습니다.

초보자가 자주 막히는 부분

그럴듯해 보여서 바로 실행 — 매끄러운 코드가 곧 올바른 코드는 아닙니다.
무엇을 지우는지 모르고 실행 — 삭제·덮어쓰기 명령은 한 번 더 확인해야 합니다.
변경을 통째로 적용 — 한꺼번에 바꾸면 문제의 원인을 좁히기 어렵습니다.
되돌릴 수단이 없음 — 버전관리 없이 작업하면 실수했을 때 복구가 막막합니다.
실행해 보지 않고 넘어감 — 읽어서 맞아 보여도, 실제로 돌려 보기 전에는 알 수 없습니다.
출처를 따지지 않음 — 새로 끌어온 코드·라이브러리의 출처와 라이선스를 한 번은 살펴야 합니다.

검토 습관 체크리스트

이 코드·명령이 무엇을 하는지 이해했다(모르면 다시 물었다)
큰 변경은 작은 단위로 나눠 확인했다
삭제·전체 변경 같은 위험한 명령을 따로 점검했다
버전관리로 되돌릴 수 있는 상태를 만들어 뒀다
실행하거나 테스트로 의도대로 동작하는지 확인했다
새로 들어온 코드·라이브러리의 출처·라이선스를 살폈다

정리

AI 코딩 도구는 거부할 이유가 없는 좋은 조수이지만, 판단까지 맡길 대상은 아닙니다. 무엇을 하는지 이해하고, 작게 확인하고, 위험한 명령을 가려내고, 되돌릴 수 있게 두는 네 가지만 지켜도 결과물을 훨씬 안전하게 활용할 수 있습니다. 그 바탕이 되는 기본기를 아직 다지지 않았다면, 도구를 쓰기 전 기본기 정리부터 함께 보길 권합니다.

WSL 우분투 한글·로케일·시간 깔끔하게 맞추기

Thu, 09 Jul 2026 06:05:28 GMT

WSL에 우분투를 막 설치하고 나면, 한글 파일 이름이 깨져 보이거나 시간이 윈도우와 다르게 표시되는 일이 흔합니다. 처음에는 “설치가 잘못됐나” 싶지만, 대부분은 로케일과 시간대 설정이 기본값 그대로라서 생기는 일입니다. 이 글에서는 그 문제들을 한글 로케일, 한글 표시, 시간대 순서로 하나씩 짚어 정리합니다. 한 번에 여러 가지를 바꾸기보다, 확인 → 설정 → 적용을 단계로 밟아 가는 편이 원인을 좁히기 쉽습니다.

로케일이 무엇이고 왜 한글이 깨지나

로케일(locale)은 시스템이 “어떤 언어와 문자 인코딩을 기본으로 쓸지” 정해 둔 설정입니다. 우분투를 영어 기본으로 설치하면 로케일이 영어로 잡혀 있어, 한글을 다루는 일부 상황에서 글자가 깨지거나 정렬·정규식 처리가 어긋날 수 있습니다.

여기서 중요한 두 가지가 언어(LANG) 와 인코딩(UTF-8) 입니다. 한글 자체는 UTF-8 인코딩으로 표현되는데, 시스템 기본이 C/POSIX 처럼 아스키 위주 로케일이면 한글 바이트를 글자로 해석하지 못해 깨져 보이게 됩니다.

지금 로케일 확인하기

먼저 현재 상태를 봅니다.

locale

LANG= 옆이 비어 있거나 C 또는 POSIX 로 되어 있으면, 한글을 위한 설정이 아직 없는 상태입니다. 어떤 로케일을 쓸 수 있는지(이미 생성된 목록)는 다음으로 확인합니다.

locale -a

이 목록에 ko_KR.utf8 이 보이지 않는다면, 아직 한국어 로케일이 생성되지 않은 것입니다. 다음 단계에서 만들면 됩니다.

✍️ 운영자 한마디

한글이 깨져 나올 때 글꼴 문제인지 인코딩 문제인지 구분이 안 돼 한참 엉뚱한 곳을 손댔습니다. 로케일을 제대로 잡고 나니 거짓말처럼 정리됐습니다.

한국어 로케일 만들고 적용하기

한국어 UTF-8 로케일을 생성한 뒤, 기본 언어로 지정합니다.

sudo locale-gen ko_KR.UTF-8
sudo update-locale LANG=ko_KR.UTF-8

첫 줄은 한국어 로케일 데이터를 만들어 두는 명령이고, 둘째 줄은 시스템 기본 LANG 값을 그 로케일로 바꾸는 명령입니다. update-locale 은 /etc/default/locale 파일을 손봐 다음 로그인부터 적용되게 합니다.

만약 locale-gen 단계에서 로케일이 만들어지지 않는다면, 어떤 로케일을 생성할지 고르는 설정 화면을 직접 띄워 목록에서 ko_KR.UTF-8 을 선택하는 방법도 있습니다.

sudo dpkg-reconfigure locales

적용은 세션을 새로 열어야 반영된다

설정을 바꿔도 이미 열려 있는 터미널에는 곧바로 반영되지 않습니다. 터미널을 새로 열거나, 확실히 하려면 WSL을 한 번 완전히 껐다 켭니다.

wsl.exe --shutdown

위 명령은 윈도우 쪽에서 WSL을 완전히 종료해, 다음 실행 때 설정을 새로 읽게 합니다. 다시 켠 뒤 locale 을 실행해 LANG=ko_KR.UTF-8 로 바뀌었는지 확인하세요.

영어 메시지를 유지하고 싶다면

명령 결과나 에러 메시지는 영어가 더 익숙한 경우도 많습니다. 그럴 때는 시스템 언어는 영어로 두되, 한글 입출력에 필요한 부분만 UTF-8 로 맞추는 선택도 있습니다. 예를 들어 특정 작업에서만 한국어 로케일을 임시로 쓰고 싶다면, 그 명령 앞에 환경 변수를 붙이는 방식도 가능합니다.

LANG=ko_KR.UTF-8 date

이렇게 하면 그 한 번의 실행에만 한국어 로케일이 적용되고, 전체 설정은 그대로 둡니다.

한글이 보이긴 하는데 깨질 때

로케일을 맞췄는데도 한글이 이상하게 보인다면, 원인은 보통 둘 중 하나입니다. 둘은 증상이 다르니 구분해서 봐야 합니다.

인코딩 불일치 — 글자가 í•œê¸€ 처럼 다른 문자가 섞여 깨져 보이는 경우입니다. 거의 모든 현대 리눅스 환경은 UTF-8 을 쓰므로, 외부에서 가져온 파일이 EUC-KR 같은 다른 인코딩일 때 주로 생깁니다.
터미널 글꼴 — 한글이 □ 같은 빈 네모로 보이면 인코딩보다 글꼴 문제일 때가 많습니다. 시스템은 한글을 제대로 처리하고 있는데, 터미널이 그 글자를 그릴 글꼴이 없는 상태입니다.

글꼴 문제는 리눅스가 아니라 터미널 프로그램 쪽 설정에서 풉니다. Windows Terminal 같은 프로그램의 설정에서 한글을 지원하는 고정폭(monospace) 글꼴로 바꾸면 대부분 해결됩니다. 인코딩이 의심되면, 가져온 파일이 UTF-8 인지 먼저 확인하는 습관이 도움이 됩니다.

file 파일이름.txt   # 텍스트 인코딩 힌트를 보여 줍니다

시간대(타임존) 맞추기

WSL 우분투의 시간이 윈도우와 다르게 보이면 타임존이 기본값(UTC 등)으로 잡혀 있는 경우가 많습니다. 현재 시간 설정은 다음으로 확인합니다.

timedatectl

여기서 Time zone 항목이 Etc/UTC 등으로 되어 있다면 한국 시간과 어긋나 보입니다. 서울 시간대로 바꾸는 가장 간단한 방법은 timedatectl 로 직접 지정하는 것입니다.

sudo timedatectl set-timezone Asia/Seoul

환경에 따라 위 명령이 동작하지 않으면, tzdata 설정 화면을 다시 띄워 목록에서 Asia → Seoul 을 고르는 방법을 씁니다.

sudo dpkg-reconfigure tzdata

설정 후 date 명령으로 시간이 한국 시간(KST)으로 나오는지 확인하면 됩니다.

date

윈도우와 시간이 어긋나 보일 때

WSL을 오래 켜 두거나 윈도우가 절전·최대 절전에서 깨어난 뒤, WSL 안의 시계만 살짝 어긋나 보이는 경우가 있습니다. 이는 타임존이 아니라 가상 환경의 시계가 윈도우와 다시 동기화되지 못한 상황일 수 있습니다. 이럴 때는 무거운 설정을 손대기 전에, WSL을 한 번 껐다 켜서 시계를 다시 맞추는 것부터 시도해 보세요.

wsl.exe --shutdown

시계 어긋남은 단순히 보기 불편한 데서 끝나지 않고, 뒤에서 다룰 네트워크·인증 문제로 이어지기도 하니 가볍게 넘기지 않는 편이 좋습니다.

초보자가 자주 막히는 부분

설정을 바꿨는데 그대로다 — 로케일은 터미널을 새로 열거나 WSL을 재시작해야 적용됩니다. wsl.exe --shutdown 후 다시 켜 보세요.
로케일과 글꼴 문제를 혼동 — 한글이 깨지는 것과 네모(□)로 보이는 것은 원인이 다릅니다. 네모는 보통 글꼴 문제입니다.
locale -a 에 ko_KR 이 없는데 LANG만 바꿈 — 로케일을 생성하지 않고 LANG 만 지정하면 오히려 경고가 납니다. locale-gen 으로 먼저 만들어야 합니다.
timedatectl 이 안 먹힘 — 일부 WSL 환경에서는 dpkg-reconfigure tzdata 쪽이 더 확실하게 동작합니다.
영어 메시지가 사라져 당황 — 로케일을 한국어로 바꾸면 일부 안내가 한글로 나옵니다. 영어가 익숙하면 LANG 을 영어로 두는 선택도 가능합니다.

한글·시간 설정 체크리스트

locale 로 현재 LANG 값을 확인했다
locale -a 에 ko_KR.utf8 이 있는지 확인했다
sudo locale-gen ko_KR.UTF-8 로 한국어 로케일을 만들었다
sudo update-locale LANG=ko_KR.UTF-8 로 기본 언어를 지정했다
WSL을 재시작해 설정을 적용했다
timedatectl 또는 tzdata 로 시간대를 Asia/Seoul 로 맞췄다

정리

WSL 우분투의 한글과 시간 문제는 설치가 잘못된 것이 아니라, 기본 설정이 한국 환경에 맞춰져 있지 않아서 생깁니다. 로케일을 한국어 UTF-8 로 만들고, 글꼴까지 한 번 점검하고, 타임존을 서울로 맞추면 이후 작업이 한결 깔끔해집니다. 한 번에 다 바꾸기보다 확인 → 설정 → 적용을 순서대로 밟아 두면, 다음에 비슷한 문제를 만나도 침착하게 풀어갈 수 있습니다. 설정을 마쳤다면 이제 환경을 손에 익히면서 다음 작업으로 넘어가 보세요.

VS Code와 WSL 연결해서 쓰기

Thu, 09 Jul 2026 06:05:28 GMT

WSL로 우분투를 켜고 나면 곧 한 가지 고민이 생깁니다. 코드를 어떻게 편집하지? 터미널 안의 편집기에 익숙하지 않다면, 평소 쓰던 윈도우 에디터로 리눅스 파일을 다룰 수 있으면 좋겠다는 생각이 들기 마련입니다. VS Code와 WSL을 연결하면 바로 그 일이 가능합니다. 리눅스 안의 파일을 윈도우의 VS Code 창에서 그대로 열고 고칠 수 있습니다.

이 글에서는 그 연결이 어떤 원리인지 짚고, 실제로 어떻게 이어 쓰는지, 그리고 입문자가 놓치기 쉬운 “어디에 파일을 둘 것인가”와 “확장이 어느 쪽에 설치되는가”까지 살펴봅니다.

어떤 방식으로 연결되는가

핵심은 VS Code가 “리눅스 쪽에 발을 들여놓는다”는 점입니다. VS Code 본체(화면)는 윈도우에서 돌아가지만, 파일을 읽고 명령을 실행하는 부분은 WSL의 리눅스 환경에서 동작합니다. 그래서 윈도우의 익숙한 화면을 쓰면서도, 다루는 대상은 리눅스 파일이 됩니다.

에디터 화면: 윈도우의 VS Code
파일과 명령 실행: WSL 안의 리눅스
둘을 이어 주는 다리: WSL 확장

이 구조 덕분에 윈도우의 보기 좋은 편집 환경과 리눅스의 실제 작업 환경을 동시에 누릴 수 있습니다.

WSL 확장이라는 다리

이 연결을 담당하는 것이 VS Code의 WSL 확장입니다. 확장은 VS Code 안의 확장 탭에서 검색해 설치할 수 있고, 한 번 설치해 두면 이후로는 WSL 환경에 손쉽게 연결할 수 있습니다. 확장을 통해 연결하면 VS Code 창 한쪽에 현재 어떤 환경에 연결되어 있는지가 표시됩니다.

✍️ 운영자 한마디

처음엔 윈도우 쪽 에디터로 리눅스 파일을 열어 편집했는데 뭔가 자꾸 어긋났습니다. WSL에 직접 연결해 code . 로 여는 방식을 알고 나서야 깔끔해졌습니다.

code . 명령으로 폴더 열기

가장 자주 쓰는 흐름은 WSL 터미널에서 직접 VS Code를 여는 것입니다. 작업할 폴더로 이동한 뒤 아래 명령을 실행합니다.

code .

여기서 .은 “현재 폴더”를 뜻합니다. 이 명령을 실행하면 지금 위치한 리눅스 폴더가 VS Code 창으로 열리고, 그 창은 자동으로 WSL 환경에 연결된 상태가 됩니다. 특정 파일만 열고 싶다면 점 대신 파일 이름을 적으면 됩니다.

code 파일이름.txt

원격 연결 표시 확인하기

VS Code가 지금 WSL에 연결되어 있는지는 창 왼쪽 아래 구석의 표시로 확인할 수 있습니다. 여기에 “WSL”과 배포판 이름 같은 안내가 보이면, 지금 다루는 파일이 리눅스 쪽 파일이라는 뜻입니다.

이 표시를 확인하는 습관이 중요한 이유가 있습니다. 윈도우 파일을 편집하는 창과 리눅스 파일을 편집하는 창은 겉모습이 거의 같아서, 표시를 보지 않으면 지금 어느 쪽을 고치고 있는지 헷갈리기 쉽기 때문입니다.

리눅스 홈에서 작업해야 하는 이유

VS Code에서는 윈도우 폴더도 열 수 있지만, WSL로 본격적인 작업을 한다면 파일을 리눅스 홈 디렉터리 안에 두는 편이 좋습니다. WSL에서는 윈도우 쪽 폴더에 접근할 때 두 운영체제 사이를 오가는 비용이 생겨, 파일이 많아지면 눈에 띄게 느려질 수 있습니다. 반면 리눅스 홈 안의 파일은 리눅스가 자기 영역에서 바로 다루므로 빠르고 호환성 문제도 적습니다.

정리하면, 프로젝트 폴더는 리눅스 홈 아래에 만들고 그 안에서 code . 로 여는 흐름을 기본으로 삼는 것이 좋습니다.

확장은 어느 쪽에 설치되는가

WSL에 연결한 뒤 확장을 설치하다 보면, 어떤 확장은 “WSL에 설치”하라는 안내가 나옵니다. 이는 그 확장이 화면만 꾸미는 게 아니라 파일이나 명령을 직접 다루기 때문입니다.

테마처럼 화면에만 관여하는 확장: 윈도우 쪽에서 동작
언어 도구·포매터처럼 파일과 명령을 다루는 확장: WSL(리눅스) 쪽에 설치해야 제대로 동작

VS Code가 이 구분을 안내해 주므로, 안내에 따라 WSL 쪽에 설치하면 됩니다. 같은 확장을 환경마다 따로 관리한다고 생각하면 이해하기 쉽습니다.

통합 터미널 함께 쓰기

VS Code 안에는 터미널이 내장되어 있습니다. WSL에 연결된 상태에서 이 통합 터미널을 열면, 그 터미널은 리눅스 셸로 이어집니다. 즉 편집은 위쪽 에디터에서, 명령 실행은 아래쪽 터미널에서 한 화면 안에 처리할 수 있습니다. 파일을 고치고 바로 명령을 돌려 보는 과정을 창을 오갈 필요 없이 진행할 수 있어 작업 흐름이 한결 매끄러워집니다.

초보자가 자주 막히는 부분

리눅스에 또 에디터를 설치하려 함 — VS Code는 윈도우에 한 번만 깔면 되고, WSL 확장이 연결을 맡습니다.
연결 상태를 확인하지 않음 — 왼쪽 아래 원격 연결 표시를 보지 않으면, 윈도우 파일을 다루는지 리눅스 파일을 다루는지 헷갈릴 수 있습니다.
윈도우 폴더에 프로젝트를 둠 — 파일이 많아지면 느려질 수 있어, 리눅스 홈 안에 두는 편이 좋습니다.
확장이 안 먹는다고 오해 — 파일·명령을 다루는 확장은 WSL 쪽에 설치해야 동작합니다. 안내를 따라 설치하세요.
code 명령이 처음에 인식되지 않음 — 연동이 자리 잡기 전에는 명령이 안 먹을 수 있어, VS Code로 한 번 WSL에 연결한 뒤 다시 시도하면 도움이 됩니다.

연결 점검 체크리스트

윈도우에 VS Code가 설치되어 있다
VS Code에 WSL 확장을 설치했다
WSL 터미널에서 code . 로 폴더를 열어 봤다
창 왼쪽 아래에서 WSL 원격 연결 표시를 확인했다
프로젝트 파일을 리눅스 홈 안에 두었다
VS Code 통합 터미널이 리눅스 셸로 연결되는 것을 확인했다

정리

VS Code와 WSL을 연결하면 윈도우의 익숙한 편집 환경과 리눅스 작업 환경을 한자리에서 누릴 수 있습니다. WSL 확장을 다리로 삼고, code . 한 줄로 폴더를 열고, 왼쪽 아래 연결 표시를 확인하며, 통합 터미널에서 명령까지 처리하는 흐름만 익히면 됩니다. 파일은 리눅스 홈 안에 두고, 확장은 안내에 따라 WSL 쪽에 설치한다는 두 가지 원칙만 기억하면 혼선을 크게 줄일 수 있습니다. 환경과 버전에 따라 세부 화면은 조금씩 다를 수 있으니, 연결 상태 표시를 늘 한 번씩 확인하는 습관을 들이세요.

윈도우와 WSL 리눅스 사이에서 파일 안전하게 공유하기

Thu, 09 Jul 2026 06:05:28 GMT

WSL의 가장 큰 매력 중 하나는 윈도우와 리눅스가 서로의 파일을 볼 수 있다는 점입니다. 윈도우에서 받은 파일을 리눅스에서 바로 열고, 리눅스에서 만든 결과물을 탐색기로 꺼내 쓸 수 있습니다. 그런데 이 편리함을 아무 생각 없이 쓰다 보면 “왜 이렇게 느리지”, “왜 권한 오류가 나지”, “왜 스크립트가 안 돌지” 같은 문제에 부딪힙니다. 대부분 파일을 어디에 두고 어디서 작업하느냐에서 갈리는 문제입니다.

이 글에서는 양방향 접근 경로를 먼저 정리하고, 어디서 작업해야 빠른지, 그리고 권한과 줄바꿈에서 생기는 함정을 어떻게 피하는지 순서대로 다룹니다.

리눅스에서 윈도우 파일에 접근하기: /mnt/c

WSL 안에서 윈도우 드라이브는 /mnt 아래에 연결됩니다. C 드라이브는 /mnt/c, D 드라이브는 /mnt/d처럼 매핑됩니다. 예를 들어 윈도우의 C:\Users\내이름\Downloads 폴더는 리눅스에서 이렇게 접근합니다.

cd /mnt/c/Users/내이름/Downloads
ls

윈도우 경로의 역슬래시(\)는 리눅스에서 슬래시(/)로 바뀌고, 드라이브 문자는 소문자가 됩니다. 윈도우에서 내려받은 파일을 리눅스 도구로 잠깐 열어보는 정도라면 이 경로가 편리합니다.

윈도우에서 리눅스 파일에 접근하기: \wsl$

반대 방향도 됩니다. 윈도우 탐색기 주소창에 아래를 입력하면 설치된 WSL 배포판들의 파일 시스템이 보입니다.

\\wsl$

최신 환경에서는 다음 주소도 같은 역할을 합니다.

\\wsl.localhost

여기서 배포판(예: Ubuntu)을 열고 들어가면 리눅스의 홈 디렉터리까지 탐색기로 둘러볼 수 있습니다. 리눅스에서 만든 결과 파일을 윈도우 프로그램으로 열거나, 탐색기로 끌어다 옮길 때 유용합니다. 즐겨찾기에 고정해 두면 매번 주소를 치지 않아도 됩니다.

어디서 작업해야 빠른가: 파일의 “집”을 정하라

여기서 가장 중요한 원칙이 나옵니다. 리눅스에서 빌드·실행하는 프로젝트는 리눅스 홈(~) 안에 두세요. WSL2는 리눅스 자체 파일 시스템에서의 작업이 빠르고, /mnt/c 같은 윈도우 영역을 넘나드는 작업은 상대적으로 느립니다. 작은 파일 하나를 여닫는 정도는 차이를 못 느끼지만, 수많은 파일을 다루는 빌드나 패키지 설치에서는 체감 속도가 크게 벌어집니다.

그래서 보통 이렇게 정리합니다.

리눅스에서 코드를 돌리는 프로젝트 → 리눅스 홈(예: ~/projects/내앱)에 둔다.
윈도우 프로그램이 주로 다루는 문서·자료 → 윈도우 폴더에 둔다.
잠깐 옮기거나 확인할 때만 /mnt/c ↔ \\wsl$를 오간다.

mkdir -p ~/projects
cd ~/projects

✍️ 운영자 한마디

처음엔 윈도우 폴더 쪽에 프로젝트를 두고 작업했는데 이상하게 굼떠서 한참 헤맸습니다. 리눅스 홈 안으로 옮기고 나서야 ‘아, 그래서 파일을 어디에 두느냐가 중요하구나’ 하고 체감했습니다.

줄바꿈(CRLF) 주의

윈도우와 리눅스는 줄바꿈을 표현하는 방식이 다릅니다. 윈도우는 줄 끝에 보이지 않는 문자 두 개(CRLF)를, 리눅스는 하나(LF)를 씁니다. 윈도우에서 편집한 셸 스크립트를 리눅스에서 실행했을 때 이상한 오류가 난다면, 줄바꿈 문제일 때가 많습니다.

대표적으로 스크립트 첫 줄(#!/bin/bash 같은)이 CRLF로 끝나면 “명령을 찾을 수 없다”는 식의 모호한 오류가 납니다. 이때는 줄바꿈을 LF로 바꿔 주면 됩니다.

sudo apt install dos2unix
dos2unix myscript.sh

편집기를 쓴다면 줄바꿈을 LF로 저장하도록 설정하고, Git을 쓴다면 줄바꿈 자동 변환 설정을 점검해 두는 것이 근본적인 예방책입니다.

권한과 큰 파일 충돌 주의

윈도우와 리눅스는 파일 권한을 다루는 방식도 다릅니다. /mnt/c 아래 윈도우 파일에는 리눅스식 세밀한 권한(읽기·쓰기·실행 비트)이 그대로 적용되지 않을 수 있어, 권한에 민감한 도구가 경고나 오류를 낼 때가 있습니다. 반대로 탐색기에서 \\wsl$로 들어가 리눅스의 시스템 파일을 직접 수정하면 권한 구조가 꼬일 수 있습니다.

그래서 다음을 기억해 두면 충돌을 크게 줄일 수 있습니다.

권한이 중요한 작업(실행 비트, 소유권 등)은 해당 파일을 리눅스 홈에 두고 리눅스 터미널에서 처리한다.
탐색기로는 일반 작업 파일만 다루고, 리눅스 시스템 영역은 손대지 않는다.
용량이 매우 큰 파일을 양쪽 경로를 넘나들며 반복 복사하면 느리고 디스크도 두 배로 쓰게 되니, 작업할 쪽에 한 번만 두고 거기서 다룬다.

초보자가 자주 막히는 부분

프로젝트를 /mnt/c에 두고 “WSL이 느리다”고 오해 — 느린 건 WSL이 아니라 윈도우 영역을 넘나드는 파일 접근일 때가 많습니다. 리눅스 홈으로 옮기면 대개 해결됩니다.
윈도우 편집기로 저장한 스크립트가 안 돎 — 줄바꿈(CRLF) 문제일 가능성이 큽니다.
권한 오류가 자꾸 난다 — 권한이 중요한 파일을 /mnt/c에 두고 있는지 확인하세요.
탐색기로 리눅스 시스템 파일을 직접 수정 — 일반 작업 파일만 다루고 시스템 영역은 터미널에서 처리하세요.
큰 파일을 양쪽으로 계속 복사 — 작업할 쪽에 한 번만 두는 편이 빠르고 안전합니다.

파일 공유 점검 체크리스트

리눅스에서 돌리는 프로젝트를 리눅스 홈(~)에 두었다
윈도우 파일은 /mnt/c, 리눅스 파일은 \\wsl$ 로 접근하는 법을 안다
스크립트 줄바꿈을 LF로 맞췄거나 변환 방법(dos2unix)을 안다
권한이 중요한 작업은 리눅스 쪽에서 처리하기로 했다
큰 파일을 양쪽 경로로 반복 복사하지 않기로 했다

정리

WSL의 파일 공유는 강력하지만, “어디에 두고 어디서 작업하느냐”를 정해 두지 않으면 속도와 권한, 줄바꿈에서 시간을 잃기 쉽습니다. 핵심은 단순합니다. 리눅스에서 돌리는 것은 리눅스 홈에 두고, 양쪽을 오갈 때만 /mnt/c와 \\wsl$를 쓰며, 줄바꿈과 권한 차이를 미리 의식하는 것입니다. 이 원칙만 지켜도 대부분의 흔한 충돌은 피할 수 있습니다.

WSL 설치가 막힐 때, 점검 순서대로 풀어가기

Thu, 09 Jul 2026 06:05:28 GMT

설치 안내대로 따라 했는데 중간에 오류가 나거나 진행이 멈추면, 입문자 입장에서는 어디가 문제인지 가늠하기 어렵습니다. 이럴 때 필요한 것은 더 많은 검색이 아니라 점검 순서입니다. 원인이 될 만한 항목을 위에서부터 하나씩 지워 나가면, 대부분의 문제는 몇 단계 안에서 좁혀집니다. 아래 순서는 위쪽일수록 더 흔하고, 더 근본적인 원인입니다.

먼저: 한 번에 하나씩만 바꾼다

문제 해결의 가장 흔한 실수는 "안 되니까 이것저것 동시에 바꾸는 것"입니다. 그러면 무엇이 원인이었는지 알 수 없게 됩니다. 한 가지를 바꾸고 다시 시도하고, 그래도 안 되면 되돌린 뒤 다음 항목으로 넘어가세요. 변경 → 시도 → 결과 확인. 이 작은 리듬을 지키는 것만으로도 헤매는 시간이 크게 줄어듭니다.

또 하나, 오류 메시지를 끝까지 읽는 습관을 들이세요. 메시지에는 원인이나 다음 행동의 힌트가 적혀 있는 경우가 많습니다. 메시지 전문을 그대로 검색하면, 짐작으로 손대는 것보다 정확한 단서를 얻습니다.

점검 1 — 가상화가 켜져 있는가

WSL2는 가벼운 가상화를 사용합니다. 이 기능이 꺼져 있으면 설치가 끝까지 진행되지 않습니다. 작업 관리자의 성능 탭에서 가상화 항목이 "사용"으로 표시되는지 먼저 확인하세요. 꺼져 있다면 메인보드 펌웨어(BIOS/UEFI) 설정에서 가상화 옵션을 켜야 할 수 있습니다.

가상화 옵션의 이름은 제조사마다 다릅니다. 인텔은 보통 VT-x(또는 Virtualization Technology), AMD는 SVM(또는 AMD-V)으로 표기됩니다. 또한 일부 보안 소프트웨어나 다른 가상화 프로그램이 가상화 자원을 점유해 충돌하는 경우도 있으니, 설정을 켰는데도 안 된다면 그쪽도 의심해 보세요.

✍️ 운영자 한마디

설치가 막혔을 때 조급한 마음에 이것저것 동시에 건드렸다가, 정작 뭐가 원인이었는지 못 찾은 적이 있습니다. 한 번에 하나씩 바꾸는 습관을 들이고 나서야 문제가 눈에 들어오더군요.

점검 2 — 필요한 윈도우 기능이 켜져 있는가

WSL은 몇 가지 윈도우 선택 기능에 의존합니다. 최신 버전에서는 wsl --install이 이를 자동으로 켜주지만, 환경에 따라 수동으로 활성화해야 할 때가 있습니다. "Windows 기능 켜기/끄기" 화면에서 관련 기능이 체크되어 있는지 확인하세요. 기능을 켠 뒤에는 반드시 재부팅하고 다시 시도해야 합니다. 재부팅을 건너뛰면 분명히 켰는데도 적용이 안 된 것처럼 보입니다.

점검 3 — 윈도우가 최신 상태인가

명령 자체가 "알 수 없는 명령"으로 인식된다면 윈도우 버전이 오래된 경우가 많습니다. 윈도우 업데이트를 끝까지 적용한 뒤 다시 시도해 보세요. 업데이트는 한 번에 끝나지 않고, 적용 후 재부팅하면 또 다른 업데이트가 줄지어 나오기도 합니다. 더 이상 새 업데이트가 없을 때까지 반복하는 것이 안전합니다.

점검 4 — 배포판 내려받기가 멈추는가

설치는 시작됐는데 우분투 내려받기에서 멈춘다면 네트워크나 일시적인 서버 문제일 수 있습니다. 잠시 후 다시 시도하거나, 설치 가능한 목록을 확인한 뒤 배포판을 명시적으로 지정해 설치하는 방법도 있습니다.

wsl --list --online        # 설치 가능한 배포판 목록 확인
wsl --install -d Ubuntu    # 배포판을 직접 지정해 설치

사내망이나 프록시 환경에서는 내려받기가 자주 막힙니다. 다른 네트워크(예: 일반 가정망)에서 시도하면 원인이 네트워크 쪽인지 빠르게 가려낼 수 있습니다.

점검 5 — 그래도 안 되면 상태를 확인한다

현재 WSL이 어떤 상태인지 확인하면 다음 단서를 얻을 수 있습니다. 기본 버전이 WSL2로 잡혀 있는지, 커널 버전은 무엇인지 등을 보여 줍니다.

wsl --status     # 기본 배포판·버전 등 현재 상태
wsl --version    # WSL 및 커널 버전 정보

여기서 나오는 정보를 바탕으로 검색하면, 막연히 오류 메시지만 검색할 때보다 훨씬 정확한 해결책을 찾게 됩니다.

점검 6 — 한번 완전히 내렸다가 다시 시도한다

설정은 맞는 것 같은데 동작이 어딘가 꼬인 느낌이라면, WSL을 완전히 종료한 뒤 다시 시작해 보세요. 백그라운드에 남아 있던 상태가 정리되면서 풀리는 경우가 있습니다.

wsl --shutdown   # 실행 중인 모든 배포판과 WSL을 종료

이 명령은 실행 중인 작업을 모두 끝내므로, 저장하지 않은 작업이 있다면 먼저 정리한 뒤 실행하세요. 종료 후 잠시 기다렸다가 다시 시도하면 됩니다.

초보자가 자주 막히는 부분

오류 메시지를 끝까지 읽지 않음 — 메시지 안에 이미 원인이 적혀 있는 경우가 많습니다.
재부팅을 생략 — 기능을 켜거나 업데이트한 뒤에는 재부팅이 필요합니다.
여러 해결책을 동시에 적용 — 무엇이 효과가 있었는지 알 수 없게 됩니다.
관리자 권한 없이 실행 — 일부 단계는 관리자 권한 터미널이 필요합니다.
프록시·사내망을 의심하지 않음 — 내려받기 멈춤의 흔한 원인입니다.

문제 해결 체크리스트

한 번에 한 가지만 바꾸며 시도하고 있다
가상화가 '사용' 상태인지 확인했다
윈도우 기능을 켠 뒤 재부팅했다
윈도우 업데이트를 끝까지 적용했다
wsl --status 로 현재 상태를 확인했다
막히면 wsl --shutdown 후 다시 시도해 봤다

정리

설치 문제는 대부분 가상화, 윈도우 기능, 업데이트 중 하나에서 비롯됩니다. 당황해서 여기저기 손대기보다, 위에서부터 한 항목씩 점검하면 원인을 빠르게 좁힐 수 있습니다. 점검해도 풀리지 않을 때는 wsl --status로 상태를 확인하고, wsl --shutdown으로 한번 완전히 내렸다가 다시 시도하세요. 이 점검 순서를 몸에 익혀 두면 앞으로 다른 도구를 설치할 때도 같은 방식으로 침착하게 풀어갈 수 있습니다.

WSL1·WSL2·가상머신·듀얼부팅, 입문자는 무엇을 고를까

Thu, 09 Jul 2026 06:05:28 GMT

리눅스를 써보려고 검색하면 WSL, 가상머신, 듀얼부팅이라는 말이 동시에 쏟아집니다. 게다가 WSL 안에서도 1과 2로 나뉜다는 이야기까지 들으면 더 막막해집니다. 이들은 모두 “윈도우 컴퓨터에서 리눅스를 쓰는 방법”이지만, 작동 방식과 부담이 꽤 다릅니다. 처음부터 완벽한 선택을 하려고 애쓰기보다, 각 방식이 무엇을 대가로 무엇을 주는지 이해하는 편이 빠릅니다.

큰 그림: 네 가지 방식의 기본 개념

방식	한 줄 설명	재부팅	자원 부담
WSL1	리눅스 명령을 윈도우가 번역해 실행	없음	낮음
WSL2	윈도우 안에서 진짜 리눅스 커널을 가상화로 실행	없음	낮음
가상머신	윈도우 위에 가상의 컴퓨터를 통째로 띄움	없음	중간~높음
듀얼부팅	부팅 때 윈도우/리눅스 중 선택	필요	없음(전용)

먼저 같은 “WSL”이라도 1세대와 2세대가 어떻게 다른지부터 짚고, 그다음 가상머신·듀얼부팅과 비교하겠습니다.

WSL1 vs WSL2 — 같은 이름, 다른 속

WSL1과 WSL2는 둘 다 윈도우 안에서 리눅스를 켜지만, 내부 작동 원리가 다릅니다. WSL1은 리눅스의 시스템 호출을 윈도우가 그때그때 번역해서 처리합니다. 진짜 리눅스 커널은 없습니다. 반면 WSL2는 가벼운 가상화 위에서 실제 리눅스 커널을 돌립니다. 이 차이가 호환성과 성능, 네트워킹에서 갈립니다.

항목	WSL1	WSL2
리눅스 커널	없음(윈도우가 번역)	있음(실제 커널)
시스템콜 호환성	제한적	높음
리눅스 홈 안 파일 작업	보통	빠름
윈도우 파일(/mnt/c) 작업	빠름	상대적으로 느림
네트워킹 방식	윈도우와 동일하게 공유	별도 가상 네트워크 개념

정리하면, 리눅스 프로젝트를 리눅스 홈 안에 두고 개발하거나 도커처럼 커널 기능이 필요한 도구를 쓸 때는 WSL2가 유리합니다. 반대로 윈도우 쪽 폴더(/mnt/c/...)에 있는 파일을 아주 빈번하게 직접 다루는 작업이라면 WSL1이 더 빠르게 느껴질 수 있습니다. 네트워킹도 차이가 있는데, WSL1은 윈도우와 네트워크를 사실상 그대로 공유하는 반면, WSL2는 별도의 가상 네트워크를 통해 동작합니다. 그래서 WSL2에서 띄운 서버에 윈도우 브라우저로 접속하는 식의 상황에서는 주소를 어떻게 잡는지 한 번씩 헷갈릴 수 있는데, 대부분은 기본 설정으로도 잘 동작합니다.

다만 입문자라면 기본값인 WSL2로 시작하고, 필요할 때 배포판별로 버전을 바꾸는 정도면 충분합니다. 어떤 배포판이 WSL 몇 버전으로 동작 중인지는 wsl --list --verbose로 확인할 수 있고, 버전 전환은 wsl --set-version 같은 명령으로 합니다. 다만 옵션의 정확한 형식과 변환에 걸리는 시간은 환경마다 다를 수 있으니, 처음 전환할 때는 공식 문서를 확인하고 진행하세요. 한 번 정한 뒤에는 굳이 자주 바꿀 일이 많지 않습니다.

✍️ 운영자 한마디

예전엔 뭐 5년전만해도 듀얼부팅을 많이 썼던것 같은데, 최근에 다시 개발을 진행해보니 그냥 wsl2 쓰면 되겠더라구요. 윈도우 사용자이시라면 그냥 wsl2 쓰는게 제일 편합니다. 아니면 서버PC를 리눅스로 따로 두셔도 되구요.

WSL(1·2) — 가장 부담이 적은 출발점

WSL은 윈도우를 그대로 둔 채 리눅스를 켜기 때문에 설치가 간단하고, 윈도우 파일과 리눅스를 자유롭게 오갈 수 있습니다. 코드를 작성하고 명령줄 도구를 익히는 입문 단계에는 대부분 WSL로 충분하며, 그중에서도 WSL2가 기본 권장입니다.

다만 그래픽 위주의 리눅스 데스크톱 환경을 그대로 체험하려는 목적에는 가상머신만큼 매끄럽지 않을 수 있습니다.

가상머신 — 통째로 격리된 실험실

가상머신은 윈도우 위에 별도의 컴퓨터를 통째로 만드는 방식입니다. 리눅스 데스크톱 화면을 그대로 띄울 수 있고, 환경을 망가뜨려도 윈도우에는 영향이 없어 실험에 좋습니다. 대신 메모리와 디스크를 더 많이 쓰고, 체감 속도가 느릴 수 있습니다.

듀얼부팅 — 성능은 최고, 대신 번거로움

듀얼부팅은 디스크를 나눠 윈도우와 리눅스를 각각 설치하고, 부팅할 때 무엇을 켤지 고르는 방식입니다. 리눅스가 하드웨어를 직접 쓰기 때문에 성능이 가장 좋습니다. 그러나 파티션을 나누는 과정에서 실수하면 위험할 수 있고, 윈도우와 리눅스를 오갈 때마다 재부팅해야 합니다.

상황별 추천

명령줄과 개발 도구를 익히고 싶다 → WSL2
윈도우 폴더의 파일을 아주 자주 직접 다룬다 → WSL1도 고려
도커 등 커널 기능이 필요한 도구를 쓴다 → WSL2
리눅스 데스크톱을 통째로 체험하거나 환경을 마음껏 망가뜨려 보고 싶다 → 가상머신
리눅스를 주력으로 쓰며 성능이 가장 중요하다 → 듀얼부팅

초보자가 자주 하는 오해

“하나를 고르면 못 바꾼다” — 네 방식은 공존할 수 있고, WSL은 1·2 사이 전환도 됩니다.
“WSL1과 WSL2는 그냥 버전 숫자 차이” — 내부 작동 원리가 달라 성능·호환성 특성이 갈립니다.
“듀얼부팅이 제일 좋다니까 처음부터 그걸로” — 입문 단계에서 파티션 작업은 위험 대비 이득이 적습니다.
“가상머신이 곧 WSL2” — 둘 다 가상화를 쓰지만 사용 경험과 목적이 다릅니다.

선택 점검 체크리스트

지금 나의 목적이 ‘개발 도구·명령줄 학습’인지 ‘데스크톱 체험’인지 구분했다
리눅스 홈에서 작업할지, 윈도우 폴더에서 작업할지 따져 WSL2/WSL1을 가늠했다
내 컴퓨터의 메모리·디스크 여유를 확인했다
처음에는 되돌리기 쉬운 방식(WSL2)부터 시도하기로 했다

정리

정답은 상황에 따라 다르지만, 대부분의 입문자에게는 WSL2가 가장 부담 없는 출발점입니다. WSL1·WSL2의 차이는 “리눅스 홈에서 작업할 것인가, 윈도우 폴더를 자주 건드릴 것인가”로 기억해 두면 충분합니다. 일단 가볍게 시작해 명령줄에 익숙해진 뒤, 부족함을 느끼는 순간 다른 방식을 더해도 늦지 않습니다.

WSL2 처음 설치하기: 윈도우에서 우분투 켜기

Thu, 09 Jul 2026 06:05:28 GMT

“리눅스를 한번 써보라”는 말을 들으면 보통 두 가지 벽에 부딪힙니다. 윈도우를 지우고 새로 깔아야 하나, 아니면 컴퓨터를 한 대 더 사야 하나. WSL2는 이 두 가지를 모두 피하게 해주는 선택지입니다. 윈도우를 그대로 둔 채, 그 안에서 우분투 리눅스를 하나의 앱처럼 켜는 방식이기 때문입니다.

이 글에서는 WSL이 무엇인지 짧게 짚은 뒤, 설치 전에 확인할 것, 실제 설치 명령, 첫 실행과 상태 확인, 그리고 안전한 종료까지를 순서대로 따라갑니다. 명령은 모두 한 번씩 직접 입력해 보는 것을 권합니다.

WSL2가 정확히 무엇인가

WSL은 Windows Subsystem for Linux의 줄임말입니다. 이름 그대로 “윈도우 안에 들어간 리눅스 환경”입니다. WSL2는 그중 2세대 방식으로, 가벼운 가상화를 이용해 진짜 리눅스 커널을 윈도우 위에서 돌립니다. 1세대인 WSL1이 리눅스 명령을 윈도우가 흉내 내는 방식이었다면, WSL2는 실제 커널을 띄우기 때문에 호환성과 성능이 더 좋습니다.

핵심만 정리하면 이렇습니다.

윈도우는 그대로 두고, 리눅스를 별도 앱처럼 켭니다.
듀얼부팅처럼 재부팅할 필요가 없습니다.
윈도우 탐색기에서 리눅스 파일을 볼 수 있고, 리눅스에서도 윈도우 파일에 접근할 수 있습니다.

✍️ 운영자 한마디

솔직히 처음엔 ‘리눅스 꼭 설치해야하나? 싶었었는데, AI 툴들을 사용하면서 AI 툴들이 빠르게 개발되고있는데 윈도우 환경은 항상 늦게 개발이 되더라고요. 그래서 가장 먼저 AI 툴을 활용해보기 위해서는 리눅스 환경이 필수라고 생각했습니다.

설치 전에 확인할 것

설치 자체는 명령 한 줄이지만, 시작 전에 세 가지만 확인하면 시행착오를 크게 줄일 수 있습니다.

윈도우 버전과 업데이트

비교적 최신 버전의 윈도우라면 별도 설정 없이 wsl --install 한 줄로 끝납니다. 너무 오래된 버전에서는 이 명령이 동작하지 않을 수 있으니, 우선 윈도우 업데이트를 한 번 확인해 두는 편이 좋습니다. 정확한 최소 요구 버전은 시기에 따라 달라질 수 있으므로, 애매하면 마이크로소프트 공식 문서를 확인하는 것을 권합니다.

가상화·윈도우 기능

WSL2는 가벼운 가상화를 사용합니다. 대부분의 최신 PC에서는 기본적으로 켜져 있어 따로 손댈 필요가 없습니다. 다만 일부 환경에서는 BIOS/UEFI 설정에서 가상화 기능이 꺼져 있을 수 있는데, 이 경우 설치 후 실행 단계에서 오류가 날 수 있습니다. 이런 상황은 메인보드 제조사마다 메뉴 이름이 달라, 막히면 설치 오류 점검 글에서 다루는 방법을 참고하세요. wsl --install은 필요한 윈도우 기능(가상 머신 플랫폼 등)을 자동으로 켜주므로, 보통은 명령에 맡기면 됩니다.

관리자 권한

설치 명령은 시스템 기능을 켜기 때문에 관리자 권한이 필요합니다. 시작 메뉴에서 터미널(또는 PowerShell)을 찾아 마우스 오른쪽 버튼으로 “관리자 권한으로 실행”을 선택하세요.

설치 따라 하기

1. 설치 명령 실행

관리자 권한 터미널에서 아래 명령을 입력합니다.

wsl --install

이 한 줄이 WSL 기능을 켜고, 기본 배포판인 우분투를 자동으로 내려받아 설치합니다. 끝나면 대개 재부팅을 요구합니다.

설치할 수 있는 배포판 목록이 궁금하다면 아래 명령으로 온라인 목록을 볼 수 있습니다.

wsl --list --online

2. 배포판을 지정해서 설치하기 (선택)

기본 우분투가 아니라 특정 배포판을 콕 집어 설치하고 싶다면 -d 옵션을 씁니다. 예를 들어 우분투를 명시적으로 지정하려면 이렇게 합니다.

wsl --install -d Ubuntu

배포판 이름은 위 wsl --list --online 결과에 나온 이름을 그대로 사용하면 됩니다. 처음이라면 굳이 고민하지 말고 기본 우분투로 시작해도 충분합니다.

3. 재부팅 후 첫 실행

재부팅하면 우분투 창이 자동으로 한 번 뜹니다. 처음에는 설치를 마무리하는 데 잠깐 시간이 걸립니다. 창이 자동으로 뜨지 않으면 시작 메뉴에서 “Ubuntu”를 검색해 직접 실행해도 됩니다.

4. 사용자 이름과 비밀번호 정하기

잠시 뒤 사용자 이름과 비밀번호를 정하라는 안내가 나옵니다. 이 계정은 윈도우 계정과는 별개인 리눅스 안에서 쓰는 계정입니다. 원하시는 이름으로 설정하시면 돼요.

비밀번호를 입력할 때 화면에 아무 글자도 보이지 않는 것이 정상입니다. 그대로 입력하고 엔터를 누르세요.
이 비밀번호는 이후 sudo로 관리자 작업을 할 때 쓰이므로 기억해 두어야 합니다.

5. 패키지 목록 갱신

설치 직후에는 우분투가 알고 있는 프로그램 목록이 오래되어 있을 수 있습니다. 아래 명령으로 목록을 갱신하고 기본 패키지를 최신 상태로 맞춥니다.

sudo apt update && sudo apt upgrade

update는 “어떤 프로그램의 어떤 버전이 있는지” 목록을 새로 받아오는 단계이고, upgrade는 그 목록을 바탕으로 실제로 최신 버전을 설치하는 단계입니다. 도중에 계속할지 묻는 질문이 나오면 y를 입력하고 엔터를 누르면 됩니다. 여기까지 마치면 윈도우 안에서 쓸 수 있는 우분투 환경이 준비된 것입니다.

상태 확인과 종료 다루기

설치가 끝났다면 지금 내 WSL이 어떤 상태인지 확인하는 명령을 익혀 두면 좋습니다. 아래 명령들은 모두 **윈도우 쪽 터미널(PowerShell 등)**에서 실행합니다.

버전과 상태 확인

wsl --version
wsl --status

wsl --version은 WSL 자체와 커널 버전을, wsl --status는 기본 배포판과 기본 WSL 버전 같은 현재 상태를 보여 줍니다. 설치한 배포판 목록과 각각의 WSL 버전(1인지 2인지)은 아래로 확인합니다.

wsl --list --verbose

안전하게 종료하기

리눅스 창을 닫아도 백그라운드에서 환경이 잠시 더 떠 있을 수 있습니다. 모든 WSL 환경을 완전히 내리고 싶을 때는 아래 명령을 씁니다.

wsl --shutdown

이 명령은 설정을 바꾼 뒤 깨끗하게 다시 시작하고 싶을 때나, 무언가 꼬였을 때 “껐다 켜는” 용도로 자주 씁니다. 다시 우분투 창을 열거나 터미널에서 wsl을 입력하면 환경이 다시 켜집니다.

WSL 다시 실행하기

PowerShell 에서 실행

PowerShell에서 단순히 wsl 만 입력해주면 됩니다. 그러면 마운트되는 경로로 들어가게되는데 cd ~ 입력해주시면 WSL 우분투 홈으로 들어가게 됩니다.

윈도우 목록에서 실행

또는 윈도우에서 wsl 검색하면 아래와 같은 창이 뜨는데 실행해주시면 자동으로 wsl 이 실행되고 홈 경로로 들어가게 됩니다.

초보자가 자주 막히는 부분

비밀번호가 안 보여서 당황 — 터미널에서 비밀번호는 원래 화면에 표시되지 않습니다. 잘못된 것이 아닙니다.
관리자 권한 없이 실행 — 일반 권한 터미널에서 wsl --install을 하면 권한 오류가 납니다. 반드시 관리자 권한으로 실행하세요.
재부팅을 건너뜀 — 설치 후 재부팅을 미루면 우분투 첫 실행이 제대로 마무리되지 않을 수 있습니다.
윈도우 업데이트가 너무 오래됨 — 명령이 인식되지 않으면 윈도우 버전이 오래된 경우가 많습니다.
가상화가 꺼져 있음 — 설치는 됐는데 실행 단계에서 오류가 난다면 BIOS/UEFI에서 가상화 기능이 꺼져 있을 수 있습니다.
설정 변경 후 반영이 안 됨 — 설정을 바꾼 뒤에는 wsl --shutdown으로 한 번 내렸다가 다시 켜야 적용되는 경우가 있습니다.

설치 점검 체크리스트

관리자 권한 터미널에서 wsl --install 을 실행했다
재부팅 후 우분투 창이 한 번 떴고, 설치가 마무리됐다
리눅스 사용자 이름과 비밀번호를 정했고, 비밀번호를 기억하고 있다
sudo apt update && sudo apt upgrade 로 패키지를 한 번 갱신했다
wsl --status / wsl --list --verbose 로 상태와 버전을 확인했다
wsl --shutdown 으로 안전하게 종료하는 법을 익혔다

정리

WSL2는 “리눅스를 배우려면 큰 결심이 필요하다”는 부담을 크게 낮춰 줍니다. 윈도우를 그대로 둔 채 우분투를 앱처럼 켜고, 마음에 들지 않으면 지우면 그만입니다. 설치 한 줄에서 끝내지 말고, 상태를 확인하고 안전하게 종료하는 명령까지 한 번씩 다뤄 두면 이후 작업이 훨씬 편안해집니다. 설치를 마쳤다면, 이제 터미널의 기본 명령에 익숙해지거나 윈도우와 리눅스 사이에서 파일을 주고받는 방법을 익힐 차례입니다. 막히는 부분이 있으면 설치 오류를 점검하는 글을 함께 참고하세요.

WSL에 OpenAI Codex CLI 설치하기

Thu, 09 Jul 2026 06:05:28 GMT

OpenAI Codex CLI는 터미널에서 동작하는 AI 코딩 도구입니다. 윈도우만 써왔다면 “터미널에 설치”라는 말부터 낯설 수 있는데, WSL(우분투) 리눅스 터미널을 마련해 두면 설치 흐름이 한결 깔끔해집니다.

이 글에서는 WSL 환경을 기준으로, 실제 설치 명령어를 그대로 따라 칠 수 있게 순서대로 정리했습니다. 도구는 자주 갱신되므로, 가장 정확한 기준은 글 아래 출처에 적은 공식 문서임을 먼저 밝혀 둡니다.

Codex CLI가 어떤 도구인가

Codex CLI는 작업하려는 폴더 안에서 명령을 입력해, 대화하듯 코드를 읽고·고치고·실행하는 도구입니다. 그래픽 앱처럼 창을 띄우는 대신 터미널에서 동작하기 때문에, 설치도 일반 프로그램보다는 개발 도구를 설치하는 흐름에 가깝습니다.

같은 계열의 다른 도구를 먼저 설치해 본 적이 있다면 흐름이 거의 비슷합니다. (참고: Claude Code 처음 설치하고 실행해보기)

설치 전에 갖춰야 할 것

WSL(우분투) 터미널 — 윈도우라면 먼저 WSL로 리눅스 터미널을 마련해 둡니다. 아직 WSL이 없다면 WSL2 설치 글을 먼저 보고 오면 됩니다.
(npm 설치를 택할 경우) Node.js와 npm — npm으로 설치하려면 Node.js 환경이 먼저 필요합니다. 버전을 깔끔하게 관리하려면 Node.js 버전 매니저로 들이는 편이 이후가 편합니다. 아래의 curl 설치 스크립트를 쓰면 Node 없이도 설치할 수 있으니, Node가 없다면 그쪽을 택해도 됩니다.

WSL 터미널을 열었다면, Node가 이미 있는지 한 번 확인해 봅니다.

node -v
npm -v

버전 숫자가 출력되면 npm 설치 방법을 바로 쓸 수 있고, “command not found”가 나오면 Node가 아직 없는 상태이니 curl 설치 스크립트를 쓰거나 Node부터 설치하면 됩니다.

설치 방법

설치 방법은 두 가지입니다. 둘 중 하나만 따라 하면 됩니다.

방법 A — npm으로 설치 (Node.js가 있을 때)

이미 Node.js·npm을 쓰고 있다면, 패키지 매니저로 한 줄에 설치합니다.

npm install -g @openai/codex

-g는 시스템 어디서나 codex 명령을 쓸 수 있게 전역(global)으로 설치하라는 뜻입니다.

방법 B — 공식 설치 스크립트로 설치 (Node 없이)

Node를 따로 설치하고 싶지 않다면, OpenAI가 제공하는 설치 스크립트를 쓰는 방법이 간단합니다. WSL(리눅스)에서는 다음 명령을 사용합니다.

curl -fsSL https://chatgpt.com/codex/install.sh | sh

참고로 macOS에서는 brew install --cask codex(Homebrew)도 가능하고, 윈도우 PowerShell에서 바로 설치하는 방법도 따로 있습니다. 이 글은 WSL 기준이므로 위 두 방법을 권장합니다.

설치가 됐는지 확인

설치가 끝났으면 버전을 출력해 정상 설치를 확인합니다.

codex --version

버전 숫자가 나오면 설치가 끝난 것입니다. 만약 “command not found”가 나온다면 터미널을 새로 열거나, 설치 경로(PATH) 설정을 점검해 보세요.

작업 폴더로 이동해서 실행

설치가 끝났다면 아무 곳에서나 실행하지 말고, 작업하려는 프로젝트 폴더 안으로 먼저 이동한 뒤 실행합니다. Codex는 “지금 위치한 폴더”를 작업 대상으로 삼기 때문에, 어디서 실행하느냐가 곧 어떤 파일을 다루게 되느냐로 이어집니다.

cd ~/projects/my-app
codex

codex를 실행하면 터미널 안에서 대화형 화면이 열립니다.

첫 실행 — 로그인(인증)

처음 codex를 실행하면 로그인 절차를 거칩니다. 화면 안내에서 “Sign in with ChatGPT”(ChatGPT 계정으로 로그인) 를 선택하면 브라우저를 통해 계정과 연결됩니다. ChatGPT 계정 대신 API 키로 인증하는 방법도 있는데, 이 경우 키 발급 등 추가 설정이 필요합니다.

한 번 로그인해 두면 이후에는 매번 로그인하지 않아도 되는 경우가 많지만, 구체적인 방식·유효 기간은 환경과 버전에 따라 다를 수 있으니 화면 안내를 그대로 따르는 것이 정확합니다.

초보자가 자주 막히는 부분

WSL 준비를 건너뜀 — 윈도우에서 리눅스 명령(curl, npm)을 바로 치려다 막히는 경우가 많습니다. 먼저 WSL 터미널을 열고 그 안에서 실행하세요.
방법 A·B를 둘 다 실행 — 두 방법은 택일입니다. 하나로 설치한 뒤 codex --version으로 확인하면 됩니다.
command not found — 설치 직후 명령이 안 잡히면 터미널을 새로 열거나 PATH 설정을 점검합니다.
엉뚱한 폴더에서 실행 — 작업하려는 프로젝트 폴더 안에서 실행해야 의도한 파일을 다룹니다.
명령을 오래된 글에서 베껴 옴 — 패키지명·옵션은 바뀔 수 있습니다. 항상 공식 문서의 최신 안내를 우선하세요.

설치 점검 체크리스트

WSL(우분투) 터미널을 열었다
npm 또는 curl 설치 스크립트 중 한 가지로 설치했다
codex --version으로 설치를 확인했다
작업할 프로젝트 폴더로 이동한 뒤 codex를 실행했다
첫 실행에서 ChatGPT 계정 또는 API 키로 로그인했다

출처

이 글의 설치 명령은 아래 공식 자료를 기준으로 작성했습니다. 도구는 자주 갱신되므로, 실제 설치 전에 최신 안내를 한 번 더 확인하시길 권합니다.

정리

WSL에서 Codex를 설치하는 핵심은 리눅스 터미널을 먼저 마련하고, npm이나 공식 설치 스크립트 중 하나로 설치한 뒤, 작업 폴더에서 실행해 로그인하는 흐름입니다. 버전과 환경에 따라 세부는 달라질 수 있으니, 명령은 위 공식 문서를 기준으로 확인하세요. 설치를 마쳤다면, 도구를 더 잘 활용하기 위한 기본기를 함께 점검해 두면 도움이 됩니다.

WSL Ubuntu 복제 및 새 환경 만들기 (Export / Import 완벽 가이드)

Thu, 09 Jul 2026 06:05:28 GMT

WSL을 쓰다 보면 “지금 환경은 그대로 두고, 블로그용·AI 실험용 환경을 따로 두고 싶다”는 순간이 옵니다. 개발·블로그·실험을 한 우분투에 다 몰아넣으면 패키지 버전이 충돌하거나 설정이 꼬이기 쉽기 때문입니다.

WSL은 사실 우분투 하나만 돌리는 도구가 아니라, 독립된 리눅스 환경을 여러 개 동시에 운영할 수 있는 플랫폼입니다. 이 글에서는 환경을 늘리는 두 가지 길을 명령어와 함께 정리합니다.

Ubuntu RootFS를 받아 새 환경 생성 — 깨끗한 새 환경
기존 환경을 Export 후 다른 이름으로 Import해 복제 — 지금 환경을 통째로 복사

먼저: 현재 설치된 WSL 확인

무엇을 하든, 지금 어떤 WSL이 깔려 있는지부터 확인합니다. PowerShell에서 실행합니다.

wsl -l -v

예시 출력:

  NAME            STATE           VERSION
* Ubuntu          Running         2

방법 1. Ubuntu를 새로 설치하기 (RootFS)

기존 환경과 완전히 분리된 깨끗한 우분투가 필요할 때 쓰는 방법입니다.

1) Ubuntu WSL RootFS 다운로드

캐노니컬이 제공하는 공식 WSL용 RootFS 이미지를 내려받습니다.

24.04 LTS RootFS: https://cloud-images.ubuntu.com/wsl/releases/24.04/current/ubuntu-noble-wsl-amd64-24.04lts.rootfs.tar.gz
버전별 목록: https://cloud-images.ubuntu.com/wsl/releases/24.04/current/

2) 설치 폴더 만들기

환경이 저장될 폴더를 미리 만들어 둡니다. 용량이 늘어날 수 있으니 여유 있는 드라이브(예: D)를 권합니다.

mkdir D:\WSL\Ubuntu-Blog

3) Import로 새 환경 생성

내려받은 RootFS 파일을 새 이름으로 등록합니다.

wsl --import Ubuntu-Blog D:\WSL\Ubuntu-Blog C:\Downloads\ubuntu-noble-wsl-amd64-24.04lts.rootfs.tar.gz

명령의 세 인자는 각각 다음을 뜻합니다.

Ubuntu-Blog          ← 새로 만들 WSL 이름
D:\WSL\Ubuntu-Blog   ← 이 환경이 저장될 폴더
ubuntu-...tar.gz     ← 방금 받은 RootFS 파일 경로

4) 최초 실행

wsl -d Ubuntu-Blog

RootFS로 만든 환경은 처음에 root 계정으로 로그인됩니다. 일상적으로 쓸 일반 사용자를 만들어 줍니다.

5) 사용자 생성과 sudo 권한

우분투 안(리눅스 셸)에서 실행합니다.

adduser blog
usermod -aG sudo blog

adduser는 비밀번호 등 정보를 물어보며 계정을 만들고, usermod -aG sudo는 그 계정에 관리자(sudo) 권한을 더합니다.

6) 기본 사용자 설정

실행할 때마다 root가 아니라 방금 만든 계정으로 들어오게 합니다. /etc/wsl.conf를 편집합니다.

sudo nano /etc/wsl.conf

아래 내용을 적고 저장합니다.

[user]
default=blog

7) WSL 재시작

설정을 적용하려면 해당 환경을 한 번 종료했다가 다시 켭니다. PowerShell에서:

wsl --terminate Ubuntu-Blog
wsl -d Ubuntu-Blog

이제 blog 계정으로 자동 로그인됩니다.

✍️ 운영자 한마디

새 환경을 만들 때 root로만 쓰다가 나중에 권한 문제로 고생하기 쉽습니다. 처음에 일반 사용자 만들고 기본 사용자로 지정하는 단계까지 끝내 두면, 그다음부터는 훨씬 편합니다.

방법 2. 기존 Ubuntu 환경 복제하기 (Export / Import)

지금 쓰는 환경에 이미 Node.js·Python·각종 도구가 깔려 있다면, 그걸 통째로 복사하는 방법입니다.

Ubuntu
 ├─ 사용자: tbalja
 ├─ Node.js
 ├─ Python
 └─ 각종 개발 도구

이 상태를 그대로 다른 이름의 환경으로 복제할 수 있습니다.

1) Export (백업 파일로 내보내기)

PowerShell에서 원본 환경을 하나의 .tar 파일로 내보냅니다.

wsl --export Ubuntu D:\Backup\ubuntu_backup.tar

Ubuntu               ← 내보낼 원본 WSL 이름
ubuntu_backup.tar    ← 만들어질 백업 파일

이 .tar 파일은 그 자체로 백업본이기도 합니다. 다른 PC로 옮겨 복원할 수도 있습니다.

2) Import (새 이름으로 복원/복제)

저장 폴더를 만들고, 백업 파일을 새 이름으로 들여옵니다.

mkdir D:\WSL\Ubuntu-Test
wsl --import Ubuntu-Test D:\WSL\Ubuntu-Test D:\Backup\ubuntu_backup.tar

확인:

wsl -l -v

  NAME            STATE           VERSION
* Ubuntu          Stopped         2
  Ubuntu-Test     Stopped         2

주의 — Import는 “복제”입니다

Export/Import는 환경을 그대로 복사하므로, 아래 내용이 전부 함께 따라옵니다.

사용자 계정
SSH 키
설치된 패키지
환경 변수
Node.js / Python / Docker 설정 등

즉, 이런 상태가 됩니다.

Ubuntu
 └─ tbalja

Ubuntu-Test
 └─ tbalja   ← 계정·키까지 동일하게 복제됨

사용자 계정과 키까지 똑같은 게 편할 때도 있지만, 완전히 새로운(깨끗한) 환경을 원한다면 Export/Import가 아니라 방법 1의 RootFS 새 설치를 택하는 편이 낫습니다.

WSL 관리 명령 모음

여러 환경을 운영하다 보면 자주 쓰게 되는 명령들입니다. 모두 PowerShell에서 실행합니다.

특정 환경 실행하기

wsl -d Ubuntu
wsl -d Ubuntu-Blog

특정 환경 종료하기

wsl --terminate Ubuntu-Blog

환경 삭제하기

wsl --unregister Ubuntu-Test

⚠️ --unregister는 해당 WSL의 모든 데이터를 삭제합니다. 되돌릴 수 없으니 이름을 꼭 확인하세요.

설치 목록 확인

wsl --list --verbose

이 명령은 배포판 이름·상태·버전만 보여줍니다. 실제 설치 경로(VHDX 파일 위치)는 나오지 않습니다.

실제 설치 경로(VHDX) 확인

설치 경로는 레지스트리의 BasePath 값에 들어 있습니다. PowerShell에서 다음처럼 한 번에 뽑아볼 수 있습니다.

Get-ChildItem HKCU:\Software\Microsoft\Windows\CurrentVersion\Lxss | ForEach-Object { Get-ItemProperty $_.PSPath | Select-Object DistributionName, BasePath }

설치 경로를 옮기고 싶다면 레지스트리를 직접 고치지 마세요. wsl --export로 백업한 뒤 원하는 폴더에 wsl --import하는 방식이 안전합니다.

정리

WSL은 리눅스 하나를 실행하는 도구가 아니라, 여러 독립 환경을 동시에 굴릴 수 있는 플랫폼입니다.

깨끗한 새 환경이 필요하면 RootFS를 받아 wsl --import
기존 환경을 그대로 쓰려면 wsl --export → wsl --import로 복제
목적별로 분리해 두면 충돌이 줄고 유지보수가 편해집니다

환경이 여러 개가 되면 윈도우와 리눅스 사이 파일을 오갈 일도 많아지는데, 그 흐름은 윈도우·리눅스 파일 공유 글에서 이어서 보면 좋습니다.

Gemini CLI 처음 설치하고 WSL에서 실행해보기

Thu, 09 Jul 2026 06:05:28 GMT

Claude Code나 Codex CLI를 한 번 써봤다면, 이제 “Gemini도 터미널에서 바로 쓸 수 있나?”라는 생각이 들 수 있습니다. Google의 Gemini CLI는 브라우저에서 Gemini를 여는 대신, 작업 중인 프로젝트 폴더 안에서 gemini 명령으로 AI에게 코드를 읽히고 설명을 부탁할 수 있는 도구입니다.

다만 이런 도구는 설치 명령 한 줄보다 내 WSL 환경에서 명령이 어디에 설치되고, PATH가 어떻게 잡히는지가 더 중요합니다. 글 작성 시점에 실제로 WSL 터미널에서 Node/npm 버전, npm 패키지 버전, 별도 임시 설치 경로에서의 실행 여부를 확인했습니다. 아래 캡처는 그 확인 과정의 예시입니다.

먼저 확인한 환경

이 글의 확인 환경은 다음과 같습니다.

항목	확인값
터미널	WSL 계열 리눅스 터미널
Node.js	`v22.23.1`
npm	`10.9.8`
확인한 Gemini CLI 패키지 버전	`0.49.0`

설치 글을 볼 때는 항상 “내 환경과 글쓴이의 환경이 같은가?”를 먼저 봐야 합니다. 특히 Node.js와 npm은 버전 매니저, apt, 직접 설치 방식에 따라 전역 설치 위치가 달라질 수 있습니다.

node -v
npm -v
npm view @google/gemini-cli version

위 세 명령으로 최소한 다음을 알 수 있습니다.

Node.js가 WSL 안에서 정상 실행되는지
npm 명령이 현재 셸에서 잡히는지
현재 npm registry에 올라온 Gemini CLI 버전이 무엇인지

여기서 node나 npm이 command not found로 나온다면 Gemini CLI 설치부터 진행하지 말고, Node.js와 버전 관리 도구 글을 먼저 보고 Node 환경을 정리하는 편이 좋습니다.

✍️ 운영자 한마디

AI CLI 도구 설치에서 실제로 자주 막히는 곳은 도구 자체보다 Node/npm 경로였습니다. 설치 명령을 다시 복사하기 전에, 현재 터미널이 어떤 Node와 npm을 보고 있는지 먼저 확인하는 습관이 훨씬 도움이 됩니다.

Gemini CLI가 어떤 도구인가

Gemini CLI는 Google Gemini를 터미널에서 사용할 수 있게 해주는 오픈소스 AI 에이전트입니다. 단순히 질문에 답하는 챗봇이라기보다, 현재 폴더의 파일을 읽고, 코드 구조를 설명하고, 필요한 경우 수정 방향을 제안하는 개발 보조 도구에 가깝습니다.

비슷한 계열의 도구로는 Claude Code, OpenAI Codex CLI가 있습니다. 셋 모두 “작업 폴더 안에서 실행한다”는 점은 비슷하지만, 사용하는 계정, 모델, 설정 방식, 권한 확인 흐름은 조금씩 다릅니다. 그래서 처음에는 여러 도구를 한꺼번에 자동화하기보다, 하나씩 설치하고 기본 동작을 확인하는 편이 안전합니다.

WSL에서 설치하기

Gemini CLI의 표준 설치 흐름은 npm을 사용합니다. WSL 터미널에서 아래 명령을 실행합니다.

npm install -g @google/gemini-cli

여기서 -g는 전역 설치(global)를 뜻합니다. 특정 프로젝트 안에서만 쓰는 라이브러리가 아니라, 터미널 어디서나 gemini 명령을 실행할 수 있게 설치하는 방식입니다.

다만 전역 설치는 환경마다 결과가 다를 수 있습니다. 예를 들어 npm 전역 prefix가 /usr처럼 시스템 경로를 가리키면 권한 문제를 만날 수 있습니다. 그럴 때는 sudo를 붙여 억지로 밀어붙이기보다, Node를 nvm 같은 버전 매니저로 관리하는 쪽이 나중에 덜 꼬입니다.

설치가 제대로 되는지 별도 경로에서 검증해보기

전역 설치 전에 패키지가 실제로 내려받아지고 실행 파일이 만들어지는지 확인하고 싶다면, 임시 경로에 설치해 보는 방법도 있습니다. 글 작성 시점에는 별도 prefix를 지정해 설치한 뒤, 생성된 실행 파일로 버전을 확인했습니다.

npm install --prefix /tmp/gemini-cli-check @google/gemini-cli
/tmp/gemini-cli-check/node_modules/.bin/gemini --version

이 방식은 실제 사용을 위한 설치라기보다 패키지 자체가 정상 설치되는지 확인하는 검증용입니다. 평소 사용할 때는 앞의 전역 설치 명령을 쓰는 편이 간단합니다.

전역 설치 후에는 다음 명령으로 확인합니다.

gemini --version

버전 숫자가 출력되면 설치가 정상적으로 된 것입니다.

`gemini` 명령을 못 찾을 때

설치 후 가장 흔하게 만나는 상황은 이것입니다.

gemini: command not found

이 메시지를 보면 설치가 실패했다고 생각하기 쉽지만, 실제로는 설치 위치가 현재 PATH에 잡히지 않은 문제일 때가 많습니다. 먼저 아래 명령으로 확인합니다.

npm prefix -g
command -v gemini

확인 순서는 이렇게 잡으면 됩니다.

npm prefix -g로 npm 전역 설치 기준 경로를 확인합니다.
command -v gemini로 현재 셸에서 gemini 명령이 잡히는지 확인합니다.
전역 prefix가 /usr처럼 시스템 경로라면 권한 문제 가능성을 봅니다.
nvm을 쓴다면 새 터미널에서 nvm 초기화가 제대로 되는지 확인합니다.
설치 직후라면 터미널을 닫고 다시 열어 PATH가 갱신되는지 확인합니다.

입문 단계에서는 “안 되면 sudo”로 가기보다, 어디에 설치됐고 현재 셸이 그 위치를 보고 있는지를 먼저 확인하는 편이 안전합니다.

작업 폴더에서 첫 실행하기

설치가 끝났다면 아무 폴더에서나 실행하지 말고, 도움을 받고 싶은 프로젝트 폴더 안에서 실행합니다.

예를 들어 연습용 프로젝트가 ~/projects/my-app에 있다면 이렇게 이동합니다.

cd ~/projects/my-app
gemini

처음 실행하면 대화형 화면이 열리고, 인증 방식을 묻는 안내가 나옵니다. 공식 빠른 시작 문서는 가장 간단한 방식으로 Login with Google을 안내합니다. 화면에서 Google 로그인 방식을 선택하면 브라우저 인증 흐름으로 이어집니다.

계정 이름, 인증 토큰, API 키가 보이는 화면은 블로그에 그대로 올리지 않는 편이 좋습니다. 캡처가 필요하다면 계정명과 토큰은 반드시 가리고 올리세요.

첫 질문은 파일 수정이 아니라 읽기부터

Gemini CLI를 처음 켰다면 바로 “이 프로젝트를 고쳐줘”라고 하기보다, 읽기 중심 요청부터 시작하는 편이 좋습니다.

이 프로젝트에서 먼저 읽어야 할 파일과 실행 방법을 찾아서 요약해줘.

또는 다음처럼 범위를 좁혀 요청할 수 있습니다.

package.json과 README를 보고 이 프로젝트의 실행 방법만 정리해줘.

이렇게 시작하면 Gemini CLI가 현재 폴더를 어떻게 이해하는지 확인할 수 있습니다. 파일 수정은 그다음 단계입니다.

파일 수정 전 확인할 것

AI CLI 도구가 파일을 고치겠다고 제안할 때는 바로 승인하기보다, 어떤 파일을 어떻게 바꾸는지 확인해야 합니다. 특히 아래 파일은 작은 변경도 영향을 크게 줄 수 있습니다.

.env, .env.local 같은 환경변수 파일
배포 설정 파일
인증·토큰 관련 파일
package.json, lockfile
GitHub Actions 같은 자동화 설정

입문 단계에서는 자동 승인이나 무제한 실행 옵션을 켜기보다, 한 번씩 확인하며 진행하는 기본 흐름에 익숙해지는 것을 권합니다.

Google 로그인과 API 키 방식

Gemini CLI는 여러 인증 방식을 지원합니다. 공식 저장소에는 Google 계정 로그인, Gemini API 키, Vertex AI 같은 선택지가 소개되어 있습니다. 입문자라면 먼저 Google 로그인 방식으로 시작하는 편이 단순합니다.

API 키를 쓰는 방식은 자동화나 별도 모델 선택에는 유용할 수 있지만, 키 관리가 필요합니다. API 키를 터미널에 붙여넣거나 설정 파일에 저장할 때는 절대 공개 저장소에 올라가지 않도록 조심해야 합니다.

Claude Code·Codex CLI와 같이 쓸 때

티발자랩의 흐름대로라면 이미 Claude Code 처음 설치하고 실행해보기나 WSL에 OpenAI Codex CLI 설치하기를 봤을 수 있습니다. Gemini CLI까지 설치하면 한 WSL 환경 안에 여러 AI 코딩 도구가 공존하게 됩니다.

이때 중요한 것은 “어떤 도구가 더 좋다”를 빨리 결론내리는 것이 아니라, 같은 프로젝트에서 다음 기준으로 비교해 보는 것입니다.

설치와 로그인 과정이 얼마나 단순한가
현재 프로젝트 구조를 얼마나 잘 설명하는가
파일을 수정하기 전에 변경 의도를 명확히 보여주는가
긴 로그나 에러 메시지를 읽고 원인을 잘 좁혀 주는가
내가 쓰는 작업 방식과 비용·한도가 맞는가

특히 무료 사용량이나 모델 정책은 시간이 지나며 바뀔 수 있습니다. 검색 결과나 예전 블로그 글만 믿기보다 공식 문서에서 최신 기준을 확인하는 습관이 필요합니다.

초보자가 자주 막히는 부분

npm이 없는 상태에서 설치 명령부터 실행 — 먼저 node -v, npm -v로 준비 상태를 확인하세요.
윈도우 PowerShell과 WSL 터미널을 섞음 — 이 글의 명령은 WSL 우분투 터미널 기준입니다. 어느 터미널에서 실행 중인지 확인하세요.
설치 후 gemini 명령을 못 찾음 — 터미널을 새로 열고, npm 전역 설치 경로와 PATH를 확인합니다.
전역 prefix가 /usr로 잡힘 — 권한 문제가 날 수 있으니 Node 설치 방식을 점검합니다.
엉뚱한 폴더에서 실행 — 작업하려는 프로젝트 폴더로 cd 한 뒤 실행하세요.
처음부터 파일 수정을 맡김 — 첫 사용은 프로젝트 설명, 실행 방법 찾기, 에러 로그 분석처럼 읽기 중심 작업부터 시작하는 편이 안전합니다.
API 키를 공개 저장소에 커밋 — API 키 방식으로 인증한다면 .env, 설정 파일, Git 추적 여부를 반드시 확인하세요.

설치 점검 체크리스트

WSL(우분투) 터미널을 열었다
node -v, npm -v로 Node.js와 npm을 확인했다
npm view @google/gemini-cli version으로 현재 패키지 버전을 확인했다
npm install -g @google/gemini-cli로 설치했다
gemini --version으로 설치를 확인했다
명령이 안 잡히면 npm prefix -g와 PATH를 점검했다
작업할 프로젝트 폴더로 이동한 뒤 gemini를 실행했다
첫 실행에서 Google 로그인 인증을 마쳤다
파일 수정 전에는 변경 내용을 확인하며 진행한다

출처

이 글은 아래 공식 자료를 기준으로 설치 명령과 기본 흐름을 확인했습니다. Gemini CLI는 릴리스가 빠른 도구이므로, 실제 설치 전에는 최신 문서를 한 번 더 확인하는 것을 권합니다.

정리

WSL에서 Gemini CLI를 설치하는 핵심은 Node.js와 npm 확인 → 패키지 버전 확인 → 설치 → gemini --version 확인 → 작업 폴더에서 첫 실행입니다.

설치 명령 한 줄만 보면 쉬워 보이지만, 실제로는 PATH와 전역 설치 경로에서 막히는 경우가 많습니다. 그래서 설치가 안 된다고 바로 단정하지 말고, 현재 터미널이 어떤 Node/npm을 보고 있는지, gemini 실행 파일이 PATH에 잡히는지부터 차분히 확인해 보세요.

요즘 입문자들이 WSL 설치에서 자주 멈추는 지점

Thu, 09 Jul 2026 06:05:28 GMT

개발환경 세팅을 막 시작하는 분들과 이야기하다 보면, 막히는 자리가 몇 년 전과 조금 달라졌다는 인상을 받습니다. 예전에는 설치 명령 자체가 복잡해서 거기서 좌절하는 경우가 많았다면, 요즘은 명령 한 줄로 설치가 끝나는 대신 그 앞뒤에서 멈추는 분이 더 많아 보입니다.

이 글은 정해진 정답을 안내하는 정보형 글이라기보다, 최근 흐름을 지켜보며 느낀 점을 정리한 칼럼입니다. 그래서 “이렇게 하면 됩니다”보다는 “요즘은 여기서 자주 멈추더라”는 이야기에 가깝습니다.

막히는 자리가 달라진 이유

설치 도구가 좋아진 만큼, 어려움의 성격도 바뀌었습니다. 명령 한 줄이 알아서 기능을 켜고 배포판까지 받아 주니, ‘설치 과정’ 자체는 예전만큼 큰 산이 아닙니다. 대신 그 자동화가 가려 둔 앞뒤의 작은 절차들이 새로운 걸림돌이 됐습니다. 자동으로 처리되는 부분이 많아질수록, 사람이 챙겨야 하는 한두 가지를 놓쳤을 때 “왜 안 되는지”가 더 안 보이게 되는 셈입니다.

설치보다 ‘권한과 재부팅’에서 멈춘다

가장 자주 보이는 지점은 의외로 단순합니다. 관리자 권한으로 터미널을 열지 않아 권한 오류를 만나거나, 설치 후 재부팅을 미루다가 “설치가 안 됐다”고 느끼는 경우입니다. 명령 자체는 어렵지 않은데, 그 주변의 작은 절차가 생략되면서 전체가 막힌 것처럼 보입니다.

특히 재부팅은 “나중에 하면 되겠지” 하고 넘기기 쉬운 단계인데, 이걸 건너뛰면 분명히 설치 명령을 실행했는데도 다음 화면이 제대로 이어지지 않습니다. 그러면 “명령이 틀렸나” 하고 엉뚱한 곳을 의심하게 됩니다. 사실은 절차 하나가 비어 있을 뿐인데 말이죠.

✍️ 직접 써보고 느낀 점

제가 주변에서 설치를 도울 때도 막상 명령에서 막히는 경우는 드물었습니다. 오히려 ‘관리자 권한으로 열어야 한다’는 한 줄을 놓쳤거나, 재부팅을 건너뛰고 ‘안 된다’고 단정해서 멈춘 경우가 대부분이었습니다. 저 역시 다시 설치할 때 비밀번호 입력 화면에서 커서만 깜빡이는 걸 보고 잠깐 멈칫했던 기억이 납니다. 알고 보면 사소한데, 처음엔 그 사소함이 잘 안 보입니다.

검은 화면 앞에서의 망설임

설치를 마친 뒤 터미널을 열면, 많은 분이 “이제 뭘 쳐야 하지?”에서 멈춥니다. 설치라는 큰 산을 넘었는데 정작 첫 명령 앞에서 더 오래 망설이는 것이죠. 이건 지식의 문제라기보다, 마우스 없이 글자만으로 컴퓨터를 다루는 방식에 대한 낯섦에 가깝습니다.

그래서 저는 입문자에게 설치 직후 거창한 작업을 권하지 않습니다. 현재 위치를 확인하고, 목록을 보고, 폴더를 한 번 만들어 보는 정도면 충분합니다. 별것 아닌 명령이라도 내가 친 대로 화면이 반응하는 걸 직접 보면, 검은 화면이 갑자기 덜 무서워집니다. 작은 성공이 두세 번 쌓이면 두려움은 생각보다 빠르게 줄어듭니다.

‘제대로 된 게 맞나’ — 확인으로 안심하기

또 하나 자주 보이는 정서는 막연한 불안입니다. 분명 설치는 끝난 것 같은데 “이게 맞게 된 건지” 확신이 서지 않아 다음으로 못 나아가는 경우죠. 이럴 때는 상태를 보여 주는 확인 명령을 한두 개 알려 드리는 것만으로 표정이 풀립니다. 무엇이 어떻게 깔렸는지 눈으로 확인하고 나면, “일단 여기까지는 됐구나” 하는 발판이 생기기 때문입니다. 결국 입문 단계에서 필요한 건 더 많은 기능이 아니라, 지금 상태를 스스로 확인할 수 있는 작은 수단인 것 같습니다.

최근에 더 자주 보이는 질문

“설치는 됐는데, 이게 제대로 된 게 맞나요?” — 상태 확인 명령 한두 개로 안심하는 것이 도움이 됩니다.
“윈도우 파일이랑 리눅스 파일이 섞이는 건가요?” — 경로 개념을 짧게 잡아 주면 대부분 해소됩니다.
“뭔가 잘못 누르면 컴퓨터가 망가질까 봐 무서워요” — 되돌리기 쉬운 작업부터 시작하면 됩니다.
“화면에 글자가 안 보이는데 고장 난 건가요?” — 비밀번호 입력처럼 원래 안 보이는 경우가 있다는 걸 미리 알면 덜 당황합니다.

정리하며

요즘 입문자들이 멈추는 자리는 ‘어려운 명령’이 아니라, 설치 앞뒤의 작은 절차와 검은 화면에 대한 낯섦입니다. 그래서 안내하는 입장에서도 명령을 더 많이 알려 주기보다, 처음의 망설임을 줄여 주고 “지금 잘 가고 있다”는 신호를 주는 쪽이 더 효과적이라고 느낍니다. 결국 입문의 벽은 기술보다 심리에 가까울 때가 많습니다. 다음 칼럼에서는 비슷한 맥락에서, AI 코딩 도구를 처음 쓸 때 생기는 오해들을 정리해 보려 합니다.

AI 코딩 도구를 처음 쓸 때 흔한 오해들

Thu, 09 Jul 2026 06:05:28 GMT

AI 코딩 도구를 처음 써 보는 분들과 이야기하다 보면, 도구 자체보다 도구에 대한 기대에서 어긋남이 시작되는 경우가 많습니다. 기능이 어렵다기보다, “이 도구가 무엇을 해주는 것인가”에 대한 그림이 실제와 다른 것이죠. 그 그림만 조금 손보면, 같은 도구가 갑자기 훨씬 쓸 만해집니다.

이 글은 사용법을 정리한 정보형 글이라기보다, 최근 입문자들에게서 자주 보이는 오해를 지켜보며 느낀 점을 적은 칼럼입니다.

‘다 알아서 해줄 것’이라는 기대

가장 자주 보이는 오해는 도구가 시작부터 끝까지 알아서 처리해 줄 거라는 기대입니다. 그래서 한 번의 요청으로 원하는 결과가 바로 나오길 바라고, 그렇지 않으면 “도구가 별로다”라고 느끼곤 합니다. 하지만 실제로는 무엇을 원하는지 사람이 먼저 분명히 정해 주어야 하고, 나온 결과가 맞는지 판단하는 몫도 여전히 사람에게 남습니다.

조금 더 들여다보면, 이 기대의 뿌리에는 “요청을 막연하게 던져도 알아서 좋은 쪽으로 채워 주겠지” 하는 마음이 있습니다. 그런데 막연한 요청에는 막연한 결과가 돌아옵니다. 같은 도구라도 “무엇을, 어떤 조건에서, 어디까지” 해 달라고 좁혀서 부탁하면 결과의 질이 눈에 띄게 달라집니다. 결국 도구의 성능 이전에, 요청을 또렷하게 만드는 것이 사용자의 첫 번째 일인 셈입니다.

✍️ 직접 써보고 느낀 점

저도 처음엔 한 번의 요청으로 완성된 결과가 나오길 기대했다가, 엉뚱한 방향으로 흘러간 코드를 받아 들고 당황한 적이 있습니다. 기대를 ‘완성품을 받는다’에서 ‘초안을 같이 만든다’로 바꾸고 나서야, 같은 도구가 훨씬 쓸 만하게 느껴졌습니다. 작게 시키고, 결과를 보고, 다시 방향을 잡아 주는 식으로 주고받으니 오히려 속도가 붙더군요.

‘코드를 이해 안 해도 된다’는 착각

두 번째로 자주 보이는 흐름은, 도구가 만들어 준 코드를 이해하지 않고 그대로 받아쓰는 태도입니다. 잘 돌아갈 때는 문제가 없어 보이지만, 막상 결과가 틀리거나 멈췄을 때 손을 댈 수 없게 됩니다. 도구가 내놓은 코드도 결국 내가 책임지고 읽어야 할 글이라는 점은 바뀌지 않습니다.

특히 입문 단계에서는 “돌아가니까 됐다”와 “이해했으니까 됐다”를 구분하기 어렵습니다. 그런데 이 둘은 시간이 지날수록 격차가 벌어집니다. 짧게라도 “이게 왜 이렇게 동작하지?”를 한 번 짚고 넘어가는 습관이, 나중에 문제가 생겼을 때 훨씬 큰 시간을 아껴 줍니다. 도구를 빠르게 쓰는 것과 이해를 건너뛰는 것은 다른 이야기입니다.

‘틀리지 않는다’는 믿음

세 번째는 도구가 항상 맞는 답을 준다고 믿는 경우입니다. 그럴듯하게 정리된 결과일수록 의심 없이 받아들이기 쉬운데, 실제로는 사실과 다른 내용을 자신 있게 내놓는 일도 드물지 않습니다. 문장이 매끄럽다는 것과 내용이 옳다는 것은 별개인데, 잘 다듬어진 결과 앞에서는 그 구분이 흐려지기 쉽습니다.

그래서 처음 쓰는 분일수록 결과를 ‘정답’이 아니라 ‘초안’으로 받아들이는 태도가 안전합니다. 특히 파일을 지우거나 시스템을 바꾸는 종류의 명령이라면, 실행 전에 무슨 동작인지 한 번 더 확인하는 습관이 필요합니다. 의심은 도구를 불신하라는 뜻이 아니라, 결과를 내 손으로 한 번 검증하라는 뜻에 가깝습니다.

그래서, 어떤 태도가 도움이 될까

오해를 뒤집으면 자연스럽게 권하고 싶은 태도가 보입니다. 무엇을 원하는지 구체적으로 정해서 부탁하고, 결과를 작은 단위로 받아 확인하고, 중요한 작업은 되돌릴 수 있게 해 두는 것입니다. 이 세 가지만 지켜도 도구와의 호흡이 한결 안정적으로 바뀝니다. 도구를 더 잘 쓰는 일은 결국 더 좋은 명령어를 외우는 것이 아니라, 도구와 사람이 역할을 어떻게 나눌지를 정하는 일에 가깝습니다.

정리하며

요즘 입문자들이 헷갈리는 지점은 도구의 성능이 아니라, 도구를 ‘대신해 주는 존재’로 보느냐 ‘보조해 주는 존재’로 보느냐의 차이에 가깝습니다. 무엇을 시킬지 정하고, 결과를 읽고, 맞는지 판단하는 일은 여전히 사람의 몫입니다. 도구를 보조로 받아들이는 순간, 오히려 더 잘 쓰게 된다고 느낍니다. 다음 칼럼에서는 비슷한 맥락에서, 개발환경 세팅에 시간을 너무 많이 쏟지 않는 방법을 정리해 보려 합니다.

개발환경 세팅에 너무 많은 시간을 쓰지 않으려면

Thu, 09 Jul 2026 06:05:28 GMT

입문 단계의 분들을 지켜보다 보면, 의외로 학습보다 환경 세팅에 더 많은 시간을 쏟는 흐름이 자주 보입니다. 좋은 도구를 갖추려는 마음 자체는 자연스럽지만, 그 준비가 길어지면서 정작 본래 하려던 공부가 계속 뒤로 밀리는 경우가 적지 않습니다.

이 글은 어떤 도구를 써야 하는지 안내하는 정보형 글이라기보다, 그 ‘미뤄짐’의 흐름을 지켜보며 느낀 점을 적은 칼럼입니다.

준비가 곧 실력처럼 느껴질 때

테마를 고르고, 설정 파일을 다듬고, 단축키를 정리하는 일은 손에 잡히는 성취감을 줍니다. 화면이 깔끔해지고 도구가 늘어날 때의 만족감은 분명 진짜입니다. 다만 그 만족감이 ‘공부를 하고 있다’는 느낌과 쉽게 헷갈린다는 게 문제입니다. 환경이 좋아진 것과 실력이 는 것은 다른 일인데, 준비하는 동안에는 그 둘이 잘 구분되지 않습니다.

게다가 환경 세팅은 결과가 즉각 눈에 보입니다. 색이 바뀌고 글꼴이 정돈되면 “뭔가 해냈다”는 신호가 바로 돌아오죠. 반면 학습은 더디고 답답합니다. 그래서 우리는 무의식적으로, 보상이 빠른 쪽으로 시간을 옮기게 됩니다. 세팅에 자꾸 손이 가는 건 의지가 약해서가 아니라, 그쪽이 더 즉각적인 만족을 주기 때문인 경우가 많습니다.

✍️ 직접 써보고 느낀 점

저 역시 한동안 설정 파일과 테마를 다듬느라 정작 만들려던 걸 미룬 적이 있습니다. 반대로 최소한의 환경만 갖추고 바로 시작했을 때는, 부족한 부분이 ‘불편’이라는 또렷한 형태로 드러나서 오히려 무엇을 더해야 할지 정하기가 쉬웠습니다. 미리 다 갖추려 했을 때보다, 필요할 때 하나씩 채웠을 때 그 도구를 더 오래, 더 잘 쓰게 되더군요.

‘완벽한 환경’이라는 움직이는 목표

또 하나 자주 보이는 흐름은, 완벽한 환경에는 끝이 없다는 점입니다. 하나를 갖추면 더 좋아 보이는 다른 도구가 눈에 들어오고, 남들의 화려한 설정을 보면 내 환경이 부족해 보입니다. 그렇게 기준이 계속 올라가다 보면 ‘아직 준비가 덜 됐다’는 느낌에서 영영 벗어나지 못합니다. 정작 그 도구들 대부분은 지금 단계에서 당장 필요하지 않은 경우가 많습니다.

특히 요즘은 다른 사람의 잘 꾸며진 환경을 쉽게 접할 수 있습니다. 그 화면들은 멋져 보이지만, 대개 오랜 시간에 걸쳐 그 사람의 필요에 맞게 쌓인 결과입니다. 그걸 출발선에서 통째로 따라 하려 하면, 정작 나에게는 왜 필요한지도 모르는 설정들만 잔뜩 떠안게 됩니다. 비교의 기준은 남의 완성된 환경이 아니라, 어제의 내 환경이면 충분합니다.

세팅도 공부의 일부일 수 있다

오해를 피하자면, 환경을 다듬는 일이 무의미하다는 말은 아닙니다. 셸 설정을 손보고 단축키를 정리하는 과정에서 자연스럽게 터미널과 친해지고, 도구가 어떻게 맞물려 돌아가는지 감이 잡히기도 합니다. 그 자체가 작은 학습인 셈이죠. 문제는 세팅이 ‘학습을 미루는 핑계’가 될 때입니다. 그래서 저는 두 가지를 구분하려 합니다. 지금 하려는 이 작업이 ‘오늘 공부를 시작하기 위한 준비’인지, 아니면 ‘공부를 미루기 위한 우회로’인지. 같은 행동이라도 그 의도만 솔직하게 짚어 보면, 멈춰야 할 때와 더 다듬어도 좋은 때가 꽤 또렷하게 갈립니다.

그래도 최소한 갖춰야 할 것

물론 아무 준비 없이 시작하라는 말은 아닙니다. 지금 공부를 시작하는 데 꼭 필요한 만큼은 갖추는 게 맞습니다. 다만 그 ‘최소한’의 기준을 ‘완벽’이 아니라 ‘오늘 한 걸음을 뗄 수 있는 정도’로 잡자는 것입니다. 터미널을 열 수 있고, 파일을 만들고 고칠 수 있고, 한 일을 되돌릴 수 있을 정도면 대부분의 학습은 시작할 수 있습니다. 나머지는 그 위에 얹으면 됩니다.

일단 시작하고, 필요할 때 다듬기

제가 권하는 태도는 단순합니다. 지금 공부를 시작할 수 있을 만큼만 갖추고, 나머지는 ‘불편을 느낀 그 순간’에 하나씩 더하는 것입니다. 실제로 손에 닿는 불편을 겪고 나서 도구를 들이면, 그 도구가 왜 필요한지도 또렷해지고 더 오래 씁니다. 불편은 귀찮은 신호가 아니라, 무엇을 다듬어야 할지 알려 주는 가장 정확한 안내판입니다. 미리 다 갖추는 것보다, 필요할 때 채우는 쪽이 결과적으로 더 빠르고 덜 지칩니다.

정리하며

요즘 입문자들이 자주 빠지는 함정은 ‘환경이 완벽해야 시작할 수 있다’는 생각입니다. 하지만 환경은 시작을 위한 도구일 뿐, 시작 그 자체를 대신해 주지는 않습니다. 부족한 채로 출발해도 괜찮고, 다듬는 일은 그다음에 와도 늦지 않습니다. 완벽한 준비보다, 일단 시작한 사람이 결국 더 멀리 간다고 느낍니다.

AI 코딩 작업에서 에이전트 역할을 나누는 기준

Wed, 08 Jul 2026 00:00:00 GMT

AI 코딩 도구를 쓰다 보면 “에이전트를 여러 개로 나누면 더 잘하지 않을까?”라는 생각이 듭니다. 실제로 큰 작업에서는 역할을 나누는 것이 도움이 됩니다. 하지만 역할을 제대로 정하지 않으면 에이전트만 많아지고 결과는 더 헷갈립니다.

중요한 것은 “몇 개로 나눌까”가 아니라 “각 역할이 무엇을 책임질까”입니다. 이 글에서는 AI 코딩 작업에서 가장 현실적으로 쓸 수 있는 역할 분담 기준을 정리합니다.

기본은 조사, 구현, 검토다

가장 무난한 분담은 세 가지입니다.

조사 담당: 현재 코드 구조, 관련 파일, 기존 패턴을 읽는다
구현 담당: 실제 변경을 만든다
검토 담당: 요구사항 누락, 위험한 변경, 빌드 오류 가능성을 본다

이 구조는 코딩뿐 아니라 블로그 글 이전, 설정 변경, 문서 정리에도 잘 맞습니다. 특히 기존 프로젝트에 무언가를 추가할 때는 조사 없이 바로 구현으로 들어가면 맥락을 놓치기 쉽습니다.

조사 담당은 답을 내는 사람이 아니다

조사 역할은 구현 아이디어를 내는 역할이 아닙니다. 먼저 현재 상태를 있는 그대로 확인하는 역할입니다.

예를 들어 Astro 블로그에서 새 글을 추가한다면 조사 담당은 이런 것을 봅니다.

콘텐츠 스키마가 어떤 frontmatter를 요구하는가
기존 글의 제목과 말투는 어떤가
이미지 경로는 어디를 쓰는가
카테고리 slug는 무엇인가
빌드는 어떤 명령으로 검증하는가

조사 결과가 좋아야 구현 담당이 헛다리를 짚지 않습니다.

구현 담당은 범위를 좁혀야 한다

구현 담당에게는 가능한 한 좁은 범위를 줘야 합니다. “블로그를 개선해줘”처럼 넓은 요청은 결과가 산만해집니다.

좋은 요청은 이런 식입니다.

src/content/posts/새-slug.md 파일 하나를 만든다
기존 글 1개를 티발자랩 톤으로 리라이팅한다
frontmatter는 현재 스키마에 맞춘다
이미지는 /images/...png 경로를 사용한다
관련 글은 2~3개만 연결한다

작업 범위가 좁으면 검토도 쉬워집니다. AI가 만든 변경이 마음에 들지 않아도 되돌릴 범위가 작습니다.

검토 담당은 다른 관점으로 본다

검토 역할은 단순한 맞춤법 검사가 아닙니다. 구현 담당이 놓치기 쉬운 것을 다른 관점에서 보는 역할입니다.

AI 코딩 작업에서는 특히 아래를 봐야 합니다.

요구사항을 빠뜨리지 않았는가
기존 파일을 불필요하게 많이 건드리지 않았는가
삭제나 덮어쓰기처럼 위험한 변경이 있는가
빌드나 테스트를 실제로 돌렸는가
글이라면 사이트 톤과 카테고리에 맞는가
이미지라면 브랜드 텍스트와 해상도가 맞는가

AI가 만든 결과를 또 다른 AI에게 검토시키는 것은 꽤 유용합니다. 다만 최종 판단은 사람이 해야 합니다. 검토 에이전트도 틀릴 수 있기 때문입니다.

역할 이름보다 입력과 출력을 정한다

역할 이름을 멋지게 붙이는 것보다 중요한 것은 입력과 출력입니다.

예를 들어 “검토 담당”이라는 이름만 있으면 모호합니다. 대신 이렇게 정해야 합니다.

입력: 구현 diff, 요구사항, 빌드 결과
출력: 통과 여부, 문제 목록, 수정 제안
하지 않을 일: 직접 수정하지 않기

이렇게 해야 역할이 겹치지 않습니다. 역할이 겹치면 여러 에이전트가 같은 말을 반복하거나 서로 다른 방향으로 수정하려고 합니다.

처음부터 많이 나누지 않는다

처음부터 5개, 6개 역할을 만들 필요는 없습니다. 오히려 관리가 어려워집니다.

입문 단계에서는 이렇게 시작해도 충분합니다.

작은 작업: 하나의 에이전트
중간 작업: 구현 + 검토
큰 작업: 조사 + 구현 + 검토

나중에 정말 필요해지면 문서 담당, 테스트 담당, 보안 검토 담당처럼 더 나눌 수 있습니다. 하지만 시작은 작게 하는 편이 좋습니다.

역할 분담 전 체크리스트

조사·구현·검토 중 어떤 단계가 필요한지 구분했다
각 역할의 입력과 출력이 명확하다
구현 담당의 작업 범위를 파일 또는 기능 단위로 좁혔다
검토 담당이 볼 기준을 요구사항·빌드·위험 변경 중심으로 정했다
처음부터 불필요하게 많은 역할을 만들지 않았다

정리

AI 코딩 작업에서 역할을 나누는 이유는 에이전트를 많이 쓰기 위해서가 아닙니다. 조사, 구현, 검토가 한꺼번에 섞여 결과가 흐려지는 것을 막기 위해서입니다.

작은 작업은 하나의 에이전트로 충분합니다. 하지만 기존 프로젝트를 읽고, 변경하고, 검토해야 하는 작업이라면 역할을 나누는 편이 안전합니다. 특히 검토 역할은 AI 결과를 실제 프로젝트에 넣기 전 마지막 안전장치로 생각하는 것이 좋습니다.

CLI 자동화가 실패할 때 먼저 확인할 것들

Wed, 08 Jul 2026 00:00:00 GMT

CLI 자동화를 만들다 보면 처음에는 잘 되다가 어느 순간 멈춥니다. 파일 하나가 예상과 다르거나, 권한이 없거나, 경로가 바뀌었거나, 조건을 너무 넓게 잡아서 엉뚱한 대상까지 처리하기도 합니다.

이때 가장 안 좋은 대응은 전체를 처음부터 다시 만드는 것입니다. 자동화 실패는 대부분 한 지점에서 시작됩니다. 먼저 해야 할 일은 그 지점을 찾는 것입니다.

전체가 아니라 멈춘 단계를 본다

자동화는 보통 여러 단계로 나뉩니다.

입력 파일을 찾는다
내용을 읽거나 변환한다
조건에 맞는지 판단한다
결과를 저장하거나 전송한다
필요하면 다음 작업을 실행한다

실패했을 때는 “자동화가 안 된다”가 아니라 “몇 번째 단계에서 멈췄는가”로 봐야 합니다.

예를 들어 PDF를 텍스트로 뽑고 AI에게 요약을 맡기는 흐름이라면, 문제는 AI 요약이 아닐 수 있습니다. PDF에서 텍스트가 제대로 안 뽑혔거나, 파일 경로가 틀렸거나, 빈 파일을 AI에게 넘겼을 수도 있습니다.

로그를 먼저 남긴다

입문자가 만든 스크립트는 실패했을 때 조용히 끝나는 경우가 많습니다. 그러면 어디서 멈췄는지 알 수 없습니다.

처음에는 멋진 로깅 도구가 없어도 됩니다. 단계마다 현재 무엇을 하는지 출력해도 충분합니다.

echo "1. 입력 파일 확인"
echo "2. 텍스트 추출 시작"
echo "3. 결과 파일 저장"

이런 단순한 출력만 있어도 어느 지점까지 갔는지 알 수 있습니다. 나중에 익숙해지면 로그 파일로 남기거나, 실패한 명령의 종료 코드를 확인하면 됩니다.

입력 데이터가 예상과 다른지 확인한다

자동화는 입력이 늘 같은 모양일 거라고 가정하기 쉽습니다. 하지만 실제 파일과 데이터는 자주 예외를 만듭니다.

파일명이 다르다
확장자가 대문자다
빈 파일이 섞여 있다
줄바꿈 방식이 다르다
한글 인코딩이 깨진다
CSV 열 개수가 예상과 다르다
PDF가 텍스트가 아니라 스캔 이미지다

특정 파일에서만 멈춘다면 그 파일 하나를 따로 열어 보세요. 전체 흐름이 아니라 그 입력이 다른 점을 찾는 것이 빠릅니다.

권한과 경로를 확인한다

리눅스와 WSL에서는 권한과 경로 문제도 흔합니다.

스크립트가 파일을 못 읽거나 못 쓰면 먼저 아래를 봅니다.

pwd
ls -l

현재 어느 폴더에서 실행 중인지, 파일 권한이 어떤지 확인합니다. 상대경로를 썼다면 실행 위치가 바뀌는 순간 다른 파일을 보게 됩니다.

특히 cron이나 백그라운드 작업으로 돌릴 때는 평소 터미널에서 실행할 때와 환경이 다를 수 있습니다. PATH, 작업 디렉터리, 환경변수가 다르면 같은 명령도 실패할 수 있습니다.

조건이 너무 넓거나 좁은지 본다

자동화 조건도 자주 문제를 만듭니다.

예를 들어 파일명을 기준으로 처리한다면 조건이 너무 넓어서 원치 않는 파일까지 잡을 수 있습니다. 반대로 너무 좁으면 처리해야 할 파일을 놓칩니다.

*.pdf만 처리한다고 했는데 대문자 .PDF는 빠진다
report가 들어간 파일만 찾다가 old_report_backup.pdf까지 처리한다
날짜 조건이 현지 시간과 UTC 차이 때문에 어긋난다
“완료”라는 단어를 기준으로 잡았는데 다른 문맥에도 등장한다

조건은 처음부터 실제 적용하지 말고, 먼저 대상 목록만 출력해 보는 편이 안전합니다.

find . -name "*.pdf" -print

삭제나 이동 전에 “무엇이 대상이 되는지”를 눈으로 확인하면 사고를 줄일 수 있습니다.

되돌리기 어려운 동작은 마지막에 붙인다

자동화에서 가장 위험한 동작은 되돌리기 어려운 동작입니다.

파일 삭제
원본 덮어쓰기
메일 자동 발송
외부 API에 실제 데이터 전송
데이터베이스 업데이트

처음부터 이런 동작을 켜두면 실패했을 때 피해 범위가 커집니다. 가능하면 처음에는 dry-run 방식으로 “무엇을 할 예정인지”만 출력하게 만드세요.

echo "삭제 예정: $file"
# rm "$file"  # 검증 전에는 주석 처리

확신이 생긴 뒤에 실제 동작을 켜도 늦지 않습니다.

AI 워크플로우도 중간 결과를 남긴다

AI 도구를 연결한 자동화도 결국 입력과 출력의 흐름입니다.

예를 들어 이런 구조라면:

PDF에서 텍스트 추출
추출 텍스트 정리
AI에게 요약 요청
요약 결과를 마크다운으로 저장

각 단계의 중간 결과를 남기는 것이 좋습니다. 그래야 요약이 이상할 때 원인을 나눠 볼 수 있습니다.

PDF 추출이 문제인지
전처리에서 내용이 사라졌는지
AI 프롬프트가 모호한지
저장 단계에서 깨졌는지

AI가 들어가면 결과가 그럴듯해 보여서 오히려 원인을 놓치기 쉽습니다. 그래서 더더욱 중간 파일과 로그가 필요합니다.

CLI 자동화 실패 점검 체크리스트

어느 단계에서 멈췄는지 로그로 확인했다
문제가 된 입력 파일 하나를 따로 열어 봤다
현재 실행 위치와 파일 권한을 확인했다
PATH, 환경변수, 작업 디렉터리가 평소와 같은지 봤다
조건이 너무 넓거나 좁지 않은지 대상 목록만 먼저 출력했다
삭제·발송·덮어쓰기 같은 동작은 검증 전까지 꺼두었다
AI에게 넘기기 전후의 중간 결과를 파일로 남겼다

정리

CLI 자동화가 실패했을 때는 전체를 다시 만들기보다 실패한 단계를 좁혀야 합니다. 입력 데이터, 권한과 경로, 조건, 환경 차이, 되돌리기 어려운 동작을 차례로 보면 대부분 원인이 드러납니다.

자동화는 한 번에 완성되는 일이 아닙니다. 처음에는 로그를 남기고, dry-run으로 확인하고, 중간 결과를 보존하는 식으로 안전하게 키워 가는 편이 좋습니다. 특히 AI 워크플로우는 결과가 그럴듯해 보일 수 있으니, AI가 무엇을 입력으로 받았는지부터 확인하는 습관이 중요합니다.

AI 에이전트 하나로 충분할 때와 나눠야 할 때

Wed, 08 Jul 2026 00:00:00 GMT

AI 코딩 도구를 쓰다 보면 어느 순간 이런 생각이 듭니다. “이 작업을 한 번에 맡겨도 될까, 아니면 조사 담당과 수정 담당을 나눠야 할까?” Claude Code, Codex, Gemini CLI처럼 에이전트식으로 움직이는 도구를 쓰면 더 자주 마주치는 고민입니다.

결론부터 말하면, 처음부터 나누지 않는 편이 좋습니다. 작업이 단순하면 에이전트 하나가 더 빠르고 명확합니다. 반대로 작업의 단계가 서로 다른 성격을 갖기 시작하면 그때 역할 분담을 생각해볼 만합니다.

하나로 충분한 작업

하나의 에이전트로 충분한 작업은 대체로 범위가 작고, 결과 확인도 단순합니다.

예를 들면 이런 작업입니다.

README 문구 한두 곳 고치기
특정 오류 메시지의 원인 설명 받기
작은 함수 하나 리팩터링하기
설정 파일의 옵션 의미 확인하기
이미 알고 있는 명령을 현재 프로젝트에 맞게 정리하기

이런 일은 조사, 구현, 검토가 크게 분리되지 않습니다. 에이전트를 나누면 오히려 설명하고 넘기는 시간이 더 듭니다.

나누는 편이 나은 작업

반대로 단계의 성격이 달라지면 하나의 에이전트에게 모두 맡겼을 때 결과가 흐려질 수 있습니다.

예를 들어 이런 작업입니다.

여러 파일을 읽고 원인을 찾아야 하는 버그 분석
새 기능을 만들기 전에 기존 구조를 조사해야 하는 작업
글이나 문서를 옮기면서 톤과 스키마를 같이 맞춰야 하는 작업
AI가 만든 코드를 별도 관점으로 검토해야 하는 작업
보안, 삭제, 배포처럼 실수 비용이 큰 변경

이럴 때는 역할을 나눌 이유가 생깁니다.

조사 담당: 현재 구조와 관련 파일을 읽는다
수정 담당: 실제 변경을 만든다
검토 담당: 요구사항을 빠뜨리지 않았는지, 위험한 변경이 없는지 본다

핵심은 에이전트 수가 아니라 책임 경계입니다. 누가 무엇을 확인할지 분명해야 나눈 의미가 있습니다.

나누기 전에 먼저 하나로 실행해 본다

입문 단계에서는 바로 멀티에이전트 구조를 짜기보다, 하나의 에이전트로 작게 실행해 보는 것이 좋습니다. 그래야 어느 지점에서 결과가 흐려지는지 보입니다.

예를 들어 “Gemini CLI 설치 글을 개선해줘”라고 한 번에 맡겼더니 설치 설명, 오류 대응, 썸네일 문구, 내부 링크가 뒤섞인다면 그때 나누면 됩니다.

1단계: 기존 글과 관련 파일 조사
2단계: 본문 리라이팅
3단계: 빌드와 이미지 검수

이렇게 나누면 각 단계에서 확인할 것이 분명해집니다.

나누면 생기는 비용도 있다

에이전트를 나누면 장점만 있는 것은 아닙니다. 역할이 많아질수록 관리할 것도 늘어납니다.

같은 내용을 여러 번 설명해야 합니다
앞 단계의 결과를 뒤 단계에 정확히 넘겨야 합니다
서로 다른 판단이 충돌할 수 있습니다
최종 책임은 여전히 사람이 져야 합니다

그래서 “나누면 더 좋아질까?”보다 “나누지 않으면 무엇이 흐려질까?”를 먼저 묻는 편이 좋습니다.

판단 기준

저는 보통 아래 질문으로 결정합니다.

에이전트를 나누기 전 체크리스트

작업이 조사·수정·검토처럼 다른 성격의 단계로 나뉘는가
한 에이전트에게 맡겼을 때 앞 지시와 뒤 지시가 섞일 가능성이 큰가
결과를 다른 관점에서 검토해야 할 만큼 위험하거나 중요한가
각 역할의 입력과 출력이 명확한가
나눠서 얻는 이득이 설명·관리 비용보다 큰가

정리

AI 에이전트는 하나로 충분할 때가 많습니다. 작업이 작고 결과 확인이 단순하다면 나누지 않는 편이 빠릅니다.

하지만 조사, 구현, 검토가 섞이기 시작하면 이야기가 달라집니다. 그때는 역할을 나눠 각 단계의 책임을 분명히 하는 것이 좋습니다. 멀티에이전트는 복잡해 보이기 위한 장식이 아니라, 복잡한 작업을 덜 헷갈리게 만드는 정리 도구입니다.

PDF를 AI 워크플로우에 넣기 전에 텍스트부터 확인하기

Wed, 08 Jul 2026 00:00:00 GMT

PDF를 AI 워크플로우에 붙일 때 처음에는 일이 아주 단순해 보입니다. PDF 파일을 넣고, 텍스트를 뽑고, 그 결과를 AI에게 넘기면 요약이나 분류가 끝날 것 같습니다. 실제로 작은 문서에서는 그렇게 보이기도 합니다.

그런데 문제는 “AI 답변이 자연스럽다”와 “AI가 원본을 제대로 읽었다”가 같은 말이 아니라는 데 있습니다. WSL이나 리눅스 터미널에서 PDF를 텍스트로 추출해 보면, 화면에서 보던 문서와 자동화가 읽은 텍스트가 꽤 다르게 나오는 경우가 있습니다.

저는 PDF 작업을 자동화할 때 이제 프롬프트부터 만지지 않습니다. 먼저 확인하는 것은 AI에게 넘기기 전의 입력 텍스트입니다.

자동화가 보는 것은 PDF 화면이 아니라 추출된 텍스트다

사람은 PDF를 볼 때 레이아웃을 같이 봅니다. 제목은 제목처럼 보이고, 표의 행과 열은 눈으로 맞춰 읽고, 페이지 번호나 꼬리말은 알아서 무시합니다.

하지만 자동화 흐름은 보통 다릅니다. 대략 이런 순서가 됩니다.

PDF 파일을 읽는다
PDF에서 텍스트를 추출한다
추출된 텍스트를 AI에게 넘긴다
AI가 요약·분류·정리를 한다

여기서 2번이 틀어지면 뒤의 3번과 4번도 같이 틀어집니다. AI가 아무리 답을 잘해도, 입력이 잘못 들어가면 그럴듯하게 틀린 결과가 나옵니다.

먼저 문장 하나를 복사해 본다

가장 단순한 1차 확인은 PDF에서 문장 하나를 드래그해서 복사해 보는 것입니다. 별것 아닌 확인처럼 보이지만, 이 단계에서 꽤 많은 문제가 드러납니다.

문장이 자연스럽게 복사되는가
줄이 문장 중간에서 이상하게 끊기지 않는가
한글이 깨지지 않는가
표 안의 글자가 엉뚱한 순서로 붙지 않는가
아예 선택이 안 되는 이미지 PDF는 아닌가

텍스트가 자연스럽게 복사되면 일단 출발점은 괜찮습니다. 반대로 선택이 안 되거나 줄바꿈이 심하게 깨지면 OCR이나 후처리 단계를 따로 생각해야 합니다.

위 이미지는 실제 업무 문서가 아니라 문제 상황을 재현한 샘플입니다. 핵심은 하나입니다. 화면에서는 한 문단처럼 보여도, 복사한 텍스트는 다른 구조일 수 있습니다.

텍스트 PDF와 스캔 PDF를 구분한다

PDF는 겉보기에는 비슷해도 내부 구조가 다릅니다.

텍스트 PDF는 문서 안에 글자 정보가 들어 있습니다. 그래서 드래그와 복사가 비교적 잘 됩니다. 이런 문서는 pdftotext 같은 도구나 라이브러리로 텍스트를 뽑는 흐름을 만들기 쉽습니다.

스캔 PDF는 종이를 사진처럼 넣어 둔 문서에 가깝습니다. 사람 눈에는 글자가 보이지만, 컴퓨터 입장에서는 이미지입니다. 이 경우 OCR로 글자를 읽어야 합니다.

OCR이 들어가면 난이도가 한 단계 올라갑니다. 글자를 읽는 것뿐 아니라, 흐릿한 숫자, 도장, 서명, 두 단 편집, 표 구조까지 같이 문제가 됩니다.

WSL·리눅스에서는 작은 샘플 파일로 먼저 시험한다

터미널에서 PDF 처리를 시작할 때는 처음부터 전체 폴더를 돌리지 않는 편이 좋습니다. 샘플 PDF 하나로 흐름을 확인한 뒤에 범위를 넓혀야 합니다.

예를 들어 pdftotext를 쓴다면, 먼저 설치 여부부터 확인합니다.

pdftotext -v

명령을 찾을 수 없다면 우분투에서는 보통 아래 패키지에 들어 있습니다.

sudo apt update
sudo apt install poppler-utils

그다음 바로 대량 처리하지 말고, 샘플 하나만 텍스트로 뽑아 봅니다.

pdftotext sample.pdf sample.txt

그리고 결과 파일을 엽니다.

less sample.txt

이때 확인할 것은 “파일이 만들어졌는가”가 아닙니다. 진짜 확인할 것은 아래입니다.

문단 순서가 원본과 비슷한가
제목과 본문이 섞이지 않았는가
페이지 번호가 본문처럼 들어오지 않았는가
표의 항목과 숫자가 떨어져 나가지 않았는가
한글이 깨지지 않았는가

이 확인 없이 바로 AI에게 넘기면, 나중에는 어디서 틀어졌는지 찾기가 더 어려워집니다.

표가 있는 PDF는 특히 조심한다

PDF 자동화에서 가장 자주 틀어지는 곳은 표입니다. 화면에서 보면 표는 명확합니다. 항목, 금액, 비고가 행과 열로 정리되어 있습니다.

하지만 텍스트로 뽑으면 행과 열의 관계가 사라질 수 있습니다.

예를 들어 원본에서는 서버 비용 옆에 50,000원이 붙어 있었는데, 추출 텍스트에서는 항목들이 먼저 나오고 숫자들이 나중에 몰려 나올 수 있습니다. 이 상태에서 AI에게 “비용표로 정리해줘”라고 하면, AI는 다시 깔끔한 표를 만들어 줍니다.

문제는 그 표가 원본과 같다는 보장이 없다는 점입니다. AI는 흩어진 값을 그럴듯하게 다시 맞춰 놓을 수 있습니다. 특히 견적서, 정산표, 매출표, 사용량 보고서처럼 숫자가 중요한 문서는 이 과정을 건너뛰면 위험합니다.

머리말·꼬리말·페이지 번호도 입력 오염이다

여러 페이지짜리 PDF를 텍스트로 추출하면 본문과 상관없는 문구가 반복해서 들어오는 일이 많습니다.

문서 제목
회사명
페이지 번호
작성일
저작권 문구
워터마크

사람은 이런 정보를 자연스럽게 무시하지만, AI에게 넘기는 입력에는 그대로 들어갑니다. 그러면 요약문에 같은 문구가 반복되거나, 페이지 번호가 본문 숫자처럼 섞이는 일이 생깁니다.

그래서 저는 긴 PDF를 다룰 때, AI 프롬프트를 고치기 전에 먼저 추출 텍스트를 봅니다. 반복되는 꼬리말이 계속 들어오고 있다면 그것은 프롬프트 문제가 아니라 입력 정리 문제입니다.

숫자와 날짜는 AI에게 보정시키지 않는다

OCR이나 추출 과정에서 숫자는 특히 조심해야 합니다.

0과 O
1과 l
쉼표와 마침표
마이너스 기호
날짜의 구분자
버전 번호

사람이 보면 어색한 10,00 같은 값도 AI는 문맥을 보고 자연스럽게 고쳐 버릴 수 있습니다. 겉보기에는 좋아 보이지만, 원본과 다르면 틀린 결과입니다.

숫자가 중요한 문서는 AI가 알아서 보정해 주는 것이 오히려 위험합니다. 금액, 날짜, 수량, 버전 번호가 들어간 PDF라면 추출 결과와 원본을 먼저 대조해야 합니다.

바로 자동화하지 말고 검수 지점을 남긴다

입문 단계에서 PDF 자동화는 “완전 자동”보다 “반자동”으로 시작하는 편이 안전합니다.

처음부터 전체 과정을 한 번에 묶기보다 아래처럼 중간 파일을 남겨 보세요.

pdftotext sample.pdf sample.txt

그리고 sample.txt를 눈으로 확인한 뒤 AI 요약이나 분류에 넘깁니다. 나중에 문제가 생겨도 “PDF 추출이 문제였는지, AI 요약이 문제였는지”를 나눠 볼 수 있습니다.

자동화에서 중간 결과를 남기는 것은 귀찮아 보이지만, 실제로는 디버깅 시간을 줄여 줍니다.

개인정보와 민감 정보는 먼저 걸러야 한다

PDF에는 생각보다 민감한 정보가 많이 들어갑니다.

이름
전화번호
이메일
주소
계약 조건
견적 금액
내부 프로젝트명
고객사 정보

AI 도구에 파일을 올리거나 API로 텍스트를 보내기 전에, 이 정보가 외부로 나가도 되는지 먼저 판단해야 합니다. 자동화가 편해 보여도 민감한 문서를 통째로 넘기는 것은 별개의 문제입니다.

PDF를 AI 워크플로우에 넣기 전 체크리스트

PDF에서 문장 하나를 복사해 봤다
텍스트 PDF인지 스캔 PDF인지 대략 구분했다
샘플 하나를 텍스트로 추출해 중간 결과를 확인했다
표의 항목과 숫자가 원본과 맞는지 봤다
머리말·꼬리말·페이지 번호가 반복해서 섞이는지 확인했다
금액·날짜·수량·버전 번호를 AI가 임의로 보정하지 않게 원본과 대조했다
개인정보와 민감 정보가 외부 AI 도구로 나가도 되는지 판단했다

정리

PDF 자동화에서 먼저 봐야 할 것은 AI 요약 품질이 아닙니다. 그보다 앞에 있는 텍스트 추출 품질입니다.

WSL이나 리눅스에서 PDF를 다룰 때는 샘플 하나를 텍스트로 뽑고, 줄바꿈·표·숫자·반복 문구를 확인한 뒤 다음 단계로 넘기는 습관을 들이는 편이 좋습니다. 그래야 AI가 만든 결과가 틀렸을 때도 원인을 좁힐 수 있습니다.

자동화는 입력을 빠르게 처리하게 해 줍니다. 그래서 입력이 틀리면 틀린 결과도 빠르게 만들어집니다. PDF는 특히 그 차이가 잘 드러나는 문서 형식입니다. 프롬프트를 고치기 전에, 먼저 AI가 실제로 무엇을 읽고 있는지 확인해 보세요.

메일 자동화를 AI에게 맡길 때 오발송을 막는 법

Sun, 05 Jul 2026 00:00:00 GMT

메일함에는 반복되는 일이 많습니다. 정기 알림에 라벨을 붙이고, 긴 보고 메일을 요약하고, 비슷한 문의에 답장 초안을 만드는 일입니다. 자동화 효과가 큰 영역이지만, 실수했을 때 피해도 큽니다.

특히 자동 삭제와 자동 회신은 잘못 실행되면 되돌리기 어렵습니다. 그래서 메일 자동화는 “전부 맡기기”보다 안전한 단계부터 AI에게 맡기고, 실제 발송은 사람이 승인하는 흐름으로 시작해야 합니다.

메일 자동화를 다섯 단계로 나눕니다

메일 처리 흐름은 보통 아래처럼 나눌 수 있습니다.

단계	하는 일	초기 자동화 권장 여부
읽기	메일 제목·본문 확인	조건부 가능
분류	발신자·제목·내용으로 분류	가능
요약	핵심 내용과 할 일 정리	가능, 원문 확인 필요
답장 초안	답변 문장 생성	가능, 사람 검토 필요
발송·삭제	실제 메일 전송·제거	초기에는 비추천

처음에는 분류와 요약까지만 자동화하세요. 답장 초안은 만들 수 있지만 발송 버튼은 사람이 누르는 구조가 좋습니다.

1단계: 자동화할 메일 한 종류만 정합니다

모든 메일을 한 번에 처리하려 하지 마세요. 패턴이 분명한 한 종류부터 고릅니다.

좋은 첫 대상:

정기 서버 상태 알림
뉴스레터나 업데이트 알림
같은 형식의 영수증·청구 안내
제목 규칙이 분명한 자동 보고서

처음부터 제외할 대상:

고객 불만이나 환불 요청
계약·결제·계정 관련 메일
수신자마다 답변이 크게 달라지는 문의
개인정보와 첨부파일이 많은 메일

2단계: 분류 조건을 좁게 잡습니다

“알림 메일”처럼 넓은 조건보다 발신자와 제목을 함께 씁니다.

발신자: alerts@example.com
제목에 포함: [Daily Status]
동작: Status 라벨 추가
금지: 삭제, 읽음 처리, 자동 답장

AI에게 분류 규칙을 만들게 할 때도 금지 조건을 함께 줍니다.

아래 샘플 메일을 기준으로 분류 조건을 만들어줘.
처음에는 라벨만 붙이고 삭제·이동·읽음 처리·답장은 하지 않게 해줘.
조건이 너무 넓지 않은지도 검토해줘.

3단계: 개인정보와 전달 범위를 확인합니다

메일에는 생각보다 많은 민감 정보가 들어 있습니다.

이름, 전화번호, 이메일 주소
주문번호, 계정번호, 결제 정보
내부 서버 주소와 오류 로그
인증 링크와 비밀번호 재설정 URL
계약서나 영수증 첨부파일

AI에게 전체 메일을 넘길 필요가 없다면 필요한 부분만 전달하세요. 예를 들어 요약에 첨부파일이 필요 없다면 첨부파일 접근 권한을 주지 않는 편이 좋습니다.

샘플을 만들 때는 이렇게 가릴 수 있습니다.

고객 이름: [REDACTED]
이메일: [REDACTED]
주문번호: [REDACTED]

4단계: 답장 초안과 발송을 분리합니다

메일 자동화에서 가장 중요한 안전장치입니다.

나쁜 흐름:

메일 수신 → AI 답장 생성 → 자동 발송

권장 흐름:

메일 수신 → AI 요약 → 답장 초안 생성 → 사람 검토 → 승인 후 발송

AI에게 답장 초안을 만들게 할 때 아래를 확인합니다.

수신자 이름과 회사명이 맞는가
날짜, 금액, 일정이 원문과 맞는가
확정하지 않은 일을 약속하지 않는가
내부 정보가 포함되지 않았는가
실제 질문에 답하고 있는가

5단계: 테스트 계정으로 먼저 실행합니다

실제 편지함 전체에 연결하기 전에 테스트 계정이나 샘플 메일로 확인하세요.

테스트 순서:

샘플 메일 한 건을 보낸다
트리거가 한 번만 실행됐는지 확인한다
올바른 라벨이 붙었는지 확인한다
AI 요약과 원문을 비교한다
답장 초안이 작성됐지만 발송되지 않았는지 확인한다
실행 로그에 민감 정보가 과하게 남지 않는지 확인한다

며칠간 실제 발송 없이 라벨링과 초안만 관찰한 뒤 확장하는 편이 좋습니다.

문제가 생기면 AI에게 이렇게 보여줍니다

자동화가 잘못 분류했을 때는 “왜 틀렸어?”보다 실제 입력과 조건을 함께 줍니다.

현재 분류 조건:
[조건 붙여넣기]

잘못 분류된 샘플:
발신자: [REDACTED]
제목: [샘플 제목]
본문 일부: [민감 정보 제거 후 붙여넣기]

원하는 결과:
이 메일은 자동 분류에서 제외해야 한다.
조건을 더 좁게 수정하고, 기존 메일에는 적용하지 않는 테스트 방법도 알려줘.

노코드 도구의 실행 로그가 있다면 실패한 단계와 에러 메시지만 함께 보여주세요.

자동 발송을 켜기 전 최소 조건

자동 발송은 충분히 검증한 뒤에도 제한적으로 적용해야 합니다.

정해진 템플릿만 사용한다
수신자 범위가 명확하다
금액·날짜·계약 내용을 생성하지 않는다
첨부파일을 자동으로 넣지 않는다
발송 내역이 로그에 남는다
언제든 자동 발송을 끌 수 있다
일정 기간 오발송 없이 테스트했다

이 조건을 만족하지 못하면 초안 생성까지만 자동화하는 편이 낫습니다.

안전한 메일 자동화 체크리스트

패턴이 분명한 메일 한 종류만 골랐다
첫 버전은 라벨링과 요약까지만 맡겼다
개인정보와 첨부파일 접근 범위를 확인했다
답장 초안과 실제 발송을 분리했다
테스트 계정과 샘플 메일로 먼저 실행했다
오류 로그와 자동화 중지 방법을 확인했다

정리

메일 자동화는 반복 업무를 크게 줄여주지만, 자동 삭제와 자동 발송은 위험합니다. 처음에는 패턴이 분명한 메일 하나를 골라 분류·라벨링·요약부터 맡기세요.

AI가 답장 초안을 만들 수는 있지만 실제 발송은 사람이 승인하는 흐름을 남기는 것이 좋습니다. 개인정보, 권한, 테스트 로그를 확인하면서 작은 단계부터 확장하면 안전하게 시간을 줄일 수 있습니다.

AI 자동화에서 노코드와 CLI를 어떻게 나눠 쓸까

Fri, 03 Jul 2026 00:00:00 GMT

AI 자동화를 알아보면 노코드 도구와 CLI가 함께 나옵니다. 노코드는 화면에서 블록을 연결하니 쉬워 보이고, CLI는 터미널 명령을 써야 하니 어렵게 느껴집니다.

하지만 둘의 차이는 난이도만이 아닙니다. 잘하는 일이 다릅니다.

노코드는 서비스와 흐름을 연결하기 좋고, CLI는 파일·로그·로컬 작업을 정확하게 처리하고 확인하기 좋습니다.

입문자는 둘 중 하나를 완전히 선택할 필요가 없습니다. 작업 단계를 나눠 잘 맞는 쪽에 맡기면 됩니다.

노코드가 잘 맞는 작업

노코드 도구는 “어떤 일이 생기면 다음 일을 한다”는 흐름을 눈으로 보기 좋습니다.

예를 들면:

새 메일이 오면 라벨을 붙인다
폼 응답이 오면 시트에 저장한다
정해진 시간에 워크플로우를 실행한다
결과가 나오면 메신저로 알림을 보낸다

트리거와 동작이 외부 서비스에 있을 때 특히 편합니다. 로그인과 권한 연결을 화면에서 진행할 수 있고, 어느 단계에서 멈췄는지 블록으로 확인할 수 있습니다.

CLI가 잘 맞는 작업

CLI는 내 컴퓨터나 WSL 안의 파일과 프로젝트를 다룰 때 강합니다.

특정 폴더에서 파일 찾기
PDF나 이미지 일괄 변환
로그에서 오류 줄 찾기
Git 변경 사항 확인
빌드와 테스트 실행
결과 파일 크기나 개수 확인

예를 들어 AI가 코드를 수정한 뒤 아래 명령으로 결과를 확인할 수 있습니다.

git status --short
npm run build

명령을 직접 깊게 작성할 필요는 없습니다. AI에게 만들어 달라고 하고, 무엇을 확인하는 명령인지 설명하게 하면 됩니다.

한 작업 안에서 둘을 나눠 봅니다

“새 문서를 AI로 요약하고 메신저로 알림 받기”를 예로 들겠습니다.

단계	어울리는 도구	이유
새 문서 감지	노코드	트리거 연결이 쉬움
파일 다운로드	노코드 또는 CLI	저장 위치에 따라 선택
텍스트 추출	CLI	파일 처리와 결과 검증이 쉬움
AI 요약	AI 도구	판단과 언어 처리가 필요
결과 저장	노코드 또는 CLI	대상 서비스에 따라 선택
알림 발송	노코드	메신저 연결이 쉬움

이렇게 나누면 노코드에 복잡한 파일 처리 코드를 억지로 넣지 않아도 되고, CLI에서 메신저 API를 처음부터 직접 연결하지 않아도 됩니다.

AI에게 연결 설계를 맡기는 방법

어려운 연결 구조는 AI에게 먼저 설계하게 할 수 있습니다. 다만 “자동화해줘”보다 조건을 구체적으로 줘야 합니다.

아래 자동화를 입문자 기준으로 설계해줘.
노코드가 편한 단계와 WSL CLI가 편한 단계를 나눠줘.

목표:
- 새 PDF가 생기면 텍스트를 추출한다.
- AI로 요약한다.
- 결과를 디스코드에 보낸다.

조건:
- 원본 PDF는 삭제하지 않는다.
- 각 단계의 입력과 출력을 표시한다.
- 실패하면 다음 단계로 넘어가지 않는다.
- 처음에는 실제 전송 대신 결과 미리보기까지만 만든다.
- 내가 확인할 로그와 테스트 방법도 알려준다.

AI가 설계안을 만들면 실제 서비스 이름과 계정 권한을 확인하고 적용합니다.

처음 연결할 때는 데이터 하나만 봅니다

노코드 흐름이 실패하는 흔한 이유는 다음 단계로 넘어가는 데이터 형태가 예상과 다르기 때문입니다.

처음에는 전체 흐름을 실행하지 말고 아래 순서로 확인하세요.

트리거가 테스트 데이터 하나를 받는지 확인
첫 단계 출력에서 파일명과 경로 확인
AI 단계에 실제로 전달된 텍스트 확인
마지막 전송 전 결과 미리보기

필요하면 각 단계 출력을 복사해 AI에게 보여주세요.

노코드 단계의 실제 출력은 아래와 같아.
다음 AI 단계에서는 text 필드가 필요한데 현재 어떤 필드를 연결해야 하는지 알려줘.

[테스트 출력 붙여넣기]

권한은 필요한 만큼만 연결합니다

노코드 도구는 메일, 드라이브, 문서, 메신저 계정 접근을 요구할 수 있습니다. 편하다고 모든 권한을 허용하면 위험합니다.

읽기만 필요한데 쓰기 권한까지 요구하는가
개인 계정 대신 테스트 계정을 쓸 수 있는가
연결을 해제하는 위치를 알고 있는가
AI에게 전달되는 데이터에 개인정보가 있는가
자동 전송 전에 사람이 확인할 수 있는가

처음에는 샘플 계정과 샘플 파일로 시험하는 편이 좋습니다.

실패했을 때 어디를 확인할까

노코드와 CLI를 함께 쓰면 경계에서 문제가 생길 수 있습니다. 이때 전체를 다시 만들지 말고 단계별로 확인합니다.

1. 트리거가 실행됐는가
2. 파일이 실제로 저장됐는가
3. CLI 명령이 성공했는가
4. 결과 파일이 비어 있지 않은가
5. AI 입력으로 전달됐는가
6. 마지막 전송 단계가 승인됐는가

CLI 결과를 확인할 때는 이런 명령이 도움이 됩니다.

ls -lh ./output
wc -c ./output/result.txt

파일이 만들어졌는지, 비어 있지 않은지 확인하는 정도면 충분합니다.

노코드·CLI 연결 체크리스트

각 단계를 트리거, 처리, AI 판단, 저장, 전송으로 나눴다
서비스 연결은 노코드, 로컬 파일·로그 처리는 CLI를 우선 검토했다
어려운 설정은 AI에게 요청하되 입력과 출력을 확인했다
계정 권한은 필요한 범위만 허용했다
처음에는 실제 발송 전에 결과 미리보기까지 테스트했다

정리

노코드와 CLI 중 하나가 항상 더 좋은 것은 아닙니다. 외부 서비스 연결과 트리거는 노코드가 편하고, 로컬 파일·로그·프로젝트 처리는 CLI가 단순한 경우가 많습니다.

입문자는 어려운 설정과 코드를 AI에게 맡겨도 됩니다. 대신 각 단계가 무엇을 받고 무엇을 내놓는지, 어떤 권한을 쓰는지, 실패 로그가 어디에 남는지는 확인해야 합니다.

무료 AI 도구로 자동화를 시험할 때 확인할 제한

Wed, 01 Jul 2026 00:00:00 GMT

새 AI 도구를 발견하면 무료 구간부터 써보게 됩니다. 대화창에서 질문 몇 번 해보고 답이 괜찮으면 자동화에도 쓸 수 있을 것 같지만, 실제로 연결해보면 다른 제한에서 막히곤 합니다.

자동화에서 확인해야 할 것은 “하루에 몇 번 쓸 수 있나”만이 아닙니다. 파일을 올릴 수 있는지, API가 있는지, 반복 실행이 가능한지, 한도가 끝났을 때 작업이 어떻게 멈추는지도 봐야 합니다.

무료 구간은 오래 버티는 요령보다 내 작업에 실제로 쓸 수 있는지 검증하는 기간으로 보는 편이 좋습니다.

먼저 검증할 작업 하나를 정합니다

무료 도구를 켜기 전에 이번에 확인할 목표를 하나만 정하세요.

PDF 한 개를 읽고 핵심 내용을 요약할 수 있는가?
빌드 오류 로그를 읽고 다음 점검 명령을 제안할 수 있는가?
마크다운 파일 다섯 개를 같은 기준으로 분류할 수 있는가?

“이 도구가 좋은가?”보다 “이 작업 하나를 끝낼 수 있는가?”로 질문을 좁히면 무료 한도를 덜 낭비합니다.

제한 1. 대화 사용량과 모델 제한

무료 구간에는 보통 시간 또는 기간별 사용량 제한이 있습니다. 더 중요한 것은 무료 모델과 유료 모델이 다를 수 있다는 점입니다.

확인할 항목은 다음과 같습니다.

무료에서 사용할 수 있는 모델
한도 초과 시 더 작은 모델로 바뀌는지
한도가 언제 다시 열리는지
긴 문서나 긴 로그를 한 번에 처리할 수 있는지

긴 로그를 자동화하려는데 문맥 길이가 부족하면 파일을 나눠 보내야 합니다. 이 과정이 매번 수동이라면 자동화 효과가 줄어듭니다.

제한 2. 파일 크기와 파일 형식

대화창에서 파일 첨부가 된다고 자동화에 바로 쓸 수 있는 것은 아닙니다.

PDF, CSV, 이미지, 압축파일을 지원하는가
한 파일의 크기 제한은 얼마인가
한 번에 여러 파일을 올릴 수 있는가
업로드한 파일이 얼마나 오래 보관되는가
파일 내용을 학습이나 서비스 개선에 사용하는 설정이 있는가

실제 자료를 올리기 전에 개인정보와 비밀값이 없는 샘플 파일로 시험하세요.

CLI에서 샘플 크기를 확인하려면 이 정도면 충분합니다.

ls -lh sample.pdf
wc -c sample.txt

AI에게 파일을 넘기기 전에 크기와 내용이 예상한 범위인지 확인하는 용도입니다.

제한 3. 대화창과 API는 별개일 수 있습니다

입문자가 가장 많이 놓치는 부분입니다. 웹 대화창을 무료로 쓸 수 있어도 API는 별도 과금일 수 있습니다.

자동화를 다른 도구와 연결하려면 보통 아래 중 하나가 필요합니다.

API 키
CLI 로그인
OAuth 연결
웹훅 또는 외부 도구 연동

AI에게 자동화 구성을 맡기기 전에 이렇게 물어보세요.

이 작업은 웹 대화창만으로 가능한가?
API나 별도 유료 기능이 필요한 단계는 어디인가?
무료 구간에서 확인할 수 있는 최소 테스트 흐름을 만들어줘.

이 질문을 먼저 하면 나중에 연결 단계에서 비용 구조가 바뀌는 일을 줄일 수 있습니다.

제한 4. 예약·반복 실행이 가능한가

한 번 실행하는 것과 매일 자동으로 실행하는 것은 다릅니다. 무료 구간에서는 수동 실행만 가능하고 예약 실행이나 백그라운드 작업은 제한될 수 있습니다.

확인할 항목:

예약 작업을 만들 수 있는가
컴퓨터가 꺼져 있어도 실행되는가
한 번 실패하면 다시 시도하는가
실행 로그를 볼 수 있는가
알림을 받을 수 있는가

무료 구간에서 예약 실행이 안 되더라도 작업 흐름 자체는 검증할 수 있습니다. 먼저 수동으로 한 번 성공시키고, 반복 실행이 정말 필요해졌을 때 유료 또는 다른 실행 방식을 검토하면 됩니다.

제한 5. 자동화가 끊겼을 때 어떻게 되는가

무료 한도가 끝났을 때 자동화가 조용히 멈추면 곤란합니다. 그래서 실패 동작을 미리 정해야 합니다.

한도 초과나 인증 실패가 나면 다음 단계로 넘어가지 않는다.
원본 파일은 그대로 둔다.
에러 메시지와 실행 시각을 로그로 남긴다.
사람에게 확인 알림을 보낸다.

AI에게 스크립트나 워크플로우를 만들어 달라고 할 때 이 조건까지 함께 넣으세요.

유료 전환을 검토할 시점

무료 한도에 한두 번 걸렸다고 바로 결제할 필요는 없습니다. 아래 신호가 반복될 때 검토하면 됩니다.

매일 쓰는 작업인데 한도 때문에 자주 멈춘다
파일이나 문맥 제한 때문에 매번 사람이 잘라 넣는다
API 또는 예약 실행이 꼭 필요하다
결과를 검수하는 시간보다 한도 관리 시간이 더 든다
도구가 내 작업 흐름에 이미 자리 잡았다

비용보다 중요한 기준은 “이 도구가 없으면 다시 손으로 반복해야 하는가”입니다.

무료 AI 자동화 테스트 체크리스트

이번에 검증할 작업을 하나만 정했다
무료 모델과 사용량 제한을 공식 안내에서 확인했다
파일 크기·형식·보관 조건을 확인했다
대화창과 API 비용이 별도인지 확인했다
한도 초과 시 멈춤·로그·알림 조건을 정했다
실제 자료 대신 안전한 샘플로 먼저 시험했다

정리

무료 AI 도구는 자동화 가능성을 시험하기에 충분히 유용합니다. 다만 대화 횟수만 볼 것이 아니라 파일, API, 반복 실행, 로그, 개인정보 조건까지 확인해야 합니다.

작은 샘플 하나로 흐름을 검증하고, 한도 관리 때문에 오히려 손이 더 많이 갈 때 유료 전환을 검토하세요. 무료 구간의 목표는 오래 버티는 것이 아니라 내 작업에 맞는지 판단하는 것입니다.

내 작업에 맞는 AI 비서 도구를 고르는 기준

Sun, 28 Jun 2026 00:00:00 GMT

AI 비서 도구를 찾아보면 이름이 많이 나옵니다. ChatGPT, Claude, Gemini 같은 대화형 AI도 있고, Claude Code, Codex, Gemini CLI 같은 코딩 도구도 있습니다. 여기에 OpenClaw나 Hermes처럼 메신저와 연결해 작업을 실행하는 비서 도구도 있습니다.

도구 이름부터 비교하면 헷갈립니다. 먼저 물어야 할 질문은 이것입니다.

나는 AI에게 대답을 듣고 싶은가, 코드를 고치게 하고 싶은가, 실제 작업을 실행하게 하고 싶은가?

이 질문에 따라 고를 도구가 달라집니다.

AI 비서 도구를 세 종류로 나눠 봅니다

입문자 관점에서는 세 종류로 나누면 쉽습니다.

종류	주로 하는 일	예시
대화형 AI	질문 답변, 요약, 아이디어 정리	ChatGPT, Claude, Gemini
AI 코딩 도구	코드 읽기, 수정, 테스트 제안	Claude Code, Codex, Gemini CLI
실행형 AI 비서	메신저·서버·PC에서 실제 작업 실행	OpenClaw, Hermes 계열 도구

셋은 경쟁 관계라기보다 역할이 다릅니다. 처음에는 내가 원하는 일이 어느 칸에 가까운지부터 보면 됩니다.

기준 1. 실제로 무엇을 맡길 것인가

도구를 고르기 전에 맡길 일을 한 문장으로 적어봅니다.

오류 로그를 붙여넣고 원인을 물어보고 싶다
로컬 프로젝트의 코드를 읽고 수정하게 하고 싶다
매일 아침 정해진 정보를 메신저로 받고 싶다
서버나 개인 PC에서 예약 작업을 돌리고 싶다

첫 번째라면 대화형 AI로 충분할 수 있습니다. 두 번째라면 AI 코딩 도구가 맞습니다. 세 번째와 네 번째라면 실행형 AI 비서를 고민할 만합니다.

기준 2. 어디에서 실행되는가

실행형 AI 비서는 보통 내 컴퓨터나 서버에서 동작합니다. 이 말은 장점과 부담이 함께 있다는 뜻입니다.

장점은 내 파일, 명령, 일정, 메신저와 연결해 실제 작업을 할 수 있다는 점입니다. 반대로 내 컴퓨터가 꺼져 있으면 멈추거나, 서버에 올리면 서버 관리가 필요할 수 있습니다.

입문자라면 처음부터 24시간 서버 운영을 목표로 하기보다, 먼저 로컬에서 작은 작업을 실행해보는 편이 좋습니다.

기준 3. 어떤 채널로 부를 것인가

AI 비서는 보통 대화창이나 메신저로 부릅니다.

터미널에서 바로 부를 것인가
디스코드나 텔레그램 같은 메신저로 부를 것인가
이메일이나 일정과 연결할 것인가
혼자 쓸 것인가, 팀 채널에서 쓸 것인가

평소 쓰지 않는 채널을 억지로 붙이면 오래 쓰기 어렵습니다. 본인이 이미 쓰는 도구와 맞는지가 중요합니다.

기준 4. 승인과 로그가 있는가

실행형 AI 비서는 실제 명령을 실행할 수 있습니다. 그래서 “얼마나 똑똑한가”보다 “실행 전에 멈춰서 확인할 수 있는가”가 중요합니다.

확인할 질문은 이렇습니다.

명령 실행 전에 승인 단계가 있는가?
어떤 파일을 바꿨는지 로그가 남는가?
실패했을 때 에러를 다시 볼 수 있는가?
권한을 제한할 수 있는가?

AI가 실제 행동을 할수록 안전장치가 중요합니다.

기준 5. 기억이 필요한가

어떤 도구는 이전 대화나 선호를 기억하는 데 강하고, 어떤 도구는 매번 새 작업처럼 처리합니다.

기억이 필요한 작업은 이런 경우입니다.

매번 같은 형식으로 보고서를 받고 싶다
특정 프로젝트의 규칙을 계속 유지하고 싶다
내가 선호하는 응답 방식이나 검수 기준이 있다

반대로 일회성 질문이 많다면 기억 기능보다 설치와 사용이 쉬운지가 더 중요합니다.

처음 고를 때 피할 것

입문 단계에서는 아래를 피하는 편이 좋습니다.

모든 기능을 비교하려고 하기
여러 도구를 동시에 설치하기
인증 토큰과 권한을 한꺼번에 많이 연결하기
자동 실행부터 켜기
개인 자료나 회사 자료를 검수 없이 넘기기

먼저 작은 작업 하나만 맡기세요. 예를 들어 “이 프로젝트에서 npm run build가 실패하면 로그를 읽고 다음 확인 순서를 알려줘” 정도면 충분합니다.

AI에게 도구 선택을 물어보는 방식

AI에게 “어떤 도구가 좋아?”라고 물으면 보통 유명한 도구 목록이 나옵니다. 대신 내 작업 조건을 주고 비교하게 만드는 편이 좋습니다.

나는 WSL에서 블로그와 자동화 작업을 하고 있어.
AI에게 맡기고 싶은 일은 다음과 같아.

- 로컬 프로젝트 빌드 실패 로그 확인
- 글 초안 검토
- 반복 작업 체크리스트 만들기
- 나중에는 디스코드에서 간단히 요청하기

대화형 AI, AI 코딩 도구, 실행형 AI 비서 중 무엇부터 쓰면 좋을지 비교해줘.
설치 난이도, 안전장치, 로그 확인 기준도 함께 알려줘.

이렇게 물어보면 도구 이름보다 내 상황에 맞는 선택 기준을 얻을 수 있습니다.

AI 비서 도구 선택 체크리스트

맡길 작업을 한 문장으로 적었다
대화형, 코딩형, 실행형 중 어디에 가까운지 구분했다
실행 위치가 로컬인지 서버인지 확인했다
승인, 로그, 권한 제한 기능을 확인했다
처음에는 작은 작업 하나만 맡기기로 했다

정리

AI 비서 도구는 기능이 많다고 무조건 좋은 것이 아닙니다. 내가 맡기려는 작업, 실행 위치, 부르는 채널, 승인과 로그, 기억 기능이 내 방식에 맞아야 오래 씁니다.

처음에는 하나만 고르세요. 작은 작업 하나를 맡겨보고, 불편한 점이 구체적으로 보이면 그때 다른 도구를 비교해도 늦지 않습니다.

AI에게 작업을 나눠 맡길 때 역할 정의서 쓰는 법

Thu, 25 Jun 2026 00:00:00 GMT

AI 도구에 일을 맡기다 보면 “이건 조사용 AI, 이건 구현용 AI, 이건 검토용 AI로 나누면 좋겠다”는 생각이 듭니다. 실제로 작업을 나누면 더 깔끔해질 때가 있습니다.

하지만 역할 이름만 나누면 오히려 복잡해집니다. “조사 담당”, “정리 담당”, “검토 담당”이라는 이름은 그럴듯하지만, 무엇을 받아서 무엇을 내놓아야 하는지 없으면 AI가 서로 같은 일을 하거나 필요한 정보를 빠뜨립니다.

그래서 필요한 것이 역할 정의서입니다.

역할 이름보다 입력과 출력이 먼저입니다

좋은 역할 정의는 아래 질문에 답할 수 있어야 합니다.

이 역할은 무엇을 받는가?
무엇을 해야 하는가?
무엇을 어떤 형식으로 내놓는가?
무엇은 하지 말아야 하는가?
다음 역할은 이 결과를 어떻게 쓰는가?

예를 들어 “조사 담당”이라고만 쓰면 모호합니다.

더 좋은 정의는 이렇습니다.

역할: 조사 담당
입력: 글 주제와 독자 수준
해야 할 일: 공식 문서와 실제 사례를 찾아 핵심 근거를 정리한다
출력: 출처 URL, 핵심 요약, 주의할 점을 표로 작성한다
금지: 확인되지 않은 수치를 단정하지 않는다

이렇게 쓰면 다음 역할이 무엇을 받아야 하는지 분명해집니다.

처음에는 2~3개 역할만 나눕니다

역할이 많다고 좋은 것은 아닙니다. 입문 단계에서는 아래 정도면 충분합니다.

역할	맡길 일	출력물
조사	자료와 조건 확인	근거 목록, 주의점
작업	수정, 초안, 스크립트 작성	변경안, 실행 방법
검토	누락·위험·오류 확인	수정 요청 목록

이 구조는 코딩 작업에도, 문서 작업에도, 자동화 작업에도 쓸 수 있습니다.

중요한 것은 “작업 역할”과 “검토 역할”을 분리하는 것입니다. 같은 AI에게 만들기와 검토를 모두 시키면 자기 실수를 지나칠 수 있습니다.

AI 코딩 작업 예시

예를 들어 티발자랩 블로그 글을 고치는 작업을 AI에게 나눠 맡긴다고 해보겠습니다.

조사 역할

역할: 조사 담당
입력: 수정할 글 제목과 현재 글 본문
해야 할 일: 제목이 약속한 내용과 본문이 맞는지 확인한다
출력: 부족한 부분, 보강할 섹션, 삭제해도 되는 반복 표현 목록
금지: 본문을 직접 수정하지 않는다

수정 역할

역할: 수정 담당
입력: 조사 담당의 보강 목록과 원문
해야 할 일: 티발자랩 톤에 맞게 본문을 수정한다
출력: 수정된 본문 또는 패치
금지: 글의 핵심 주제와 발행일을 임의로 바꾸지 않는다

검토 역할

역할: 검토 담당
입력: 수정된 본문
해야 할 일: 제목과 본문이 맞는지, 위험한 명령이 과한지, 입문자 관점인지 확인한다
출력: 통과/수정 필요와 이유
금지: 새 내용을 크게 추가하지 않고 검토에 집중한다

이렇게 나누면 각 AI가 하는 일이 겹치지 않습니다.

역할 사이에 넘길 결과물을 정합니다

멀티에이전트에서 자주 생기는 문제는 “앞 역할이 뭘 넘겼는지”가 흐릿한 것입니다.

조사 역할이 출처 없이 요약만 넘기면 검토 역할은 근거를 확인할 수 없습니다. 수정 역할이 어떤 파일을 바꿨는지 남기지 않으면 검토 역할은 diff를 볼 수 없습니다.

그래서 각 역할의 출력 형식을 미리 정합니다.

조사 결과는 표로 작성한다.
수정 결과는 변경한 파일 목록과 함께 제공한다.
검토 결과는 통과/수정 필요/보류 중 하나로 표시한다.

형식이 있으면 AI 결과를 사람이 확인하기도 쉬워집니다.

역할 정의서 템플릿

아래 템플릿을 그대로 써도 됩니다.

역할 이름:

입력:
- 

해야 할 일:
- 

출력 형식:
- 

하지 말아야 할 일:
- 

검수 기준:
-

처음에는 이 정도만 있어도 충분합니다. 복잡한 에이전트 프레임워크를 몰라도, 역할 정의서가 있으면 AI에게 일을 나눠 맡기기 쉬워집니다.

AI 역할 분담 체크리스트

역할 수를 2~3개로 제한했다
각 역할의 입력과 출력이 분명하다
역할끼리 하는 일이 겹치지 않는다
검토 역할을 따로 두었다
각 역할이 하지 말아야 할 일을 적었다

정리

AI에게 작업을 나눠 맡길 때 중요한 것은 멋진 구조가 아닙니다. 각 역할이 무엇을 받고, 무엇을 만들고, 무엇을 하지 말아야 하는지 분명히 하는 것입니다.

처음에는 조사, 작업, 검토 정도로 작게 나누세요. 역할 정의서가 선명하면 AI가 만든 결과도 이어 붙이기 쉬워지고, 사람이 검수할 지점도 분명해집니다.

자동화 도구와 AI 도구, 입문자는 무엇부터 써야 할까

Tue, 23 Jun 2026 00:00:00 GMT

자동화를 시작하려고 하면 도구 이름이 한꺼번에 나옵니다. n8n, Zapier, Make 같은 자동화 도구도 있고, ChatGPT, Claude, Gemini, Codex 같은 AI 도구도 있습니다. 여기에 WSL, CLI, 스크립트까지 나오면 어디서 시작해야 할지 헷갈립니다.

먼저 구분해야 할 것은 도구 이름이 아닙니다.

내 작업이 정해진 절차의 반복인지, 매번 판단이 필요한 일인지부터 봐야 합니다.

이 기준을 잡으면 무엇부터 써야 할지 훨씬 쉬워집니다.

자동화 도구는 규칙 반복에 강합니다

자동화 도구는 “이 조건이면 이 작업을 한다”가 분명한 일에 강합니다.

예를 들면 이런 작업입니다.

새 파일이 생기면 특정 폴더로 복사한다
매일 아침 정해진 자료를 모은다
빌드가 끝나면 알림을 보낸다
특정 메일이 오면 라벨을 붙인다

이런 작업은 판단보다 절차가 중요합니다. 조건과 순서가 분명하면 자동화 도구가 잘 처리합니다.

AI 도구는 판단이 필요한 일에 강합니다

AI 도구는 매번 내용이 달라지는 일에 강합니다.

예를 들면 이런 작업입니다.

긴 로그에서 원인 후보 찾기
회의록에서 결정 사항만 요약하기
코드 변경의 위험한 부분 찾기
문서 초안을 읽기 좋게 다듬기
자동화 스크립트 초안 만들기

이런 일은 같은 명령을 반복한다고 해결되지 않습니다. 내용을 읽고 판단해야 하므로 AI가 잘 맞습니다.

같은 작업 안에서도 역할이 나뉩니다

예를 들어 “PDF 자료를 요약해서 정리하기”라는 작업을 봅니다.

단계	맞는 도구	이유
PDF 파일 목록 찾기	자동화 도구 / CLI	규칙이 분명함
PDF를 텍스트로 변환	CLI / 스크립트	반복 처리 가능
텍스트가 비어 있는지 확인	CLI	검증 가능
핵심 내용 요약	AI 도구	판단과 언어 처리가 필요
결과 저장	자동화 도구 / CLI	절차가 분명함

하나의 작업 안에서도 규칙 단계와 판단 단계가 나뉩니다. 이걸 구분하면 도구 선택이 쉬워집니다.

입문자는 무엇부터 시작하면 좋을까

처음에는 둘을 한 번에 연결하지 않는 편이 좋습니다. 어디서 문제가 생겼는지 찾기 어렵기 때문입니다.

WSL·CLI는 어디에 필요한가

티발자랩에서 WSL과 CLI를 다루는 이유는 리눅스 전문가가 되기 위해서가 아닙니다. AI와 자동화 도구가 만든 결과를 확인하려면 최소한의 실행 환경과 확인 명령이 필요하기 때문입니다.

예를 들어 AI가 “이 명령을 실행해 보세요”라고 했을 때 아래 정도는 확인할 수 있어야 합니다.

pwd
ls
git status --short
npm run build

이 명령들은 사람 대신 개발을 하기 위한 것이 아니라, AI가 한 작업이 맞는지 확인하기 위한 기본 도구입니다.

잘못 고르면 생기는 문제

자동화 도구와 AI 도구를 잘못 고르면 이런 일이 생깁니다.

규칙이 분명한 파일 이동을 AI에게 맡겨 결과가 매번 달라진다
판단이 필요한 문서 요약을 규칙 자동화로 억지로 처리한다
처음부터 여러 도구를 연결해 어디서 실패했는지 모른다
AI가 만든 스크립트를 검수하지 않고 바로 실행한다

도구가 나쁜 것이 아니라 역할을 잘못 맡긴 것입니다.

AI에게 이렇게 물어보면 좋습니다

도구 선택이 헷갈릴 때는 AI에게 바로 도구명을 묻기보다 작업을 나눠 달라고 요청하세요.

아래 작업을 자동화하고 싶어.
이 작업을 규칙 단계와 AI 판단 단계로 나눠줘.
각 단계에 어울리는 도구도 추천해줘.
처음 입문자가 안전하게 시작할 수 있는 순서로 정리해줘.

작업:
[내가 줄이고 싶은 작업 설명]

이렇게 물어보면 “무슨 도구를 써야 하지?”에서 “어떤 단계를 먼저 줄일까?”로 관점이 바뀝니다.

도구 선택 전 체크리스트

줄이고 싶은 작업을 한 문장으로 적었다
규칙 반복 단계와 AI 판단 단계를 나눴다
처음에는 도구 하나 또는 단계 하나만 자동화하기로 했다
AI가 만든 결과를 사람이 확인할 지점을 정했다
삭제·덮어쓰기·외부 전송은 첫 버전에 넣지 않기로 했다

정리

자동화 도구와 AI 도구는 경쟁 관계가 아닙니다. 역할이 다릅니다. 자동화 도구는 정해진 절차를 반복하는 데 강하고, AI 도구는 매번 달라지는 내용을 판단하는 데 강합니다.

입문자는 도구부터 고르기보다 작업을 먼저 나누면 됩니다. 규칙 단계와 판단 단계를 구분하고, 작은 단계 하나를 AI와 함께 성공시키는 것부터 시작하세요.

AI 자동화란 무엇이고 어디까지 맡기면 좋을까

Sun, 21 Jun 2026 00:00:00 GMT

“AI 자동화”라는 말을 들으면 뭔가 거창해 보입니다. 서버를 띄우고, 여러 도구를 연결하고, 코드도 짜야 할 것 같습니다. 하지만 입문자 관점에서 보면 핵심은 더 단순합니다.

AI 자동화는 반복되는 일 중에서 사람이 매번 판단하던 부분을 AI에게 맡기고, 사람은 결과를 확인하는 흐름입니다.

중요한 건 처음부터 모든 일을 자동으로 돌리는 것이 아닙니다. AI에게 맡길 부분과 사람이 봐야 할 부분을 나누는 것입니다.

자동화는 반복 절차를 맡기는 일입니다

일반 자동화는 규칙이 분명한 일을 잘합니다.

예를 들어 이런 일입니다.

매일 같은 폴더에서 새 파일을 찾기
빌드 전에 git status 확인하기
PDF 파일을 텍스트 파일로 변환하기
특정 로그 파일을 찾아 목록으로 보여주기

이런 작업은 “언제, 어떤 조건이면, 무엇을 한다”가 비교적 분명합니다. 그래서 사람이 매번 손으로 하지 않아도 컴퓨터가 반복할 수 있습니다.

AI 자동화는 판단이 섞인 반복을 맡기는 일입니다

현실의 작업에는 단순 반복만 있는 것이 아닙니다.

오류 로그를 보고 원인을 추정하기
긴 문서에서 필요한 부분만 요약하기
코드 변경 내용을 보고 위험한 부분을 찾기
여러 파일 중 어느 것을 먼저 고쳐야 할지 판단하기

이런 일은 규칙만으로 처리하기 어렵습니다. 바로 이 지점에 AI가 들어갑니다.

예를 들어 PDF 처리 흐름이라면 일반 자동화는 PDF를 텍스트로 바꾸는 일을 맡고, AI는 그 텍스트를 읽고 요약하거나 분류하는 일을 맡습니다. 사람은 중간 텍스트가 제대로 뽑혔는지, AI 요약이 말이 되는지 확인합니다.

티발자랩식 AI 자동화는 이렇게 봅니다

티발자랩에서 말하는 AI 자동화는 “AI가 다 알아서 하니 나는 아무것도 몰라도 된다”가 아닙니다.

반대로 이렇게 봅니다.

사람: 작업 목표와 금지 조건을 정한다
AI: 명령, 스크립트, 설정 초안을 만든다
사람: 경로, 삭제, 덮어쓰기, 로그, 결과를 확인한다
AI: 오류 로그를 보고 다음 수정안을 제안한다
사람: 적용 여부를 결정한다

이 구조라면 리눅스나 CLI를 전문가처럼 깊게 파지 않아도 됩니다. 대신 AI가 만든 결과를 확인할 만큼의 기본기는 필요합니다.

예를 들어 아래 명령의 의미 정도는 알아두면 좋습니다.

git status --short
npm run build
ls
pwd

이 명령들은 “직접 개발을 다 하기 위한 명령”이라기보다, AI가 작업한 결과를 확인하고 다시 설명하기 위한 도구입니다.

처음 맡기기 좋은 작업의 조건

첫 AI 자동화는 작아야 합니다. 아래 세 가지를 만족하는 작업이 좋습니다.

1. 자주 반복된다

한 달에 한 번 하는 일보다 매일 또는 매주 반복하는 일이 좋습니다. 자동화는 만드는 데도 시간이 들기 때문에, 자주 반복될수록 효과가 큽니다.

2. 입력과 출력이 분명하다

AI에게 이렇게 말할 수 있어야 합니다.

입력: ./logs 폴더의 에러 로그
출력: 에러 원인 후보와 다음 확인 명령 목록

입력과 출력이 흐릿하면 AI도 추측하게 됩니다.

3. 틀려도 되돌릴 수 있다

처음부터 삭제, 결제, 발송, 배포처럼 되돌리기 어려운 작업을 맡기면 위험합니다. 먼저 목록 확인, 요약 초안, 파일 변환처럼 사람이 확인하고 넘어갈 수 있는 작업이 좋습니다.

AI에게 맡기기 전 이렇게 요청합니다

처음 요청은 길어도 괜찮습니다. 오히려 조건을 자세히 줄수록 안전합니다.

WSL에서 반복 작업을 자동화하고 싶어.

목표:
- ./docs 폴더의 PDF 파일을 텍스트로 바꾸고 싶다.

조건:
- 원본 파일은 삭제하지 않는다.
- 기존 파일을 덮어쓰지 않는다.
- 첫 버전은 실제 처리 전에 대상 목록만 보여준다.
- 각 명령이 무엇을 확인하는지 설명해준다.
- 실패하면 어떤 로그를 나에게 보여줘야 하는지도 알려준다.

이렇게 요청하면 AI가 만든 결과를 검수하기 쉬워집니다.

사람이 꼭 확인해야 할 지점

AI가 만든 자동화 결과에서 먼저 볼 부분은 정해져 있습니다.

어떤 폴더를 대상으로 하는가
원본 파일을 삭제하거나 이동하지 않는가
기존 파일을 덮어쓰지 않는가
실패했을 때 멈추는 조건이 있는가
실행 후 확인할 명령이 있는가
외부 전송, 배포, 결제, 메일 발송이 포함되어 있지 않은가

이 정도만 봐도 많은 사고를 막을 수 있습니다.

첫 AI 자동화 후보 체크리스트

자주 반복되는 작업이다
입력과 출력이 한 문장으로 설명된다
틀려도 원본을 잃지 않는다
AI가 만든 결과를 사람이 한 번 확인할 수 있다
실패했을 때 보여줄 로그나 에러 메시지가 있다

정리

AI 자동화는 거창한 기술 이름이 아니라, 반복되는 일의 일부를 AI에게 맡기고 사람이 검수하는 작업 방식입니다. WSL과 CLI는 이 흐름을 더 잘 확인하기 위한 도구입니다.

처음부터 모든 것을 자동으로 돌리려고 하지 마세요. 작은 작업 하나를 고르고, AI에게 조건을 자세히 알려주고, 결과를 확인하는 단계부터 시작하면 충분합니다.

티발자랩

라즈베리파이5 AI 머신 세팅 1: 우분투 서버 설치와 SSD 부팅

라즈베리파이는 어떤 컴퓨터인가

이번 설치에 준비한 것

1. Raspberry Pi Imager 설치하기

2. 장치와 Ubuntu Server 선택하기

3. 저장소에서 USB 메모리 선택하기

4. 호스트 이름 정하기

5. 지역·시간대·키보드 설정하기

6. 사용자 이름과 비밀번호 만들기

7. Wi-Fi 미리 설정하기

8. SSH 원격 접속 켜기

9. 이미지 쓰기와 완료 확인

10. USB와 SSD를 연결해 첫 부팅하기

11. lsblk로 USB와 SSD 구분하기

12. SSD의 기존 서명 지우기

13. dd로 USB 전체를 SSD에 복사하기

14. 전원을 끄고 USB 제거 후 재부팅하기

15. SSD로 부팅됐는지 확인하기

정리

공식 자료

터미널 반복 작업을 자동화 흐름으로 나누는 법

1단계: 자동화할 작업을 한 문장으로 좁힌다

2단계: 손으로 하던 일을 단계로 나눈다

3단계: AI에게 줄 작업 정의서를 만든다

4단계: AI가 만든 결과에서 볼 것

입력 경로가 맞는가

출력 위치가 안전한가

실패 조건이 있는가

위험 명령이 있는가

5단계: 처음에는 확인 모드로 요청한다

6단계: AI에게 다시 물어볼 로그를 남긴다

7단계: AI 워크플로우를 붙일 때도 중간 파일을 남긴다

정리

첫 CLI 자동화 전에 점검할 5가지

1. 자동화할 작업을 한 문장으로 좁힌다

2. 입력과 출력 예시를 적는다

3. 하지 말아야 할 일을 먼저 적는다

4. 처음에는 확인 모드로 요청한다

5. 실패했을 때 AI에게 보여줄 정보를 정한다

AI에게 바로 줄 수 있는 요청 예시

정리

AI 코딩 도구에 코드 올리기 전 확인할 것들

먼저 “AI에게 필요한 정보”를 좁힌다

비밀값이 들어갈 수 있는 파일을 먼저 분리한다

프로젝트 안에서 의심 단어를 검색한다

로그에서 가릴 정보를 확인한다

AI에게 넘길 최소 묶음을 만든다

회사·고객 자료는 내 판단만으로 올리지 않는다

정리

AI 코딩 도구를 쓰기 전에 알아두면 좋은 기본기

1. 터미널에 익숙해지기

2. 파일·폴더와 경로 개념 잡기

3. Git 기초 익히기

4. 요청을 구체적으로 적는 습관

5. 작은 단위로 시키기

6. 결과를 확인하는 습관

초보자가 자주 막히는 부분

정리

Claude Code 처음 설치하고 실행해보기

Claude Code가 어떤 도구인가

설치 전에 갖춰야 할 것

Node.js가 준비됐는지 확인하기

설치와 첫 실행의 흐름

1. 공식 안내에서 설치 방법 확인

2. 패키지 매니저로 설치

3. 작업 폴더로 이동해서 실행

4. 첫 인증(로그인)

도구가 파일을 다룰 때 거치는 확인 절차

초보자가 자주 막히는 부분

정리

bash와 zsh, 입문자는 무엇부터 쓰면 좋을까

셸이란 무엇인가

bash와 zsh는 어떻게 다른가

기본 제공 여부

자동완성과 테마

플러그인 생태계

설정 파일

지금 내 셸을 확인하고 바꾸는 법

현재 셸 확인

11. `lsblk`로 USB와 SSD 구분하기

13. `dd`로 USB 전체를 SSD에 복사하기