AI 코딩 도구에 대한 가장 흔한 오해는 '모델이 더 똑똑해지면 해결된다'는 생각이다. 하지만 현장에서 반복되는 좌절—자신 있게 틀린 답변, 변경 사항의 연쇄 버그, 의도와 전혀 다른 코드—은 모델의 지능 문제가 아니다. 세 편의 실험적 사례가 동시에 가리키는 것은 하나다. 문제는 설계 구조에 있다.
병목 1: AI는 당신의 코드베이스를 '탐색'하지 못한다
dev.to의 한 엔지니어가 날카롭게 진단한 것처럼, Claude 같은 AI 어시스턴트의 진짜 병목은 지능이 아니라 코드베이스 내비게이션이다. auth 모듈을 수정했는데 api 레이어가 3일 뒤 깨지는 이유는, AI에게 두 모듈이 연결되어 있다는 사실을 알 방법이 없기 때문이다. 대부분의 AI_INDEX 템플릿은 디렉터리 목록—일종의 전화번호부—에 불과하다. 어디에 무엇이 있는지는 알지만, 무엇이 무엇을 부르는지는 모른다.
이 문제의 해법은 레포 전체를 그래프 자료구조로 전환하는 것이다. 각 도메인을 노드로, 실제 import 관계를 엣지로 삼는 인접 리스트 구조의 AI_INDEX.md를 만들면, BFS(너비 우선 탐색) 알고리즘으로 변경의 영향 범위를 코드 한 줄 작성하기 전에 추적할 수 있다. 여기에 LSP(Language Server Protocol)를 결합하면 grep의 문자열 매칭 대신 언어 타입 체커가 직접 참조를 찾아준다—같은 쿼리로 토큰 비용은 20분의 1, 정확도는 제로 오탐이다. /trace-impact 커맨드 하나로 변경이 닿는 모든 경로를 레벨별로 펼쳐볼 수 있는 구조가 완성된다.
병목 2: AI는 당신의 '의도'를 모른다
"사용자 인증 추가해줘"라고 입력하면 AI는 선택한다. OAuth냐 이메일/패스워드냐, 세션이냐 JWT냐, 미들웨어 위치는 어디냐. 문제는 이 선택들이 코드가 존재한 이후에야 드러난다는 것이다. Andrej Karpathy가 '바이브 코딩'을 명명한 2025년 초부터 데이터가 쌓이기 시작했고, 결과는 냉혹했다. 숙련된 개발자가 AI 도구를 쓸 때 실제 코드베이스에서 19% 더 느려졌고, AI가 공동 작성한 PR은 주요 이슈가 1.7배 더 많았다. 모델이 더 좋아진다고 해결되지 않는다. 모델은 처음부터 당신의 의도를 갖고 있지 않았으니까.
autospec이 제안하는 해법은 스펙 중심 개발 워크플로우다. spec → plan → tasks → implement 순서를 강제하고, 각 단계 산출물을 마크다운이 아닌 스키마 검증 가능한 YAML로 만든다. spec.yaml에는 사용자 스토리, 인수 조건, 엣지 케이스, 범위 외 항목이 명시된다. "OAuth는 이번 범위 밖"이라는 문장 하나가, 나중에 생길 수많은 오해를 차단한다. 더 중요한 것은 constitution.yaml—프로젝트의 불변 원칙(테스트 우선, 성능 기준, 에러 포맷 등)을 우선순위와 강제 메커니즘까지 명시한 문서—이 모든 AI 세션에 주입된다는 점이다. AI가 팀의 컨벤션을 모르는 채로 동작하는 문제를 구조적으로 차단한다.
또 하나의 실용적 이점은 비용이다. 38개 태스크 기준, 전체 컨텍스트를 매번 넣는 방식 대비 83% 비용 절감이 보고됐다. 페이즈별 격리된 컨텍스트 윈도우를 쓰기 때문에, 4단계 작업도 1단계와 같은 선명도로 실행된다.
병목 3: 의존성 순서 없이는 통합이 깨진다
LoginForm이 UserAuthService에, UserAuthService가 User 도메인에, User가 AuthStatus 열거형에 의존한다면—이 순서를 어기고 코드를 생성하면 통합은 반드시 깨진다. ISL(Intent Specification Language) 빌드 파이프라인은 이 문제를 컴파일러의 논리로 푼다. 스펙 파일 전체를 스캔해 DAG(방향 비순환 그래프)를 구성하고, 위상 정렬로 생성 순서를 결정한다. npm이나 cargo가 패키지를 설치하는 방식, Make가 빌드 타깃을 처리하는 방식과 동일한 원리다.
여기서 핵심은 dep.sign.ts의 역할이다. 스펙 문서(ref.md)가 아니라 실제 생성된 코드의 시그니처를 다음 컴포넌트에 입력으로 넘긴다. LLM이 스펙과 미묘하게 다른 관용적 표현을 선택했더라도, 다운스트림 컴포넌트는 현재 실제로 존재하는 인터페이스에 맞춰 컴파일된다. 통합 불일치를 구조적으로 제거하는 것이다. 파이프라인 마지막에는 Auditor가 논리적 사각지대—isLoading 플래그가 세팅되지만 CATCH 블록에서 리셋되지 않는 경우 등—를 PR이 열리기 전에 잡아낸다.
세 전략이 가리키는 하나의 방향
세 사례를 관통하는 공통 원리는 명확하다. AI를 창의적 협업자가 아니라 정밀한 컴파일러로 대우하라. 코드베이스를 그래프로 만들어 탐색 가능하게 하고, 의도를 스펙으로 외재화해 검증 가능하게 하고, 의존성을 위상 정렬로 처리해 통합을 결정론적으로 만드는 것—이 세 가지는 모두 AI의 출력 품질을 높이는 방법이 아니라, AI가 처리할 입력의 구조를 설계하는 방법이다.
프론트엔드 개발자 관점에서 시사점은 더 구체적이다. 컴포넌트 트리, 상태 흐름, API 경계—이미 우리가 다루는 시스템은 본질적으로 그래프다. AI 도구를 '빠른 자동완성'으로 쓰는 것과 '설계 파트너'로 쓰는 것의 차이는, 이 구조를 AI가 읽을 수 있는 형태로 명시화했느냐에 달려 있다. 더 좋은 프롬프트를 고민하기 전에, 더 좋은 구조를 설계해야 할 시점이다.