[한글자막] 사람이 아닌 에이전트를 위한 문서 작성법: OpenWiki 내부 공개

한 줄 핵심

OpenWiki는 에이전트가 코드 저장소 문서를 더 적은 토큰과 더 적은 도구 호출로 읽고 갱신할 수 있도록, 사람보다 에이전트 중심으로 설계한 CLI 기반 문서·메모리 시스템이다.

시간별 요약

1. 0:00
   OpenWiki는 저장소 문서를 사람이 아닌 에이전트가 소비하도록 설계한 CLI이며, 핵심 목표는 일반 목적 메모리를 코드베이스 문서에 먼저 적용하는 것이다. 특히 문서를 생성하는 것보다, 에이전트가 빠르게 찾고 이해할 수 있게 구조화하는 문제를 더 중요하게 본다.
2. 2:00
   에이전트용 문서는 인간용 문서와 달리 각 조각이 독립적으로 이해되어야 하고, 정확한 제목과 컨텍스트 윈도우에 맞는 길이가 필요하다. OpenWiki는 NPM으로 쉽게 설치되는 CLI와 간단한 초기 설정으로 시작되며, 초기화 시 wiki 파일과 agents.md, GitHub Actions까지 자동으로 구성한다.
3. 5:02
   문서 구조는 quickstart.md, 디렉터리별 분할 문서, OKF front matter, index.md, log.md로 이루어지며, OKF의 type·title·description·tags·timestamp가 검색과 필터링을 돕는다. 문서 간 마크다운 링크와 리소스 태그를 적극적으로 써서 관련 컨텍스트를 빠르게 따라가게 만드는 것이 핵심이다.
4. 9:01
   초기 평가에서는 Deep Sweep 일부 과제에 적용했을 때 성공률이 소폭 개선되고 토큰 사용량과 도구 호출이 줄어드는 경향이 보였다. 다만 아직 평가 초기 단계라서, 문서 생성 자체보다 검색·회수 품질이 더 어려운 문제로 남아 있다.
5. 10:01
   처음에는 에이전트만 읽는 문서를 목표로 했지만, 실제로는 사람도 읽어야 하므로 다이어그램과 흐름도를 추가하는 방향으로 조정했다. 또한 init과 update 두 명령으로 Git 히스토리를 반영해 일일 갱신을 자동화하고, 변경 사항은 PR로 올려 쉽게 머지할 수 있게 했다.
6. 13:01
   init은 저장소를 스캔하고 Git 히스토리까지 참고해 계획을 세운 뒤 문서를 쓰고, deterministic pass로 OKF 준수 여부와 index.md, change log를 정리한다. update는 마지막 실행 이후 변경이 없으면 건너뛰고, 변경이 있으면 커밋들을 반영해 위키를 갱신한 뒤 PR을 생성한다.
7. 15:00
   현재는 오픈소스로 공개되어 NPM 설치와 다양한 provider 지원, 포크 기반 커스터마이징이 가능하다. 다음 단계는 더 나은 prompting, 대형 저장소 대응, 그리고 agents.md 의존을 넘어선 전용 검색·필터링·질의 도구를 제공하는 것이다.

실무 인사이트

• 에이전트용 문서는 서사형 설명보다 독립적으로 검색·재사용 가능한 짧은 단위와 정확한 메타데이터가 더 중요하다.
• 문서 생성 자동화보다 실제 성능을 좌우하는 것은 검색·회수 품질이므로, OKF 같은 구조화된 front matter와 교차 링크를 먼저 설계해야 한다.
• 지속 운영을 위해서는 초기 생성보다 갱신 자동화가 핵심이며, Git 히스토리와 PR 기반 업데이트가 실무 적용성을 높인다.