Table of Contents

Davia 사용법 2026: AI 코딩 에이전트 문서화 설치 가이드

Davia는 AI 코딩 에이전트가 코드베이스를 읽고, 프로젝트 안에 인터랙티브 내부 문서와 편집 가능한 화이트보드를 만들도록 돕는 오픈소스 CLI입니다. Cursor, Claude Code, GitHub Copilot, Windsurf, OpenCode 같은 도구를 쓰고 있다면 “코드는 빨리 바뀌는데 문서는 계속 낡는 문제”를 한 번쯤 겪었을 가능성이 큽니다.

Davia가 겨냥하는 지점이 바로 그 부분입니다. README를 하나 더 쓰자는 이야기가 아닙니다. AI 에이전트가 .davia 폴더에 문서 페이지, MDX 컴포넌트, JSON 데이터, Mermaid/Excalidraw 기반 다이어그램을 생성하고, 사용자는 이를 브라우저에서 보고 고칠 수 있습니다.

3줄 요약

Davia는 AI 코딩 에이전트가 코드베이스를 분석해 로컬 위키와 인터랙티브 문서를 만들도록 돕는 CLI입니다.
npm i -g davia 후 davia init --agent=claude-code처럼 초기화하고, 사용 중인 에이전트에게 문서화를 요청하는 방식입니다.
주목받는 이유는 코드 생성보다 더 어려워진 “프로젝트 맥락 유지” 문제를 문서와 화이트보드로 풀려고 하기 때문입니다.

이 글에서 다루는 내용

Davia란 무엇인지
Davia 설치와 기본 사용법
실제 davia init 실행 결과
.davia 폴더 구조와 문서 생성 방식
Davia가 AI 코딩 에이전트 시대에 주목받는 이유
Notion, Confluence, Mermaid 문서와의 차이
Davia를 쓰면 좋은 경우와 아직 조심해야 할 점
자주 묻는 질문 FAQ

확인일: 2026년 7월 6일. GitHub API 기준 davialabs/davia는 TypeScript 기반 MIT 라이선스 프로젝트이며, 약 1.6k stars / 119 forks를 기록하고 있었습니다. npm 패키지 davia의 최신 버전은 0.1.14였습니다.

Davia란?

Davia는 “AI coding agents를 위한 interactive, editable docs”를 표방하는 오픈소스 프로젝트입니다. 공식 문서의 설명을 풀어 쓰면, Davia는 AI 코딩 에이전트가 프로젝트를 읽고 사람이 볼 수 있는 내부 문서를 로컬에 생성하게 하는 도구입니다.

일반적인 문서화 도구와 다른 점은 산출물이 단순 Markdown에 그치지 않는다는 점입니다. Davia는 HTML 페이지, MDX 컴포넌트, JSON 데이터, Mermaid 다이어그램, Excalidraw 스타일 화이트보드를 함께 다룹니다. 그래서 문서가 “읽는 파일”에 머무르지 않고, 브라우저에서 편집 가능한 작업 공간에 가까워집니다.

공식 문서에서는 Davia를 다음 흐름으로 설명합니다.

프로젝트 루트에서 davia init을 실행한다.
Davia가 .davia 폴더와 에이전트용 규칙 파일을 만든다.
사용자는 Cursor, Claude Code, GitHub Copilot 같은 에이전트에게 문서화를 요청한다.
에이전트가 .davia/assets/ 아래에 문서와 다이어그램을 생성한다.
davia open으로 로컬 브라우저에서 결과를 확인한다.
필요하면 davia push로 클라우드 워크스페이스에 공유한다.

한 줄로 정리하면, Davia는 AI 코딩 에이전트 문서화 워크플로를 프로젝트 안에 설치해주는 도구입니다.

Davia 설치 전 요구사항

Davia는 npm 패키지로 배포됩니다. npm 메타데이터 기준 요구 Node 버전은 >=18입니다.

먼저 Node.js와 npm이 설치되어 있는지 확인합니다.

