팀 단위 AI 컨텍스트를 설계하면서 배운 것들

취미로 소위 바이브코딩을 해볼 때와 실제로 업무에서 AI를 사용해서 개발할 때 가장 결정적인 차이는 뭘까요? 개인적인 경험으로는 후자에서는 ‘내가 아는 걸 AI가 모르는 경우가 훨씬 많다’라는 것입니다. 전자의 경우 보통 스펙을 기반으로 이러저런 걸 만들어줘 하면 되고, 현 시점의 에이전트들은 자신의 지식으로 (제가 써본 적도 없는 기술스택으로) 그런 지시를 너무 잘 수행해냅니다. 그러나 어떤 도메인, 어떤 직무든 간에 실제 업무에서는 AI 등장 훨씬 전부터 존재하고 있던 배경과 지식과 함정들이 많죠.

예를 들면… A라는 정보가 a 테이블에도 있고 b 테이블에 있는데 a는 정합성이 떨어지니 b 것을 봐야 한다 라든지. 아니면 이 모듈의 구현은 무슨무슨 외부 제약에 의해 일시적으로만 이렇게 되어 있다든지. 아니면 이 배치의 결과는 무슨무슨 중요 잡에서 참조하기에 잘못 건드리면 개 큰 스노우볼이 굴러온다든지.

이런 컨텍스트가 제대로 제공되지 않을 때, 코드만 봐서 알 수 없는 내용이라면 개발자는 항상 이 모든 지식을 구구절절 써서 떠먹여 줘야 하고, 코드에 있는 내용이라도 코드베이스 크기와 복잡도에 따라 AI가 허허벌판을 열심히 헤매면서 피같은 토큰을 흩뿌리는 꼬라지를 보고 있어야 하죠. 어느 쪽이든 답답해서 못 해먹을 노릇입니다. 최악인 건 그 모든 고생과 낭비의 결과물이 세션이 끝나면 사라진다는 것이고요.

그래서 저는 AI를 업무에 본격적으로 사용하게 되면서 제 나름의 컨텍스트 저장소를 관리하려고 나름 시도를 했었습니다. 하지만 최신화 업데이트가 잘 되지 않았고, 혼자 얼렁뚱땅 쓰다보니 규모를 크게 키우지는 못하고 있었는데요. 그러다가 팀에서도 니즈가 있다는 사실을 알게 되어 최근에 팀 단위의 공유 지식 베이스를 구축하게 되었습니다. 지식 베이스라고 하니 말은 거창한데 사실 별 건 없고, 그냥 ‘나는 알고 AI는 모르는 지식’ 모아놓은 곳이라고 할 수 있겠네요.

어떻게 공유할까

지식이 생산되는 곳과 필요한 곳에 대한 고민

당연히 가장 먼저 마주친 질문은 “지식을 어디에 둘 것인가"였습니다. 처음엔 각 프로젝트 레포에서 연관된 스펙 문서들을 작성하려 했습니다. 문제는 다 그렇지는 않지만 여러 프로젝트에서 공통적으로 필요한 지식이 분명히 존재한다는 것이었죠.

예를 들면 어떤 데이터의 명세는 배치 잡으로 돌아가는 코드가 그 원천이지만, 모델을 학습할 때도, API로 서빙될 때도 그 데이터에 대한 정보가 필요하고, 거꾸로는 그 배치를 고칠 때 소비하는 다운스트림에 어떤 영향이 가는지도 알아야 합니다. 지금까지는 그게 대체로 다 사람 머릿속에 들어 있었거든요. 이런 정보들은 분명 공유되는 중앙 레포지토리로 갈 필요가 있습니다. 물론 특정 프로젝트 안에서만 의미 있는 컨벤션이나 구현 디테일까지 굳이 중앙화하여 관리할 필요는 없습니다.

지식 소비는 효율적으로, 추가 노력 없이

