LLM 협업을 위한 텍스트 기반 개발 워크플로우: Obsidian과 Git 활용법

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

LLM을 활용한 소프트웨어 개발 시 세션 간 맥락 소실과 계획-구현 간의 괴리는 흔히 발생하는 문제이다. 이를 해결하기 위해 Markdown 파일, Obsidian Kanban, Git을 결합한 텍스트 중심의 협업 워크플로우를 활용한다. LLM이 코드를 파악해 research.md를 작성하고 이를 기반으로 plan.md에서 작업을 페이즈 단위로 분할하는 구조를 가진다. 실제 사례에서 이 방식은 LLM이 추가적인 정보 전달 없이도 즉시 작업 맥락을 파악하게 하여 개발 효율을 높였다. 결과적으로 인간과 AI가 동일한 소스를 공유하며 복잡한 프로젝트를 체계적으로 관리할 수 있는 환경을 제공한다.

배경

Git 기본 사용법, Markdown 문법, Obsidian 사용 경험

대상 독자

LLM을 활용해 복잡한 프로젝트를 관리하려는 소프트웨어 개발자

의미 / 영향

텍스트 기반의 단순한 구조는 복잡한 AI 에이전트 도구보다 실무에서 더 강력한 통제력을 제공한다. 특히 컨텍스트 윈도우의 한계를 파일 분할과 구조화된 기록으로 극복하는 실질적인 방법론이 유효함이 확인됐다.

섹션별 상세

LLM과의 협업에서 세션 간 맥락이 소실되는 문제는 개발 생산성을 저해하는 주요 요인이다. 기존 도구들은 인간 중심적이거나 AI가 접근하기 어려운 폐쇄적인 구조를 가진 경우가 많다. 이를 해결하기 위해 인간과 AI가 모두 읽고 쓸 수 있는 Markdown 기반의 공유 워크플로우가 필요하다. Git을 통한 버전 관리는 이 과정에서 변경 이력을 추적하고 장기적인 기억 장치 역할을 수행한다.

근거

LLM은 컨텍스트가 명시적이고 읽기 쉬울 때 가장 잘 작동한다. — Why text files 섹션

research.md 파일은 구현 전 시스템의 실제 상태를 파악하여 잘못된 가정을 방지하는 핵심 도구이다. LLM은 소스 코드, 마이그레이션, 테스트 및 문서를 상세히 파악하여 아키텍처 제약 사항과 엣지 케이스를 기록한다. 모호한 요약 대신 구조화된 발견 사항을 작성함으로써 계획 수립을 위한 견고한 토대를 마련한다. 이 단계는 무엇이 존재한다고 가정하는가가 아닌 실제로 무엇이 존재하는가를 정의하는 과정이다.

plan.md는 연구 결과를 바탕으로 구현 단계를 구체적인 페이즈로 분할하여 관리하는 로드맵이다. 각 페이즈는 독립적으로 검증 가능한 작업 단위로 구성되며, 세부 사항은 별도의 파일로 분리하여 관리한다. 이를 통해 LLM은 전체 프로젝트 대신 현재 작업 중인 특정 페이즈의 파일만 로드하여 컨텍스트 창을 효율적으로 사용할 수 있다. 작업이 진행됨에 따라 체크리스트를 업데이트하여 진행 상황을 명확히 공유한다.

Obsidian Kanban은 텍스트 기반의 파일 구조를 시각적인 대시보드로 변환하여 프로젝트의 전체 상태를 한눈에 파악하게 해준다. 칸반 보드의 각 카드는 실제 Markdown 파일에 대한 링크로 구성되어 있어 보드 업데이트가 곧 파일 업데이트와 직결된다. 메타프로젝트, 계획 중, 진행 중, 완료 등의 컬럼을 통해 작업의 흐름을 관리하며 Git 로그는 프로젝트의 타임라인 역할을 한다. 별도의 복잡한 도구 없이도 텍스트 파일만으로 강력한 프로젝트 관리 환경을 구축할 수 있다.

근거

Git은 채팅 기록이 사라진 후에도 장기 기억 장치 역할을 한다. — Continuity between sessions 섹션

용어 해설

Context Window: — LLM이 한 번에 처리할 수 있는 텍스트 정보의 총량을 의미한다. 긴 대화나 복잡한 코드를 다룰 때 이 한계를 초과하면 이전 정보가 유실되므로, 본문처럼 파일을 분할하여 필요한 맥락만 주입하는 방식이 중요하다. 이는 모델의 추론 정확도와 비용 효율성에 직접적인 영향을 미치는 핵심 요소이다.
Kanban Board: — 작업의 흐름을 시각적으로 관리하는 도구로, 할 일, 진행 중, 완료 등의 상태를 카드로 표시한다. 본문에서는 Obsidian을 통해 Markdown 파일을 카드로 변환하여 인간과 AI가 프로젝트 진행 상황을 직관적으로 공유하는 인터페이스로 활용한다. 복잡한 워크플로우를 단순화하여 병목 구간을 파악하는 데 유용하다.
Version Control: — 파일의 변경 사항을 시간 순서대로 기록하고 관리하는 시스템이다. Git을 사용하여 AI와의 협업 과정에서 발생한 모든 수정 이력을 보존하며, 이는 LLM의 단기 기억 한계를 보완하는 장기 기억 장치 역할을 수행한다. 협업 중 발생한 오류를 추적하고 이전 상태로 안전하게 복구하는 데 필수적이다.

언급된 리소스

GitHubObsidian Kanban