AI와 3개월 동안 키운 대규모 Kotlin 라이브러리 생태계

대규모 라이브러리 작업에서 AI는 단순 코드 생성기보다 연구, 자동화, 리뷰, 문서화, 반복 작업을 이어 주는 협업 도구에 가까웠습니다.

2026-05-18 · bluetape4k engineering note

지난 3개월 동안 bluetape4k 생태계를 크게 확장하며 Claude Code와 Codex를 거의 매일 활용했다. 작업 범위는 단일 애플리케이션에 그치지 않았다. 여러 라이브러리 저장소, BOM, Spring Boot 3/4 통합, Ktor 예제, Exposed JDBC/R2DBC, AWS, graph, image, leader election, text processing, workshop 문서까지 이어졌다.

처음에는 AI가 코드 작성 속도를 높여 줄 것이라 기대했다. 실제로 더 큰 효과는 다른 곳에서 나타났다. 코드 한두 파일을 빠르게 만드는 일보다 반복 작업을 자동화하고, 작업 과정을 문서화하고, 테스트를 보강하며, 여러 저장소에서 같은 기준을 유지하는 데서 차이가 컸다. 반대로 AI와 함께 일하는 절차가 없으면 생산성은 쉽게 흔들렸다.

AI가 실제로 도와준 일

먼저 체감한 효과는 자동화였다. GitHub Actions 워크플로 정비, 여러 저장소에 같은 설정을 적용하는 작업, Dependabot과 의존성 거버넌스 점검, 릴리스와 빌드 검증은 사람이 직접 반복할수록 피로가 쌓인다. AI는 이런 작업을 작은 단위로 나누고, 저장소별 차이를 확인하며, 실패 지점을 다시 좁혀 가는 데 유용했다.

문서 작업도 달라졌다. KDoc 보강, README 작성과 영·한 번역, 예제 설명, 마이그레이션 노트, GitHub issue와 PR 설명은 라이브러리 품질에 직접 영향을 주지만 시간이 많이 든다. AI를 활용한 뒤에는 초안을 빠르게 만들고, 사람이 최종 의미와 방향을 조정하는 방식으로 바뀌었다.

테스트 범위를 넓히는 데도 효과가 있었다. 기존 모듈에서 비어 있는 테스트 영역을 찾고, 공개 API 계약을 테스트로 고정하고, 경계 사례를 제안하며, 실패한 테스트를 분석하는 데 AI를 썼다. 특히 여러 모듈에 흩어진 유사 패턴을 비교해 “여기에도 같은 종류의 테스트가 필요하다”는 식으로 확장할 때 도움이 됐다.

신규 기능을 검토할 때는 조사와 시범 구현이 특히 유용했다. 이미지 처리에서 libvips를 검토하거나, Spring Boot 4와 Ktor 3 기반 예제를 구성하거나, Exposed R2DBC 사용 패턴을 정리할 때 AI는 공식 문서, 기존 코드, 대안의 장단점을 빠르게 모았다. 덕분에 사람은 선택지의 품질과 프로젝트 적합성에 더 집중할 수 있었다.

예제 시나리오를 구성할 때도 AI가 유용했다. 사용자가 어떤 흐름으로 배우면 좋은지, Spring Boot 예제와 Ktor 예제를 어떻게 나눌지, workshop chapter를 어떤 순서로 확장할지 아이디어를 얻었다. 이를 issue와 구현 계획으로 구체화할 수 있었다.

처음 2개월은 협업 자체가 어려웠다

처음 두 달은 AI를 쓴 시간이 그대로 생산성으로 이어지지 않았다. 반복 지시가 많았고, 이전에 전달한 규칙이 누락되거나 지시를 잘못 해석해 매 작업마다 사람이 다시 점검해야 하는 경우가 많았다.

문제는 작업 스타일이 매 세션마다 달라지는 것이었다. 어떤 세션에서는 테스트를 충분히 작성했지만, 다른 세션에서는 테스트가 약했다. 어떤 세션에서는 bluetape4k 작업 영역에 이미 있는 기능을 잘 찾아 쓰지만, 다른 세션에서는 같은 기능을 새로 만들려고 했다. 한 모듈에서 이미 해결한 문제를 다른 작업에서 다시 파는 일도 있었다.