그러면 결국 중앙에 공유 지식 베이스가 있고 각 프로젝트 레포에서 작업할 때 그걸 참조하는 방식이 됩니다. 이때 가장 중요한 것은 각 프로젝트에서 AGENTS.md/CLAUDE.md가 지식 베이스에 대한 적절한 포인터 기능을 하도록 하는 것입니다. 지식 베이스에는 수많은 문서가 있기 때문에 이를 잘 설정해두지 않으면 효율적인 탐색이 어렵습니다. 연관된 작업을 할 때만 필요한 정보를 온디맨드로 로드하는 것이 핵심입니다.

예를 들면,

• API 개발에서 데이터 I/O를 다루는 부분을 변경할 때는 서빙 데이터 스펙 문서를 봐
• 배치 잡의 스케줄이나 재처리 로직을 건드릴 때는 테이블 리니지 문서를 봐
• 특정 로그는 A 라이브러리로 읽어야 하니 해당 라이브러리 관련 문서를 봐

또 Git 레포로 지식 베이스를 만들게 되면, 각 팀원의 로컬 개발 환경에서 각자 이것의 최신 버전이 어떻게 읽히도록 할 것인지도 좀 고민이 되는 문제였습니다. 무엇보다 에이전트 세션은 프로젝트 단위로 열리니까요. 주변에 물어보고 서치도 해보니 여러 레포 간 cross 참조가 필요할 때는 하나의 dev container 안에 여러 레포를 같이 두고 개발하는 경우도 많더군요. 개인적으로는 어떤 특수한 구조를 각 팀원에게 강제할 수는 없다고 생각했습니다. 아무리 작은 거라도 뭔가 세팅을 직접 해야 되면 다르게 할 가능성이 높고 귀찮아지고 누구 새로 오면 또 알려줘야 되고 그렇잖아요? 공유 자체가 각자의 워크플로우에 얹히는 추가 부담이 되어서는 안 되는 거죠. 그래서 그냥 각 프로젝트 레포에서 session start hook을 설정해서, 세션 시작할 때마다 지식 베이스 레포를 pull해서 로컬에 최신 정보를 유지하는 방식을 선택했습니다. 아직까지는 잘 작동하는 것 같습니다.

마지막으로 지식 베이스 탐색용 스킬은 기본적으로 하나 있어야 합니다. 그래야 사람이 직접 찾거나 명시적으로 시키지 않아도 세션 중에 에이전트가 자연스럽게 헤매지 않고 필요한 정보를 물어오거든요. 스킬 지침은 “이런 종류의 질문이 오면 이런 순서로 찾아라"라는 탐색 경로를 조건별로 가이드해줍니다.

예를 들면 데이터 탐색 시에는 이런 식으로:

• 테이블명을 알고 있을 때 → 상세 스펙 파일을 바로 찾아 읽는다
• 테이블명이 명확하지 않을 때 → 이 인덱스 문서에서 이름으로 grep
• “이런 성격의 데이터가 있었던 것 같은데” 식으로 도메인/주제로 탐색할 때 → 이 도메인 문서를 거쳐 후보 테이블을 좁힌다
• “스케줄이 hourly인 로그성 테이블 중에 뭐가 있지” 같은 속성 조건으로 탐색할 때 → 이 인덱스 문서를 속성값으로 grep
• 데이터의 리니지 관련일 때 → frontmatter의 어떤 필드를 따라간다(DAG)

몇 번 써보면서 사실 스킬 내용보다는 지식 베이스의 퀄리티가 더 중요하다는 인상을 받았습니다. 아래 어떻게 작성할까 섹션에서 언급하겠지만 에이전트가 잘 탐색할 수 있는 구조와 형식으로 만들면 스킬에는 간단한 수준의 가이드만 있어도 정확도 높게 정보를 찾아낼 수 있습니다.

어떻게 업데이트할까

아무리 체계화되고 질 좋은 정보로 가득 찬 공유 지식 베이스를 만들었다 한들 그게 최신으로 유지될 수 있는 방법이 없으면 동작하지 않을 겁니다. 여러 프로젝트에서 팀원들이 각각 열심히 작업을 하면서 매일 새로운 변경사항이 발생하니까요. 낡은 문서는 가끔 없는 것만도 못할 때가 있기 때문에, 지식을 업데이트하는 것이 공유만큼이나 중요한 설계의 절반이었습니다.

