TL;DR

  • 에이전트형 코드는 최첨단 수준의 코드 조각을 만들 수 있지만, 아키텍처와 제약 조건이 없으면 응집력과 일관성을 갖춘 시스템을 만들기 어려움.
  • 테스트와 정적 분석만으로는 코드의 내부 구조를 강제할 수 없으며, 기능을 지탱할 아키텍처라는 기둥이 필요함.
  • Epiq는 에이전트형 워크플로가 널리 쓰이기 전부터 사람이 저장 방식, 이벤트 속성, 인과 순서를 중심으로 아키텍처를 정립함.
  • Claude Code가 프로젝트에 도입된 뒤에는 견고한 구조 위에 기능과 테스트를 빠르게 쌓았으며, 동시성·Git 상호작용·장기 사용을 검증하는 테스트도 마련함.
  • 프로젝트의 핵심 데이터 모델은 기존 데이터 마이그레이션 없이 새 이벤트 유형과 로그에서 도출한 정보로 기능을 확장하게 했으며, 코드를 전부 직접 쓰지 않는 기술은 사람이 직접 이해하고 다듬어야 할 부분을 아는 것임.

에이전트형 코드의 형태

  • 에이전트형 코드는 쉽게 모양을 바꾸고 적은 노력으로 어떤 형태든 취할 수 있는 천에 비유할 수 있지만, 그 자체로 견고한 구조를 만들기는 어려움.
  • 에이전트는 인간 지식의 최첨단에 맞먹는 뛰어난 코드 조각을 만들 수 있지만, 응집력과 일관성은 여전히 과제임.
  • 아무런 지침이 없는 에이전트형 코드는 형태 없는 천과 같음.

말뚝의 오류

  • 에이전트 워크플로의 구조 부족을 해결하려고 테스트, 계약, 정적 분석을 더하는 것이 자연스러운 대응처럼 보임.
  • 그러나 가장자리를 말뚝으로 고정하는 것만으로는 내부 구조의 견고함을 확보하기 어려움.
  • 제약을 적용할 내부 구조가 없다면 결과는 여전히 부드럽고 납작한 엉망임.
  • 테스트로 고정해도 내부 구조가 없으면 엉망인 상태가 남음.

천막 세우기

  • 천을 원하는 형태로 팽팽하게 펴려면 튼튼한 기둥이 필요함. 소프트웨어에서는 추가 작업의 방향을 잡고 테스트와 정적 분석이 제약을 적용할 수 있게 하는 뚜렷한 아키텍처가 이에 해당함.
  • 천막에서는 내부 구조와 천, 말뚝이 서로 의존함. 소프트웨어도 마찬가지로, 기능의 망을 펼칠 아키텍처가 없으면 제약을 거는 말뚝은 별 쓸모가 없음.
  • 반대로 말뚝이 없다면 아침에 일어났을 때 나무 구조물은 그대로인데 천은 멀리 떨어진 나무 꼭대기에 걸려 있을 수 있음.
  • 구조와 테스트가 함께 작동해야 부드러운 천에 형태가 생김.
  • 이론은 이러하며, 다음은 이 원리가 프로젝트에서 어떻게 전개됐는지에 대한 이야기임.

수많은 의심

  • 2025년 초여름, 저장 상태를 저장소에 두고 Git으로 동기화하는 이슈 트래커 Epiq 개발을 시작함.
  • 당시 에이전트형 워크플로는 아직 먼 소문에 불과했음. 코드를 직접 고치며 씨름하고, 끝없는 러버덕 디버깅을 하고, 11시간의 명상 세션에 해당하는 자동차 여행을 거치며 프로젝트의 아키텍처를 수많은 의심 속에서 다듬음.
  • 아이디어의 숲에서 나무를 골라 잘못된 가지를 쳐냈고, 기록한 뒤 다시 가지를 치고 다듬어 마침내 서로 엮음. 그 결과 다음과 같은 타협 불가 아키텍처 기둥이 정립됨.
  • 사용자 범위에 한정된 추가 전용 이벤트 로그를 영속성 계층으로 사용함
  • 공유 기록만 참조하는, CRDT와 유사한 속성의 이벤트를 사용함
  • 벽시계 시간을 동률 해소 기준으로 삼아 인과 순서를 결정함
  • 이후의 모든 기능은 이 기둥 위에 놓임.

