Chiko IT
AI & Machine Learning

Claude Code 실전 활용법 — GUI 없이 터미널에서 AI 코딩하는 법

Chiko
17min read

목차

화요일 오후 3시, 팀 슬랙에 "Claude Code 써본 사람 있어요?"라는 메시지가 올라왔다. 프론트엔드에서 백엔드로 넘어온 지 2년째, 당시 메인 도구는 Cursor였다. 터미널에서 AI가 코딩을 도와준다는 건 알고 있었지만, GUI도 없이 코드 수정을 확인하고 파일을 탐색하는 게 가능한지 의문이었다. "그걸 왜 쓰냐"가 첫 반응이었다.

M1 MacBook Pro에서 npm install -g @anthropic-ai/claude-code를 실행하고, iTerm2에서 claude를 입력했다. Express 라우터 리팩토링을 시켜봤는데, 프로젝트의 파일 구조를 훑고 관련 파일을 찾아 수정하는 걸 보고 생각이 바뀌기 시작했다. 터미널 탭 하나 열어서 바로 쓸 수 있다는 것도, 하루 종일 터미널에 붙어 있는 백엔드 개발 흐름에 딱 맞았다. 3주 동안 실무에 투입하며 내린 결론은, Claude Code에 대해 흔히 갖는 인식 상당수가 틀렸다는 거다.

"터미널에서 AI 코딩은 불편하다"는 착각

가장 흔한 반응이다. Cursor나 VS Code + Copilot처럼 에디터 안에서 인라인으로 코드가 뜨는 게 편하지, 왜 굳이 터미널에서 하느냐는 거다. 프론트엔드 할 때는 나도 같은 생각이었다.

백엔드 작업을 하면 얘기가 달라진다. 서버에 SSH 접속해서 로그를 보고, Docker 컨테이너 상태를 확인하고, DB 쿼리를 날리고, 환경변수를 조작하는 과정이 전부 터미널에서 이루어진다. 이 흐름 도중에 AI한테 뭘 물어보려면 별도 IDE를 열거나 브라우저 탭을 띄워야 한다. 손은 터미널에 있는데 눈은 에디터로 가는 거다. 컨텍스트 스위칭이 발생한다.

Claude Code는 터미널 네이티브다. 작업하던 디렉토리에서 바로 claude를 치면 시작된다. 파일 시스템을 직접 읽고, 셸 명령어를 실행하고, git 히스토리도 확인한다. IDE를 경유하지 않는다. 프론트엔드에서 넘어온 입장에서 이게 처음엔 오히려 불안하게 느껴졌는데, 3일 지나니까 IDE를 여는 게 귀찮아졌다. SSH로 원격 서버에 접속한 상태에서도 그 환경 안에서 바로 Claude Code를 띄울 수 있다는 점도 생각보다 쓸모가 크다.

핵심은 도구의 형태가 아니라 작업의 성격에 있다. 브라우저 프리뷰가 필요한 프론트엔드 작업이면 GUI IDE가 낫다. 서버 로직, 인프라, 배포 스크립트 작업이면 터미널을 벗어나지 않는 게 빠르다. "GUI가 없어서 불편하다"가 아니라, "GUI가 필요 없는 작업에 GUI를 강제하는 게 불편하다"가 정확한 표현이다. 프론트에서 백엔드로 넘어오면서 이 감각을 체득한 게 Claude Code를 자연스럽게 받아들이는 데 큰 역할을 했다.

CLAUDE.md 없이 Claude Code를 쓰면 반만 쓰는 거다

Claude Code를 처음 쓰는 사람 대부분이 설치하자마자 프롬프트부터 친다. "이 함수 리팩토링해줘", "테스트 코드 만들어줘" 같은 식으로. 결과가 아예 나쁘진 않은데, 프로젝트의 맥락을 못 잡는 느낌이 계속 들었다. 네이밍 컨벤션이 우리 프로젝트와 다르고, 이미 존재하는 유틸 함수를 무시한 채 새로 만드는 일이 반복됐다.

원인은 CLAUDE.md였다. 정확히는, 그걸 안 만들었던 게 문제.