귀찮으니까 자동으로, 단 최소한의 human-in-the-loop

여러분 이거 스펙 바꾸면 문서도 반드시 업데이트 부탁드려요 🙏

…가 되겠나요. 처음 한 두번은 해줄 수 있어도, 바빠 죽겠는데 업무를 하나 더하는 이런 규칙이 준수될 리 없습니다. 그래서 업데이트는 사람에게 맡기면 안 됩니다. 사람은 원래 하던 대로 각자 프로젝트 레포에서 코드를 바꾸고 PR을 머지할 뿐이고, 그 변경이 공유 지식에 영향을 주는지 판단하고 문서를 갱신하는 일은 AI가 해야 합니다. 한창 핫했던 카파시의 LLM wiki도 이런 아이디어였죠. AI는 귀찮아하지도 까먹지도 지치지도 않는다고요.

구체적으로는 GitHub Actions로 돌립니다. 프로젝트 레포에서 어떤 변경이든 머지되면, 그 레포는 repository_dispatch 이벤트(레포명 + 머지 SHA)만 지식 베이스 레포로 던집니다. 지식 베이스 레포 쪽 워크플로우가 그 SHA 범위를 checkout해서 diff를 분석하고, 관련 문서를 갱신할 필요가 있으면 새 브랜치와 PR을 알아서 만듭니다.

주요 포인트는 이렇습니다.

• 스케줄이 아닌 트리거 방식: 변경 추적이 효율적이고 정확히 필요한 시점에 업데이트, 단 변경사항이 ‘머지될 때’를 기준으로 하여 확정적인 스펙 변경이 발생할 때만 업데이트
• 트리거와 업데이트 책임은 확실히 분리: 각 프로젝트 레포는 트리거만, 지식 베이스 레포에서 실제 업데이트를 담당해서 프로젝트가 늘어나도 반복되는 워크플로/시크릿/프롬프트 설정 복붙 부담이 없게
• 공통된 지침을 마련해 두기: 지식 베이스 레포의 CONTRIBUTING.md가 만약 A 레포에서 뭐가 바뀌면 뭐뭐뭐를 확인한다 수준의 세밀한 프롬프트로 제공하여 업데이트의 품질을 보장

이렇게 해서 워크플로우가 생성한 지식 변경 PR은 슬랙으로 알림이 가고, 원래 변경을 만든 코드 작업자가 이를 리뷰한 뒤 최종 머지합니다. 마지막 게이트에 사람을 앉힌 이유는 어쨌든 공유 지식은 최소한의 품질이 보장되어야 하기 때문입니다.

참고로 지금까지 경험 상 AI가 코드 분석을 잘못 해서 ‘틀린’ 지식을 추가하거나, 발생한 변경을 ‘누락’한 적은 없습니다. 다만 너무 구현단의 지식을 소비관점의 설명서에 넣으려고 했다든가 하는 미묘한 방향성 판단이 맞지 않아 인간이 개입한 적은 한두 번쯤 있네요. 대체로는 추가 작업 없이 바로 머지가 되는 편입니다.

어떻게 작성할까

공유/업데이트 사이클 외에도 중요한 마지막 주제는 지식 문서(.md)가 실제 어떤 형식과 구조로 되어있는지입니다. 팀에서 필요한 지식들은 모델/데이터/API 스펙부터 파이프라인/아키텍처 구조도와 히스토리성 문서까지 다양한데요. 저의 경우 팀 업무 상 아무래도 데이터 명세의 비중이 가장 높긴 하지만, 다음 내용은 일반적으로 적용됩니다.

AI가 읽고 탐색하기 편하게

사람이 읽고 확인할 때도 있지만 대체로 이 문서들의 소비자는 에이전트가 될 것입니다. 따라서 AI가 얼마나 쉽고 효율적으로 탐색할 수 있을지를 고민하면서 템플릿을 만들어가는 게 좋습니다.

