Claude Code로 개발할 때 알아두면 좋은 팁들

Claude Code로 개발하다 보면 AI가 코드를 작성해주는 건 좋은데, 개발 서버를 직접 실행하고 관리하는 부분에서 불편함을 느낄 때가 있다. 특히 서버를 띄우고 로그를 확인하면서 실시간으로 디버깅하는 워크플로우가 익숙한 개발자라면 더욱 그렇다.

몇 가지 간단한 설정으로 Claude Code와의 협업을 훨씬 더 편하게 만들 수 있다.

서버 로그는 파일로 남기자

개발 서버를 실행할 때 stdout을 파일로 리다이렉트해두면 Claude Code가 필요할 때 로그를 확인할 수 있다.

npm run dev > output.log 2>&1

그리고 프로젝트의 CLAUDE.md에 이렇게 적어두면 된다:

## Server Logs

Development server logs are stored in `output.log` in the server directory.
You can check the logs by reading this file.

이렇게 해두면 Claude Code가 에러를 디버깅할 때 알아서 로그 파일을 확인하고 문제를 파악한다. 매번 "로그 좀 봐줘"라고 말할 필요가 없다.

nodemon 설정 최적화

Claude Code를 사용해 Node.js 애플리케이션을 개발할 때 자주 마주치는 문제가 있다. 바로 프로세스 관리 다.

파일을 저장할 때마다 nodemon이 서버를 재시작하는데, 이전 프로세스가 제대로 종료되지 않으면 메모리 누수가 발생하거나 포트가 이미 사용 중이라는 에러가 뜨고, 좀비 프로세스가 쌓이기도 한다.

SIGTERM 신호 설정

nodemon.json에 한 줄만 추가하면 이 문제를 해결할 수 있다:

{
  "signal": "SIGTERM"
}

기본적으로 nodemon은 SIGUSR2 신호를 사용하는데, 이는 일부 상황에서 프로세스가 제대로 종료되지 않을 수 있다. SIGTERM 을 사용하면 프로세스에게 종료를 요청하고, 정리 작업 후 안전하게 종료할 수 있다.

Claude Code에 맞춘 nodemon 설정

Claude Code는 자동 저장 기능 이 활성화되어 있어 파일 변경이 매우 자주 발생한다. 저장할 때마다 재시작하면 CPU를 많이 사용하고 개발 흐름이 끊긴다.

실무에서 사용하기 좋은 완전한 설정 예시:

{
  "signal": "SIGTERM",
  "watch": ["src"],
  "ext": "ts,js,json",
  "ignore": [
    "**/*.test.ts",
    "**/*.spec.ts",
    "node_modules",
    "dist",
    "coverage",
    "*.config.js",
    ".env*",
    "README.md",
    "*.log"
  ],
  "exec": "ts-node --transpile-only src/index.ts",
  "delay": "2000"
}

delay: "2000" 설정으로 마지막 변경 후 2초를 대기하게 하면, 여러 파일을 연속으로 수정해도 한 번만 재시작된다.

애플리케이션에서 SIGTERM 처리하기

Node.js 애플리케이션에서 SIGTERM을 처리하는 코드도 추가하면 좋다:

process.on('SIGTERM', async () => {
  console.log('SIGTERM 신호를 받았습니다. 정리 작업을 시작합니다...');

  server.close();
  await db.close();

  console.log('정리 작업 완료. 프로세스를 종료합니다.');
  process.exit(0);
});

개발 환경은 osascript로 자동화

매번 터미널 여러 개 열고 명령어 입력하는 게 귀찮다면 osascript를 사용해보자. iTerm2를 쓴다면 이런 스크립트를 작성할 수 있다:

#!/usr/bin/osascript

tell application "iTerm"
    create window with default profile

    tell current session of current window
        write text "cd ~/project/backend && npm run dev > output.log 2>&1"
        split horizontally with default profile
    end tell

    tell second session of current tab of current window
        write text "cd ~/project/backend && tail -f output.log"
        split vertically with default profile
    end tell

    tell third session of current tab of current window
        write text "cd ~/project/webapp && npm run dev"
        split vertically with default profile
    end tell

    tell fourth session of current tab of current window
        write text "cd ~/project && caddy run"
    end tell
