AI 코딩의 다음 병목 구간은 레포지토리 이해도입니다

현재 AI 코딩 에이전트가 할 수 있는 일 중 가장 흥미롭지 않은 것은 코드를 생성하는 것입니다.

제가 의도한 것보다 말이 다소 거칠게 들릴 수도 있습니다. 생성(Generation)은 여전히 중요합니다. 더 나은 모델도 여전히 중요합니다. 더 빠른 편집도 여전히 중요합니다. 하지만 파일이 세 개뿐이고 히스토리도 없는 데모 레포지토리(demo repo)가 아닌, 실제 코드베이스(codebase)에서 이러한 도구들을 사용해 보았다면, 여러분은 이미 고통의 지점이 어디로 이동했는지 알고 있을 것입니다.

병목 구간은 "모델이 React 컴포넌트를 작성할 수 있는가?"가 아닙니다.

병목 구간은 "에이전트가 이 레포지토리가 왜 이상한지 이해하고 있는가?"입니다.

실제 레포지토리들은 기이한 것들로 가득 차 있습니다. 아무도 문서화하지 않은 명명 규칙(Naming conventions), 마이그레이션(Migration)의 잔재, 정치적 역사가 담긴 피처 플래그(Feature flags), 단 한 번의 처절한 운영 사고 때문에 존재하는 테스트들, 그리고 제거했다가는 결제 시스템을 망가뜨릴 수도 있는 우연해 보이는 API 경계들까지. 유용한 변경 사항과 자신감 넘치는 엉망진창을 가르는 수백 가지의 사소한 사실들이 존재합니다.

코딩 에이전트들은 파일을 편집하는 능력은 훨씬 좋아지고 있습니다. 다음 단계의 스택은 편집이 시작되기 전에 시스템을 읽기 쉽게(legible) 만드는 능력이 더 좋아져야 합니다.

더 큰 컨텍스트 윈도우(Context windows)가 이해와 동일한 것은 아니다

게으른 답변은 모델에게 더 많은 컨텍스트(Context)를 던져주는 것입니다.

레포지토리 전체를 줍니다. README를 추가합니다. 문서(docs)를 추가합니다. 최근 5개의 티켓(tickets)을 추가합니다. 아키텍처 결정 기록(architecture decision records)을 추가합니다. 이전 세션의 트랜스크립트(transcript)를 추가합니다. 테스트 출력값을 추가합니다. 그냥 하는 김에 package lock 파일도 추가합니다.

그것은 작동하다가, 어느 순간 작동하지 않게 됩니다.

더 큰 컨텍스트 윈도우는 더 많은 텍스트를 담을 수 있습니다. 하지만 그것이 자동으로 그 텍스트를 지도(map)로 바꾸어 주지는 않습니다. 어떤 파일이 아키텍처 경계이고 어떤 것이 부수적인 래퍼(wrappers)인지 자동으로 알지 못합니다. 레포지토리에 명확하게 명시되어 있지 않는 한, 특정 디렉토리가 더 이상 사용되지 않는(deprecated) 상태라는 것도 알지 못합니다. 무섭게 생긴 검증(validation) 브랜치가 2021년의 파트너 통합(partner integration)을 보호하고 있다는 사실도 알지 못합니다.

더 많은 컨텍스트는 오히려 문제를 악화시킬 수도 있습니다. 에이전트가 모든 것을 보았다는 기분 좋은 착각을 불러일으키는 동안, 유용한 신호(signal)는 가공되지 않은 파일 덤프와 오래된 노트 아래에 파묻혀 버립니다.

레포지토리 이해(Repo understanding)에는 구조가 필요합니다.

그렇기 때문에 코드베이스를 그래프 (graphs), 도메인 맵 (domain maps), 가이드 투어 (guided tours), 시맨틱 검색 인터페이스 (semantic search surfaces), 그리고 차이점 영향도 뷰 (diff-impact views)로 변환하는 도구들이 올바른 방향처럼 느껴지는 것입니다. 특정 제품이 무엇인지는 패턴만큼 중요하지 않습니다. 즉, 레포지토리를 결정론적으로 파싱 (parse)하고, 의도적으로 요약하며, 인간과 에이전트 (agents)가 모두 검사할 수 있는 아티팩트 (artifact)를 생성하는 패턴이 중요합니다.

마지막 부분이 중요합니다. 만약 레포지토리 맵이 단순히 숨겨진 프롬프트 연료 (prompt fuel)에 불과하다면, 그것은 또 다른 마법 상자 (magic box)일 뿐입니다. 하지만 그것이 팀이 검토하고, 갱신하며, 수정할 수 있는 파일, 그래프, 가이드 또는 생성된 아티팩트라면, 그것은 엔지니어링 시스템 (engineering system)의 일부가 됩니다.

에이전트 스택은 점점 채팅 형태를 벗어나고 있습니다

초기 코딩 에이전트 (coding-agent) 이야기는 주로 모델 (model)에 관한 것이었습니다.