CLAUDE.md는 프로젝트 루트에 놓는 마크다운 파일이다. Claude Code가 세션을 시작할 때 자동으로 읽는다. 프로젝트의 기술 스택, 코딩 컨벤션, 디렉토리 구조, 자주 쓰는 명령어를 적어두면 이걸 기반으로 응답을 생성하게 된다. 시스템 프롬프트를 프로젝트 단위로 버전 관리하는 셈이다. (출처: Anthropic Claude Code 공식 문서, 2025년 공개)

시행착오 끝에 안정화된 구성

처음에 기술 스택만 한 줄 적었다. "Node.js + Express + PostgreSQL." 아무런 차이를 못 느꼈다. 너무 추상적이라 Claude가 활용할 게 없었던 거다. 여러 차례 수정하며 테스트한 끝에 아래 형태로 정착했다.

# 프로젝트 컨텍스트

## 기술 스택
- Runtime: Node.js 20 LTS
- Framework: Express 4.18 + TypeScript 5.4
- DB: PostgreSQL 16 + Prisma 5.11
- 테스트: Vitest 1.6 + supertest

## 코딩 컨벤션
- 함수명: camelCase, 파일명: kebab-case
- 에러 처리: AppError 클래스 사용 (src/utils/app-error.ts)
- 응답 포맷: { success: boolean, data: T, error?: string }
- 로깅: winston 사용, 직접 console.log 금지

## 디렉토리 구조
- src/routes/ — 라우터 (기능별 분리)
- src/services/ — 비즈니스 로직
- src/middleware/ — 인증, 에러핸들러, 로깅
- src/utils/ — 공통 유틸리티

## 자주 쓰는 명령어
- npm run dev — 개발 서버 (포트 3001)
- npm run test — Vitest 실행
- npm run db:migrate — Prisma 마이그레이션

이렇게 해두니 Claude Code가 새 라우터를 만들 때 AppError를 자동으로 import하고, 응답 포맷도 프로젝트 표준에 맞추고, 테스트도 Vitest 기반으로 작성했다. winston 로거를 쓰라는 걸 인식했기 때문에 console.log를 박지 않는다. CLAUDE.md 없이 같은 작업을 시키면 try-catch에 console.error를 쓰는 코드가 나온다. 차이가 상당하다.

한 가지 덧붙이면, CLAUDE.md도 계속 관리해야 한다는 점이다. 프로젝트가 진화하면 스택이 바뀌고 컨벤션이 추가된다. 한 번 쓰고 방치하면 Claude가 오래된 정보를 기준으로 응답한다. 2주에 한 번 정도 훑어보면서 현재 상태와 맞는지 확인하는 게 좋다.

/init 명령어를 쓰면 Claude Code가 프로젝트를 분석해서 CLAUDE.md 초안을 자동 생성해준다. 처음부터 빈 파일에서 시작하기 부담스러우면 이걸로 뼈대를 잡고 다듬는 게 현실적이다. 자동 생성된 내용은 꽤 일반적이라, 프로젝트 고유의 컨벤션이나 금지 패턴은 직접 추가해야 한다.

Cursor를 이기는 순간, 지는 순간

Cursor가 나쁜 도구라는 뜻이 아니다. 프론트 시절부터 써왔고, React 컴포넌트 작업이나 CSS 수정에서는 지금도 Cursor를 연다. 인라인 diff가 눈에 보이고, 프리뷰 확인이 즉각적이다. 이건 부정할 수 없다.

그런데 Claude Code가 확실히 앞서는 영역이 있다.

멀티파일 리팩토링. Cursor에서 여러 파일을 동시에 수정하려면 관련 파일을 일일이 열어 컨텍스트에 추가해야 한다. Claude Code는 프로젝트 디렉토리를 직접 탐색한다. "src/routes 아래 모든 라우터에서 인증 미들웨어 이름을 authGuard로 통일해줘"라고 하면 해당 파일들을 찾아 일괄 수정한다. 우리 프로젝트에서 라우터 파일이 12개였는데, Cursor에서 하나씩 태그하는 것과 Claude Code에서 한 문장으로 끝내는 것은 체감 시간 차이가 크다.

셸 명령어 연계. "Prisma 스키마에 Order 모델 추가하고 마이그레이션까지 적용해줘"라고 하면 스키마 파일을 수정한 뒤 npx prisma migrate dev --name add-order-model을 실행한다. 코드 수정과 CLI 실행 사이에 경계가 없다. IDE에서는 에디터에서 코드를 고치고, 터미널 패널로 전환해서 명령어를 입력하는 2단계를 거친다. Claude Code는 그 구분 자체가 존재하지 않는다.

