가이드

1. 플랜 만들기

플랜은 이렇게 정리되며, 가입하고 나면 앞의 두 단계는 이미 준비되어 있습니다.

워크스페이스          사람, 역할, 에이전트가 접속할 때 쓰는 키
  └─ 프로젝트         만들고 있는 것 하나, 그리고 그 플랜들이 쓰는 말
       └─ 폴더        선택 사항이며, 폴더 안에 폴더를 둘 수 있음
            └─ 플랜   그래프 하나

앱은 한 화면입니다. 왼쪽 사이드바에는 최근이 있고, 그 아래에 워크스페이스의 모든 프로젝트가 폴더, 플랜과 함께 나옵니다. 프로젝트나 폴더를 클릭하면 펼치거나 접고, 플랜을 클릭하면 오른쪽에 열립니다. 설정, 멤버, 휴지통도 오른쪽에 열리며, 그동안에도 사이드바는 옆에 그대로 있습니다. 사이드바의 가장자리를 끌면 폭을 넓힐 수 있습니다.

프로젝트나 폴더에 마우스를 올리면 그 줄에 새 플랜과 새 폴더 아이콘이 나타나며, 누르면 그 안에 만들어집니다. 트리 맨 아래의 아이콘으로는 플랜, 폴더, 새 프로젝트를 만듭니다. 이름은 트리에서 바로 입력합니다. 플랜이나 폴더를 다른 폴더로 끌어다 놓으면 그 안으로 옮겨지고, 줄의 메뉴나 오른쪽 클릭으로 이름 바꾸기, 이동, 공유, 내보내기, 휴지통으로 옮기기를 할 수 있습니다.

처음부터 General 프로젝트가 하나 있습니다. 플랜은 문서가 아니라 그래프입니다. 위에서 아래로 써 내려가는 대신, 항목을 추가하고 서로 어떤 관계인지 밝혀 나가게 됩니다.

2. 그리기

노드를 만드는 가장 빠른 방법은 다른 노드에서 시작하는 것입니다. 노드 오른쪽의 단자에서 끌어 빈 캔버스에 놓으면, 놓은 자리에 이미 연결된 새 노드가 생기고 바로 제목을 입력할 수 있습니다. Enter를 누르면 남고, Escape를 누르면 다시 없어집니다. 그룹 안에 놓으면 새 노드는 그 그룹에 들어갑니다. 빈 플랜에서는 타이틀 블록의 노드 추가나, 캔버스를 오른쪽 클릭했을 때 나오는 여기에 노드 추가로 같은 방식으로 만듭니다. 제목을 더블클릭하면 카드 위에서 바로 이름을 바꿀 수 있습니다.

노드를 클릭하면 오른쪽에 패널이 열립니다. 여기서 종류, 상태, 태그를 정하고 내용을 원하는 만큼 적습니다. 내용은 내보낼 때 그 노드의 Markdown 파일 본문이 되므로, 제대로 써 둘 만합니다.

새로 그은 연결은 모두 흐름으로 시작합니다. 연결을 클릭해 의미를 고르세요.

• 흐름 — 시스템이 실제로 움직이는 방향입니다. 이 화면이 저 엔드포인트를 호출하고, 그 엔드포인트가 저 테이블을 읽는 식입니다. 무엇이 이 전달을 일으키는지, 무엇을 싣고 가는지 적으면 둘 다 선 위에 표시됩니다. 응답은 반대 방향을 가리키는 흐름을 하나 더 그리면 됩니다. 목록이 아니라 시스템을 그리게 해 주는 것이 바로 이 연결입니다.
• 포함 — 감싸는 쪽에서 안에 들어갈 쪽으로 이어집니다. 내보낼 때 디렉터리가 되는 것이 이 연결이며, 그룹을 끌면 안에 든 것이 모두 함께 움직입니다.
• 의존 — 무엇이 먼저 있어야 하는지를 나타냅니다. 무엇이 무엇을 호출하는지와는 다른 이야기입니다. 내보낼 때 파일에 번호를 매기는 순서가 됩니다.
• 관련 — 구조를 담지 않는 단순한 연관입니다.

