나와 같은 시각적 학습자를 위한 기술을 만들었습니다

배경 (Background)

에이전틱 코딩 (agentic coding) 여정을 시작한 지 1년이 넘었습니다. 불과 몇 달 만에 소프트웨어 산업은 바이브 코딩 (vibe coding)에서 명세 기반 개발 (spec-driven development)으로 빠르게 변화했습니다. 매일 수많은 방법론이 쏟아져 나오고 있습니다. 압도적이지 않나요? 하지만 이 모든 방법론은 결국 엄청난 양의 마크다운 (markdown) 파일을 읽고 쓰는 것으로 귀결됩니다.

문제 (The Problem)

읽어야 할 문서가 너무 많으면 머리가 어지럽습니다. 대부분의 경우, 단순히 읽는 것만으로도 쉽게 주의가 산만해집니다. 문맥 (context)을 흡수할 수 있는 다양한 방법을 시도해 보았지만, 저에게 맞는 방법은 없었습니다. 그래서 저는 제 선호도에 맞춘 기술을 직접 만들기로 결심했습니다.

무엇을 만들었나? (What I built?)

저는 doc-server를 만들었습니다. 이는 프로젝트의 명세 (spec)/계획 (plans)/문맥 (context)을 HTML로 제공하는 아주 작은 로컬 웹 앱으로, 이를 통해 문서를 빠르게 탐색하고 프로젝트의 문맥을 파악할 수 있습니다. 하나의 포트 (port)에서 여러 프로젝트나 워크트리 (worktrees)를 지원할 수 있습니다. 이것은 읽기 전용 문서 검토기 (documentation reviewer)이지만, 저장소 (repo)에 문서가 추가되면 업데이트됩니다.

어떻게 작동하나? (How it works?)

• doc-server는 Claude Code가 작성한 마크다운 (markdown) 파일들을 브라우징 가능한 스타일링된 웹사이트로 변환해 주는 Python 기반의 로컬 HTTP 서버입니다.

• 기본적으로, 에이전트 (agent)는 워크트리 (worktree)에서 감지된 서로 다른 문서들을 브랜치 기반의 경로 (branch-based routes)에 작성합니다.

• 브랜치 기반 라우팅 (Branch-based routing). 모든 프로젝트의 문서는 http://localhost:8910/<project>/<branch>/라는 예측 가능한 URL에 위치합니다. 사용자가 main 브랜치에 있든 feat/auth 워크트리에 있든, URL은 항상 현재 브랜치와 일치합니다. 이는 여러 워크트리가 충돌 없이 공존할 수 있음을 의미합니다.

• 새로고침 시 동기화 (Sync on refresh). 서버는 페이지를 로드할 때마다 ~/.claude/doc-server/에서 마크다운 (markdown) 파일을 다시 읽습니다. 별도의 빌드 단계나 파일 워처 (file watcher)가 필요 없습니다. 브라우저를 새로고침하기만 하면 에이전트가 방금 작성한 최신 버전을 바로 확인할 수 있습니다.

• 앞서 언급했듯이 이는 로컬 앱이지만, 접근성을 위해 tailscale (메시 VPN, mesh vpn)을 사용하여 어디서든, 특히 컴퓨터를 떠나 있을 때도 개인적으로 문서에 접속할 수 있도록 했습니다.

스크린샷 (Screenshots)

저는 코드 에디터에 시스템 프롬프트 (system prompt)를 생성하여 워크트리 컨텍스트 (worktree context)를 제공함으로써, /doc-server 스킬이 이를 인식하고 홈 페이지에 요약을 렌더링할 수 있도록 했습니다.

다음 단계는? (What's next?)

이 글을 읽고 계신 지금도 저는 이 스킬을 계속 다듬고 있지만, 꼭 한번 사용해 보세요! 설치 방법은 다음과 같습니다:

# 이 마켓플레이스를 추가한 다음, 거기서 플러그인을 설치하세요:
/plugin marketplace add nljms/skills
/plugin install doc-server@nljms-skills
...

이 리포지토리(repo)에 이슈(issue)나 기능 요청을 제출해 주세요: https://github.com/nljms/skills. 협업은 언제나 환영이니 편하게 알려주세요! 😄