터미널과 작업 폴더: Claude Code는 어디서 실행해야 할까

처음 보면 터미널은 좀 딱딱해 보입니다. 어두운 창, 깜빡이는 커서, 익숙한 버튼은 하나도 없습니다. 하지만 실제로는 훨씬 평범합니다. 컴퓨터에게 할 일을 직접 말하는 방법일 뿐입니다. 명령 하나는 파일을 보여 주고, 다른 명령은 원하는 폴더로 옮겨 주고, 또 다른 명령은 프로그램을 실행합니다.

에이전트와 일하기 시작할 때 막히는 문제는 대부분 요청을 어떻게 썼느냐가 아니라, 터미널이 엉뚱한 폴더에 있다는 데서 생깁니다. 그래서 먼저 폴더와 경로를 정리하고, claude 명령은 그다음에 다루겠습니다. 마지막에는 이 모든 내용을 codegym-project 프로젝트에 적용해 봅니다. 이 프로젝트에서는 과제 하나하나가 별도의 프로젝트로 존재합니다.

터미널 - 프로젝트를 직접 다루는 방법

터미널은 텍스트 명령으로 컴퓨터를 다루는 창입니다. 메뉴에서 원하는 버튼을 찾는 대신, 할 일을 정확히 지정합니다. 파일을 보여 줘, 폴더를 열어 줘, 프로그램을 실행해 줘.

마우스가 더 빠른 건 같은 동작을 열 번째 반복해야 하는 순간까지입니다. 대신 터미널에는 이런 장점이 있습니다.

명령 하나가 구체적인 동작 하나를 합니다. 결과가 같은 창에 바로 보이니 짐작할 필요가 없습니다.
순서를 쉽게 반복할 수 있습니다. 폴더를 확인하고, 파일을 보고, 이동해서 실행하는 흐름 그대로요.
인터페이스가 숨기는 상태가 보입니다. 무엇보다 현재 폴더가 보입니다.

둘 중 하나만 골라야 하는 건 아닙니다. IDEA에서는 파일을 눈으로 찾아 클릭해서 여는 게 편하고, 터미널에서는 정확한 명령을 실행하고 바로 결과를 보는 게 편합니다. 실제로는 두 방법을 늘 함께 씁니다.

Claude Code도 명령으로 실행합니다

claude를 입력하면 에이전트는 터미널의 현재 디렉터리에서 작업을 시작합니다. 그러니 먼저 터미널이 어디에 있는지 파악하고, 그다음에 에이전트를 실행하는 편이 좋습니다.

일상 작업에 쓰는 명령 다섯 개

동작 다섯 개. 처음에는 정말 이것만으로 충분합니다. Windows에서는 PowerShell을, macOS와 Linux에서는 기본 터미널을 씁니다. 짧은 명령은 세 경우 모두 똑같이 생겼습니다.

명령	원래 뜻	하는 일
`pwd`	`print working directory` - "작업 디렉터리 출력"	터미널이 지금 있는 폴더의 전체 경로를 출력합니다.
`ls`	`list` - "목록"	현재 디렉터리의 파일과 폴더를 보여 줍니다.
`cd demo-project`	`change directory` - "디렉터리 변경"	바로 옆에 있는 `demo-project` 폴더로 들어갑니다.
`cd ..`	`..`은 상위 디렉터리를 뜻합니다	터미널을 한 단계 위 폴더로 올립니다.
`claude`	실행할 프로그램의 이름	현재 디렉터리에서 Claude Code를 실행합니다.

PowerShell에서 짧은 명령은 편의를 위한 별칭일 뿐입니다. pwd는 Get-Location을, ls는 Get-ChildItem을, cd는 Set-Location을 호출합니다. 긴 이름에 겁먹을 필요도, 지금 외울 필요도 없습니다. 다만 이 이름을 보면 명령의 의미가 잘 드러납니다.

이제 macOS나 Linux에서 짧게 한 번 돌려 봅시다. 처음에 터미널은 projects 폴더에 있고, 그다음 demo-project로 이동합니다.