같은 패널에서 무엇이 연결을 일으키는지, 무엇을 싣고 가는지 적거나 연결을 지웁니다.

자동 배치를 누르면 그래프를 알아서 배치해 줍니다. 손으로 끌어다 놓은 것은 움직이지 않습니다. 직접 놓은 노드는 그때부터 고정되며, 직접 다시 옮기지 않는 한 고정은 풀리지 않습니다.

3. 캔버스 다루기

캔버스는 그림 도구처럼 다룹니다.

• 빈 캔버스에서 끌면 선택 상자가 그려지고, 상자에 닿은 노드가 모두 선택됩니다. Shift를 누른 채 끌면 지금 선택에 더해집니다. Shift, Ctrl, ⌘ 중 하나를 누른 채 클릭하면 노드 하나를 선택에 넣거나 뺍니다.
• 화면 이동은 마우스 가운데 버튼으로 끌거나, Space를 누른 채 끌거나, 휠을 굴리면 됩니다. Shift와 휠을 함께 쓰면 옆으로 움직입니다. 확대와 축소는 Ctrl이나 ⌘을 누른 채 휠을 굴리거나 두 손가락을 오므리고 벌려서 합니다.
• 선택한 것을 끌면 한꺼번에 옮겨지고, Backspace나 Delete를 누르면 지워집니다.
• Alt/⌥를 누른 채 끌면 원래 노드는 제자리에 두고, 놓은 자리에 복사본을 만듭니다.
• Ctrl/⌘ + C, X, V로 복사, 잘라내기, 붙여넣기를 합니다. 붙여넣기는 포인터 위치에 되며, 다른 플랜이나 탭에도 붙여 넣을 수 있습니다. Ctrl/⌘ + D는 그 자리에서 복제합니다.

끄는 동안 캔버스는 간격도 맞춰 줍니다. 노드를 옆 노드와의 거리가 이미 있는 다른 두 노드 사이의 거리와 같아지는 곳으로 가져가면 그 자리에 붙고, 같은 간격이 분홍색 치수로 표시됩니다. 간격이 고른 노드를 가로나 세로 한 줄로 선택하면 간격마다 손잡이가 나타나며, 하나를 끌면 모든 간격이 한꺼번에 바뀝니다. 간격이 고르지 않다면 먼저 오른쪽 클릭해 간격 고르게 맞추기를 고르세요.

4. 내용 쓰기

노드의 내용은 블록 편집기입니다. #과 공백을 입력하면 제목이 되고(##, ###은 더 작은 제목), -는 목록, 1.은 번호 목록, []는 할 일, >는 인용, 백틱 세 개는 코드, ---는 구분선이 됩니다. /를 입력하면 모든 블록의 메뉴가 열리며, 여기에는 표, 토글, 콜아웃(메모, 팁, 주의, 위험)도 있습니다. 블록 옆의 손잡이를 끌면 블록을 다른 곳으로 옮길 수 있습니다.

여러 사람이 같은 내용을 동시에 쓸 수 있고, 쓰는 동안 서로의 커서가 보입니다. 에이전트가 쓰는 내용도 같은 방식으로 합쳐집니다. 캔버스의 카드에도 제목까지 같은 내용이 그대로 보이며, 할 일은 카드에서 바로 체크할 수 있습니다.

편집기 밖에서는 내보내기든 에이전트든 모두 내용을 Markdown으로 읽습니다. 표는 Markdown 표가 되고, 토글은 <details> 블록, 콜아웃은 Obsidian 콜아웃이 되므로 보관소에서도 원래 모습대로 열립니다.

5. 프로젝트의 상태·종류·태그

