터미널에서 AI 에이전트 쓰기 — 완전 입문 가이드

컴퓨터를 잘 몰라도 따라 할 수 있게 만든 안내서입니다.
Windows 11 기준이며, 처음부터 끝까지 순서대로 따라 하면 됩니다.
예상 소요 시간: 설치 30분 + 첫 사용 20분

이 문서를 읽는 방법

• 바로 시작하고 싶다면: 아래 가장 간단 — 최단 경로 요약만 따라 하세요. 막히면 그때 해당 절을 펼쳐 보면 됩니다.
• 처음이라면: 1부부터 순서대로 읽으세요. 건너뛰지 마세요.
• 터미널을 이미 써 봤다면: 2부를 건너뛰고 3부부터 보세요.
• 회색 상자 안의 글자는 컴퓨터에 입력하는 명령어입니다. 그대로 복사해서 붙여넣으면 됩니다.
• 각 단계마다 "제대로 됐는지 확인하기" 항목이 있습니다. 반드시 확인하고 다음으로 넘어가세요.
• 부록 E는 문제가 생겼을 때만 보는 선택 설정입니다. 처음에는 건너뛰세요.

가장 간단 — 최단 경로 요약

전체를 읽을 시간이 없다면 이 순서만 따라 하면 됩니다. 각 단계 끝의 절 번호에 자세한 설명과 문제 해결 방법이 있습니다.

1. 터미널 열기

1. 키보드에서 Windows 키 를 누릅니다 (창문 모양이 그려진 키, 보통 왼쪽 Ctrl 옆에 있습니다).
2. 나타난 검색창에 터미널 이라고 입력합니다.
3. 터미널 이라는 앱이 나오면 Enter 를 누릅니다.

검은색(또는 파란색) 창이 열리고 이런 글자가 보이면 성공입니다.

PS C:\Users\홍길동>

→ 자세히: 2.1절

2. Node.js 설치하기

터미널에 아래를 입력하고 Enter.

winget install --id OpenJS.NodeJS.LTS -e

확인 — 기존 터미널을 닫고 새 터미널에 입력합니다.

node --version

이런 결과가 나오면 성공입니다. 숫자는 달라도 됩니다.

v24.9.0

→ 자세히: 3.2절

3. Git 설치하기

터미널에 아래를 입력하고 Enter.

winget install --id Git.Git -e

확인 — 터미널을 새로 열고 입력합니다.

git --version

git version 2.52.0.windows.1

이런 결과가 나오면 됩니다. 안 나오면 터미널을 새로 켜서 다시 설치하세요.

→ 자세히: 3.3절

4. AI 에이전트 설치하기

구독 중인 것 하나만 설치하면 됩니다.

a. Claude Code (Claude 구독자)

터미널에 입력합니다.

irm https://claude.ai/install.ps1 | iex

안 되면 아래를 터미널에 입력합니다.

npm install -g @anthropic-ai/claude-code

확인 — 터미널을 완전히 닫고 새로 연 뒤 입력합니다.

claude --version

b. Codex CLI (ChatGPT 구독자)

터미널에 입력합니다.

irm https://chatgpt.com/codex/install.ps1 | iex

안 되면

npm install -g @openai/codex

그래도 안 되면

winget install --id OpenAI.Codex -e

확인 — 터미널을 완전히 닫고 새로 연 뒤 입력합니다.

codex --version

→ 자세히: 4.2절(Claude Code) · 4.3절(Codex CLI)

5. 로그인하고 시작하기

먼저 작업할 폴더를 만들고 그 안으로 들어갑니다. 바탕화면이나 C:\Users\내이름 에서 실행하지 마세요.

mkdir C:\AI연습

cd C:\AI연습

그 상태에서 설치한 것을 입력하고 Enter.

claude

codex

처음이면 로그인 화면이 뜹니다. 브라우저에서 구독 계정으로 로그인하고 터미널로 돌아오면 됩니다. 다음부터는 로그인 없이 바로 시작됩니다.

→ 자세히: 5.1절 ~ 5.3절

6. Orca 로 여러 에이전트를 동시에 (선택)

Orca는 여러 AI 코딩 에이전트를 동시에 돌리기 위한 프로그램입니다. 4단계까지 마쳤다면 준비는 이미 끝났습니다.

a. 설치하기

1. 웹브라우저로 https://www.onorca.dev 에 접속합니다.
2. Download 버튼을 누릅니다.
3. Windows 용 설치 파일(orca-windows-setup.exe)을 내려받습니다.
4. 내려받은 파일을 더블클릭합니다.
5. 설치 창이 뜨면 기본값 그대로 계속 진행합니다.

b. 사용하기

1. 왼쪽 Projects 옆의 폴더에 + 가 붙은 아이콘(Add Project)으로 작업할 폴더를 추가합니다. 그 폴더는 Git 저장소여야 합니다. 아니라면 그 폴더에서 터미널을 열고 git init 을 한 번 실행하세요.
2. 프로젝트 이름 위의 +(New workspace)를 눌러 작업공간을 만듭니다.
3. 실행 화면의 드롭다운에서 쓸 에이전트를 고르고, 평소처럼 한국어로 지시합니다.
4. 작업공간을 두 개, 세 개 더 만들면 그게 병렬 실행입니다.

처음에는 승인 방식을 Manual 로 바꾸세요. Orca는 권한 확인을 건너뛰는 옵션이 기본으로 켜져 있습니다.

→ 자세히: Orca 병렬 AI 에이전트 입문 가이드

7. 필수 명령어 5개

대화창 안에서 쓰는 것은 사실상 이 다섯 개입니다. 이것만 알면 막히지 않습니다.

→ 자세히와 사용량 한도: 5.0절

8. 기능 늘리기 — MCP·플러그인 (선택)

한글(HWP) 문서, 법령, 국가통계처럼 AI가 기본으로 못 하는 일은 확장을 설치해서 붙입니다. 설치 명령을 찾을 필요 없이, 저장소 주소를 주고 시키면 됩니다.

https://github.com/chrisryugj/kordoc 이거 사용할 수 있게 전역적으로 설치해줘.

설치가 끝나면 터미널을 완전히 닫고 새로 엽니다.

→ 자세히: 7부

1부. 왜 터미널에서 AI를 쓰는가

1.1 지금 쓰는 AI 챗봇과 무엇이 다른가

웹브라우저에서 ChatGPT나 Claude를 쓸 때의 흐름은 이렇습니다.

나: "이 엑셀 파일 정리하는 방법 알려줘"
AI: (방법을 글로 설명해 줌)
나: (설명을 읽고 → 엑셀을 열고 → 직접 손으로 작업)

AI는 말로만 알려주고, 실제 작업은 사람이 합니다. 파일을 AI에게 하나씩 올려야 하고, AI가 준 답을 다시 복사해서 붙여넣어야 합니다.

터미널에서 쓰는 AI 에이전트는 흐름이 다릅니다.

나: "이 폴더의 엑셀 파일들 정리해줘"
AI: (폴더를 직접 열어봄 → 파일을 직접 읽음 → 직접 수정함 → 결과 보고)
나: (확인만 함)

핵심 차이는 하나입니다. AI가 내 컴퓨터의 파일을 직접 읽고 쓸 수 있다는 것.

1.2 실제로 무엇을 할 수 있나

프로그래머가 아니어도 쓸 수 있는 일들을 분야별로 묶었습니다.

문서·자료 정리

