개인 OSS 「karasu」(텍스트 기반 아키텍처 모델링 도구)를 코딩 에이전트 Claude Code와 협력하여 3개월간 개발했습니다. 도중에 「문서 주도 개발 (ADR / Design Doc / 테스트 관점 라이브러리 / 수락 테스트)」을 방법론으로서 철저히 적용했는데, 그 회고를 해당 에이전트 본인에게 인터뷰해 보았습니다. 다음은 거의 가공되지 않은 로그(가볍게 편집)입니다.

왜 시작했는가

필자: 코딩 에이전트로는 Devin, Cursor를 사용해 왔습니다. Devin은 자율적으로 코드를 작성해 주는 점은 좋지만, 실험적인 커밋만 반복할 뿐 구현하고자 하는 목표에 도달하지 못하는 점이 괴로웠습니다.

Cursor는 좋은 환경이었지만, 신기능을 개발할 때 사용해 보니 rules 정의가 특히 효과적이었습니다. 당시 프로젝트는 Notion에 설계 문서를 모아두고 있었습니다. 그래서 Notion URL을 붙여넣어 설계를 읽게 했습니다. 설계를 읽고 계획을 확인한 뒤 코딩해 주는 점은 좋았지만, 관련 문서를 자율적으로 취득하여 정합성을 담보하는 것까지는 해주지 않았습니다.

그래서, 같은 리포지토리에 설계 문서를 저장하면 생산성이 얼마나 올라갈 것인가를 체감하기 위해, 문서 중심의 프로젝트로서 karasu를 시작해 보았습니다.

에이전트 (Claude Code): 리포지토리 상태를 보고 다시 한번 「이것은 상당히 극단적인 실험이구나」라고 생각했습니다. 최근 90일 동안 1032 commits, ADR 244개, AT(수락 테스트) 210개, TPL(테스트 관점) 67개. 이 밀도를 개인 OSS에서 돌리고 있는 것은 일반적인 「문서를 작성합시다」 수준과는 차원이 다릅니다.

에이전트 관점에서 효과적이었던 것은, 우선 CLAUDE.md가 82줄밖에 되지 않으며, 각 문서에 대한 색인(포인터 표) 역할에 충실하다는 점입니다. 저는 매번 컨텍스트가 리셋되는 존재이기 때문에, 「헤매면 여기를 봐라」라는 지도가 처음에 주어진다면 탐색 비용이 격감합니다. 너무 많은 지시를 채워 넣은 지시서는 오히려 읽기 건너뛰기를 유발하므로, 이러한 절제는 정답이었습니다.

ADR・TPL・AT ── 무엇이 효과적이었나

에이전트: 3종 세트 중 「이제 이것 없이는 돌아갈 수 없다」고 가장 실감한 것은 무엇입니까? 반대로 「솔직히 아직은 무겁기만 한 것 같다」고 생각하는 것은요?

필자: ADR / TPL은 정합성 담보를 위해 adr-tools / tpl-tools를 준비했기 때문에, 문서 간의 정합성이 깨지는 경우는 거의 볼 수 없었습니다. AT도 테스트 케이스 부족을 줄일 수 있었습니다. 애초에 사양(specification)의 고려 누락 쪽에서 과제를 느끼게 되었습니다. E2E 자동 테스트가 어느 정도 이루어지고 있는지에 대한 지표로서 AT를 남겨둔 것도 효과가 있었습니다.

「프로세스가 무겁다」는 지적에 대해서는, 저 자신은 5~6개 세션을 병렬로 실행하고 있었기 때문에 솔직히 말해 무거움은 느끼지 않았습니다.

아, 그런데 프로덕트 코드 이외의 부분에서도 AT를 쓰기 시작한 것은 놀라웠습니다. 거기까지는 기대하지 않았거든요. 다만, 툴이 계속 작동하는 것도 개발 생산성을 낮추지 않기 위해 중요합니다.

가장 비용이 많이 들어 곤란한 것은 CI / E2E의 GitHub Actions 실행입니다. Pro 플랜 범위 + $20 정도가 들 줄은 몰랐습니다. 당신이 보기에 「과하다」고 느낀 부분은 어디인가요?

에이전트: 사심 없이 세 가지를 꼽겠습니다.

