tmux를 사랑하는 DevOps 마법사도 아닙니다. 화려한 터미널 테마를 사용하는 유튜버도 아닙니다. 당신의 데이터를 정리하는 **에이전트 (agent)**가 바로 그 주인공입니다.

우리 모두는 깨달음의 순간을 경험한 적이 있습니다. 아마도 Karpathy의 에이전트 기반 LLM 위키에 관한 노트였을 수도 있습니다. 혹은 당신의 Obsidian 보관함(vault)이 내구성이 뛰어난 형식으로 성장하는 것을 지켜보는 과정이었을 수도 있습니다. 어쩌면 git이 이미 모든 변경 사항과 모든 버전을 추적하고 있다는 사실을 깨달았을 때였을지도 모릅니다.

모든 조각은 이미 갖춰져 있었습니다. Markdown, 링크, 지식 그래프(knowledge graphs), Git. 하지만 그 누구도 이 전체를 완성하여 출시하지는 않았습니다.

핵심 아이디어는 훌륭하지만, 에이전트에게 기계적인 질문을 던지면 제자리를 맴도는 모습을 보게 될 것입니다:

> 깨진 링크를 모두 수정해줘

read notes/a.md   → 1,400 tokens
...

에이전트는 매번 한 번에 파일 하나씩, 모든 것을 다시 읽고 있으며, 당신은 매 토큰마다 비용을 지불하고 있습니다.

내가 처음에 시도했던 것

Obsidian은 데스크톱 앱과 함께 CLI를 출시했습니다. 저도 그것을 사용해 보았습니다. 단점은 즉각적이었습니다. 데스크톱 앱이 실행 중이어야 한다는 점이었습니다. 그것은 서버에서 대규모로 실행할 도구가 아니라, 보조 도구로 설계되었습니다.

그래서 저는 저만의 것을 만들기로 결심했습니다. 이름을 obsy라고 지었습니다. 몇 가지 기능이 작동했지만, 곧 멈췄습니다.

이유는 간단했습니다. 제 에이전트에게 필요했던 것은 더 나은 노트 앱이 아니었습니다. 그것은 **조합 가능한 마크다운 엔진 (composable markdown engine)**이었습니다.

파일 뒤에 숨겨진 구조

당신의 노트에 이미 자리 잡고 있는 것들을 살펴보세요:

---
type: task
status: blocked
...

그게 전부입니다. Markdown. YAML 프론트매터 (frontmatter). 표준 링크. 이것은 **이식성 (portable)**이 있고 **내구성 (durable)**이 있습니다.

하지만 다시 읽어보세요. type, status, tags, priority. 이것들은 단순한 장식이 아닙니다. 그것들은 **구조화된 필드 (structured fields)**입니다. 그리고 하단에 있는 그 링크들은요? 그것들은 **그래프의 엣지 (edges in a graph)**입니다.

이런 파일이 수백 개 정도 쌓이면 당신은 스스로에게 질문하기 시작할 것입니다:

SELECT * FROM tasks WHERE status = 'blocked' AND tags LIKE '%docker%'를 실행할 수 있다면, 왜 마크다운 (Markdown) 파일 모음으로는 똑같은 일을 할 수 없는 걸까요?

그래서 저는 당신의 위키 번들 (wiki bundle)을 하나의 **데이터베이스 (database)**로 취급하는 CLI를 만들게 되었습니다. 인간이 설계하고, 에이전트 (agent)가 구현했습니다. wiki CLI를 소개합니다.

요약 (In a nutshell)

wiki는 터미널을 위한 범용 도구로, 다음과 같은 기능을 수행합니다:

• 폴더 구조 인덱싱 (Indexing)
• 링크 그래프 (link graph) 인덱싱
• 번들에 대한 구조화된 쿼리 (structured queries) 응답
• 번들에 대한 기계적 변환 및 검사 수행
• 분 단위가 아닌 밀리초 (milliseconds) 단위로 응답
• 모든 컴퓨터나 서버에서 실행 가능
• 운영체제 (OS) 및 클라이언트에 무관 (agnostic)

이를 통해 당신의 에이전트가 얻는 이점은 다음과 같습니다:

