에이전트에게 위키를 맡기다 — 스킬 + 스키마 주입

이 시리즈의 마지막 단계입니다. 지난 글에서 봉인된 버킷을 하나씩 집어 오는 소비 루프를 만들었으니, 이제 그 버킷을 실제로 요약해 위키로 바꾸는 소비처를 붙일 차례입니다. 여기서 한 걸음 더 나갔습니다 — 단순히 LLM API를 호출하는 대신, 에이전트에게 '스킬'로 맡겼습니다.

왜 API 호출이 아니라 에이전트인가

버킷 안에는 "무엇이 바뀌었다"는 변경 기록만 있습니다. source·ref·title·url 정도죠. 좋은 요약을 하려면 그걸로는 부족하고, 원문을 직접 열어 내용을 읽어야 합니다. 때로는 관련 문서를 함께 참고해야 맥락이 잡힙니다.

이건 단발 API 호출보다 에이전트가 더 잘합니다. 필요하면 원문을 조회하고, 판단해서 정해진 형식으로 정리하는 일련의 행동이니까요. 마침 팀 서버에는 오픈소스 에이전트(Hermes)가 사내 데이터센터의 GPT-OSS 계열 모델과 연결돼 있었습니다. 이미 있는 이 에이전트에게, 재사용 가능한 작업 지침 = 스킬을 하나 만들어 주기로 했습니다.

지침서부터, 그다음 스킬로

곧장 코드를 짜지 않고 **작업 지침서(샘플)**부터 만들어 방향을 맞췄습니다. 지침서에 담은 요구사항은 이렇습니다.

변경 기록에 그치지 말고 원문까지 열어 지식을 정리한다.
출력은 공개된 llm-wiki 패턴(개인 지식베이스를 LLM으로 정리하는 방식)을 따르고, wiki/docs/ 아래에 저장한다.
처리한 버킷은 archive/로 옮긴다.
반드시 실제로 돌려 보고 결과를 확인한다.

방향이 맞다는 걸 확인한 뒤, 이 지침을 스킬로 옮겼습니다. 스킬은 각 단계를 스크립트로 나눠 순서대로 실행하게 구성했습니다. 이렇게 하니 에이전트가 매번 즉흥적으로 판단하지 않고, 정해진 절차를 밟아 결과가 일정해졌습니다.

스킬은 복사해서 바로 설치할 수 있게 만들었습니다. 에이전트의 스킬 디렉터리에 폴더째 넣으면 끝나도록요. 원문 조회에 필요한 계정·토큰은 코드에 박지 않고 환경 변수로 뒀습니다.

# 에이전트가 원문을 읽을 때 쓰는 자격증명 (.env)
AT_EMAIL=<아틀라시안 계정>
AT_API_TOKEN=<API 토큰>

이 값으로 Jira·Confluence를 API로 직접 조회하니, 별도의 수집 과정 없이 필요한 원문을 그때그때 읽어 옵니다.

출력을 강제하기: SCHEMA 주입

에이전트에게 "요약해 줘"라고만 하면, 매번 형식이 조금씩 다르게 나옵니다. 위키 문서는 구조가 일정해야 사람도, 다음 단계의 검색도 다루기 편합니다.

그래서 원하는 문서 구조를 SCHEMA.md에 적어 두고, 요약할 때 이걸 시스템 프롬프트로 주입했습니다. "이 스키마대로 써라"를 매 호출의 규칙으로 못박은 겁니다.

[시스템 프롬프트] = SCHEMA.md 내용
[사용자 입력]     = 원문 + 변경 맥락
→ 출력: 스키마를 따르는 위키 문서

SCHEMA.md를 어디에 둘지도 고민이었는데, 산출물 폴더(docs/)가 아니라 스킬 디렉터리 안에 뒀습니다. 이건 결과물이 아니라 **스킬의 일부(규칙)**니까요. 규칙과 결과를 같은 폴더에 섞지 않는 원칙은, 앞서 코드와 데이터를 분리한 것과 같은 결입니다.

그리고, 에이전트가 위키를 '쓰게' 하기

위키를 만드는 것과, 그 위키를 활용하는 것은 다른 일입니다. 마지막으로 에이전트에게 "이 docs/ 지식을 근거로 답하라"는 지침(AGENT.md)을 붙였습니다. 채널마다 다른 역할을 주고 싶으면 채널별 프롬프트를 설정으로 분리할 수도 있게 했고요. 이제 같은 에이전트가 지식을 쌓기도 하고, 꺼내 쓰기도 합니다.

문서로 남기기

빌드 과정 자체도 사내 문서(Confluence)에 남겼습니다. 전체 시스템을 도식으로 먼저 그려 두고 시작하니, 나중에 합류하는 사람이 "무엇이 어디로 흐르는지"를 한눈에 잡을 수 있었습니다. 만든 사람에게는 당연한 구조도, 처음 보는 사람에겐 그림 한 장이 열 문단보다 빠릅니다.

정리

변경 기록만으로는 부족하다 → 원문을 직접 열어 정리하는 에이전트 스킬로.
지침서로 방향을 맞춘 뒤, 스크립트를 순서대로 밟는 스킬로 옮겨 결과를 일정하게.
자격증명은 코드가 아니라 환경 변수로, 스킬은 복사·설치 가능하게.
SCHEMA를 시스템 프롬프트로 주입해 출력 형식을 강제, 규칙과 결과는 폴더를 나눈다.
만드는 것으로 끝내지 말고 활용(AGENT.md)과 문서화까지.

시리즈를 마치며

두 번의 시즌에 걸쳐 사내 지식 위키를 만들었습니다.

시즌 1: 1시간 폴링으로 Jira·Confluence를 수집·요약하고, 스크럼봇·QA봇을 얹었습니다.
시즌 2(이번 시리즈): 폴링을 걷어내고 이벤트 기반으로 재구축했습니다 — 슬랙으로 변경을 잡아채고(2편), 5분 버킷으로 안전하게 쌓고(3편), fixedDelay로 밀려도 안 놓치게 소비하고(4편), 에이전트 스킬로 위키를 만들었습니다.

한 번 만든 걸 갈아엎는 건 아깝습니다. 하지만 문제의 진짜 위치(수집 방식)를 찾고 나면, 다시 세우는 게 결국 빠른 길이었습니다. 지식이 "쌓여만 있는" 상태에서 "물어보면 답하는" 상태로 — 그 사이를 잇는 건 화려한 모델이 아니라, 데이터가 흐르는 구조였습니다.