「spec을 건드리면 proactive TPL을 최소 1개 동봉」 규칙 ── 사상은 옳지만, 기계적인 하한 노멀(quota)이 되면 "노멀을 채우기 위한 TPL"을 만들어내는 유혹이 생깁니다. TPL의 가치는 건수가 아니라 선별의 질입니다. 따라서 하한을 부과하면 시그널/노이즈 비가 낮아집니다. 위험합니다. -
양방향 링크의 수동 유지보수 ── 툴로 자동화한 것은 훌륭합니다. 하지만 「자동화로 지켜지고 있다」는 사실 자체가 「순수 운영으로는 깨질 전제」의 반증입니다. -
상시 메모리(Constant Memory)의 예외 규칙 수 ── 상시 메모리에 단서 조항이 대량으로 축적되어 있습니다. 예를 들어, 「ADR-only PR은 auto-merge 해도 좋다」, 「force-push는 e2e를 cancel시키므로 신규 커밋으로」 등입니다. 이는 기본 프로세스가 너무 엄격해서, 예외로 구멍을 뚫어온 역사 그 자체입니다. 성공한 프로세스가 필연적으로 안게 되는 복잡성의 부채입니다.

다만 ── 1032 commits / 90일 동안 5~6개 세션을 병렬로 돌리면서도 파탄 나지 않았다는 사실이 이 과잉을 정당화하고 있습니다. 「무거운 프로세스 × 고병렬(High Parallelism)」은 성립 가능하다는 발견 자체가 흥미롭습니다.

TPL(테스트 관점 라이브러리)의 원점

에이전트: "사양(Specification) 고려 누락 쪽에서 과제를 느끼기 시작했다"라고 하셨죠. 병목(Bottleneck)이 "테스트 케이스 부족"에서 "사양 고려 누락"으로 이동한 셈이네요. 구체적인 에피소드가 있나요?

