Featured Post

사내 문서 찾느라 하루 날린 적 있다면, Glean으로 슬랙과 개발 문서까지 한 번에 찾는 방법

작성자:
Glean - 사내 지식검색 관련 이미지

안녕하세요. 요즘 날씨가 참 묘하죠. 평일엔 모니터 앞에 붙어 있다가도 주말만 되면 괜히 바다 쪽으로 차를 몰고 싶어지는 계절입니다. 얼마 전에는 강원도 삼척에 잠깐 다녀왔는데요. 바다 앞에 앉아서 아무 생각 없이 파도만 보고 있으니, 아 이래서 사람이 가끔은 멀리 나가야 하는구나 싶더라고요. 그런데 뭐, 월요일 아침이 되면 다시 회사 메신저 알림이 울립니다. 현실 복귀죠.

그 월요일 아침에 제가 또 겪은 일이 있습니다. 분명 예전에 정리해 둔 로그인 API 장애 대응 문서가 있었거든요. 그런데 그게 Notion에 있었는지, Slack 스레드에 있었는지, Jira 티켓 댓글에 있었는지, 아니면 누군가 GitHub PR에 남긴 코멘트였는지 도무지 기억이 안 나는 겁니다. 코딩보다 문서 찾는 데 더 힘을 쓰는 날, 개발자라면 다들 한 번쯤 있잖아요.

저희 팀도 딱 그랬습니다. 히스토리는 쌓이는데, 정보는 여기저기 흩어지고, 신규 입사자가 질문하면 저도 같이 검색창을 열고 헤매는 상황이 반복됐어요. 그때 도입해서 꽤 재미를 본 도구가 바로 Glean입니다. 오늘은 제가 실제로 Glean을 사내 개발 문서, Slack, Custom Wiki와 연동하면서 겪었던 삽질을 좀 편하게 풀어볼게요. 공식 문서에 예쁘게 적힌 이야기가 아니라, 진짜 회사에서 붙여보면서 알게 된 것들 위주입니다.

사내 문서와 개발 정보를 검색하는 노트북 화면

Glean을 써보니, 진짜 문제는 검색창이 아니라 문서가 흩어진 방식이더라고요

Glean을 아주 쉽게 말하면 사내 정보용 Google 검색창에 가깝습니다. Google Drive, Slack, Jira, GitHub, Notion, Confluence 같은 도구들을 하나로 묶고, 그 안에 있는 문서와 대화를 자연어로 찾게 해주는 LLM 기반 엔터프라이즈 검색 도구라고 보면 됩니다.

예전에는 이런 식이었어요.

“로그인 API 에러 핸들링 문서 어디 있지?”

그러면 Slack에서 검색하고, Notion에서 검색하고, Jira에서 검색하고, GitHub PR까지 뒤집니다. 중간에 누가 말을 걸면 흐름이 끊기고요. 다시 기억을 더듬습니다. 그러다 20분쯤 지나면 내가 뭘 찾고 있었는지도 살짝 흐릿해져요. 이게 은근히 사람을 지치게 합니다.

Glean을 붙인 뒤에는 검색 방식이 조금 달라졌습니다. 그냥 검색창에 “로그인 API 500 에러 대응 방식 알려줘”라고 치면, 관련 Slack 스레드, 장애 회고 문서, GitHub PR, Jira 티켓을 한 번에 찾아줍니다. 거기에 문서 요약까지 붙으니 처음에는 살짝 신기하더라고요. 뭐랄까, 머릿속에 흩어진 기억 조각을 누가 대신 꺼내주는 느낌이었습니다.

다만 여기서 끝이 아니었습니다. 저희 회사에는 공식 SaaS 도구 말고도 내부망에 따로 띄워둔 Markdown 기반 Custom Wiki가 있었거든요. 진짜 중요한 개발 가이드, 장애 대응 기록, 오래된 아키텍처 결정 문서들이 오히려 그 안에 많이 있었습니다. Glean 기본 커넥터만 연결해서는 반쪽짜리 검색이 될 수밖에 없었죠.

그래서 결국 Glean Custom Connector API를 이용해서 내부 Wiki 데이터를 직접 밀어 넣는 작업을 했습니다. 그때 만들었던 프로젝트 구조는 대략 이런 식이었어요.