node -v
npm -v

Node.js가 없다면 공식 다운로드 페이지에서 설치하거나, macOS/Linux에서는 nvm, fnm, mise 같은 버전 매니저를 써도 됩니다.

# 예시: Node.js 버전 확인
node -v

# 예시 출력
# v22.23.1

Davia 설치 방법

전역 CLI로 설치하는 공식 경로는 다음입니다.

npm i -g davia

설치 후 CLI가 잡히는지 확인합니다.

davia --help

전역 설치가 부담스럽거나 잠깐만 테스트하고 싶다면 npm exec로 실행할 수도 있습니다.

npm exec --yes --package=davia -- davia --help

이번 글을 작성하면서 실제로 위 명령을 실행했고, 다음 명령들이 노출되는 것을 확인했습니다.

Commands:
  init [options]   Initialize Davia in the current directory
  docs [options]   Generate initial documentation
  open [options]   Start the Davia web server
  login [options]  Log in to Davia
  push             Push local documentation to your remote workspace

Davia 사용법: 가장 짧은 실행 흐름

가장 기본적인 Davia 사용법은 세 단계입니다.

npm i -g davia
cd your-project
davia init --agent=claude-code

그다음 Claude Code, Cursor, GitHub Copilot 등 사용 중인 AI 코딩 에이전트에게 이렇게 요청합니다.

Use Davia to generate a local wiki that documents this project.
Include visual architecture diagrams, key request flows, and editable whiteboards.

문서가 생성되면 로컬 웹 UI를 엽니다.

davia open

팀과 공유할 필요가 있다면 push를 실행합니다.

davia push

다만 공식 문서에 따르면, 현재는 이미 push한 기존 클라우드 워크스페이스를 업데이트하는 기능이 아직 지원되지 않습니다. 지금 단계에서는 davia push가 새 워크스페이스를 만드는 흐름에 가깝다고 보는 편이 안전합니다.

지원하는 AI 코딩 에이전트

Davia는 AI 코딩 에이전트 문서화 흐름에 붙는 도구입니다. 비슷한 맥락의 개발자 도구가 궁금하다면 Daily Info Lab의 Ponytail 사용법 글도 같이 보면 좋습니다. Ponytail이 에이전트의 과잉 구현을 줄이는 쪽이라면, Davia는 에이전트가 프로젝트 문서를 남기게 하는 쪽에 가깝습니다.

공식 문서 기준 Davia는 다음 에이전트 값을 지원합니다.

도구	`--agent` 값
Cursor	`cursor`
Claude Code	`claude-code`
GitHub Copilot	`github-copilot`
Windsurf	`windsurf`
OpenCode	`open-code`

예를 들어 Cursor를 쓴다면 다음처럼 초기화합니다.

davia init --agent=cursor

Claude Code를 쓴다면 다음처럼 실행합니다.

davia init --agent=claude-code

에이전트를 연결하고 싶지 않다면 단순히 davia init만 실행해도 됩니다.

davia init

실제 실행 검증: `davia init --agent=cursor`

이번 글에서는 단순히 README만 요약하지 않고, 임시 디렉터리에서 Davia CLI를 직접 실행했습니다.

테스트 환경은 다음과 같습니다.

node: v22.23.1
npm: 10.9.8

실행한 명령입니다.

mkdir -p /tmp/davia-smoke-test
cd /tmp/davia-smoke-test
npm exec --yes --package=davia -- davia --help
npm exec --yes --package=davia -- davia init --agent=cursor

davia init --agent=cursor 실행 후 다음 파일들이 생성됐습니다.

.cursor/rules/davia-documentation.mdc
.davia/AGENTS.md
.gitignore

.gitignore에는 Davia 관련 파일이 자동으로 추가됐습니다.

# Davia
.davia/
.cursor/rules/davia-documentation.mdc

