이 글은 소프트웨어 팩토리가 실패하는 이유의 2부입니다*
이 글의 발표 영상은 YouTube에서 보실 수 있습니다: https://www.youtube.com/watch?v=Ib5GBkD555M
다시 불을 켜며
1부에서는 모델이 장기적으로 코드베이스 품질을 유지하는 데 신뢰할 수 없는 이유에 대해 깊이 다뤘습니다. 왜 아무리 하네스 엔지니어링이나 토큰 최적화를 해도 모델 훈련 및 벤치마크 문제를 해결할 수 없는지, 그리고 코드 품질 평가에 있어 "모델을 심판으로 삼는" 방식이 어떤 사람들이 말하는 것처럼 효과적이지 않은 이유에 대해 설명했습니다.
현재로서는 심판은 바로 여러분입니다. 그래서 우리는 코드 리뷰를 다시 도입할 것입니다.
우리는 AI 이전부터 해오던 바로 그 방식을 다시 받아들일 것입니다. 즉, 사전에 약간의 계획을 세워 길고 어려운 리뷰의 가능성을 줄이는 것입니다.
우리는 레버리지를 찾을 것이고, AI를 활용하여 이를 4단계에 걸쳐 도울 것입니다:
- 제품 요구 사항
- 시스템 아키텍처
- 프로그램 설계
- 수직 슬라이스
제품 리뷰
모든 것은 제품 리뷰에서 시작합니다: 우리가 무엇을 만들고 왜 만드는지 명확히 하는 짧은 문서입니다. 목표는 두 문장이나 긴 음성 메모의 횡설수설을 반구조화된 형태로 바꾸는 것입니다.
먼저, 해결해야 할 문제에 대해 의견을 맞춥니다. 즉, 사용자의 언어로 표현된 실제 사용자 불편입니다. 둘째, 성공의 모습을 정의합니다. 즉, 출시 후 무엇을 보고 이 기능을 만들 가치가 있었다고 판단할 수 있는지입니다. 이상적으로는 "XYZ 워크플로우를 더 짧은 시간에 수행할 수 있다" 또는 "온보딩 마일스톤 ABC에 더 빨리 도달한다"와 같은 사용자 결과입니다. 때로는 오류율이나 지연 시간과 같은 더 낮은 수준의 지표일 수도 있고, 때로는 "X에 대한 고객 지원 티켓이 중단된다"와 같은 것일 수도 있습니다.
우리는 이것을 제품 공간에 상당히 밀접하게 유지하려고 노력하며, 기술적인 부분으로 빠지지 않도록 합니다. 제품 세계와 기술 세계 양쪽에 발을 담그고 있는 사람으로서, 저는 여기서 종종 기술적인 세부 사항으로 빠져드는 자신을 발견합니다. 그럴 때는 그냥 나중 단계를 위해 메모해 두고 사용자가 실제로 경험하는 것으로 돌아가려고 노력합니다. 기술 결정이 제품 결정을 막고 있다면, 현재까지의 내용을 확정하고 아키텍처로 들어가거나 실현 가능한 것에 대한 더 많은 프로토타입 연구를 수행합니다.
그리고 대부분이 사용자가 보는 것에 관한 것이기 때문에, 저는 설명하지 않고 목업을 만듭니다. 실제 화면의 대략적인 HTML 목업 하나가 세 문단으로는 연장될 논란을 해결해 줍니다.
진행 중인 실제 사례입니다: 문서는 JSON 개요로 기능을 정의한 다음, 실제 화면의 두 가지 대략적인 HTML 목업을 보여줍니다:
https://x.com/dexhorthy/status/2078592010852982977
물론 모든 것이 제품 리뷰를 받는 것은 아닙니다. 텍스트 수정, 일회성 스크립트, 명백한 재현 방법이 있는 버그와 같은 경우에는 여전히 에이전트에 바로 원샷으로 전달합니다. 이 프로세스는 에이전트가 우리 의도를 오해할 때 비용이 많이 드는 변경 사항을 위한 것입니다.
이 시리즈의 모든 문서와 마찬가지로, 우리는 작성자 옵트인 리뷰를 수행합니다. 리뷰 시간을 절약하려면 PR을 검토할 사람을 선택하고, 문서 댓글을 통해 비동기식으로 제품/기술 사양을 함께 검토하세요 (우리는 이를 위해 HumanLayer를 사용하지만, GitHub/Notion/PlanNotator 등에서도 쉽게 할 수 있습니다).
시스템 아키텍처
제품 리뷰가 완료되면 시스템 아키텍처를 수행합니다. 이것은 특별히 새로운 것은 아니며, 바이브 코더들조차도 중요성을 인정하기 시작한 부분입니다.
리뷰 시간을 절약하려면 PR을 검토할 사람을 선택하고, 코딩 단계에 들어가기 전에 제품/기술 사양을 함께 검토하세요.
이 단계에서는 서비스, 엔드포인트, 스키마, 큐, 저장소가 서로 어떻게 통신하는지에 대해 프로그램 설계의 세부 사항으로 들어가지 않고 의견을 맞춥니다. 인간과 에이전트 간의 통신 대역폭을 최대화하기 위해 여기서는 시퀀스 다이어그램과 같은 시각화를 많이 사용합니다:
계약/엔드포인트 형태:
데이터 모델 및 변환:
Mermaid도 괜찮지만, 때로는 과도할 수 있고 의견이 일치했다는 잘못된 확신을 줄 수 있습니다. 아키텍처는 상당히 높은 레버리지를 가지며, 이 단계에서 차단할 수 있는 잠재적으로 나쁜 모델 습관이 많습니다. 하지만 고품질 코드를 생산하기에는 충분하지 않습니다. 이를 위해서는 프로그램 설계가 필요합니다.
프로그램 설계
아키텍처 후에 에이전트 코딩에서 극히 과소평가되었다고 생각하는 작업을 수행합니다: 프로그램 설계.
대부분의 사람들은 아키텍처가 올바르면 모델이 알아서 잘 해낼 것이라고 가정합니다. 그렇게 해도 되지만, 결과가 마음에 들지 않을 수 있습니다.
하지만 제가 보기에 효과가 좋은 것은,任何人(인간이든 에이전트든)이 구현을 작성하기 전에 아키텍처보다 한 단계 더 내려가 코드의 형태를 정의하는 것입니다: 타입, 메서드 시그니처, 프로그램 레이아웃, 콜 스택 등입니다.
프로그램 설계 스킬의 첫 번째 버전은 형편없었습니다. 읽기 어렵고 지루했습니다. Mermaid도 시도해 봤지만, 우리가 실제로 좋아하는 것은 의사 코드의 가벼운 시각화입니다:
콜 스택 트리: 오케스트레이션이나 제어 흐름 변경이 있을 때 사용합니다. 변경되는 부분이 중요할 때는 diff 구문을 사용합니다:
Dillon Mulroy는 계획 프로세스의 일부로 콜 그래프를 사용하는 것에 대해 이야기하는데, 저는 그것이 정확히 옳은 접근 방식이라고 생각합니다.
파일 트리 diff: 코드베이스의 레이아웃과 파일 위치를 파악하는 데 도움이 됩니다.
핵심 새 함수의 타입 및 메서드 시그니처: 아키텍처 문서에는 너무 내부적이지만 에이전트가 잘못 이해할 수 있는 부분입니다.
이러한 작업들은 생성하는 데 오래 걸리지 않으며(모델이 초안을 작성하고, 당신이 그것에 대해 논쟁합니다), 각각은 그렇지 않으면 코드 리뷰 중에 암묵적으로 내려야 할 결정입니다. 즉, 마음을 바꾸기에 가장 비용이 많이 드는 시점에 말이죠.
수직 슬라이스
다음으로 우리는 "수직 슬라이스"라고 부르는 것을 좋아합니다. Matt Pocock과 저는 2026년 1월 라이브 스트림에서 수직 슬라이스 또는 "트레이서 불릿"에 대해 이야기한 적이 있습니다. 이는 트레이서 불릿이라고도 불립니다.
모델은 제가 "수평 계획"이라고 부르는 것을 좋아합니다. 즉, 스택 순서대로 작업을 수행하는 것입니다:
- 데이터베이스 마이그레이션
- 서비스 레이어
- API
- 프론트엔드
실제로 이것이 의미하는 바는 진행하면서 솔루션을 실제로 "확인"할 방법이 없다는 것입니다. 코드로 테스트할 수는 있지만, 제가 만든 거의 모든 기능에 대해 테스트를 읽는 것은 시작일 뿐이었고, 작업 중에 브라우저에서 무언가를 띄우거나 curl로 요청을 보내는 것은 항상 작업 흐름의 빈번한 부분이었습니다.
AI 이전에는 누군가가 2000줄 이상의 코드 또는 500줄의 코드를 작성하면서 중간에 무언가를 확인하지 않는 경우는 드물었습니다.
제가 익숙했던 것과의 차이를 알아차리는 데 시간이 좀 걸렸습니다. AI 이전에 코드를 작성할 때, 저는 항상 중간에서 시작하여 바깥쪽으로 작업했습니다. 대략적으로:
- API 계약 생성 및 목업 데이터 제공, curl로 테스트
- 목업 데이터를 소비하는 프론트엔드 생성, 브라우저에서 반복 및 다듬기
- API를 서비스 레이어에 연결 (서비스는 목업 데이터/동작 제공)
- 데이터베이스 마이그레이션 추가, 서비스를 데이터베이스에 연결
- 비즈니스 로직 대량 추가
- 오류 처리 대량 추가
그리고 각 단계에서 테스트/반복/다듬기를 수행했습니다.
코드에 대해 많은 신경을 쓰거나 코드베이스의 이 부분에서 모델이 좋은 작업을 수행할 수 있을지 의심스럽다면, 각 단계에서 코드도 검토합니다. 100-200줄을 확인하고 방향을 수정하는 것이 훨씬 저렴합니다.
여기서는 그렇게 할 것입니다. 대부분의 최첨단 모델은 인간의 개입 없이는 이와 같은 계획을 설계하지 않으며, 코드베이스나 작업별로 일반화하기 어렵기 때문에 저는 여기서 루프에 남아 있는 것을 선호합니다. 저를 믿으세요. 만약 사고를 아웃소싱할 수 있었다면 이미 했을 것입니다.
30분의 계획이 몇 시간의 리뷰를 절약합니다
그래서 우리는 인간이 루프에 있어야 한다고 주장하는 몇 가지 단계가 있습니다. 만약 나중에 엄청난 양의 슬롭 코드를 정리하는 데 시간을 낭비하지 않고 인간 수준에 가까운 품질을 유지하려면 말입니다. (즉, 실제로 빠르게 진행하고 싶다면)
- 제품 설계
- 시스템 아키텍처
- 프로그램 설계
- 수직 슬라이스
물론 우리가 출시하는 모든 것에 대해 이 전체 프로세스를 수행하는 것은 아닙니다 (아래 사이드퀘스트 참조). 대략적인 분포는 다음과 같을 것으로 추정합니다:
- 작업의 약 40%는 원샷 또는 1-2회의 가벼운 피드백과 함께 원샷으로 처리됩니다.
- 중간 규모 작업의 경우, 제품/시스템 설계를 하나의 계획 문서에 모두 포함하고 작업을 단계로 나누지 않습니다.
- 대규모 작업의 경우, 모든 단계를 수행합니다. 대규모 리팩터링과 같이 제품 부분이 의미 없는 경우는 건너뜁니다.
그리고 대부분의 경우, 모델에 한 번에 1-3개의 슬라이스를 보내고 진행하면서 코드를 검토합니다. 내부 구조든 실제 기능이든 초기에 방향을 수정하는 것이 2천 줄 이상의 코드를 작성한 후에 무엇이 잘못되었는지 전혀 모르는 상태가 되는 것보다 훨씬 쉽습니다.
아마도 풀 리퀘스트가 너무 많다고 느끼실 겁니다
PR이 너무 많은 것이 아닙니다. 좋지 않은 PR이 너무 많은 것입니다.
AI 이전부터 우리 모두는 재작업이 필요한 많은 PR을 검토해 왔습니다.
하지만 훌륭한 PR은 검토하는 즐거움입니다. 모든 파일을 스크롤하면서 코드는 깔끔하고, 소프트웨어가 어떻게 되어야 하는지에 대한 모든 결정/논의/어렵게 얻은 의견을 따릅니다.
반면에, 풀 리퀘스트가 20%만 재작업이 필요하더라도(그리고 이것도 관대한 편입니다. 대부분의 AI 원샷 PR은 50%에 가깝다고 말하고 싶습니다), 그것은 제출자와 검토자 모두에게 지적 부담이자 정서적 부담입니다. (제출자가 AI라 할지라도, 누군가는 이 작업을 시작했거나 AI 결과를 다듬었거나, 최소한 결과에 관심이 있을 것입니다.)
시간을 절약해 드리기 위해 (거의 끝나갑니다), 사이드 퀘스트에서 이에 대해 더 자세히 이야기했습니다:
제약 조건 이론 (2026 에디션)
여기서 핵심 논제에 대해 약간 실망하기 쉽습니다: "지금으로서는 코드를 읽는 데 갇혀 있다."
저는 그냥 원하는 것을 요청하고 모델이 알아서 처리하게 두고 코드를 읽지 않아도 시간이 지나도 진화하고 망가지지 않는 아름다운 프로덕션 소프트웨어를 얻을 수 있는 세상에 대해 꽤 기대하고 있었습니다.
하지만 제가 여기서 최선을 다해 설명하려고 한 것은 다름 아닌 제약 조건들입니다. 모델은 어떤 것에는 능숙하고, 다른 것에는 그렇지 않습니다. 이러한 제약 조건 하에서 프로세스를 어떻게 최적화할 것인가?
모델은 어떤 것에는 능숙하고, 다른 것에는 그렇지 않습니다. 이러한 제약 조건 하에서 프로세스를 어떻게 최적화할 것인가?
10-100배 더 빠르게 움직이려고 너무 바빠서 코드 품질이 더 이상 중요하지 않다고 스스로를 설득하고 있을 수도 있습니다. 하지만 제약 조건을 받아들이고 2-3배 더 빠르고 안전하게 움직일 수 있습니다.
제가 드리는 마지막 조언은 기본적으로 다음과 같습니다:
- 제약 조건을 잘 이해하고, 모델과 많이 작업하면서 직관을 개발하세요.
- 이러한 제약 조건의 범위 내에서 시스템을 최적화하세요.
- 레버리지를 찾으세요.
- 코드를 읽으세요, 젠장.
그게 다입니다. 제안을 듣고 싶다면 계속 스크롤하세요. 이 글이 여러분이 재앙을 피하는 데 도움이 되거나, 적어도 귀여운 애니메이션들을 보면서 재미를 느꼈기를 바랍니다.
읽어주셔서 감사합니다
-dex
추신: 우리는 이것에 푹 빠져 있습니다
저희는 humanlayer.com을 구축하고 있습니다. 인간(또는 인간에 매우 가까운) 수준의 코드 품질을 유지하면서 2-3배 더 빠르게 움직일 수 있도록 돕는 에이전틱 IDE 및 협업 플랫폼입니다.
저희는 두 가지 아이디어를 향해 나아가고 있습니다: "소프트웨어 팩토리를 위한 빌딩 블록"과 "소프트웨어 유지보수성을 위한 더 나은 검증기"(아마도 더 나은 모델까지도).
HumanLayer는 최대 3명의 소규모 팀에게 무료이며, 시작하는 데 도움이 필요하시면 디스코드에 방문하시거나 founders@humanlayer.dev로 연락 주십시오.
@calvinfo님의 영감, 공동 창업자 @0xBlacklight님, 이러한 아이디어를 탐구할 장을 제공해 주신 @swyx님과 @aiDotEngineer 팀, 그리고 저희를 응원해 주시는 모든 고객, 투자자, 친구, 가족 여러분께 감사드립니다.
더 알아보고 싶으시다면, 저는 이 주제에 대해 거의 입을 다물지 못하기 때문에, 이 게시물의 모든 링크와 함께 팟캐스트, 장기 화이트보드 세션 등 자료의 다른 버전들을 아래에서 찾으실 수 있습니다.
추가 자료
팟캐스트 및 기사:
- Dex와 Gergely의 컨텍스트 엔지니어링 및 소프트웨어 팩토리에 관한 Pragmatic Engineer 인터뷰 - 2026년 7월
- Dex와 Matt Pocock의 evergreen AI 코딩 조언 (그리고 Ralph Loops) - 2026년 1월
AI That Works 에피소드:
이 게시물의 링크:
- 소프트웨어 팩토리가 실패하는 이유 기조연설 — AI Engineer World's Fair 2026
- StrongDM의 라이트-오프 소프트웨어 팩토리
- OpenAI: 하네스 엔지니어링 (2026년 2월)
- Ryan Lopopolo의 Symphony 발표 (2026년 4월)
- AI Engineer Europe에서 Mario: "슬롭 세상에서 파이 구축하기"
- FT: 코딩 에이전트 사고로 인한 Amazon 장애
- Matt Pocock: 무너지는 코드베이스
- Faros AI: AI 가속화 채찍 효과 보고서
- 코딩 에이전트를 위한 고급 컨텍스트 엔지니어링 (발표, 8/25)
- No Vibes Allowed (발표, 11/25)
- RPI에 대해 우리가 잘못 알고 있던 모든 것 (발표, 3/26)
- Awesome-RLVR - 강화 학습 리소스
- 코딩 에이전트를 위한 고급 컨텍스트 엔지니어링 (글)
- 12-Factor Agents
- Addy Osmani의 바이브 코딩 vs. 유지보수
- NATO 소프트웨어 엔지니어링 컨퍼런스, 1968
- DoD DevSecOps 참조 설계 (PDF)
- Ramp의 코딩 에이전트 플랫폼
- Stripe: Minions, 원샷 엔드투엔드 코딩 에이전트
- WorkOS: Project Horizon
- Brex (Latent Space)
- Dan Shapiro: 소프트웨어 팩토리의 다섯 단계
- Simon Willison의 StrongDM 소프트웨어 팩토리
- "바다를 끓이다"
- 샷건 수술 (refactoring.guru)
- John Ousterhout — 소프트웨어 설계의 철학
- Robert C. Martin — Clean Code
- Martin Fowler — Refactoring
- aider
- cline
- codebuff
- SWE-Agent 논문 (2024)
- OpenAI Codex 발표 (11월)
- Calvin French-Owen — AI Council 발표
- SWE-bench Multilingual (데이터셋)
- AIE Worlds Fair 2026 - The Great Loops Debate ("과대광고가 규율을 앞지르고 있다")
- SWE-Marathon (Abundant AI)
- DeepSWE (Datacurve)
- Frontier Code (Cognition)
- 돌연변이 테스트 (Wikipedia)
- Dillon Mulroy의 계획에서 콜 그래프 사용
- Dex × Matt Pocock: 수직 슬라이스 / 트레이서 불릿 (라이브스트림, 2026년 1월)
- "생각하는 힘든 작업은 아웃소싱할 수 없다" (Jake Nations)
