AI를 위한
회사 지식 관리 도구

왜 필요한가 · THE PROBLEM

설명서는 왜 늘 실패할까?

사람이든 AI든, 좋은 설명서가 있어야 일을 잘합니다.

한 문장 정의 · WHAT IT IS

“AI를 위한 인수인계 문서”를 자동으로 관리

아무리 똑똑한 신입(=AI)도 첫날엔 우리 회사를 모릅니다. 그래서 인수인계 매뉴얼을 주죠. llm-wiki가 바로 그 매뉴얼을 대신 정리해 주는 사서(司書) 로봇입니다.

어떻게 지식을 주입하나 · HOW

AI가 ‘우리 회사 방식’으로 일하게 만드는 4가지 장치

핵심 개념 · 신뢰 딱지 (TRUST)

AI가 쓴 건 “확인 전”, 사람이 통과시켜야 “확인 완료”

검토 전까지는 계속 ‘확인 전’으로 남아 리포트에 표시됩니다. → AI가 쓴 걸 무턱대고 믿지 않게 하는 안전장치.

핵심 개념 · 근거 (EVIDENCE)

모든 설명은 “실제 코드 위치”와 연결된다

결제 기능은 안전합니다.

결제 기능은 안전합니다.
(근거: src/payment.js 42번째 줄)

그래서 코드가 바뀌면 “그 근거 낡았어요”라고 콕 집어줄 수도 있습니다. → 헛소리(환각)가 줄어든다.

사용 방법 · CLI · API · MCP

우리 도구를 부르는 3가지 방법

일하는 엔진은 하나. 그 엔진에 들어가는 ‘입구’가 셋일 뿐 — 손님만 다르고 답은 같습니다.

MCP 자세히 ① · 어떻게 동작하나

AI가 우리 도구를 “직접 불러” 쓴다

🔒 열려 있는 건 읽기/확인 18개뿐 — 파일을 바꾸는 명령은 0개. AI가 들여다볼 순 있어도 절대 못 고칩니다.  read-only

MCP 자세히 ② · 서버는 어디에?

어디에도 호스팅 안 됨 — 내 컴퓨터에서 잠깐 돈다

인프라 0 · 관리 0 · 인터넷 노출 0. 휴대폰 계산기 앱처럼 열면 켜지고 닫으면 꺼집니다.

한 걸음 더 · 1.16 · 새 이름 & 방향

‘공통 표준’에서 ‘거버넌스 도구’로 — 그리고 새 이름

여러분이 바꿀 건 설치할 때 쓰는 이름 하나뿐 — 나머지 사용법은 동일합니다.

우리가 지켜온 것 · PRINCIPLES

1.0 이후 한 번도 어기지 않은 5가지 원칙

실무 · 작업 한 사이클

실제 작업은 이렇게 한 바퀴 돈다

↺ 그리고 다시 처음으로 — 이 사이클이 계속 돌면 문서가 항상 최신으로 유지됩니다.

최근 능력 · 1.15 · 1.18 · 1.19

이제 AI가 스스로 쓰고 · 검색하고 · 검증받는다

앞의 작업 사이클을 더 빠르게 돌리고, 빠뜨리면 잡아내는 장치들입니다.

왜 우리에게 이득인가 · BENEFITS

팀에 실제로 뭐가 좋아지나

올바른 사용법 ① · 위키가 있는 프로젝트

지금도 잘 하고 계세요 — 딱 한 줄만 추가

…를 만들어줘. 기능은 A, B, C.
구축된 llm-wiki 확인 후 작업해줘.

…를 만들어줘. 기능은 A, B, C.
1) 먼저 llm-wiki(관련 문서)를 읽고 컨벤션대로 작업.
2) 끝나면 관련 문서도 갱신하고,
   새로/바뀐 건 needs_review 로 남겨줘.

올바른 사용법 ② · 위키가 없는 프로젝트

“참고해서 만들어줘”는 위험합니다

이 패키지는 ‘보고 베끼는 견본’이 아니라 ‘실행하는 도구’예요. 참고만 시키면 AI가 제멋대로 흉내 내서 형식이 안 맞고, 나중에 검사에서 오류가 납니다.

llm-wiki를 새로 구축해줘.
1) 다음 명령을 실제로 실행:
   npx llm-wiki-governance quickstart --write --agent claude
2) 코드를 읽고 각 문서를 실제 근거로 채워줘.
3) 채운 내용은 needs_review 로 남겨줘.

“참고해서 흉내”  →  “도구를 실행해 뼈대 만들고 코드로 채우기”