코드 스타일도 흔들렸다. bluetape4k가 이미 제공하는 helper, assertion, Testcontainers launcher, 코루틴 패턴을 쓰기보다 외부 라이브러리나 일반적인 예제 스타일을 가져오려는 경우가 있었다. 대규모 라이브러리 생태계에서는 “동작하는 코드”만으로 부족하다. “기존 생태계와 같은 방식으로 동작하는 코드”여야 한다. AI에게 이 차이를 계속 알려 주는 장치가 필요했다.

또 하나의 비용은 토큰 소모였다. 매번 같은 배경, 규칙, 저장소 구조와 검증 절차를 다시 설명하는 일은 비효율적이었다. AI가 기억을 유지하지 못한다면, 기억을 외부화해 다시 불러올 수 있는 구조가 필요했다.

3개월째부터 협업 방식이 안정화됐다

전환점은 memory, wiki, lessons, skill을 축적하기 시작하면서 찾아왔다. 작업이 끝날 때마다 “완료”로만 끝내지 않았다. 무엇이 문제였고, 어떤 결정을 했고, 다음 작업자는 무엇을 피해야 하는지 lessons에 남겼다. 반복되는 결정은 skill로 승격했다.

대표적으로 bluetape4k-workflow, bluetape4k-full-feature, bluetape4k-code-patterns 같은 개인용 skill을 만들었다. 이 skill들은 bluetape4k의 운영 규칙을 다음 단계를 차단할 수 있는 체크리스트로 표현한다. 어떤 작업은 설계부터 해야 하는지, 어떤 작업은 fast track으로 충분한지, Kotlin 코드에서 어떤 검증과 테스트 스타일을 써야 하는지, GitHub issue와 PR은 어떤 기준으로 작성해야 하는지를 AI가 매번 다시 추측하지 않게 했다.

그중 bluetape4k-workflow는 작업을 시작할 때 먼저 적용하는 분류기 역할을 했다. 작업을 Type A Full Feature, B Fast Track, C Bug Fix, D Code Review, E Maintenance, P Publish, F Self Improve로 나눈다. 작은 문서 수정에는 과도한 설계 절차를 붙이지 않지만, 적용되지 않는 gate도 구체적인 범위 근거가 있을 때만 N/A로 처리한다. 반대로 새 모듈이나 공개 API처럼 되돌리기 어려운 작업에는 brainstorming, spec, plan, review, test, lessons까지 강하게 요구한다. 이 구분만으로도 토큰 소모와 반복 지시가 크게 줄었다.

bluetape4k-workflow는 단계별 통과 여부를 판정한다

bluetape4k-workflow의 핵심은 “다음에 무엇을 할지 알려 주는 절차표”가 아니라는 점이다. 각 단계가 다음 단계로 넘어가도 되는지 판정하는 장치에 가깝다. AI가 바로 구현으로 뛰어들려고 해도, 작업 흐름은 먼저 작업 종류를 분류하고 필요한 산출물과 검증 조건을 확인한다. 어떤 단계가 통과되지 않으면 다음 단계로 넘어가지 않으며, 누락된 설계·테스트·문서·리뷰를 먼저 채우게 한다.

이 방식은 작업 규모에 따라 절차를 다르게 적용할 때 특히 효과적이었다.

작은 문서/설정 변경

1. Maintenance 분류
2. 변경 범위 확인
3. 문서/API 이름 검증
4. Astro 빌드 또는 actionlint
5. 커밋/배포

작은 작업에 spec, plan, 자문 리뷰를 과도하게 붙여 토큰을 낭비하는 일을 막는다. 대신 실제로 필요한 링크, 경로, 빌드 검증은 빠뜨리지 않는다.

새 모듈, 공개 API, 저장소 간 변경

1. Full Feature 분류
2. brainstorming, spec, plan 작성
3. spec/plan 다관점 리뷰
4. Claude Code/Codex 상호 리뷰
5. 구현, 테스트, benchmark
6. 6-Tier 코드 리뷰, CI gate, lessons 기록

설계 없이 구현부터 시작하거나 기존 bluetape4k 패턴을 무시하고, 테스트·문서·CI·lessons가 뒤늦게 누락되는 일을 막는다.