우선 핵심적인 메타데이터를 항상 frontmatter로 분리하는 것이 좋고요. 테이블 명세라고 한다면 그레인(grain), PK, 파티션, 스케줄, 업스트림 소스, 다운스트림 서빙 대상 같은 항목들을 필드로 삼습니다. 이렇게 구조화해 두면 전체를 한 줄씩 스캔 가능한 인덱스를 기계적으로 뽑아낼 수 있기에, “a_id가 PK인 테이블이 뭐뭐 있지?” 같은 광역 질문에도 효율적으로 대답할 수 있습니다.

최대한 파싱 가능한 문법을 활용하도록 하는 것도 도움이 됩니다. 예를 들어 업스트림 소스를 db.table:D-7~D 같은 고정 문법으로, 산출물을 스토어별 프리픽스로 표준화해서 표기하려고 했습니다. “이 테이블의 최근 7일치 데이터를 본다"고 문장으로 써두면 사람은 이해하기 좋지만, 에이전트가 업스트림/다운스트림을 자동으로 순회하는 데는 간단하게 파싱할 수 있는 방식이 더 낫습니다. 특히 “이 칼럼 바뀌었는데 뒤 테이블에 반영되려면 몇일치 재처리 해야 돼?” 같은 lineage 파악이 필요한 과제를 grep 한 줄로 풀 수 있습니다.

에이전트가 스펙들을 탐색할 때 타고 들어갈 순서를 고려해서 문서 구조를 설정해야 합니다. 예를 들면 큰 도메인 단위의 요약 문서를 일종의 인덱스(진입점)처럼 만들어서, 먼저 그것을 읽고, 어떤 세부 문서들이 있는지 파악한 뒤 정말 필요한 해당 문서를 읽도록 하는 방식이 될 수 있겠죠. 이렇게 레이어를 분리하지 않으면 처음부터 내용이 긴 세부 스펙 문서를 다 읽어야 해서 탐색이 비효율적이고 컨텍스트가 낭비됩니다.

역시 사람의 터치는 어느 정도 필요했다

업데이트 사이클에도 마지막에 사람의 검수 단계를 넣어둔 것처럼, 맨 처음 스펙 문서를 일괄 생성할 때도 제 예상보다 훨씬 더 사람 손맛이 필요하더군요. 코드로 파악할 수 있는 것들은 AI를 돌렸지만(2-3회의 독립적인 서브에이전트로 검수 병행), 코드에서 추출할 수 없는 지식은 최대한 수작업으로 넣어줬었습니다. 계속 사용하면서도 보완점은 나오기 마련인데, 팀 단위 컨텍스트라면 같이 만들어가는 것이 바람직할 것 같습니다.

마무리

그래서 이거 만드니까 좋았나요?

라고 묻는다면 모든 면에서 이전보다 훨씬 편해졌다고 단언할 수 있습니다.

• 개발 중 필요한 정보를 알아서 잘 찾아 줌. 특히 쿼리 작성을 기막히게 하고, 로컬에서 접근이 되는 DB는 조회용 에이전트도 정의해서 잘 쓰는 중.
• 지금 변경하고 있는 부분의 cross-project 영향도를 대체로 알아서 생각해 줌 (커밋하려고 했더니 잠깐! 이거 고치면 어쩌구 배치 시간도 바꿔야 하는데요? 라고 해서 약간 감동함)
• 광역적인 스펙 질문뿐 아니라 내가 만들어서 사람들이 나한테 물어보는데 나는 전혀 기억나지 않는 무언가도 즉각 잘 대답해줌 (“이 모델에서 학습 유저는 전체 대상인가요 아니면 특정 조건으로 필터링을 하신 건가요?” “아아아ㅏ잠시만요” 클로드야 도와줘 ..)
• 그냥 무엇보다 이전에 백번 말해줘야 되던 거 안 해도 돼서 입이(아니 손이) 안 아픔

올해 뭐 컨텍스트 엔지니어링, 하네스 엔지니어링 등 말이 많았고 자꾸 바뀌고 있지만 사실 거창하게 생각할 필요는 전혀 없습니다. 나 혹은 우리 팀에 필요한 지식을 효율적인 방법으로 먹여줄 수 있는 구조를 만드는 것은 작게부터 시작해볼 수 있는 일이고, 어쨌든 에이전트와 함께 개발을 한다면 필수적인 기반이 아닐까 합니다.