신규 개발자처럼 Claude Code 온보딩하기: 17년 개발 경험에서 얻은 교훈

Skyline은 워싱턴 대학교 MacCoss Lab의 수석 개발자 Brendan MacLean이 관리하는 오픈 소스 단백질 분석 소프트웨어로, 2008년부터 꾸준히 개발되어 왔습니다. Skyline은 혈장이나 조직 같은 시료에서 단백질을 검출하고 정량화하는 데 활용되며, 바이오마커 발견과 질병 연구, 신약 개발에 핵심적인 역할을 합니다. MacCoss Lab의 코드베이스는 C# 코드 70만 줄 이상으로 구성되어 있으며, 소규모 팀이 17년간 유지보수하면서 매일 밤 20만 건 이상의 자동화 테스트를 실행하고 있습니다.

거의 30년에 걸쳐 Brendan은 Skyline을 하나로 묶는 구심점 역할을 해왔습니다. 수십 명의 학부생과 대학원생, 포스닥 연구원을 연구실에 온보딩해 온 산 증인이기도 합니다.*

개발자들이 들어오고 나가는 과정에서 코드베이스는 그들의 기여를 고스란히 흡수했습니다. 2024년에 이르자 오랜 프로젝트에서 흔히 나타나는 부담이 쌓였고, 개발자가 교체되면서 손대기 어려운 영역도 생겨났습니다.

수십 년간 연구실 구성원들을 훈련시켜 온 Brendan은 방대한 코드베이스에 연구자를 빠르게 적응시키는 방법을 잘 알고 있었습니다. 그런데 그 방법론을 AI 도구에 그대로 적용했더니 손쓰기 힘들었던 코드베이스가 다시 관리 가능한 상태로 돌아왔습니다. 그것은 전혀 예상치 못한 결과였습니다.

같은 온보딩 문제, 다른 종류의 개발자

Brendan은 최신 AI 코딩 도구가 해당 언어와 환경에 특화된 기존 도구만큼 C# 코드를 제대로 이해할 수 있을지 회의적이었습니다.

브라우저에서 Claude.ai로 진행한 초기 실험은 그 우려를 확인해 줬습니다. 문제를 설명하고 응답을 받은 뒤, 프로젝트 코드를 전혀 참조하지 않고도 설명할 수 있는 독립적인 문제에만 범위를 한정해 C# 파일 전체를 프로젝트에 다시 붙여넣는 방식이었습니다.

"변경 사항이 점점 세밀해질수록 작업이 매우 번거로워졌습니다." Brendan의 말입니다.

Claude.ai와의 매 세션은 처음부터 다시 시작하는 것과 같았습니다. Skyline이 무엇인지, 각 컴포넌트가 어떻게 연결되는지, 17년간의 개발 과정에서 무엇이 확립되었는지—Claude는 아무것도 알지 못했습니다.

이는 신규 개발자를 온보딩할 때 Brendan이 겪던 문제와 똑같았고, 거기서 아이디어가 떠올랐습니다.

"Claude Code를 통해 Claude를 제 대형 프로젝트에 소개하는 방식을 신입 개발자를 교육할 때와 동일하게 가져가기로 했습니다. 제한된 프로젝트를 성공적으로 완수할 만큼만 설명하고, 그 과정에서 다음 반복을 위한 개선된 컨텍스트를 쌓아가는 방식이죠." Brendan의 설명입니다.

그는 모든 AI 컨텍스트를 코드베이스와 분리된 별도 저장소 pwiz-ai로 옮겼습니다. 모든 브랜치와 시점에 걸쳐 적용할 수 있도록 분리한 것입니다. 루트의 CLAUDE.md 파일은 환경 설정을 담당하고 Claude를 관련 문서로 안내합니다. 전문 지식 자체가 아니라 '전체 구조 파악'을 위한 안내서라고 보면 됩니다.

전문 지식은 스킬(skills)에 담겨 있습니다. 에이전트에 역량과 전문성을 부여하기 위한 개방형 포맷입니다. 예를 들어 debugging 스킬은 Claude가 이른바 "추측과 테스트" 모드에 빠지지 않도록, 수정을 시도하기 전에 근본 원인 분석을 먼저 수행하도록 유도하기 위해 설계되었습니다. 스킬은 수동 또는 자동으로 트리거할 수 있으며, Brendan은 가장 중요한 스킬에 명시적인 조건을 설정해 세밀하게 조정합니다. debugging 스킬의 설명은 이렇게 적혀 있습니다. "버그, 장애, 예상치 못한 동작을 조사할 때 항상 로드할 것."