서버 디버깅. 로그를 읽고, 환경변수를 확인하고, 프로세스 상태를 점검하는 걸 바로 시킬 수 있다. "최근 에러 로그에서 500 응답만 필터링해서 원인 분석해줘"가 하나의 명령으로 완결된다. IDE 기반 도구는 이런 시스템 레벨 접근에서 제한이 생긴다.

반면 Claude Code가 약한 지점도 분명하다. 시각적 피드백이 필요한 모든 것이다. 컴포넌트 스타일링, 레이아웃 조정, 애니메이션 확인. 터미널에서 CSS가 어떻게 렌더링되는지 볼 방법은 없다. 프론트엔드 작업 경험이 있으니 이 한계가 더 선명하게 느껴진다. 디자인 시안과 비교하면서 코드를 고치는 작업은 Cursor 환경이 압도적으로 유리하다.

현재 내 워크플로우는 프론트 작업은 Cursor, 백엔드와 인프라는 Claude Code로 나눠 쓰는 것이다. 하나만 고르라면 못 고른다. 작업 성격에 따라 도구가 달라져야 한다는 게 2년간 프론트와 백엔드를 오가며 배운 것 중 하나다.

"프롬프트만 잘 쓰면 된다"에 속지 마라

"AI 도구는 프롬프트가 전부다." Claude Code에서는 절반만 맞는 얘기다.

같은 "이 API에 rate limiting 추가해줘"라는 프롬프트를 두 가지 조건에서 실행해봤다. CLAUDE.md가 없는 상태에서는 express-rate-limit를 새로 설치하고 기본 설정으로 app.use에 글로벌 미들웨어를 추가했다. 동작은 하지만 우리 프로젝트의 아키텍처와 맞지 않는다. CLAUDE.md에 "rate limiting은 Redis 기반으로, 기존 src/middleware/rate-limiter.ts를 확장할 것"이라고 한 줄 적어뒀더니 결과가 달라졌다. 기존 파일을 찾아 엔드포인트별 설정을 추가하고, Redis 연결도 기존 config를 재사용했다.

프롬프트는 동일한데 결과물이 전혀 다르다. "구체적으로 써라", "예시를 줘라"는 프롬프트 팁도 물론 도움이 된다. 그런데 매번 프롬프트에 프로젝트 맥락을 장황하게 적는 건 비현실적이다. CLAUDE.md에 한 번 정리해두면 이후 모든 세션에 자동 반영된다. 프롬프트 엔지니어링보다 컨텍스트 엔지니어링의 체감 효과가 크다는 걸 3주간 반복해서 확인했다.

Extended thinking이라는 기능도 언급할 가치가 있다. Claude Code에서 복잡한 추론이 필요한 작업을 시킬 때, 내부적으로 사고 과정을 확장하는 모드가 존재한다. 단순 코드 생성에는 큰 차이가 없지만, "이 모듈의 의존성을 분석해서 분리 전략을 제안해줘"처럼 아키텍처 수준의 질문에서는 응답 깊이가 달라진다. 토큰 소모가 늘어나는 대신 추론 품질이 올라가는 트레이드오프인데, 설계 단계에서는 써볼 만하다.

세션 간 기억: 메모리 기능

Claude Code에는 세션을 넘어 기억을 유지하는 메모리 기능이 있다. 선호하는 코딩 스타일이나 반복 작업 패턴을 기록해서 다음 세션에 반영한다. "try-catch 대신 Result 패턴을 선호해"라고 한 번 말해두면 이후에도 해당 패턴을 적용한다.

다만 프로젝트를 옮기면 이전 프로젝트의 맥락이 섞이는 문제가 있었다. Node.js 프로젝트에서 쓰던 컨벤션이 Python 스크립트 작업에서 튀어나온 적이 있다. 프로젝트별로 .claude/ 설정을 분리하면 줄일 수 있는 문제인데, 공식 문서에서 깊게 다루지 않아 직접 부딪혀야 알게 되는 영역이다.

컨텍스트 윈도우 — 크다고 좋은 게 아니다

