코딩 에이전트가 읽는 저장소 위키를 만드는 OpenWiki

코딩 에이전트가 읽는 저장소 위키를 만드는 OpenWiki

AI 뉴스 썸네일

코딩 에이전트가 저장소를 제대로 이해하려면 최신 구조와 규칙을 설명하는 문서가 필요해요. 하지만 코드가 바뀔 때마다 사람이 문서를 고치는 일은 쉽게 밀려요. OpenWiki는 코드와 여러 지식 소스를 읽어 에이전트가 참고할 로컬 위키를 만들고, CI에서 변경 내용을 계속 갱신하는 CLI예요. 1

핵심 요약

구분	내용	확인할 점
Code 모드	현재 저장소를 분석해 `openwiki/`에 문서를 만들어요	기존 `AGENTS.md`와 `CLAUDE.md`는 지정 블록만 바꿔요
Personal 모드	로컬 저장소, Gmail, Notion, 웹 검색 등을 개인 위키로 묶어요	소스별 인증 정보와 전송 범위를 먼저 확인해야 해요
문서 형식	Google Open Knowledge Format 0.1 형식으로 Markdown을 저장해요	일반 문서라서 다른 도구로 열고 버전 관리하기 쉬워요
자동 갱신	GitHub Actions와 GitLab CI 예제로 문서 변경 PR을 만들어요	생성된 문서도 코드 리뷰 대상에 포함하는 편이 좋아요

1. 저장소 설명을 에이전트가 찾기 쉬운 위키로 바꿔요

OpenWiki의 Code 모드는 현재 저장소를 읽고 `openwiki/` 폴더에 문서를 만들어요. 첫 실행에는 `openwiki --init`, 이후 갱신에는 `openwiki --update`를 써요. 대화형 화면 없이 결과만 받아야 하는 CI에서는 `openwiki code --update --print`를 사용할 수 있어요. 초기 문서가 없어도 갱신 명령이 필요한 파일을 만들어요. 2

생성 결과는 독자적인 데이터베이스에만 갇히지 않아요. OpenWiki는 두 모드 모두 Google Open Knowledge Format 0.1 번들을 출력해요. 개념 문서는 `type` 값이 있는 YAML frontmatter를 갖고, 문서 사이 관계는 일반 Markdown 링크로 표현해요. 저장소에서 바로 읽고 diff를 확인하거나 다른 Markdown 도구와 연결하기 쉬운 구조예요.

728x90

저장소 루트의 `AGENTS.md`와 `CLAUDE.md`도 함께 관리해요. 이 파일에는 코딩 도구가 위키를 참고하도록 안내하는 블록이 들어가요. 기존 파일이 있다면 전체를 덮지 않고 `OPENWIKI:START`와 `OPENWIKI:END` 사이만 갱신해요. 팀이 직접 적은 규칙을 보존하면서 위키 진입점만 자동으로 유지할 수 있어요.

프로젝트별 문서 범위와 우선순위는 `openwiki/INSTRUCTIONS.md`에 따로 적을 수 있어요. 이 파일은 생성 문서가 아니라 사람이 관리하는 지침으로 취급돼요. 업데이트 과정에서 문서화 도구가 임의로 다시 쓰지 않는다는 점도 실무에서 유용해요.

CI에서 문서 변경을 코드처럼 검토해요

공식 저장소에는 GitHub Actions, GitLab CI, Bitbucket Pipelines 예제가 있어요. 예약 실행이나 코드 변경을 계기로 위키를 갱신하고, 바뀐 문서를 PR이나 머지 요청으로 올리는 방식이에요. 문서가 조용히 바뀌는 대신 개발자가 diff를 읽고 코드 상태와 맞는지 확인할 수 있어요.

자동 갱신이 오래된 문서 문제를 줄여도 정확성을 보장하지는 않아요. 특히 설계 의도, 예외 처리 이유, 운영상 금지 사항은 코드만 읽어서 놓칠 수 있어요. `INSTRUCTIONS.md`에 핵심 범위를 명시하고, 생성된 설명을 리뷰한 뒤 병합하는 과정이 필요해요. 문서 PR을 테스트 결과처럼 참고 자료로 보고 사람이 최종 판단하는 구성이 안전해요.

개인 지식과 저장소 문서는 서로 다른 범위로 다뤄요

Personal 모드는 `~/.openwiki/wiki`에 개인용 위키를 만들어요. 로컬 Git 저장소뿐 아니라 Gmail, Notion, X, 웹 검색, Hacker News 같은 소스를 여러 개 연결할 수 있어요. 같은 종류의 커넥터도 목적별로 나눠 구성할 수 있어서 업무 자료와 관심 주제 자료를 별도로 가져올 수 있어요. 수집 원본과 manifest는 로컬 커넥터 폴더에 저장되고, 소스별 실행이 이를 위키 문서로 정리해요. 2

여러 계정과 업무 문서를 묶는 기능은 편하지만 권한 범위가 넓어질 수 있어요. Gmail이나 Notion을 연결하기 전에 어떤 데이터가 로컬에 남고, 선택한 추론 제공자에게 어떤 내용이 전달되는지 확인해야 해요. 커넥터 설정에는 비밀 값을 직접 적지 않고 환경 변수 이름만 참조하도록 설계돼 있어요.

OpenWiki는 실행 결과와 제공자·커넥터 이름 수준의 익명 텔레메트리를 기본으로 보내요. 공식 설명에 따르면 파일 내용, 저장소 이름, 자격 증명, 입력 문구, 모델 출력, 경로와 URL은 수집하지 않아요. 원치 않으면 `OPENWIKI_TELEMETRY_DISABLED=1`이나 `DO_NOT_TRACK=1`로 끌 수 있어요. 민감한 저장소에서는 설치 직후 이 설정과 실제 전송 항목을 먼저 확인하는 편이 좋아요.

설치는 `npm install -g openwiki`로 할 수 있고 MIT 라이선스로 공개돼 있어요. OpenAI, Anthropic, Gemini, AWS Bedrock과 OpenAI 호환 엔드포인트 등 여러 추론 제공자를 선택할 수 있어요. 로컬 모델 서버도 호환 API 주소와 모델 ID를 지정하면 연결할 수 있어요.

왜 중요한가요

코딩 에이전트가 저장소를 매번 처음부터 탐색하면 같은 구조와 규칙을 반복해서 찾느라 시간과 토큰을 써요. 반대로 오래된 문서를 그대로 믿으면 현재 코드와 다른 전제에서 수정할 수 있어요. OpenWiki는 저장소 문서를 정기적으로 다시 만들고 변경분을 리뷰하게 해 이 간극을 줄이는 접근이에요. 2

도입 여부는 생성 문서의 양보다 실제 질문에 답하는지로 판단하는 편이 좋아요. 새 개발자가 모듈 경계를 찾는 시간, 코딩 도구가 관련 파일을 고르는 정확도, 문서 PR에서 반복해서 고치는 오류를 비교해 보세요. 민감한 소스를 연결한다면 문서 품질보다 권한과 데이터 경로 점검을 먼저 끝내야 해요.

참고 자료

1. OpenWiki - 코드베이스를 위한 에이전트용 문서를 작성하고 관리하는 CLI — GeekNews
2. langchain-ai/openwiki — GitHub