코드를 안 짜는 팀이 100만 줄을 만들었습니다

OpenAI 내부에서 좀 말이 안 되는 실험을 했어요.

빈 git 리포지터리를 하나 만들었어요. 거기서부터 시작해서, 사람이 코드를 한 줄도 직접 쓰지 않고 소프트웨어 제품을 만들었어요. 코드도, 테스트도, CI 설정도, 문서도, 내부 도구도 — 전부 Codex 에이전트가 썼어요. AGENTS.md 파일조차 Codex가 직접 쓴 거예요.

5개월 후. 약 100만 라인의 코드. 1,500개의 PR. 수백 명의 내부 사용자가 매일 쓰는 실제 제품이 나왔어요.

3명으로 시작했어요. 엔지니어 1인당 하루 평균 3.5개의 PR을 병합했어요. 나중에 7명으로 팀이 늘었는데, 놀랍게도 처리량이 오히려 증가했대요.

이 숫자들이 놀랍긴 한데요. 솔직히 숫자는 별로 중요하지 않아요. 중요한 건 이 팀이 코드를 안 쓰면서 대신 뭘 했느냐예요. 그리고 거기서 나온 교훈들이 — 제가 몇 달째 이 뉴스레터에서 다뤘던 것들을 아주 구체적으로 확인해주거든요.

한 가지 더요. "수동으로 작성한 코드가 없다"는 게 이 팀의 핵심 철학이 됐대요. 처음에는 실험이었는데, 나중에는 원칙이 된 거예요. 에이전트가 어려움을 겪으면 "그럼 내가 직접 짜지" 하는 대신, "에이전트가 어려움을 겪는 이유가 뭐지? 뭘 고쳐줘야 하지?"라고 물은 거예요. 이 태도가 결국 5개월 간의 교훈을 만들어낸 거예요.

오늘은 이 실험에서 실무에 바로 쓸 수 있는 것들을 뽑아보려고 합니다.

소프트웨어 엔지니어링의 변화

코드를 안 짠 대신 뭘 했느냐

이 팀이 가장 먼저 부딪힌 문제가 재밌어요.

초기 진행이 예상보다 느렸대요. 왜? Codex가 멍청해서? 아니요. 에이전트가 일할 환경이 안 되어 있어서요.

도구가 없고, 추상화가 없고, 내부 구조가 없고. 에이전트한테 "이거 만들어"라고 시켰는데, 에이전트가 쓸 수 있는 빌딩 블록이 없었던 거예요. 상위 목표를 달성하기 위한 중간 단계들이 부족했던 거예요.

이전 뉴스레터에서 Simon Willison 글을 다루면서 이 말을 했어요. "코드를 짜는 건 싸졌지만, 좋은 코드를 만드는 건 여전히 비싸다." 이 팀이 경험한 것도 똑같아요. 에이전트가 코드를 짜는 건 빠른데, 그 코드가 쓸 만한 환경을 만드는 건 사람이 해야 했어요.

그래서 엔지니어들의 역할이 완전히 바뀌었어요.

예전 엔지니어	이 팀의 엔지니어
기능 구현	에이전트가 기능을 구현할 수 있는 추상화 설계
버그 수정	에이전트가 버그를 재현·수정할 수 있는 도구 구축
코드 리뷰	에이전트 간 리뷰 프로세스 설계
테스트 작성	에이전트가 테스트를 실행할 수 있는 하니스 구축
PR 머지	병합 게이트와 자동화 프로세스 설계

실패했을 때 핵심 질문이 있어요. "더 분발하자"가 아니라 "어떤 기능이 누락되어 있으며, 에이전트가 읽기 쉽고 실행 가능하게 만들려면 어떻게 해야 하는가"예요.

이 질문이 좋은 이유가요. 에이전트한테 뭔가를 시켰는데 결과가 별로일 때, 보통 두 가지 반응이 나오잖아요. "AI가 아직 멀었다"이거나 "프롬프트를 더 잘 써봐야지"예요. 근데 이 팀은 제3의 답을 찾은 거예요. "환경을 고치자."

이전 뉴스레터에서 "코드베이스 품질이 에이전트 성능을 결정한다"는 이야기를 했었잖아요. 타입 시스템이 강하고 테스트가 있는 프로젝트에서 에이전트가 훨씬 잘 동작한다고요. 그게 개인 프로젝트 수준의 관찰이었다면, 이 팀의 경험은 그걸 조직 수준으로 확장한 거예요. 개인 프로젝트에서 "타입 시스템과 테스트"가 하는 역할을, 조직에서는 "린터, 아키텍처 제약, 문서 시스템, 관측 가능성 도구"가 하는 거예요.