• 폴더에 흩어진 PDF 100개의 제목과 요약을 표로 만들기
• 파일 이름을 일정한 규칙으로 한꺼번에 바꾸기
• 여러 워드 파일에서 특정 내용만 뽑아서 하나로 합치기

데이터 작업

• 엑셀/CSV 파일의 오류 찾아 고치기
• 여러 개의 표를 하나로 합치고 통계 내기
• 데이터를 그래프로 그려서 이미지 파일로 저장하기

연구·학술

• 논문 초안의 문장을 학술적 톤으로 다듬기
• 참고문헌 형식을 저널 규정에 맞게 통일하기
• 실험 데이터를 처리하는 스크립트를 만들고 실행하기

일상 업무

• 반복되는 보고서 양식을 자동으로 채우기
• 웹에서 자료를 모아 정리하기
• 이메일 초안을 여러 건 한꺼번에 만들기

프로그래밍 (관심 있다면)

• 프로그램을 처음부터 만들기
• 남이 만든 코드를 이해하고 고치기

1.3 자주 하는 걱정에 대한 답

"프로그래밍을 몰라도 되나요?"

됩니다. 한국어로 "이거 해줘"라고 말하면 됩니다. 다만 터미널 창을 여는 법과 명령어 몇 개는 알아야 하는데, 그건 2부에서 다룹니다. 30분이면 익힙니다.

"내 파일을 망가뜨리면 어쩌죠?"

AI 에이전트는 파일을 수정하기 전에 "이렇게 바꿔도 될까요?"라고 매번 물어봅니다. 사용자가 승인해야만 실행합니다. 게다가 8부에서 안내하는 안전 수칙(백업, 폴더 분리)을 지키면 위험은 거의 없습니다.

"내 파일이 외부로 새어 나가나요?"

AI가 읽은 파일 내용은 답변을 만들기 위해 서버로 전송됩니다. 이건 웹 챗봇에 파일을 업로드하는 것과 같습니다. 개인정보, 미공개 연구 데이터, 회사 기밀은 작업 폴더에 두지 마세요. 자세한 내용은 8부에 있습니다.

"돈이 드나요?"

기본적으로 유료 구독이 필요합니다. 이미 ChatGPT Plus나 Claude Pro를 쓰고 있다면 추가 비용 없이 그 구독으로 이용할 수 있습니다. Google의 Antigravity CLI는 Google 계정으로 로그인하면 일정량을 무료로 쓸 수 있습니다(정확한 한도는 공식 문서를 확인하세요). 4.1절에 정리해 두었습니다.

"리눅스를 깔아야 하나요? WSL이 필요한가요?"

아닙니다. Windows에서 그대로 쓰면 됩니다. 예전에는 일부 도구가 Windows를 지원하지 않아 WSL(리눅스 환경)이 필요했고 그 시절 자료가 아직 많이 남아 있지만, 지금은 세 도구 모두 Windows 전용 설치본을 제공합니다. 자세한 판단 기준은 부록 D에 있습니다.

"검은 화면이 무서워요."

가장 흔한 반응입니다. 하지만 실제로 쓰는 명령어는 5개 정도이고, 나머지는 전부 한국어로 대화하는 것입니다. 검은 화면은 그냥 AI와 대화하는 창이라고 생각하면 됩니다.

2부. 터미널 기초 — 30분이면 충분합니다

프로그래머가 되려는 게 아닙니다. AI에게 일을 시킬 수 있을 정도만 배웁니다.

2.1 터미널이란 무엇인가

터미널은 컴퓨터에게 글자로 명령을 내리는 창입니다.

평소에는 마우스로 폴더를 더블클릭해서 엽니다. 터미널에서는 cd 폴더이름이라고 타이핑해서 엽니다. 결과는 똑같습니다. 방법만 다릅니다.

왜 굳이 이걸 쓰냐면, AI 에이전트가 이 방식으로만 동작하기 때문입니다. 마우스로 클릭하는 화면이 없습니다.

터미널 열어보기

1. 키보드에서 Windows 키 를 누릅니다 (창문 모양이 그려진 키, 보통 왼쪽 Ctrl 옆에 있습니다).
2. 나타난 검색창에 터미널 이라고 입력합니다.
3. 터미널 이라는 앱이 나오면 Enter 를 누릅니다.

검은색(또는 파란색) 창이 열리고 이런 글자가 보일 겁니다.

PS C:\Users\홍길동>

이게 정상입니다. 뜻은 이렇습니다.

• PS = PowerShell(파워셸)의 약자. 명령을 받아주는 프로그램 이름입니다.
• C:\Users\홍길동 = 지금 내가 있는 위치(폴더). 이게 가장 중요합니다.
• > = "명령을 입력하세요"라는 신호. 이 뒤에 타이핑하면 됩니다.

기억할 것: 터미널에는 항상 "현재 위치"가 있습니다. 탐색기 창에서 특정 폴더를 열어둔 상태와 똑같습니다. 명령은 모두 그 위치를 기준으로 실행됩니다.

2.2 명령어의 구조

명령어는 대부분 이 형태입니다.

명령어 대상 -옵션

예를 들어 보겠습니다.

cd Documents

• cd = 명령어 ("이 폴더로 이동해라"라는 뜻, change directory의 약자)
• Documents = 대상 (이동할 폴더 이름)

명령어를 입력한 뒤에는 반드시 Enter 를 눌러야 실행됩니다. Enter를 누르기 전까지는 아무 일도 일어나지 않으니, 오타가 나도 당황하지 말고 지우면 됩니다.

2.3 폴더와 경로 이해하기

컴퓨터의 폴더는 서랍장처럼 층층이 들어 있습니다.

C:\                          ← C드라이브 (가장 바깥)
└── Users\                   ← 사용자 폴더
    └── 홍길동\               ← 내 폴더
        ├── Documents\        ← 문서
        ├── Downloads\        ← 다운로드
        └── Desktop\          ← 바탕화면

이걸 한 줄로 쓴 것이 경로(path) 입니다.

C:\Users\홍길동\Documents

역슬래시(\)가 서랍의 구분선입니다. 한글 키보드에서는 원화 기호(₩)로 보이는데, 같은 글자입니다. 걱정하지 마세요.

경로를 손으로 타이핑하지 않는 방법 (중요)

경로를 직접 입력하면 오타가 나기 쉽습니다. 훨씬 쉬운 방법이 있습니다.

방법 1 — 탐색기에서 복사하기
1. 파일 탐색기에서 원하는 폴더를 엽니다.
2. 위쪽 주소창을 한 번 클릭합니다. 경로가 글자로 바뀝니다.
3. Ctrl + C 로 복사합니다.
4. 터미널에서 cd 를 입력하고 (cd 다음에 한 칸 띄고), 마우스 오른쪽 버튼을 한 번 클릭하면 붙여넣기가 됩니다.

방법 2 — 탐색기에서 바로 터미널 열기 (가장 편함)
1. 파일 탐색기에서 원하는 폴더를 엽니다.
2. 폴더 안 빈 공간에 마우스 오른쪽 클릭을 합니다.
3. "터미널에서 열기" 를 선택합니다.

이러면 그 폴더 위치에서 터미널이 바로 열립니다. 앞으로 이 방법을 주로 쓰게 됩니다.

주의: 경로에 띄어쓰기가 있으면 큰따옴표로 감싸야 합니다.
틀림: cd C:\내 문서\연구 자료
맞음: cd "C:\내 문서\연구 자료"

