Rootr 사용 가이드

먼저, 몇 가지 용어부터

Rootr는 "AI가 함께 쓰는 문서 도구"입니다. 그래서 가장 먼저 할 일은 당신의 AI를 Rootr에 연결하는 것입니다. 아래 용어만 알면 이 장 전체가 쉬워집니다.

• AI 에이전트(agent): 단순히 대화만 하는 게 아니라, 시킨 일을 실제로 처리해 주는 AI를 말합니다. 예를 들어 Claude Code, Claude Desktop, Codex 같은 프로그램입니다. 이 가이드에서 "에이전트"는 곧 "당신의 AI"라고 생각하시면 됩니다.
• API: 프로그램끼리 정보를 주고받는 통로입니다. 사람이 화면의 버튼을 누르는 대신, AI가 이 통로로 Rootr에 "이 문서 보여줘", "여기에 한 줄 추가해줘" 같은 요청을 보냅니다.
• API 키(key): 그 통로를 열 수 있는 "열쇠"이자 신분증입니다. `rootr_`로 시작하는 긴 문자열이며, 이 열쇠를 가진 AI만 당신의 자료에 접근할 수 있습니다. 그래서 비밀번호처럼 남에게 보여주면 안 됩니다.
• MCP: AI가 외부 도구를 표준 방식으로 쓰게 해주는 규칙(약속)입니다. 쉽게 말해 "AI와 Rootr 사이의 만능 어댑터"입니다. MCP로 연결해두면 AI가 Rootr를 자기 컴퓨터의 폴더처럼 다룹니다.
• 워크스페이스(workspace): 당신의 문서·폴더가 모여 있는 공간입니다. 회사로 치면 하나의 "작업실"입니다. 각 워크스페이스에는 고유 id가 있습니다.

연결하는 방법은 크게 네 갈래입니다. ① 주소(URL) 하나만 붙여넣으면 끝나는 원격 커넥터, ② 클릭 몇 번으로 키를 만들어 붙여넣는 원클릭 MCP, ③ 설정 파일을 직접 다루는 방식, ④ 프로그램에서 직접 부르는 API. 개발을 모르셔도 ①만 하면 충분합니다. 그림으로 보면 이렇습니다.

1.1 원격 커넥터 — URL 붙여넣고 로그인만 (가장 쉬움, 권장)

설치·터미널·설정 파일 없이 연결하는 방법입니다. Claude와 ChatGPT 모두 아래 주소 하나로 연결됩니다.

1. AI 설정에서 커넥터(Connectors) → 커스텀 커넥터 추가를 열고, 위 주소를 붙여넣습니다.
2. 브라우저에 Rootr 화면이 뜹니다. 로그인하고, 연결할 워크스페이스와 권한(읽기 전용 / 읽기+쓰기)을 골라 허용을 누릅니다.
3. AI 화면에 Rootr 도구들이 나타나면 성공입니다. 시험 삼아 "내 워크스페이스에 어떤 문서가 있어?"라고 물어보세요.

• ChatGPT는 유료 플랜에서만 커넥터를 지원합니다.
• ChatGPT에게 문서 생성·수정까지 시키려면 커넥터 고급 설정에서 개발자 모드(Developer mode)를 켜야 합니다 (OpenAI 정책).

화면 캡쳐로 하나씩 따라 하는 Claude·ChatGPT 연결 가이드 →

1.2 원클릭 MCP 키 연동 — 컴퓨터에 설치해 쓰는 방식

Rootr가 연결에 필요한 설정을 자동으로 만들어 줍니다. 당신은 그걸 복사해서 AI에 붙여넣기만 하면 됩니다. 순서는 이렇습니다.

1. 왼쪽 메뉴에서 설정(Settings)을 엽니다.
2. 설정 안에서 연동(Integrations) 탭을 누릅니다.
3. "AI 에이전트 연동 (MCP)" 항목을 찾아 MCP 키 만들기… 버튼을 누릅니다.
4. 키에 이름을 붙이고(예: "내 노트북 Claude"), 어디까지 허용할지 권한을 고른 뒤 만들기를 누릅니다. 그러면 아래 코드 상자에 열쇠(API 키)가 채워진 설정이 자동으로 나타납니다.
5. 당신이 쓰는 AI에 맞는 복사 버튼을 눌러, 아래 안내대로 붙여넣습니다.

복사 버튼은 당신이 쓰는 AI 종류에 따라 세 가지가 있습니다.