에이전트한테 "눈"을 줬어요

이 팀이 단순히 "코드 써줘"만 시킨 게 아니에요. 에이전트가 자기 작업의 결과를 직접 검증할 수 있는 도구를 만들어줬어요.

어떤 것들이냐면요.

git worktree별 앱 부팅 기능. Codex가 변경사항을 만들면, 그 변경사항이 적용된 별도의 앱 인스턴스를 바로 띄울 수 있어요. 메인 브랜치에 영향 없이요. 이러면 에이전트가 "내가 만든 코드가 실제로 작동하는지"를 직접 확인할 수 있어요.

Chrome DevTools Protocol 연결. DOM 스냅샷, 스크린샷, 탐색 작업을 위한 스킬을 만들었어요. Codex가 버그를 재현하고, 수정사항을 검증하고, UI 동작에 대해 직접 추론할 수 있게 된 거예요. 사람이 브라우저 열고 "이거 제대로 돌아가나?" 확인하는 것과 같은 걸, 에이전트가 하게 만든 거예요.

로컬 관측 가능성 스택. 로그, 메트릭, 추적을 각 워크트리마다 일시적으로 유지되는 로컬 스택을 통해 Codex에 노출했어요. 에이전트가 LogQL로 로그를 쿼리하고 PromQL로 메트릭을 쿼리할 수 있어요. 이러면 "서비스 시작이 800ms 이내에 완료되도록 해줘" 같은 프롬프트가 가능해져요. 에이전트가 직접 측정하고 최적화할 수 있으니까요.

결과가 뭐냐면요. 한 번의 Codex 실행으로 6시간 이상 자율 작업이 가능해졌대요. 종종 사람이 잠자는 동안에요. 아침에 일어나면 PR이 와 있는 거예요.

이전 뉴스레터에서 "에이전트 코딩 루프와 검증 하니스"를 다루면서 "검증 하니스가 전부"라고 했잖아요. 이 팀이 만든 것들 — Chrome DevTools 연결, 관측 가능성 스택, worktree별 앱 부팅 — 이게 전부 검증 하니스예요. 에이전트가 "내가 잘 하고 있나?"를 스스로 확인할 수 있게 해주는 도구예요. 이게 없으면 에이전트가 6시간 동안 엉뚱한 방향으로 달려도 모르는 거잖아요.

AGENTS.md, 이렇게 쓰면 망합니다

여기서부터 실전 교훈이 나와요.

이 팀도 처음에 "하나의 큰 AGENTS.md"를 시도했대요. 모든 규칙, 모든 지침, 모든 제약조건을 한 파일에 다 넣은 거예요. 결과가 어땠을까요?

예측 가능하게 실패했대요.

왜 실패하는지를 4가지로 정리해줬는데, 이게 진짜 뼈 때려요.

첫째, 컨텍스트는 희소 리소스예요. 거대한 지침 파일을 넣으면, 에이전트가 정작 중요한 제약 조건을 놓치거나 엉뚱한 규칙에 최적화하기 시작해요. 이전 뉴스레터에서 "컨텍스트 윈도우는 AI의 RAM"이라고 했잖아요. RAM에 쓸데없는 걸 잔뜩 넣으면 정작 필요한 게 밀려나는 거예요.

이거 제가 실제로 경험한 거예요. CLAUDE.md에 규칙을 계속 추가하다 보니 300줄이 넘었는데, 어느 순간부터 에이전트가 초반 규칙들을 무시하기 시작하더라고요. 나중에 추가한 규칙만 따르고요. 컨텍스트 윈도우 안에서 뒤쪽에 있는 정보가 앞쪽 정보를 밀어내는 현상이에요.

둘째, 지침이 너무 많으면 지침이 아니에요. 모든 게 "중요"하면 중요한 건 없어요. 에이전트가 의도적으로 탐색하는 대신, 그냥 로컬에서 패턴 매칭을 시작해요. "이 근처에 비슷한 코드가 있네, 이거 따라하면 되겠지" 식으로요. 지침을 읽는 게 아니라 코드를 보고 따라하는 거예요.

셋째, 순식간에 무덤이 돼요. 거대한 매뉴얼은 금방 낡아요. 코드는 바뀌는데 문서는 안 바뀌니까, 에이전트가 이미 유효하지 않은 규칙을 따르게 돼요. "이 API는 v1을 써라"라고 적혀 있는데 v1은 이미 deprecated됐고 v2가 나온 지 3개월이 지났어요. 근데 AGENTS.md는 그대로예요.