2.4 꼭 알아야 할 명령어 5개

이것만 알면 됩니다.

PowerShell에서 실행하세요.
아래 명령은 PowerShell(2.1절에서 연 터미널 앱의 기본값)에서 동작합니다. 옛 명령 프롬프트(cmd)에서는 ls, pwd 가 없어 오류가 납니다. 프롬프트가 PS C:\...> 로 시작하면 PowerShell, C:\...> 로만 시작하면 명령 프롬프트입니다. 후자라면 창을 닫고 터미널 앱을 새로 여세요.

① cd — 폴더 이동하기

cd Documents

Documents 폴더로 들어갑니다.

cd ..

점 두 개는 한 단계 위로(바깥으로) 나가기입니다.

cd \

C드라이브 맨 바깥으로 갑니다.

② ls — 지금 폴더에 뭐가 있는지 보기

ls

현재 폴더의 파일과 폴더 목록이 나옵니다. 탐색기로 폴더를 들여다보는 것과 같습니다.

③ pwd — 내가 지금 어디 있는지 확인

pwd

현재 위치의 전체 경로를 보여줍니다. 길을 잃었을 때 씁니다.

④ mkdir — 새 폴더 만들기

mkdir 내연구

현재 위치에 내연구라는 폴더가 생깁니다.

⑤ cls — 화면 지우기

cls

화면이 지저분해졌을 때 깨끗하게 만듭니다. 파일이 지워지는 게 아니라 화면만 정리됩니다.

2.5 알아두면 편한 조작법

Tab 키 자동완성은 꼭 익히세요. cd Doc 까지만 치고 Tab을 누르면 cd Documents\ 로 알아서 완성됩니다. 오타를 막아줍니다.

2.6 지금 바로 연습해 보기

터미널을 열고 아래를 순서대로 입력해 보세요. 한 줄 입력할 때마다 Enter를 누릅니다.

pwd

→ 내 위치가 나옵니다.

ls

→ 파일 목록이 나옵니다.

cd Documents

→ 문서 폴더로 들어갑니다.

pwd

→ 위치가 바뀐 게 보입니다.

mkdir AI연습

→ 새 폴더가 만들어집니다.

ls

→ 방금 만든 AI연습 폴더가 목록에 보입니다.

cd ..

→ 다시 밖으로 나옵니다.

여기까지 됐다면 터미널 기초는 끝입니다. 정말로 이게 전부입니다.

잘 안 될 때

어떤 오류가 나도 컴퓨터는 고장 나지 않습니다. 마음 편히 여러 번 해보세요.

3부. 설치 준비 — 기반 프로그램 3가지

AI 에이전트를 설치하기 전에, 그것이 돌아가는 데 필요한 프로그램들을 먼저 깝니다.

3.0 무엇을 왜 설치하는가

모두 무료이고 안전한 공식 프로그램입니다.

실행 정책·한글 깨짐 설정은 지금 하지 않습니다.
예전에는 설치 전에 미리 해 두라고 안내했지만, 요즘 설치본은 대부분 이 설정 없이도 그대로 설치됩니다. 필요 없는 설정을 미리 건드릴 이유가 없으므로 부록 E 로 옮겼습니다. 설치나 실행 중에 스크립트를 실행할 수 없으므로 또는 한글이 ??? 로 깨지는 문제가 생기면 그때 부록 E를 보고 처리하세요.

Node.js가 "권장"인 이유
예전에는 AI 에이전트가 전부 npm(Node.js에 포함된 설치 도구)으로만 설치됐습니다. 지금은 Claude Code·Antigravity CLI·Codex CLI 모두 Node.js 없이 바로 설치되는 전용 설치본을 제공합니다. 그래도 Node.js를 깔아두길 권합니다. 설치 문제가 생겼을 때 대안 경로가 되고, AI가 만드는 도구 중 상당수가 Node.js를 씁니다. 시간을 아끼고 싶다면 3.2절을 건너뛰고 4부로 가도 됩니다.

3.1 Windows Terminal 설치

Windows 11에는 대부분 이미 설치되어 있습니다. 2.1절에서 터미널이 잘 열렸다면 이 단계는 건너뛰세요.

없다면 터미널(또는 명령 프롬프트)에 아래를 입력합니다.

winget install --id Microsoft.WindowsTerminal -e

3.2 Node.js 설치 (권장)

Node.js는 프로그램을 실행하고 설치해 주는 기반 엔진입니다. AI 에이전트를 npm 방식으로 설치할 때 쓰이고, AI가 만들어 주는 도구를 돌릴 때도 자주 필요합니다.

설치 방법 A — 명령어로 (권장, 빠름)

터미널에 아래를 입력하고 Enter.

winget install --id OpenJS.NodeJS.LTS -e

설치가 진행되고 몇 분 걸립니다. 설치 완료 또는 Successfully installed 라는 글자가 나오면 끝입니다.

설치 방법 B — 홈페이지에서 내려받기

명령어가 안 먹히면 이 방법을 씁니다.

1. 웹브라우저로 https://nodejs.org 에 접속합니다.
2. 초록색 버튼 중 "LTS" 라고 쓰인 것을 클릭합니다. (LTS = 장기 지원 안정 버전. Current 버전은 고르지 마세요.)
3. 내려받은 파일(node-v24...msi)을 더블클릭합니다.
4. 설치 창이 뜨면 아무것도 바꾸지 말고 계속 "Next" 를 누릅니다.
5. Automatically install the necessary tools... 체크박스가 나오면 체크하지 마세요. (필요 없고 오래 걸립니다.)
6. "Install" → 완료되면 "Finish".

제대로 됐는지 확인하기 (반드시 하세요)

터미널 창을 완전히 닫고, 새로 엽니다. (이 과정을 빼먹으면 설치했는데도 안 된다고 나옵니다.)

새 터미널에 입력합니다.

node --version

이런 결과가 나오면 성공입니다.

v24.9.0

숫자는 달라도 됩니다. v 로 시작하는 버전 번호가 나오면 됩니다. (2026년 9월 기준 LTS는 24.x 계열이고, 22.x도 아직 지원됩니다.)

npm --version

이것도 확인합니다. 10.9.2 같은 숫자가 나오면 됩니다.

node는 무엇이고 npm은 무엇인가요?
node는 엔진이고, npm은 프로그램을 설치해 주는 도구입니다. Node.js를 깔면 둘 다 같이 설치됩니다.

안 될 때

'node'은(는) ... 인식되지 않습니다 라고 나온다면:

1. 터미널을 닫고 새로 열었는지 확인하세요. (가장 흔한 원인입니다.)
2. 그래도 안 되면 컴퓨터를 재부팅하고 다시 확인하세요.
3. 그래도 안 되면 9.1절을 보세요.

3.3 Git 설치

Git은 원래 프로그래머가 파일 변경 이력을 관리하는 도구인데, AI 에이전트가 내부적으로 사용합니다. 사용법을 배울 필요는 없고, 깔아두기만 하면 됩니다.

Windows에서는 이유가 하나 더 있습니다. Git을 설치하면 함께 깔리는 Git Bash를 Claude Code가 자동으로 감지해 명령 실행용 셸로 씁니다. 인터넷에 널려 있는 리눅스식 명령어가 그대로 통해서 오류가 눈에 띄게 줄어듭니다. 필수는 아니지만 깔아두는 편이 낫습니다.