경로의 마지막 부분을 보세요. projects가 demo-project로 바뀌었습니다. 마법 같은 건 없습니다. cd 명령은 새 파일을 열지도, 아무것도 복사하지도 않았습니다. 터미널의 현재 위치를 다른 폴더로 옮겼을 뿐입니다.

시간을 아껴 주는 키

금방 시간을 아껴 주는 습관이 몇 가지 있습니다. 터미널은 입력 기록을 저장하고, 긴 이름을 자동으로 완성하도록 도와줍니다.

↑ - 이전 명령을 보여 줍니다. 여러 번 누르면 기록을 더 거슬러 올라갑니다.
↓ - 기록에서 더 최근 명령으로 돌아옵니다.
Tab - 명령, 파일, 폴더 이름을 자동 완성합니다. 예를 들어 cd dem을 입력하고 Tab을 누르면 cd demo-project가 됩니다.
←와 → - 줄 안에서 커서를 움직입니다. 명령 전체를 다시 입력하지 않고 글자 하나만 고칠 수 있습니다.
Ctrl+C - 보통 실행 중인 명령을 멈춥니다. 잘못 실행했거나 프로세스가 끝나지 않을 때 씁니다.
Ctrl+L - 터미널의 보이는 영역을 지웁니다. 파일이나 명령 기록은 지우지 않습니다.

가장 자주 쓰게 되는 건 위쪽 화살표와 Tab입니다. 화살표는 이미 입력한 명령을 되살려 주고, 자동 완성은 긴 경로에서 오타를 줄여 줍니다.

폴더, 디렉터리, 경로

경로를 복사해 명령에 넣었는데, 다른 폴더로 이동하자 똑같은 명령이 더 이상 동작하지 않습니다. 오타 때문이 아닙니다. 경로에는 두 종류가 있고, 그중 하나는 터미널이 지금 어디에 있느냐에 따라 달라집니다. 둘 다 살펴보겠습니다.

먼저 이름부터 짚고 가죠. 생각보다 간단합니다. 폴더와 디렉터리는 같은 것입니다. 인터페이스에서는 주로 "폴더"라고 하고, 터미널 이야기를 할 때는 "디렉터리"라고 합니다.

경로는 디스크에 있는 디렉터리의 주소입니다. Windows, macOS, Linux마다 구분 기호는 다르게 생겼지만 원리는 같습니다. 경로의 조각 하나하나가 한 단계씩 더 깊이 들어갑니다. 먼저 디스크나 루트 디렉터리, 그다음 사용자, 프로젝트를 모아 두는 폴더, 그리고 마지막으로 특정 프로젝트입니다.

전체 경로와 절대 경로는 같은 것을 부르는 두 이름입니다. 이런 경로는 파일 시스템의 가장 꼭대기에서 시작합니다. Windows에서는 드라이브 문자에서, macOS와 Linux에서는 / 기호에서 시작하죠. 터미널이 지금 어느 디렉터리에 열려 있든 항상 같은 곳을 가리킵니다.

상대 경로는 반대입니다. 현재 디렉터리에서 출발하는 길을 나타냅니다. 주소의 앞부분을 반복하지 않아도 되니 더 짧아집니다. 하지만 다른 폴더로 옮기면 경로의 의미가 달라집니다.

프로젝트 안에 이런 파일이 있다고 해 봅시다.

demo-project/
└── src/
    └── index.html

터미널은 demo-project의 루트에 열려 있습니다. 같은 index.html에 도달하는 방법은 두 가지입니다.

시스템	전체 경로(절대 경로)	`demo-project` 기준 상대 경로
Windows	`C:\Users\student\projects\demo-project\src\index.html`	`.\src\index.html`
macOS	`/Users/student/projects/demo-project/src/index.html`	`./src/index.html`
Linux	`/home/student/projects/demo-project/src/index.html`	`./src/index.html`

점 .은 "현재 디렉터리"를 뜻합니다. 그래서 .\src\index.html과 ./src/index.html은 "현재 폴더에서 src로 들어가 index.html을 가져온다"로 읽습니다. 점은 흔히 생략합니다. src\index.html과 src/index.html도 같은 뜻입니다.

