AI가 복잡한 코드베이스에서 작동하게 만드는 방법

AI 코딩 도구들이 실제 프로덕션 코드베이스(production codebases)에서 어려움을 겪는다는 점은 꽤 널리 받아들여지는 사실인 것 같습니다. AI가 개발자 생산성에 미치는 영향에 대한 Stanford의 연구 결과는 다음과 같습니다:

• AI 도구에 의해 배포된 많은 "추가 코드(extra code)"는 결국 지난주에 배포된 형편없는 코드(slop)를 재작업하는 데 사용됩니다.
• 코딩 에이전트(Coding agents)는 새로운 프로젝트나 작은 변경 사항에는 훌륭하지만, 규모가 크고 이미 구축된 코드베이스에서는 종종 개발자의 생산성을 오히려 감소시킬 수 있습니다.

이에 대한 일반적인 반응은 "이것은 절대 작동하지 않을 것이다"라는 비관론과, "언젠가 더 똑똑한 모델이 나오면 가능할지도 모른다"라는 보다 신중한 입장 사이 어딘가에 있습니다.

몇 달간의 시행착오 끝에, 저는 핵심적인 컨텍스트 엔지니어링 (context engineering) 원칙을 수용한다면 오늘날의 모델로도 정말 멀리 갈 수 있다는 것을 발견했습니다.

이것은 또 다른 "생산성을 10배로 높여라"와 같은 홍보 문구가 아닙니다. 저는 AI의 과열된 분위기(ai hype machine)와 상호작용할 때 꽤 신중한 편입니다. 하지만 우리는 무엇이 가능한지에 대해 상당한 낙관론을 갖게 만드는 워크플로우(workflows)를 우연히 발견했습니다. 우리는 Claude Code가 30만 라인(300k LOC) 규모의 Rust 코드베이스를 처리하고, 일주일 치의 업무를 하루 만에 완료하며, 전문가 리뷰를 통과하는 코드 품질을 유지하도록 만들었습니다. 우리는 제가 "빈번한 의도적 압축 (frequent intentional compaction)"이라고 부르는 일련의 기술을 사용합니다. 이는 개발 프로세스 전반에 걸쳐 AI에 컨텍스트(context)를 제공하는 방식을 의도적으로 구조화하는 것입니다.

저는 이제 코딩을 위한 AI가 단순한 장난감이나 프로토타입용이 아니라, 매우 기술적인 엔지니어링 기술(engineering craft)이라는 점을 완전히 확신합니다.

비디오 버전: 비디오를 선호하신다면, 이 포스트는 8월 20일 Y Combinator에서 진행된 강연을 바탕으로 작성되었습니다.

AI Engineer 2025에서 발표된 두 개의 강연이 이 문제에 대한 저의 생각을 근본적으로 형성했습니다.

첫 번째는 "명세(Specs)가 새로운 코드다"라는 주제의 Sean Grove의 강연이며, 두 번째는 AI가 개발자 생산성에 미치는 영향에 대한 Stanford의 연구입니다.

Sean은 우리 모두가 *vibe coding(분위기 코딩)*을 잘못하고 있다고 주장했습니다. AI 에이전트와 두 시간 동안 채팅하며 원하는 것을 명시한 뒤, 모든 프롬프트는 버리고 최종 코드만 커밋하는 방식은... 마치 Java 개발자가 소스 코드는 버린 채 JAR 파일을 컴파일하고 컴파일된 바이너리만 체크인하는 것과 같습니다.

Sean은 AI가 주도하는 미래에는 명세(specs)가 실제 코드가 될 것이라고 제안합니다. 2년 뒤에는 오늘날 어셈블리(assembly)를 읽기 위해 헥스 에디터(hex editor)를 여는 빈도(대부분의 사람들에게는 거의 없는 일이죠)와 비슷한 빈도로 IDE에서 Python 파일을 열게 될 것이라는 뜻입니다.

개발자 생산성에 관한 Yegor의 강연은 이와는 다른(orthogonal) 문제를 다루었습니다. 그들은 10만 명의 개발자가 남긴 커밋을 분석했으며, 그 결과 다음과 같은 사실들을 발견했습니다.