넷째, 검증이 안 돼요. 하나의 커다란 파일은 "이 규칙이 아직 유효한가?", "이 부분의 담당자가 누구인가?", "이 규칙과 저 규칙이 충돌하지 않는가?"를 기계적으로 점검하기 어려워요. 그래서 드리프트가 불가피해요.

코드와 구조의 세계

이 팀이 대신 한 것

AGENTS.md를 백과사전이 아니라 목차로 쓴 거예요.

짧은 AGENTS.md — 약 100줄. 여기에는 전체 구조의 맵만 넣어요. "설계 문서는 여기 있고, 아키텍처 규칙은 여기 있고, 실행 계획은 여기 있어." 실제 내용은 구조화된 docs/ 디렉터리에 분산시켜요.

AGENTS.md          ← 맵/목차 (~100줄)
ARCHITECTURE.md    ← 아키텍처 개요
docs/
├── design-docs/   ← 설계 문서 (핵심 신념, 검증 상태 포함)
│   ├── index.md
│   └── core-beliefs.md
├── exec-plans/    ← 실행 계획 (진행중/완료/기술부채)
│   ├── active/
│   ├── completed/
│   └── tech-debt-tracker.md
├── product-specs/ ← 제품 명세서
├── references/    ← 외부 레퍼런스 (LLM용 텍스트 파일)
├── DESIGN.md
├── QUALITY_SCORE.md ← 도메인별 품질 등급
└── ...

핵심은 점진적 공개(progressive disclosure)예요. 에이전트가 처음부터 1,000페이지를 읽는 게 아니라, AGENTS.md라는 짧은 진입 지점에서 시작해서 필요한 맥락이 생기면 해당 문서를 탐색하는 거예요.

이거 생각해보면 신입 개발자 온보딩이랑 똑같아요. 첫날부터 모든 문서를 읽히지 않잖아요. "전체 구조는 이래, 네가 맡을 부분은 여기야, 자세한 건 여기 문서 참고해"라고 하잖아요. 에이전트한테도 똑같이 하면 돼요.

그리고 이 팀은 여기서 한 걸음 더 나갔어요. 문서가 부패하지 않도록 기계적으로 시행한 거예요. 전용 린터와 CI 작업이 지식 베이스가 최신 상태이고, 교차 링크되어 있고, 올바르게 구성되어 있는지를 자동으로 검증해요. 심지어 "doc-gardening" 에이전트라는 걸 반복 실행시켜서, 실제 코드 동작을 반영하지 않는 오래된 문서를 찾아내고 수정용 PR을 여는 거예요.

문서가 코드와 함께 진화하는 시스템을 만든 거예요. 사람이 "어, 이 문서 업데이트해야 하는데..." 하고 미루는 게 아니라, 에이전트가 자동으로 낡은 문서를 감지해서 업데이트하는 거예요.

실전에서 바로 적용한다면요. CLAUDE.md가 200줄이 넘었으면, 쪼개세요. 핵심 규칙만 CLAUDE.md에 남기고, 상세 내용은 별도 파일로 빼서 "자세한 내용은 docs/architecture.md를 참고하라"고 안내하는 거예요.

에이전트가 모르면 없는 거예요

이 팀이 발견한 것 중 제일 강렬한 교훈이 이거예요.

에이전트의 관점에서, 실행 중 컨텍스트 내에서 접근할 수 없는 것은 사실상 존재하지 않는다.

Google Docs에 적혀 있어요? 에이전트는 모릅니다. Slack에서 합의했어요? 에이전트는 모릅니다. 팀원 머릿속에 있어요? 당연히 모릅니다.

에이전트가 아는 건 리포지터리에 있는 것뿐이에요. 코드, 마크다운 문서, 스키마, 실행 계획. 버전 관리되고 있는 아티팩트만 존재하는 거예요.

이전 뉴스레터에서 "AI는 문서를 다 읽는다"고 했잖아요. 맞는 말인데, 뒤집으면 "문서에 안 써져 있으면 AI한테는 없는 거다"예요.

실전에서 이게 어떤 차이를 만드냐면요.

Slack에서 "우리 이 패턴으로 가자"라고 합의했어요. 사람들은 알고 있어요. 3개월 뒤에 새로 들어온 사람도 시니어한테 물어보면 "아, 그건 이렇게 하기로 했어"라고 들어서 알 수 있어요. 근데 에이전트한테는 그 합의가 전달이 안 되잖아요. 그래서 에이전트가 다른 패턴으로 코드를 짜요. "왜 이렇게 짰어?" — 에이전트 입장에서는 합리적이에요. 그 합의를 본 적이 없으니까요.

