회사에서 AI 도구를 자유롭게 활용할 수 있도록 지원해 준 덕분에, 그동안 Cursor, Cline, Copilot 등 다양한 코딩 에이전트를 활용해 개발 생산성을 높일 수 있었습니다. 그러던 중 지난 2025년 6월 24일 Anthropic에서 터미널 기반의 코딩 에이전트인 Claude Code를 정식 출시했습니다.
터미널은 개발자가 컴퓨터와 직접 대화를 나눌 수 있는 창구라서 떼려야 뗄 수 없지만, GUI의 도움을 받아 개발 하다보면 터미널에 익숙하지 않을 수 있습니다. GUI가 편하기도 하고요. 그래서 별도 GUI 인터페이스를 갖추고 있는 Cursor, Cline 같은 도구를 사용해 오던 입장에서, 처음에 Claude Code 컨셉만 들었을땐 마냥 불편할 것만 같았습니다.
그런데 막상 써보니 인터페이스가 터미널이라 굉장히 가벼울 뿐 아니라, 특정 IDE에 종속되지 않고 어디서든 쓸 수 있다는 점이 장점으로 느껴졌습니다. 특히 JVM 환경에서 주로 개발하다 보니, 프로젝트 인덱싱, 컴파일, 빌드 등의 과정이 Cursor나 Cline에서는 다소 불편하게 느껴졌는데, Claude Code는 IntelliJ의 터미널에서 실행되니 마치 플러그인 하나 설치해 쓰는 듯한 경험이었습니다. 그래서 Cursor를 주로 사용하던 저는 이제 Claude Code만 쓰는 사람이 되었습니다.
코딩 에이전트를 포함한 AI 기술은 하루가 다르게 빠르게 발전하고 있습니다. 일주일, 한 달만 지나도 새로운 기술과 모델이 나오고, 이전 것은 금세 시야에서 사라집니다. 개발자는 그때마다 새로운 경험을 맞이하게 됩니다. Cursor, Cline 같은 도구를 쓰면서 이 다음에 뭐가 나올까 궁금했는데 Claude Code가 하나의 변곡점이 될 거라는 느낌을 받았습니다.
혼자서 스터디도 하고 사내 엔지니어들과 이야기를 나누면서 Claude Code를 더 잘 써보기 위한 방법들을 하나 둘 찾아나갔고, 지난 달 전사 테크 올핸즈에서 ‘한 번 쓰고 끝이 아니다. 끊임없이 진화하는 코딩 에이전트 활용법’ 이라는 주제로 Claude Code 사용 방법에 대해 공유했습니다.
결국 코딩 에이전트를 사용하는 목적 중 하나는 생산성을 극대화 시키기 위함인데, 코딩 에이전트에게 무언가 시키고 나면 다시 제가 직접 수정하는 일이 생겼고 이건 목적에서 조금은 벗어난다는 생각이 들었습니다. ‘이럴 거면 내가 짜는 게 낫지‘ 라는 결론으로 이어질 수도 있고요. 그래서 Claude Code를 더 잘 활용하기 위해 Rules, Custom commands, Hooks 등을 작성했고, 머지 않아 또 다른 패러다임에 변화가 올거라 믿지만, 개인 블로그에도 간단하게 기록차 남겨봅니다.
Claude Code 101
다들 첫 출근날과 처음으로 업무 받은 날을 기억하나요? 만약 어떤 회사에 입사를 했는데 팀에 나 혼자라고 가정해봅시다. 업무를 받았으니 무언가 해야 되는데 참고할 만한 문서가 있긴 한데 많이 부실합니다. 그리고 작성된 코드 양은 너무 많아서 어디 부터 봐야 할 지 모르는 상황입니다. 이럴때 우리는 어떻게 해야할까요?
‘어떤 것부터 알면 될까?’ 생각이 들텐데, 실제로는 내가 뭘 알아야 하는지도 모르는 상태입니다. 아는게 있어야 뭘 모르는지도 알게 될테니까요. 그렇다면 이 상황을 어떻게 해결하면 좋을까요? 간단한 방법은 2가지가 있습니다. 누군가에게 일단 물어보거나, 스스로 알아갈 때까지 고뇌하는 것입니다.
이런 상황을 해결하기 위해 회사는 ‘신규 입사자 온보딩’ 프로그램을 운영하곤 합니다. 신규 입사자가 왔을때 여기는 어떤 문화를 가지고 있고, 시스템은 어떻고, 나는 어떤 일을 어떻게 하면 되는지 방법을 알려줍니다. 새로 온 동료가 그동안의 오래된 제품에 대한 맥락과 팀의 일하는 방식을 알아가기 까지 스스로 한다면 더 오랜 시간이 걸릴텐데, 잘 정리되어 있는 문서나 참고해야 할 요소들이 많다면 더 빠르게 알아갈 수 있을거에요.
코딩 에이전트도 이와 크게 다르지 않습니다. 무작정 코딩 에이전트에게 ‘1000원 할인 코드 작성해줘’ 라고 하면 코딩 에이전트는 구체적인 정보를 찾기 위해 더 많은 시간을 쓰고 알지 못한다면 추측을 하기도 합니다. 그래서 코딩 에이전트가 나와 수년을 함께 한 동료가 되기 위해서는 알고 있는 모든 것을 알려줘야 합니다.
우리 팀의 프로젝트 아키텍처는 어떤 형태로 구성되어 있는지 자세히 알려줘야 합니다. 의존성 규칙과 방향이 강제되어 있다면 이 또한 반드시 알려줘야 합니다.
코드 컨벤션이 있다면 이 또한 자세히 가이드 해줘야 합니다. 팀에서 사용중인 코드 컨벤션이 없다면 각 언어의 공식 컨벤션이라도 알려주면 좋습니다. 저희 팀은 클래스 네이밍에 Alistair Cockburn이 언급한 원칙인 the name should be the goal as a short active verb phrase 을 준수합니다. 이름만 보고도 그 클래스의 역할과 책임이 명확히 드러나야 하고, 역할과 책임 그리고 의미있는 접미사/접두사를 사용합니다. 그래서 대부분의 클래스는 동사 + 역할 + 접미사 의 조합으로 이름을 짓고 있습니다.
팀에서 사용중인 테스트 작성법이 있다면 이것도 자세히 알려줍니다. 저희 팀은 외부 의존성이 필요한 Mocking Library 사용을 지양하고, 조금 더 Production Code 변화에 유연하게 대응하기 위해 Test Double을 직접 만들어서 사용합니다. 그리고 테스트 코드를 구조화해서 가독성, 유지보수성, 일관성을 끌어 올리기 위해 AAA(Arrange, Act, Assert) 패턴을 사용합니다.
커밋을 작성할 때에도 기본 형식이 있습니다. 커밋 메시지의 맨 앞에는 이슈 티켓을 입력하고, 그 다음에는 어떤 유형의 커밋이고 어떤 모듈의 변화인지, 그리고 마지막에는 커밋의 설명을 간단하게 작성합니다.
GZ-{티켓번호} {타입}({모듈}): {설명}
Claude Code는 우리 팀이 이렇게 일한다는 사실을 알고 있을까요? 알 수 없으면 알려주면 됩니다. 팀의 일하는 방식을 알려주면 그 순간 수년을 함께 한 동료가 될 수 있습니다. 애자일하게 일하는 조직일수록 일하는 방식은 날이 갈수록 개선됩니다. 저희 팀도 마찬가지로 일하는 방식과 가이드가 그 때의 상황에 따라 더 나은 방향으로 계속해서 개선되고 있습니다. 과거에는 맞았지만 지금은 다를 수 있으니까요. 미래에는 더 다를거고요.
마찬가지로, 다양한 코드 작성 Rule을 통해 Claude Code는 어떻게 코드를 작성하면 되는지 알게 될텐데, 이 Rule은 계속해서 개선되고 진화해야 합니다. 개발 팀미팅에서 클래스 네이밍하는 방식이 변경됐다면 Rule에도 업데이트 하고 Claude Code에게도 이 사실을 알려줘야 합니다. 그래서 우스갯소리로 가이드 문서(Rule)가 얼마나 자주 업데이트 되는지 보면, 코딩 에이전트를 얼마나 잘 활용하고 있는지 알 수 있습니다.
그래서 Claude Code 뿐만 아니라 코딩 에이전트에게 무언가 프롬프팅을 완료하고 나면 끝이 아니라 이제부터가 시작입니다. 코드를 원하는대로 잘 작성했다면 다음번에도 이처럼 잘 할 수 있도록 가이드 해줘야 합니다. 코딩 에이전트에게 준 피드백과 쌓여가는 Rule은 곧, 복리의 마법으로 다가올 것이라는걸 믿는게 중요하다고 생각합니다.
발표 자료 중간에 Claude Code 기본 사용법과 소소한 팁이 있는데, 이 글에 담기엔 단순 정보라서 PDF를 참고해주시면 좋겠습니다.
아무튼.. 가장 중요한 것은 꺾이지 않는 마음입니다. 코딩 에이전트에게 무언가 명령을 했는데 잘 알아듣지 못하고 엉뚱한 코드를 작성한다거나 내가 작성하는 스타일과 다르게 코드를 작성한다거나, 마음에 들지 않을때 있습니다. 이 때 우리는 ‘그냥 내가 하는게 낫겠다’ 라는 생각이 들면서 갈림길에 놓이게 됩니다.
이 때 한 숨 크게 고르시고, 어떤게 잘못되었는지 어떻게 작성해야 하는지 알려주어야 합니다. 이건 마치 일을 빠르게 처리하지 못하고 있는 신규 입사자 동료에게 답답함을 느끼는 것과 같다고 생각합니다. 수정이 필요한 부분이 있다면 직접 고치지 않고, 어떤 코드를 어떻게 작성하면 되는지 알려주어야 합니다. 잘 해냈다면 다음 번에는 어떻게 하면 되는지 피드백을 통해 가이드와 Rule을 갱신합니다.
마지막으로, 이 발표에서 전달하려고 했던 메시지 메시지입니다.
- 코딩 에이전트가 못하면 가르치자
- 코딩 에이전트가 해냈으면 회고하자
- 그리고 복리의 마법을 믿자
마치며
코딩 에이전트를 접하고 나서 정말 많은 시간을 코드 작성법(Rule)을 만드는 일에 할애했습니다. 팀에서 수십개 서비스를 모노레포에 관리중인데, 오래전부터 아키틱체와 코드 컨벤션을 잘 유지하고 가이드를 다듬어 놓아서 초기 Rule을 작성하는데에 시간은 오래 걸렸지만 어렵지 않았습니다.
지금은 Claude Code를 사용하면서 N개의 일을 병렬로 할 수 있는 환경이 되었습니다. 커밋 메시지를 작성한다던가, Pull Request 본문을 작성하는 등 코드를 작성하고 나서 반복적으로 하는 작업들은 더이상 제가 하지 않습니다. Claude Code가 일을 잘 해서 그런것도 있지만, 초기에 Rule 셋팅하는 시간을 많이 투자한 덕분이라고 생각합니다.
단순한 기능을 만들 때에는 가이드 없이 Claude Code를 바로 사용해도 좋다고 생각합니다. 하지만 조금 복잡해지거나 도메인 규칙을 이해해야 한다거나, 우리 팀만의 가이드에 따라 코드 작성이 필요하다면 바로 사용하는건 멈추고 Rule 부터 정돈하기를 권장합니다.
마지막으로, 작성된 모든 내용은 제 개인적인 의견이고 소수의 인원이 작업을 하는 곳보다 다수의 인원이 같은 Repository에 작업을 할 때에는 더 빛을 보는 방법이니 참고해주세요. 모두 복리의 마법을 믿고 코딩 대탈출 하셨으면 좋겠습니다!
- P.S. 발표 자료는 일부 내용 제거된 형태로 업로드 되어 있습니다. ClaudeCode101_20250809.pdf를 참고하시면 됩니다. 궁금하신 점이 있으면 편하게 메일로 연락 주세요.