여러 팀의 시스템을 이해하기 위한 AI 집단 지성 구축하기

• SumUp의 여러 도메인에 걸친 시스템을 이해할 때마다 엔지니어 3~4명을 모으는 대신,
  약 66개 저장소와 조직 맥락을 연결한 AI 에이전트 시스템을 구축함
• 저장소를 기술 스택이 아닌
  제품과 팀 구조에 따라 묶고, 도메인별 AGENTS.md

에 원칙, 조직 구조, 서비스 폐기 계획과 진행 중인 프로젝트를 담음
주 에이전트와 범위가 제한된 하위 에이전트가 조사와 해결책 탐색을 나눠 수행하며, 구조화된 JSON 보고서로 결과를 전달해 도메인 경계와 맥락을 유지함

• Notion과 Slack의 최근 일주일 변경 사항으로 맥락 갱신 PR을 만들고,
  사람이 검토한 뒤 병합해 팀의 계획과 의사결정을 최신 상태로 유지함
  OpenCode로 작업별 모델과 제공업체를 바꿔 사용하며, 조사 결과는 도메인별 근거와 프롬프트를 포함한 단일 HTML 파일로 공유함

시스템을 이해하기 위해 사람부터 모으는 문제

• 관리 업무가 늘면 직접 코드를 작성하는 시간은 줄지만,
  시스템이 실제로 어떻게 작동하는지 이해할 필요는 여전히 남음
• SumUp에서는 도메인마다 수십 개의 서비스와 애플리케이션이 있어, 여러 도메인에 걸친 프로젝트를 시작할 때마다
  엔지니어 3~4명을 모아 연결 관계와 변경 지점을 파악해야 했음
• Mermaid 다이어그램, Miro 보드, RFC와 기술 문서도 변화 속도를 따라가기 어려워짐
• 목표는
  코드와 팀 구조, 서비스 간 연결 관계를 함께 조사해 이런 회의를 줄이는 것임
• 문서에 명시되지 않고 대화나 회의에 흩어진 조직 지식도 함께 드러내고자 함

범용 에이전트에서 도메인별 맥락으로

• 첫 시도는
  Notion Custom Agents에 GitHub와 다른 도구를 연결하는 방식이었음

• 단일 팀에서는 유용했지만, 도메인과 저장소가 늘자 필요한 문서를 놓치고 도구 호출이 실패하는 일이 많아짐

• 업무를 맡길 만큼 신뢰하기 어려워 직접 시스템을 구축함

• 회사 전체를 포괄하는 대신
  두 도메인과 하나의 공통 모바일 앱으로 범위를 제한하고, 관련 저장소 약 66개를 Git 서브모듈로 연결함

• 폴더는 Kotlin·Go 같은 기술 분류가 아니라
  제품과 팀의 구조를 따름

• Sales와 Payments를 각각 도메인 폴더로 나누고, 클라이언트와 플랫폼 인프라도 별도로 배치함

• 큰 도메인은 하위 도메인으로 나눠 각각의 맥락을 관리함

• 도메인별
  AGENTS.md

에는 코드만으로 알 수 없는 정보를 담음

• 도메인의 정의와 원칙, 팀 구조, 진행 중인 프로젝트를 기록함

• 아직 실행에 옮기지 않은 서비스 폐기 의향도 포함함

• 초기 정보는 Notion과 Slack에서 AI로 추출하고, 직접 알고 있는 조직 지식과 표본 점검으로 검증함

• 도메인을 넘나드는 질문에 좋은 답을 얻도록
  맥락 파일을 반복 조정하는 데 가장 많은 시간이 들었음

저장소별로 조사하고 전체 시스템으로 종합하기

• 저장소가 약 10개를 넘자 에이전트가 직접 조사할지 하위 에이전트에 맡길지 일관되게 결정하지 못하고,
  서로 다른 도메인의 경계를 혼동하기 시작함

• 지침에 “반드시”, “중요함”을 강조하는 것만으로는 해결되지 않았음

• 하위 에이전트는
  저장소 하나로 작업 범위를 제한하고, 조사 결과나 해결책을 보고서로 작성함

• 주 에이전트가 구조화된 작업 지시와 사용자의 최초 질문을 함께 전달함

• 보고서에는 해당 도메인의 원칙, 관행, 목표와 진행 프로젝트를 반영함
  Zod 스키마로 정의한 JSON을 사용해 인계 형식을 일정하게 유지함