이 결과가 중요합니다. Davia는 문서 산출물을 Git에 바로 넣는 방식이 아니라, .davia를 로컬 작업 공간으로 두고 AI 에이전트가 그 안에 문서를 쓰게 합니다. 동시에 Cursor 같은 도구에는 에이전트 규칙 파일을 심어 “Davia 방식으로 문서화하라”는 지침을 남깁니다.

`.davia` 폴더 구조

공식 문서의 프로젝트 구조 설명에 따르면, Davia는 프로젝트 루트 아래 .davia 폴더를 만듭니다. 대표 구조는 다음과 같습니다.

.davia/
├── AGENTS.md          # 코딩 에이전트가 따라야 하는 문서화 프롬프트
└── assets/
    ├── *.html         # 사용자가 보는 문서 페이지
    ├── components/    # MDX 컴포넌트
    ├── data/          # JSON 데이터와 변환된 화이트보드 다이어그램
    └── mermaids/      # Mermaid 원본 파일

각 폴더의 역할은 다음처럼 볼 수 있습니다.

경로	역할	주요 파일
`.davia/AGENTS.md`	AI 에이전트가 따라야 할 Davia 문서화 규칙	Markdown
`.davia/assets/*.html`	실제 문서 페이지	HTML
`.davia/assets/components/`	인터랙티브 UI 컴포넌트	MDX
`.davia/assets/data/`	데이터와 변환된 화이트보드	JSON
`.davia/assets/mermaids/`	Mermaid 원본 다이어그램	`.mmd`

Davia 문서에서 흥미로운 부분은 Mermaid 처리 방식입니다. AI 에이전트가 .mmd 파일을 만들면 Davia가 이를 JSON으로 변환하고, HTML 페이지에서는 다음과 같은 형태로 편집 가능한 화이트보드를 임베드합니다.

<excalidraw data-path="data/diagram-name.json"></excalidraw>

그래서 최종 결과물은 단순 이미지가 아닙니다. 사용자가 직접 움직이고 수정할 수 있는 다이어그램에 가깝습니다.

Davia가 주목받는 이유

1. AI 코딩의 병목이 코드 작성에서 맥락 유지로 이동했다

AI 코딩 에이전트는 이미 코드 작성 속도를 크게 올렸습니다. 문제는 그다음입니다. 코드가 빨리 바뀔수록 프로젝트 문맥은 더 빨리 낡습니다.

개발팀에서 실제로 문제가 되는 질문은 대개 이런 것들입니다.

이 인증 흐름은 지금도 유효한가?
결제 API는 어떤 서비스와 DB 테이블을 건드리는가?
새로 추가된 기능이 기존 도메인 모델과 어떻게 연결되는가?
다음 AI 세션이 이 프로젝트를 이해하려면 무엇을 먼저 읽어야 하는가?

Davia는 이 질문에 답하기 위한 로컬 문서 레이어를 만들려고 합니다. AI 에이전트가 코드만 고치고 끝나는 것이 아니라, 사람이 읽고 수정할 수 있는 프로젝트 지식도 같이 남기게 하는 방식입니다.

2. 문서를 정적 파일이 아니라 편집 가능한 작업 공간으로 본다

README, Notion, Confluence, Mermaid는 모두 유용합니다. 하지만 AI 코딩 에이전트가 계속 코드를 바꾸는 환경에서는 문서도 더 자주 수정되어야 합니다.

Davia는 문서를 “완성된 문서”라기보다 “계속 고치는 작업 공간”에 가깝게 봅니다. 특히 화이트보드가 중요합니다. 인증 흐름, 큐 처리, 데이터 파이프라인, 프론트엔드 상태 흐름 같은 것은 텍스트보다 다이어그램이 이해하기 쉽습니다. Davia는 이 다이어그램을 이미지로 박제하지 않고, Excalidraw처럼 편집 가능한 형태로 만들려 합니다.

3. 기존 AI 코딩 도구에 바로 붙는다