예를 들어 단순한 블로그 문구 수정은 Maintenance로 분류된다. 이 경우 작업 흐름은 설계 gate를 조용히 건너뛰지 않고, 적용되지 않는 이유를 범위 증거와 함께 N/A로 남긴다. 그래도 빌드가 깨지지 않는지, 배포 페이지에 문구가 반영되는지, 관련 lessons에 반복 가능한 규칙을 남길 필요가 있는지는 확인한다. 작은 작업은 빠르게 끝내되 검증은 남기는 방식이다.

반대로 새 Ktor 모듈이나 Spring Boot auto-configuration처럼 구조를 바꾸는 작업은 Full Feature gate를 통과해야 한다. brainstorming에서 대안을 넓히고, spec에서 범위를 고정하고, plan에서 구현 순서와 테스트 전략을 쪼갠다. 그 다음 Claude Code와 Codex가 서로 다른 관점으로 spec/plan을 리뷰하고, 구현 후에는 6-Tier 코드 리뷰와 CI gate를 통과해야 한다. 느려 보이지만, 큰 작업에서 잘못된 방향으로 빠르게 가는 비용을 줄여 줬다.

큰 작업에서는 superpowers 방식으로 brainstorming, spec, plan을 먼저 만들었다. brainstorming은 문제를 바로 구현으로 옮기기 전에 대안과 위험을 넓게 보게 했고, spec은 만들 것과 만들지 않을 것을 고정했다. plan은 구현 순서, 테스트 전략, 문서 업데이트, CI 영향 범위를 작업 단위로 나눴다. AI에게 “잘 만들어 줘”라고 맡기는 대신, 사람이 검토할 수 있는 설계 문서와 실행 계획을 먼저 만드는 방식이었다.

spec과 plan은 한 번 작성하고 끝내지 않았다. 아키텍처, 테스트, 성능, 보안, 공개 API, 문서 관점에서 다시 읽게 했고, Claude Code와 Codex가 서로의 결과를 비판하게 했다. Claude Code CLI가 spec/plan의 빈틈을 찾으면, Codex가 그 지적을 현재 저장소 구조와 테스트 가능성에 맞게 반영하는 식이었다. 이 상호 리뷰는 특히 대규모 변경에서 “그럴듯하지만 프로젝트에 맞지 않는 설계”를 줄이는 데 도움이 됐다.

코드 리뷰에서도 같은 구조를 사용했다. 단순히 diff를 훑는 대신 관점을 나누어 봤다. API 계약이 깨지지 않았는지, 코루틴 취소를 삼키지 않는지, Exposed나 Spring Boot auto-configuration 규칙을 어기지 않는지, README와 실제 코드가 일치하는지, 테스트가 실패 경로까지 잠그는지 확인했다. 여기에 Claude Code와 Codex 상호 리뷰를 더하면 한쪽 모델이 놓친 명명 불일치, 누락된 보호 장치, 오래된 문서, 저장소 간 일관성 문제를 다른 쪽이 잡아내는 경우가 많았다.

bluetape4k-workflow의 또 다른 장점은 “작업의 끝”을 명확히 만든다는 점이었다. 구현이 끝났다는 느낌이 아니라, 어떤 테스트를 통과했고, 어떤 리뷰를 거쳤고, 어떤 lessons를 남겼고, 어떤 검증은 못 했는지를 기록하게 했다. 이 덕분에 다음 세션의 AI는 이전 작업의 맥락을 다시 추측하지 않고, 남겨진 spec, plan, lessons, PR 기록을 근거로 이어서 작업할 수 있었다.

작업 전후 리뷰도 중요했다. Claude Code CLI와 Codex CLI를 서로 리뷰에 사용하면서 한쪽 AI가 만든 계획이나 구현을 다른 쪽이 비판하게 했다. 특히 큰 변경에서는 구현 전에 설계 문제를 찾고, 구현 후에는 누락된 테스트, 깨진 계약, 어색한 문서, 저장소별 차이를 점검하는 방식이 효과적이었다.

이후 AI의 작업 방식은 덜 흔들렸다. 여전히 사람이 방향을 정하고 마지막 판단을 해야 하지만, AI가 매번 처음부터 출발한다는 느낌은 줄었다. 경험이 lessons와 skill에 쌓이면서 다음 작업의 품질이 이전 작업의 결과를 반영하기 시작했다.