제약을 통한 방향 설정

  • 각 원칙은 개별적으로 이례적이지 않지만, 함께 적용하면 주류 해법이 아님. 워크플로가 100% 에이전트형이었다면 이 아키텍처는 나올 가능성이 낮았을 수 있음. 확률적 모델은 비정형적인 선택에 불이익을 주기 때문임.
  • 제약 조건을 드러내면 이 해법이 나올 가능성이 커짐.
  • 보드는 서버나 특정 공급업체에 의존하지 않고 코드와 함께 저장소에 존재함
  • 유일한 전송 수단은 Git임
  • 사용자에게 병합 충돌 해결을 요구하지 않음
  • 여러 사람과 에이전트가 온라인 또는 오프라인에서 동시에 편집할 수 있음
  • 이 제약은 비전에서 도출됨. 에이전트는 제약으로 안내받지 않으면 비표준 해법을 발견하는 경향이 낮으며, 비전이 없으면 제약도 주어지지 않음.
  • 코드베이스에 대한 비전이 부족한 에이전트에게 빨간 버튼을 요청한 뒤 파란 버튼을 요청하면, 하나의 설정 가능한 버튼 대신 서로 다른 버튼 컴포넌트 두 개가 만들어질 수 있음.
  • 시스템의 근본 원칙과 제약 조건은 사람의 비전에서 도출하는 편이 바람직함.

뜻밖의 축복

  • 초기에는 에이전트형 워크플로가 없었기에 내부 구조를 대부분 직접 만들고 충분히 이해할 수 있었음.
  • 기둥이 세워진 뒤인 2026년 늦여름, 바로 옆에 천 공장이 문을 여는 듯한 행운이 찾아옴. Claude Code가 도입됨.
  • 에이전트형 워크플로가 더 일찍 도입됐다면 아키텍처에 해가 됐을 수 있음. 실제로는 기능의 천을 펼칠 틀이 준비된 바로 그때 에이전트가 도착함.
  • 그 순간 기능뿐 아니라 테스트도 저렴하게 추가할 수 있게 됨. 기둥 하나를 땅에 단단히 고정하려고 천막 말뚝을 천 개 박는 것도 가능해짐.
  • 이제 핵심부는 극도로 꼼꼼한 테스트로 고정돼 있음.
  • 테스트 전체가 동시성 모델을 무너뜨리려 함
  • 다른 테스트가 Git 상호작용을 무너뜨리려 함
  • 한 테스트는 20명으로 구성된 팀이 10년 동안 매일 트래커를 집중적으로 사용하는 상황을 시뮬레이션하고, 그 규모에서도 보드를 계속 사용할 수 있고 응답성이 유지되는지 검증함

대전환

  • 이 프로젝트의 모든 근본 기둥에는 공통점이 있음. 모두 데이터 모델과 관련됨.
  • 일반적으로 데이터는 유연하고 소프트웨어는 견고하다고 여겨지지만, 에이전트형 워크플로는 이 관계에 도전하며 어쩌면 뒤집기까지 함.
  • 그러나 데이터가 시스템을 굳히는 효과는 달라지지 않음. 데이터에는 마이그레이션, 파악되지 않은 출처, 서로 다른 품질, 위험한 변환이 따르며, 이 모든 요소가 시스템 진화를 어렵게 함.
  • 올바른 데이터 모델을 고르는 일은 사후 작업이 아니라 아키텍처의 핵심 기능임. 이는 부드러운 코드 조직을 펼치는 기둥이며, 테스트로 땅에 고정됨.
  • 이 프로젝트에서 데이터 모델은 분산 실시간 협업에 필수적일 뿐 아니라 시스템의 진화 가능성도 높였음.
  • 지금까지 모든 새 기능은 로그에서 정보를 새로운 방식으로 도출하거나 이벤트 유형을 추가하는 방식으로 구현했으며, 기존 데이터를 마이그레이션한 적은 없음.
  • 이미지 첨부 기능은 새 이벤트 유형을 추가하는 것만으로 구현함. 새 클라이언트는 해당 이벤트를 인식하고 이전 클라이언트는 무시함.
  • 고급 통계 기능은 이벤트 로그에서 도출할 수 있는 정보를 찾아내는 방식으로 구현함.
  • 모든 시스템이 같은 제약 아래 놓인 것은 아니며, 다른 비전에는 다른 구조적 기둥이 필요함.
  • 어떤 경우든 코드를 전부 직접 쓰지 않는 기술은 직접 관여하고 직관을 길러야 하는 부분이 무엇인지 아는 것임.

천막으로 돌아가기

  • 시스템의 중심 원칙을 사람이 직접 다듬고 이해해야 할 필요는 여전히 있음.
  • 에이전트형 워크플로는 짧은 시간에 틀을 아름다운 장식으로 마무리하고 말뚝 천 개로 땅에 단단히 고정하는 데 도움을 줄 수 있음.
  • 그러나 충분히 이해된 견고한 아키텍처 기둥이 없다면 남는 것은 부드럽고 형태 없는 엉망뿐임. 장식은 화려해도 납작하고 축축하며 뒤엉킨 상태임.
  • 이 관점에 공감하는지, 아니면 동의하지 않는지 의견을 나눠 달라는 요청임.