Davia는 자체 AI IDE를 새로 쓰라고 요구하지 않습니다. Cursor, Claude Code, GitHub Copilot, Windsurf, OpenCode처럼 이미 쓰는 도구에 규칙을 붙이는 방식입니다.

이 접근은 현실적입니다. 개발자는 도구를 자주 바꾸고 싶어 하지 않습니다. Davia는 에디터를 대체하기보다, 현재 에이전트가 문서까지 만들도록 역할을 확장합니다.

4. 로컬 우선 구조라 민감한 코드베이스에 적용하기 쉽다

Davia는 먼저 로컬 .davia 폴더에 문서를 만듭니다. 필요할 때만 davia push로 원격 워크스페이스에 올립니다.

내부 문서와 코드 구조는 민감한 정보입니다. 처음부터 모든 문서를 외부 SaaS로 보내는 방식은 팀에 따라 부담이 큽니다. Davia처럼 로컬에서 만들고 확인한 뒤 공유 여부를 선택하는 흐름은 개발자 도구로서 설득력이 있습니다.

5. 아직 초기 버전이라 더 눈에 띈다

npm 기준 최신 버전은 0.1.14이고, GitHub 릴리스 페이지에는 별도 릴리스가 등록되어 있지 않았습니다. 성숙한 엔터프라이즈 문서 플랫폼이라기보다는 빠르게 실험 중인 오픈소스 도구에 가깝습니다.

그런데도 GitHub stars가 빠르게 쌓인 이유는 분명합니다. 많은 팀이 “AI가 만든 코드 변경을 팀 지식으로 어떻게 남길 것인가”라는 문제를 아직 해결하지 못했기 때문입니다.

Davia vs Notion, Confluence, Mermaid

Davia를 이해하려면 기존 문서 도구와의 차이를 보는 편이 빠릅니다.

도구	강점	Davia와의 차이
README/Markdown	Git과 잘 맞고 가볍다	인터랙티브 UI나 편집 가능한 화이트보드에는 약하다
Notion	팀 문서 작성과 공유가 쉽다	코드베이스 옆에서 AI 에이전트가 직접 생성하는 구조는 아니다
Confluence	조직 단위 문서 관리에 강하다	개발자 로컬 워크플로와 AI 에이전트 연결은 별도 설계가 필요하다
Mermaid	텍스트로 다이어그램을 관리하기 좋다	결과물을 직접 편집 가능한 화이트보드로 다루기는 어렵다
Davia	AI 에이전트가 로컬 문서와 다이어그램을 생성한다	아직 초기 버전이고 클라우드 업데이트 기능은 제한적이다

Davia가 기존 도구를 완전히 대체한다고 보기는 어렵습니다. 오히려 “AI 코딩 에이전트가 프로젝트를 이해하고 문서화하는 초기 레이어”로 쓰고, 팀 공식 문서는 Notion이나 Confluence로 옮기는 식의 조합이 더 현실적일 수 있습니다.

`davia docs`는 언제 쓰나

CLI에는 davia docs 명령도 있습니다.

davia docs --agent=claude-code --port=3005

패키지 내부 코드를 확인해보면, 이 명령은 문서 생성을 위해 AI API 키를 확인합니다. 키가 없으면 .env 또는 .davia/.env에 다음 중 하나를 넣으라고 안내합니다.

ANTHROPIC_API_KEY=your_api_key_here
OPENAI_API_KEY=your_api_key_here
GOOGLE_API_KEY=your_api_key_here

다만 공식 quickstart는 davia init --agent=... 후 사용 중인 코딩 에이전트에게 직접 문서화를 요청하는 흐름도 안내합니다. 이미 Claude Code나 Cursor를 쓰고 있다면, 처음에는 davia init 후 에이전트에게 직접 요청하는 방식이 더 이해하기 쉽습니다.

실전 프롬프트 예시

Davia를 초기화한 뒤에는 에이전트에게 구체적으로 요청하는 것이 좋습니다. “문서 만들어줘”보다 범위와 산출물을 지정하면 결과가 더 쓸 만해집니다.