종류와 상태는 프로젝트에 속하므로, 한 프로젝트의 모든 플랜이 같은 말을 씁니다. 새 프로젝트는 상태 아이디어, 계획됨, 진행 중, 막힘, 완료, 중단과 종류 기능, 작업, 결정, 메모, 그룹으로 시작합니다. 상태 선택 목록에는 상태마다 제 색이, 종류 선택 목록에는 종류마다 테두리 모양이 보입니다. 두 목록 모두 맨 끝에 편집…이 있어, 누르면 프로젝트 설정의 상태·종류·태그가 열립니다.

여기서 추가하고, 이름과 색을 바꾸고, 순서를 정합니다. 상태마다 할 일, 진행 중, 막힘, 완료, 취소 중 하나의 분류가 있고, 분류가 그 상태의 역할을 정합니다. 에이전트에게 다음 일로 무엇을 제안할지, 어떤 흐름을 빨간색으로 그릴지, 무엇을 진행률로 셀지가 여기에 달려 있습니다. 종류마다 테두리 모양이 있고, 작업으로 셀지도 정합니다. 상태나 종류를 없애면 보관됩니다. 선택 목록에서는 빠지지만, 그 값을 쓰는 노드는 누군가 바꿀 때까지 그대로 유지합니다. 그룹은 기본 제공이라 없앨 수 없습니다.

태그는 선택 목록처럼 씁니다. 입력하면 프로젝트의 태그가 걸러지고, Enter를 누르면 강조된 태그가 골라지거나, 맞는 것이 없으면 제 색을 가진 새 태그가 만들어집니다. 입력란이 비어 있을 때 Backspace를 누르면 마지막 태그가 빠집니다. 태그의 메뉴에서는 색을 바꾸거나 프로젝트에서 삭제할 수 있으며, 삭제해도 노드에는 이름이 남습니다.

6. 에이전트 연결하기

계정 설정에서 에이전트를 열고 키를 만든 다음, URL과 키를 MCP 클라이언트에 붙여 넣으세요. 컴퓨터에 따로 설치하는 것은 없고, 서버에는 HTTP로 접속합니다. 정확한 설정 블록과 전체 도구 목록은 문서에 있습니다.

키는 내가 멤버로 있는 모든 곳에서 나로서 동작하므로, 워크스페이스가 몇 개든 키 하나면 충분합니다. 키는 클라이언트 하나에만 주고, 그 클라이언트의 이름을 붙여 두고, 그 컴퓨터를 다른 사람에게 넘길 때는 폐기하세요.

7. 에이전트에게 그리게 하기

에이전트에게 평소처럼 계획을 쓰게 한 다음, 그 계획을 캔버스에 올려 달라고 하세요. 에이전트는 create_plan으로 플랜을 엽니다. 원하면 경로를 주어 폴더에 바로 넣을 수도 있습니다.

{
  "name": "create_plan",
  "arguments": {
    "title": "Billing rework",
    "folder": "Specs/Billing"
  }
}

그다음 apply_ops로 그립니다. 여러 변경을 묶어 원자적으로 처리하는 호출 한 번이며, 결과는 열려 있는 모든 캔버스에 동시에 나타납니다. 그 뒤의 모든 변경도 이 호출로 합니다.

{
  "name": "apply_ops",
  "arguments": {
    "planId": "…",
    "ops": [
      { "op": "upsert_node",
        "node": { "slug": "pricing-rules", "title": "Pricing rules" } },
      { "op": "upsert_node",
        "node": { "slug": "tax", "title": "Tax by region",
                  "kind": "decision", "status": "blocked" } },
      { "op": "upsert_edge",
        "edge": { "from": "tax", "to": "pricing-rules",
                  "carries": "rate table" } }
    ]
  }
}

여기에 빠진 것이 있습니다. 바로 좌표입니다. 에이전트는 구조만 선언하고 배치는 서버가 합니다. 언어 모델에게 위치를 정하게 하면 아무도 읽고 싶지 않은 다이어그램이 나오고, 그러느라 컨텍스트까지 소모하기 때문입니다. 또 노드는 식별자로 가리키므로, 같은 호출을 두 번 보내도 두 번째에는 아무것도 바뀌지 않습니다.

