에이전트가 같은 삽질을 반복하지 않게: 운영 LLM Wiki 실험기

요약

LLM Wiki를 처음 만들 때는 “중요한 내용을 잘 저장해두자” 정도로 생각했다. 그런데 에이전트들을 실제로 굴리다 보니, 단순히 문서를 많이 쌓는 것보다 더 중요한 문제가 보였다.

이 기록은 개념인가, 질문의 답인가, 반복 절차인가, 운영 정책인가, 아니면 나중에 이유를 다시 물을 결정인가?

이 구분을 하지 않으면 Wiki는 금방 “좋은 말이 많이 적힌 메모장”이 된다.

이번 글은 concept 중심으로 쌓이던 운영 Wiki가 query, procedure, policy, decision으로 분화되면서 에이전트 운영의 기억 장치가 되어가는 과정을 정리한 실험기다.

(참고로 이 위키는 이번 스터디 참여 전 구축한 것으로, 스터디 후에 더 발전된 위키를 구축할 수 있기를 기대하고있다. 뻘짓 상황을 공유하고자 올림.)

초기 상태: concept만 쌓이는 Wiki

초기 운영 Wiki는 대략 이런 구조였다.

ops-wiki/
├── SCHEMA.md
├── index.md
├── log.md
├── entities/
├── concepts/
├── raw/
└── META-wiki-handoff.md

처음에는 이 정도로도 충분해 보였다.

예를 들면 이런 문서들이 쌓였다.

Claude Code 같은 도구 설명
ACP integration 패턴
session resume 방식
tool-use enforcement 개념
agent handoff 기준
profile HOME 해석

이 단계의 Wiki는 “운영 중 알게 된 개념과 패턴을 쌓는 곳”이었다.

그리고 실제로 도움이 됐다. 에이전트가 한 번 겪은 설정 문제나 도구 연결 방식을 다음에 다시 볼 수 있었고, 실패한 사건도 raw/worklog로 남기기 시작했다.

하지만 곧 한계가 보였다.

문제: 중요한 것들이 전부 같은 종류가 아니었다

운영하면서 생긴 기록들은 겉보기에는 모두 “중요한 지식”이었다. 하지만 실제 성격은 달랐다.

초기에는 이런 것들이 concepts/에 섞이기 쉬웠다.

그러면 나중에 문제가 생긴다.

에이전트가 “따라야 하는 규칙”과 “읽고 이해하면 되는 설명”을 구분하지 못한다.
반복 절차가 매번 다시 설명된다.
왜 그렇게 결정했는지 로그 속에 묻힌다.
사용자가 다시 물어본 질문의 답을 또 새로 정리한다.
결국 사용자가 매번 “그거 Wiki에 남겨”, “query로 넣어”, “다른 에이전트도 보게 해”라고 지시해야 한다.

즉, 문제는 문서가 부족한 것이 아니었다.

문서 타입을 제대로 나누지 않아서, 다음 에이전트가 무엇을 행동 기준으로 삼아야 하는지 흐려지는 것이 문제였다.

첫 전환점: Wiki 자체를 health check하다

운영 중간에 Wiki 자체를 점검했다. 점검 결과는 꽤 명확했다.

깨진 wikilink가 있었다.
실제 사용 tag와 SCHEMA의 tag taxonomy가 어긋났다.
raw source에 hash가 빠진 파일이 있었다.
가치 있는 질의 결과를 queries/에 남기는 습관이 약했다.
정기적인 lint 루틴이 필요했다.

이때부터 Wiki는 “내용을 담는 곳”이 아니라 “관리해야 하는 시스템”이 됐다.

특히 query 문제가 중요했다. 에이전트는 질문에 답하는 데는 익숙하지만, 그 답이 나중에도 재사용될 만한지 판단해서 Wiki에 남기는 일은 자동으로 잘 하지 않았다.

그래서 운영 규칙이 하나 생겼다.

다시 도출하기 귀찮은 답변이나 여러 근거를 종합한 판단은 query로 남긴다.

두 번째 전환점: SCHEMA v2와 routing rule

가장 큰 변화는 SCHEMA v2였다.

초기 schema의 page type은 대략 이 정도였다.