컨텍스트가 갖춰지면, Claude에게 코드베이스 디버깅 방법을 가르치는 데 드는 부담이 크게 줄어듭니다. Claude는 이미 코드가 무엇을 하는지 알고 있습니다. 상호작용이 제로베이스가 아니라 이해를 바탕으로 시작되는 것입니다.

"'Claude가 내 대형 프로젝트를 진정으로 학습할 수 없다'는 우려가 큰 걸림돌처럼 느껴졌지만, 갈수록 명확해지는 사실이 있습니다. 컨텍스트는 다른 프로젝트 산출물과 마찬가지로 유지하고 키워나가야 할 대상일 뿐입니다." Brendan의 말입니다.

기술 부채 해소와 개발 속도 향상

Skyline에 Files View 패널을 추가하는 프로젝트—문서 관련 파일 전체를 보여주는 새로운 인터페이스로, 파일 시스템 모니터링과 드래그 앤 드롭 구성 기능을 포함—는 담당 개발자가 팀을 떠나면서 1년이 지나도록 미완성 상태로 남아 있었습니다. Brendan이 Claude Code와 함께 이를 이어받았습니다.

2주 후 작업이 완료되었고, 최종 커밋 전체에 Claude가 공동 작성자로 이름을 올렸습니다.

"그런 상태로 남겨진 기존 작업들은 대개 폐기로 끝났습니다." Brendan의 말입니다. 학술 연구실에서는 개발자 교체가 잦습니다. 대학원생은 학위를 마치고 떠나고, 포스닥은 다음 자리로 이동하며, 인턴은 여름이 끝나면 돌아갑니다. 과거였다면 진행 중인 작업은 그대로 선반 위에 방치되었을 것입니다.

3년 전, Brendan은 담당 개발자를 잃은 후 Skyline의 야간 테스트 관리 모듈에 기능 추가를 중단했습니다. 해당 모듈은 과학 데이터 웹 포털인 LabKey Server의 일부로 Java로 작성되어 있었습니다. 최근 숙련된 LabKey 개발자가 Claude Code로 설정 문서를 작성한 덕분에, Brendan은 하루도 채 걸리지 않아 수년간 원하던 기능을 추가하고, 과거에는 디자이너에게만 맡겼던 CSS로 페이지 레이아웃까지 개선할 수 있었습니다.

새로운 인프라도 뒤따랐습니다.

Skyline의 2,000장이 넘는 튜토리얼 이미지 스크린샷 재현 작업이 이제 완전히 자동화되었으며 재현율은 거의 100%에 달합니다. Claude Code를 활용해 변경된 부분만 표시하는 diff 뷰와 픽셀 변화 강조 기능도 추가했습니다. 또한 Claude가 이 diff를 직접 "볼" 수 있도록 C#으로 MCP 서버를 작성했습니다. Claude Code는 매일 아침 테스트 실패, 예외 사항, Skyline 야간 테스트 인프라에서 수집한 미해결 지원 스레드를 담은 일일 요약 보고서를 생성해, Brendan이 업무를 시작하기 전에 받아볼 수 있도록 메일함에 전달합니다.

또한 Claude는 이 기능을 구현하기 위해 Python으로 MCP 서버를 작성했습니다. LabKey Server의 세 가지 관계형 데이터 스트림, 팀 이메일, GitHub의 릴리스 태그가 달린 코드 등 세 가지 데이터 소스를 통합해 활용합니다.

Brendan의 개발자들은 이제 코드를 직접 작성하는 일이 크게 줄었습니다. 대신 Claude Code에 지시를 내리고, 자동화 스크립트와 MCP 구현을 자율적으로 생성하는 데 이 도구를 활용합니다. 실제로 에이전트 코딩 도구에 회의적이었던 연구실 개발자 한 명이 이온 이동도 데이터를 시각화하는 모빌로그램 창(mobilogram pane)이라는 새 플로팅 확장 기능을 직접 개발해 출시했고, Claude Code 덕분이라고 했습니다.

"다들 그동안 업무에 치여 엄두를 못 냈던 재미있는 신기능에 도전하는 모습을 보고 있습니다." Brendan의 말입니다.