demo-project에서 상위 폴더 projects로 올라가면 이전의 상대 경로는 더 이상 통하지 않습니다. 새 위치에서는 Windows라면 .\demo-project\src\index.html, macOS와 Linux라면 ./demo-project/src/index.html이 필요합니다. 전체 경로는 그대로입니다.

공백이 들어간 경로는 큰따옴표로 감쌉니다. 그렇지 않으면 터미널은 공백 뒤에서 다른 인수가 시작된다고 판단합니다.

cd "C:\Users\student\My Projects\demo-project"

현재 디렉터리가 중요한 이유

터미널은 첫 명령을 입력하기 전에도 항상 어떤 디렉터리에 있습니다. 이 디렉터리를 현재 디렉터리 또는 작업 디렉터리라고 합니다. 명령은 여기서부터 파일을 찾고 상대 경로를 계산합니다.

마우스로도 이미 폴더를 고르고 있습니다

"Downloads"에 있는 파일을 "Documents" 안의 "회계 부서 기밀" 폴더로 복사해야 한다고 해 봅시다. 파일을 복사하고, 원하는 폴더까지 경로를 끝까지 따라간 다음, 거기서야 "붙여넣기"를 누릅니다. 파일은 디스크의 정해진 주소 한 곳에 기록됩니다. 파일을 "Documents 어딘가에" 붙여넣는 사람은 없습니다. 매번 정확한 위치까지 찾아가는데, 마우스로 하다 보니 의식하지 못할 뿐입니다.

터미널에서도 하는 일은 같습니다. 탐색기 창 대신 경로 한 줄이 있을 뿐입니다. 디렉터리는 여전히 여러분이 고르고, 에이전트는 바로 그 디렉터리에서 작업을 시작합니다.

기술적으로는 드라이브 루트 C:\에서 터미널을 열 수도 있습니다. 좋은 생각일까요? 아닙니다. Claude Code가 디스크의 파일을 전부 읽어 들이기 시작해서가 아닙니다. 그러지는 않습니다. 문제는 출발점을 잘못 골랐다는 데 있습니다.

에이전트에게 프로젝트 하나의 명확한 경계가 없습니다. 바로 옆에 시스템 파일, 사용자 폴더, 여러분의 다른 프로젝트가 있습니다.
상대 경로가 예상과 다른 곳에서 시작됩니다. src가 어느새 그 src가 아니게 됩니다.
경로만 봐서는 지금 어떤 프로젝트로 작업하고 있는지 알 수 없습니다.

실수하기 쉬운 사소한 점이 하나 더 있습니다. IDEA에서 열려 있는 파일과 터미널의 현재 디렉터리는 서로 다른 상태입니다. 한 프로젝트의 파일을 보고 있어도 터미널은 여전히 다른 프로젝트에 있을 수 있습니다. 에디터 탭을 바꾼다고 이미 열린 터미널이 따라 옮겨 가지는 않습니다.

출발점

프로젝트 루트는 한 프로젝트에 관련된 파일이 들어 있는 최상위 폴더입니다. 코드, 설정, 문서, 그 밖에 필요한 자료가 여기에 있습니다. 형식적인 정의를 외울 필요는 없습니다. 역할로 보면 더 쉽습니다. 이 폴더가 프로젝트 하나를 통째로 묶어 줍니다.

예를 들어 projects라는 공용 폴더에는 서로 독립적인 프로젝트 여러 개가 들어 있을 수 있습니다.

projects/
├── demo-project/
│   ├── README.md
│   └── src/
└── calculator/
    ├── README.md
    └── src/

이 트리에서 projects는 컨테이너입니다. 첫 번째 프로젝트의 루트는 demo-project, 두 번째 프로젝트의 루트는 calculator입니다. 기술적으로는 공용 폴더에서 에이전트를 실행할 수도 있지만, 거기에는 쓸모 있는 컨텍스트가 적습니다. 서로 관련 없는 프로젝트 두 개가 나란히 있으니까요.