glean-custom-connector/
├── config/
│   └── default.json
├── src/
│   ├── client/
│   │   ├── gleanApiClient.js
│   │   └── wikiApiClient.js
│   ├── sync/
│   │   └── wikiSyncer.js
│   └── index.js
├── package.json
└── README.md

겉으로 보면 단순합니다. 내부 Wiki API에서 문서를 가져오고, Glean이 원하는 스키마로 바꾼 다음, Push API로 보내는 구조예요. 그런데 실제로 해보면 늘 그렇듯이 “그냥 변환해서 보내면 되겠지”가 잘 안 됩니다. 날짜 포맷이 다르고, 작성자 이메일이 비어 있고, 오래된 문서는 HTML이 깨져 있고, 어떤 문서는 제목만 있고 본문이 없고요. 이런 작은 예외들이 쌓이면 배치 동기화가 생각보다 자주 넘어집니다.

Custom Wiki를 Glean API에 붙이면서 제일 많이 삽질한 부분

아래는 내부 Wiki 문서를 Glean에 인덱싱할 때 사용했던 핵심 코드 흐름입니다. 실제 회사 코드 그대로는 아니고, 설명하기 쉽게 줄인 버전입니다. Node.js와 Axios를 썼고, 배치 작업으로 주기적으로 문서를 밀어 넣는 방식이었어요.

const axios = require('axios');
const config = require('config');

async function indexWikiDocument(doc) {
  const gleanEndpoint = `${config.get('glean.apiUrl')}/v1/indexdocument`;
  const apiKey = config.get('glean.apiKey');

  const payload = {
    datasource: "custom_wiki",
    objectType: "wiki_page",
    id: `wiki_${doc.id}`,
    title: doc.title,
    body: {
      mimeType: "text/plain",
      textContent: doc.content
    },
    viewUrl: `https://wiki.internal.company.com/pages/${doc.id}`,
    author: {
      email: doc.authorEmail
    },
    createdAt: new Date(doc.createdAt).getTime() / 1000
  };

  try {
    const response = await axios.post(gleanEndpoint, payload, {
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      }
    });

    console.log(`[Success] Indexed document ID: ${doc.id}`);
    return response.data;
  } catch (error) {
    if (error.response) {
      console.error(`[Error] Failed to index. Status: ${error.response.status}`);
      console.error(`[Detail]`, JSON.stringify(error.response.data));
    } else {
      console.error(`[Network Error]`, error.message);
    }
  }
}

처음에는 이 코드가 계속 400 Bad Request를 뱉었습니다. 로그를 보면 대충 이런 느낌이었어요.

[Error] Failed to index. Status: 400
[Detail] {"message":"createdAt must be a valid epoch timestamp in seconds"}

아, 진짜 이런 에러는 보면 바로 알아차릴 것 같잖아요. 그런데 막상 배치 로그 수백 줄 사이에 섞여 있으면 은근히 놓칩니다. 원인은 createdAt 포맷이었습니다. JavaScript의 Date.getTime()은 millisecond 단위인데, Glean API는 second 단위를 기대하고 있었어요. 그래서 / 1000 처리가 필요했습니다.

이런 건 공식 문서에도 적혀 있긴 합니다. 그런데 실무에서는 문서 한 줄보다 실제 에러 로그 한 번이 더 오래 기억에 남습니다. 저도 그 뒤로 외부 API에 날짜를 보낼 때는 무조건 단위를 먼저 확인하는 버릇이 생겼어요. 여행 갈 때 숙소 체크인 시간을 두 번 확인하는 것처럼요. 별거 아닌데, 안 하면 꼭 문제가 납니다.