end tell

이 스크립트를 dev-start.scpt 같은 이름으로 저장하고 chmod +x dev-start.scpt로 실행 권한을 주면 된다. 이제 한 번의 명령으로 백엔드 서버, 로그 모니터링, 프론트엔드 서버, HTTPS 프록시까지 한 번에 띄워진다.

Claude Code는 서버를 실행하지 않게 하자

이게 가장 중요한 팁이다. Claude Code에게 서버를 실행하도록 시키지 말고, nodemon이나 위의 스크립트를 통해서 직접 실행해두는 게 좋다.

왜냐하면 Claude Code가 프로세스를 관리하면 로컬에서 실시간으로 같이 확인하면서 개발하기 어렵기 때문이다. 개발 서버가 띄워진 상태에서 브라우저를 열어두고, 코드 변경하면 바로바로 확인하는 워크플로우가 훨씬 자연스럽다.

CLAUDE.md에 이렇게 적어두면 된다:

## Development Server

The development server is already running with nodemon.
DO NOT run `npm run dev` or restart the server.
Code changes will be automatically reflected.
Just modify the code files.

Claude Code는 코드만 수정하고, 서버는 nodemon이 자동으로 재시작해준다. 브라우저를 새로고침하면 바로 변경사항이 반영된 걸 확인할 수 있다.

변수명은 명확하게 지어주자

Claude Code는 코드를 기반으로 동작하기 때문에 변수명이 매우 중요하다.

예를 들어 userCount와 userTotal이라는 변수가 있다고 하자. 개발자 입장에서는 userCount는 현재 활성 유저 수, userTotal은 전체 누적 가입자 수라는 의미로 사용하고 있을 수 있다. 하지만 Claude Code는 변수명만 보고 판단하기 때문에, 두 변수를 혼동해서 완전히 다른 의미로 사용할 수 있다.

// 혼동하기 쉬운 변수명
const userCount = getActiveUsers();
const userTotal = getTotalUsers();

// 명확한 변수명
const activeUserCount = getActiveUsers();
const totalRegisteredUsers = getTotalUsers();

비슷한 이름의 변수가 여러 개 있으면 Claude Code가 잘못된 변수를 참조하거나, 의도와 다른 로직을 구현할 확률이 높아진다. 특히 비슷한 역할을 하는 변수들이 많은 코드베이스에서 이런 문제가 자주 발생한다.

그래서 Claude Code와 함께 작업할 때는 변수명을 평소보다 더 명확하고 구체적으로 짓는 게 좋다. 사람 입장에서는 "이 정도면 알겠지"라고 생각해도, AI는 문맥을 완벽하게 파악하지 못할 수 있기 때문이다.

Playwright로 UI 검증하기

Claude Code는 Playwright MCP를 통해 브라우저를 직접 제어할 수 있다. 이 기능을 활용하면 복잡한 UI 개발을 훨씬 효율적으로 진행할 수 있다.

핵심은 구구절절 상황을 설명하지 말고, 명확한 수치 기반의 조건을 부여하는 것 이다.

예를 들어 "사이드바랑 메인 컨텐츠가 잘 정렬되어야 해"라고 말하면 Claude Code 입장에서는 "잘 정렬"이 뭔지 판단하기 어렵다. 대신 이렇게 구체적으로 요청하면 된다:

- 사이드바의 상단 경계와 메인 컨텐츠의 상단 경계가 일치해야 함
- 두 요소 사이의 간격은 정확히 24px
- 사이드바 너비는 280px로 고정

그리고 Claude Code에게 Playwright로 해당 요소들의 실제 수치를 로그로 출력하라고 시키면 된다:

const sidebar = await page.locator('.sidebar').boundingBox();
const mainContent = await page.locator('.main-content').boundingBox();

console.log('Sidebar:', sidebar);
console.log('Main Content:', mainContent);
console.log('Top alignment diff:', Math.abs(sidebar.y - mainContent.y));
console.log('Gap between elements:', mainContent.x - (sidebar.x + sidebar.width));

이렇게 하면 Claude Code가 로그를 확인하고 조건에 맞지 않는 부분을 스스로 찾아서 수정한다. "대충 맞는 것 같은데요"가 아니라 수치로 증명 할 수 있기 때문에 훨씬 정확한 결과물을 얻을 수 있다.