자유로운 그래프 탐색 (Free graph navigation)

wiki backlinks /projects/infra/dns-setup.md   # 이곳을 가리키는 모든 항목
wiki links /projects/infra/dns-setup.md       # 이 항목이 가리키는 대상
wiki orphans                                  # 아무것도 연결되지 않은 항목
...

데이터베이스와 유사한 쿼리 (Database-like queries)

항목을 필터링하여 관련 있는 소수만을 처리할 수 있습니다.

# 필터링
wiki list --where type=task --where tags=docker
# key!=value는 부정 (negation)
...

변환 가능한 **구조화된 데이터 (structured data)**로 추출할 수 있습니다:

wiki list --where type=task --where status=blocked \
  --format json | jq '.[] | {date, tags}'

체크리스트 항목 추출 (Extracting checklist items)

산문 속에 숨겨져 있거나 파일 곳곳에 흩어져 있는 - [ ] 체크박스 (checkboxes) 형태의 작업들을 추출합니다:

wiki checkboxes --prefix /backlog        # /backlog/** 내에 모인 모든 미결 항목

안전한 이름 변경 (Renaming safely)

wiki move /topic.md /archive/topic.md    # 위치 이동 또는 이름 변경, 해당 항목을 가리키는 모든 링크 재작성
wiki check                               # 상태 린트 (health lint): 깨진 링크, 유형이 지정되지 않은 항목, 드리프트 (drift)
wiki tidy --all                          # 링크, 파일 이름, 위키링크 (wikilinks) 등을 정규화

파일 이름을 변경하면 상대 경로 링크를 포함하여 베이스 전체의 모든 링크가 한 번에 따라 변경됩니다. 죽은 참조 (dead references)나 '찾기 및 바꾸기' 식의 도박을 할 필요가 없습니다.

표 형식 데이터 내보내기 (Exporting tabular data)

예를 들어, 에이전트가 송장(invoice) 목록을 준비했다고 가정해 봅시다.

---
type: dataset
---
...

**마크다운 표 (markdown tables)**도 동일하게 작동합니다:

wiki table /finance/invoices.md --format csv | duckdb -c \
  "SELECT currency, sum(amount) FROM read_csv_auto('/dev/stdin') GROUP BY currency"

...

좋은 소식은 이 모든 과정을 직접 연결(wire)할 필요가 없었다는 점입니다. 당신의 에이전트가 해낸 것입니다. 바퀴를 다시 발명할 필요 없이 내구성이 있는 형식을 소싱(sourcing)해냈습니다.

여기에는 더 탐구할 내용이 많지만, 핵심은 다음과 같습니다:

필요한 곳에 토큰 (tokens)을 사용하세요.
중요한 순간에 연산 (compute)을 사용하세요.

기계적인 부분은 정확한 작업을 즉각적이고 거의 비용 없이 수행하는 도구에 맡기십시오.

제대로 된 지식 베이스 (knowledge base)를 구축함에 있어, 이것이 바로 **토큰을 낭비하는 것 (burning tokens)**과 1초 미만의 답변 (sub-second answers) 사이의 차이입니다.

하지만 여전히 빠진 조각이 하나 있습니다.

에이전트에게 조작법 가르치기

Claude는 지난 10년 중 가장 훌륭한 스크립트를 작성할 수 있지만, wiki CLI에 대해서는 전혀 알지 못합니다. 또한 당신이 기대하는 워크플로우 (workflow)에 대해서도 전혀 모릅니다.

wiki는 무수히 많은 형태로 사용될 수 있습니다. **워크플로우 (workflow)**가 바로 이 도구를 당신의 것으로 만드는 요소입니다:

• 무엇을 기록할 가치가 있는가
• 언제 거친 메모를 정식 항목으로 승격시킬 것인가
• 항목들이 어떻게 연결되어야 하는가
• 백로그 (backlog)가 어떻게 구조화되어 있는가
• 중복 항목을 어떻게 처리할 것인가 등

공통적인 관례 (conventions)가 이미 설정된 스타터 스캐폴딩 (scaffold)을 구성할 수 있습니다:

wiki init --workflow product-docs