winget install --id Git.Git -e

홈페이지에서 받으려면 https://git-scm.com/download/win 에서 내려받아 설치합니다. 설치 창에서 선택 항목이 많이 나오는데, 전부 기본값 그대로 두고 Next 를 눌러도 문제없습니다.

확인하기

터미널을 새로 열고 입력합니다.

git --version

git version 2.52.0.windows.1

이런 결과가 나오면 됩니다.

3.4 3부 마무리 점검

새 터미널을 열고 아래를 하나씩 입력해 전부 버전이 나오는지 확인합니다.

node --version

npm --version

git --version

세 개 모두 버전 번호가 나오면 준비 완료입니다. 하나라도 안 나오면 9부 문제 해결을 보세요.

4부. AI 에이전트 설치하기

4.1 어떤 것을 고를까

세 가지 중 하나를 고르면 됩니다. 처음이라면 하나만 설치해서 익숙해진 뒤 늘리세요.

추천

• 돈을 안 쓰고 먼저 경험해 보고 싶다 → Antigravity CLI (4.4절)
• 이미 ChatGPT Plus를 쓰고 있다 → Codex CLI (4.3절)
• 이미 Claude Pro를 쓰고 있거나, 문서·연구 작업이 주 목적이다 → Claude Code (4.2절)

세 개를 다 설치해도 서로 충돌하지 않습니다. 다만 처음에는 하나로 시작하세요.

Gemini CLI를 찾으신다면
Google의 gemini 명령(Gemini CLI)은 2026년 6월 18일부로 개인 사용자 지원이 종료되었습니다. 후속 도구가 아래 4.4절의 Antigravity CLI(agy) 입니다. 인터넷의 옛 자료는 아직 npm install -g @google/gemini-cli 를 안내하지만, 지금 그 방법으로 설치하면 로그인 단계에서 막힙니다. 자세한 사정은 4.4절에 정리해 두었습니다.

4.2 Claude Code 설치

설치 방법 A — 전용 설치본 (권장)

터미널에 입력합니다.

irm https://claude.ai/install.ps1 | iex

1~3분 정도 걸립니다. Node.js가 없어도 되고, 이후 업데이트도 알아서 처리됩니다. 처음이라면 이 방법을 쓰세요.

irm ... | iex 는 "인터넷에서 설치 스크립트를 받아 바로 실행하라"는 뜻입니다. 주소가 claude.ai 인지 확인하고 실행하세요. 출처가 불분명한 주소로는 절대 쓰지 마세요.

설치 방법 B — npm으로 (Node.js가 이미 있다면)

npm install -g @anthropic-ai/claude-code

진행 중에 글자가 여러 줄 지나가는 건 정상입니다. WARN 이라는 노란 경고가 몇 개 나와도 무시하면 됩니다. ERR! 라는 빨간 오류가 나오면 9부를 보세요. Node.js 22 이상이 필요합니다.

-g 는 "컴퓨터 전체에 설치하라"는 뜻입니다. 이걸 붙여야 어느 폴더에서든 쓸 수 있습니다.
sudo npm install -g 처럼 관리자 권한을 붙이는 방식은 쓰지 마세요. 권한이 꼬입니다.

둘 중 하나만 하세요. 이미 npm으로 깔았다면 claude install 을 실행해 전용 설치본으로 옮길 수 있습니다.

확인하기

터미널을 완전히 닫고 새로 연 뒤 입력합니다.

claude --version

버전 번호와 함께 (Claude Code) 라고 나오면 성공입니다.

로그인하기

작업할 폴더를 하나 만들고 그 안에서 실행합니다.

mkdir C:\AI작업

cd C:\AI작업

claude

처음 실행하면 순서대로 이런 것들을 묻습니다.

1. 테마(색상) 선택 — 화살표 키로 고르고 Enter. 아무거나 상관없습니다.
2. 로그인 방식 선택 — 두 가지가 나옵니다. (문구는 버전에 따라 조금씩 다릅니다.)
   - 구독 계정으로 로그인 → Claude Pro/Max 구독자용. 대부분 이걸 고릅니다.
   - Console(API) 계정으로 로그인 → 사용한 만큼 돈을 내는 방식. 회사·기관 계정이 있는 경우.
3. 브라우저가 자동으로 열립니다. Claude 계정으로 로그인하고 "Authorize" 를 누릅니다.
4. 화면에 긴 문자열(코드)이 나옵니다. 그걸 복사해서 터미널에 붙여넣고 Enter.
5. 폴더 신뢰 여부를 묻습니다. Yes, proceed 를 고릅니다.

이제 대화창이 뜹니다. 로그인은 한 번만 하면 되고, 다음부터는 claude 만 치면 바로 시작됩니다.

알아두면 좋은 명령

대화창 안에서 / 로 시작하는 특별한 명령을 쓸 수 있습니다.

4.3 OpenAI Codex CLI 설치

설치 방법 A — 전용 설치본 (권장)

irm https://chatgpt.com/codex/install.ps1 | iex

설치 방법 B — npm으로

npm install -g @openai/codex

설치 방법 C — winget으로

winget install --id OpenAI.Codex -e

셋 중 하나만 하세요. 여러 방법으로 설치하면 버전이 꼬여서 나중에 원인을 찾기 어렵습니다.

확인하기

터미널을 새로 열고 입력합니다.

codex --version

로그인하기

codex login

브라우저가 열립니다. ChatGPT 계정으로 로그인하면 됩니다. ChatGPT Plus / Pro 구독자는 추가 결제 없이 구독에 포함된 사용량으로 이용합니다.

로그인이 잘 됐는지 확인하려면:

codex login status

실행하기

작업 폴더로 이동한 뒤 입력합니다.

codex

4.4 Antigravity CLI 설치 (Gemini CLI의 후속)

먼저 알아둘 것 — Gemini CLI는 끝났습니다

Google은 2026년 5월 19일 Gemini CLI와 Gemini Code Assist IDE 확장의 개인 사용자 지원 종료를 발표했고, 2026년 6월 18일부로 실제 서비스가 중단되었습니다. 후속 도구가 Antigravity CLI이며 터미널 명령어는 agy 입니다.

아직 Gemini CLI를 쓸 수 있는 경우: Gemini Code Assist Standard/Enterprise 라이선스 보유자, Google Cloud를 통한 Code Assist for GitHub 사용자, 유료 Gemini API 키 보유자. 여기 해당하지 않는 개인 사용자는 로그인 자체가 되지 않습니다.

이미 Gemini CLI를 깔아두었다면 먼저 지웁니다.

npm uninstall -g @google/gemini-cli

설치

관리자 권한이 아닌 일반 PowerShell에 입력합니다.

irm https://antigravity.google/cli/install.ps1 | iex

설치본은 C:\Users\사용자이름\AppData\Local\agy\bin 에 들어가고, 설치 스크립트가 PATH 등록까지 해 줍니다.

명령 프롬프트(cmd)를 쓴다면 대신 이렇게 합니다.
curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd && install.cmd && del install.cmd

확인하기

터미널을 완전히 닫고 새로 연 뒤 입력합니다.

agy --version

버전 번호가 나오면 성공입니다. agy 를 못 찾는다는 오류가 나면 십중팔구 터미널을 새로 열지 않아서입니다. 그래도 안 되면 9.1절을 보세요.

로그인하기

작업 폴더로 이동한 뒤 실행합니다.

agy