어떤 모델이 코드를 더 잘 작성하는가? 어떤 모델이 지시 사항을 더 잘 따르는가? 어떤 모델이 경로를 이탈하지 않고 더 큰 변경을 수행할 수 있는가?

이것은 여전히 유용하지만, 무게 중심이 이동하고 있습니다. 이제 본격적인 작업은 하네스 (harness) 주변에서 이루어집니다: 기술 (skills), 플러그인 (plugins), 명령 (commands), 커넥터 (connectors), 권한 (permissions), 모델 전환 (model switching), 할당량 가시성 (quota visibility), 도구 실행 (tool execution), 그리고 워크스페이스 상태 (workspace state) 등이 그것입니다.

이러한 변화는 최신 터미널 에이전트 (terminal-agent) 워크플로우에서 확인할 수 있습니다. CLI는 더 이상 단순히 셸 (shell) 옆에 있는 텍스트 상스가 아닙니다. 그것은 운영 표면 (operating surface)이 되어가고 있습니다. 컨텍스트 (context)를 추적하고, 명령을 노출하며, 모델을 전환하고, 서비스에 인증합니다. 또한 개발자가 모델을 제품의 전부라고 가정하는 대신, 모델 주변의 환경에 대해 생각하도록 만듭니다.

가장 유용한 에이전트 동작은 누군가가 붙여넣는 것을 기억해야 하는 완벽한 프롬프트 (prompt) 안에 머물러서는 안 됩니다. 그것은 내구성이 있는 팀 인프라 (team infrastructure) 안에 존재해야 합니다.

팀에 마이그레이션 규칙 (migration rule)이 있다면, 에이전트가 사용할 수 있는 곳에 기록하십시오. 레포지토리에 테스트 의식 (testing ritual)이 있다면, 그 의식을 실행 가능하게 만들거나 최소한 명시적으로 만드십시오. 프론트엔드에 디자인 규칙이 있다면, 모델이 스크린샷으로부터 취향을 추론하기를 바라지 마십시오. 보안 검토에 타협할 수 없는 사항이 있다면, 검사 가능한 지침으로 패키징하십시오.

프롬프트는 저렴합니다. 설치된 동작 (installed behavior)이야말로 레버리지 (leverage)가 발생하는 지점입니다.

그것이 바로 검토가 필요한 이유이기도 합니다.

기술(Skills)과 플러그인(plugins)은 결과가 수반되는 레포지토리 컨텍스트(repo context)입니다

저는 기술(skill) 및 플러그인(plugin) 시스템의 방향성을 지지합니다. 왜냐하면 이 시스템들은 개발자들이 이미 알고 있는 사실, 즉 모든 팀은 고유한 로컬 운영 절차(local operating procedure)를 가지고 있다는 점을 인정하기 때문입니다.

모델은 범용적(generic)이지만, 작업은 그렇지 않습니다.

어떤 레포지토리는 보수적인 의존성 업그레이드(dependency upgrades)를 원합니다. 다른 곳은 공격적인 리팩터링(refactors)을 원합니다. 어떤 팀은 아주 작은 PR을 선호하는 반면, 다른 팀은 완전한 수직적 슬라이스(vertical slices)를 원합니다. 어떤 제품은 접근성(accessibility)을 릴리스 차단 요소(release blocker)로 취급합니다. 또 다른 곳은 이를 최선(best-effort)의 체크리스트로 유지하는데, 이는 별개의 문제이긴 하지만 여전히 실질적인 팀의 행동 양식입니다.

이러한 선호 사항들이 채팅(chat) 안에만 머물러 있다면, 그것들은 사라져 버립니다. 하지만 그것들이 기술(skills), 플러그인(plugins), 명령(commands), 또는 레포지토리 로컬 가이드(repo-local guidance)가 되면, 그것들은 복리로 작용(compound)합니다.

그것이 유용한 부분입니다.

위험한 부분 또한 동일한 문장입니다.

그것들은 복리로 작용합니다.

잘못된 기술(skill)은 매번 실행되는 나쁜 습관으로 변할 수 있습니다. 오래된 컨벤션(convention)은 코드베이스가 변경된 지 몇 달이 지난 후에도 새로운 작업을 계속 잘못된 방향으로 이끌 수 있습니다. 잘못된 가정을 연결하는 플러그인(plugin)은 누군가 알아차리기 전에 수십 번의 세션(sessions)을 조용히 형성할 수 있습니다.

따라서 검토(review)의 대상이 달라집니다. 우리는 더 이상 생성된 코드만을 검토하는 것이 아닙니다. 우리는 그 코드를 만들어낸 설치된 행동 양식(installed behavior)을 검토하고 있는 것입니다.

이는 다음과 같은 지루한 질문들이 중요해짐을 의미합니다.

이 레포지토리 가이드의 소유자는 누구인가?
이 아키텍처 맵(architecture map)은 언제 갱신되었는가?
에이전트(agent)가 자신이 어떤 규칙을 따랐는지 설명할 수 있는가?
팀이 기술(skills)과 워크플로(workflows)의 변경 사항을 차이점 분석(diff)할 수 있는가?
오래된 컨텍스트(stale context)가 만료될 수 있는가?
사람이 벡터 스토어(vector store)를 역공학(reverse-engineering)하지 않고도 맵을 수정할 수 있는가?