이건 사람한테도 똑같이 적용되는 문제예요. 신입이 들어왔을 때 Slack 히스토리를 전부 읽으라고 하지 않잖아요. 중요한 결정은 위키나 문서에 정리해놓잖아요. 에이전트도 마찬가지예요. 근데 사람은 물어볼 수라도 있지, 에이전트는 물어볼 줄도 몰라요. 그냥 자기가 아는 것만으로 판단해요.

이 팀의 원칙이요. Slack에서 결정하지 말고, 리포지터리에서 결정하라. 합의가 되면 바로 문서로 옮겨라. 안 그러면 에이전트한테는 그 결정이 없었던 거예요.

제품 원칙, 엔지니어링 규범, 심지어 팀 문화(이모지 선호도까지!)를 리포지터리에 기록했대요. 새 팀원을 합류시키듯이 에이전트한테 정보를 제공하면 더 나은 결과물이 나온다고요.

그리고 재밌는 부분이 하나 더 있어요. 이 팀은 "지루한" 기술을 선호했대요. 왜냐면 지루한 기술이 결합성이 좋고, API가 안정적이고, LLM 학습 데이터에 잘 표현되어 있어서 에이전트가 모델링하기 더 쉬운 경향이 있거든요.

심지어 어떤 경우에는 공개 라이브러리를 가져다 쓰는 대신 에이전트가 기능의 일부를 직접 재구현하게 하는 게 더 저렴했대요. 예를 들어, 범용 p-limit 스타일 패키지를 가져오는 대신 자체 map-with-concurrency 헬퍼를 구현했어요. 이유가요.

OpenTelemetry 계측과 긴밀하게 통합됨
테스트 커버리지 100%
런타임이 기대하는 방식대로 정확히 동작
에이전트가 전체 코드를 이해하고 수정할 수 있음

외부 라이브러리의 불투명한 업스트림 동작을 에이전트가 이해하려면 그 라이브러리 소스 코드까지 읽어야 하잖아요. 그것보다 직접 만드는 게 에이전트한테는 더 쉬운 거예요. 이건 "코드가 싸졌으니까 직접 만드는 게 합리적인 경우"의 좋은 예시예요.

규칙은 문서로 전달하지 말고, 코드로 강제하세요

여기서 한 단계 더 나가요.

문서에 규칙을 아무리 잘 써놓아도, 에이전트가 놓칠 수 있어요. CLAUDE.md에 "이 레이어에서 저 레이어를 직접 호출하지 마세요"라고 써놨는데, 에이전트가 안 읽었거나, 컨텍스트 윈도우에서 밀려났거나, 다른 규칙이랑 충돌해서 무시할 수 있잖아요.

이전 뉴스레터에서 "암묵적 불변조건을 깨는 경우가 많다"는 이야기를 했잖아요. 그때는 "되돌릴 수 없는 결정 직전에 인간이 개입"하라고 했는데, 이 팀은 거기서 한 걸음 더 나간 거예요. 인간이 개입하기 전에 기계적으로 위반을 막아버리는 거예요.

이 팀의 해결책이요. 맞춤형 린터와 구조적 테스트로 기계적으로 강제한 거예요.

예를 들면. 각 비즈니스 도메인이 고정된 레이어로 분리되어 있어요.

Types → Config → Repo → Service → Runtime → UI

교차 문제 (인증, 커넥터, 텔레메트리, 기능 플래그)
→ Providers라는 하나의 명시적 인터페이스를 통해서만 유입

그 외: 허용되지 않으며 기계적으로 강제 적용

이 순서를 어기면 린터가 잡아요. 에이전트가 읽든 안 읽든 상관없이 CI에서 터지는 거예요. Service 레이어에서 UI 코드를 직접 호출하면, 그 PR은 머지가 안 돼요.

여기서 진짜 영리한 게 있어요. 린트 오류 메시지에 수정 지침을 주입한 거예요. 일반 린터는 "이 규칙을 위반했습니다"만 말하잖아요. 이 팀은 "이 규칙을 위반했습니다. 이렇게 수정하세요: [구체적 방법]"이라고 오류 메시지에 넣었어요. 에이전트가 오류를 보고 바로 어떻게 고쳐야 하는지 알 수 있게요.

이게 왜 중요하냐면요. 에이전트가 린트 에러를 만나면 보통 이렇게 해요.

