24P by GN⁺ 2일전 | ★ favorite | 댓글 3개
  • 대규모 프로덕션 코드베이스에서 최신 언어 모델로 성과를 내기 위한 컨텍스트 엔지니어링 원칙과 실무 워크플로우를 제시하는 글
  • 핵심은 Frequent Intentional Compaction으로, 개발 전 과정에서 컨텍스트를 구조화·압축해 에이전트의 판단 품질과 진행 트래젝터리를 안정화함
  • 연구→계획→구현의 3단계로 사전 연구 산출물과 계획 문서를 만들고 사람 검토를 고레버리지 지점에 배치해 슬롭(slop) 과 재작업을 줄임
  • 실제로 Rust 기반 30만 LOC의 BAML에서 버그 수정취소/WASM 지원 등 복잡 과제를 단기간에 달성한 사례를 통해 브라운필드 환경에서도 유효함을 입증함
  • 결론적으로 AI 코딩은 장난감이 아니라 정교한 엔지니어링 수공업이며, 팀 차원의 프로세스/문화 전환이 경쟁우위의 관건임

배경: 복잡한 코드베이스에서의 AI 한계와 문제의식

  • 대부분의 개발자들은 AI 코딩 도구가 실제 프로덕션 코드베이스에서는 기대만큼 잘 작동하지 않는다는 점을 잘 알고 있음
  • AI 코딩 도구가 대형 코드베이스와 복잡 과제에서 생산성을 떨어뜨린다는 연구 결과가 존재함
    • Stanford 연구 결과, AI 도구가 추가하는 코드의 상당 부분이 이전에 AI가 생성한 미흡한 코드를 다시 손보는 식으로 반복 작업을 초래
    • AI 코딩 에이전트는 신규 프로젝트나 소규모 변경에는 효과적이지만, 대규모 코드베이스에서는 오히려 개발자 생산성을 낮출 수 있음
    • 그래서 현장의 반응은 “지금은 어렵다, 좀 더 똑똑한 모델이 나오면”이라는 신중한 태도를 보이는 경우가 많음
  • 하지만 실제 300,000 LOC의 대형 Rust 코드베이스에서 컨텍스트 엔지니어링을 적용해보니, 기존 모델만으로도 생산성과 품질 모두 시장 수준을 넘어설 수 있었음
    • 핵심은 빈번한 의도적 축소(frequent intentional compaction) 로, 개발 과정 내내 AI에 주어지는 맥락을 구조화되고 관리된 형태로 만드는 것
    • 결국 ‘AI 코딩’이란 기술적 장인정신이 필요한 영역임

사상적 토대: “Specs are the new code”와 생산성 연구

  • AI Engineer 2025에서의 두 가지 발표가 사고방식 변화를 이끌었음
  • Sean Grove의 "Specs are the new code" 발표에서 “대화형 프롬프트를 버리고 스펙을 코드로 보존하라”고 얘기함
    • 프롬프트를 버리고 산출 코드만 커밋하는 관행은 소스 없이 바이너리만 체크인하는 일에 비유됨
  • 스탠포드의 AI가 개발자 생산성에 미치는 영향 연구 는 AI가 단기 산출을 늘려도 품질 저하와 재작업으로 순효과가 감소할 수 있음을 시사함
    • 10만 개발자의 커밋 분석 결과, AI 도구가 재작업 증가를 초래해 생산성 이득을 상쇄하는 현상 관찰
    • 그린필드에서는 효과적이나 브라운필드고난도 작업에서 역효과가 빈번하다는 통찰 제시

원칙: Frequent Intentional Compaction의 개념

  • 컨텍스트 윈도우를 항상 40–60% 수준으로 관리하며, 내용 과잉·누락·오정보를 최소화하는 지속 압축 전략을 채택함
    • 압축 대상은 파일 검색 로그, 코드 흐름 추적, 수정 내역, 테스트/빌드 로그, 대형 JSON 등의 노이즈임
  • 각 단계 산출물을 구조화 아티팩트로 남겨 다음 턴의 입력 품질을 보장함
    • 예: 진행 요약, 목표와 접근, 완료 단계, 현재 실패 지점을 기록한 progress 문서 생성