"Claude는 200K 토큰 컨텍스트를 지원한다." 이 숫자를 보고 "거대한 코드베이스를 통째로 넣으면 되겠네"라고 기대하면 실망할 수 있다.

실제로 써보면 컨텍스트에 파일을 많이 넣을수록 응답 품질이 떨어지는 걸 느끼게 된다. 한번은 서비스 레이어 전체를 한꺼번에 리팩토링하려고 관련 파일 15개를 올렸다가, 의도와 다른 파일을 수정하고 이미 삭제된 함수를 참조하는 코드를 생성하는 걸 목격했다. 관련 파일 3~4개에 집중시키니 같은 작업의 정확도가 눈에 띄게 올라갔다. 이건 사람한테 서류 100장을 한꺼번에 읽으라고 하는 것과 비슷하다. 분량이 늘수록 핵심을 놓치기 쉽다.

Claude Code는 파일을 요청할 때 전체를 읽기보다 관련 부분을 선택적으로 가져온다. 그래도 사용자가 의식적으로 스코프를 관리하는 게 결과물에 영향을 준다. "전체 리팩토링"보다 "먼저 라우터만 수정하고, 그 다음에 서비스 레이어를 수정하자"처럼 단계를 나누는 게 낫다.

팁 하나. 새 세션을 시작할 때 /init을 먼저 실행하는 습관을 들이면 좋다. 이 명령어가 프로젝트 구조를 파악해서 내부적으로 인덱싱한다. /init 없이 바로 작업을 시키면 "파일이 어디 있는지"부터 탐색하느라 토큰을 소모하게 된다. 처음 Claude Code를 쓸 때 이걸 몰라서 40분 동안 헤맨 적이 있다. 그 40분은 Claude Code 탓이 아니라 내 탓이었다.

2주간 IDE 없이 백엔드만 개발해봤다

Claude Code가 실무에서 진짜 쓸 만한지 직접 확인하고 싶었다. 2주 동안 의도적으로 VS Code를 닫고, 터미널 + Claude Code만으로 백엔드 작업을 했다. M1 MacBook Pro, iTerm2, zsh 환경이다.

빨라진 것들

API 엔드포인트 작성이 체감상 1.5배 정도 빨라졌다. 이전에는 기존 라우터를 복사해서 이름을 바꾸고, 서비스 파일을 만들고, zod 스키마를 정의하는 보일러플레이트 과정이 있었다.

# 실제 작업 지시 예시 — 한 문장으로 라우터+서비스+스키마 생성
claude "POST /api/orders 엔드포인트를 추가해줘.
유효성 검사는 zod, 인증은 authGuard 미들웨어 적용.
src/routes/order.ts에 라우터, src/services/order-service.ts에 로직 분리"

# 에러 디버깅 — 에러 메시지를 그대로 전달
claude "npm run test 실행 결과를 보고 실패 원인을 분석해줘"

# 세션이 느려지면 정리하고 재시작
claude /clear

CLAUDE.md가 있으니 생성된 코드가 프로젝트 컨벤션에 맞아서, 별도 수정 없이 바로 돌아가는 경우가 절반 이상이었다. 나머지 절반도 소소한 수정 정도로 끝났다.

목요일 오후에 배포 직후 TypeError: Cannot read properties of undefined (reading 'userId')가 터지면서 서버가 불안정해진 적이 있다. 에러 로그와 관련 코드를 Claude Code에 전달하니, 호출 체인을 따라가면서 optional chaining이 빠진 지점을 정확히 짚어줬다. 이때 체감한 건, Claude Code가 단일 파일 에러보다 여러 파일에 걸친 호출 흐름을 추적하는 데 더 강하다는 거다. 서비스 → 리포지토리 → 미들웨어를 넘나드는 에러를 사람이 추적하면 10분은 걸릴 일을 2분 안에 잡아냈다.

git 작업과의 연계도 매끄러웠다. 하루 작업을 마치고 "오늘 변경된 내용으로 커밋 메시지 작성해줘"라고 하면 diff를 분석해서 의미 단위로 메시지를 제안한다. PR 설명도 "이 브랜치의 변경사항을 요약해줘"로 생성할 수 있다. 이건 생각보다 시간을 아껴주는 부분이다.

불편했던 것들

