Claude Code를 본격적으로 개발에 도입한 지 약 반년이 지났다. 처음에는 "터미널에서 동작하는 AI 어시스턴트? VS Code 확장 프로그램이면 충분하지 않나?"라고 생각했지만, 지금은 완전히 메인 개발 도구가 되었다.

이 기사에서는 실제로 Claude Code로 일상적인 개발을 하고 있는 입장에서, 정말 쓸 수 있는 Tips만 철저히 해설한다. "AI가 편리합니다!"와 같은 막연한 이야기가 아니라, 구체적인 커맨드(Command)와 설정을 전부 적는다.

SES 엔지니어로서 현장에서 사용할 경우의 주의점이나, 프리랜서 독립 준비를 위한 스킬업에 대해서도 다루지만, 메인은 어디까지나 "Claude Code의 실전적인 사용법"이다.

Claude Code의 최우선 파일은 CLAUDE.md다. 프로젝트 루트(Project Root)에 두면, Claude Code가 매번 대화를 시작할 때 자동으로 읽어 들인다. 말하자면 "AI를 위한 지시서"이며, 이것을 어떻게 작성하느냐에 따라 출력 품질이 극적으로 변한다.

실제로 내가 사용하고 있는 구성은 다음과 같다:

# 프로젝트 개요
이 리포지토리(Repository)는 XXX의 백엔드 API.
TypeScript + Hono + Cloudflare Workers로 동작함.
...

처음에는 "이렇게 해줬으면 좋겠다"라고만 적었지만, 금지 사항을 명시하는 것이 효과가 더 높다는 것을 깨달았다. AI는 "좋은 의도로" 불필요한 일을 하기 쉬우므로, 명확하게 제한을 거는 편이 더 잘 작동한다.

예를 들어 이전에 Claude Code가 멋대로 패키지를 추가하여 의존 관계(Dependency)가 깨진 적이 있었다. 그 이후로 CLAUDE.md에 금지 사항으로 적어두고 있다.

# 프로젝트 디렉토리에서 실행
cd ~/my-project
claude

이것뿐이다. VS Code를 열 필요도 없다. 터미널 하나로 완결되는 것이 Claude Code의 강점이다.

비자명한(Non-trivial) 태스크에서는 갑자기 코드를 쓰게 하지 않는다. 먼저 계획을 세우게 한다.

대화 속에서 "먼저 계획을 세워줘"라고 말하거나, /plan을 입력하면 계획 모드(Plan Mode)로 들어간다.

> /plan
> 이 API에 페이지네이션(Pagination) 기능을 추가하고 싶어. 현재 코드를 읽고,
> 어떤 파일을 어떻게 변경할지 계획을 작성해줘.

Claude Code가 관련 파일을 읽고 변경 계획을 제시해 준다. 이를 확인한 뒤 구현에 들어가면 재작업(Re-work)이 급감한다.

실제 경험: 계획 모드를 사용하지 않고 "페이지네이션 추가해줘"라고 통째로 맡겼더니, 기존의 응답 형식을 깨뜨려 버렸다. 계획 모드에서 "기존 응답 형식은 유지해줘"라고 사전에 확인했다면 막을 수 있었을 것이다.

Claude Code에는 "Agent"라는 기능이 있다. 메인 대화와 독립된 에이전트를 기동하여 병렬로 작업을 시킬 수 있다.

내가 자주 사용하는 패턴:

리서치용 에이전트: 코드베이스 조사를 맡김 -
테스트 실행 에이전트: 백그라운드에서 테스트를 돌림 -
리뷰용 에이전트: 변경 내용의 독립 리뷰

메인 컨텍스트 윈도우(Context Window)를 더럽히지 않고 조사할 수 있다는 점이 은근히 크다. 규모가 큰 코드베이스에서는 "그 파일이 어디였더라" 하는 조사만으로도 컨텍스트가 가득 차 버리기 때문이다.

> /commit

이것으로 변경 내용을 읽어 들여, 적절한 커밋 메시지(Commit Message)를 생성하여 커밋해 준다. 커밋 메시지를 생각하는 시간이 제로가 되었다.

단, 주의할 점이 있다:

.env 파일 등의 기밀 정보가 포함되어 있지 않은지 확인된다 -
기본적으로 git add -A가 아니라, 개별 파일을 지정하여 스테이징(Staging)한다 -
Co-Authored-By: Claude가 자동으로 붙는다

Claude Code에는 find나 grep 커맨드 대신, 전용 Glob 툴과 Grep 툴이 있다. 이것들은 파일 검색이나 문자열 검색에 최적화되어 있어, 일반적인 커맨드보다 빠르고 정확하게 코드를 찾을 수 있다.