복잡한 레이아웃이나 반응형 UI를 개발할 때 특히 유용하다. 여러 브레이크포인트에서 각 요소의 크기와 위치가 어떻게 변하는지 수치로 확인하면서 개발할 수 있기 때문이다.

테스트 문서 먼저 만들기

브라우저로 테스트를 많이 하는 기능을 개발할 때는 테스트 문서를 먼저 만들어달라고 하는 것 이 효과적이다.

Claude Code에게 "이 기능 개발해줘"라고 바로 시키는 대신, "이 기능을 테스트하기 위한 테스트 시나리오를 먼저 작성해줘"라고 요청하는 것이다. 그러면 Claude Code가 체크리스트 형태로 테스트 항목들을 정리해준다:

## 로그인 기능 테스트 시나리오

### 정상 케이스
- [ ] 올바른 이메일/비밀번호로 로그인 시 대시보드로 이동
- [ ] 로그인 후 사용자 이름이 헤더에 표시됨
- [ ] 새로고침해도 로그인 상태 유지

### 에러 케이스
- [ ] 잘못된 비밀번호 입력 시 에러 메시지 표시
- [ ] 존재하지 않는 이메일 입력 시 에러 메시지 표시
- [ ] 빈 필드로 제출 시 유효성 검사 메시지 표시

### 엣지 케이스
- [ ] 연속 5회 실패 시 계정 잠금 안내
- [ ] 네트워크 오류 시 재시도 버튼 표시

이렇게 테스트 문서가 있으면 Claude Code가 Playwright로 문서에 있는 항목들을 하나씩 체계적으로 검증 할 수 있다. "잘 동작하는 것 같아요"가 아니라 "모든 테스트 항목을 통과했습니다"라는 명확한 결과를 얻을 수 있다.

특히 복잡한 폼이나 여러 상태를 가진 UI를 개발할 때 유용하다. 개발자가 놓치기 쉬운 엣지 케이스까지 Claude Code가 미리 정리해주기 때문에, 나중에 버그로 발견되는 일이 줄어든다.

코드가 안 될 때는 리뷰를 요청하자

Claude Code가 작성한 코드가 이상하게 동작하거나 아예 동작하지 않을 때가 있다. 원인을 찾기 어렵고 코드도 난잡해 보인다면, 증상을 설명하지 말고 리뷰를 요청 하는 게 효과적이다.

예를 들어 "이 코드가 동작 안 해", "에러가 나는데 원인을 모르겠어"라고 말하면 Claude Code가 추측으로 이것저것 시도하면서 코드가 더 꼬일 수 있다.

대신 이렇게 요청하면 된다:

"로그인 기능이 올바르게 동작하는지 리뷰해줘"
"결제 모듈 코드가 정상적으로 구현되었는지 검토해줘"

이렇게 하면 Claude Code가 전체적인 코드 흐름을 처음부터 검토하면서 잘못된 부분을 스스로 찾아낸다. 증상에 매몰되지 않고 코드 전체를 객관적으로 보기 때문에, 개발자도 놓쳤던 근본적인 문제를 발견할 확률이 높다.

정리

Claude Code와 함께 개발할 때는 역할 분담을 명확히 하는 게 중요하다:

• Claude Code: 코드 작성, 로직 구현, 버그 수정
• 개발자: 개발 환경 구축, 서버 실행, 실시간 모니터링

nodemon의 signal: "SIGTERM" 설정과 적절한 delay, ignore 설정을 해두면 Claude Code가 코드를 수정할 때마다 안정적으로 서버가 재시작된다. AI에게 모든 걸 맡기는 게 아니라, 각자 잘하는 일을 하게 만드는 게 핵심이다.

연관 포스트

• Claude Code 개발 가이드 - Claude Code 활용법 종합 가이드
• Claude Code로 복잡한 페이지 디버깅하기 - 문서화 전략으로 복잡한 버그 해결하기
• Claude Code로 개발했다면, 코드리뷰는 필수다 - 개발 후 코드리뷰의 중요성

참고

• nodemon 공식 문서
• Node.js Process Signals