AI와 3개월 동안 만든 대규모 Kotlin 라이브러리 생태계
지난 3개월 동안 bluetape4k 생태계를 크게 확장하면서 Claude Code와 Codex를 적극적으로 사용했다. 작업 범위는 단일 애플리케이션이 아니라 여러 라이브러리 repository, BOM, Spring Boot 3/4 통합, Ktor 예제, Exposed JDBC/R2DBC, AWS, graph, image, leader election, text processing, workshop 문서까지 이어졌다.
처음 기대했던 것은 “AI가 코드를 빨리 만들어 줄 것”이었다. 하지만 실제로 가장 큰 효과는 코드 한두 파일을 빨리 작성하는 데서 나오지 않았다. 효과는 반복 작업을 자동화하고, 작업 과정을 문서화하고, 테스트를 보강하고, 여러 repository에서 같은 기준을 유지하는 데서 나왔다. 반대로 AI와 제대로 협업하기 위한 작업 프로세스가 없으면 생산성은 쉽게 흔들렸다.
AI가 실제로 도와준 일
섹션 제목: “AI가 실제로 도와준 일”가장 먼저 체감한 도움은 자동화였다. GitHub Actions workflow 정비, 여러 repository에 같은 설정을 적용하는 작업, Dependabot과 dependency governance 점검, release와 build 검증 같은 일은 사람이 직접 반복하면 지치기 쉽다. AI는 이런 작업을 빠르게 나누고, repo별 차이를 확인하고, 실패한 부분을 다시 좁혀 가는 데 유용했다.
문서 작업도 큰 도움을 받았다. KDoc 보강, README 작성, README 영/한 번역, 예제 설명, migration note, GitHub issue와 PR 설명을 일정한 톤으로 작성하는 작업은 라이브러리 품질을 끌어올리는 데 중요하지만 시간이 많이 든다. AI를 붙이면서 문서의 초안을 빠르게 만들고, 사람이 마지막 의미와 방향을 조정하는 방식으로 바뀌었다.
테스트 coverage 향상에도 효과가 있었다. 기존 모듈의 빈 테스트 영역을 찾고, public API 계약을 테스트로 잠그고, edge case를 제안하고, 실패한 테스트를 분석하는 데 AI를 사용했다. 특히 여러 모듈에 흩어진 유사 패턴을 비교해 “여기에도 같은 종류의 테스트가 필요하다”는 식으로 확장하는 데 도움이 됐다.
신규 기능을 검토할 때는 research와 pilot 작업이 유용했다. 예를 들어 image 처리에서 libvips를 검토하거나, Spring Boot 4와 Ktor 3 기반 예제를 구성하거나, Exposed R2DBC 사용 패턴을 정리할 때 AI는 공식 문서, 기존 코드, 대안의 장단점을 빠르게 모아 의사결정 속도를 높였다.
예제 시나리오를 만드는 데도 AI가 강했다. 사용자가 실제로 어떤 흐름을 따라 배우면 좋은지, Spring Boot 예제와 Ktor 예제를 어떻게 나눌지, workshop chapter를 어떤 순서로 확장할지 같은 아이디어를 제안받고 바로 issue와 구현 계획으로 바꿀 수 있었다.
처음 2개월은 협업 자체가 어려웠다
섹션 제목: “처음 2개월은 협업 자체가 어려웠다”처음 두 달은 AI를 쓰는 시간이 곧바로 생산성으로 이어지지 않았다. 반복 지시가 많았고, 이전에 말한 규칙이 누락되거나, 지시를 무시하거나, 매 작업마다 사람이 다시 점검해야 하는 일이 많았다.
가장 큰 문제는 작업 스타일이 매 세션마다 달라지는 것이었다. 어떤 세션에서는 테스트를 충분히 작성하지만, 다른 세션에서는 테스트가 약했다. 어떤 세션에서는 bluetape4k workspace에 이미 있는 기능을 잘 찾아 쓰지만, 다른 세션에서는 같은 기능을 새로 만들려고 했다. 기존 모듈에서 이미 해결한 문제를 다른 작업에서는 다시 삽질하는 일도 있었다.
코드 스타일도 흔들렸다. bluetape4k가 이미 제공하는 helper, assertion, testcontainer launcher, coroutine pattern을 쓰기보다 외부 라이브러리나 일반적인 예제 스타일을 가져오려는 경우가 있었다. 대규모 라이브러리 생태계에서는 “동작하는 코드”보다 “기존 생태계와 같은 방식으로 동작하는 코드”가 더 중요하다. AI에게 이 차이를 계속 알려 주는 장치가 필요했다.
또 하나의 비용은 토큰 소모였다. 매번 같은 배경, 같은 규칙, 같은 repo 구조, 같은 검증 절차를 다시 설명하는 것은 비효율적이었다. AI가 기억을 유지하지 못한다면, 기억을 외부화하고 다시 불러올 수 있는 구조가 필요했다.
3개월째부터 협업 방식이 안정화됐다
섹션 제목: “3개월째부터 협업 방식이 안정화됐다”전환점은 memory, wiki, lessons, skill을 쌓기 시작하면서 왔다. 작업이 끝날 때마다 단순히 “완료”로 끝내지 않고, 무엇이 문제였고, 어떤 결정을 했고, 다음 작업자는 무엇을 피해야 하는지 lessons에 남겼다. 반복되는 결정은 skill로 승격했다.
대표적으로 bluetape4k-workflow, bluetape4k-design, bluetape4k-patterns 같은 개인 skill을 만들었다. 이 skill들은 단순 체크리스트가 아니라 bluetape4k 작업의 기본 운영 방식을 담는다. 어떤 작업은 설계부터 해야 하는지, 어떤 작업은 fast track으로 충분한지, Kotlin 코드에서 어떤 validation과 test style을 써야 하는지, GitHub issue와 PR은 어떤 기준으로 작성해야 하는지를 AI가 매번 다시 추측하지 않게 했다.
이 중 bluetape4k-workflow는 작업을 시작할 때 가장 먼저 적용하는 router 역할을 했다. 작업을 Full Design, Fast Track, Bug Fix, Code Review, Maintenance로 나누고, 작업 성격에 따라 필요한 단계와 건너뛸 단계를 정했다. 작은 문서 수정에 과도한 설계 절차를 붙이지 않고, 반대로 새 모듈이나 public API처럼 되돌리기 어려운 작업에는 brainstorming, spec, plan, review, test, lessons까지 강하게 요구했다. 이 구분만으로도 토큰 소모와 반복 지시가 크게 줄었다.
bluetape4k-workflow는 단계별 gatekeeper다
섹션 제목: “bluetape4k-workflow는 단계별 gatekeeper다”bluetape4k-workflow의 가장 큰 특징은 단순히 “다음에 무엇을 할지 알려 주는 절차표”가 아니라, 각 단계가 다음 단계로 넘어가도 되는지 확인하는 gatekeeper 역할을 한다는 점이다. AI가 바로 구현으로 뛰어들려고 해도, workflow는 먼저 작업 종류를 분류하고, 필요한 산출물과 검증 조건을 확인한다. 어떤 단계가 통과되지 않으면 다음 단계로 넘어가지 않고, 누락된 설계, 테스트, 문서, 리뷰를 먼저 채우게 한다.
이 방식은 작업 규모에 따라 절차를 다르게 적용할 때 특히 효과적이었다.
- Maintenance 분류
- 변경 범위 확인
- 문서/API 이름 검증
- Astro build 또는 actionlint
- 커밋/배포
작은 작업에 spec, plan, advisor review를 과하게 붙여 토큰을 낭비하는 문제를 막는다. 대신 실제로 필요한 링크, 경로, 빌드 검증은 빠뜨리지 않는다.
- Full Design 분류
- brainstorming, spec, plan 작성
- spec/plan 다관점 리뷰
- Claude Code/Codex 상호 리뷰
- 구현, 테스트, benchmark
- 6-Tier code review, CI gate, lessons 기록
설계 없이 구현부터 시작하는 문제, 기존 bluetape4k 패턴을 무시하는 문제, 테스트/문서/CI/lessons가 뒤늦게 빠지는 문제를 막는다.
예를 들어 단순한 블로그 문구 수정은 Maintenance로 분류된다. 이 경우 workflow는 “지금 spec을 만들 필요가 있는가?”를 먼저 판단하고, 불필요한 단계를 스킵한다. 하지만 빌드가 깨지지 않는지, live page에 문구가 반영되는지, 관련 lessons에 반복 가능한 규칙을 남길 필요가 있는지는 확인한다. 작은 작업은 빠르게 끝내되 검증은 남기는 방식이다.
반대로 새 Ktor module이나 Spring Boot auto-configuration처럼 구조를 바꾸는 작업은 Full Design gate를 통과해야 한다. brainstorming에서 대안을 넓히고, spec에서 범위를 고정하고, plan에서 구현 순서와 테스트 전략을 쪼갠다. 그 다음 Claude Code와 Codex가 서로 다른 관점으로 spec/plan을 리뷰하고, 구현 후에는 6-Tier code review와 CI gate를 통과해야 한다. 이 절차는 느려 보이지만, 큰 작업에서 잘못된 방향으로 빠르게 가는 비용을 줄여 줬다.
큰 작업에서는 superpowers 방식의 brainstorming, spec, plan을 먼저 만들었다. brainstorming은 문제를 바로 구현으로 밀어 넣기 전에 대안과 위험을 넓게 보게 했고, spec은 무엇을 만들지와 만들지 않을지를 고정했다. plan은 구현 순서, 테스트 전략, 문서 업데이트, CI 영향 범위를 작업 단위로 쪼갰다. AI에게 “잘 만들어 줘”라고 맡기는 대신, 사람이 검토할 수 있는 설계 문서와 실행 계획을 먼저 만드는 방식이었다.
spec과 plan은 한 번 작성하고 끝내지 않았다. 아키텍처, 테스트, 성능, 보안, public API, 문서 관점에서 다시 읽게 했고, Claude Code와 Codex가 서로의 결과를 비판하게 했다. Claude Code CLI가 spec/plan의 빈틈을 찾고, Codex가 그 지적을 현재 repository 구조와 테스트 가능성에 맞게 반영하는 식이었다. 이 상호 리뷰는 특히 대규모 변경에서 “그럴듯하지만 프로젝트에 맞지 않는 설계”를 줄이는 데 도움이 됐다.
코드 리뷰에서도 같은 구조를 사용했다. 단순히 diff를 훑는 대신 여러 관점을 나누어 봤다. API 계약이 깨지지 않았는지, coroutine cancellation을 삼키지 않는지, Exposed나 Spring Boot auto-configuration 규칙을 어기지 않는지, README와 실제 코드가 일치하는지, 테스트가 실패 경로까지 잠그는지 확인했다. 여기에 Claude Code와 Codex 상호 리뷰를 더하면 한쪽 모델이 놓친 naming drift, 누락된 guard, stale documentation, cross-repo 일관성 문제를 다른 쪽이 잡아내는 경우가 많았다.
bluetape4k-workflow의 또 다른 장점은 “작업의 끝”을 명확히 만든다는 점이었다. 구현이 끝났다는 느낌이 아니라, 어떤 테스트를 통과했고, 어떤 리뷰를 거쳤고, 어떤 lessons를 남겼고, 어떤 검증은 못 했는지를 기록하게 했다. 이 덕분에 다음 세션의 AI는 이전 작업의 맥락을 다시 추측하지 않고, 남겨진 spec, plan, lessons, PR 기록을 근거로 이어서 작업할 수 있었다.
작업 전후 리뷰도 중요했다. Claude Code CLI와 Codex CLI를 서로 리뷰에 사용하면서 한쪽 AI가 만든 계획이나 구현을 다른 쪽이 비판하게 했다. 특히 큰 변경에서는 구현 전에 설계 문제를 찾고, 구현 후에는 누락된 테스트, 깨진 계약, 어색한 문서, repo별 차이를 점검하는 방식이 효과적이었다.
이후부터 AI는 덜 흔들렸다. 여전히 사람이 방향을 정하고 마지막 판단을 해야 하지만, AI가 매번 처음부터 출발하는 느낌은 줄었다. 경험이 lessons와 skill에 쌓이면서 다음 작업의 품질이 이전 작업의 결과를 반영하기 시작했다.
기존 라이브러리의 완성도가 올라갔다. 안정성과 성능을 점검하고, 오래된 버그를 수정하고, 테스트 coverage를 보강하고, KDoc과 README를 최신 상태로 맞추는 작업을 더 자주 할 수 있었다. 이런 작업은 눈에 띄는 신규 기능보다 덜 화려하지만, 라이브러리 사용자에게는 훨씬 직접적인 품질 차이를 만든다.
신규 기능 개발 속도도 빨라졌다. research와 pilot을 먼저 돌려 대안을 좁히고, 설계와 테스트 방향을 잡은 뒤 구현에 들어가니 시행착오가 줄었다. AI는 메인 코드와 테스트 구현뿐 아니라 코드 리뷰와 문서화까지 연결해서 도와줬다.
Benchmark를 더 자주 만들 수 있었던 것도 효과였다. 같은 문제를 여러 방식으로 구현해 보고 처리량, latency, allocation, coroutine/virtual thread 차이, cache 전략, 직렬화 방식 같은 기준으로 비교했다. AI는 benchmark fixture와 반복 측정 코드를 빠르게 구성하고 결과를 해석할 관점을 제안했다. 덕분에 “어떤 방식이 더 빠르다”에서 끝나지 않고, 어떤 조건에서는 어떤 방식을 선택해야 하는지 사용자에게 선택 가이드로 제공할 수 있었다.
예제도 더 다양해졌다. 단순히 API 사용법만 보여주는 예제가 아니라 사용자의 관심사에 따라 어떤 repository를 보면 좋은지, Spring Boot와 Ktor 예제를 어떻게 비교하면 좋은지, Exposed JDBC와 R2DBC를 어떤 순서로 익히면 좋은지 같은 learning path를 만들 수 있었다.
무엇보다 여러 repository에 대해 일관된 작업을 할 수 있게 됐다. 대규모 생태계에서 일관성은 기능 수만큼 중요하다. BOM, dependency management, README 구조, 테스트 스타일, CI workflow, issue와 PR 작성 기준이 흔들리면 유지보수 비용이 커진다. AI는 이 일관성을 강제하는 도구로 쓸 때 가장 큰 효과가 있었다.
AI를 잘 쓰면 생산성은 분명히 높아진다. 하지만 핵심은 AI에게 모든 것을 맡기는 것이 아니라, 사람이 해결해야 할 문제, 즉 WHAT을 명확히 정의하는 것이다. 어떤 해결 방식, 즉 HOW는 AI에게 맡길 수 있다. 단, 그 HOW가 프로젝트의 철학과 기존 구조를 벗어나지 않도록 guardrail이 필요하다.
Research, 설계, 계획이 가장 중요하다. 바로 구현을 시키면 빨라 보이지만, 큰 작업에서는 잘못된 방향으로 빠르게 가는 비용이 더 크다. AI에게 먼저 조사하게 하고, 대안을 비교하게 하고, 테스트 전략을 정하게 한 뒤 구현으로 들어가는 쪽이 더 안정적이었다.
AI는 매번 기억이 리셋된다. 그래서 경험을 누적할 인프라가 필요하다. lessons, qmd, wiki, repo-local docs, skill 같은 외부 기억 장치를 만들고, 실제 작업에서 계속 사용해야 한다. 한 번 배운 것을 다음 작업에 반영하지 못하면 AI 협업은 매번 초보 상태로 돌아간다.
마지막으로, 경험은 skill에 보강해야 한다. lessons는 사건의 기록이고, skill은 다음 작업의 실행 규칙이다. issue, PR, review, 실패한 build, 누락된 테스트에서 얻은 반복 가능한 교훈을 skill에 반영하면 AI는 점점 더 프로젝트에 맞는 동료가 된다.
bluetape4k에서의 3개월은 “AI가 개발자를 대체한다”는 이야기와는 거리가 멀었다. 오히려 반대에 가까웠다. AI가 잘 일하게 만들려면 개발자가 문제를 더 명확히 정의하고, 작업 시스템을 더 정교하게 만들고, 결과를 더 엄격하게 검증해야 했다. 그 과정을 감수할 때 AI는 대규모 라이브러리 생태계를 꾸준히 밀고 나가는 강력한 증폭기가 된다.