에러 메시지를 읽는다
"어떻게 고치지?" 고민한다
추측해서 수정한다 (맞을 수도 있고 틀릴 수도 있음)

근데 에러 메시지에 수정 방법이 있으면요.

에러 메시지를 읽는다
수정 방법대로 고친다
끝

추측이 없어져요. 정확도가 올라가요.

문서로 규칙 전달	코드로 규칙 강제
"이 레이어에서 직접 호출하지 마세요"	린터가 종속성 방향 검사 → 위반 시 에러 + 수정 방법
"경계에서 데이터 파싱을 해주세요"	구조적 테스트가 파싱 여부 검증
"파일 크기를 적절히 유지하세요"	린트 규칙이 파일 크기 제한을 정적 적용
"구조화된 로깅을 사용하세요"	린트가 console.log 사용 시 에러 + 대안 제시
에이전트가 놓칠 수 있음	에이전트가 위반할 수 없음

이전 뉴스레터에서 "AI가 짠 코드를 믿지 마라, 검증시켜라"를 다뤘잖아요. 그때는 테스트와 린팅으로 검증하라고 했는데, 이 팀은 거기서 한 걸음 더 나간 거예요. 검증뿐 아니라 자가 수정까지 가능하게 만든 거예요.

재밌는 건요. 이런 수준의 아키텍처 제약은 보통 엔지니어 수백 명 규모에서 도입하잖아요. 근데 이 팀은 3명일 때부터 했어요. 왜? 에이전트한테는 이게 초기 전제 조건이니까요. 에이전트는 구조가 없으면 방향을 못 잡아요. 사람은 암묵적으로 "아 이건 이렇게 해야지"를 알지만, 에이전트는 몰라요.

그리고 이 팀이 하나 더 말한 게 있어요. "문서화가 부족하면 규칙을 코드로 승격하라." 리뷰 코멘트에서 같은 피드백이 반복되면, 그걸 문서에만 추가하는 게 아니라 린트 규칙으로 만들어버리는 거예요. "이거 하지 마세요"를 100번 말하는 것보다, 한 번 린트 규칙으로 만들면 영원히 작동하잖아요.

중앙에서 경계를 설정하고, 로컬에서는 자율성을 허용하는 거예요. 이 팀은 이걸 "대규모 엔지니어링 플랫폼 조직을 이끄는 것과 비슷하다"고 표현했어요. 경계, 정확성, 재현성이 중요한 부분은 엄격하게 강제하고, 그 경계 내에서 솔루션을 표현하는 방식에는 에이전트에게 자유를 주는 거예요.

결과로 생성된 코드가 인간의 문체 선호도와 항상 일치하지 않을 수 있대요. 근데 문제가 안 된대요. 출력이 정확하고, 유지관리 가능하고, 에이전트가 읽기 쉬우면 기준을 충족하는 거라고요.

개발 팀과 협업

AI 슬로프는 매주 청소하면 안 돼요

에이전트가 많은 코드를 빠르게 만들면 새로운 문제가 생겨요. 엔트로피예요.

에이전트는 리포지터리에 이미 있는 패턴을 참고해서 새 코드를 만들어요. 근데 기존 패턴 중에 최적이 아닌 것도 있잖아요. 그걸 그대로 복제하고 확산시켜요. 시간이 지나면 코드베이스 전체의 일관성이 점진적으로 하락해요.

이거 "AI 코딩 도구가 복잡성 편향을 악화시킨다"에서 다뤘던 문제랑 같은 맥락이에요. AI는 기본적으로 "코드를 더 추가하는 쪽"으로 편향돼요. 불필요한 래퍼 함수, 타입 변환, 추상화를 추가하는 경향이 있다고 했잖아요. 이 팀은 그걸 조직 수준에서 경험한 거예요.

이 팀도 처음에는 매주 금요일마다 "AI 슬로프" 정리를 했대요. 일주일의 20%를 정리에 쓴 거예요. 결과가 어땠을까요?

확장 안 됐대요. 에이전트가 코드를 만드는 속도가 사람이 정리하는 속도를 초과하니까요. 월요일~목요일에 에이전트가 쌓아놓은 엔트로피를 금요일 하루에 다 못 치우는 거예요.

그래서 이 팀이 찾은 패턴이 가비지 컬렉션이에요. 자바에 가비지 컬렉터가 있잖아요. 메모리를 쓰다가 한꺼번에 청소하는 게 아니라, 조금씩 계속 청소하는 거예요. 코드베이스 엔트로피도 같은 방식으로 관리하는 거예요.