실무 요약 · CHEAT SHEET

딱 이것만 기억하세요

자주 묻는 질문 · FAQ

자주 나오는 궁금증

정말 도움이 되나 · 실측 3-ARM 통제 실험 (REAL-LLM · N=3)

측정해봤습니다 — 이득은 도구가 아니라 “내용”

그래서 진짜 자산은 ‘유지된 내용’입니다 — 낡은 위키를 믿게 한 이전 실험에선 보안 관련 오답이 나왔고, 그걸 막는 게 drift·사람 검토(verified)입니다. 외부 Vue/Quasar 앱 1개 · Claude Opus 4.8 · 태스크 6개 · N=3 · 채점은 에이전트(기준은 사람 표본 비준) · 6개 중 1개는 조회가 3.17배로 패 — 보편적 속도 주장이 아닌, 스코프가 한정된 결과.

발전 스토리 ① · 1.0 → 1.27

한 번에 하나씩, 순서대로 쌓아온 기능

발전 스토리 ② · 1.28 → 1.31 · 가장 최근

최근 릴리스는 조금 더 자세히

• 1.28게이트를 실제로 켠 릴리스문서를 안 고치면 빌드가 빨개진다(impact가 이제 기본으로 차단 — 되돌리는 설정 2가지 제공) · 우리가 배포하는 4개 채널(훅·CI 템플릿·액션·우리 CI)이 드디어 그 게이트를 실행 · 어댑터 8종 전부 v2 형태로 · AI 작업환경 자체를 점검하는 harness-health · 릴리스 노트는 검사 면제
• 1.29켠 게이트가 우리 릴리스에서 울던 것을 고침버전 숫자 한 줄만 바뀐 package.json은 이제 "바뀐 파일"로는 계속 보고하되 문서 대조에는 쓰지 않는다 — 배포할 때마다 아무도 조치할 수 없는 경고가 쏟아지던 문제. 0이 되지는 않는다(11건 → 4건, 남는 건 내용이 진짜 바뀐 파일들) · 첫 구현이 세 군데 틀렸고 배포 전 교차검증이 전부 잡아냈다
• 1.29.1고칠 방법이 없는 경고를 없앰도구가 손댈 수 없는 문서(도입처가 복사해 쓰는 템플릿)를 두고 "낡았다"고 경고해서 해결할 방법이 없는데 빌드가 빨개졌다 — 검사 대상에서 뺐다. 7건 → 5건, 여기서도 0이 되지는 않는다
• 1.29.2AI에게 “누가 읽을지”까지 지시지금까지는 AI가 얼마나 읽을지만 정해줬다. 이제 훑어보고 찾는 일은 값싼 보조 AI에게 맡기고 요약만 받아오도록, 판단·수정·문서 서술은 맡기지 않도록 지시문에 적어 보낸다. 정직 포인트: 지시문이 약 30% 길어지는 비용은 확실하고, 절감은 측정하지 않았으므로 주장하지 않는다
• 1.30부담을 프로젝트에 맞게 고른다지금까지는 이 도구를 쓰면 모든 프로젝트가 같은 수준의 문서 관리를 받았다. 이제 lite · standard · strict 세 단계 중에 고른다 — 개인 프로젝트나 빠르게 도는 작업은 lite로 두면 문서 때문에 빌드가 막히지 않고, 인수인계를 앞두면 strict로 올린 뒤 backfill이 빠진 문서를 찾아 준다. 검사 엔진은 하나 그대로이고 같은 저장소에서 언제든 오간다. 기존 프로젝트는 손대기 전까지 아무것도 안 바뀐다. 정직 포인트: AI 지시문이 15~21% 길어지는 비용은 확실하고, 그게 문서 작업을 줄여 값을 하는지는 측정하지 않았다
• 1.31우리 도구가 자기 문서부터 못 지키고 있었다  —  가장 최근세 단계를 만든 뒤 제품에게 그 단계를 다 가르치지 못했다. 검사 하나(drift)가 단계를 무시했고, 리포트 4곳이 "mode"를 다른 뜻으로 쓰고 있었고, 문서는 단계 이전 동작을 설명했다. 사용자에게 실제로 위험했던 것도 하나 있었다 — 우리가 배포하는 CI 템플릿이 이름만 같은 남의 패키지를 내려받아 실행할 수 있었다. 출하 이후 줄곧 고칠 방법이 없던 경고 9건 → 0. 정직 포인트: 이번 수정 둘은 통과하던 빌드를 새로 실패시킬 수 있다 — 그대로 밝히고 되돌리는 설정을 함께 적었다