• Claude Code(터미널에서 쓰는 Claude): 복사한 한 줄 명령을 터미널 창에 그대로 붙여넣고 실행하면 연결이 끝납니다.
• Claude Desktop(앱): 복사한 내용을 Claude 설정 파일(`claude_desktop_config.json`)에 넣고 앱을 다시 켜면 됩니다. 이 파일 위치는 Claude Desktop 설정 화면에서 찾을 수 있습니다.
• Codex CLI: 복사한 명령을 터미널에 붙여넣으면 자동으로 설정 파일에 저장됩니다.

1.3 수동으로 MCP 등록하기 (설정 파일을 직접 다루는 분)

개발에 익숙해서 설정 파일을 직접 관리하고 싶다면 아래처럼 넣습니다. 이건 "Rootr에 연결되는 작은 프로그램(rootr-cli)을 AI가 실행하도록" 알려주는 설정입니다. `ROOTR_API_KEY`에는 위에서 만든 열쇠를, `ROOTR_WORKSPACE`에는 워크스페이스 id를 넣습니다.

Claude Code라면 이 내용을 `~/.claude.json` 파일에, Claude Desktop이라면 `claude_desktop_config.json` 파일의 `mcpServers` 부분에 넣습니다. `rootr-cli`를 컴퓨터에 전역 설치했다면 `command`를 `"rootr"`로, `args`를 `["mcp"]`로 짧게 써도 됩니다.

1.4 rootr CLI — 터미널에서 사람이 직접

CLI(명령줄 도구)는 검은 터미널 창에 명령을 입력해 Rootr를 다루는 방법입니다. AI 없이 사람이 직접 쓰거나, 정해진 시간에 자동으로 도는 스크립트에 넣을 때 유용합니다. 아래 명령을 순서대로 실행해 보세요.

• 경로 쓰는 법: 슬래시(/)로 시작하면 "폴더 경로"로, 아니면 "문서의 고유 번호(id)"로 알아서 인식합니다.
• "append(덧붙이기)"를 권합니다: 문서 전체를 다시 쓰지 않고 끝에 이어 붙이기만 하므로, 다른 사람이나 다른 프로그램이 동시에 편집해도 서로 충돌하지 않습니다.
• 한 줄씩 설명이 필요하면 `rootr --help`를 입력하면 사용법이 나옵니다.

1.5 REST API로 직접 부르기 (프로그래머용)

직접 프로그램을 만든다면, 어떤 언어에서든 인터넷 요청(HTTP)으로 Rootr를 부를 수 있습니다. 주소는 `https://rootr.io/api/v1`이고, 요청할 때마다 열쇠를 `x-api-key`라는 이름표에 담아 보냅니다. 아래는 터미널에서 바로 시험해 볼 수 있는 예시입니다.

각 명령이 어떤 뜻인지 몰라도 괜찮습니다. 요점은 "열쇠를 헤더에 담아 주소로 요청을 보낸다"는 것입니다. 사용할 수 있는 모든 요청의 전체 목록은 ⑩ 레퍼런스에 링크된 기술 문서(OpenAPI)에서 볼 수 있습니다.

1.6 열쇠(API 키)의 두 종류와 권한

열쇠는 두 종류가 있고, 얼마나 넓은 범위까지 열 수 있는지가 다릅니다. 또 각 열쇠에는 "무엇까지 허용할지"를 정하는 권한(스코프)이 붙습니다. 필요한 만큼만 허용하는 게 안전합니다.

• 권한(스코프) 예: docs:read(문서 읽기) · docs:write(문서 수정) · graph:read(지식 열람) · ask(질문하기) · webhooks:manage(알림 설정). 읽기만 시키고 싶으면 docs:read만 켜면 됩니다.
• 원칙: 대부분의 연결은 워크스페이스 키로 충분합니다. 계정 키는 권한이 넓으니 꼭 필요할 때만 쓰세요.

1.7 AI에게 일을 시키는 요령

연결이 끝나면 AI에게 자연어로 시키면 됩니다("이 문서 요약해서 아래에 붙여줘"). 결과가 더 안전하고 정확하려면 아래를 지키게 하세요.

