Subicura's Blog

Chungsub Kim

무려 4년 만에 새 글입니다!! 🤯
바쁘다는 이유도 있었지만, 사실 그동안 재밌거나 흥미로운 신기술이 뜸했던 것 같습니다. 알아두면 유익한 2019 개발 이야기에 적었던 Next.js와 Kubernetes 같은 기술이 무려 5년 넘은 지금까지 큰 변화 없이 사용되고 있고, 유튜브의 인기로 누가 블로그를 보나.. 싶은 것도 있었습니다.
그러다 최근 Claude Code를 사용하면서 큰 충격과 공포을 받았고, AI와 코딩에 대한 생각을 정리해 보았습니다.
4년 만에 블로그 시스템(ruby+jekyll)도 Claude Code로 업데이트했습니다.
뭔가 오류가 뜨는 것 같지만, 기분탓입니다 ㅎ
                
            
Claude Code의 등장
GitHub Copilot을 시작으로 최근엔 Cursor를 사용하지만, AI 기능을 적극적으로 사용하진 않고, 여전히 코딩을 보조하는 역할로 사용하고 있습니다. 몇 글자 입력하면 알아서 코드를 제안하는 게 지금도 신기하지만, 반복적인 타이핑을 줄여줄 뿐 프로젝트가 커지고 코드가 복잡해지면 엉뚱하게 동작하기 시작합니다. 뭔가 잘 사용하는 고오오오수 분들도 많지만, AI 기능을 잘 사용하기 위해선 많은 노력이 필요해 보입니다. 결국 지지
그러던 중 Claude Code가 등장했습니다.
몇 달 전까지 모든 코드를 직접 작성했지만, 최근엔 AI로 90% 이상 작성하고 있습니다. 코딩 대신 집중하는 건 아키텍처 설계와 코드 리뷰입니다.
글자 수정이나 간격 조정 같은 간단한 작업도 AI에게 맡깁니다. 내가 직접 고치는 것보다, AI를 위해 문서와 요구사항을 정리하는 게 장기적으로 효율적이라고 생각하고 있습니다.
Claude Code와 Opus 4.1이 그 가능성을 보여줬고, AI의 발전 속도를 봤을 때, 스스로 이슈를 읽고 요구사항을 구체화하고 코드 PR까지 올리는 상황이 곧 다가올 거라 봅니다.
신입 개발자
ChatGPT는 전체 코드를 전달할 수 없어서 막힐 때 질문하거나 아키텍처를 구상할 때 사용했습니다.
GitHub Copilot과 Cursor, Windsurf 등 Editor와 연동된 도구가 나오면서 코드를 공유하고 직접적인 도움을 받기 시작했습니다. 하지만, AI 모델의 한계로 복잡한 코드는 잘 이해하지 못했고, 작업을 맡긴다기보단 내가 작업하는데 옆에서 도움을 조금씩 주는 포지션이였습니다.
그런데, Claude Code는 다릅니다. 똑똑한 신입 개발자와 짝코딩하는 느낌입니다.
코딩도 잘하고 손도 빠릅니다. 복잡한 코드도 잘 해석하며 단순히 “이렇게 수정하세요”라고 하는 게 아니라, “이 부분을 이런 식으로 진행해 보면 어떨까요?”라고 토론하고, 문서 정리나 기술 설명도 잘합니다. grep, git, npm 같은 명령어를 실행할 수 있어, 유연하고 강력하게 동작합니다.
코드만 보면 알 수 없는 프로젝트의 맥락이나 암묵적 규칙, 예외 상황도 잘 정리해서 알려주면 기가 막히게 이해합니다. 예전에 AI가 엉뚱한 답을 내놓으면 “역시 아직 멀었군”AI 탓이란 생각이었는데, 요즘엔 “내가 애매하게 전달했군”내 탓이란 생각을 합니다.
실제로 회사에 신입이 들어오면 프로젝트 구조를 설명하고 작은 작업을 맡기고 리뷰하면서 온보딩을 하듯이, 거의 동일한 피드백 루프를 Claude Code와 함께 합니다.
AI의 특징
AI는 똑똑하지만, 기억력이 좋지 않습니다.
메멘토(2000)란 영화의 주인공이 단기 기억상실증이 있어서, 사진, 메모, 문신에 기억을 기록했는데, AI도 동일하게 대화 내용을 어딘가 기록해 두고 새로운 요청을 보내면 기존 대화를 그대로 다시 보냅니다. 새로운 대화 세션을 만들면, 기존 대화는 기억을 못 한다고 보는 게 편합니다.
똑똑하지만 매일 기억을 잃는 신입이라면 무엇을 해야 할까요? 그래서 문서화와 리팩토링이 중요합니다. 항상 새로 출근하는 신입 개발자를 위해 최신화된 문서와 헷갈리지 않는 코드 품질을 유지해야 합니다.
Garbage In, Garbage Out
쓰레기를 넣으면 쓰레기가 나온다.
1950~60년대 초창기 컴퓨터 과학자들과 프로그래머들 사이에서 자주 쓰이던 말입니다. 컴퓨터는 “생각”하지 않고 입력값을 그대로 연산하기 때문에, 입력이 부정확하면 아무리 성능이 좋아도 결과가 쓸모없다는 교훈을 담고 있습니다.
AI 시대에도 동일합니다. 지브리 스타일로 그려달라고 하면 지브리 스타일로 그리고, 픽사 스타일로 그려달라고 하면 픽사 스타일로 그립니다.
“모바일 메뉴를 추가해 줘” 라는 요구사항은 언뜻 괜찮아 보이지만, 모바일 메뉴에서 흔히 사용하는 햄버거 버튼을 2줄을 사용할지 3줄을 사용할지 알 수 없고, 왼쪽 위에 그릴지, 오른쪽 위에 그릴지도 알 수 없습니다. 메뉴를 누르면 나오는 화면이 꽉 차게 원하는지, 반만 가리는지도 알 수 없습니다. 요청자는 머릿속 그림을 상대방도 알 거라고 생각합니다.
AI는 입력을 보고 최대한 의도를 파악해서 답하지만, 말하지 않은 생각을 읽을 수는 없습니다.
Claude Code 시작하기
대략적인 특징을 알았으니, 일단 써봅시다.
Claude Code는 에디터가 아닙니다. 단독으로 실행하는 대화형 프로그램으로 이야기를 주고받으며 코드를 읽고 쓰고, 다양한 명령을 수행합니다.
설치하기
Node.js를 설치하고 다음 명령어를 입력합니다.
설치했으면, claude 명령어로 시작합니다.
CLI 기본
Claude Code는 다양한 기능이 있는데, 딱히 몰라도 쓰는 데 문제없습니다. 몇 가지 자주 사용하는 명령어를 알아봅시다.
alias를 설정합니다. claude 매번 치기 귀찮..
shift+enter로 여러 줄 입력할 수 있게 terminal 설정을 합니다.
방금 사용했던 세션으로 다시 시작하고 싶다면 --continue 옵션을 사용합니다.
예전에 사용했던 세션을 보고 선택하고 싶다면 --resume 옵션을 사용합니다.
계획을 먼저 듣고 싶다면 shift+tab을 눌러 plan 모드를 설정합니다. 앞으로 자주 쓸 거에요.
CLAUDE.md
CLAUDE.md 파일은 Claude Code가 대화를 시작할 때 자동으로 가져오는 파일입니다. 내용을 잘 작성한다면 컨텍스트 수집이나 토큰 사용량을 최적화할 수 있고, 더 정확한 답변을 얻을 수 있습니다.
CLAUDE.md 생성
보통 프로젝트 루트에 CLAUDE.md 파일을 만들고 다음과 같은 내용을 적습니다.
기본 명령어 (빌드, 테스트, 개발 서버 실행 등)
핵심 파일 및 함수 설명
코드 스타일 가이드
테스트 작성 가이드
알리고 싶은 것
    