실제로 지킬 규칙은 간단합니다. 바꾸고 싶은 바로 그 프로젝트의 최상위 폴더를 찾아서, 거기서 터미널을 열고 도구를 실행하세요. 그러면 명령, 파일, 프로젝트 지침이 알아보기 쉬운 하나의 영역 안에 모입니다.

너무 넓은 폴더는 작업의 경계를 흐립니다

에이전트는 컨텍스트를 파악하려고 작업 주변의 구조와 파일을 살펴봅니다. 너무 위쪽 폴더에서 실행하면 주변에 다른 프로젝트까지 들어옵니다. 요청이 모호하면 에이전트는 그 프로젝트들도 작업과 관련이 있다고 판단하고, 진행하는 도중에 바꾸라고 하지 않은 것까지 바꿀 수 있습니다.

작업에 몰두하다 보면 기대한 결과만 확인하고 옆 프로젝트에 생긴 추가 수정은 놓치기 쉽습니다. 그래서 올바른 작업 디렉터리는 형식적인 절차가 아니라 에이전트에게 주는 분명한 경계입니다.

codegym-project의 구조

이제 이 모든 이야기가 향하던 CodeGym의 경우입니다. IDEA 플러그인은 과제를 codegym-project라는 큰 트리 하나에 내려받습니다. 밖에서 보면 프로젝트 하나처럼 보이지만, 안에는 중요한 반전이 있습니다. 과제 하나하나가 별도의 프로젝트입니다.

공용 더미 속 파일 하나가 아니라 독립된 프로젝트입니다. 자기 폴더, 자기 파일, 그리고 .claude에 에이전트를 위한 자기만의 규칙이 있습니다. 과제 수만큼 프로젝트가 있다는 뜻입니다. 말 그대로요.

단순화하면 트리는 이렇게 생겼습니다.

codegym-project/
└── src/ko/codegym/claude/course/level01/
    ├── task05/
    │   ├── .claude/          # task05용 에이전트 규칙
    │   └── arkanoid.html     # 이 과제의 파일
    └── task09/
        ├── .claude/          # task09용 별도 규칙
        ├── arkanoid.html
        ├── clicker.html
        └── tictactoe.html

앞의 비유에 나온 사무실이 이번에는 문에 번호를 달고 나타났습니다. task05와 task09입니다. 사무실마다 자기 서류와 자기 규칙이 있고, codegym-project는 건물 전체입니다. 도우미를 로비로 부르는 것만으로는 부족합니다. 지금 하는 일이 놓인 사무실을 콕 집어 알려 줘야 합니다.

옆 과제는 현재 과제의 컨텍스트를 보태 주지 않습니다. task09를 푸는 데 task05의 파일은 필요 없고, 한 폴더의 규칙이 다른 폴더의 규칙을 대신하지도 않습니다. 그래서 CodeGym에서 작업할 때는 공용 codegym-project가 아니라 특정 과제의 폴더가 프로젝트 루트가 됩니다.

과제 하나에 실행 한 번

task09를 풀고 있다면 task09에서 터미널을 열고 거기서 claude를 실행하세요. 코스 전체의 공용 루트는 이 용도로는 너무 넓습니다.

과제 폴더에서 에이전트 실행하기

좋은 소식이 있습니다. 긴 주소를 손으로 입력할 필요는 없습니다. IDEA는 선택한 폴더에서 바로 터미널을 열 수 있습니다.

아래는 수동으로 하는 방법입니다. 물론 Claude Code는 스스로 디렉터리를 옮겨 다니며 필요한 폴더에서 명령을 실행할 수 있습니다. 그래도 한 번쯤은 직접 해 볼 만합니다. 에이전트의 안내에 기대지 않아도 되고, 현재 과제의 경계가 바로 눈에 들어오니까요.

