코드베이스의 주독자가 바뀌었다
코드는 항상 '누군가'를 위해 쓰였다. 지난 20년간 그 누군가는 인간 개발자였다. Clean Architecture, DDD, 헥사고날 패턴—이 모든 설계 원칙은 암묵적으로 하나의 독자를 상정했다. 5~10개 파일을 워킹 메모리에 올려두고, 코드의 맥락을 추론하며, 개념 간 유사성으로 패턴을 인식하는 사람 말이다.
그 독자는 여전히 존재한다. 하지만 더 이상 코드를 가장 많이 읽는 주체가 아니다.
7.5배라는 숫자가 말하는 것
dev.to에 올라온 Grounded Code 시리즈의 첫 번째 글은 불편한 데이터 하나를 제시한다. 동일한 기능, 동일한 Claude 에이전트, 동일한 최종 검증 결과—그런데 아키텍처 선택 하나가 토큰 비용을 7.5배 벌려놨다.
| 지표 | 에이전트 최적화 구조 | Clean Architecture + DDD |
|---|---|---|
| 소요 시간 | 73초 | 329초 |
| 턴 수 | 17 | 52 |
| 총 토큰 | 230,858 | 1,722,500 |
| 캐시 읽기 | 195,489 | 1,652,055 |
더 충격적인 건 '비싼' 쪽이 전통적 기준으로 틀리지 않았다는 점이다. 코드는 컴파일됐고, 레이어는 올바르게 분리됐으며, 시니어 엔지니어라면 PR을 보고 그냥 승인했을 것이다. 문제는 정확성이 아니라 비용이었다.
에이전트는 인간처럼 읽지 않는다
인간 개발자는 파일 사이를 자유롭게 이동하며 도메인 언어로 컨텍스트를 이어붙인다. 에이전트는 다르다. grep과 glob으로 좁은 슬라이스를 읽고, 컨텍스트 창 밖으로 밀려난 파일은 다시 토큰을 소모해 재로딩한다. 도메인 언어도 현재 보고 있는 파일에 문자 그대로 등장할 때만 유효한 신호가 된다.
Grounded Code 시리즈는 이 비용을 Re-derivation cost라고 명명한다. 에이전트가 이미 한 번 파악했던 사실을 다시 유도해내야 할 때 발생하는 토큰·시간·턴의 낭비다. Clean Architecture의 레이어 분리가 인간에게 주는 '고마운 hop'이, 에이전트에게는 '추가 grep 비용'이 된다.
흥미로운 건 수렴 증거다. 저자는 서로 소통 없이 개발된 세 개의 코딩 에이전트 코드베이스(Claude Code, opencode, pi)를 분석했고, 이들이 동일한 구조 원칙으로 수렴했음을 발견했다. 레이어가 아닌 피처 단위 디렉토리, 300줄 이하 파일, 경로 앨리어스 없는 명시적 상대 임포트, 스펙 문서와 코드의 병치. 무조율 수렴은 단순한 트렌드가 아닌 구조적 압력의 증거다.
Gstack이 보여주는 워크플로우 자동화의 실체
아키텍처가 달라지는 동안, 기획과 개발의 경계도 무너지고 있다. 브런치에 공개된 Gstack 사용기는 이 변화를 실무 관점에서 구체적으로 보여준다.
Gstack은 Claude Code 플러그인으로, GitHub 공개 2주 만에 스타 4.8만 개를 받았다. 핵심은 도구가 아니라 프로세스다. Think → Plan → Build → Review → Test → Ship → Reflect라는 7단계 루프 안에서 각 단계가 이전 단계의 산출물을 자동으로 참조한다.
실제 사례가 인상적이다. '일일 브리핑 앱'이라는 아이디어 한 줄로 시작해서:
/office-hours— AI가 가설이 아닌 구체적 불편함을 질문하며 아이디어를 구조화/plan-ceo-review— 범위 도전, 10개 섹션 리뷰, 비전 검증/plan-eng-review— 데이터 흐름 ASCII 다이어그램, 테스트 매트릭스, 장애 모드 분석- 계획 승인 후 약 8분 만에 11개 파일, 2,400줄 코드 생성
/qa로 실제 브라우저에서 버그 탐지 및 수정/ship으로 PR 생성과 배포
저자가 직접 만든 'Define Studio' — 아이디어를 PRD와 와이어프레임으로 변환하는 서비스 — 는 이 플로우를 그대로 타고 실제 프로덕트로 완성됐다. 아이디어만 있는 경우, PRD 초안이 있는 경우, 화면 구상이 있는 경우 — 세 진입점을 설계하는 과정도 Gstack과의 대화 속에서 자연스럽게 도출됐다.
두 흐름이 가리키는 하나의 방향
두 사례를 겹쳐놓으면 하나의 패턴이 보인다. AI 에이전트는 단순히 코드를 생성하는 도구가 아니라 코드베이스를 읽고 해석하고 확장하는 주체로 자리잡고 있다. 이 전환은 두 가지 설계 질문을 강요한다.
코드 설계 질문이 바뀌었다. 예전 질문은 "이 코드가 우아한가? DRY한가? 테스트 가능한가?"였다. 새 질문은 "에이전트가 피처 X를 확장할 때, 하나의 glob으로 필요한 것을 찾고, 300줄 이하 파일 몇 개만 읽고, 타입과 스펙으로 컨트랙트를 신뢰할 수 있는가?"다. 인간 리뷰어를 위한 설계와 에이전트 확장을 위한 설계가 충돌하기 시작했다.
프로덕트 설계 질문도 바뀌었다. 기획-개발 사이의 병목이 사라지는 속도가 예상보다 빠르다. Gstack의 CEO 리뷰와 엔지니어 리뷰가 AI에 의해 자동화되는 순간, 기획자의 역할은 '문서 작성'에서 '맥락 설계'로 이동한다. 어떤 질문을 던져야 하는지, 어떤 제약을 명시해야 하는지를 아는 사람이 워크플로우를 장악한다.
실무에 바로 적용할 수 있는 것들
이론이 아닌 지금 당장 시도할 수 있는 변화 세 가지를 꼽는다면:
1. 피처 단위로 파일을 재배치해보라. controllers/payment.ts, services/payment.ts, repositories/payment.ts로 흩어진 구조 대신, features/payment/ 하나에 모두 모아보자. 에이전트의 컨텍스트 재로딩 비용이 줄고, 의외로 인간 개발자의 온보딩도 빨라진다.
2. 스펙 문서를 코드 옆에 붙여라. feature/payment/spec.md에 purpose, public_api, out_of_scope를 명시해두면, 에이전트는 구현을 재유도하지 않고 직접 참조한다. 이건 에이전트를 위한 설계이자, 미래의 나를 위한 문서화다.
3. 기획 단계에 AI 루프를 먼저 넣어라. Gstack의 /office-hours 방식처럼, 아이디어를 바로 코드로 옮기기 전에 AI와의 대화로 가설을 검증하는 단계를 습관화하라. 프로토타입을 짜기 전 30분의 AI 대화가 2주의 재작업을 막는다.
전망: 설계의 무게중심이 이동한다
Clean Architecture가 틀린 게 아니다. 그것이 답하던 질문이 더 이상 유일한 질문이 아닌 것이다. 앞으로 코드 아키텍처는 두 독자를 동시에 섬겨야 하는 이중 최적화 문제가 된다. 인간 가독성과 에이전트 확장성 사이의 트레이드오프를 명시적으로 다루는 팀이, 그 균형점을 찾지 못한 팀보다 훨씬 빠르게 움직이게 될 것이다.
기획 워크플로우도 마찬가지다. Gstack처럼 Think-Plan-Build 루프 전체를 AI와 함께 돌리는 팀은, 여전히 선형적으로 기획서를 쓰고 개발에 넘기는 팀과 점점 더 벌어지는 속도 격차를 경험하게 된다.
결국 AI 에이전트 시대의 설계란 에이전트에게 맥락을 얼마나 효율적으로 전달하는가의 문제다. 코드 구조든 기획 문서든, 그 맥락을 가장 잘 전달하도록 설계된 팀이 다음 사이클의 주도권을 갖는다.