Obsidian으로 프로젝트를 구조적으로 관리하기

왜 Obsidian인가

프로젝트를 진행하다 보면 머릿속에만 있는 것들이 너무 많다는 생각이 들 때가 있습니다. ERD, 플로우차트, 백로그, 일정... 이런 것들이 흩어져 있으면 프로젝트의 전체 그림을 보기 어렵습니다. 그래서 모든 것을 한 곳에서 관리할 수 있는 도구가 필요했고, Obsidian을 선택하게 되었습니다.

Obsidian은 마크다운 기반의 노트 앱이지만, 단순한 메모 도구를 넘어서 제2의 뇌 역할을 할 수 있습니다. 특히 프로젝트 문서화와 구조적 사고에 유용하다는 것을 알게 되었습니다.

활용 예정인 기능들

1. ERD와 다이어그램

Obsidian은 Mermaid를 기본 지원합니다. 별도 플러그인 없이 코드 블록만으로 ERD를 그릴 수 있습니다.

erDiagram
    USER ||--o{ POST : writes
    POST ||--o{ COMMENT : has
    USER ||--o{ COMMENT : writes

데이터베이스 설계를 문서와 함께 관리할 수 있다는 점이 좋습니다. 스키마가 변경되면 같은 파일에서 ERD도 함께 수정하면 되니까요.

2. 플로우차트와 시퀀스 다이어그램

복잡한 비즈니스 로직이나 API 흐름을 시각화할 때도 Mermaid가 유용합니다.

sequenceDiagram
    Client->>API: 요청
    API->>DB: 쿼리
    DB-->>API: 결과
    API-->>Client: 응답

코드로 다이어그램을 그리면 버전 관리가 됩니다. 드래그 앤 드롭으로 그린 다이어그램은 수정 이력을 추적하기 어렵지만, 텍스트 기반이면 Git으로 변경 사항을 관리할 수 있습니다.

3. 명세 문서 작성

기능 명세를 작성할 때 Obsidian의 양방향 링크가 빛을 발합니다. 관련된 문서들을 [[링크]]로 연결하면, 어떤 기능이 어떤 API와 연결되고, 어떤 테이블을 사용하는지 한눈에 파악할 수 있습니다.

예를 들어, "회원가입 기능" 문서에서 "User 테이블 ERD"와 "인증 API 명세"를 링크하면, 나중에 그래프 뷰에서 전체 연결 관계를 시각적으로 확인할 수 있습니다.

4. 백로그와 일정 관리

칸반 보드 플러그인을 활용하면 백로그를 시각적으로 관리할 수 있습니다. 하지만 저는 단순한 체크리스트 방식을 선호합니다.

## 이번 주 할 일
- [x] ERD 초안 작성
- [ ] API 명세 문서화
- [ ] 플로우차트 정리

복잡한 도구보다는 단순한 형식이 오래 유지됩니다. 화려한 프로젝트 관리 도구를 쓰다가 결국 방치하는 경험을 여러 번 했기 때문입니다.

시스템을 구조적으로 분해하기

가장 기대되는 부분은 시스템을 구조적으로 분해하는 것입니다. 큰 프로젝트를 작은 단위로 쪼개고, 각 단위 사이의 관계를 명확히 하면 작업 효율이 올라갑니다.

예를 들어, 블로그 시스템을 만든다면:

블로그 시스템
├── 인증 모듈
│   ├── 회원가입
│   ├── 로그인
│   └── JWT 관리
├── 글 관리 모듈
│   ├── 글 CRUD
│   ├── 이미지 업로드
│   └── SEO 메타데이터
└── AI 분석 모듈
    ├── 제목 개선
    └── 메타 설명 생성

이렇게 트리 구조로 정리하면, 각 모듈을 독립적으로 개발하고 테스트할 수 있습니다. 또한 의존성이 명확해지니 병렬 작업도 가능해집니다.

Claude Code와의 연동

최근에 Obsidian과 Claude Code를 MCP(Model Context Protocol)로 연동했습니다. 이제 Claude Code에서 Obsidian 노트를 읽고 쓸 수 있습니다.

이 연동이 가져올 변화가 기대됩니다:

• 코딩 중에 명세를 바로 참조할 수 있습니다
• 작업 내용을 자동으로 문서화할 수 있습니다
• 프로젝트 컨텍스트를 AI와 공유할 수 있습니다

결국 문서화의 핵심은 접근성이라는 생각이 듭니다. 아무리 좋은 문서도 찾기 어려우면 쓰이지 않습니다. 작업 환경에서 바로 접근할 수 있어야 문서화가 습관이 됩니다.

앞으로의 계획

당장 완벽한 시스템을 만들려고 하지는 않으려 합니다. 일단 시작하고, 불편한 점이 생기면 그때 개선하는 방식이 저에게는 맞는 것 같습니다.

첫 번째 목표는 현재 진행 중인 프로젝트의 구조를 Obsidian에 옮기는 것입니다. ERD, 모듈 구조, 주요 플로우를 문서화하고, 이것들을 서로 연결해서 프로젝트의 조감도를 만들어볼 생각입니다.

잘 정리된 문서는 미래의 나에게 주는 선물이라는 말이 있습니다. 지금 조금 수고하면 나중에 "이게 왜 이렇게 되어 있지?"라는 질문에 답할 수 있을 테니까요.