워크플로우: Research → Plan → Implement

  • Research 단계에서 관련 파일·흐름·원인 가설을 조사해 요약 리서치 문서를 산출함
    • 필요시 서브에이전트로 신선한 컨텍스트에서 범위 탐색과 요약을 수행함
  • Plan 단계에서 수정 대상 파일, 변경 방식, 검증·테스트 절차를 상세히 서술한 구현 계획을 작성함
    • 계획은 코드리뷰보다 고레버리지 검토 지점으로 활용됨
  • Implement 단계에서 계획을 단계적으로 집행하고, 각 단계 검증 후 계획 문서에 상태를 재압축해 누적함
    • 복잡 과업은 단계별 합류 시마다 컨텍스트 재정렬을 수행함

안티패턴과 점진적 고도화

  • 나이브한 접근은 채팅형 흐름에서 컨텍스트가 오염되어 사과 루프나 탈선으로 이어지는 문제 노출
    • 약간 나은 방식은 세션 초기화와 “지시 추가 프롬프트”이나, 근본적 노이즈 제어가 미흡함
  • 의도적 압축은 진행 요약(파일)과 커밋 메시지를 사용해 맥락을 재구성하는 더 나은 방식임
    • 이상적 압축 산출물 포맷 예시를 제시하며, 정확성/완전성/크기/트래젝터리 최적화를 목표로 설정함

컨텍스트 최적화의 기술적 관점

  • LLM은 무상태 함수이므로, 품질은 전적으로 입력 컨텍스트에 의해 좌우됨
    • 최악의 상황 순서는 오정보 > 누락 > 노이즈 과다
  • 컨텍스트는 작을수록 유리하므로, 최소 입력으로 최대 정합성을 얻는 압축이 핵심임
    • 간단 루프형 에이전트 실행 전략(예: “Ralph” 프로세스) 등 대안적 관점도 언급됨

서브에이전트의 역할: 사람역할 놀이가 아닌 컨텍스트 제어

  • 서브에이전트는 찾기/요약/정리를 독립 컨텍스트에서 수행해 주 에이전트의 창을 청결히 유지함
    • 이상적 응답은 목표/현황/경로가 구조화된 압축 산출물 형태로 반환됨
  • 서브에이전트를 통해 탐색 비용을 국소화하고, 본 작업 컨텍스트의 집중도를 높임

사례 1: BAML 버그 수정 한 번에 통과

  • Rust 30만 LOC의 BAML에서 초진입자가 버그 수정 PR을 수시간 내 제출·승인 받은 사례 제시
    • 리서치 문서를 여러 번 돌려 품질을 끌어올리고, 최종 계획 기반 구현으로 첫 통과 달성
  • 브라운필드 적합성, 슬롭 제거, 정렬 유지 측면 목표 중 다수를 충족함

사례 2: BAML에 취소/WASM 지원 35k LOC

  • 두 사람이 7시간취소 기능WASM 컴파일 지원을 추가하는 대규모 변경 작업을 시연함
    • 팀 추정치로 각 3–5일 분량을 리서치/계획/구현 파이프라인으로 단축함
  • 일부 PR은 즉시 병합, 일부는 작동 데모 수준으로 개방 유지하며 고난도 과제 해결 가능성을 증명함

한계와 실패로부터의 학습

  • Parquet Java에서 Hadoop 의존 제거 시도는 의존 트리 파고들기 미흡으로 실패 사례로 남음
    • 결론: 모든 문제가 7시간 프롬프트링으로 풀리지는 않으며, 도메인 전문가의 참여가 필요함
  • 사람 검토의 레버리지는 연구>계획>코드 순으로 커지며, 잘못된 연구 한 줄이 수천 줄 오류로 확장될 위험 존재함

팀 정렬을 위한 문서 우선주의

  • 코드리뷰의 본질은 정신적 정렬(mental alignment) 유지에 있다는 관점 제시
    • 대형 PR 연쇄는 팀의 제품 이해 상실과 불안을 유발하므로, 스펙/계획/리서치로 정렬 비용을 낮춤
  • 엔지니어는 2천 줄 코드보다 200줄 계획 문서를 더 자주·정확히 읽을 수 있음
    • 낯선 영역 이슈 대응에서도 리서치 프롬프트가 빠른 안내 역할을 수행함