수동 정리 대신 두 가지를 조합했어요.

첫째, "황금 원칙"을 코드로 인코딩. "공유 유틸리티 패키지를 쓸 것", "YOLO-style로 데이터 탐색하지 말 것" 같은 원칙을 린터와 테스트로 강제한 거예요. 에이전트가 추측한 형태를 바탕으로 실수로 무언가를 구축하지 못하도록 경계를 검증하고 유형 지정된 SDK에 의존하게 한 거예요.

둘째, Codex 백그라운드 작업으로 매일 자동 정리. 에이전트가 정기적으로 편차를 검사하고, 품질 등급을 업데이트하고, 리팩터링 PR을 만들어요. 대부분 1분 이내에 검토 가능하고, 자동으로 병합돼요. 사람이 "이번 주 금요일에 정리해야지" 하는 게 아니라, 매일 자동으로 조금씩 정리되는 거예요.

이 팀이 쓴 비유가 좋아요.

"기술 부채는 고금리 대출과 같다. 이자가 쌓여 고통스럽게 한꺼번에 갚는 것보다, 조금씩 꾸준히 갚아나가는 편이 훨씬 낫다."

전통적 접근	가비지 컬렉션 접근
분기별 "리팩터링 스프린트"	매일 자동 정리 백그라운드 작업
부채가 쌓인 후 한꺼번에 해결	부채가 쌓이기 전에 예방
사람이 정리 대상 식별	에이전트가 편차를 자동 감지
정리가 기능 개발과 경쟁	정리가 기능 개발과 병행
금요일에 몰아서	매일 조금씩

그리고 이게 선순환이에요. 사람의 취향이 한 번 포착되면(린트 규칙으로, 문서로, 테스트로) 코드의 모든 라인에 지속적으로 반영돼요. 나쁜 패턴이 코드베이스에 며칠이나 몇 주 동안 퍼지기 전에 매일 포착되고 해결돼요.

AI가 문제를 만들고, AI가 문제를 정리하는 시스템. 사람은 "어떤 패턴이 맞는지"만 한 번 정의하면, 그 이후로는 자동이에요.

병합 철학이 바뀐다

여기서 하나 더 재밌는 게 있어요.

이 팀은 처리량이 늘어나면서 기존 엔지니어링 규범이 오히려 역효과를 내기 시작했대요.

보통 우리가 아는 규범이 뭐예요? PR을 올리면 사람이 꼼꼼하게 리뷰하고, 모든 테스트가 통과하면 머지한다. 근데 에이전트가 하루에 3.5개의 PR을 만드는데, 사람이 전부 꼼꼼하게 리뷰하면 하루 종일 리뷰만 해야 해요. 다른 일은 못 하고요.

그래서 이 팀은 최소한의 차단 병합 게이트로 운영했어요. PR은 수명이 짧고, 테스트 불안정성은 진행을 무기한 막기보다는 후속 실행으로 해결했어요. 그리고 사람의 PR 검토는 가능하지만 필수는 아니었어요. 시간이 지나면서 거의 모든 검토 작업을 에이전트 간 처리로 전환했대요.

핵심 원칙이 이거예요.

에이전트 처리량이 사람의 주의력을 초과하는 시스템에서는, 수정 비용이 저렴하고 대기 시간이 비싸다.

코드가 싸졌잖아요. 그러면 수정도 싸요. 수정이 싸면, "완벽하게 만들어서 한 번에 머지하는 것"보다 "빠르게 머지하고, 문제가 있으면 빠르게 수정하는 것"이 합리적이에요.

근데 이게 가능한 이유가 있어요. 앞에서 말한 것들 — 맞춤형 린터, 구조적 테스트, 에이전트 간 리뷰, 가비지 컬렉션 패턴 — 이런 안전망이 깔려 있기 때문이에요. 안전망 없이 "그냥 머지해"하면 당연히 망해요.

이 팀도 주의를 줬어요. "이는 처리량이 적은 환경에서는 적합하지 않을 수 있다. 적절한 절충안이 필요하다." 에이전트 처리량이 낮거나 자동 검증 인프라가 부족한 환경에서는 기존 규범이 여전히 유효하다고요.

자율성의 임계점

이 모든 게 쌓이면 어떤 일이 벌어지냐면요.

에이전트가 한 번의 프롬프트를 통해 이런 걸 할 수 있게 됐대요.

