AI Agent의 기억력을 파일로 보완하기 - Obsidian + ClaudeCode 적용기

 

바이브코딩은 왜 실패하는가 -AI 협업 가이드북

본 게시글은 위 도서에서 소개된 클로드 코드와 옵시디언을 활용한 바이브 코딩 방식을 실제 프로젝트에 적용해 본 경험을 정리한 글입니다.

---

커서AI를 활용해 진행하던 프로젝트가 있었는데, 어느 순간 소스 코드를 확인할 때마다 낯설어지는 경험을 했다.

'use client'가 왜 여기 붙어있지? IndexedDB 캐싱 코드는 사용하는 곳도 없어 보이는데 존재하고, page.tsx 파일 안에는 뭐 이리 많은 로직들이 들어있는 거지 싶었다.

의도한 기능은 당연히 동작했지만, 해당 기능이 어떻게 동작하는지를 설명할 수 없었다.

원인은 단순히도, 기억을 못 했기 때문이다. 분명 커서 AI에서 구현을 맡기면서도 하나하나 확인을 했을 텐데, 나중에 돌아보니 기억을 못 하는 것이다. 매 세션마다 "이 기능 구현해 줘, 저 기능 구현해 줘" 하다 보니 전반적인 큰 그림이 없는 채로 개별 기능만 올라가고 있었던 것이다.

 

 

기억을 파일로 만들자

위키독스에 올라와있는 '바이브코딩은 왜 실패하는가' 라는 책을 읽으면서 방향을 바로잡아보기로 했다. 핵심은 생각보다 단순했다.

AI에게 기억을 기대하지 말고, 기억의 원천을 파일로 만들어서 주입하자

 

기록 > 설계 > 구현 > 기록. 이 루프를 만들고 활용하는게 전부였다.

도구로는 구조화된 문서를 만드는데 적합한 Obsidian과 이를 ClaudeCode를 통해 제어할 수 있게 하는 mcp.

GitHub - iansinnott/obsidian-claude-code-mcp: Connect Claude Code and other AI tools to your Obsidian notes using Model Context

옵시디언 볼트에 프로젝트 관련 문서를 쌓아두고, Claude COde가 세션을 시작할 때 MCP를 통해 그 문서들을 읽어오게 하면, Agent도 나도 매 세션마다 같은 맥락을 가지고 작업에 돌입할 수 있었다.

 

실제로 프로젝트를 진행하며 적용한 옵시디언 볼트의 구조는 대략 다음과 같다.

프로젝트/Melog/
├── 프로젝트-개요.md     ← 기술스택, 디렉토리, 전체 조감
├── 의사결정.md          ← "왜 이렇게 했는가"
├── 체크리스트.md        ← Phase별 할 일
├── 설계/아키텍쳐.md     ← 컴포넌트 구조, 데이터 흐름
├── 기능/               ← 기능/버그별 개별 문서
├── 에러로그/
└── 세션로그/            ← 세션별 작업 기록

 

1. 프로젝트-개요.md

이 프로젝트가 어떤 프로젝트인지에 대한 한 장의 요약이다. Rust + Axum 백엔드, Next.js 프론트엔드에 OCI를 통한 배포 등등 기타 기술스택과 디렉토리 구조까지 포함해 세션을 시작할 때 AI에게 건네줄 간단한 컨텍스트이다.

 

2. 의사결정.md

기능을 구현하거나 수정할 때, 많은 의사결정이 수반된다. 가령 동일한 기능이라고 하더라도 구현하는 방법은 다양한데, 이럴 때 왜 그런 방식을 선택했는지에 대한 내용을 담는 문서이다. 이 의사결정 문서는 추후에 비슷한 문제에 봉착했을 때, 기존에 결정된 방향에 따라 작업을 할 수 있도록 해주는 지침이 된다.

 

3. 체크리스트.md

Phase 단위로 할 일을 관리하도록 하는 파일이다. SEO 적용, Dead Code 제거, 캐싱 등 하나의 큰 단위를 Phase로 나누고 체크리스트로 관리하면, 어떤 작업을 해야 할지, 또 어디까지 작업을 진행했는지 한 눈에 이해할 수 있게 된다.

 

4. 세션로그.md

세션로그는 하나의 세션에서 작업을 진행하다가 잠시 멈추게 되는 경우가 발생했을 때 작성하도록 했다. [이번 세션에서 진행한 일 / 발생한 문제 / 해결한 방법 / 다음 세션에서 할 일] 등등 해당 세션에서의 작업 내용 요약과 추후 진행해야 할 일들을 요약 정리하도록 했다. 그래서 일시중단된 작업을 추후에 재개할 때, 해당 세션로그 파일을 읽게 함으로써 컨텍스트를 어느 정도 유지할 수 있도록 하는 역할을 한다.

 

 

매끄럽게 이어지게 하자

위와 같은 옵시디언 볼트 구조를 갖춘 이후에는 Claude code에게 시의적절하게 파일들을 읽게 하여 컨텍스트를 주입해야 한다. 

세션을 시작하면 Claude Code가 mcp를 통해 옵시디언 볼트에서 관련 문서를 읽게 한다. 프로젝트-개요.md 파일로 전반적인 아키텍쳐를 이해하고, 체크리스트.md 파일을 통해 어떤 Phase가 진행 중인지 파악한다. 그리고 가장 최근에 작성된 세션로그.md 파일을 읽혀 어디까지 진행했는지를 파악하게 한다.

 

3월 21일에 작성했던 세션 로그는 다음과 같다. 오전 세션에서 렌더링 구조를 분석해서 관련된 문제를 도출했고, 점심 이후 세션에서 기존의 렌더링 구조 개선을 위해 서버 컴포넌트 적용 전략을 확정 지었다. 오후 세션에서는 해당 전략을 바탕으로 구현을 완료했다. 하나의 구현을 위해 세 번의 세션을 거쳤지만 맥락이 끊기지 않고 이어졌다. 이전 세션에서의 세션 로그가 다음 세션의 시작점이 됐기 때문이다.

# 세션 로그 — 2026-03-21 14:08
## 다음 세션에서 할 일
- Phase 7 나머지 항목 순서대로 진행
  1. /ranking/[type] — RSC + Pagination CSR 분리
  2. /streamer — RSC(데이터) + CSR(인터랙션) 혼합
  ...

 

 

이미 진행하던 프로젝트라면 - 리버스 엔지니어링

위 방식을 적용해 관리하던 프로젝트는 이미 예전부터 진행하던 프로젝트였다. 소스코드는 존재하는데 관련된 명세, 문서들이 부족한 상황이었다.

그래서 소스코드를 Claude Code에게 넘긴 후, 역방향으로 문서를 뽑아내는 방식을 사용했다. 기존에 작성된 소스코드를 분석한 후 아키텍쳐 문서를 작성해 줘, 기존에 작성된 소스에서의 잠재적인 문제점들을 분석해줘 와 같은 방식을 통해 기존에 구현된 기능에 대한 명세를 뽑고, 그 명세를 토대로 보완할 점들을 추출해 낼 수 있었다.

---

이와 같은 방식을 개인 프로젝트에서부터 회사에서도 사용하고 있다. 다만 아직 완전히 자리 잡은 건 아닌 것 같다. 볼트 구조도 쓰다 보면 조금씩 바뀌고 있고, 세션로그를 작성하지 않고 그냥 넘어가는 날도 있다. 그래도 이전보다는 코드를 열 때 낯설다는 느낌은 많이 줄었다.