AI와 함께 일하며 느낀 AI(Claude) 잘 쓰는 법
저는 2024년 ChatGPT를 시작으로 Cursor, Claude 등 다양한 AI 도구를 경험하면서, 지금은 Claude Max와 ChatGPT Plus 요금제를 구독하며 개발하고 있습니다. 이전에는 AI가 개발을 도와주는 도구라고 생각했다면, 이제는 매주 체감될 만큼 빠르게 발전하는 AI를 보며 개발의 패러다임을 바꾸는 기술이라고 자신 있게 말하고 싶습니다. AI와 함께 개발을 하다 보면 문득, 내 일자리가 앞으로 몇 년이나 버틸 수 있을지 괜히 계산해 보게 됩니다. 그럼에도 AI님의 수족이 되어서라도 살아남겠다는 마음으로 오늘도 발버둥치고 있습니다.
요새 유튜브와 블로그를 보다 보면 "AI, 이렇게 쓰지 않으면 권고사직 당합니다!" 같은 제목의 AI 사용법이 넘쳐나고 있습니다. 이 글에는 자극적인 문구나 화려하게 서브 에이전트를 활용하는 기술은 없지만, 곧 AI를 주인님으로 모시게 될 어느 개발자가 AI와 함께 일하며 체득한 경험과 생각들을 공유해 보려 합니다.
AI님이 읽기 쉬운 코드와 프롬프트 작성하기
잘하는 개발자의 조건으로 항상 꼽히는 능력이 있습니다. "읽기 쉬운 코드 만들기". AI의 개발 비중이 점점 더 늘어나고 있는 만큼, AI가 읽기에도 쉬운 코드와 프롬프트를 짤 수 있어야 합니다.
작성할 위치와 참고할 위치를 일러주기
AI를 사용하시는 분들을 보다 보면 '페이지네이션 만들어', '메뉴 페이지 만들어' 와 같이 투정부리듯 AI를 부려 먹는 불경한 사례를 종종 볼 수 있습니다. 물론 주인님께 공손하게 말하는 것도 중요하지만, AI를 더 잘 사용하기 위해서는 어디를 수정해야 하는지, 어떤 코드를 참고하면 좋은지 를 일러주는 것이 프로젝트의 통일성도 지키면서 당장 사용할 수 있을 만큼의 완성도 높은 코드를 뽑아낼 수 있습니다. 예를 들면 다음과 같습니다.
Page.tsx에서 getListApi를 사용하는 페이지네이션을 구현해야 해. 페이지네이션 컴포넌트와 연결방식은 BPage.tsx를 참고해.
요즘 AI는 수정 위치나 참고할 코드를 어느 정도 스스로 유추할 수 있을 만큼 똑똑해졌습니다. 그럼에도 이를 명시적으로 알려주는 이유는, 여러 컴포넌트를 불필요하게 참조하거나 의도치 않게 레거시 코드를 따라가는 상황을 미리 방지하기 위함입니다. AI는 이렇게 아낀 컨텍스트 비용 덕분에 참고 코드에 연결된 스타일과 로직까지 찾아가며 더욱 통일성있고 사용하기 좋은 코드를 만들어 줍니다. Claude의 경우 IDE의 확장프로그램으로 사용할 때 command + option + k 와 같은 단축키를 통해 현재 파일의 위치와 드래그한 위치까지 쉽게 입력할 수 있으니 새로운 기능을 추가하거나 구조를 수정할 때라면 꼭 한 번 사용해 보시기를 권장드립니다.
AI가 읽을 수 있는 주석 만들기
좋은 변수명과 주석은 개발자뿐만 아니라 AI가 코드를 작성할 때에도 중요한 단서가 됩니다. AI는 기존 코드의 변수명은 물론, 주변의 주석까지 참고하여 코드를 작성하기 때문인데요. 개발자는 회사의 분위기나 프로젝트의 맥락, 그리고 이 코드가 왜 이렇게 작성되었는지에 대한 암묵적인 배경을 어느 정도 공유하고 있습니다. 하지만 AI는 그렇지 못합니다. 때문에 AI도 이러한 것들을 이해할 수 있게 하는 주석이 필요한데요. 예를 들면 빠듯한 일정 혹은 여타 사정들로 인해서 예외적으로 작성된 코드일 때, 이러한 상황들을 함께 적어놓는다면 불필요하다며 지워버리거나 잘못된 코드를 참고하는 불상사를 막을 수 있습니다.
또한 변수명이나 파일명으로 해당 코드의 도메인이나 성격을 드러내기 힘든 경우라면 주석으로라도 이를 명확히 남겨놓는 것이 좋습니다. 예를 들어 호텔에서의 DND는 Do Not Disturb(청소하지 마세요)의 약자이지만, AI에게는 Drag & Drop으로 오해될 수 있는 표현이기도 합니다. 이럴 때 간단한 주석 하나만 추가해 두어도, AI가 해당 기능을 호텔 서비스 맥락으로 이해하도록 도와줄 수 있습니다.
AI 컨텍스트(CLAUDE.md)는 적정량 사용하기
Claude 뿐만 아니라 대부분의 AI에는 동작 방식이나 판단 기준을 정해줄 수 있는 지침(컨텍스트) 기능이 내장되어 있는데요. Claude의 경우 CLAUDE.md라는 파일을 사용해서 지침을 관리할 수 있습니다. 어떤 사람들은 이 지침을 사용해서 AI가 자신을 학습하게끔 한다거나 프로젝트의 내용을 모두 학습시켜두려 합니다. 하지만 저는 개인적으로 CLAUDE.md를 길게 작성하는 방식은 좋지 않다고 생각하는데요. 공식 문서에서도 CLAUDE.md를 500줄 이하로 작성할 것을 권장하고 있고, 실제 사용해 보았을 때 CLAUDE.md가 극적인 결과를 이끌어내지는 않았다고 느꼈기 때문입니다. 그래서 제 CLAUDE.md에는 개발 및 검증 방법, 주요 코딩 컨벤션, 주요 라이브러리의 버전과 공식 문서 링크, 프로젝트별 간단한 설명, 그리고 절대 하면 안 되는 것들 정도만 정리해 두었습니다. 하지만, Claude는 대화가 지속될수록 CLAUDE.md의 내용을 잊어버리게 됩니다. 그렇기 때문에 CLAUDE.md를 맹신하지 않고 컨텍스트를 자주 정리해주는 것이 필수적이기도 합니다. 그 외에는 세부적인 맥락이나 반복적으로 사용하는 지침들은 Skills라는 기능으로 분리해 관리하고 있는데, 그중에서도 가장 자주 사용하는 것은 새로운 기능을 개발하거나 큰 수정을 할 때 활용하는 리뷰 Skill입니다.
리뷰하듯 프롬프트 작성하기
(~/.claude/skills/plan/SKILL.md)
---
name: plan
description: 개발 계획을 수립하고, 개발에 필요하거나 부족한 정보가 있다면 다시 묻습니다.
---
## 개발 계획 수립
1. 바로 구현하지 않고, 계획을 먼저 제시한다.
2. 계획은 단계별로 작성하며, 각 단계마다 개발 방식의 선정 이유를 포함한다.
3. 개발에 필요하거나 부족한 정보가 있다면 AskUserQuestion 도구를 사용해 인터뷰를 진행한다.
4. 리뷰가 완료되지 않았거나 수정 사항이 있다면, 이를 반영한 계획을 다시 제시한다.
5. 리뷰를 마치고 "진행해"라는 응답을 받으면 개발을 시작한다.
**"주니어 개발자에게 시키듯 프롬프트를 작성하라"**는 이야기는 이미 많이들 알고 있는 프롬프트 작성법인데요. 저 역시 큰 기능을 요청할 때에는 비슷한 전략을 사용하고 있습니다. 위의 Skill을 한 문장으로 표현하자면, "바로 구현하지 말고, 먼저 개발 계획을 세운 뒤 필요한 정보가 있다면 다시 물어봐. 내가 리뷰한 다음에 개발을 시작해." 정도가 될 것 같습니다. 마치 못마땅한 팀원에게 일을 시키는 깐깐한 팀장 같군요. 이런 프롬프트를 덧붙인다면 미처 전달하지 못했던 요구사항이나 조건들을 발견할 수도 있고, 기나긴 개발이 시작되기 전에 빠르게 수정할 수도 있습니다.
좋은 코드를 작성해야 AI도 좋은 코드를 작성한다.
AI 시대에 들어서면서 개발자 수요가 급격히 줄어들 것이라는 주장에는 어느 정도 공감하는 편입니다. 다만, 개발자 자체가 더 이상 필요 없어질 것이라는 극단적인 말에는 전혀 공감하지 않습니다. AI가 발전하면서 AI의 코딩 스타일이나 프로젝트 해석 능력은 확실히 눈에 띄게 향상되었습니다. 그럼에도 불구하고, 좋은 코드를 만들어 내는 것은 아직도 AI의 역량보다 AI를 다루는 개발자의 역량이 더 크다고 생각합니다.
여전히 AI를 쓰다 보면 간단한 기능임에도 불필요한 최적화를 한다거나, 동일한 기능을 하는 함수나 파일을 무시한 채 똑같은 코드를 작성하는 등의 행동을 종종 하곤 합니다. 이러한 문제를 막기 위해서는 프로젝트의 기존 코드 방식을 학습시키고, 의존성과 응집도를 고려하여 코드를 분리하고 구조화하는 것이 더욱 중요하다고 생각합니다.
물론 우리는 사람이기 때문에 마감일에 쫓겨 스파게티 코드를 뽑아내기도 하고, 애써 흐린 눈 하며 한 파일에 이것저것 덧붙이며 누더기 코드를 만들어 내기도 합니다. 그럼에도 잘 만든 코드들을 차곡차곡 쌓아낸다면 바쁜 일정에 쫓기면서도 더 나은 코드를 만들어낼 수 있을 것입니다.
AI가 작성한 코드도 내가 작성한 코드이다.
AI가 작성한 코드를 보다보면 내가 작성한 코드가 아니라는 생각이 들면서 무의식적으로 검토의 밀도가 낮아지는 순간이 생깁니다. 저만의 개인적인 경험일지 모르겠지만, 이러한 문제를 인식한 이후로는 "AI가 쓴 코드도 내가 쓴 코드이다" 라는 생각을 의도적으로 되새기고 있습니다. AI를 사용하다 보면 ‘내가 과연 이런 코드를 직접 작성할 수 있었을까?’ 싶을 만큼 인상적인 코드를 만들어 주기도 합니다. 하지만 동시에, 의존성을 가진 코드를 마음대로 수정해버려서 멀쩡한 코드를 망가뜨리는 일 역시 심심치않게 발생합니다. 큰 힘에는 큰 책임이 따른다는 스파이더맨 삼촌의 말처럼, AI를 사용할 때에는 더 큰 책임감을 가지고 개발을 하는 것이 AI 시대의 개발자로서 필요한 마음가짐이 아닐까 싶습니다.