코드베이스의 현재 상태 검증
보고된 버그 재현
실패 상황을 시연하는 동영상 녹화
수정사항 구현
애플리케이션을 실행하여 수정사항 검증
해결책을 보여주는 두 번째 동영상 녹화
PR 열기
에이전트 및 사람 피드백에 응답
빌드 실패 감지 및 수정
판단이 필요한 경우에만 사람에게 에스컬레이션
변경사항 병합

11단계를 한 번에요. 이전 뉴스레터에서 "코드 치는 시대는 끝났다"를 다루면서, 카파시가 "30분 만에 끝났다"고 한 것보다 더 극단적이에요. 버그 리포트부터 수정 완료까지, 사람이 거의 개입하지 않는 거예요.

근데 이 팀이 강조한 게 있어요. "이러한 동작은 이 리포지터리의 특정 구조와 툴링에 따라 크게 달라지며, 유사한 투자 없이 일반화할 수 있다고 가정해서는 안 된다."

즉, 이 결과는 5개월간 쌓아온 스캐폴딩 — 린터, 아키텍처 제약, 관측 가능성 도구, 에이전트 간 리뷰 프로세스, doc-gardening 에이전트, 가비지 컬렉션 패턴 — 이 모든 것이 합쳐져서 나온 거예요. 에이전트가 갑자기 똑똑해진 게 아니라, 환경이 좋아져서 에이전트가 더 많은 걸 할 수 있게 된 거예요.

솔직히 이렇게 느꼈습니다

이 글 읽으면서 두 가지가 동시에 느껴졌어요.

"와, 진짜 되는구나." 100만 줄이요. 수백 명이 매일 쓰는 실제 제품이요. 사람이 코드 한 줄 안 쓰고요. 이전까지는 "에이전트로 프로덕션 제품을 만든다"가 좀 과장이라고 생각했거든요. 사이드 프로젝트나 프로토타입은 몰라도, 수백 명이 매일 쓰는 실제 제품? 근데 이건 OpenAI 내부에서 5개월간 실제로 운영한 결과니까 부정하기 어렵잖아요.

근데 동시에 "이거 보통 팀이 따라할 수 있나?"라는 생각도 들었어요. 솔직히 말할게요. 이 팀이 한 것들 — 맞춤형 린터, 아키텍처 자동 검증, 에이전트 간 코드 리뷰, Chrome DevTools Protocol 연결, 관측 가능성 스택, 백그라운드 정리 에이전트, doc-gardening 에이전트 — 이걸 처음부터 세팅하는 건 엄청난 투자예요. 그리고 이 팀은 Codex를 만든 OpenAI의 팀이에요. 자기들 제품을 제일 잘 아는 사람들이 자기들 제품으로 실험한 거예요.

근데 핵심 교훈들은 규모에 상관없이 적용 가능해요. AGENTS.md를 목차로 쓰는 것, 규칙을 문서 대신 코드로 강제하는 것, 에이전트가 접근할 수 없는 지식은 리포지터리로 옮기는 것, 린트 오류 메시지에 수정 지침을 넣는 것 — 이건 1인 사이드 프로젝트에서도 바로 할 수 있는 거잖아요.

그리고 솔직히 제일 인상 깊었던 건 이 문장이에요.

"소프트웨어 구축에는 여전히 규율이 필요하다. 다만 그 규율은 코드에서 스캐폴딩으로 이동했다."

이전 뉴스레터에서 카파시가 "코드 치는 시대는 끝났다"고 했잖아요. 그때 제가 "끝난 건 타이핑이지 개발이 아니다"라고 했었는데, 이 팀의 실험이 그걸 정확히 보여주는 것 같아요. 코드를 안 쳤지만 엔지니어링은 더 많이 했어요. 다만 그 엔지니어링의 대상이 코드가 아니라 시스템, 도구, 프로세스였던 거예요.

그리고 한국에서도 비슷한 사례가 나오고 있어요. 긱뉴스에서 공유된 "40일, 100만 줄, 130억 토큰 — Lablup 신정규 대표가 발견한 에이전틱 워크플로의 실체"라는 글이 있는데요. 한국의 스타트업에서도 비슷한 규모의 에이전트 활용 실험이 진행되고 있다는 거예요. 이게 OpenAI만의 이야기가 아니라, 업계 전체가 이 방향으로 가고 있다는 신호인 것 같아요.

오늘 바로 해보세요

1. CLAUDE.md가 200줄 넘었으면 쪼개세요 (10분)

# CLAUDE.md (~100줄. 맵/목차 역할만)

## 프로젝트 개요
(3줄)