• 내용 추가는 "덧붙이기(append)", 부분 수정은 "찾아 바꾸기(edit)"를 먼저 쓰게 하세요. 문서 전체를 새로 쓰는 방식은 실수로 기존 내용을 지울 수 있어, 정말 필요할 때만 씁니다.
• 워크스페이스를 처음부터 구조로 만들 땐, AI가 먼저 계획을 세우고 몇 가지 질문을 한 뒤 만들게 하세요(무작정 만들지 않도록).
• 변경 알림(웹훅)을 다시 AI가 받게 해두었다면, "AI 자신이 만든 변경"은 무시하도록 하세요. 안 그러면 자기가 만든 알림에 자기가 반응하는 무한 반복이 생깁니다.

1.8 AI가 쓸 수 있는 도구 목록 (총 38개)

연결하면 AI는 아래 도구들을 쓸 수 있게 됩니다. 종류별로 묶어 요약한 표이며, 각 도구의 자세한 설명은 ⑩ 레퍼런스에 있습니다. 지금은 "이만큼 다양한 일을 시킬 수 있구나" 정도만 보시면 됩니다.

Rootr가 처음이라면 이 순서대로만 따라오세요. 개발 지식은 필요 없습니다.

2.1 가입하고 로그인하기

• 이메일과 비밀번호로 가입하거나, 구글 계정으로 클릭 한 번에 시작할 수 있습니다.
• 처음 로그인하면 "첫 워크스페이스(작업 공간)를 만드세요"라는 안내가 나옵니다. 워크스페이스는 문서와 폴더가 담기는 나만의 공간입니다.

2.2 문서와 폴더 만들기

화면 왼쪽에 트리(나뭇가지처럼 펼쳐지는 목록)가 있습니다. 여기서 폴더를 만들어 분류하고, 그 안에 문서를 만듭니다. 컴퓨터의 폴더/파일과 똑같다고 생각하시면 됩니다.

2.3 "AI로 만들기"로 한 번에 구성하기

빈 화면부터 하나하나 만들 필요가 없습니다. "무엇을 하고 싶은지" 한 문장으로 적으면(예: "신제품 출시 준비 공간 만들어줘"), AI가 몇 가지를 되물은 뒤 폴더·문서·표까지 갖춘, 바로 쓸 수 있는 구조를 자동으로 만들어 줍니다.

문서를 저장하면, 뒤에서 자동으로 그 내용이 "지식 지도"로 정리됩니다(자세한 건 ⑥장). 그리고 곧바로 ①장으로 가서 AI를 연결하세요 — 그때부터가 Rootr의 진짜 힘입니다.

Rootr의 문서는 "블록"이라는 조각들로 이뤄집니다. 제목, 문단, 목록, 표, 그림 하나하나가 블록입니다. 원하는 곳에 끼워 넣고 순서를 바꿀 수 있어, 글쓰기가 훨씬 자유롭습니다.

• 실시간 공동 편집: 여러 명이 같은 문서를 동시에 열어 고쳐도, 서로의 변경이 즉시 반영됩니다. 누가 어디를 보고 있는지도 표시됩니다.
• 버전 기록(자동 저장 이력): 문서를 고칠 때마다 이전 상태가 자동으로 저장됩니다. 실수로 지웠어도 예전 버전으로 되돌릴 수 있습니다(오른쪽 위 시계 아이콘).
• 특별한 블록들: 강조 상자(콜아웃), 태그(꼬리표), 그리고 순서도 같은 그림을 코드로 그리는 mermaid 다이어그램을 넣을 수 있습니다. AI가 문서를 쓸 때도 이런 다이어그램을 자동으로 그려 줍니다.
• 외부에서 넣은 내용도 실시간 반영: AI나 프로그램이 API로 문서에 글을 추가하면, 지금 그 문서를 열어 보고 있는 화면에도 바로 나타납니다.

아래는 버전 기록 화면입니다. 문서를 고친 시점들이 목록으로 남아, 언제든 그때 내용을 확인하거나 되돌릴 수 있습니다.

"노드"는 트리(왼쪽 목록)에 들어가는 항목 하나하나를 부르는 말입니다. 문서도 노드, 폴더도 노드, 표도 노드입니다. Rootr에는 아래처럼 여러 종류의 노드가 있고, 하려는 일에 맞는 걸 고르면 됩니다. 먼저 전체를 한눈에 보고, 그다음 중요한 것들을 하나씩 설명합니다.

DATABASE (표) — 형식이 정해진 목록

엑셀 표와 노션 데이터베이스를 합친 것이라고 보시면 됩니다. 각 칸(열)마다 "이 칸은 글자, 저 칸은 날짜, 이 칸은 상태(선택)" 하고 형식을 정합니다. 같은 데이터를 네 가지 방식으로 볼 수 있습니다 — 표(table), 칸반 보드(board, 상태별로 카드가 열을 이룸), 달력(calendar), 타임라인. 행 추가·수정은 화면에서도, AI에게 시켜서도 됩니다.