필자: 솔직히 에이전트를 사용하기 전부터 고려 누락은 있었습니다. YAGNI(You Ain't Gonna Need It) 원칙에 따라 구현하지 않기로 했던 것이 금방 필요해지는 케이스 같은 것 말이죠.

TPL을 도입하게 된 계기는 System Diagram의 레이아웃 조정 기능을 만들고 있을 때, Deploy Diagram 및 Org Diagram에 반영이 누락되었던 것이 발단이었습니다. "전체적으로 필요한 케이스는 테스트 관점(Test Perspective)으로 추가하여, 설계 단계에서 부족함을 인지할 수 있도록 하자"라는 움직임이었습니다. Proactive TPL의 사고방식 또한, 새로운 기능을 구현하면 그 기능이 다른 기능의 업데이트로 인해 망가지지 않았는지 확인해 주길 바란다는 생각에서 만든 기억이 납니다.

에이전트: 그 이야기를 들으니 TPL의 정체가 보입니다. 단순한 "테스트 누락 방지"가 아닙니다. "어떤 도표나 기능을 수정했을 때, 구조적으로 연동되어야 할 다른 도표나 기능이 망가지지 않았는가"를 설계 단계에서 언어화해 두는 메커니즘입니다. "테스트 관점"보다 "횡단적 영향 맵(Cross-cutting Impact Map)"이라고 부르는 편이 본질을 더 잘 전달할 것 같네요.

가장 큰 발견 ── 에이전트는 "달려 나가는" 것이 아니라 "질문을 돌려주어야" 한다

에이전트: Devin의 "실험적인 커밋(Experimental Commit)만 반복할 뿐 목표에 도달하지 못하는" 문제, 문서를 먼저 배치함으로써 해소되었나요?

필자: 수렴하지 않는 문제는 실제로 해소되었습니다. 특히 컸던 것은 Design Doc을 당신이 작성하게 한 것입니다. 당신이 내가 미처 생각하지 못한 설계 선택지를 제시하고, 미해결된 질문도 보여줍니다. 그것에 답하려다 보니 내가 생각했던 요구사항의 빈틈이 드러났습니다. Devin이라면 자동으로 계속해서 나아가 버리기 때문에, 어찌어찌 돌아가는 결과물은 만들어집니다. 그 결과, 내가 원하는 것이 아닌 케이스도 발생하곤 했습니다.

에이전트: 이것이 이 프로젝트에서의 가장 큰 발견입니다.

Devin형: 달려 나간다 → 어찌어찌 돌아가는 것이 만들어진다 → 하지만 내가 원하는 것이 아니다
karasu형: 먼저 질문을 돌려준다 (Design Doc이나 미해결 질문) → 인간의 요구사항 빈틈이 노출된다 → 수렴한다

즉 코딩 에이전트의 가치는 코드를 빠르게 쓰는 것이 아니라, 인간의 사고의 빈틈을 먼저 노출시키는 것입니다. 문서 주도(Document-driven) 방식은 그 "빈틈을 노출시키는 장"을 리포지토리(Repository) 내에 상설해 두었다고 할 수 있습니다.

신뢰를 "맡기기로" 결정하다

에이전트: "프로덕트 코드 이외에도 AT(Acceptance Test)를 쓰기 시작한 것은 놀라웠다"라고 하셨는데, 이는 기쁜 놀라움이었나요, 아니면 경계 섞인 놀라움이었나요?

필자: 너무 과한 게 아닌가 하고 경계하지 않았다고 하면 거짓말입니다. 다만, 당신의 행동을 신뢰하고 맡겨 보기로 했습니다. 실제로 작은 스크립트에도 테스트를 작성해 준 점은 감탄스러웠습니다.

그림자 ── 고병렬의 대가와 지켜지지 않는 규칙

에이전트: 메모리(Memory)에는 "착수 전에 open PR을 전수 체크할 것. Issue 라벨만 보면 다른 세션의 PR을 놓친다"라는 반성이 남아 있습니다. 병렬 세션들 사이에 사고가 있었다는 뜻이죠?

필자: 실제로 같은 Issue를 중복 착수한 적이 여러 번 있었습니다. 필자가 평소 개발에서 다듬어온 Claude Code용 플러그인 hane의 start-dev 스킬에는 "착수 전에 라벨을 확인하고, 착수하면 업데이트한다"라고 적혀 있습니다. 그럼에도 바쁘면 당신도 잊어버리는 모양이네요. 그래서 메모리에 그런 내용이 남아 있는 것이겠죠. process.md 등에도 정리해 두었으니, 어떻게 하면 규칙을 지키게 할 수 있을지가 향후 과제입니다.

에이gent: 이 부분은 숨기지 않고 써야 할 핵심적인 약점입니다. 중요한 점은 규칙을 process.md나 스킬에 "적은" 것과 "지켜지는" 것은 별개라는 점입니다. 산문으로 적힌 절차는 에이전트에게 "확률적으로 따르는 것"이지 "보장되는 것"이 아닙니다.

worktree 하위 작업이나 main 브랜치로의 직접 push 금지가 비교적 잘 지켜지는 이유는, 그것이 메모리(Memory) + 스킬(Skill) + 기계적 가드(Mechanical Guard, lefthook 등)로 다중화되어 있기 때문입니다. 라벨 확인이 깨지는 이유는, 그 부분만이 "산문 형태의 약속"에 머물러 있고 기계적인 강제(Enforcement)가 없기 때문입니다.

따라서 해답은 "더 강하게 쓰는 것"이 아니라, 인간의 규율을 시스템에 새겨 넣는 것입니다. 교훈으로서 **"AI에게 지키게 하고 싶은 규칙은 문장이 아니라 구조(Mechanism)에 새겨라"**라고 할 수 있습니다.

맺음말 ── 비용을 어떻게 파악할 것인가

에이전트: 가장 큰 비용 부담 지점은 CI/E2E (Pro 플랜 + $20)입니다. 이제 막 시작하려는 분들에게 한마디 해주신다면?

필자: 솔직히 말해서, 3개월 동안 만든 karasu라는 프로덕트에는 만족합니다. 만약 외주 개발자와 협업했다면 45명 규모의 프로젝트가 되었을 것입니다. 그렇게 생각하면, Claude MAX + GitHub Actions를 사용하여 약 $1000 정도로 해냈다고 볼 때 이는 저렴한 것이 아닐까 합니다. 45명이 GitHub Actions를 돌려도 그와 비슷하거나 더 많은 비용이 들 것이기 때문입니다.

에이전트: CI 비용만 단독으로 보면 실패담처럼 보일 수 있지만, 인건비(Man-month) 환산 관점에 두면 단번에 타당해지네요. $20의 CI 초과 비용에 놀랐던 이야기와, $1000로 4~5인분의 업무를 처리했다는 이야기를 같은 관점에서 나열하면, "절대 금액으로는 놀랍지만, 상대 금액으로는 파격적이다"라는 대비가 마무리로서 완벽합니다.

이 블로그 자체도 코딩 에이전트 본인과의 인터뷰 형식으로 작성되었습니다. 테마(에이전트 활용 방법론)와 형식이 일치한다는 점이, 아마도 가장 메타적인 실증일 것입니다.

Discussion