Glean 연동할 때 제가 실제로 체크한 항목들

    • id는 반드시 안정적으로 유지하기: 문서 제목이 바뀌어도 같은 문서로 인식되어야 하니, 내부 Wiki의 고유 ID를 기준으로 만들었습니다.
    • viewUrl은 실제 사용자가 접근 가능한 주소로 넣기: 검색 결과를 클릭했는데 권한 오류나 404가 뜨면 신뢰도가 바로 떨어집니다.
    • author.email은 가능하면 비워두지 않기: 나중에 “이 문서 누가 썼지?”를 찾을 때 꽤 중요합니다.
    • 본문은 HTML보다 text/plain으로 시작하기: 처음부터 예쁘게 렌더링하려고 욕심내면 파싱 문제가 늘어납니다. 안정화한 뒤 확장하는 게 낫습니다.
    • 삭제된 문서 처리도 따로 만들기: 인덱싱만 하고 삭제 반영을 안 하면, Glean에 유령 문서가 남습니다.

특히 삭제 문서 처리는 처음에 대충 넘겼다가 한 번 크게 당했습니다. 내부 Wiki에서는 삭제된 문서인데 Glean 검색에는 계속 떠 있는 거예요. 신규 입사자가 그 문서를 보고 예전 방식대로 설정했다가 테스트 환경이 꼬였습니다. 그날 이후로 동기화 작업에는 삭제 이벤트와 만료 정책을 꼭 넣습니다. 경험이라는 게 참, 좋게 말하면 배움이고 솔직히 말하면 대가를 치른 기억이죠.

Glean 도입 전후, 체감 차이는 꽤 컸습니다

도구 하나 붙였다고 팀 문화가 하루아침에 바뀌진 않습니다. 그래도 검색 시간이 줄어드는 건 확실히 체감됐어요. 특히 운영 장애가 났을 때, 예전 회고 문서나 관련 Slack 논의를 빨리 찾아내는 게 생각보다 큰 차이를 만들었습니다.

구분 Glean 도입 전 Glean 도입 후
검색 위치 Slack, Notion, Jira, GitHub, 내부 Wiki를 각각 열어야 했습니다. 검색창 하나에서 대부분의 정보를 같이 찾을 수 있었습니다.
검색 방식 정확한 키워드를 기억해야 했고, 용어가 다르면 못 찾는 경우가 많았습니다. 자연어로 물어봐도 관련 문맥을 어느 정도 찾아줬습니다.
장애 대응 시 예전 장애 회고를 찾느라 10분 넘게 걸릴 때가 있었습니다. 비슷한 장애 기록과 담당자 코멘트를 1분 안에 찾는 경우가 많았습니다.
신규 입사자 온보딩 “그 문서 여기 있어요” 하면서 링크를 계속 전달했습니다. 검색어와 필터 사용법만 알려줘도 스스로 찾아가는 비율이 늘었습니다.

제가 제일 좋았던 건 신규 입사자 온보딩 쪽이었습니다. 예전에는 새로운 분이 오면 슬랙으로 링크를 열 개쯤 던져드렸어요. “이건 개발 환경이고요, 이건 배포 가이드고요, 이건 장애 대응이고요, 아 이건 조금 오래됐는데 참고만 하세요.” 말하는 저도 헷갈리고, 듣는 분은 더 힘들었을 겁니다.

Glean을 붙인 뒤에는 “검색할 때 type:document 배포 가이드나 custom_wiki 로그인 API처럼 쳐보세요” 정도로 안내가 바뀌었습니다. 물론 처음부터 완벽하진 않았습니다. 그래도 링크 전달자로 살던 선임 개발자들의 피로가 꽤 줄었어요. 이건 꽤 큰 변화입니다.

LLM 검색이라고 다 믿으면 안 됩니다, 검색 품질은 결국 데이터 습관에서 갈립니다

요즘 LLM 도구가 워낙 똑똑해 보이다 보니, 도입하면 알아서 정리해주고 알아서 답해줄 거라고 기대하기 쉽습니다. 저도 처음엔 살짝 그랬습니다. 그런데 실무에서는 그렇지 않더라고요. AI 검색은 좋은 데이터를 더 잘 찾게 해주는 도구이지, 엉망인 데이터를 깨끗하게 만들어주는 청소부는 아닙니다.

가장 난감했던 사례가 Slack 잡담 노출이었습니다. 예를 들어 어떤 모듈 이름을 검색했는데, 공식 문서보다 Slack에서 누군가 농담처럼 남긴 “이거 버그 너무 많아서 당분간 쓰지 말죠 ㅋㅋ” 같은 메시지가 위에 뜨는 겁니다. 그 말이 당시에는 맞았을 수도 있지만, 지금은 패치가 끝난 상태였어요. 신규 입사자가 그걸 보면 공식적인 판단처럼 받아들일 수 있습니다. 꽤 위험하죠.