WHITEBOARD · PRESENTATION · FORM

• 화이트보드: 도형과 연결선으로 자유롭게 그리는 넓은 캔버스입니다. 구조도나 아이디어 정리에 좋습니다.
• 발표(PRESENTATION): 슬라이드를 만드는 곳입니다. 슬라이드의 제목·본문·메모에 적은 "글"이 지식 지도에 자동으로 연결되므로, 중요한 내용은 반드시 글로 적고, 이미지에는 설명(캡션)을 달아 주세요.
• 설문/폼(FORM): 워크스페이스 바깥에 있는 사람에게 링크를 보내 응답을 받는 양식입니다. 받은 응답은 표(DATABASE)에 자동으로 모입니다.

ISSUE_TRACKER (이슈) · LOG (데이터 기록)

• 이슈 트래커: 버그나 할 일을 하나씩 "이슈"로 만들어, 번호(#1, #2…)·상태(열림/닫힘)·라벨·담당자·댓글로 추적합니다. 개발 협업 도구(GitHub)의 이슈와 같은 방식입니다.
• LOG(데이터 기록장): 시간에 따라 쌓이는 기록(예: 서버 응답 시간, 장애 이벤트)을 형식을 정해 넣는 곳입니다. 여기서 "관계(relation)" 칸을 쓰면, 그 기록이 어디서 비롯됐는지 자동으로 이어지는 "데이터 계보"가 생깁니다(⑦장).

팀으로 쓸 때 가장 중요한 건 "누가 어디까지 볼 수 있느냐"입니다. Rootr는 이걸 아주 간단하게 다룹니다.

역할(권한 등급)

• Owner(소유자): 워크스페이스의 모든 것을 관리. Admin(관리자): 구성원·설정 관리. Member(구성원): 문서 작성·편집. Viewer(뷰어): 보기만 가능.
• 권한은 폴더에서 그 안의 문서로 자동으로 물려받습니다. 즉 폴더 하나에 권한을 정하면 그 안 전체에 적용됩니다. 특정 문서만 예외로 따로 정할 수도 있습니다.

비공개 · 공유 · 공개

• 비공개 노드: "초대된 사람만" 스위치를 켜면, 내가 만든 문서/폴더를 나(와 초대한 사람)만 볼 수 있게 숨길 수 있습니다.
• 공유 링크로 초대: 링크를 보내 워크스페이스 바깥의 사람을 초대할 수 있습니다.
• 외부 공개(발행): 특정 문서를 인터넷 주소(`/p/문서이름`)로 누구나 볼 수 있게 공개할 수 있습니다. 공개 문서는 외부인이 "이렇게 고치면 어떨까요"라고 수정을 제안할 수 있고, 소유자가 그 제안을 받아들이거나(merge) 거절할(reject) 수 있습니다 — 마치 문서판 협업(Git)처럼요.

지식 지도(지식그래프)란?

문서를 저장하면 Rootr가 뒤에서 자동으로 그 안의 "중요한 대상"과 "관계"를 뽑아냅니다. 예를 들어 사람·팀·서비스·시스템·장애·결정 같은 것들을 찾아내고, "이 장애가 저 서비스에서 일어났다" 같은 연결을 만듭니다. 이렇게 점(대상)과 선(관계)으로 이어진 지도를 "지식그래프", 쉽게 말해 "지식 지도"라고 합니다. 흩어진 문서 여러 개가 하나의 연결된 그림이 되는 것입니다.

• 미니 지도: 문서 하나를 열면, 그 문서가 언급한 대상들을 작은 지도로 바로 볼 수 있습니다.
• 전체 지도 탐색: 그래프 화면에서 특정 대상을 검색하고, 그 주변에 무엇이 연결됐는지, 두 대상 사이에 어떤 경로가 있는지 따라갈 수 있습니다.

Ask — "왜?"라고 물어보기 (근본 원인 분석)

Ask(질문) 기능에 평소 말로 질문하면(예: "지난주부터 결제가 왜 자꾸 실패하지?"), Rootr는 지식 지도와 문서를 함께 뒤져서, 근거(어느 문서의 어느 문장에서 나왔는지)를 함께 붙인 답을 줍니다. 특히 "무엇이 원인인지"를 추적하는 근본 원인 분석(RCA)에 강합니다. 같은 질문을 앞서 배운 CLI나 API의 `ask`로도 할 수 있습니다.

LOG(데이터 기록장)란?

LOG는 시간에 따라 쌓이는 기록을 담는 특별한 표입니다. 일반 표와 다른 점은, 넣기 전에 "칸의 형식"을 정한다는 것입니다 — 이 칸은 글자, 이 칸은 숫자, 이 칸은 심각도(정보/경고/오류), 이 칸은 시각 하는 식으로요. 그러면 이상한 값이 들어오는 걸 걸러 주고, 평소와 크게 다른 값(이상치)을 자동으로 표시해 줍니다. 서버 응답 시간, 장애 이벤트, 작업 처리 건수 같은 걸 기록하기에 좋습니다.

"계보(리니지)"란?

계보(데이터 리니지)는 "이 데이터가 어디서 왔고, 무엇이 여기서 비롯됐는지"의 연결입니다. 족보(가계도)를 떠올리면 쉽습니다. LOG의 칸 중 "관계(relation)" 형식의 칸을 쓰면, 한 기록이 다른 기록을 가리키게 되고, 그 순간 둘 사이에 계보 선이 자동으로 그어집니다. 그래서 나중에 "이 장애의 원인이 된 앞선 이벤트가 뭐였지?"를 그림으로 따라갈 수 있습니다.

• 넣는 방법: 화면 입력, 파일 업로드(CSV/엑셀), 또는 프로그램/센서에서 실시간 전송까지 지원합니다.
• 자동 연결: 관계 칸에 값을 넣으면 계보 선이 저절로 생깁니다. 따로 관리할 필요가 없습니다.
• 통계: 시간별·항목별로 개수·평균·최대 같은 요약을 볼 수 있습니다.

웹훅(변경 알림)이란?

웹훅은 "Rootr에서 무슨 일이 생기면, 정해둔 다른 프로그램에 그 사실을 자동으로 알려주는 기능"입니다. 예를 들어 "이 폴더의 문서가 바뀌면 우리 팀 채팅으로 알림을 보내라"처럼요. 사람이 계속 지켜볼 필요 없이 변화에 반응하게 만들 수 있습니다.

• 범위 좁히기: 워크스페이스 전체가 아니라 특정 폴더·문서로만 한정하거나, 태그(꼬리표)로 걸러서 원하는 것만 알림받을 수 있습니다(상위 폴더의 태그는 그 안에도 적용됩니다).
• 무엇이 바뀌었는지: 문서/댓글/시스템 종류로 구분되며, 전체 내용이 아니라 "바뀐 부분(차이)"만 담아 보내 안전합니다.
• 서명 키: 알림이 진짜 Rootr에서 온 것인지 확인하는 열쇠가 만들 때 한 번 발급됩니다. 받는 쪽 서버에 저장해 두세요.

또한 이슈 트래커는 실시간(SSE)으로 화면이 갱신되고, 외부 시스템과 양방향으로 연결할 수 있습니다. 앞서 배운 CLI/AI 연결을 정해진 시간에 자동 실행하도록 걸어두면, "문서가 바뀌면 → AI가 요약을 덧붙인다" 같은 자동 흐름도 만들 수 있습니다.

• 여러 계정 동시 사용: 회사 계정과 개인 계정처럼 여러 계정에 함께 로그인해두고, 클릭으로 전환하며 쓸 수 있습니다.
• 요금제: 사용 인원(좌석) · 저장 공간 · AI 사용량을 조합한 방식입니다. AI 기능은 요금제마다 정해진 "그래프 크레딧"만큼 쓸 수 있습니다. 정확한 가격과 포함 범위는 요금제 페이지에서 확인하세요. 3명까지는 무료로 시작할 수 있습니다.
• 가져오기: 다른 곳에 있던 문서를 워크스페이스로 불러올 수 있습니다.

여기는 직접 프로그램을 만드는 분을 위한 참고 자료 모음입니다. 화면으로만 쓰신다면 이 장은 건너뛰어도 됩니다.

• REST API 전체 명세: 사용할 수 있는 모든 요청이 기계가 읽을 수 있는 형식으로 정리된 문서 — `/api/api-docs-json`.
• GraphQL 스키마: 또 다른 질의 방식의 전체 구조 — `/api/graphql/sdl`.
• AI 도구 38종 상세: `rootr-cli`의 설명서(README)에 각 도구가 무엇을 하는지 자세히 적혀 있습니다.

자주 만나는 오류와 해결