비즈니스에 대한 내용
암묵적인 규칙들
예외 사항
하지 말 것
처음 파일을 만드는 거라면 claude /init 명령어로 자동 생성하고 수정하는게 편합니다.
샘플
CLAUDE.md 업데이트
Claude Code랑 작업하다 보면 의도와 다르게 동작하는 경우가 있습니다. 그럴 때마다 파일을 업데이트합니다. 위 예시에선, Claude가 자꾸 아이콘을 svg로 만들어서 사용하려고 해서 lucide icon을 사용하게 했고, 다크 모드를 고려 안 하고 class를 설정하는 경우가 있어 다크 모드에 대한 안내를 추가했습니다.
직접 내용을 편집해도 되지만, 그냥 Claude Code에 맡겨도 됩니다. xxx 를 다시 실수하지 않도록, CLAUDE.md 파일에 내용을 업데이트해 줘
CLAUDE.md 관리
파일 하나가 커지면 분리해서 관리할 수 있습니다. (메모리 관리 참고)
사용자 메모리(~/.claude/CLAUDE.md)를 설정하면 모든 프로젝트에 공통 내용을 적용할 수 있습니다.
현재, 이 정도 내용을 사용 중입니다.
IDE 연동
VSCode(Cursor)나 IntelliJ 터미널에서 claude를 실행하고 /ide 명령으로 연동할 수 있습니다.
선택한 파일이나 코드 컨텍스트를 전달하는 기능이 있는데 보통, diff를 이쁘게 보는 용도로 주로 사용합니다.
Super Claude
Claude Code는 확장할 수 있는 구조로 되어 있습니다. 예를 들어서, 너는 10년 차 보안 전문가야... 같은 품질에 도움이 되는 문구를 매번 입력하지 않고 나만의 명령어를 만들 수 있습니다.
누군가 이런 게 있으면 좋겠다 싶은걸 모았고 가장 유명한 게 Super Claude입니다.
다음 명령어로 설치합니다.
체감상 엄청나게 좋아진다기보단, 설치하기 귀찮은 mcp를 쉽게 설치해주고, /sc:analyze 처럼 특화된 기능을 손쉽게 사용할 수 있습니다.
Model (Opus vs Sonnet)
Claude Code는 현재 Opus와 Sonnet을 지원합니다.
모델
      장점
      단점
      추천 상황
    