그래서 저희는 검색 품질을 높이기 위해 몇 가지 기준을 잡았습니다.

    • 공식 문서 저장소에 높은 가중치 주기: 내부 Wiki, Notion의 공식 개발 가이드, 운영 매뉴얼을 우선 노출되도록 조정했습니다.
    • Slack은 채널별로 다르게 보기: 공지 채널과 장애 대응 채널은 포함하되, 잡담 성격이 강한 채널은 제외하거나 낮은 가중치로 뒀습니다.
    • 오래된 문서에는 상태 태그 붙이기: 더 이상 쓰지 않는 문서 제목에는 [DEPRECATED], [이관됨], [참고용] 같은 태그를 붙였습니다.
    • 문서 소유자 정하기: 중요한 운영 문서는 담당 팀이나 담당자를 메타데이터로 넣었습니다. 나중에 검증할 때 정말 편합니다.
    • 검색 결과 피드백 루프 만들기: 엉뚱한 결과가 상위에 뜨면 그냥 웃고 넘기지 않고, 왜 떴는지 보고 가중치나 문서 상태를 조정했습니다.

여기서 제가 확실히 느낀 게 있습니다. Glean 같은 AI 검색 도구를 잘 쓰는 팀은 문서를 많이 쓰는 팀이 아니라, 문서의 상태를 관리하는 팀입니다. 문서가 오래됐는지, 지금도 유효한지, 누가 책임지는지 정도만 관리해도 검색 품질이 확 달라집니다. 이건 좀 귀찮아도 해볼 만합니다.

바이브 코딩으로 Glean 연동할 때, 프롬프트를 이렇게 주면 덜 헤맵니다

저도 요즘은 코딩할 때 LLM 도움을 많이 받습니다. 예전 같으면 API 문서 열어놓고 한 줄씩 맞춰봤을 텐데, 이제는 초안 작성이나 에러 원인 추적은 AI에게 꽤 맡기는 편이에요. 다만 그냥 “Glean API 연동 코드 짜줘”라고 하면 결과물이 애매합니다. 돌아갈 것처럼 생겼는데, 막상 실무에 넣으면 빠진 게 많아요.

제가 써보고 괜찮았던 프롬프트는 이런 식입니다.

Node.js 환경에서 내부 Wiki 문서를 Glean Custom Connector API로 동기화하는 배치 스크립트를 작성해줘.

조건:
1. Wiki API에서 page 목록을 가져온다.
2. 각 page를 Glean indexdocument payload 형식으로 변환한다.
3. createdAt은 epoch second로 변환한다.
4. authorEmail이 없으면 fallback 이메일을 사용한다.
5. 400, 401, 429, 500 에러를 구분해서 로그를 남긴다.
6. 429가 발생하면 exponential backoff로 재시도한다.
7. 삭제된 문서를 처리할 수 있도록 deleteDocument 함수도 분리한다.
8. 설정값은 config/default.json에서 읽는다.

코드는 운영 배치에 넣을 수 있게 함수 단위로 나누고, 테스트하기 쉬운 구조로 작성해줘.

이렇게 조건을 구체적으로 주면 결과가 훨씬 나아집니다. 특히 에러 코드별 처리, 재시도 정책, 삭제 문서 처리를 프롬프트에 넣는 게 중요합니다. AI는 기본적으로 예쁜 성공 케이스 코드를 잘 만듭니다. 그런데 운영 코드는 실패했을 때의 태도가 더 중요하거든요. 저는 이 부분을 꼭 요구합니다.

반대로 피해야 할 프롬프트도 있습니다.

Glean 연동 코드 만들어줘.