전체 프로젝트 위키 만들기

Document this project using Davia.
Create an overview page, architecture map, main domain model page,
and key request flow diagrams.

인증 흐름만 문서화하기

Using Davia, document this project's authentication flow.
Include a visual diagram showing Client → API Server → Auth Service → Database.
Explain login, token creation, token validation, and logout.

API 스펙을 인터랙티브 문서로 만들기

Using Davia, create a wiki page for the API spec.
Group endpoints by category.
Show each endpoint as a card with method, path, summary, request body, and response shape.

데이터베이스 스키마만 표로 정리하기

Using Davia, generate a page that documents only the database schemas.
For each schema, include fields, relations, important indexes, and where it is used.

변경된 코드만 문서에 반영하기

Using Davia, update the local wiki for the recent changes in this branch.
Focus on modified services, changed API behavior, and any new diagrams needed.

Davia를 쓰면 좋은 경우

Davia는 다음 상황에서 특히 잘 맞습니다.

Cursor, Claude Code, GitHub Copilot 같은 AI 코딩 에이전트를 이미 쓰고 있다.
코드베이스가 커져서 신규 합류자 온보딩이 느리다.
인증, 결제, 큐, 데이터 파이프라인처럼 흐름 설명이 중요한 코드가 많다.
README 하나로는 프로젝트 구조를 설명하기 어렵다.
Mermaid 다이어그램을 만들지만, 나중에 수정하기 번거롭다.
AI 에이전트가 다음 작업에서도 참고할 수 있는 로컬 문서가 필요하다.

작은 팀이라면 특히 “새 기능을 만들 때마다 Davia로 관련 흐름을 업데이트한다”는 식으로 실험해볼 만합니다. 문서화가 별도 업무가 아니라 코드 변경의 일부가 되기 때문입니다.

아직 조심해야 할 점

Davia는 방향이 흥미롭지만 아직 초기 도구입니다. 다음 조건에 해당한다면 바로 팀 표준으로 도입하기보다 작은 프로젝트에서 먼저 테스트하는 편이 좋습니다.

문서 산출물을 반드시 Git에 커밋하고 리뷰해야 한다.
회사 문서 정책상 Notion, Confluence, Google Docs만 허용된다.
클라우드 워크스페이스 업데이트가 안정적으로 필요하다.
AI API 키나 외부 AI 코딩 에이전트를 코드베이스에 쓰기 어렵다.
생성된 문서의 정확성을 검토할 사람이 없다.

특히 마지막 항목이 중요합니다. Davia가 문서 생성을 돕더라도, AI 에이전트가 만든 설명이 항상 정확하다고 볼 수는 없습니다. 인증, 결제, 보안, 데이터 흐름 같은 문서는 반드시 사람이 한 번 검토해야 합니다.

문제 해결 체크리스트

`davia` 명령을 찾을 수 없을 때

전역 npm bin 경로가 PATH에 잡혀 있는지 확인합니다.

npm bin -g
which davia

전역 설치 대신 일회성 실행을 쓰면 PATH 문제를 피할 수 있습니다.

npm exec --yes --package=davia -- davia --help

`davia open`에서 프로젝트를 못 찾을 때

현재 디렉터리가 davia init을 실행한 프로젝트 루트인지 확인합니다.

pwd
ls -la .davia

다른 디렉터리에서 실행하면 Davia가 등록된 프로젝트를 선택하게 하거나, 프로젝트를 찾지 못할 수 있습니다.

`davia docs`가 API 키 오류를 낼 때

.env 또는 .davia/.env에 사용하려는 모델 제공자의 API 키를 넣습니다.

ANTHROPIC_API_KEY=...
OPENAI_API_KEY=...
GOOGLE_API_KEY=...

`davia push`가 실패할 때

먼저 로그인 상태와 네트워크를 확인합니다.

davia login
davia push