"이 함수 어디서 쓰이고 있어?"라고 물으면 Claude Code가 내부적으로 Grep을 사용하여 모든 파일을 검색해 준다.

큰 파일을 통째로 다시 쓰는 것이 아니라, 변경 부분만 지정하여 편집하는 Edit 툴이 있다. 파일 전체를 전송하는 Write와 비교했을 때, 토큰(Token) 소비가 대폭 적다.

Claude Code에게 "이 함수의 버그를 고쳐줘"라고 말하면, 해당 부분만 차분(Diff) 편집해 준다.

앞서 언급한 바와 같이, 구체적인 예를 조금 더:

데이터베이스

• ORM은 Drizzle을 사용함
• 마이그레이션(Migration)은 bun run db:migrate로 실행
  ...

Claude Code는 기본적으로 파일 쓰기나 명령 실행 시 확인을 요청한다. 이를 적절히 설정함으로써 안전성과 효율성의 균형을 맞출 수 있다.

settings.json에서 특정 명령을 허용 리스트(Allowlist)에 넣을 수 있다:

{
"permissions": {
"allow": [
...

테스트 명령이나 git 읽기 관련 작업은 자동 허용으로 설정해 두면, 매번 확인 다이얼로그가 뜨지 않아 쾌적하게 사용할 수 있다.

Claude Code의 '훅(Hook)'을 사용하면 특정 이벤트에 따라 쉘 명령(Shell Command)을 자동으로 실행할 수 있다.

예를 들어, 파일 편집 후에 자동으로 린트(Lint)를 실행하는 설정:

{
"hooks": {
"PostToolUse": [
...

이를 통해 "Claude Code가 편집 → 자동으로 포맷팅"이 실현된다.

Claude Code에는 세션 간에 정보를 유지하는 '메모리(Memory)' 기능이 있다. 이는 ~/.claude/projects/<프로젝트 경로>/memory/에 Markdown 파일로 저장된다.

"이것 좀 기억해 둬"라고 말하면 자동으로 저장해주지만, 중요한 결정 사항을 직접 저장하게 할 수도 있다:

> 이 프로젝트에서는 API 응답 형식으로
> { data: T, meta: { total: number, page: number } }
> 를 통일된 포맷으로 사용하고 있어. 기억해 둬.

다음 대화에서 "API 응답 형식은?"이라고 물으면 메모리에서 정보를 불러온다.

빌드나 테스트처럼 시간이 걸리는 명령은 백그라운드(Background)에서 실행시키고, 완료되면 알림을 받을 수 있다:

> 백그라운드에서 테스트 전부 돌려줘. 끝나면 결과 알려줘.

테스트가 돌아가는 동안 다른 작업을 의뢰할 수 있으므로 대기 시간이 거의 제로에 가깝다.

긴 대화를 계속하면 Claude Code의 컨텍스트(Context)가 압축된다. 이 과정에서 중요한 정보가 유실될 수 있다.

대책:

• 큰 태스크는 서브 에이전트(Sub-agent)로 분할한다
• 하나의 대화에서 여러 개의 무관한 태스크를 수행하지 않는다
• 중요한 결정 사항은 메모리에 저장한다

Claude Code가 작성한 코드를 확인하지 않고 그대로 커밋(Commit)했다가 버그를 넣은 적이 몇 번 있다.

대책:

• git diff로 변경 내용을 반드시 육안으로 확인한다
• 테스트를 작성한 후 구현을 의뢰한다 (TDD 스타일)
• Claude Code 스스로에게 "이 변경 사항으로 기존 테스트가 통과하는지 확인해줘"라고 요청한다

Claude Code와 별개로 Anthropic API를 직접 호출하는 코드를 작성했다가 예상치 못한 비용이 발생한 적이 있다. Claude Code 자체는 구독(Max Plan 등)을 통해 사용할 수 있지만, API 직접 호출은 종량제(Pay-as-you-go)이므로 주의가 필요하다.

대책:

• CLAUDE.md에 "API 직접 호출 금지"를 명시한다 - 필요한 경우 Claude CLI를 경유한다
• 환경 변수의 API KEY를 무효화해 둔다

실제로 Claude Code로 개발 중인 TypeScript 프로젝트에서의 사용법을 소개한다.

> 이 프로젝트에 RSS 피드 생성 기능을 추가하고 싶어.
> 먼저 기존 코드를 읽고, 어디에 어떻게 추가할지 계획을 세워줘.

Claude Code가 src/ 이하의 파일 구조를 읽고, 기존 라우팅(Routing)과 데이터 흐름(Data Flow)을 파악한 후 계획을 제시한다.

계획을 확인한 후:

> OK, 그 계획대로 진행해줘. 테스트도 작성해줘.

> `bun test`를 실행했더니 3건이 실패했어. 수정해줘.

Claude Code가 테스트를 실행하고, 에러 메시지를 읽고, 해당 코드를 수정하며, 다시 테스트를 실행하여 통과하는 것을 확인한다. 여기까지 전부 자동이다.

> src/content/generator.ts 파일이 너무 커졌어.
> 책임을 분리하고, 모든 테스트가 통과하는 상태를 유지하면서 리팩터링(Refactoring)해줘.

파일 분할이나 인터페이스(Interface) 추출을 제안해 준다. 변경할 때마다 테스트를 확인하므로, 리팩터링으로 인한 퇴보(Regression)를 방지할 수 있다.

SES 엔지니어로서 고객사에 상주하는 경우, Claude Code 이용 시 몇 가지 주의할 점이 있다.

• 클라이언트의 소스 코드를 Claude Code로 전송하게 되므로, 반드시 보안 정책을 확인할 것
• 기밀 정보가 포함된 파일은 .claudeignore로 제외 설정 가능
• 사내 네트워크에서의 외부 API 통신이 허용되어 있는지 확인

AI 도구를 능숙하게 다루는 엔지니어와 그렇지 못한 엔지니어 사이에는 생산성에서 명확한 차이가 나타나고 있다. SES 단가 시세를 고려할 때, AI 도구 활용 기술은 앞으로 점점 더 중요한 차별화 요소가 될 것이다.

프리랜서로 독립할 때도 "AI 도구를 사용한 고속 개발"이 가능하다는 점은 큰 무기가 된다. 프리랜서 독립 준비로서 Claude Code와 같은 도구에 익숙해져 두는 것을 권장한다.

2026년 현재, AI 코딩 도구에는 주로 3가지 선택지가 있다:

나만의 활용법:

• 신규 프로젝트 시작, 대규모 리팩터링 (Refactoring) → Claude Code
• 기존 코드에 대한 작은 변경, 보완이 필요할 때 → Copilot
• 프런트엔드 (Frontend) UI 조정 → Cursor

Claude Code의 최대 강점은 "터미널에서 완결되는 자율성"이다. 파일 읽기/쓰기, 테스트 실행, git 커밋까지 전부 수행해 준다. Copilot은 보완 기능은 우수하지만, 프로젝트 전체를 조망하는 작업에는 서툴다.

• CLAUDE.md에 투자하기: 프로젝트 고유의 규칙과 금지 사항을 정성껏 작성할 것
• 계획 → 실행 → 검증의 사이클 준수: 갑자기 코드를 작성하게 하지 말 것
• AI의 출력을 너무 신뢰하지 말 것: 반드시 diff를 확인하고, 테스트로 검증할 것

Claude Code는 "마법 지팡이"는 아니지만, 올바르게 사용하면 개발 속도를 대폭 높일 수 있는 도구다. 특히 개인 개발이나 프리랜서로 독립한 후에는, 혼자서 여러 프로젝트를 처리할 때 강력한 무기가 된다.

SES 단가 시세가 궁금한 엔지니어도, 프리랜서 독립 준비 중인 엔지니어도, 우선 Claude Code를 직접 만져보는 것을 권한다. 구독(Max Plan)으로 사용할 수 있어, API 종량제 과금을 걱정하지 않고 테스트해 볼 수 있다는 점도 좋다.

• OpenClaw × Claude Code 실전 가이드 | AI 주도 개발의 구체적 워크플로우 【2026년 최신】
• Claude Code로 개발 속도 3배 | SES에서 프리랜서가 되어 바뀐 일하는 방식 【2026년 최신】
• OpenClaw × Claude Code 연계 철저 해설 【2026년 최신】 AI 에이전트 실전 가이드

AI 주도塾 — AI를 사용한 스몰 비즈니스 구축법을 배우는 곳

Claude Code, OpenClaw, AI 경영 OS의 실전 노하우를 매주 공개 중.

월액 ¥4,980로 과거 기사 모두 무제한 열람 가능.

SES 해체신서 프리랜서 DB에서는 고단가 프로젝트를 다수 게재 중입니다.

• ✅ 마진율 공개로 투명한 거래
• ✅ AI/클라우드/Web 계열 엄선 프로젝트
• ✅ 전담 코디네이터가 단가 협상 지원