• AI 도구는 종종 많은 재작업(rework)을 초래하여, 체감되는 생산성 향상을 저해한다.

• AI 도구는 그린필드(greenfield, 신규) 프로젝트에는 효과적이지만, 브라운필드(brownfield, 기존) 코드베이스와 복잡한 작업에는 종종 역효과를 낸다.

이는 제가 창업자들과 대화하며 들었던 내용과 일치했습니다.

• “너무 많은 슬롭(slop, 저질 코드/결과물).”
• “기술 부채 공장(Tech debt factory).”
• “대규모 저장소(repos)에서는 작동하지 않는다.”
• “복잡한 시스템에서는 작동하지 않는다.”

어려운 작업을 위한 AI 코딩에 대한 전반적인 분위기는 다음과 같습니다.

언젠가 모델이 더 똑똑해지면...

심지어 Amjad조차도 9개월 전 Lenny의 팟캐스트에 출연하여, PM(Product Manager)들이 Replit 에이전트를 사용하여 새로운 것을 프로토타이핑한 다음, 이를 엔지니어들에게 전달하여 프로덕션(production)용으로 구현하게 하는 방식에 대해 이야기했습니다. (주의: 저는 최근에 그를 따라잡지 못했으므로(사실 한 번도 못 봤습니다), 이 입장은 바뀌었을 수도 있습니다.)

제가

이 부분에 대해서는 나중에 더 자세히 파고들겠지만, 이것이 단순한 이론이 아님을 증명하기 위해 구체적인 사례를 개략적으로 설명하겠습니다. 몇 주 전, 저는 LLM(Large Language Models)과 함께 작동하는 프로그래밍 언어를 위한 30만 라인(300k LOC) 규모의 Rust 코드베이스인 BAML에 우리의 기술을 테스트해 보기로 했습니다. 저는 기껏해야 아마추어 Rust 개발자일 뿐이며, BAML 코드베이스는 이전에 한 번도 만져본 적이 없었습니다.

한 시간 정도 지나자, 저는 버그를 수정하는 PR(Pull Request)을 제출했고, 다음 날 아침 메인테이너(maintainer)로부터 승인을 받았습니다. 몇 주 후, @hellovai와 저는 BAML에 3.5만 라인(35k LOC)을 배포하기 위해 페어 프로그래밍을 진행하여 취소 지원(cancellation support)과 WASM 컴파일 기능을 추가했습니다. 이는 팀에서 시니어 엔지니어가 각각 3~5일이 걸릴 것이라고 예상했던 기능들이었습니다. 우리는 두 개의 초안 PR을 약 7시간 만에 준비했습니다.

다시 말씀드리지만, 이 모든 것은 우리가 '빈번하고 의도적인 압축(frequent intentional compaction)'이라고 부르는 워크플로우를 중심으로 구축되었습니다. 본질적으로는 컨텍스트 관리(context management)를 중심으로 전체 개발 프로세스를 설계하여, 활용률을 40~60% 범위로 유지하고, 정확히 적절한 시점에 영향력이 큰 인간의 검토(human review)를 포함시키는 방식입니다. 우리는 '조사, 계획, 구현(research, plan, implement)' 워크플로우를 사용하지만, 여기서 얻은 핵심 역량과 학습 내용은 특정 워크플로우나 프롬프트 세트보다 훨씬 더 일반적입니다.

저는 제가 만난 가장 생산적인 AI 코더 중 하나와 함께 작업하고 있었습니다.
그들은 며칠마다 2,000라인 규모의 Go PR을 쏟아냈습니다.
그리고 이것은 Next.js 앱이나 CRUD API가 아니었습니다. 이것은 유닉스 소켓(unix sockets)을 통해 JSON RPC를 수행하고, 포크된(forked) 유닉스 프로세스(대부분 claude code sdk 프로세스, 이에 대해서는 나중에 더 자세히 설명하겠습니다 🙂)로부터 스트리밍되는 stdio를 관리하는, 경합 조건(race-prone)이 발생하기 쉬운 복잡한 시스템 코드였습니다.

며칠마다 2,000라인의 복잡한 Go 코드를 주의 깊게 읽어야 한다는 아이디어는 지속 가능하지 않았습니다. 저는 ghostty에 AI 기여도를 공개해야 한다는 규칙을 추가했을 때의 Mitchell Hashimoto가 된 것 같은 기분이 들기 시작했습니다.