이 지점에서 AI 코딩은 자동 완성(autocomplete)처럼 보이는 것을 멈추고, 운영 업무(operations work)처럼 보이기 시작합니다.

병렬 에이전트(Parallel agents)는 이해(understanding)를 운영 문제로 만듭니다

에이전트 하나가 레포지토리를 오해하는 것은 짜증 나는 일입니다.

다섯 개의 에이전트가 병렬로 레포지토리를 오해하는 것은 워크플로 장애(workflow incident)입니다.

병렬 에이전트 제품(Parallel agent products)이 흥미로운 이유는 다음 단계의 고통을 드러내기 때문입니다. 에이전트들이 서로 다른 워크스페이스에서, 서로 다른 브랜치를 건드리며 동시에 실행될 수 있게 되면, 인간에게는 컨트롤 플레인(control plane)이 필요해집니다. 무엇이 실행되고 있는가? 무엇이 변경되었는가? 어떤 세션이 여전히 토큰을 태우고 있는가? 어떤 디프(diff)가 준비되었는가? 어떤 에이전트가 권한 경계(permission boundary)에 부딪혔는가? 이 녀석은 어떤 로컬 서버를 사용하고 있는가?

재미있는 점은, 이 문제가 사실 AI에 관한 것이 아니라는 사실입니다.

이것은 오래된 소프트웨어의 진리입니다: 동시성(concurrency)은 조정 비용(coordination cost)을 발생시킵니다.

에이전트는 그 비용을 제거하지 않습니다. 단지 옮길 뿐입니다. 때로는 그 비용을 배가시키기도 합니다.

Git 격리(isolation)가 도움이 됩니다. 세션 대시보드(session dashboards)가 도움이 됩니다. 디프 리뷰(diff review)가 도움이 됩니다. 알림(notifications)이 도움이 됩니다. 수동적 가시성(passive visibility)이 도움이 됩니다. 하지만 그 어떤 것도 '이해(understanding)'를 대체할 수는 없습니다. 그것들은 작업 단위들이 레포지토리(repo)에 대한 공유된 관점에 기반할 때에만 유용해집니다.

그렇지 않으면 컨트롤 플레인은 여러 에이전트가 그럴듯한 헛소리(plausible nonsense)를 생산하는 것을 지켜보는 더 예쁜 방법이 될 뿐입니다.

HN의 회의론은 유용한 경고 라벨입니다

개발자 토론에서는 코딩 에이전트가 프레임워크 스택(framework stack)의 큰 부분을 대체할 수 있다는 주장이 반복적으로 나옵니다. 그 매력은 이해합니다. 만약 에이전트가 글루 코드(glue code)를 생성할 수 있다면, 아마도 더 적은 추상화(abstractions)가 필요할지도 모릅니다. 아마도 제품에 더 가까운 코드를 작성할 수 있을지도 모릅니다. 아마도 스캐폴딩(scaffolding)은 일회용이 될 수도 있습니다.

그럴지도 모릅니다.

하지만 그 토론의 회의적인 측면이야말로 팀들이 벽에 붙여두고 명심해야 할 부분입니다.

빠른 스캐폴딩은 프로덕션 엔지니어링(production engineering)과 같지 않습니다. 프로덕션 시스템에는 숨겨진 제약 조건들이 있습니다: 데이터 무결성(data integrity), 권한(permissions), 마이그레이션(migrations), 남용 사례(abuse cases), 감사 로그(audit logs), 속도 제한(rate limits), 이상한 고객들, 망가진 통합(broken integrations), 그리고 여전히 돈이 흐르고 있기 때문에 여전히 중요한 오래된 결정들 말입니다.

그러한 제약 조건을 이해하지 못하는 에이전트는 당신을 프레임워크로부터 해방시켜 주는 것이 아닙니다. 그저 가드레일(guardrails)을 우회하여 생성하고 있을 뿐입니다.

기능의 첫 80퍼센트까지는 그것이 놀랍게 느껴질 수 있습니다. 그러다 마지막 20퍼센트가 이자가 붙어 찾아옵니다.

이것이 바로 레포지토리 이해도 (repo understanding)가 승수 (multiplier)인 이유입니다. 이는 에이전트가 국소적 타당성 (local plausibility)을 최적화하기 시작하기 전에 시스템의 전체적인 형태를 파악할 수 있도록 돕습니다.

새로운 에이전트를 추가하기 전에 내가 개선할 것들

만약 어떤 팀이 나에게 내일 당장 코딩 에이전트를 더 유용하게 만드는 방법을 묻는다면, 나는 새로운 모델 구독부터 시작하지 않을 것입니다.

나는 레포지토리의 표면 (repo surface)부터 시작할 것입니다.

누락된 지도를 작성하십시오. 계속해서 위반되고 있는 경계 (boundaries)를 문서화하십시오. 암묵지 (tribal knowledge)를 일반 파일로 전환하십시오.