레거시 코드베이스를 다루는 개발자를 위한 조언

17년간 개발자를 온보딩하고, 동일한 방법론을 Claude Code에 1년 이상 적용해 온 경험을 바탕으로, Brendan이 레거시 코드베이스를 다루는 개발자들에게 전하는 이야기입니다.

컨텍스트가 최고의 무기입니다

Claude가 생성하는 할 일 목록과 계획은 세션이 끝나면 사라집니다. 세션을 넘어 유지되는 것은 컨텍스트뿐이며, 이를 의도적으로 관리해야 합니다. 대부분의 개발자가 이 단계를 건너뛰는데, 그것이 바로 성과가 일정 수준에서 정체되는 이유입니다.

"Claude는 '컨텍스트'를 기록해야만 학습할 수 있다는 점을 이해하세요. 마법을 기대하지 마세요." Brendan의 말입니다. "컨텍스트 레이어를 구축하고 유지하는 데 투자하세요. 그리고 다른 프로젝트 산출물과 동일하게 버전 관리하고, 확장하고, 유지보수하세요."

Brendan이 AI 컨텍스트를 별도 저장소에 보관하는 이유는 코드보다 다른 속도로 성장하고, 모든 브랜치와 시점에 적용되기 때문입니다. 코드 저장소 안에 두었을 때는 점점 제약이 생겼습니다. 같은 저장소에 컨텍스트를 두는 것도 충분히 유효한 방법이지만, 중요한 것은 버전 관리가 이루어지고, 꾸준히 유지되며, 필요할 때 언제든 접근할 수 있어야 한다는 점입니다.

스킬 라이브러리 구축에 투자하세요

스킬을 활용해 어떤 Claude 인스턴스든 로드할 수 있는 도메인 지식을 담아두세요. Brendan의 스킬은 "복제가 아닌 참조" 원칙을 따릅니다. 각 스킬은 내용을 직접 담는 대신 중앙 문서 지식베이스를 가리키는 방식으로, 스킬을 가볍고 유지보수하기 쉽게 만들어 줍니다.

그가 가장 많이 사용하는 스킬은 다음과 같습니다. 프로젝트 전반과 관련 문서를 Claude에게 안내하는 skyline-development 스킬, 프로젝트 고유의 커밋 및 PR 관행을 담은 version-control 스킬, 그리고 Claude가 "추측과 테스트" 모드에 빠지지 않고 수정 시도 전에 근본 원인 분석을 먼저 수행하도록 유도하는 debugging 스킬입니다.

데이터 접근이 핵심이라면 MCP 통합을 활용하세요

테스트 결과, 예외 보고서, 지원 스레드 등 Claude가 실제 데이터에 접근해야 하는 경우 MCP 통합을 구축하세요.

오픈 소스 프로젝트에서 컨텍스트 레이어를 구축하고 유지하는 일은 특히 중요합니다. 온보딩 예산도 없고, 문서로 남기지 않으면 조직 기억도 남지 않으며, 어떤 기여자가 내년에도 함께할지 보장이 없기 때문입니다. 한번 구축된 컨텍스트는 모든 기여자가 활용할 수 있고, 사람의 암묵지와 달리 프로젝트 전체 수명에 걸쳐 유지됩니다. pwiz-ai 저장소 자체가 오픈 소스 산출물입니다. 특정 기여자가 아닌 프로젝트에 귀속되는 컨텍스트이며, 그것을 만든 모든 사람보다 오래 살아남습니다.

17년의 온보딩, 하나의 결론

신입 직원에게 70만 줄짜리 코드베이스를 건네주고 첫날부터 성과를 기대하지는 않을 것입니다. 한정된 프로젝트를 먼저 맡기고, 함께 살펴보면서, 이해가 깊어질수록 점차 범위를 넓혀가는 것이 맞습니다.

Brendan이 깨달은 것처럼, Claude와 함께 쌓아가는 컨텍스트도 정확히 같은 방식으로 작동합니다.

코드베이스를 충분히 이해한 엔지니어는 브랜치와 시점을 넘나들며 자유롭게 작업할 수 있습니다. 충분한 컨텍스트와 방향이 주어진 Claude도 마찬가지입니다.

*Anthropic 공동 창업자 Dario Amodei는 과거 MacCoss Lab 소속이었습니다.