이렇게 던지면 대체로 그럴듯한 샘플은 나옵니다. 하지만 인증 방식이 회사 환경과 안 맞거나, pagination이 빠져 있거나, rate limit 처리가 없거나, 삭제 동기화가 빠진 경우가 많습니다. 그러면 나중에 사람이 다시 다 고쳐야 합니다. AI에게 일을 맡기려면, 일을 잘게 쪼개서 시키는 게 좋습니다. 사람한테 업무 요청할 때랑 비슷해요. “이거 알아서 해줘”보다 “여기까지는 이렇게, 예외는 이렇게 봐줘”가 훨씬 낫습니다.

운영에 넣기 전에 꼭 봐야 하는 현실적인 부작용들

Glean이 편한 건 맞습니다. 하지만 회사 안의 정보를 한곳에 모으는 도구라서, 조심해야 할 부분도 분명히 있습니다. 저는 이걸 안 보고 기능만 밀어붙이면 나중에 보안팀이나 법무팀과 긴 대화를 하게 된다고 생각합니다. 긴 대화요. 좋은 의미의 긴 대화는 아닐 때가 많고요.

권한 동기화가 검색 품질보다 먼저입니다

가장 중요한 건 권한입니다. 원래 볼 수 없는 문서가 검색 결과에 보이면 안 됩니다. 검색 결과 제목만 노출돼도 문제가 될 수 있어요. 예를 들어 인사 평가 관련 문서 제목이나 보안 취약점 분석 문서 제목이 권한 없는 사람에게 보인다면, 본문을 못 봐도 이미 사고입니다.

그래서 Custom Connector를 만들 때는 문서 본문만 보내지 말고, ACL이나 권한 그룹 정보를 어떻게 반영할지 꼭 같이 설계해야 합니다. 저희도 초반에는 “일단 인덱싱부터 해보자”로 시작했다가, 권한 모델을 다시 맞추느라 구조를 한 번 손봤습니다. 급할수록 이 부분은 먼저 보는 게 낫습니다.

오래된 문서가 똑똑하게 다시 살아나는 문제

AI 검색이 무서운 점은 오래된 문서도 너무 잘 찾아준다는 겁니다. 예전에는 깊숙이 묻혀 있어서 아무도 안 보던 3년 전 배포 가이드가, 어느 날 검색 결과 상단에 올라올 수 있습니다. 그 문서가 지금도 맞으면 다행인데, 보통은 아닙니다.

이 문제를 줄이려면 문서에 상태를 넣어야 합니다. 저는 아래처럼 최소한의 메타데이터라도 넣는 걸 좋아합니다.

{
  "status": "active",
  "owner": "platform-team",
  "lastReviewedAt": "2025-01-15",
  "deprecated": false
}

이런 메타데이터가 있으면 나중에 검색 필터나 가중치 조정에 써먹을 수 있습니다. 특히 lastReviewedAt은 꽤 유용합니다. 오래된 문서가 무조건 나쁜 건 아니지만, 오래됐다는 사실은 사용자에게 알려줘야 합니다. 여행 블로그에서 5년 전 맛집 가격표를 그대로 믿으면 곤란한 것처럼요.

비용과 운영 부담도 생각보다 중요합니다

Glean 같은 엔터프라이즈 도구는 개인용 앱처럼 가볍게 붙이고 끝나는 느낌은 아닙니다. 라이선스 비용도 있고, 커넥터 유지보수도 있고, 보안 검토도 있습니다. 내부 Wiki 스키마가 바뀌면 커넥터도 같이 고쳐야 하고요. API rate limit이나 배치 실패 알림도 봐야 합니다.

저라면 작은 팀에서 바로 전사 도입을 밀어붙이기보다는, 개발 조직 하나나 플랫폼 팀부터 PoC를 해보는 쪽을 추천합니다. 한 달 정도만 써봐도 감이 옵니다. “이거 우리한테 진짜 필요하구나” 혹은 “우리는 먼저 문서 정리부터 해야겠구나”가 꽤 선명하게 보입니다.

제가 실제로 쓰는 Glean 검색 습관 몇 가지

도구는 결국 손에 익어야 제값을 합니다. 저는 Glean 검색창을 쓸 때 그냥 단어 하나만 던지기보다, 약간의 필터를 같이 붙이는 편입니다. 처음엔 귀찮은데 익숙해지면 훨씬 빠릅니다.