브라우저가 자동으로 열립니다. Google 계정으로 로그인하고 권한을 허용하면 터미널로 돌아와 대화창이 준비됩니다. 로그인 정보는 Windows 자격 증명 관리자에 저장되므로 다음부터는 agy 만 치면 바로 시작됩니다.

첫 실행 시 작업 폴더를 신뢰하는지(Workspace Trust) 묻습니다. 본인이 만든 폴더라면 신뢰를 선택합니다.

알아두면 좋은 명령

업데이트

설치 스크립트를 다시 실행하면 최신 버전으로 올라갑니다.

irm https://antigravity.google/cli/install.ps1 | iex

5부. 첫 사용 — 실제로 시켜보기

5.0 먼저 외울 것 — 필수 명령어 5개

대화창 안에서 쓰는 것은 사실상 이 다섯 개입니다. 이것만 알면 막히지 않습니다.

도구마다 명령이 조금씩 다릅니다.
위 다섯 개는 Claude Code 기준입니다. Codex CLI·Antigravity CLI 는 이름이 다르거나 없는 것도 있습니다. 대화창에서 /help 를 입력하면 그 도구가 실제로 가진 명령과 단축키가 전부 나옵니다. 막히면 /help 부터 보세요.

사용량은 "일정 기간" 단위로 회복됩니다

구독료를 냈다고 무한히 쓸 수 있는 게 아닙니다. AI 회사들은 정해진 기간 안에 쓸 수 있는 양(토큰) 을 배정하고, 그 기간이 지나면 다시 채워 줍니다. 그래서 한도에 걸려도 기다리면 풀립니다.

읽는 방법 — "5시간 단위"는 처음 지시를 보낸 시점부터 5시간이 한 묶음이라는 뜻입니다. 그 안에서 배정량을 다 쓰면 다음 묶음이 시작될 때까지 기다려야 합니다. 여기에 주 단위 한도가 겹쳐 있어서, 며칠 몰아서 많이 쓰면 5시간 한도가 남아 있어도 주 한도에 먼저 걸릴 수 있습니다.

정확한 수치는 여기 적지 않습니다.
배정량은 요금제(Pro·Max·Plus 등)와 시점에 따라 자주 바뀝니다. 숫자를 외우는 대신 /usage 로 그때그때 확인하는 습관을 들이세요.

사용량을 아끼는 방법 3가지

• 주제가 바뀌면 /clear — 대화가 길어지면 이전 내용을 매번 다시 읽어 들여 사용량을 많이 먹습니다. 새 주제를 시작할 때는 대화를 비우세요.
• 쉬운 일은 가벼운 모델로 — /model 로 바꿉니다. 파일 정리나 단순 변환에 무거운 모델을 쓸 이유가 없습니다.
• 작업 폴더를 작게 유지 — AI가 훑어야 할 파일이 적을수록 덜 먹습니다. 8부의 "전용 작업 폴더" 원칙이 사용량 측면에서도 유리합니다.

두 갈래 중 하나를 고르세요

여기서부터는 길이 둘로 갈립니다. 어느 쪽을 먼저 해도 괜찮습니다. 순서가 정해져 있지 않고, 한쪽을 했다고 다른 쪽을 못 하는 것도 아닙니다.

① 터미널에서 연습하기 — 아래 5.1절부터 그대로 읽으면 됩니다. 도구가 실제로 무엇을 하는지, 승인 화면이 어떻게 생겼는지 눈으로 익히기에는 이쪽이 낫습니다. 문제가 생겼을 때 원인을 찾는 감각도 여기서 생깁니다.

② Orca로 바로 써보기 — 검은 화면이 부담스럽거나, 처음부터 여러 작업을 동시에 돌려보고 싶다면 이쪽입니다. Orca 입문 가이드 로 넘어가세요. Orca는 4부에서 설치한 AI CLI를 그대로 가져다 쓰므로, 4부까지 마쳤다면 준비는 이미 끝났습니다.

권하는 순서: ①을 30분 해보고 ②로 넘어가는 것입니다. Orca는 결국 4부의 도구들을 여러 개 띄우는 껍데기라서, 그 도구가 무엇인지 알고 나면 훨씬 쉽게 이해됩니다. 다만 이건 권유일 뿐이고, ②부터 시작해도 아무 문제 없습니다.

5.1 작업 폴더 준비하기

AI 에이전트는 "실행한 폴더" 안의 파일만 다룹니다. 이게 안전장치이기도 합니다.

바탕화면이나 C:\Users\내이름 같은 곳에서 실행하지 마세요. 그러면 AI가 컴퓨터의 모든 파일을 뒤질 수 있게 됩니다.

연습용 폴더를 하나 만듭니다.

mkdir C:\AI연습

cd C:\AI연습

5.2 연습용 파일 만들기

빈 폴더에서는 할 게 없으니, 연습용 파일을 하나 만들어 봅니다.

notepad 메모.txt

메모장이 열리면 "파일을 만들겠냐"고 묻습니다. "예" 를 누르고, 아무 내용이나 몇 줄 적은 뒤 Ctrl + S 로 저장하고 닫습니다.

예시:

2026년 1월 매출: 1200만원
2026년 2월 매출: 1450만원
2026년 3월 매출: 980만원

5.3 AI 실행하고 대화하기

claude

(Codex를 설치했으면 codex, Antigravity CLI면 agy 를 입력합니다.)

대화창이 뜨면 한국어로 그냥 말하면 됩니다.

첫 질문으로 이렇게 쳐 보세요.

이 폴더에 어떤 파일이 있는지 확인하고 내용을 요약해줘

AI가 폴더를 살펴보고 메모.txt 를 읽은 뒤 요약해 줄 것입니다.

다음으로 이렇게 시켜 봅니다.

메모.txt의 매출 데이터를 표 형태로 정리하고, 
평균과 증감률을 계산해서 매출정리.md 파일로 저장해줘

5.4 승인 요청 이해하기 — 가장 중요한 부분

AI가 파일을 수정하거나 만들려고 할 때, 이런 화면이 나옵니다.

파일을 만들려고 합니다: 매출정리.md

  1. Yes                        (한 번만 허용)
  2. Yes, and don't ask again   (앞으로 계속 허용)
  3. No, tell Claude what to do  (거부하고 다른 지시)

화살표 키로 고르고 Enter를 누릅니다.

초보자를 위한 원칙

• 읽기만 하는 작업 → 1. Yes 로 편하게 허용
• 파일을 새로 만드는 작업 → 1. Yes
• 기존 파일을 고치거나 지우는 작업 → 내용을 꼼꼼히 읽고 판단
• 2번(계속 허용)은 처음엔 고르지 마세요. 익숙해진 뒤에 쓰세요.
• 이상하다 싶으면 3. No 를 고르고 "그건 하지 말고 대신 ○○해줘" 라고 말하면 됩니다.

작업을 중간에 멈추고 싶으면 Ctrl + C 를 누릅니다.

5.5 종료하기

대화창에서 이렇게 입력하면 끝납니다.

exit

또는 Ctrl + C 를 두 번 누릅니다.

5.6 다음에 다시 시작하기

1. 파일 탐색기에서 작업 폴더를 엽니다.
2. 빈 공간에 마우스 오른쪽 클릭 → "터미널에서 열기".
3. claude 입력. (또는 codex / agy)

로그인은 이미 되어 있으므로 바로 시작됩니다.

6부. 실제로 시켜볼 만한 일들