에이전트도 프로젝트의 말을 씁니다. 플랜을 읽으면 어떤 종류와 상태가 있는지 알게 되고, 프로젝트에 없는 값을 쓰면 있는 값의 목록과 함께 거절됩니다. 그래서 에이전트가 제멋대로 상태를 지어낼 수 없습니다.

에이전트에게 한 가지 부탁해 둘 만한 것이 있습니다. 사람이 알아볼 수 있는 식별자입니다. pricing-rules는 다음 메시지에서 이름으로 부를 수 있지만, node-7은 그렇지 않습니다.

8. 파일 가져가기

내보내기를 누르면 zip 파일을 내려받습니다. 포함 관계는 디렉터리가 되고, 의존 순서는 각 파일 이름의 번호가 되며, 노드마다 자기 frontmatter를 담고 있습니다. 그래서 이 묶음은 그래프를 그림으로 보여 주는 데 그치지 않고, 그래프 자체를 빠짐없이 기술합니다.

plan-export.zip
├── README.md                 개요와 목차
├── 01-foundation/            다른 노드를 포함하는 노드는 디렉터리가 됨
│   ├── README.md             …그 노드 자신의 내용은 여기에
│   ├── 01-ledger-schema.md
│   └── 02-pricing-rules.md   의존 관계에 따라 번호가 붙음
├── 02-invoicing/
│   └── 01-render-pdf.md
├── plan.canvas               Obsidian에서 배치 그대로 열림
└── plan.json                 같은 내용을 기계가 읽는 형식으로

폴더를 Obsidian 보관소에 넣으면 plan.canvas가 같은 다이어그램으로 열립니다. 아니면 소스 코드 옆에 커밋해 두세요. 에이전트가 실행할 때마다 읽게 되는데, 사실 이것이 이 모든 일의 목적입니다.

의존 관계에 순환이 있어도 내보내기는 막히지 않습니다. 순환은 매번 같은 방식으로 끊기고 README에 기록되므로, 같은 플랜은 언제나 같은 파일로 내보내집니다.

9. 다른 사람과 함께 작업하기

편집은 실시간으로 이루어집니다. 한 플랜을 함께 보는 두 사람은 서로의 변경을 바로바로 보고, 같은 노드의 내용을 동시에 입력해도 한쪽이 다른 쪽을 덮어쓰지 않고 합쳐집니다. MCP로 쓰는 에이전트도 참여자 한 명일 뿐입니다.

공유를 누르면 계정 없이도 누구나 열어서 읽고 내보낼 수 있는 링크가 만들어집니다. 공유를 중지하면 그 링크도 더 이상 열리지 않습니다.

워크스페이스의 멤버에서는 누가 있는지 보고, 역할(소유자, 관리자, 편집자, 뷰어)을 바꾸고, 초대 링크를 만들 수 있습니다. 아직 이메일 기능이 없으니 링크는 직접 보내세요.

10. 직접 호스팅하기

전체 스택이 AGPL-3.0이고, Node와 Postgres 말고는 필요한 것이 없습니다. 저장소를 클론하고, .env.example을 복사하고, Postgres를 띄우고, 마이그레이션을 적용한 다음 실행하면 됩니다. 정확한 명령어는 README에 있습니다.

모든 설정은 환경 변수로 하며, 웹 앱은 서버 주소를 빌드할 때가 아니라 실행할 때 읽습니다. 그래서 한 번 빌드한 번들이 어느 환경에서나 그대로 돌아갑니다.

아직 없는 것

어차피 마주치게 될 테니 솔직하게 적어 둡니다. 이메일은 한 통도 보내지 않으므로 초대는 직접 전달하는 링크이고, 이메일 주소는 바꿀 수 없습니다. 로그인은 이메일과 비밀번호로만 할 수 있습니다. 앱 안에는 검색창이 없고, 기록에는 모든 변경이 남지만 이전 버전으로 되돌릴 수는 없습니다.

이 중 하나가 걸림돌이라면 GitHub Issues에 알려 주세요. 다음에 무엇을 만들지가 그 의견에 따라 달라집니다.