총정리와 비용 구조

  • 목표 전부를 충족: 브라운필드 호환, 복잡 문제 해결, 슬롭 최소화, 팀 정렬 유지 달성임
    • 운영 비용 관점에서 팀 3명이 Opus 토큰 비용 월 약 $12k 수준으로 운용 중임
  • 예외는 존재하나, 전반적으로 작동하는 방법론으로 자리잡았음을 강조함

앞으로의 변화와 제품화

  • 코딩 에이전트는 상품화될 것이며, 조직·워크플로우 변혁이 진짜 난제임
    • AI가 코드 99%를 작성하는 세계에서 협업 방식 전면 개편이 경쟁력의 분기점임
  • 이를 지원하기 위해 CodeLayer라는 “포스트 IDE” 도구를 프라이빗 베타로 공개
    • Superhuman for Claude Code를 지향하며 스펙 퍼스트 에이전틱 개발을 가속화함

CodeLayer라는 서비스 소개로 마무리...

Hacker News 의견
  • 흥미로운 읽을거리였고 참신한 아이디어도 있었음. 하지만 이런 주장은 문제가 있다고 생각함. Sean은 AI가 발전해서 앞으로는 스펙 문서가 진짜 코드가 될 것이라고 예측했음. 앞으로 2년 안에 사람들이 IDE로 파이썬 파일을 확인하는 빈도가, 오늘날 사람이 어셈블리를 보기 위해 hex editor를 여는 빈도와 같을 것이라는 주장임. 자신은 처음엔 불편했지만, PR의 코드를 일일이 읽는 대신 테스트에 집중하고 스펙을 진짜 소스로 여기는 방식을 받아들이게 됐다고 함. 그러나 LLM의 비결정성(non-determinism) 문제로, 아무리 프롬프트를 잘 짜도 항상 합리적인 구현을 기대할 수 없음. 컴파일러는 결정적이고, 버그가 있다 해도 재현·디버깅이 되는데, LLM은 그렇지 않음

    • 주니어 개발자와 작업할 때도 구현이 어느 정도는 결정적임. 하지만 AI 모델에선 명확하게 지시해도 완전히 다른 구현이 반복적으로 나옴

    • 재미있는 점은 사실 스펙 문서 자체도 이미 비결정적이라는 점임. 누구나 오해할 수 없도록 requirements를 영어로 작성하려고 들면, 결국엔 프로그래밍 언어가 되어버림

    • "프롬프트가 완벽할 수 있지만, LLM이 합리적 구현으로 바꿔줄 보장조차 없다"는 우려에 동의함. 오히려 자연어로 작성한 프롬프트는 본질적으로 모호하고 불완전한 경우가 많음. 그래서 창의적 결과가 필요한 곳에선 좋은 방향이지만, 소프트웨어 요건 정의엔 자연어가 적합했다면 이미 소프트웨어 공학이 수십 년 전에 해결됐을 것임. LLM에 열광했으나, 이걸로 모든 문제를 해결하려 하는 것은 무리가 있다고 생각함. 요구사항 명세에 있어서는 예전의 형식 시스템, 수학적 검증 시도와 비슷하지만 아주 반대편에 있는 느낌임. 이 역시 부분 실패로 끝나더라도 소프트웨어 개발에 대한 새로운 인사이트를 줄 실험이라고 봄. 일부 도메인에선 진짜 가치가 생길테고, 다른 곳에선 완전히 버려질 수도 있음. 흥미로운 시대임

    • 사실 사람들이 명확하고 상세하게 기술적인 스펙이나 문서를 잘 쓰는 경우도 거의 없음. 그게 있더라도, 그게 2년 안에 대중화될 것 같지도 않음. 소프트웨어 엔지니어링을 정말 깊이 이해하는 기술 문서 작가가 실제로 코드는 안 보고 AI 에이전트에게 프롬프트만 잘 준다고 만족할까? 난 동의 못함. 전형적인 "엔지니어가 사람을 기계처럼 여기는" 사고방식에 가까움

    • "컴파일러 덕분에 빌드할 때마다 hex editor로 어셈블리를 볼 필요 없다"는 주장도, 물론 도구가 좋아진 덕이지만, 실제로 HPC 과학 연구 분야에선 컴파일러가 중요 루프 벡터화를 제대로 했는지 확인하려고 Intel VTune 등으로 어셈블리를 직접 뜯어보는 경우가 많았음

  • 두 개의 서로 다른 코드베이스에서 이런 패턴을 사용해봤음. 하나는 50만 줄짜리 apache airflow 대규모 모놀리식 레포였고, 다른 하나는 flutter로 처음부터 만드는 개인 사이드 프로젝트였음. flutter와 dart는 정말 모르는 분야였음. 그럼에도 이 방법이 효과 있음을 느꼈음. 그린필드 프로젝트는 거의 /create_plan만 돌려도 되고, 에이전트의 모든 지원을 활용할 수 있었음. 중요한 건 AI가 내놓는 문서들을 꼼꼼히 리뷰하는 것임. 내가 놓치고 걱정하는 엣지케이스를 다뤘는지, 기술 선택이 온당한지 직접 체크하면 됨. 예를 들어 sqlite 패턴을 깨고 postgres 추천하는 식으로 잘못된 의사결정이 있는지 바로 알 수 있음. 보통은 에이전트랑 직접 채팅하면서 플랜을 바로 수정할 수 있음. 회사에선 github copilot을 사용해야 해서 프롬프트를 좀 다르게 써야 했지만, 단계 간 의도적 요약(compaction)은 여전히 하고 있음. copilot이 claude code 처럼 서브 에이전트를 지원하진 않지만, 나름 생산성은 유지되고 있음.


    한 가지 개인적 경험도 공유하고 싶음. AI 코딩 지원 시대 직전, 내 일이 너무 지루해지고 있다는 생각에 심하게 우울했었음. 여러 레포와 팀, 사람의 성향 등 때문에 대규모 코드베이스 작업은 늘 잡무투성이였음. AI 코딩이 제일 좋았던 점은 이런 사소한 일거리들을 매끄럽게 다뤄준다는 거였음. 난 무언가 잘 작동하는 걸 만드는 데서 큰 보람을 느끼는데, 번번이 이런 잔일에 막혀 그 기쁨이 사라졌음. 이젠 꾸준히 좋은 결과를 내고, 스스로도 대견하다는 생각을 함

    • 내 경험을 나눠줘서 고마움. 시작할 땐 굉장히 불편했는데 적응되고 나니 다시는 이전 방식으로 돌아갈 수 없게 됨
  • 나는 대규모 코드베이스에서 작업할 때 사용하는 패키지를 만들었음 [GitHub.com/iambateman/speedrun]. 먼저 /feature로 기능 설명을 입력하면 코드베이스 분석을 시작하고, 질문을 던짐. 내가 답변하면 계획을 markdown 형식으로 작성함. 이 과정에서 8~10개의 markdown 파일이 생기고, 뭘 할지와 예시 코드까지 담겨 있음. 다음엔 "code critic" 단계로, 오류를 찾아내려 하지만 사실 60%는 틀림. 나는 이 피드백에서 엉뚱한 오류를 걸러냄. 이쯤 되면 내가 원하는 변경점과 기능 설명이 들어있는 깔끔한 폴더가 완성됨. 이제 Claude Code에게 “진행해”라고만 하면 단계별로 작업이 시작됨. 이 방식 덕분에 방향이 어그러지는 걸 막고, 결과물에 확신을 가질 수 있음. 이런 워크플로를 하루에 몇 번씩 대형 작업에 쓰고, 비교적 구체적 작업엔 평범한 Claude code만 씀. 꽤 효율적인 워크플로라고 생각함

    • 난 왜 이렇게 복잡한 과정을 거치고 싶어하는지 전혀 이해 못하겠음. LLM을 조금 참고만 하는 평범한 코딩이 이 방식보다 더 생산적이라고 생각함

    • LLM을 대규모 코드베이스에 쓸 때 큰 문제는 같은 실수를 반복한다는 점임. 각 작업별로 아키텍처 관련 결정을 어떻게 문맥 속에서 계속 추적하는지 궁금함

    • 정말 멋져 보임. 중간에 의사코드(pseudo code) 단계가 있는데, 실제로 사전에 워크플로나 프로세스 정의가 도움이 됐는지 궁금함. 또 각 파일을 100줄 이내로 유지하는 게 중요하다는 이야길 들었는데, 본인도 비슷하게 느꼈는지 궁금함

  • 이 글은 마치 내 Claude code에서 문맥(context) 관리에 완전히 포기한 순간을 타임캡슐처럼 남겨둔 듯함. 난 코드 각 파트마다 폴더로 스펙을 따로 만들어 기능별 로그를 담았음. 파이썬으로 API 서버 여러 서브시스템(계정, 알림, 구독 등)을 관리했음. 상황이 복잡해지면서, Claude가 비즈니스 로직을 제대로 파악하지 못하고 문맥 관리가 극도로 어려워졌음. 예를 들어 간단한 RBAC 시스템을 만들려고 할 때, 계정-프로필 관계를 설명하는 UML 다이어그램과 예시까지 줘야 그나마 기대한 대로 동작함

    • 그래서 우리가 research_codebase.md를 먼저 만들었던 게 결정적 이유라고 생각함. 제일 큰 고민은 "이 코드베이스를 우리가 맡게 됐는데, 구조를 모르면 모델에게 어떻게 작업을 시킬 수 있나?"임. AI가 주로 작성한 코드에선 두 가지 문제가 있음. 1) 코드가 익숙하지 않으면 플로우와 기능을 빨리 파악할 수 있도록 research 단계가 필요함 2) 거대한 PR 리뷰는 매우 고통스러운데, 계획(plan)이 바뀐 내용과 이유를 구조화해서 정리해줌. 참고로 Mitchell이 ampcode의 thread 공유 기능을 엄청 칭찬했는데, 이건 #2에 좋은 솔루션임 [https://x.com/mitchellh/status/1963277478795026484]
  • AI 활용에 대해 온갖 선언과 주장들이 넘치는데, 실제로 구체적인 과정이나 프롬프트를 공개하는 경우는 없음. 말로만 그럴싸하게 떠드는 건 쉽고, 진짜로 유용하려면 프롬프트 로그가 남겨져야 진짜임. AI가 생성한 커밋엔 어떤 프롬프트들이 적용됐는지 로그도 포함되어, 커밋 로그를 훑듯이 프롬프트 로그도 직접 따라가보며 코드 작성 과정을 알 수 있어야 함

  • 글쓴이가 35K 라인 코드를 7시간 만에 조사, 구현했다고 자랑하면서 실제로는 7일간 40개의 커밋이 남아있다고 함. 하루에 한 시간씩 한 건지 의문임. 그리고 가장 최근 커밋 중 하나가 "테스트 일부 무시"임이 웃김

    • 글을 더 읽어보면 이 부분 인정하는 내용이 있음. "취소 PR은 좀 더 손이 필요했지만, 하루 만에 엄청난 진전을 이뤘음"
  • "몇 주 뒤, @hellovai와 함께 BAML에 35k LOC를 추가해 취소 지원·WASM 컴파일 등 새 피처를 도입함. 기존 팀에서는 각 기능에 3~5일 걸릴 거라 예측했었음"이란 문장이 있던데, 그럼 선임 엔지니어가 하루에 4~6KLOC씩 작성할 거라고 생각한 건가?(genAI 이전에?)

    • 여기서 빠진 사실은 선임 엔지니어라면 실제론 2KLOC만에 해결했을 것이라는 점임

    • 그리고 사실 글쓴이도 다른 곳에서 이 작업이 실제로는 일주일 걸렸음을 인정함 https://news.ycombinator.com/item?id=45351546

  • "처음엔 불편했지만, PR의 모든 코드를 다 읽는 걸 포기하게 됐고, 테스트만 꼼꼼히 확인하게 됐다. 스펙이 진짜 소스가 됐다"는 부분에 전적으로 동의함. 우리의 역할은 구현 세부사항을 직접 작성하는 일이 아니라, 동작을 정의하고 검증하는 쪽으로 옮겨가고 있다고 느낌. 최근엔 S3-to-SFTP 파이썬 오퍼레이터에 재귀 업로드를 추가할 필요가 있었는데, 복잡한 경로 플래그가 많았음. 내 프로세스는 다음과 같았음 - 1) 기존 동작을 명확한 스펙(즉, 단위 테스트 통과시키며)으로 추출 2) 새 기능에 맞도록 스펙 확장 3) 문제와 테스트를 코딩 에이전트에게 전달. 결국, 옛 코드를 전혀 이해할 필요가 없다는 걸 깨달음. 내 초점은 새 코드가 스펙을 제대로 따르는지 여부뿐이었음. 앞으로의 미래에는 올바름을 검증하는 데 우리의 가치가 있을 것이고, 실제 코드는 에이전트가 알아서 처리하는 세부사항이 될 것임

    • "우리 역할이 구현 세부사항 작성에서 동작 정의 및 검증으로 옮겨간다"는 데 동의함. 사실 이게 주된 일 아니었나 싶기도 함. 고급 언어나 컴파일러, 다른 추상화 덕에 구현 세부 작성에 쓰는 시간은 꾸준히 줄어드는 추세임

    • "내 포커스는 새 코드가 스펙대로 동작하는지 여부"에 대해서 Postel의 법칙(Postel's Law)을 떠올림. 널리 쓰이는 시스템의 관측된 동작이 사실상 그 시스템의 공개 인터페이스 및 스펙이 되면서, 모든 그릇된 점과 구현 오류까지도 포함되기 마련임. 코드의 클라이언트 쪽이 스펙을 정말 잘 지키는지 테스트하고, 만약 편차가 있다면 이를 탐지해서 처리할 필요도 있음

    • Claude Plays Pokemon도 같은 점을 보여줬음. AI는 (뭔가 잘 동작하는지) 판단하는 데 약함. 오히려 계속 같은 데만 맴돎. 하지만, 사람이 중간중간 방향을 바로잡아주면 강력한 조합이 될 수 있음

    • 실제로 동작의 모든 면을 정의하려 든다면, 결국 코드를 거의 다 작성하는 셈임. PR에 있는 어떤 한 줄도 바로 의미가 파악 안 된다면, 아마 전체 동작을 충분히 정의하지 못한 것임

  • "앞으로 몇 년 안에 스펙 문서가 실제 코드가 되고, 파이썬 파일을 열어볼 일은 거의 없을 것이다"는 주장이 있었음. 이게 실현되려면 AI 코드 생성이 99.9% 정확해야 하며, 환각(hallucination)도 거의 없어야 함. 우리가 컴파일러를 믿고 어셈블리 코드를 안 보는 것은, 결과물이 항상 동일하고 오류가 없다는 확신이 있기 때문임(드물게 버그나 옵티마이제이션 이슈가 있긴 하지만 거의 한 번에 고쳐짐). 아직은, AI가 생성한 코드가 스펙(즉, 원래의 코드)과 달리 동작하면 결국 사람이 다시 고쳐야만 함

  • 구현을 쪼개 작업 단위별로 처리하거나 검토한다는 팁이 매우 인상적이었음.

    1. 기능 또는 버그 리포트를 기술적 구현 스펙으로 분해하고, 논리 분할(COT)을 활용
    2. 구현 스펙 검증 후 리뷰 피드백을 원래 프롬프트 에이전트에 전달, 수정·통합
    3. 구현 스펙을 실제 실행 계획으로 변환, 모듈별로 논리적으로 분할, 의존관계도 함께 확인
    4. 코딩 에이전트로 빌드, 테스트, 통합을 반복
    5. 필요하면 해당 피처 전체를 하나의 커밋으로 스쿼시함 이 프로세스는 복잡한 신규 기능 작업에서 유용했음. 검증이 더 필요하다면 각 단계에서 사람(HITL)을 개입시킬 수 있음. 대규모 코드베이스에서는 항상 ARCHITECTURE.md를, 대형 모듈엔 DESIGN.md를 유지할 것 추천함
    • 직장에선 시도 안 해봤지만, 사이드 프로젝트에선 새 기능을 브랜치로 만들고 CLAUDE에 최대한 상세한 프롬프트를 줌. 그러면 CLAUDE-feature.md를 만들어서 구현 계획과 지원 정보(코드베이스에서 접근 가능한 요소 등)도 정리함. 내가 봤을 때 파일에 빠진 점이나, 설명이 혼란스러운 게 있으면 추가 프롬프트로 보완함. 비교적 큰 프롬프트 사이에선 /reset하고, 다시 문서를 참조하게 하고, 반복적으로 개선함. 실제 구현할 때도 /reset 한 번 더 하고, 계획의 각 단계를 체크포인트마다 /reset 시키며 진척 상황을 문서에 업데이트하게 함. 대체로 충분히 괜찮게 돌아가긴 하지만, 직장에선 그다지 신뢰할까 싶음