우리의 접근 방식은 sean의 **명세 기반 개발(spec-driven development)**과 같은 방식을 채택하는 것이었습니다.

처음에는 불편했습니다. PR 코드의 모든 줄을 읽는 것을 내려놓는 법을 배워야 했습니다. 저는 여전히 테스트 코드는 꽤 주의 깊게 읽지만, 명세(specs)가 무엇을 왜 구축하고 있는지에 대한 우리의 진실의 원천(source of truth)이 되었습니다.

이 전환 과정은 약 8주가 소요되었습니다. 저를 포함하여 관련된 모든 이들에게 믿기지 않을 정도로 불편한 과정이었습니다. 하지만 이제 우리는 매우 원활하게 작동하고 있습니다. 몇 주 전에는 하루에 6개의 PR(Pull Request)을 배포하기도 했습니다. 지난 3개월 동안 마크다운(markdown)이 아닌 파일을 수동으로 편집한 횟수는 한 손에 꼽을 정도입니다.

우리가 필요했던 것은 다음과 같습니다:

• 브라운필드 코드베이스(Brownfield Codebases)에서 잘 작동하는 AI
• 복잡한 문제를 해결하는 AI
• 슬롭(Slop, 저품질 결과물) 없음
• 팀 전체의 정신적 정렬(Mental Alignment) 유지

(그리고 네, 물론 가능한 한 많은 토큰을 사용하도록 해봅시다.)

저는 다음 내용들을 심도 있게 다룰 것입니다:

• 코딩 에이전트(coding agents)에 컨텍스트 엔지니어링(context engineering)을 적용하며 배운 점
• 이러한 에이전트를 사용하는 것이 매우 기술적인 숙련도를 요구하는 작업인 차원들
• 왜 이러한 접근 방식이 일반화될 수 없다고 믿는지
• (3)번에 대해 제가 반복적으로 틀렸음이 증명된 횟수

우리 대부분은 챗봇(chatbot)과 같은 코딩 에이전트를 사용하는 것으로 시작합니다. 문제에 대해 느낌(vibing)대로 대화(또는 취한 듯 소리치며)를 주고받다가, 컨텍스트(context)가 바닥나거나, 포기하거나, 혹은 에이전트가 사과하기 시작할 때까지 계속합니다.

약간 더 똑똑한 방법은 경로를 벗어났을 때 세션을 버리고 새로 시작하는 것이며, 아마도 프롬프트(prompt)에 약간 더 많은 조종(steering)을 가하는 것입니다.

[original prompt], 하지만 반드시 XYZ 접근 방식을 사용해줘, 왜냐하면 ABC 접근 방식은 작동하지 않을 것이기 때문이야

여러분은 아마 제가 "의도적 압축(intentional compaction)"이라고 부르게 된 작업을 해본 적이 있을 것입니다. 경로를 잘 가고 있든 아니든, 컨텍스트가 차오르기 시작하면 작업을 일시 중지하고 새로운 컨텍스트 창(context window)으로 다시 시작하고 싶을 것입니다. 이를 위해 다음과 같은 프롬프트를 사용할 수 있습니다.

"지금까지 우리가 진행한 모든 내용을 progress.md에 작성해줘. 최종 목표, 우리가 취하고 있는 접근 방식, 지금까지 완료한 단계, 그리고 현재 해결 중인 실패 사례를 반드시 기록해줘"

의도적 압축을 위해 커밋 메시지(commit messages)를 사용할 수도 있습니다.

무엇이 컨텍스트를 잡아먹는가?

• 파일 검색
• 코드 흐름(code flow) 이해
• 편집 적용
• 테스트/빌드 로그
• 도구로부터 생성된 거대한 JSON 블롭(blobs)

이 모든 것들은 컨텍스트 윈도우 (context window)를 가득 채울 수 있습니다. **압축 (Compaction)**은 단순히 이들을 구조화된 아티팩트 (artifacts)로 정제하는 것을 의미합니다.

의도적인 압축을 위한 좋은 출력 결과물에는 다음과 같은 것들이 포함될 수 있습니다.