이 명령은 중요한 두 개의 파일을 생성합니다:

• AGENTS.md: 에이전트를 위한 일반 지침입니다. CLI를 사용하여 위키 번들 (wiki bundle)을 어떻게 운영해야 하는지 알려줍니다.
• WORKFLOW.md: 지식 베이스 (knowledge base)를 위한 관례 (conventions)입니다. 항목이 어떻게 분류되는지, 어떤 유형을 사용하는지, 항목들이 어떻게 연결되는지를 정의합니다. 이는 시작점일 뿐이며, 당신의 사고방식에 맞게 수정하면 됩니다.

지식 베이스를 넘어선 프로젝트의 경우, 재사용 가능한 (reusable) SKILL.md를 로드할 수도 있습니다: https://github.com/agentic-wiki/skills.

당신이 구축할 수 있는 것

일단 이 패턴을 보고 나면, 다시는 이전으로 돌아갈 수 없을 것입니다.

• 개인 지식 베이스 (Personal knowledge base)
• 팀 지식 베이스 (Team's knowledge base)
• 칸반 보드 (Kanban board)
• 제품 문서 (Product documentation)
• 표 형식 데이터셋 (Tabular datasets)
• 위 항목들의 모든 조합

동일한 프리미티브 (Primitive). 동일한 엔진 (Engine). 동일한 에이전트 (Agent). 당신의 컨벤션 (Conventions). 당신의 워크플로우 (Flow). 당신의 데이터 (Data).

이 중 어느 것도 단독으로는 새로운 것이 아닙니다. 제텔카스텐 (Zettelkasten) 방법론, 포맷, Claude, Codex, Gemini, Hermes, 그리고 CLI 도구를 호출하는 Pi까지 말이죠. 하지만 이들이 결합되면 _"내 에이전트가 무언가를 읽는다"_와 "내 에이전트가 내 지식을 관리한다" 사이의 루프를 완성합니다.

이 모든 것은 당신과 당신의 자동화 워크플로우 (Automation flow)가 모두 읽을 수 있는 포맷으로 이루어집니다.

직접 시도해 보세요

Wiki는 macOS, Linux, WSL 또는 Windows에서 작동합니다.

brew install agentic-wiki/tap/wiki

# 또는:
...

또는 GitHub releases에서 바이너리 (Binary)를 가져오세요.

워크플로우 스타터 (Workflow starter)를 사용하여 위키 번들 (Wiki bundle)을 스캐폴딩 (Scaffold) 하세요. default는 범용 버전입니다.

wiki init --workflow product-docs    # AGENTS.md 및 WORKFLOW.md 생성
wiki status                   # 카운트: 항목 (Entries), 링크 (Links), 태그 (Tags), 체크박스 (Checkboxes), 깨진 링크 (Broken links), 고아 항목 (Orphans)

그런 다음 에이전트 (Agent)가 해당 폴더를 가리키도록 하고 작업을 부여하세요:

pi -p "Please, walk the codebase under ~/code/my-project and scaffold a wiki bundle
    with the relevant concepts, components and examples as the project knowledge base.
    Also, prepare a linear set of tutorials that the user can follow, each with links
...

AGENTS.md와 WORKFLOW.md를 따르면, 당신의 에이전트는 Obsidian으로 열 수 있고 wiki로 관리할 수 있는 구조화된 지식 베이스를 스캐폴딩할 것입니다.

그래서, 누가 위키 CLI를 필요로 할까요?

여전히 tmux 마법사는 아닙니다. 여전히 당신도 아닙니다. 하지만 파일이 12개를 넘어가면, 당신의 에이전트가 필요할 가능성이 매우 높습니다.

에이전트는 판단력을 가져오고, 도구는 결정론 (Determinism)을 가져옵니다. 어느 하나만으로는 비결이 될 수 없으며, 이 둘이 함께할 때 비로소 완성됩니다.

도구는 github.com/agentic-wiki/wiki에서 사용할 수 있으며, 스킬 (Skills)은 github.com/agentic-wiki/skills에서 확인할 수 있습니다. 이슈 (Issues)와 PR (Pull Requests)은 언제나 환영합니다.