## 핵심 규칙
(10줄 이내 — 진짜 중요한 것만)

## 상세 가이드
- 아키텍처: docs/architecture.md를 참고하라
- 코딩 컨벤션: docs/conventions.md를 참고하라
- 테스트 가이드: docs/testing.md를 참고하라
- API 설계 원칙: docs/api-design.md를 참고하라

전부 CLAUDE.md에 넣지 말고, "여기 가서 읽어"라고 안내만 하세요. 에이전트가 필요할 때 해당 문서를 읽을 거예요. 핵심은 CLAUDE.md를 "모든 규칙이 있는 곳"이 아니라 "모든 규칙을 찾을 수 있는 곳"으로 만드는 거예요.

2. Slack에서 합의한 거 하나를 리포지터리에 옮기세요 (5분)

최근에 Slack이나 회의에서 "우리 이 패턴으로 가자"라고 합의한 거 있잖아요. 그거 지금 리포지터리 어딘가에 적혀 있어요? 없으면, 에이전트한테는 그 합의가 없었던 거예요. 지금 바로 docs/decisions.md에 한 줄이라도 적으세요.

# 아키텍처 결정 기록

## 2026-03-15: API 응답 포맷
- 결정: 모든 API 응답은 `{ data, error, meta }` 형태를 따른다
- 이유: 프론트엔드 파싱 일관성
- 참여자: 에피, 개발팀

이 형식 아니어도 괜찮아요. 한 줄이라도 적혀 있으면 에이전트가 참고할 수 있어요.

3. 린트 규칙 하나에 "수정 방법"을 추가하세요 (5분)

기존 린트 규칙 중에 에이전트가 자주 위반하는 게 있으면, 오류 메시지에 수정 방법을 넣어보세요.

// Before
"파일 크기 제한 초과"

// After  
"파일 크기 제한 초과 (현재 450줄, 제한 300줄). 
 이 파일을 기능 단위로 분리하세요. 
 예: UserService에서 UserValidator를 별도 파일로 추출.
 참고: docs/conventions.md#file-size"

에이전트가 이 메시지를 읽고 바로 수정할 수 있어요. 추측 없이요.

4. "이번 주에 정리할 것" 대신 "매일 정리할 것"을 하나 만드세요 (3분)

기술 부채 정리를 금요일에 몰아서 하고 계신다면, 작은 것 하나를 매일 자동으로 돌려보세요.

예를 들어, CI에 "사용하지 않는 import를 자동 제거하는" 단계를 추가하는 거예요. 이거 하나만으로도 코드베이스가 점진적으로 깔끔해져요. 에이전트가 불필요한 import를 추가하는 건 아주 흔한 문제이고, 이건 자동으로 잡을 수 있는 가장 쉬운 것 중 하나예요.

마무리

이 팀이 5개월간 보여준 건 "에이전트가 코드를 잘 짠다"가 아니에요. "에이전트가 잘 일할 수 있는 환경을 만드는 게 진짜 엔지니어링이다"는 거예요.

코드를 안 쓴다고 할 일이 없어지는 게 아니에요. 오히려 할 일이 바뀌는 거예요. 구조를 만들고, 규칙을 코드로 강제하고, 지식을 리포지터리에 기록하고, 엔트로피를 매일 조금씩 정리하는 일. 이게 "스캐폴딩"이에요. 그리고 이 스캐폴딩이 좋을수록 에이전트가 더 잘 일해요. 6시간을 혼자 돌려놔도 괜찮을 만큼요.

제 강의에서 "CLAUDE.md 하나로 AI가 달라집니다"를 다루는데요. 이 글을 읽고 나니까 그게 빙산의 일각이었다는 게 보이네요. CLAUDE.md는 시작이고, 진짜 게임은 그 위에 쌓는 시스템 — 린터, 아키텍처 제약, 문서 구조, 자동 정리 — 에 있어요. 이 팀은 그 전체 그림을 5개월 만에 보여줬고, 그 결과가 100만 줄이에요.

미래의 개발 환경

레퍼런스

Harness Engineering: Building with Codex in an Agent-First World — Ryan Lopopolo (OpenAI). 5개월간 사람의 직접 코딩 없이 100만 라인의 제품을 구축한 실험 보고서

매주 바이브 코딩 실전 인사이트를 보내드립니다.

Claude Code로 진짜 제품을 만드는 법이 궁금하시면,

👉 에피코딩 강의 보러 가기 (https://effycoding.pages.dev)

이 뉴스레터가 도움이 됐다면, 동료 개발자에게 공유해주세요.