명령은 구체적일수록 결과가 좋습니다. 아래 예시를 복사해서 상황에 맞게 고쳐 쓰세요.

6.1 파일 정리

이 폴더의 모든 파일 이름을 "날짜_제목" 형식으로 바꿔줘. 
날짜는 파일이 만들어진 날짜를 쓰고, 형식은 20260901 처럼 해줘.
바꾸기 전에 어떻게 바꿀지 목록으로 먼저 보여줘.

이 폴더의 PDF 파일들을 확인해서 
파일명, 제목, 페이지 수, 한 줄 요약을 표로 만들어 목록.md 로 저장해줘.

6.2 데이터 작업

data.csv 파일을 열어서 빈 칸이 있는 행이 몇 개인지 알려주고,
빈 칸을 어떻게 처리하면 좋을지 방법을 제안해줘. 
아직 파일을 고치지는 마.

매출.xlsx 의 월별 매출을 막대그래프로 그려서 
PNG 이미지로 저장해줘. 제목과 축 이름은 한글로 넣어줘.

6.3 문서 작성

초안.md 를 읽고, 학술 논문에 어울리는 건조하고 객관적인 문체로 다듬어줘.
원문은 그대로 두고 수정본을 초안_수정.md 로 따로 저장해줘.
어디를 왜 고쳤는지도 정리해줘.

아래 내용으로 공문 형식의 메일 초안을 3가지 톤(정중/간결/친근)으로 써줘.
내용: (여기에 상황 설명)

6.4 배우면서 쓰기

방금 뭘 했는지 초보자도 이해할 수 있게 설명해줘.

지금 이 폴더에서 내가 할 수 있는 유용한 작업 5가지를 제안해줘.

6.5 좋은 지시문 쓰는 요령

요령 4가지

1. 무엇을 할지 + 어떻게 할지 + 결과를 어디에 저장할지를 함께 말합니다.
2. 위험한 작업은 "먼저 계획을 보여주고, 내가 승인하면 실행해" 라고 덧붙입니다.
3. 원본을 지키고 싶으면 "원본은 건드리지 말고 사본을 만들어" 라고 명시합니다.
4. 결과가 마음에 안 들면 "다시 해줘"가 아니라 "○○ 부분을 △△로 바꿔줘" 라고 구체적으로 말합니다.

7부. 기능 늘리기 — MCP와 플러그인

AI 에이전트가 기본으로 못 하는 일이 있습니다. 한글(HWP) 문서를 열거나, 법령 원문을 확인하거나, 국가통계를 끌어오는 일 같은 것입니다. 이런 기능은 "확장"을 설치해서 붙입니다.

7.1 MCP와 플러그인은 무엇이 다른가

둘 다 "AI가 할 수 있는 일의 범위"를 넓히는 장치입니다. 설치한 뒤에는 따로 명령을 외울 필요 없이 평소처럼 한국어로 지시하면 됩니다. AI가 필요할 때 알아서 꺼내 씁니다.

MCP는 Model Context Protocol의 줄임말입니다. AI와 외부 프로그램이 대화하는 규격 이름이고, 그 규격에 맞춰 만들어진 프로그램을 MCP 서버라고 부릅니다.

7.2 가장 쉬운 설치법 — AI에게 시키기

설치 명령을 직접 찾아 칠 필요가 없습니다. 저장소 주소를 주고 시키면 됩니다.

대화창에 이렇게 입력합니다.

https://github.com/chrisryugj/kordoc 이거 사용할 수 있게 전역적으로 설치해줘.

AI가 그 저장소의 설명서를 읽고, 이 컴퓨터에 맞는 설치 명령을 골라 실행합니다. 중간에 승인 화면이 몇 번 뜹니다.

설치가 끝나면 터미널을 완전히 닫고 새로 여세요. 새로 설치한 확장은 대부분 다시 켜야 인식됩니다.

승인 화면을 읽고 누르세요.
확장 설치는 컴퓨터에 프로그램을 새로 까는 작업입니다. 8부의 원칙이 여기에도 그대로 적용됩니다. 어떤 명령을 실행하려는지 읽고, 모르는 저장소라면 설치하지 마세요. MCP 서버는 설치한 뒤 AI가 다루는 파일과 데이터에 접근할 수 있습니다.

아래 7.3절부터는 설치 명령을 직접 쓰고 싶을 때를 위한 정리입니다. AI에게 시켜서 잘 됐다면 읽지 않아도 됩니다.

7.3 kordoc — 한글(HWP·HWPX) 문서 다루기

한국에서 가장 자주 막히는 지점입니다. HWP·HWPX 파일을 읽고, 고치고, 새로 만듭니다.

설치 방법 A — 설치 마법사 (권장)

터미널에 입력합니다. 이 컴퓨터에 깔린 AI 클라이언트를 알아서 찾아 설정까지 해 줍니다.

npx -y kordoc setup

설치 방법 B — Claude Code 플러그인으로

Claude Code 대화창 안에서 입력합니다.

/plugin marketplace add chrisryugj/kordoc

/plugin install kordoc@kordoc

써 보기 — 설치 후 터미널을 새로 열고, HWPX 파일이 있는 폴더에서 이렇게 시킵니다.

보고서.hwpx 내용을 요약하고 표는 그대로 살려서 정리해줘

7.4 korean-law-mcp — 법령·판례 조회

AI가 법 조문을 지어내는 것을 막아 줍니다. 국가법령정보센터(법제처) 공식 데이터를 직접 조회해서 인용이 실제로 존재하는지 대조합니다.

설치 방법 A — Claude Code 플러그인으로 (가장 간단)

/plugin marketplace add chrisryugj/korean-law-mcp

/plugin install korean-law@korean-law-marketplace

설치 방법 B — 전역 설치

npm install --ignore-scripts --omit=optional -g korean-law-mcp

발급받은 키를 환경 변수 LAW_OC 에 넣어야 합니다. 이 부분은 AI에게 시키는 편이 빠릅니다.

korean-law-mcp가 API 키를 쓰도록 LAW_OC 환경 변수를 설정해줘. 키는 여기 있어: (발급받은 키)

써 보기

민법 제750조 원문을 확인하고, 최근 개정 이력이 있으면 같이 알려줘

7.5 korean-stats-mcp — 국가통계(KOSIS) 조회

통계청 KOSIS 데이터를 실시간으로 끌어옵니다. 출처(표 번호)를 같이 붙여 주므로 보고서에 그대로 쓸 수 있습니다.

설치 방법 — Windows 설치 스크립트

터미널에 입력합니다.

irm https://raw.githubusercontent.com/chrisryugj/korean-stats-mcp/main/install.ps1 | iex

설치 중에 KOSIS API 키를 물어봅니다. 발급받은 키를 붙여넣으면 됩니다.

써 보기

광주광역시 최근 10년 인구 추이를 표로 정리하고 출처를 같이 적어줘

7.6 gptaku_plugins — Claude Code 플러그인 모음

Claude Code에 기능을 붙이는 플러그인 18종이 한 곳에 모여 있습니다.

설치 — Claude Code 대화창 안에서 차례로 입력합니다.

/plugin marketplace add https://github.com/fivetaku/gptaku_plugins.git

/plugin install insane-search@gptaku-plugins

/reload-plugins

장터를 한 번 등록해 두면 다른 플러그인은 /plugin install <이름>@gptaku-plugins 로 골라 담으면 됩니다. 처음에는 하나만 설치해서 써 보세요.