• 개별 저장소 조사에는 비교적 가벼운 모델을 쓰고,
  전체 시스템을 종합하는 역할에는 고성능 모델을 배정함

• 구체적인 범위와 명령을 주는 방식이 비용뿐 아니라 결과 품질에도 도움이 됐음

• 사용자는 주 에이전트와 대화하며, 주 에이전트가 하위 작업을 배정하고 결과를 연결함
  시스템 조사: 관련 도메인과 저장소를 찾고 조사 계획을 세운 뒤, 보고서를 합쳐 작동 방식과 연결 관계를 설명함. 필요하면 Mermaid 다이어그램도 생성함
  해결책 탐색: 도메인별로 접근법과 장단점을 평가한 뒤, 전체 시스템에 적합한 해결책을 종합함
  조직 맥락 적용: 팀 구조와 조직 가치, 엔지니어링 전략을 고려하며, 도메인 주도 설계·Conway’s Law·Team Topologies 같은 관점을 활용함

Notion과 Slack의 변화를 맥락 파일에 반영하기

• 조사 시스템을 만들어도
  맥락 갱신이 한 사람에게 의존하면 그 사람이 정보를 공유하지 않는 순간 낡기 시작함

• 갱신할 정보는 서비스 간 연결과 데이터 흐름뿐 아니라
  폐기 계획, 새 프로젝트, 바꾸고 싶지 않은 부분, 현재와 미래의 과제까지 포함함

• 모든 문서를 동적으로 검색하는 RAG도 검토했지만, 필요한 것은 초기 맥락과 주간 변경 사항이어서 더 단순한 방식을 선택함

• 갱신은
  주간 조사 → GitHub 이슈 → Cursor PR → 사람 검토 순서로 진행함

• 맞춤 에이전트가 Notion과 접근 권한이 있는 Slack 채널에서 최근 일주일의 변경 사항을 조사함

• 도메인별 폴더 구조에 맞춰 보고서를 작성하고 GitHub 이슈에 첨부함
  Cursor Cloud Agent가 보고서와 기존 맥락 파일을 읽어 갱신 PR을 만듦

• 사람이 보고서와 PR을 모두 읽고 오류와 불필요한 내용을 수정한 뒤 병합함

• 주간 조사에는
  100만 토큰 컨텍스트 창을 가진 모델을 사용했으며, 더 작은 컨텍스트의 모델은 이 작업에 실패했음

• 코드 저장소인 서브모듈도
  주 1회 갱신하며, 이 단계의 자동화는 후속 과제로 남아 있음

결과와 조사 과정을 함께 공유하기

• 주 에이전트와 하위 에이전트는 같은 JSON 스키마와 맞춤 도구를 사용해, 보고서에서 필요한 부분을 바로 읽을 수 있음

• 최종 결과는
  단일 HTML 파일로 생성함

• 핵심 발견 사항, 도메인별 상세 결과와 장단점, 최종 제안을 담음

• 사용자 질문과 주 에이전트가 하위 에이전트에 내린 지시도 포함함

• 대화 내용을 다시 요약해 전달하면 빠질 수 있는
  도메인별 맥락과 조사 근거를 함께 남김

• 결과만 필요한 사람은 핵심 요약을 읽고, 자세히 확인할 사람은 같은 파일에서 세부 내용을 살펴볼 수 있음

OpenCode와 필요한 저장소만 불러오는 CLI

OpenCode를 선택한 가장 큰 이유는 모델과 제공업체를 바꿀 수 있다는 점임

• 작업에 맞는 모델을 시험하고, 특정 제공업체의 서비스가 중단돼도 다른 모델로 작업을 이어갈 수 있음

• 맞춤 에이전트와 도구를 구성할 수 있고, 데스크톱 앱으로 비개발자도 접근할 수 있음

• 수십 개의 서브모듈을 다루기 위해
  저장소 관리용 CLI도 만듦

• 필요한 저장소나 도메인별 그룹을 한 번에 불러오고, 사용하지 않는 로컬 복사본은 제거해 공간을 확보함

• 에이전트도 Git 명령을 반복하는 대신 이 CLI로 필요한 저장소를 준비함

• 현재는 필요한 기능의 약
  80%를 갖춘 상태로 보고, 추가 효용에 비해 큰 시간을 들이지 않도록 점진적으로 개선하고 있음

• 후속 계획은
  저장소 자동 갱신, 공유 기억 갱신, 클라우드 조사 실행이며, 최종 목표는 Slack에서 @멘션으로 주 에이전트를 사용하는 것임

댓글과 토론