Opus
      복잡한 작업 가능, 정확도 높음
      느림, 비용 높음
      복잡한 아키텍처 설계
    
Sonnet
      빠른 응답, 저렴
      복잡한 작업 제한적
      간단한 수정, 문서 작성
    
무료나 Pro 계정으론 Opus를 거의 사용할 수 없습니다. Opus가 훨씬 강력하므로 Claude Code를 제대로 사용하고 싶다면 Max 5x 플랜($100/month) 이상을 추천합니다.
워크플로우
Claude Code는 정해진 워크플로우가 없습니다. 요구사항만 잘 정리하면 대부분 잘 작동하지만, 일반적으로 계획을 먼저 세우면 결과가 더 좋아집니다.
plan mode로 일을 요청하고 내 의도를 정확히 파악했는지 확인하는게 기본 전략입니다.
다음은 Claude Code와 작업할 때 도움이 되는 몇가지 팁입니다.
추가 정보 전달
살펴보거나 작업하길 원하는 파일이 있다면 같이 전달합니다.
❌ 장바구니 담기 이벤트를 전송할 때, 상품의 금액 정보를 추가해 줘.
✅ 장바구니 담기 이벤트가 @cart-event.ts에 정의되어 있어. 현재, 상품 코드랑 수량만 전달하고 있는데 상품 금액을 추가해 줘.
요구사항 개선
엉뚱한 소리를 하는 경우는 몇 가지 상황이 있습니다.
너무 큰 작업을 준 경우, 작업을 더 작개 쪼갭니다.
예외적인 상황을 이해 못 한 경우, 문서에 내용을 추가합니다.
맥락을 이해하지 못한 경우, 요구사항을 조금 더 구체화합니다.
파일 기반 작업
복잡한 작업은 한 번에 진행하지 말고, 개발 계획을 PLAN.md 파일로 만들고 작업합니다. 계획을 파일로 만들어 달라고 하고, 계획을 리뷰해서 파일을 업데이트하고, 파일 기반으로 일하면 더 구조적으로 일할 수 있습니다.
리뷰
아직 AI가 작성한 코드를 다 믿을 수 없습니다. 계획을 세우고 코드를 작성하기 시작하면 처음 1-2번 정도 수정을 의도대로 하고 있는지 확인하고 나머지 작업을 맡깁니다. 작업이 끝나면 코드 리뷰를 하고 다시 수정 요청하거나, 문서를 보완합니다.
사례모음
Claude Code는 기능 구현외에 다양한 업무에 활용할 수 있습니다.
신규 웹 서비스 구축
유명한 라이브러리를 쓰면, AI도 잘 이해할 확률이 높습니다.
최근에 신규 서비스를 구축할 땐 다음 기술 스택을 주로 사용합니다.
Next.js - 프론트엔드 & API
shadcn - UI 라이브러리
템플릿
    
