팀 위키는 왜 방치되는가
팀 위키가 실패하는 이유는 대개 성실함이 부족해서가 아니다. 지식이 생기는 장소와 문서가 저장되는 장소가 다르기 때문이다. 실제 결정은 Slack 스레드에서 나고, 배경 설명은 회의에서 오가며, 구현 이유는 GitHub 이슈나 Linear 티켓에 남고, 최종 안내문은 Notion이나 Confluence에 흩어진다. 그런데 위키는 누군가 시간을 내어 따로 정리해야 한다.
이 구조에서는 문서가 늘어날수록 신뢰가 떨어진다. 새 문서는 생기지만 옛 문서는 갱신되지 않는다. 신규 입사자는 문서를 읽고도 "이게 아직 맞나요?"라고 묻는다. 오래된 정책과 새로운 결정이 동시에 존재하고, 사람들은 결국 위키보다 담당자에게 직접 묻는다.
LLM Wiki는 이 지점을 바꾼다. 팀 위키를 "누군가 정리해야 하는 문서"가 아니라 "AI가 초안을 만들고 사람이 승인하는 시스템"으로 설계한다. Karpathy가 말한 LLM Wiki 패턴의 핵심은 원본 자료를 raw/에 보존하고, LLM이 이를 읽어 구조화된 Markdown 위키를 계속 갱신하는 것이다1. 팀에서는 이 원칙을 Slack, 회의록, 이슈 트래커, 고객 피드백, 제품 문서까지 확장한다.
회사의 raw/는 업무가 발생하는 곳이다
개인 위키에서는 사용자가 직접 자료를 raw/에 넣는다. 팀 위키에서는 그렇게 하면 금방 실패한다. 회사의 원본 자료는 이미 여러 도구 안에서 생기고 있기 때문이다. 따라서 팀용 LLM Wiki는 "자료를 모아 넣는 폴더"보다 "업무 도구에서 원본을 수집하는 입구"로 설계해야 한다. 조직 규모에서는 GitHub, Slack, Linear, 회의록 도구, Google Drive 같은 실제 업무 도구에서 지속적으로 ingest되는 구조가 필요하다는 지적도 같은 맥락이다2.
가장 단순한 폴더 구조는 다음과 같다.
team-wiki/
raw/
slack/
meetings/
issues/
customer-feedback/
product-docs/
assets/
wiki/
projects/
products/
customers/
decisions/
onboarding/
policies/
source-summaries/
index.md
log.md
CLAUDE.md 또는 AGENTS.md중요한 원칙은 raw/를 원본 보관소로 두는 것이다. Slack 대화를 정리해서 저장하지 말고, 가능한 한 원문에 가까운 형태로 저장한다. 회의록도 AI가 요약한 결과만 저장하지 말고, 원 transcript나 참석자 검토본을 함께 보존한다. 이슈 트래커도 제목과 결론만 가져오지 말고, 상태 변경, 댓글, 관련 PR 링크, 담당자 정보를 함께 남긴다.
AI가 수정하는 곳은 wiki/다. 예를 들어 고객 인터뷰 transcript 하나가 들어오면 AI는 wiki/customers/acme.md, wiki/products/admin-dashboard.md, wiki/decisions/pricing-policy-change.md, wiki/source-summaries/2026-05-19-acme-interview.md를 함께 업데이트할 수 있다. 하나의 원본이 여러 위키 페이지를 갱신하는 것이 정상이다.
팀 ingest 흐름 설계하기
팀 ingest는 단순 요약 작업이 아니다. 원본을 읽고, 기존 위키와 연결하고, 변경이 필요한 페이지를 찾아 초안을 만들고, 검수자에게 보내는 흐름이다.
기본 흐름은 다음과 같다.
수집: Slack 스레드, 회의록, 이슈, 고객 피드백, 제품 문서를
raw/에 저장한다.정규화: 날짜, 작성자, 채널, 관련 프로젝트, 원본 링크를 메타데이터로 붙인다.
민감정보 점검: 개인정보, API 키, 계약 조건, 비공개 고객명 등 공개 범위를 확인한다.
AI 초안 생성: AI가 관련 위키 페이지를 찾고, 새 내용이 들어갈 위치를 제안한다.
변경안 리뷰: 담당자가 diff를 보고 승인, 수정, 반려한다.
반영과 기록: 승인된 내용만
wiki/에 반영하고log.md에 남긴다.
팀 위키에서 가장 가치 있는 페이지는 "결론"만 담은 페이지가 아니다. 결정 배경, 변경 이유, 담당자, 관련 링크가 함께 있는 페이지다. 예를 들어 의사결정 기록 페이지는 다음 항목을 가져야 한다.
---
type: decision
status: approved
owner: product-lead
created: 2026-05-19
updated: 2026-05-19
sources:
- raw/meetings/2026-05-19-pricing-sync.md
- raw/slack/pricing-thread-2026-05-18.md
related:
- wiki/products/pricing.md
- wiki/customers/enterprise-segment.md
---
## 결정
엔터프라이즈 플랜의 최소 계약 기간을 6개월에서 12개월로 변경한다.
## 배경
최근 3건의 고객 인터뷰에서 초기 구축 지원 비용이 반복적으로 문제로 제기되었다.
## 근거
- 고객 A는 온보딩 기간이 평균 8주 이상 걸린다고 말했다.
- 세일즈 팀은 6개월 계약에서 지원 비용 회수가 어렵다고 보고했다.
## 영향
- 가격 페이지 수정 필요
- 영업 FAQ 수정 필요
- 기존 고객 갱신 정책은 별도 검토 필요
## 검토 필요
- 법무팀 계약서 문구 확인
- 고객 성공팀의 온보딩 리소스 재계산이런 페이지가 쌓이면 팀은 같은 질문을 반복하지 않는다. "왜 이렇게 결정했지?"라는 질문에 매번 Slack을 뒤지지 않아도 된다. 위키가 답을 새로 조합하는 것이 아니라, 이미 정리된 결정의 지도를 제공한다.
회의록은 끝이 아니라 시작이다
회의 AI 도구는 요약과 액션 아이템을 잘 뽑아준다. 하지만 회의 요약은 그대로 믿기에는 위험하다. 긴 회의 대화는 주제가 흩어지고, 발화자가 바뀌며, 중요한 맥락이 생략될 수 있다. LLM 기반 회의 recap 연구에서도 중요한 세부 사항 누락과 잘못된 귀속이 협업에 부정적 영향을 줄 수 있다고 지적한다3.
그래서 팀 위키에서는 회의록을 최종 문서로 보지 않는다. 회의록은 ingest의 원본이다. AI는 회의록에서 다음을 추출한다.
결정된 사항
보류된 사항
새로 생긴 질문
담당자와 기한
영향을 받는 제품, 고객, 정책, 프로젝트
기존 위키와 충돌하는 내용
그다음 관련 페이지를 업데이트한다. 제품 변경이 결정되면 제품 페이지가 바뀐다. 고객 불만이 확인되면 고객 피드백 페이지가 갱신된다. 정책 예외가 논의되면 정책 페이지에 "검토 중" 상태로 반영된다. 회의록은 한 번 읽고 끝나는 문서가 아니라, 여러 위키 페이지를 업데이트하는 원천 자료다.
온보딩 문서를 파생 문서로 만들기
대부분의 팀은 온보딩 문서를 따로 만든다. 문제는 제품과 조직이 바뀌면 온보딩 문서가 가장 먼저 낡는다는 점이다. 신규 입사자가 읽는 문서일수록 최신이어야 하는데, 실제로는 가장 늦게 갱신된다.
LLM Wiki에서는 온보딩 문서를 독립 문서가 아니라 파생 문서로 설계한다. 제품 페이지, 프로젝트 페이지, 정책 페이지, 의사결정 기록이 갱신될 때 온보딩 문서도 함께 점검된다.
예를 들어 결제 시스템 구조가 바뀌면 AI는 다음 작업을 제안해야 한다.
wiki/products/payments.md업데이트wiki/decisions/payment-provider-migration.md생성 또는 갱신wiki/onboarding/engineering-payments-onboarding.md의 아키텍처 설명 수정wiki/policies/payment-incident-response.md의 담당자와 절차 확인 요청
이렇게 하면 온보딩 문서는 "신규 입사자를 위해 따로 정리하는 문서"가 아니라 팀 지식의 최신 상태를 반영하는 입구가 된다. 신규 입사자는 오래된 가이드가 아니라 현재 팀이 실제로 일하는 방식을 읽게 된다.
AI는 초안 작성자, 사람은 책임자
팀 위키에서 AI에게 모든 권한을 주면 안 된다. AI는 초안 작성자와 연결 정리자 역할에 강하다. 긴 회의록에서 핵심을 뽑고, Slack 스레드와 이슈를 연결하고, 관련 위키 페이지를 찾아 변경안을 제안할 수 있다. 반면 최종 판단은 사람이 해야 한다.
사람이 반드시 맡아야 할 일은 네 가지다.
첫째, 출처 확인이다. AI가 요약한 내용이 원문과 맞는지 확인한다. 특히 고객 발언, 법적 표현, 숫자, 계약 조건은 원문 링크를 열어 확인해야 한다.
둘째, 민감정보 제거다. 고객 개인정보, 내부 매출 수치, 보안 취약점, 접근 토큰, 인사 정보는 공유 위키에 그대로 들어가면 안 된다.
셋째, 잘못된 요약 수정이다. AI가 말의 뉘앙스를 잘못 이해했거나, 참석자의 의견을 팀의 결정처럼 썼다면 사람이 고쳐야 한다.
넷째, 공개 범위 결정이다. 어떤 내용은 팀 전체 위키에, 어떤 내용은 리더십 위키에, 어떤 내용은 개인 메모에만 남겨야 한다.
좋은 운영 구조는 "AI 자동 반영"이 아니라 "AI 자동 초안 + 사람 승인"이다. 작은 팀에서는 프로젝트 리드가 승인자일 수 있고, 큰 팀에서는 페이지마다 owner를 둔다. 중요한 것은 모든 페이지에 책임자가 있어야 한다는 점이다.
Schema에 팀 운영 규칙을 적어라
AI가 일관되게 일하려면 규칙이 필요하다. 이 규칙은 CLAUDE.md 또는 AGENTS.md에 적는다. Claude Code의 CLAUDE.md는 프로젝트 구조, 표준, 워크플로를 매번 반복 설명하지 않도록 지속 컨텍스트를 제공하는 파일로 쓰인다4. 팀 위키에서도 같은 방식으로 AI에게 "우리 회사의 위키 관리 규칙"을 알려준다.
팀 위키용 schema에는 최소한 다음 항목이 필요하다.
## 원칙
- raw/의 원본 파일은 절대 수정하지 않는다.
- wiki/의 변경은 출처 링크를 포함해야 한다.
- 결정, 정책, 고객 발언, 수치 정보는 반드시 source를 남긴다.
- 기존 내용과 충돌하면 임의로 덮어쓰지 말고 `conflicts` 섹션에 기록한다.
## 페이지 작성 규칙
- 모든 페이지는 YAML frontmatter를 가진다.
- owner, status, sources, updated를 포함한다.
- 내부 링크는 [[페이지명]] 형식을 사용한다.
- 확실한 사실, 추정, 의견을 구분한다.
## 사람이 반드시 검토해야 하는 경우
- 고객명, 개인정보, 계약 조건이 포함된 경우
- 보안, 법무, 재무, 인사 관련 내용인 경우
- 기존 결정과 충돌하는 경우
- 출처가 하나뿐인데 중요한 주장으로 쓰이는 경우
- AI가 발화자나 담당자를 확신하지 못하는 경우Schema는 한 번 쓰고 끝나는 문서가 아니다. 팀이 일하면서 자주 발생하는 오류를 발견할 때마다 업데이트해야 한다. AI가 매번 고객 발언을 너무 단정적으로 요약한다면 "고객 발언은 직접 인용하지 말고 요지로 정리하며, 원문 링크를 붙인다"는 규칙을 추가한다. 회의 액션 아이템 담당자를 자주 틀린다면 "담당자가 불명확하면 미지정으로 두고 검토 요청한다"는 규칙을 넣는다.
권한, 로그, lint가 공유 위키의 안전장치다
개인 위키에서는 실수해도 피해가 작다. 팀 위키에서는 다르다. 잘못된 정책 문서가 배포되면 고객 대응이 흔들리고, 오래된 기술 문서를 AI 에이전트가 읽으면 잘못된 코드를 만들 수 있다. 따라서 공유 위키에는 운영 안전장치가 필요하다.
첫째, 권한을 나눈다. 모든 사람이 모든 문서를 볼 필요는 없다. 고객 피드백, 보안 이슈, 재무 정보, 인사 정보는 접근 범위를 분리한다. AI 에이전트도 같은 권한 원칙을 따라야 한다.
둘째, 변경 이력을 남긴다. Git을 쓰면 누가, 언제, 어떤 페이지를 바꿨는지 diff로 확인할 수 있다. AI가 만든 변경안도 pull request처럼 리뷰하면 좋다. 승인 로그에는 승인자, 승인 일시, 변경 이유가 남아야 한다.
셋째, 감사 가능해야 한다. ingest, 수정, 삭제, 질의, 대량 변경은 모두 로그에 남겨야 한다. LLM Wiki를 조직 규모로 확장할 때도 민감정보 필터링과 감사 추적은 중요한 거버넌스 요소로 강조된다5.
넷째, 정기 lint를 실행한다. 팀 위키는 매주 또는 격주로 건강 점검을 해야 한다. 오래된 주장, 출처 없는 내용, 중복 페이지, 고아 페이지, 상충되는 결정을 찾는다. 예를 들어 "가격 정책 페이지는 2026년 3월 기준이라고 쓰여 있는데, 5월 회의에서 변경된 결정이 반영되지 않았다" 같은 항목을 AI가 찾아내고 담당자에게 보낸다.
좋은 lint 질문은 다음과 같다.
wiki/ 전체를 점검하라.
특히 다음을 찾아라.
1. updated가 90일 이상 지난 정책 페이지
2. source가 없는 결정 문장
3. 서로 다른 결론을 말하는 decision 페이지
4. 링크를 받지 못한 고아 페이지
5. 온보딩 문서와 실제 제품 페이지의 불일치
결과는 outputs/lint-2026-05-19.md에 저장하고,
각 항목마다 담당 owner와 권장 조치를 제안하라.작게 시작하라
팀 내부 위키 자동화는 처음부터 전사 시스템으로 만들 필요가 없다. 오히려 작게 시작해야 성공한다. 한 프로젝트, 한 Slack 채널, 한 회의체, 한 명의 리뷰어로 시작한다.
추천하는 첫 실험은 다음과 같다.
최근 2주간의 회의록 3개를
raw/meetings/에 넣는다.관련 Slack 스레드 5개를
raw/slack/에 저장한다.AI에게 프로젝트 페이지, 결정 페이지, 온보딩 FAQ 초안을 만들게 한다.
프로젝트 리드가 변경안을 검토한다.
팀원들이 실제로 반복 질문 5개를 위키에서 해결할 수 있는지 확인한다.
이 실험에서 중요한 지표는 페이지 수가 아니다. 반복 질문이 줄었는지, 신규 입사자가 더 빨리 맥락을 이해했는지, 회의 결정이 나중에 다시 뒤집히지 않았는지다.
팀 위키의 목적은 문서를 많이 만드는 것이 아니다. 팀의 기억을 잃지 않는 것이다. AI가 정리하고, 사람이 승인하고, 위키가 쌓인다. 이 구조가 자리 잡으면 팀은 매번 처음부터 설명하지 않아도 된다. 지식이 개인의 머릿속에 머무르지 않고, 팀의 운영 자산으로 남는다.
참고
1Andrej Karpathy의 LLM Wiki 아이디어 파일
2The enterprise LLM wiki: scaling Karpathy's pattern to your org
4Using CLAUDE.md files: Customizing Claude Code for your codebase
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.