상황 제가 자주 쓰는 검색어 이렇게 쓰는 이유
내가 예전에 쓴 문서를 찾을 때 장애 전파 author:me 기억은 나는데 위치가 안 떠오를 때 제일 빠릅니다.
공식 가이드만 보고 싶을 때 type:document 배포 가이드 Slack 잡담이나 임시 논의를 줄일 수 있습니다.
특정 서비스 히스토리를 볼 때 payment-service 장애 회고 장애 기록, PR, Jira 티켓을 함께 훑기 좋습니다.
오래된 문서를 피하고 싶을 때 로그인 API -DEPRECATED 폐기된 문서가 섞이는 걸 줄일 수 있습니다.

작은 팁인데, 검색어에 사람 이름이나 팀 이름을 같이 넣는 것도 좋습니다. 예를 들어 “캐시 만료 platform-team”처럼요. 회사 문서는 결국 사람이 남긴 흔적이라서, 담당 팀이나 작성자 힌트가 들어가면 결과가 훨씬 좁혀집니다.

이런 팀이라면 Glean 도입을 꽤 진지하게 봐도 좋습니다

제가 써본 느낌으로는, Glean은 단순히 “검색 잘 되는 도구”라기보다 흩어진 조직 기억을 다시 꺼내는 도구에 가깝습니다. 특히 개발팀은 코드만큼이나 맥락이 중요하잖아요. 왜 이 구조가 됐는지, 예전에 어떤 장애가 있었는지, 누가 어떤 결정을 했는지. 이런 걸 빨리 찾을 수 있으면 일의 속도가 달라집니다.

이런 팀이라면 한 번쯤 검토해볼 만합니다.

    • 사내 문서가 Notion, Google Drive, Confluence, Slack, Jira, GitHub에 흩어져 있는 팀
    • 신규 입사자 온보딩 때마다 같은 링크를 반복해서 전달하는 팀
    • 장애 대응이나 운영 히스토리를 빠르게 찾아야 하는 플랫폼 팀, SRE 팀, 백엔드 팀
    • 레거시 시스템이 많아서 “왜 이렇게 만들었지?”를 자주 추적해야 하는 조직
    • 문서는 꽤 있는데 검색 품질이 낮아서 사람들이 결국 물어보는 방식으로 일하는 팀

다만 문서가 거의 없거나, 권한 체계가 아직 정리되지 않았거나, 오래된 문서와 최신 문서가 뒤섞여 있는데 아무도 관리하지 않는 상태라면 바로 도입하기보다 준비 작업을 먼저 하는 편이 좋습니다. 좋은 검색 도구는 좋은 문서 습관을 더 빛나게 해줍니다. 반대로 문서 상태가 엉망이면 그 엉망인 상태를 더 빠르게 보여주기도 합니다. 살짝 아프지만, 이것도 필요한 과정이긴 합니다.

솔직히 저는 Glean을 붙이고 나서 퇴근 시간이 매일 한 시간씩 빨라졌다, 이런 드라마틱한 이야기는 못 하겠습니다. 회사 일이 그렇게 호락호락하진 않죠. 그래도 문서 찾느라 짜증 나는 시간이 줄었고, 예전 히스토리를 추적하는 속도는 확실히 좋아졌습니다. 그 정도면 저는 꽤 괜찮은 변화라고 봅니다.

사내 문서 찾다가 하루가 반쯤 날아간 적 있는 개발자, Slack 검색 결과 속에서 길을 잃어본 팀 리더, 온보딩 때마다 같은 설명을 반복하는 DX 담당자라면 Glean 같은 AI 지식 검색 도구를 한 번쯤 진지하게 살펴보셔도 좋겠습니다. 도구 하나가 모든 걸 해결해주진 않지만, 적어도 “그 문서 어디 있더라?”라는 말을 조금 덜 하게 만들어주긴 하니까요. 저는 그 정도만으로도 꽤 고맙더라고요.

👨‍💻

작성자: 20년 경력 IT 전문 아키텍트

실무 개발과 아키텍처 설계를 거쳐 현재는 AI 바이브 코딩과 개발 자동화를 연구하고 있습니다. 직접 삽질하며 깨달은 실전 꿀팁과 에러 극복 사례만 투명하게 공유합니다.

댓글

댓글 쓰기