type: entity | concept | comparison | query | summary```

이후에는 이렇게 바뀌었다.

type: entity | concept | comparison | decision | query | policy | procedure | summary

이 변화는 단순히 폴더가 늘어난 것이 아니다.

Wiki가 “주제별 문서함”에서 “운영 지식 라우터”로 바뀐 것이다.

이후 문서를 넣을 때는 이런 질문을 먼저 하게 됐다.

이 질문 하나가 꽤 많은 것을 바꿨다.

예전에는 “중요하니까 concepts에 넣자”였다.

이후에는 “이건 policy인가, procedure인가, decision인가?”를 먼저 묻게 됐다.

실제 구조 변화: index가 보여준 분화

변화는 index에서도 확인된다.

초기 index에 연결된 페이지는 총 12페이지 정도였고, 대부분이 Concepts에 몰려 있었다. 예를 들면 Discord routing, Google Calendar 인증, Hermes update checklist, profile cleanup 같은 항목도 모두 concept 쪽에 가까웠다.

이후 SCHEMA v2를 거치면서 index는 이렇게 바뀌었다.

ops-wiki/
├── entities/
├── concepts/
├── comparisons/
├── queries/
├── policies/
├── procedures/
├── decisions/
├── raw/
    ├── conversations/
    ├── sources/
    ├── worklogs/
    ├── incidents/
    └── artifacts
├── reports/
├── scripts/
├── legacy/
└── _backups/

이제 Wiki는 “문서가 많아진 폴더”라기보다, 운영 지식의 상태를 나눠 담는 구조에 가까워졌다.

raw는 끝이 아니라 시작점이다

운영 Wiki에서 raw/는 완성된 지식이 아니다.

처음에는 raw가 단순 보관함처럼 보였지만, 실제로는 지식이 만들어지는 첫 단계에 가깝다.

흐름은 이렇게 잡혔다.

사건 발생
→ raw/worklogs 또는 raw/incidents에 보존
→ 반복 가능하면 procedure로 승격
→ 여러 에이전트가 따라야 하면 policy로 분리
→ 왜 그렇게 했는지 중요하면 decision으로 기록
→ index와 log 갱신

예를 들면:

여기서 중요한 점은 실패를 숨기지 않는 것이다.

실패 로그가 남아야 다음 에이전트가 같은 가설을 덜 반복한다. raw incident는 “망한 기록”이 아니라, 다음 procedure나 policy의 재료가 된다.

lint, backup, log rotation: Wiki를 운영하기 위한 장치들

문서가 늘어나자 사람이 눈으로만 관리하기 어려워졌다.
그래서 세 가지 장치가 붙었다.

1. lint

Wiki lint는 읽기 전용 점검 도구다.

확인하는 것은 이런 것들이다.

frontmatter가 있는가

type과 tag가 schema에 맞는가
깨진 wikilink가 있는가
index에 빠진 문서가 있는가
raw source hash가 어긋나지 않았는가

이건 Wiki를 “읽는 노트”에서 “검사 가능한 지식베이스”로 바꾸는 단계였다.

2. backup

초기에는 git history가 없었다. 그래서 큰 구조 변경 전에는 백업 폴더를 남겼다.SCHEMA 변경, raw layout 변경, procedure 이동, log rotation 전후에 백업을 남겼고, 나중에 사례글을 쓸 때도 이 백업이 구조 변화의 근거가 됐다.

3. log rotation

log.md가 계속 길어지자 월별 legacy log로 돌렸다.

현재 로그는 가볍게 유지하고, 과거 변경 이력은 legacy에 보존하는 방식이다.

에이전트 지침

Wiki가 진짜 운영 장치가 되려면, 에이전트가 그 Wiki를 읽어야 한다.

그래서 여러 에이전트 프로필 지침과 공통 스킬에는 다음과 같은 규칙이 들어갔다.

운영 Wiki 위치를 안다
→ Wiki 관련 작업 전 SCHEMA / index / log를 먼저 본다
→ 운영 Wiki와 연구 Wiki를 혼동하지 않는다
→ 재사용 가능한 운영 지식은 Wiki 저장 후보로 본다
→ 필요하면 policy / procedure / decision / query 중 맞는 타입으로 남긴다

이 Wiki 구조는 정답이 아니다

이 구조가 모든 종류의 Wiki에 맞는다고 생각하지는 않는다. 이 글에서 말하는 운영 Wiki는 꽤 특수한 목적을 가진다.

Hermes 운영 중 에이전트들이 겪은 설정 문제, 인증 문제, 경로 문제, 도구 사용 실수, 복구 절차를 다음 세션에서 다시 찾기 쉽게 만드는 Wiki.

즉, 주된 목적은

에이전트가 같은 삽질을 반복하지 않게 하기
실패 원인과 복구 절차를 다음 세션이 찾게 하기
여러 프로필이 따라야 할 운영 기준을 공유하기
사용자가 매번 같은 설명을 반복하지 않게 하기

그래서 이 Wiki에는 procedure, policy, decision, raw incident 같은 타입이 중요했다.

반대로 일반 독서 노트, 논문 요약, 제품 기획 Wiki, 개인 지식관리 Wiki라면 전혀 다른 구조가 더 맞을 수 있다. 이 사례는 “LLM Wiki 일반론”이라기보다, 에이전트 운영을 위한 사고 방지용 Wiki에 가깝다.

아직 실험 단계인 이유

이 시스템은 아직 완성형이 아니다.

남은 문제가 있다.

1. git history가 늦게 시작됐다

Wiki는 먼저 굴러갔고, git 관리는 나중에 붙었다. 그래서 초기 구조 변화는 git diff가 아니라 log, backup, session log로 복원해야 했다.

2. 여전히 에이전트가 자동으로 잘 저장하지는 않는다

에이전트는 답변을 잘해도, 그 답변이 나중에 재사용될 지식인지 매번 잘 판단하지는 않는다.
그래서 “Wiki 저장 후보로 제안하라”는 규칙이 필요했다.

3. 너무 많이 저장하면 Wiki가 무거워진다

모든 대화를 저장하면 Wiki는 금방 쓰기 어려워진다. 그래서 저장 기준이 필요하다.

일회성 진행 상황은 저장하지 않는다.
다시 도출하기 귀찮은 답변은 query로 남긴다.
반복 절차는 procedure로 승격한다.
여러 에이전트가 따라야 하면 policy로 만든다.
결정의 이유가 중요하면 decision으로 남긴다.

참고가 될 수 있는 프롬프트

아래 프롬프트만으로는 절대 운영 Wiki가 완성되지는 않는다. 필자도 시작은 안드레이 카파시의 llm wiki 파일로부터 시작하였다.

다만 Hermes처럼 여러 에이전트가 운영 중 삽질 기록, 복구 절차, 설정 결정을 다시 찾아야 하는 환경이라면 추가로 다음 내용을 프롬프트로 줘볼 수도 있다.

우리 Hermes 운영 중 반복되는 설정 문제, 실패, 복구 절차, 운영 결정을 Wiki로 남기고 싶어. 목적은 일반 지식관리 Wiki가 아니라, 에이전트들이 다음 세션에서 같은 삽질을 반복하지 않게 하는 거야.단순히 날짜별 로그로 쌓지 말고, 아래 타입으로 나눠서 저장 후보를 판단해줘.
- concept: 읽고 이해하면 되는 운영 개념
- query: 다시 도출하기 귀찮은 질문/조사 결과
- procedure: 순서대로 실행할 복구·설정 절차
- policy: 여러 세션이나 에이전트가 따라야 할 운영 규칙
- decision: 나중에 이유를 다시 물을 운영 결정
- raw: 아직 정리 전인 원본 근거, 실패 로그, incident 기록

새 문서를 만들기 전에는 SCHEMA.md, index.md, log.md를 먼저 확인해줘.
작업 후에는 필요한 경우 index와 log를 갱신해줘.
일회성 진행 상황이나 감상은 저장하지 말고,
다음 에이전트가 실제로 다시 찾을 가능성이 있는 운영 지식만 Wiki 후보로 제안해줘.

🔥<24기 AI 스터디> 9/21 모집 마감 🔥

에이전트가 같은 삽질을 반복하지 않게: 운영 LLM Wiki 실험기