7.7 설치한 것 확인하고 지우기

뭔가 이상해지면 하나씩 끄고 확인하세요. 확장을 여러 개 깔아 두면 어느 것이 문제인지 찾기 어려워집니다. 한 번에 하나씩 설치하고, 쓰지 않는 것은 지우는 편이 낫습니다.

여기 소개한 것은 모두 제3자가 만든 공개 도구입니다. Anthropic·OpenAI·Google의 공식 제품이 아닙니다. 저장소와 설치 명령은 2026년 9월 기준으로 확인했습니다. 도구 쪽 사정이 바뀔 수 있으니, 설치가 안 되면 저장소의 설명서를 먼저 확인하세요.

8부. 안전하게 쓰기 — 꼭 지킬 5가지

① 전용 작업 폴더에서만 실행하기

AI 에이전트는 실행한 폴더와 그 아래를 작업 범위로 삼습니다.

• 하지 마세요: 바탕화면, C:\Users\내이름, C드라이브 최상위에서 실행
• 하세요: C:\AI작업\프로젝트1 처럼 목적별 폴더를 만들어 그 안에서 실행

② 원본은 미리 복사해 두기

AI가 파일을 잘못 고칠 수도 있고, 내가 승인을 잘못 누를 수도 있습니다.

작업 전에 폴더를 통째로 복사해 두세요. 가장 확실하고 간단한 안전장치입니다.

③ 민감한 정보는 작업 폴더에 두지 않기

AI가 읽은 파일 내용은 답을 만들기 위해 서버로 전송됩니다.

작업 폴더에 두지 말아야 할 것:
- 주민등록번호, 계좌번호, 비밀번호가 들어간 파일
- 미공개 연구 데이터, 심사 중인 논문 원고
- 회사 기밀, 계약서
- 다른 사람의 개인정보가 담긴 명단

기관 규정상 외부 전송이 금지된 자료는 애초에 가져오지 마세요.

④ 승인 화면을 읽고 누르기

빨리 넘기려고 무조건 Yes 를 누르는 습관은 위험합니다. 무엇을 하려는지 한 번은 읽으세요.

특히 이런 단어가 보이면 멈추고 확인합니다: 삭제(delete, rm), 덮어쓰기(overwrite), 전체(all), 강제(force)

⑤ 자동 승인 기능은 쓰지 않기

Claude Code의 --dangerously-skip-permissions, Codex CLI의 --full-auto/--yolo, Antigravity CLI의 자동 승인(auto-approve) 설정은 모두 "묻지 말고 다 해라"라는 뜻입니다. 이름 그대로 위험합니다. 초보자는 절대 쓰지 마세요.

인터넷의 팁 글에서 "이거 켜면 편하다"라고 권하는 경우가 있는데, 그건 잘못 지워도 복구 가능한 코드 저장소에서 작업하는 사람들 기준입니다. 원본 데이터가 든 폴더에서는 쓰지 마세요.

9부. 문제가 생겼을 때

9.1 "명령을 찾을 수 없습니다"

'claude'은(는) cmdlet, 함수, 스크립트 파일 ... 인식되지 않습니다.

해결 순서

1. 터미널을 완전히 닫고 새로 엽니다. (열에 아홉은 이걸로 해결됩니다.)
2. 그래도 안 되면 컴퓨터를 재부팅합니다.
3. 그래도 안 되면 설치 위치를 확인합니다.

npm config get prefix

C:\Users\내이름\AppData\Roaming\npm 같은 경로가 나옵니다. 이걸 Windows에 등록합니다.

• Windows 키 → 환경 변수 검색 → "계정의 환경 변수 편집" 실행
• 위쪽 목록에서 Path 를 선택 → "편집"
• "새로 만들기" → 위 경로 붙여넣기 → "확인" 을 모두 눌러 닫기
• 터미널을 새로 열고 다시 시도

9.2 "이 시스템에서 스크립트를 실행할 수 없으므로"

Windows가 스크립트 실행을 막고 있는 것입니다. 부록 E 의 실행 권한 설정을 하면 해결됩니다. 아래 한 줄을 터미널에 입력하면 됩니다.

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Y 를 입력하고 Enter.

9.3 한글이 ??? 나 占쏙옙 로 깨져 보임

임시 해결:

chcp 65001

영구 해결: 부록 E 의 프로필 설정을 하세요.

그래도 안 되면 Windows 설정을 바꿉니다.
- Windows 키 → 국가 또는 지역 검색 → "날짜, 시간 및 지역 형식" → "추가 날짜, 시간 및 국가별 설정" → "국가 또는 지역" → "관리자" 탭 → "시스템 로캘 변경"
- "Beta: 세계 언어 지원을 위해 Unicode UTF-8 사용" 체크 → 재부팅

오래된 한글 프로그램 일부에서 부작용이 생길 수 있습니다. 다른 방법으로 해결되지 않을 때만 쓰세요.

9.4 설치 중 빨간 ERR! 오류가 남

권한 문제인 경우: 터미널을 관리자 권한으로 다시 엽니다.
Windows 키 → 터미널 검색 → 목록에서 마우스 오른쪽 클릭 → "관리자 권한으로 실행"

네트워크 문제인 경우: 회사나 학교 네트워크의 방화벽이 막는 경우가 많습니다. 개인 인터넷(휴대폰 테더링 등)으로 바꿔서 설치해 보세요.

9.5 경로에 한글이나 띄어쓰기가 있어서 문제가 생김

D:\내 연구\2026년 자료 같은 경로는 가끔 문제를 일으킵니다.

해결: 작업 폴더는 되도록 영문·숫자·밑줄만 써서 만드세요.

• 권장: C:\AI작업\project2026
• 피하기: C:\내 문서\2026년 연구 자료 (최종)

이미 만든 폴더 경로를 쓸 때는 큰따옴표로 감싸세요.

cd "D:\내 연구\2026년 자료"

9.6 AI가 엉뚱한 답을 하거나 대화가 꼬임

대화가 길어지면 앞의 내용에 끌려다니는 경우가 있습니다.

• /clear 입력 → 대화 초기화 (세 도구 모두 같은 명령입니다)
• 또는 exit 로 나갔다가 다시 실행

주제가 바뀔 때마다 /clear 를 습관적으로 눌러주면 답의 품질이 눈에 띄게 좋아집니다.

9.7 최신 버전으로 올리기

설치할 때 쓴 방법과 같은 방법으로 올려야 합니다.

npm update -g 는 쓰지 마세요. 처음 설치할 때 기록된 버전 범위 안에서만 올라가서, 최신 버전으로 가지 않는 경우가 많습니다. @latest 를 붙인 npm install 을 쓰세요.

winget으로 Codex를 깔았다면 winget upgrade --id OpenAI.Codex -e 를 씁니다.

9.8 지우고 싶을 때

npm uninstall -g @anthropic-ai/claude-code

npm uninstall -g @openai/codex

winget uninstall --id OpenAI.Codex -e

전용 설치본으로 깐 경우는 각 도구의 공식 문서에 있는 제거 안내를 따릅니다.

수명이 끝난 Gemini CLI가 남아 있다면 이렇게 지웁니다.

npm uninstall -g @google/gemini-cli

부록 A. 용어 사전

부록 B. 명령어 한 장 요약

터미널 기본

PowerShell 기준입니다. 옛 명령 프롬프트(cmd)에서는 ls pwd 가 동작하지 않습니다(2.4절).

