App Claude Code 설치로 터미널 에이전트 자동 코딩 환경 세팅하기

터미널에서 빈 디렉토리를 열고 새 도구를 설치하려고 npm 명령어를 입력해봤습니다. 요즘 개발 커뮤니티에서 터미널 에이전트 이야기가 자주 보여서, 저도 직접 세팅해보고 싶었거든요. 기존 에디터 확장 프로그램과는 달리 이 도구는 아예 쉘 권한을 쥐고 빌드를 돌리고 에러까지 다루는 흐름이라서, 처음부터 느낌이 꽤 다릅니다. 실제로 써보니 일반적인 코딩 환경과는 확실히 결이 다르더라구요.

다만 이런 에이전트 툴은 비용 감각을 먼저 생각해야 합니다. 회사에서 매달 결제되는 API 비용을 떠올리면, 괜히 도입했다가 토큰만 크게 쓰는 건 아닌지 고민될 수 있거든요. 파일을 읽고 분석하는 범위가 넓다 보니 자칫하면 지출이 커질 수 있습니다. 그럼에도 터미널 안에서 컨텍스트를 유지한 채 바로 테스트를 돌리는 속도는 무시하기 어렵습니다. 한 번만 제대로 세팅해두면 자잘한 스크립트 작성이나 설정 파일 수정 같은 귀찮은 작업을 꽤 많이 덜어주더라구요.

Step 1: Node.js 설치 상태 확인하기

Claude Code를 로컬 컴퓨터에 깔아서 쓰려면 가장 먼저 Node.js가 제대로 설치되어 있는지 확인해야 합니다. Anthropic에서 권장하는 버전은 Node.js 18 이상이고, 호환성을 생각하면 최신 20 버전을 쓰는 편이 가장 편합니다. 터미널을 열고 아래 명령어를 입력해서 버전을 확인해봅시다.

버전 숫자가 나오지 않거나 에러 메시지가 뜬다면 공식 사이트에서 설치부터 다시 해야 합니다. 윈도우 환경에서는 환경 변수 Path가 꼬여서 명령어를 인식하지 못하는 경우도 종종 생기거든요. 이 단계에서 Node.js가 정상적으로 잡히는지 먼저 확인해두면 뒤에서 불필요한 시행착오를 줄일 수 있습니다.

Step 2: npm 패키지 글로벌 설치하기

Node.js 준비가 끝났다면 이제 npm을 사용해서 패키지를 컴퓨터 전체에 설치할 차례입니다. 글로벌 설정을 해두면 어떤 디렉토리에서든 터미널 명령어로 바로 불러올 수 있습니다. 프롬프트에 아래 명령어를 그대로 입력해보세요.

설치 과정에서 진행 표시가 올라가다가 마지막에 성공 메시지가 뜨면 정상적으로 등록된 겁니다. 여기서 권한 오류가 나면서 설치가 막히는 경우도 있습니다. 그럴 때는 터미널을 관리자 권한으로 다시 열어서 실행하면 해결되는 경우가 많습니다. 설치가 끝난 뒤에는 명령어가 실제로 인식되는지 한 번 더 확인하는 게 좋습니다.

Step 3: Anthropic API 키 발급 및 환경 변수 등록하기

이 도구는 Anthropic의 LLM을 실시간으로 가져다 쓰기 때문에 API 키가 필수입니다. 우선 Anthropic 콘솔에 들어가서 새로운 비밀 키를 발급받아야 합니다. 윈도우 파워셸 기준으로 발급받은 키를 임시로 등록하려면 다음 명령어를 실행하면 됩니다.

매번 터미널을 켤 때마다 입력하기 번거롭다면 윈도우 시스템 환경 변수에 아예 고정으로 넣어두는 편이 낫습니다. 키가 유효하지 않으면 다음 단계로 넘어가지 못하고 에러 로그가 바로 뜨니, 여기서 한 번 제대로 확인해두는 게 중요합니다. 입력한 값에 오타가 있으면 에이전트 세션 자체가 열리지 않을 수 있습니다.

Step 4: claude 명령어로 터미널 세션 열기

환경 변수 설정까지 끝났다면 드디어 터미널에서 에이전트를 실행할 준비가 된 셈입니다. 원하는 프로젝트 폴더 안으로 이동한 다음 아래 명령어를 입력하고 엔터를 눌러주세요.

첫 구동 시에는 라이선스 동의를 묻거나 로그인을 하라는 안내가 나타날 수 있습니다. 콘솔 창에서 승인 처리를 해주고 나면 폴더 내부 구조를 스캔하는 과정을 거치게 됩니다. 이때 쓸데없는 빌드 파일이나 이미지 폴더가 많으면 토큰 낭비가 커질 수 있으니, .claudeignore 파일로 예외 처리를 해두는 것이 유용합니다. 작업 범위를 줄여두면 속도와 비용을 같이 잡는 데 도움이 됩니다.

Step 5: 코딩 작업 지시하고 실행 결과 검증하기

세션이 정상적으로 시작되면 터미널 창에 에이전트와 대화할 수 있는 전용 프롬프트가 뜹니다. 여기에 원하는 코딩 요청을 영어 또는 한국어로 구체적으로 작성하면 됩니다. 예를 들어 간단한 서버 세팅을 원한다면 아래처럼 적어서 엔터를 치면 됩니다.

입력하자마자 에이전트가 알아서 파일을 만들고 필요한 라이브러리를 설치하는 모습을 볼 수 있습니다. 중간에 터미널 명령어를 실행하려고 할 때마다 사용자에게 허가 여부를 물어보는데, 이때는 꼭 확인하고 승인해줘야 합니다. 모든 단계가 끝나면 직접 서버를 띄워서 의도한 대로 구동되는지 터미널에서 바로 확인해보면 됩니다. 여기서 결과를 눈으로 보는 과정이 빠지면 나중에 원인 파악이 더 어려워집니다.

터미널 에이전트를 쓸 때 반드시 챙겨야 할 주의점

직접 설치해서 써보면 아무 생각 없이 쓰다가는 한 달 만에 청구서가 커질 수 있다는 점이 먼저 보입니다. 에이전트가 코드를 고칠 때마다 폴더 안의 여러 파일을 읽어가며 컨텍스트를 채우기 때문입니다. 이를 줄이려면 앞서 언급한 무시 리스트 설정을 꼼꼼하게 다듬어야 합니다. 또 명령어를 무조건 승인해주는 옵션도 있긴 하지만, 웬만하면 수동으로 보면서 하나씩 허가하는 편이 안전합니다. 스스로 같은 명령을 반복하며 빠지는 상황이 생기면 비용만 낭비될 수 있으니, 실행 흐름을 사람이 한 번 더 잡아주는 게 좋습니다.

결국 도구를 어떻게 통제할 것인가의 문제

터미널 안에서 코딩을 자동화해주는 도구는 확실히 손을 편하게 만들어 줍니다. 하지만 그렇다고 해서 개발자가 쉘 뒤로 완전히 숨어버리면 곤란합니다. 에이전트가 짠 코드를 꼼꼼히 확인하고, 터미널에서 실행될 명령어의 부작용을 통제하는 일은 여전히 사람의 몫입니다. Claude Code는 분명히 강력하지만, 강한 도구일수록 범위를 잘 정해두는 쪽이 더 안정적입니다. 처음 세팅만 제대로 해두면 작업 속도는 빨라지고, 통제도 놓치지 않을 수 있습니다.