Second Brain OS: Claude Code로 스스로 정리되는 지식 베이스 만들기

누구에게 적합한가

• Claude Code로 스스로 정리되는 지식 베이스를 만들고 싶은 사람에게 적합합니다. 평소 글이나 노트를 수집하면서, 파일 더미로 방치되지 않고 자동으로 추출·양방향 링크(wikilink) 생성·정돈이 되길 원하는 분을 위한 것입니다.
• 완전한 가이드, 초기 vault, agent skills, 스크립트를 제공하며, markdown 파일·wikilink·SKILL.md 중심으로 동작합니다. 파일을 읽을 수 있는 모든 agent에도 사용할 수 있습니다. Obsidian은 그래프 뷰어일 뿐, 필수 의존성이 아닙니다.
• 적합하지 않은 경우: 터미널에서 저장소를 clone하고 디렉터리를 복사하고 agent를 실행하는 과정 없이, 설치만 하면 바로 쓸 수 있는 GUI 노트 소프트웨어를 원한다면 이 워크플로는 맞지 않습니다. 공식 근거는 특정 agent 외에 어떤 클라이언트를 지원하는지, 어떤 텍스트 언어를 지원하는지, 유료 여부나 계정 요구 사항 외에 어떤 제한이 있는지 설명하지 않습니다 — 무료이며 가입이 필요 없지만, 그 외의 경계는 알 수 없습니다.

3분 만에 첫 시도 완료하기

공식 메인 경로는 터미널에서 로컬 ~/brain에 설치한 뒤, 그 디렉터리에서 Claude Code를 실행하는 것입니다:

1. 사전 준비: git과 Claude Code(agent)가 설치되어 있어야 하며, 그래프를 보려면 Obsidian도 함께 설치하는 것이 좋습니다.
2. 터미널에서 공식 설치 명령을 실행해 초기 vault와 skills, commands, agents를 ~/brain/.claude에 함께 복사합니다:

git clone https://github.com/undefined-ui/second-brain-os.git
cp -r second-brain-os/vault-template ~/brain

mkdir -p ~/brain/.claude
cp -r second-brain-os/skills   ~/brain/.claude/skills
cp -r second-brain-os/commands ~/brain/.claude/commands
cp -r second-brain-os/agents   ~/brain/.claude/agents

cd ~/brain && claude

1. 부작용과 확인 지점: 위 명령은 사용자 디렉터리에 ~/brain을 생성하고 파일을 기록합니다. 대상이 이미 존재한다면 덮어쓸지 먼저 직접 확인하세요.
2. 저위험 첫 작업 트리거하기: 글 한 편을 raw/ 디렉터리 아래 파일로 저장/붙여넣은 뒤, Claude Code에서 /ingest를 입력합니다. 이것이 공식 핵심 워크플로입니다. agent가 원본 자료를 수집·추출·링크 생성·정리하여 상호 연결된 wiki로 만듭니다. vault 내부의 markdown 파일을 읽고 쓰며, 명령 실행이나 네트워크 접근 여부는 공식 근거가 없으므로 미지로 다룹니다. 글에 민감한 내용이 있다면 먼저 마스킹한 후 raw/에 넣으세요.
3. 성공 신호: raw/의 글이 vault 안에서 wikilink가 달린 노트 페이지로 정리되는 것입니다. 공식 규칙은 "Nothing is ingested until it is linked" — 같은 라운드에서 링크가 완성되지 않으면 수집이 끝난 것이 아닙니다. 따라서 새 페이지에 다른 노트를 가리키는 링크가 실제로 나타났는지 확인하는 것이 해당 /ingest 라운드 종료 여부의 판단 기준입니다. /ingest 내부에 어떤 검사 pass가 있는지, 텍스트 유형별로 다른 절차가 있는지는 공식 근거가 없으며, 추정해서는 안 됩니다.

사용 사례

사례 1: 글 수집 후 입고. 평소 브라우저로 글을 클리핑만 하고 다시 보지 않는 경우. 시나리오: 글 한 편을 ~/brain/raw/에 클리핑으로 저장하고, Claude Code에서 /ingest를 실행합니다. agent는 공식 ingest 워크플로를 따라 핵심 내용을 추출하고, 기존 노트에 링크를 걸고, 정리합니다. 기대 결과: raw 파일이 링크로 연결된 wiki 페이지로 변환됩니다. 새 페이지에 링크가 부족하다면 공식 규칙상 해당 라운드의 수집은 미완료이며, agent에게 링크를 보완하도록 요청할 수 있습니다.

사례 2: Obsidian으로 지식 그래프 보기. 시나리오: ingest를 몇 번 마친 뒤 노트 간 연결을 확인하고 싶은 경우. 방법: Obsidian으로 ~/brain vault를 열고(공식 안내에서 Obsidian은 그래프 뷰어입니다), 노트와 wikilink가 이루는 그래프를 탐색합니다. 확인 가능한 부분: vault는 순수 markdown과 wikilink이므로 Obsidian에서 바로 열어 그래프를 표시할 수 있습니다. 그 이상의 자동 연동이나 동기화 동작은 공식적으로 설명되지 않으므로, 뷰어 이상의 통합은 기대하지 마세요.

사용 경계

• 파일 접근: 설치와 실행은 로컬의 markdown 파일을 생성·수정합니다(~/brain, raw/, .claude 디렉터리). 이는 선택적 부작용이 아니라 워크플로의 핵심입니다.
• 명령과 네트워크: 공식 근거는 위의 shell 설치 명령만 제공합니다. agent가 ingest 중에 다른 명령을 실행하거나 네트워크에 접근하는지는 근거가 없는 미지 사항입니다.
• 확인 지점: 민감한 자료를 raw/에 넣기 전에 직접 검토하세요. 기존 ~/brain을 덮어쓰기 전에 직접 확인하세요.
• 실행 환경: 로컬 터미널, git, 파일을 읽을 수 있는 agent(공식 메인 경로는 Claude Code)가 필요합니다. 그래프 뷰를 보려면 Obsidian이 필요하지만 의존성은 아닙니다. 그 외의 실행 제한은 공식적으로 나열되어 있지 않습니다.
• 미확인 핵심 정보: 지원 agent 목록이 Claude Code뿐인지(공식은 works with Claude Code and any agent that reads files라고만 표현), 지원 텍스트 언어, /ingest 외에 어떤 명령을 쓸 수 있는지 모두 근거가 없습니다. 사용 전에 skills, commands 디렉터리의 실제 파일을 직접 확인할 수 있습니다.