공식 문서상 push는 브라우저 인증을 요구할 수 있고, 기존 클라우드 워크스페이스 업데이트는 아직 지원되지 않습니다.

FAQ

Davia는 무료인가요?

Davia GitHub 저장소는 MIT 라이선스의 오픈소스 프로젝트입니다. CLI는 npm 패키지 davia로 설치할 수 있습니다. 다만 davia push로 사용하는 클라우드 워크스페이스의 정책은 공식 사이트와 계정 정책을 별도로 확인해야 합니다.

Davia는 Notion이나 Confluence를 대체하나요?

완전한 대체재라기보다는 AI 코딩 에이전트가 프로젝트 내부 문서를 생성하는 로컬 레이어에 가깝습니다. 팀 공식 문서는 Notion이나 Confluence에 두고, Davia는 코드베이스 분석과 다이어그램 초안 생성에 쓰는 조합도 가능합니다.

Davia 문서는 Git에 커밋해야 하나요?

기본 동작은 .davia 폴더를 .gitignore에 추가하는 방식입니다. 즉, 생성 문서를 로컬 작업물로 다루는 흐름이 기본입니다. 팀에서 문서를 Git으로 관리하려면 별도 규칙을 정해야 합니다.

Davia는 어떤 AI 코딩 에이전트와 쓸 수 있나요?

공식 문서 기준 Cursor, Claude Code, GitHub Copilot, Windsurf, OpenCode를 지원합니다. davia init --agent=cursor처럼 에이전트 이름을 지정하면 해당 도구에 맞는 규칙 파일을 생성합니다.

Davia를 바로 프로덕션 팀에 도입해도 될까요?

작은 프로젝트나 사이드 프로젝트에서 먼저 테스트하는 편이 좋습니다. npm 최신 버전은 0.1.14로 아직 초기 버전이며, 공식 문서상 기존 cloud workspace 업데이트도 아직 지원되지 않습니다.

정리

Davia가 흥미로운 이유는 단순히 “문서를 자동 생성한다”가 아닙니다. 더 정확히는 AI 코딩 에이전트가 코드를 바꾸는 속도에 맞춰, 프로젝트 맥락도 같이 남기려는 시도입니다.

코드 생성은 점점 쉬워지고 있습니다. 하지만 “왜 이렇게 만들었는지”, “어떤 흐름이 어디와 연결되는지”, “다음 사람이 무엇을 먼저 봐야 하는지”는 여전히 어렵습니다. Davia는 이 문제를 로컬 문서, 인터랙티브 페이지, 편집 가능한 화이트보드로 풀려고 합니다.

지금 당장 모든 팀에 필수 도구라고 말하기는 어렵습니다. 아직 초기 버전이고, 클라우드 동기화도 제한이 있습니다. 그래도 AI 코딩 에이전트를 자주 쓰는 개발자라면 한 번 테스트해볼 만합니다. 특히 프로젝트 구조를 시각화하거나, 인증/결제/API 흐름을 문서화해야 하는 팀이라면 Davia의 방향성이 꽤 잘 맞을 수 있습니다.

가장 짧은 테스트 흐름은 다음입니다.

npm i -g davia
cd your-project
davia init --agent=claude-code
# Claude Code 또는 사용 중인 에이전트에서: "Use Davia to document this project."
davia open

참고 자료

GitHub 저장소: https://github.com/davialabs/davia
공식 문서: https://docs.davia.ai/
What is Davia: https://docs.davia.ai/what-is-davia.md
Quickstart: https://docs.davia.ai/quickstart.md
CLI Commands: https://docs.davia.ai/reference/cli-commands.md
Supported Agents: https://docs.davia.ai/reference/supported-agents.md
npm package: https://www.npmjs.com/package/davia

AI/IT도구에서 이어서 보면 좋은 글

한 번 더 클릭하게 만드는 내부 링크 구간입니다. 같은 주제의 실용 글로 이동시키고, 카테고리 허브로도 연결합니다.