🧑🏻💻 Ep.05 | AI에게 일 시키는 법을 코드화한다는 것
프로젝트 루트에
CLAUDE.md라는 파일이 있습니다. AI 코딩 도구를 써본 적이 없다면 조금 낯설 수 있습니다. 이 파일은 AI에게 이렇게 말하는 문서입니다.“우리 프로젝트에서는 이렇게 일해.”
사람으로 치면 온보딩 문서에 가깝습니다.
1. 왜 이런 게 필요해졌을까
AI에게 코드를 시키면 보통 이런 일이 벌어집니다.
- 변수명을
camelCase로 써야 하는데snake_case를 사용함
- 에러 처리는
try-catch규칙인데Result타입을 사용함
- 테스트는
JUnit5인데 혼자 다른 프레임워크를 가져옴
한두 번이면 고치면 됩니다. 하지만 매번 같은 지적을 반복해야 한다면, 그건 단순한 실수가 아니라 시스템의 문제입니다.
사람이라면 한 번 들은 규칙을 기억합니다. 하지만 AI는 세션이 끝나면 잊어버립니다. 다음 대화에서 다시 같은 실수를 합니다.
그래서 규칙을 파일로 남깁니다. 세션이 바뀌어도, 사람이 바뀌어도, 프로젝트의 방식은 유지되도록 말이죠.
2. 어떤 내용이 들어갈까
실제 프로젝트의 규칙 파일을 보면 보통 이런 것들이 들어 있습니다.
코딩 규칙
- 한 번만 쓰이는 코드에 추상화를 만들지 마라
- 요청받지 않은 기능을 추가하지 마라
작업 방식
- 수정할 코드를 먼저 읽어라
- 대규모 변경을 한 번에 하지 마라
프로젝트 구조
- 이 디렉토리는 이런 용도다
- 커밋 메시지는 한국어로 작성한다
금지 사항
- 존재하지 않는 API를 지어내지 마라
projects/하위 파일을 워크스페이스 repo에 커밋하지 마라
흥미로운 점이 하나 있습니다. 이 규칙 대부분이 사실 사람에게도 해당되는 이야기라는 점입니다. 예를 들어,
“요청받지 않은 기능을 추가하지 마라”
이건 시니어 개발자가 주니어에게 자주 하는 피드백이기도 합니다. 차이가 있다면 하나입니다. AI는 명시하지 않으면 절대 스스로 깨닫지 못한다는 것입니다.
3. 규칙 파일은 팀의 거울이다
CLAUDE.md를 자세히 들여다보면 그 팀이 어떤 실수를 반복했는지 보입니다. 예를 들어 이런 규칙이 있다면기존 코드의 포매팅을 건드리지 마라
아마 이런 일이 있었을 겁니다. → AI가 코드를 수정하면서 주변 코드의 포매팅까지 전부 바꿔버린 경험.
또 이런 규칙이 있다면
에러가 나면 같은 시도를 반복하지 마라
→ 실패한 명령을 계속 재시도하면서 시간을 낭비했던 경험이 있었을 가능성이 큽니다.
팀이 겪은 실패들이 규칙으로 쌓이고 그 규칙이 다음 실패를 막습니다. 마치 포스트모템을 문서화하는 것처럼요.
4. 사람과 AI의 온보딩은 닮아 있다
새로운 팀원이 합류하면 온보딩을 진행합니다. 예를 들면 이런 이야기들이죠.
- 우리 팀은 PR 리뷰를 이렇게 한다
- 배포는 이 브랜치에서 진행한다
- 이 서비스의 핵심 로직은 여기에 있다
AI에게도 같은 과정이 필요합니다. 차이가 있다면 하나입니다. AI는 매번 새 팀원처럼 들어옵니다. 그래서 온보딩 문서가 파일로 존재해야 합니다.
이 관점에서 보면
CLAUDE.md는 단순한 설정 파일이 아닙니다. 팀의 일하는 방식을 코드처럼 버전 관리한다는 의미입니다. 누가 어떤 규칙을 추가했는지, 왜 추가했는지 모든 것이 커밋 히스토리에 남습니다. 어쩌면 이것도 팀의 성장 기록일지 모릅니다.5. 규칙이 너무 많아지면
규칙 파일이 두꺼워질수록 좋은 것은 아닙니다. 200줄짜리 규칙을 넣어두면 AI가 전부 따르지 못하는 경우가 생깁니다. 서로 충돌하는 규칙이 있으면 어중간한 결과가 나오기도 합니다.
생각해보면 사람도 비슷합니다. 코딩 가이드가 100페이지짜리 PDF라면 대부분 처음 몇 장만 읽습니다. 그래서 보통 이렇게 하는 편이 좋습니다.
- 핵심 원칙 몇 개만 명확히 적기
- 실제 문제였던 것만 추가하기
- 가상의 문제로 규칙을 늘리지 않기
장황한 규칙 100개보다 명확한 원칙 5개가 더 효과적입니다.
6. 코드화한다는 것의 의미
이 이야기는 단순히 “AI 도구 설정”에 대한 이야기가 아닙니다. 팀이 일하는 방식을
- 명문화하고
- 버전 관리하고
- 계속 개선하는 것
그게 이 파일의 진짜 역할입니다.
AI 시대에 엔지니어가 관리해야 할 것이 하나 늘어난 것처럼 보일 수도 있습니다. 하지만 솔직히 말하면, 원래 해야 했지만 그동안 하지 않았던 일을 AI 덕분에 비로소 하게 된 것에 가깝습니다.
🌱 일하는 방식을 고민하는 개발자들이 모인 곳, 루퍼스
AI에게 일을 시키기 위해 팀의 규칙을 문서화하고, 일하는 방식을 버전 관리하기 시작한 시대. 결국 중요한 건 도구가 아니라 어떻게 일할 것인가를 고민하는 힘입니다. AI 시대의 엔지니어링을 함께 고민하고 싶다면 루퍼스에서 그 여정을 시작해보세요 🙌
AI 시대에도 결국 중요한 건 생각하는 힘과 성장하는 환경이라고 믿습니다. 루퍼스에는 성장에 진심인 650+명의 크루가 함께하고 있습니다. 현업에서 부딪히는 고민과 경험을 나누며 함께 성장하는 크루들의 이야기.
전액 기부 강의 그리고 다양한 오프라인 네트워킹까지! 루퍼스는 개발자를 위한 지속 가능한 성장을 만들어 갑니다.
📢 LOOPERS의 소식이 궁금하다면?
Share article