Magic UI
21st.dev
백엔드
    
supabase
hasura
Next.js 프로젝트를 만들고 다음 명령어면 기본 뚝딱입니다.
기술 부채 해결
그동안 묵혀두었던 작업들(마이그레이션, 버전 업데이트 등), 손이 많이 가는 작업을 맡겨봅니다. 본 업무와 병행해도 부담없이 진행해볼 수 있습니다. 1~2주 예상했던 작업을 하루 만에 했다는 이야기도 많이 들립니다.
테스트 코드 작성
테스트 코드는 중요하지만, 작성하려면 귀찮은 경우가 많습니다. 그럴 때 Claude Code를 사용하면 좋습니다. 위 예시는 테스트 케이스를 사람이 이해하기 쉽게 md 파일로 관리하고 그 내용을 바탕으로 테스트 코드를 작성하게 요청한 경우입니다. 테스트 코드 작성부터 실행까지 스스로 합니다.
동작 방식 문서화
로직이 복잡한 코드는 요약된 문서를 보면 도움이 됩니다. Claude Code는 복잡한 코드를 분석해서 보기 좋게 문서로 만드는 작업을 잘합니다.
그 외
로그 메시지 가독성 개선: 보통 로그 메시지는 별도 기획 없이 개발자 재량으로 작성하는 경우가 많아, 문구가 통일되지 않고 이해하기 어려운 경우가 있습니다. 보기 좋게 다듬고 통일성 있게 수정하는 것도 잘합니다.
Git 관련 작업: 특정 브랜치를 리뷰하거나, 변경 사항을 파악할 때 도움을 받을 수 있습니다. 그리고 파일 되돌리기, 패치 비교 같은 복잡한 Git 작업도 잘합니다.
그 외에 신입 개발자가 할 수 있는 일은 모두 가능해요.
핵심역량
AI와 함께 일할 때 필요한 역량을 정리해 봅니다.
기본기+경험: 언어, 프레임워크, Git, DB/Cache/Queue 특성, 네트워크·인프라, 배포 파이프라인에 대한 이해
프로젝트 맥락: 설계·결정 배경·예외 규칙을 파악하고 유지하는 능력
비즈니스 이해: 고객이 원하는 바를 명확히 정리하고 전달하는 능력
문제에 집중: 코드 자체보다 “문제를 푸는 과정”에 집중하는 태도
정리하기: 코드 구조를 정리·리팩토링하고 일관성을 유지하는 능력
문서화: 아이디어·의사결정·지식을 명확하게 글로 정리하는 능력
메타인지: 나와 AI의 강점·약점을 구분하고, AI의 결과를 점검·보완하는 능력
그래서
최근 메타는 AI가 중급 개발자를 대체한다고 했고, 구글은 최근 작성한 코드의 1/4은 AI가 작성한 코드라고 합니다. 그래서 GCP 버그가.. AI의 발전과 개발자의 미래가 어떻게 될지는 아무도 모릅니다. 하지만 AI가 더 똑똑해지고, 빨라질 거라는 건 거의 확실합니다. 이런 상황에서 할 수 있는 건 열심히 대응하는 거라고 생각합니다.
우린 답을 찾을 것이다. 늘 그랬듯이. 모두 화이팅입니다~!
참고링크
Claude Code: 에이전트 코딩을 위한 모범 사례
Using Claude Code with your Pro or Max plan

초보를 위한 Claude Code 안내서

댓글