# [클로드 코드 밋업] 레거시 코드베이스에서 에이전트와 사람을 함께 일잘러로 만드는 환경 구축하기

> Clean Markdown view of GeekNews topic #25174. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=25174](https://news.hada.io/topic?id=25174)
- GeekNews Markdown: [https://news.hada.io/topic/25174.md](https://news.hada.io/topic/25174.md)
- Type: news
- Author: [spilist2](https://news.hada.io/@spilist2)
- Published: 2025-12-19T09:02:50+09:00
- Updated: 2025-12-19T09:02:50+09:00
- Original source: [stdy.blog](https://www.stdy.blog/designing-better-env-for-human-and-agents-in-legacy-codebase/)
- Points: 32
- Comments: 3

## Summary

레거시 코드베이스에서도 **AI 에이전트와 사람이 함께 성장하는 개발 환경**을 만드는 것이 코르카 AX 팀의 핵심 목표입니다. 문라이트 팀과의 협업을 통해 ‘좋은 경로로 가게 하고, 잘못된 경로로 못 가게 하는’ 코드 품질 관리 체계를 구축하며, 매일의 작은 리팩토링과 정적 분석 도구 활용으로 품질 지표를 눈에 띄게 개선했습니다. 이러한 접근은 외부의 일회성 지원이 아니라, 팀 내부에서 스스로 **에이전틱 엔지니어링 실천법**을 발견하고 확산시키는 지속 가능한 방식으로 자리 잡고 있습니다.

## Topic Body

(12월 17일에 서울 클로드 코드 밋업에서 발표한 자료입니다. 전체 발표자료는 이 [링크](https://www.linkedin.com/posts/xavierchoi_%EC%96%B4%EC%A0%9C-%EB%91%90-%EB%B2%88%EC%A7%B8-claude-code-meetup-seoul%EC%9D%84-activity-7407185329989804032-5kwm)를 참고하세요.)  
  
---  
  
### 코르카 AX 팀의 '내부 컨설팅' 목표  
- 코르카에 좋은 에이전틱 엔지니어링 실천법을 정착시키고, 함께 꾸준히 발전시킬 수 있는 토양을 만든다.  
  - 코르카에서는 '에이전틱 엔지니어링 실천법'을 '소프트웨어의 품질과 생산성을 모두 높이는 방향으로 AI 에이전트를 활용하기 위한 실천 방법들'로 정의  
- 엔지니어링 역량이 코르카의 또다른 핵심 경쟁력이 되도록 한다.  
- 이를 위해 문라이트 팀을 돕는 일을 시작함  
  
### [문라이트]((https://www.themoonlight.io/ko))의 상황  
- 코르카의 대표 제품인 문라이트, '함께 논문을 읽는 AI 동료'를 표방  
- 'PDF랑 대화하기'는 ChatGPT 극초창기부터 존재했던 아이템. 그러한 수많은 경쟁 제품들 중 살아남아서 요즘은 J 커브의 초창기에 있음 (최근 중국 가입자 폭증세)  
- 이렇게 되기까지 수많은 시행착오가 있었지만 핵심 경쟁력은 기능 개발 속도와 리듬을 '어떻게든' 유지하는 것  
- 속도를 위한 몇 가지 초기 의사결정  
  - typescript strict: false  
  - 자동화 테스트 최소화  
  - 중복과 하드코딩 허용  
  - 직군 구분 없음. 거의 모든 팀 구성원(7명 중 6명)이 코딩 에이전트로 구현하고 PR 올림  
- 궤도에 오르고 나니 부채로 인해 조금씩 힘들어짐  
  - 제품이 복잡해지고, 팀의 신규 구성원이 많아지고, 동시에 돌아가는 실험이 많아짐  
  - 제품 개선 속도가 조금씩 느려지고, 불안함은 조금씩 커짐  
  - 몇 명에게 코드리뷰 부담이 쏠리고 크고작은 실수가 생김  
  
### AX 팀에게 당면한 과제  
- [제품] 문라이트 제품의 품질이 향상되면서도 기능 추가 및 개선 속도는 빨라지게 하자!  
- [팀] 누구나 문라이트 코드를 더 고치기 쉬워지고, 배포 후의 스트레스는 더 적어지게 하자!  
- [문화] 1과 2를 위해, 문라이트 팀과 AX 팀이 협업하여 좋은 에이전틱 엔지니어링 실천법을 발견하고, 적용하고, 고도화하며, 점진적으로 사내에 전파하자!  
→ 코딩 에이전트가 더 좋은 응답을 줄 수 있게 되면 대부분 해결된다고 봤음  
  
### 에이전트가 더 좋은 응답을 주려면?  
  
**[1] 처음부터 좋은 경로로 가게 한다**  
- 코드베이스의 품질이 높으면 3가지 측면에서 유리해짐  
- 불필요한 컨텍스트를 덜 넣게 됨 (Less is More)  
- 에이전트가 기존의 좋은 패턴을 따라하게 됨  
- 사전학습된 코드 중 고품질 코드가 모여 있는 공간에서 샘플링된 응답이 나올 확률이 높아지도록 편향시킬 수 있음  
  - 고품질 컨텍스트를 넣으면 좋은 응답이 나온다는 연구는 많음.  
  - (뇌피셜) import 순서가 정렬된 코드베이스에서 에이전트에게 요청을 보내면? 사전학습된 코드 중 import 순서를 정렬해둔 코드는 전반적으로 고품질일 가능성이 높지 않을까?  
  - [앤트로픽 블로그](https://www.claude.com/blog/improving-frontend-design-through-skills) 중: "흥미로운 폰트를 쓰게 하는 것만으로도 다른 디자인 요소들이 개선됨"  
  
**[2] 잘못된 경로로 못 가게 한다**  
- 타입 오류 확인, 린터 오류 확인, 자동화 테스트, 죽은 코드 검사, 파일 길이 검사, 복잡도 검사, 의존관계 강제, 테스트 코드 vs 프로덕션 코드 비율 강제 등 다양한 정적 분석 도구로 잘못된 경로를 차단시킬 수 있음 (기준을 통과할 때까지 다시 일하게 함)  
  
**[3] 잘 하는 일 위주로 요청한다**  
- 사람이 잘 하는 것, LLM이 잘 하는 것, 알고리즘이 잘 하는 것이 다름. 언제 무엇을 쓸지 현명하게 선택하면 시간과 비용을 아낄 수 있음  
  - ex) i18n key 빼먹지 말라고 하기 vs [빼먹은 i18n key 찾는 스크립트 돌려보라고 하기](https://www.stdy.blog/adding-i18n-robustness-to-legacy-projects-with-ai/)  
- 누가 언제 뭘 잘하는지는 시간이 지남에 따라, 문제의 도메인이 무엇인지에 따라 달라짐. 본인 도메인에서 이 '감'을 최신화하는 습관을 심어두면 유리함  
  - ex) 새 모델 나오면 [자신만의 벤치마크](https://simonwillison.net/2024/Oct/25/pelicans-on-a-bicycle/)로 테스트해보기, 유명한 소셜 미디어 예제 따라하기  
  
**[4] 못 하는 일은 도와준다**  
- 단, 정말 못 하는 게 맞는지는 항상 확인 필요. 위임하기에 위험하거나, 지나치게 비효율적이거나… 등이 아니라면 사람보다는 AI/알고리즘이 많이 하는 게 좋음. (토큰 비용은 어차피 전기료 수준으로 싸질 것이므로)  
- 정말 못한다면? [다른 LLM에게 검토](https://github.com/karpathy/llm-council)시키기  
  - ex) 가장 간단하게는, "이거 초보 개발자가 짠 건데…"  
- AI가 일을 더 잘 하게 하려면, AI가 일을 더 잘 할 수 있는 환경을 제공해야 함. 달리 말하면 (현재의) 에이전트가 (여기서) 잘 못할 만한 것을 사람과 알고리즘과 다른 에이전트가 보강해줘야 함  
  
### 주의했던 것들  
- 문라이트는 이제 날기 시작한 로켓, AX 팀은 밖에서 찾아온 손님  
- 외부자가 와서 뭔가 짠 '해주고' 돌아가는 그림은 절대 지양  
- 품질 향상 노력이 기능 개발의 발목을 (되도록) 잡지 않게  
- 평소 일하던 방식을 크게 바꾸지 않는 종류의 일과 도전적이지만 효과적인 종류의 일을 적당한 비율로 섞기로 함  
→ AX 팀과 문라이트 팀이 '함께' 팀과 제품에 맞는 실천법을 발견해서 적용하고, 그 과정에서 코드와 제품의 품질 및 팀 역량 향상이 함께 일어나는 그림을 상상  
  
### 지난 4주간 얻은 대표적 성과들  
  
**[1] 좋은 습관들이 정착되고, 좋은 패턴들이 발견되고 있음**  
- 매일 PR 리뷰 없이 초소형 리팩토링(tidying) 커밋 올리기  
- 과거 모범적 커밋을 (신규 모델 지원 등) 따라하는 프롬프트, 그런 패턴을 발견해서 모으는 프롬프트  
- 시니어로 빙의한 코드리뷰 SKILL  
  
**[2] 코드 품질 지표를 측정 및 가시화 시작. 코드 라인 수 대비 오류/경고 수가   
빠르게 줄어들고 있음**  
- 코드 품질 지표들이 때로는 점진적으로, 때로는 드라마틱하게 줄어들고 있음  
- tidying이 매일같이 코드베이스를 조금씩 개선함으로써 어느 순간 큰 리팩토링과 큰 작업을 해볼 수 있겠다는 엄두를 내게 된 게 큼  
- [knip](https://github.com/webpro-nl/knip)을 한 패키지씩 적용하면서 오래되고 안 쓰이는 코드들도 삭제  
- 지표는 언제나 상보적이어야 함. 1000줄짜리 코드에서 오류가 1000개 나는 것보다, 10만줄짜리 코드에서 5000개 나는 게 훨씬 나음. 그러니 단순 갯수만 보는 게 아니라 라인 수 대비 오류 비율을 봄으로써 좀 더 건강한 관리 지표를 설정  
  - 코멘트와 공백을 제외한 유의미한 라인 수는 [tokei](https://github.com/XAMPPRocky/tokei)로 측정  
  
**[3] 1년 넘게 지속되던 메모리 누수 문제 고침**  
- [repomix](https://repomix.com/)를 비롯한 여러 도구와 프롬프팅을 총동원해서, 몇차례 시도 끝에 1년 넘게 지속됐던 메모리 누수 문제를 잡음  
- 서버 인스턴스 티어를 낮춰도 될 것 같아서 기뻐하는 중  
  
**[4] 매주 몇 개씩 동시에 돌아가는 실험들을 더 쉽고 안전하게 추가/삭제 가능한 추상화 구조, 프롬프트, 스크립트가 생김**  
  
결과적으로, 코드 품질은 점점 더 높아지고, 기능 개발은 더 안전하면서도 더 빨라지고, 팀의 (에이전틱) 엔지니어링 역량은 꾸준히 높아지는 3박자가 잘 맞아떨이지고 있음  
  
### 시행착오  
- 당연히 처음부터 잘 되진 않았음. 원래는 두 가지를 동시에 하고 싶었음  
  - 좀 불안하더라도 가치가 큰 변화를 한번에 도입: strict 옵션 켜기, 빡센 eslint 룰 도입, 죽은 코드를 한번에 다 지우기 등  
  - 가치가 적더라도 안전하게 한 발짝씩 가기: 매일 tyding 커밋 남기기 등  
- 그런데 전자는 불안해서 '못' 하고, 후자는 재미없어서 '안' 하게 됨  
- 대신 이렇게 바꿈  
  - 도전적인 걸 더 안전하게 (한 파일씩 tsc strict 켜서 고치고 끄기, 최소한의 룰로 eslint 적용, 한 패키지에 하나씩 knip 등)  
  - 안전한 걸 더 가치있게 (최근 변경사항에 대해 tidying 제안받는 프롬프트 만들기 등)  
- 아직도 많은 과제가 남았지만  
  - typescript: strict 켜기  
  - zod 도입해서 서버-클라 규약 맞추기  
  - 더 빡센 eslint rule 도입  
  - 더 높은 자동화 테스트 커버리지  
  - 더 다양한 정적 검사 도구로 잘못된 경로 틀어막기  
- 함께, 꾸준히, 결코 느리지 않게 나아가고 있음  
  
### One More Thing: 나의 학습 + 디버깅 습관  
  
이런 상황에서 AI에게 묻고, 고수에게 물어보며 교차검증하면 배우는 게 많음. 이 과정도 깃헙 PR과 이슈, 슬랙에 남겨 조직에 공유하고 있음  
  
- 내가 모르는 걸 다른 사람이 앎  
  - 이 지식/경험을 이 사람은 어떻게 알았을까? 어떤 신호로 이 문제를 파악했을까?  
- 나의 실수나 버그, 코드베이스의 안티패턴 등을 발견  
  - 이 문제가 생길 수밖에 없었던 원인이 무엇무엇이었을까? 다음에 실수 덜 하고, 실수를 더 일찍 발견하려면 어떻게 구조 개선을 하면 될까?  
  
### 마무리  
- AI가 더 좋은 응답을 줄 수 있게 하면 제품 팀의 문제 중 상당수가 풀린다  
  - 코드베이스 품질을 높이고 (처음부터 좋은 경로로), 다양한 도구를 도입하고 (잘못된 경로 차단)  
  - 구성원의 에이전틱 엔지니어링 역량이 높아지도록 돕자 (잘 하는 일은 요청, 못 하는 일은 돕기)  
- AI와 현명하게 협력함으로써 팀의 역량이 높아지고, 좋은 환경이 갖춰진다면 '품질 향상'과 '기능 추가/개선 속도 향상'은 동시에 얼마든지 가능하다  
- '밖에서' 좋은 걸 들고와서 도와주는 게 아니라, '안에서' 함께 발견하고 시도하자. 측정하고, 가시화하고, 축하하고, 서로 배우자

## Comments



### Comment 48002

- Author: kunggom
- Created: 2025-12-19T14:30:33+09:00
- Points: 1

밋업 기사도 나왔네요.  
  
[르포] "한국서 클로드 1위 유저 탄생"…앤트로픽 밋업 행사 가보니  
https://n.news.naver.com/mnews/article/092/0002402940  
  
> 이날 전 세계에서 클로드 코드를 가장 많이 활용한 사이오닉AI 박진형 엔지니어도 참석해 에이전트 활용 노하우를 공유했다.  
> 앞서 앤트로픽은 박 엔지니어를 글로벌 해비 유저 1위라고 밝혔다. 그는 현재 클로드 코드를 포함해 여러 AI 도구를 업무에 활용하고 있다. 매달 AI 구독료로 약 180만원을 지출하고 있다.  
  
1달에 약 180만원 ㄷㄷㄷㄷ

### Comment 47996

- Author: ds2ilz
- Created: 2025-12-19T11:58:16+09:00
- Points: 1

주니어 개발자의 적극 참여와 성장을 도울 수 있는 방법으로도 의미가 있을 것 같네요

### Comment 47998

- Author: spilist2
- Created: 2025-12-19T12:40:05+09:00
- Points: 1
- Parent comment: 47996
- Depth: 1

오 맞습니다 ㅎㅎ 그쪽으로도 열심히 하고 있습니다