효과

기존 라이브러리의 완성도가 올라갔다. 안정성과 성능을 점검하고, 오래된 버그를 수정하며, 테스트 범위를 보강하고, KDoc과 README를 최신 상태로 맞추는 작업을 더 자주 할 수 있었다. 이런 작업은 신규 기능보다 덜 화려하지만, 라이브러리 사용자에게는 훨씬 직접적인 품질 차이를 만든다.

신규 기능 개발 속도도 빨라졌다. 조사와 시범 구현으로 대안을 먼저 좁히고, 설계와 테스트 방향을 잡은 뒤 구현에 들어가니 시행착오가 줄었다. AI는 메인 코드와 테스트 구현뿐 아니라 코드 리뷰와 문서화까지 연결해서 도와줬다.

벤치마크를 더 자주 만들 수 있었던 것도 효과였다. 같은 문제를 여러 방식으로 구현해 보고 처리량, 지연 시간, 할당량, coroutine/virtual thread 차이, cache 전략, 직렬화 방식 같은 기준으로 비교했다. AI는 benchmark fixture와 반복 측정 코드를 빠르게 구성하고 결과를 해석할 관점을 제안했다. 덕분에 “어떤 방식이 더 빠르다”에서 끝나지 않고, 어떤 조건에서 어떤 방식을 선택해야 하는지 사용자에게 안내할 수 있었다.

예제도 더 다양해졌다. 단순히 API 사용법만 보여주는 예제가 아니라 사용자의 관심사에 따라 어떤 저장소를 보면 좋은지, Spring Boot와 Ktor 예제를 어떻게 비교하면 좋은지, Exposed JDBC와 R2DBC를 어떤 순서로 익히면 좋은지 같은 학습 경로를 만들 수 있었다.

무엇보다 여러 저장소에서 일관되게 작업할 수 있게 됐다. 대규모 생태계에서 일관성은 기능 수만큼 중요하다. BOM, 의존성 관리, README 구조, 테스트 스타일, CI 워크플로, issue와 PR 작성 기준이 흔들리면 유지보수 비용이 커진다. AI는 이 일관성을 강제하는 도구로 쓸 때 가장 효과적이었다.

제언

AI를 잘 쓰면 생산성은 분명히 높아진다. 다만 핵심은 AI에게 모든 것을 맡기는 것이 아니다. 사람이 해결해야 할 문제, 즉 WHAT을 명확히 정의해야 한다. 해결 방식, 즉 HOW는 AI에게 맡길 수 있다. 단, 그 HOW가 프로젝트의 철학과 기존 구조를 벗어나지 않도록 보호 장치가 필요하다.

조사, 설계, 계획이 먼저다. 바로 구현을 시키면 빨라 보이지만, 큰 작업에서는 잘못된 방향으로 빠르게 가는 비용이 더 크다. AI에게 먼저 조사하게 하고, 대안을 비교하게 하고, 테스트 전략을 정하게 한 뒤 구현으로 들어가는 쪽이 더 안정적이었다.

AI는 매번 기억이 초기화된다. 그래서 경험을 누적할 인프라가 필요하다. lessons, qmd, wiki, 저장소별 문서, skill 같은 외부 기억 장치를 만들고, 실제 작업에서 계속 사용해야 한다. 한 번 배운 것을 다음 작업에 반영하지 못하면 AI 협업은 매번 초보 상태로 돌아간다.

마지막으로, 경험은 skill에 보강해야 한다. lessons는 사건의 기록이고, skill은 다음 작업의 실행 규칙이다. issue, PR, 리뷰, 실패한 빌드, 누락된 테스트에서 얻은 반복 가능한 교훈을 skill에 반영하면 AI는 점점 더 프로젝트에 맞는 동료가 된다.

bluetape4k에서의 3개월은 “AI가 개발자를 대체한다”는 이야기와는 거리가 멀었다. 오히려 반대에 가까웠다. AI가 잘 일하게 만들려면 개발자가 문제를 더 명확히 정의하고, 작업 시스템을 더 정교하게 만들고, 결과를 더 엄격하게 검증해야 했다. 그 과정을 감수할 때 AI는 대규모 라이브러리 생태계를 꾸준히 밀고 나가는 증폭기가 된다.