프로젝트 트리에서 원하는 taskXX를 찾습니다.
과제 폴더를 마우스 오른쪽 버튼으로 클릭합니다.
Open In - Terminal을 선택합니다.
pwd 명령으로 현재 디렉터리를 확인합니다.
ls 명령으로 파일을 확인합니다.
경로가 원하는 taskXX로 끝나는지 확인한 다음 claude를 실행합니다.

IDEA는 중첩된 package 폴더를 점으로 이어진 한 줄로 보여 줄 때가 있습니다. 예를 들면 ko.codegym.claude.course.level01처럼요. 이 줄을 디스크 경로인 것처럼 옮겨 적지 마세요. Open In - Terminal로 터미널을 열거나, Copy Path/Reference로 실제 경로를 복사하는 편이 쉽습니다.

터미널이 이미 codegym-project에 열려 있다면 직접 이동해도 됩니다.

cd src/ko/codegym/claude/course/level01/task09
pwd
ls
claude

새 과제에는 새 작업 디렉터리

task05에서 task09로 넘어가셨나요? 열려 있는 에이전트 세션은 IDEA 탭을 따라 저절로 옮겨 가지 않습니다. /exit 명령으로 세션을 끝내고, 새 과제 폴더에서 터미널을 연 다음, 경로를 다시 확인하고 claude를 실행하세요.

세션 하나에 과제 하나

한 세션에서 서로 다른 과제를 섞지 마세요. 대화에는 이전 파일, 결정, 가정이 남아 있어서, 에이전트가 예전 컨텍스트를 새 작업으로 끌고 올 수 있습니다. 결국 두 과제가 뒤섞여 나중에 풀어내기 어려운 상태가 됩니다.

세션 컨텍스트가 왜 그렇게 중요한지, 어떻게 관리하는지는 코스 뒷부분에서 다룹니다. 지금은 간단한 규칙 하나만 지키세요. 새 과제에는 새 세션.

터미널 탭을 여러 개 띄워 둘 수도 있지만, 탭마다 맡은 과제가 분명해야 합니다. 처음에는 다른 과제로 넘어가기 전에 이전 세션을 닫는 편이 더 쉽습니다. 에이전트가 지금 어느 프로젝트를 맡고 있는지 추측할 필요가 없으니까요.

에이전트를 너무 위쪽에서 실행했다면

경로가 taskXX가 아니라 C:\, 홈 폴더, 또는 codegym-project로 끝나나요? 세션을 멈추고, 과제 폴더로 이동한 다음, 에이전트를 다시 실행하세요. 주소부터 바로잡고, 작업은 그다음에 이어 갑니다.

Claude Code와 함께 쓸 때 어떻게 동작하나

전체 그림으로 정리해 봅시다. 터미널은 Claude Code에 실행 명령만 주는 게 아닙니다. 프로젝트 구조, 상대 경로, 로컬 지침의 출발점도 정해 줍니다. 현재 디렉터리는 작업이 어디서 시작되는지 보여 주고, 프로젝트 하나의 루트는 에이전트에게 옆 프로젝트의 잡음 없이 서로 관련된 파일 묶음을 건네줍니다.

여기서 작업에 몰두하다 보면 잊기 쉬운 두 가지 결과가 따라옵니다. IDE에서 탭을 바꿔도 이미 실행 중인 세션의 디렉터리는 바뀌지 않습니다. 그래서 다른 과제로 넘어간다는 건 새 디렉터리이자 별도의 세션이라는 뜻입니다. 그리고 codegym-project에서 프로젝트 하나의 루트는 트리 맨 위가 아니라 특정 taskXX 수준에 있습니다.

실제로는 claude 명령을 입력하기 전에 빠른 확인 세 가지면 충분합니다.

pwd로 경로를 확인합니다.
ls로 파일을 확인합니다.
필요한 프로젝트 하나만 보이는지 확인하고, 그다음에 에이전트를 실행합니다.

이게 전부입니다. 여기서 터미널은 일을 복잡하게 만드는 게 아니라, 보이지 않던 설정을 눈에 보이게 해 줍니다. 지금 어디에 있는지, 어떤 프로젝트를 에이전트에게 맡기는지 정확히 알 수 있습니다.