코드 리뷰 반영에서 마찰이 있었다. GitHub 웹에서 리뷰 코멘트를 읽고, Claude Code에 수동으로 전달하는 과정이 번거로웠다. GitHub MCP를 연결하면 PR 코멘트를 직접 읽을 수 있다는데, MCP 세팅 자체가 추가 작업이라 2주간의 실험 기간에는 시도하지 못했다.

긴 세션에서의 속도 저하도 체감했다. 대화가 30~40턴을 넘어가면 응답에 체감상 3~5초가 더 걸리는 느낌이었다. 정밀 측정은 아니지만 확실히 느려졌다. /clear로 세션을 끊고 새로 시작하면 복구된다. CLAUDE.md 덕분에 새 세션에서도 프로젝트 맥락을 바로 잡으니 이 전략이 유효하다.

비용도 변수다. Claude Max 구독 기준으로 월 $100(Opus 사용 제한)이나 $200(Opus 5시간/일) 선이다. API 직접 호출 방식은 사용량에 따라 이보다 많이 나올 수 있다. (출처: Anthropic 가격 페이지, 2026년 3월 기준) 개인이나 2~3명 팀이면 감당 가능한 수준이지만, 10명 이상 팀이라면 생산성 향상 대비 비용 시뮬레이션이 필수다. 우리 팀은 4명인데, 아직은 각자 개인 구독이라 팀 단위 비용 논의까지는 안 갔다.

MCP 연동이라는 확장 카드

이건 간단하게만 다룬다. 아직 깊게 써보지 못한 영역이기 때문이다.

MCP(Model Context Protocol)는 Claude Code를 외부 서비스와 연결하는 프로토콜이다. GitHub, Slack, 데이터베이스 등을 Claude Code 세션 안에서 직접 접근할 수 있게 해준다. (출처: Model Context Protocol 공식 사이트, 2024년 11월 공개)

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}

프로젝트 루트에 .mcp.json으로 저장하면 된다. GitHub MCP를 연결한 뒤 "리뷰 대기 중인 PR 목록 보여줘"라고 했더니 실제로 PR 리스트가 출력됐다. Slack이나 PostgreSQL 연동도 가능하다고 하는데, 이건 시간을 따로 잡아서 테스트해볼 생각이다.

Claude Code의 현재 한계

3주 실무 투입 결과, Claude Code가 터미널 기반 AI 코딩에서 꽤 쓸 만한 도구인 건 확인했다. 백엔드 작업 생산성이 올라간 것도 사실이다. 맹점이 없는 건 아니다.

대규모 코드베이스에서 성능이 흔들린다. 파일이 수백 개를 넘어가면 탐색이 느려지고, 간혹 관련 없는 파일을 건드리는 경우가 있었다. monorepo 구조에서는 "packages/api 디렉토리만 대상으로"처럼 작업 범위를 명시적으로 좁혀주는 게 안전하다.

코드 생성 정확도는 체감상 7~8할 수준이다. 단순한 CRUD는 거의 틀리지 않는다. 비즈니스 로직이 복잡해지면 미묘한 엣지 케이스를 놓치기 시작한다. 한번은 할인 계산 로직에서 퍼센트와 고정금액 할인이 중복 적용되는 케이스를 빠뜨린 걸 테스트에서 발견했다. AI 생성 코드를 리뷰 없이 머지하는 위험은 Claude Code만의 문제가 아니라 모든 AI 코딩 도구에 공통으로 해당되는 부분이다.

오프라인 사용이 불가능한 것도 제약이다. 코드가 외부 API로 전송되기 때문에, 보안 정책이 엄격한 조직에서는 도입 자체가 어렵다. Anthropic은 사용자 코드를 모델 학습에 사용하지 않는다고 명시하고 있지만(출처: Anthropic 이용약관, 2025년 업데이트), 정책 선언과 기술적 보장은 별개 문제다.

Claude Code의 업데이트 주기가 빠른 편이라 현재 약점 상당수가 개선될 가능성은 있다. 다만 "터미널 AI 코딩이 GUI IDE를 완전히 대체한다"고 말하기엔, 2026년 4월 기준으로 아직 이르다.

관련 글

Chiko IT
Chiko IT

Platform Engineer. Python, AI, Infra에 관심이 많습니다.

More posts