설치 (한 번만)

winget install --id OpenJS.NodeJS.LTS -e

winget install --id Git.Git -e

AI 에이전트는 셋 중 필요한 것만 설치합니다.

irm https://claude.ai/install.ps1 | iex

irm https://chatgpt.com/codex/install.ps1 | iex

irm https://antigravity.google/cli/install.ps1 | iex

확인

node --version

npm --version

git --version

claude --version

매일 쓰는 흐름

1. 탐색기에서 작업 폴더 열기
2. 빈 공간에 오른쪽 클릭 → "터미널에서 열기"
3. claude 입력 (또는 codex / agy)
4. 한국어로 지시
5. 승인 화면 읽고 선택
6. exit 로 종료

대화창 안에서 쓰는 필수 명령 5개

자세한 설명과 사용량 한도는 5.0절에 있습니다.

키보드 단축키

부록 C. Mac 사용자를 위한 요약

이 문서는 Windows 기준입니다. Mac에서는 다음 차이만 알면 나머지는 같습니다.

Homebrew가 없다면 https://brew.sh 의 안내대로 먼저 설치합니다.

AI 에이전트 설치 명령은 irm ... | iex 대신 curl 을 씁니다. 나머지 사용법은 완전히 같습니다.

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

curl -fsSL https://antigravity.google/cli/install.sh | bash

Codex CLI는 Homebrew로 설치합니다.

brew install --cask codex

npm install -g ... 방식은 Windows와 완전히 같습니다.

부록 D. WSL(리눅스)을 써야 하나요?

결론: 이 가이드의 독자라면 그냥 Windows에서 쓰세요.

인터넷에서 "Claude Code는 WSL이 필요하다"는 글을 보게 될 텐데, 대부분 2024~2025년에 쓰인 글입니다. 당시에는 실제로 Windows를 지원하지 않아 WSL(Windows Subsystem for Linux, Windows 안에서 리눅스를 돌리는 기능)이 유일한 방법이었습니다. 지금은 세 도구 모두 Windows 전용 설치본을 제공하며, WSL은 필요 없습니다.

그냥 Windows를 쓰는 게 나은 이유

특히 작업 대상이 Windows 폴더의 문서·데이터라면 WSL은 손해입니다. WSL에서 Windows 드라이브(/mnt/c, /mnt/d)를 읽고 쓰는 속도는 눈에 띄게 느리고, 파일이 수백 개가 되면 체감이 큽니다.

대신 이것만 하세요

Windows에서 쓸 때 마찰을 줄이는 방법은 WSL이 아니라 Git for Windows 설치입니다(3.3절). Claude Code가 Git Bash를 감지하면 PowerShell 대신 그걸 셸로 쓰는데, 인터넷 자료와 AI가 알고 있는 명령어가 대부분 리눅스식이라 오류가 줄어듭니다.

WSL이 나은 경우

다음에 해당한다면 WSL을 고려할 만합니다. 대부분의 독자는 해당하지 않습니다.

• 리눅스 전용 개발 도구(도커, 특정 파이썬 패키지 등)를 써야 한다
• 서버에 올릴 프로그램을 만들고 있고, 개발 환경을 서버와 맞춰야 한다
• AI에게 위험한 작업을 시키면서 Windows 본체와 격리하고 싶다

WSL을 쓰기로 했다면, 작업 파일도 WSL 안쪽(~/projects/...)에 두세요. Windows 드라이브를 오가는 방식이 가장 느리고 문제도 많습니다.

부록 E. 선택 설정 — 실행 권한 · 한글 깨짐

이 두 설정은 미리 하지 않아도 됩니다. 문제가 생겼을 때만 하면 되는 선택 사항입니다. 요즘 설치본은 대부분 이 설정 없이 그대로 동작합니다.

E.1 실행 권한 설정

Windows는 보안상 외부 스크립트 실행을 기본으로 막아둡니다. 설치나 실행이 이 때문에 막힐 때 풀어 줍니다.

터미널에 입력합니다.

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

실행 정책을 변경하시겠습니까? 라고 물으면 Y 를 입력하고 Enter.

위험하지 않나요?
RemoteSigned는 "내가 만든 스크립트는 실행하고, 인터넷에서 받은 것은 서명된 것만 실행한다"는 중간 단계 설정입니다. 개발자들이 표준으로 쓰는 설정이며, 보안을 완전히 푸는 게 아닙니다. -Scope CurrentUser 때문에 내 계정에만 적용되고 컴퓨터 전체에는 영향이 없습니다.

지금 설정을 확인만 하고 싶으면 이렇게 입력합니다.

Get-ExecutionPolicy -Scope CurrentUser

E.2 한글 깨짐 방지 설정

한글 파일명이나 한글 답변이 ??? 나 占쏙옙 처럼 깨져 보일 때만 하면 됩니다.

임시로 넘기려면 터미널에 한 줄 입력합니다. 창을 닫으면 원래대로 돌아갑니다.

chcp 65001

매번 자동으로 적용하려면 프로필 파일에 적어 둡니다. 터미널에 아래를 입력합니다.

notepad $PROFILE

메모장이 열립니다. "파일을 찾을 수 없습니다. 새로 만드시겠습니까?" 라고 물으면 "예" 를 누릅니다.

메모장에 아래 3줄을 복사해서 붙여넣습니다.

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::InputEncoding  = [System.Text.Encoding]::UTF8
$PSDefaultParameterValues['*:Encoding'] = 'utf8'

Ctrl + S 로 저장하고 메모장을 닫습니다. 터미널도 닫았다가 새로 엽니다.

이 파일($PROFILE)은 터미널을 켤 때마다 자동으로 실행되는 설정 파일입니다. 여기 적어두면 매번 손댈 필요가 없습니다.

그래도 안 되면 9.3절의 Windows 시스템 로캘 변경까지 검토하세요.

마무리 — 다음 단계

여기까지 왔다면 기본기는 끝났습니다. 익숙해진 뒤 이런 것들을 시도해 보세요.

1. 작업 폴더에 안내 파일 두기 — 폴더에 규칙 파일을 만들어 "이 폴더에서는 이런 규칙으로 작업해줘"라고 적어두면, 매번 설명하지 않아도 AI가 알아서 지킵니다. Claude Code는 CLAUDE.md, Codex CLI와 Antigravity CLI는 AGENTS.md 를 읽습니다. Claude Code에서는 /init 명령으로 초안을 자동 생성할 수 있습니다.

2. 자주 쓰는 지시를 저장해 두기 — 반복하는 작업의 지시문을 메모장에 모아두고 복사해서 씁니다.

3. 확장 늘리기(MCP·플러그인) — 한글 문서, 법령, 국가통계, 구글 드라이브 같은 것을 AI에 직접 연결할 수 있습니다. 7부에 설치 방법을 정리해 두었습니다.

4. 여러 도구 비교해 보기 — 같은 일을 Claude / Codex / Antigravity에 각각 시켜보면 성격 차이를 알게 됩니다.

공식 문서

• Claude Code — https://code.claude.com/docs
• Codex CLI — https://developers.openai.com/codex/cli
• Antigravity CLI — https://antigravity.google/docs/cli/install

이 문서는 Windows 11 환경을 기준으로 작성되었습니다. 프로그램 버전이 올라가면 화면 구성이 조금씩 달라질 수 있으나, 전체 흐름은 동일합니다.