Deciduous: Claude Code를 위한 AI 기반 의사결정 그래프 구축 도구

핵심 요약

소프트웨어 개발 과정에서 과거의 의사결정 맥락을 파악하는 것은 어렵고 시간이 많이 소요되는 작업이다. Deciduous는 Claude Code와 연동하여 Git 커밋 히스토리를 분석하고, 개발자가 내린 결정의 흐름을 '의사결정 그래프'로 자동 생성한다. 이 도구는 단순한 코드 변경을 넘어 목표(Goal), 선택지(Option), 결정(Decision), 결과(Outcome) 등 7가지 노드 타입을 통해 프로젝트의 진화 과정을 체계적으로 기록한다. 이를 통해 개발자는 과거의 피벗(Pivot) 지점을 명확히 이해하고, AI 에이전트에게 프로젝트의 깊은 맥락을 효과적으로 전달할 수 있다.

배경

Git, Claude Code, Rust (Cargo) 또는 Homebrew 설치 환경

대상 독자

Claude Code를 사용하는 개발자 및 프로젝트의 설계 맥락을 체계적으로 관리하고자 하는 소프트웨어 엔지니어

의미 / 영향

AI가 단순히 코드를 생성하는 단계를 넘어 프로젝트의 설계 의도와 역사적 맥락을 관리하는 파트너로 진화하고 있음을 보여준다. 이는 문서화되지 않은 개발자의 암묵적 지식을 정형화된 데이터베이스로 변환하여 소프트웨어의 장기적인 유지보수성을 획기적으로 높일 수 있는 가능성을 제시한다.

섹션별 상세

Git 히스토리 기반의 자동 의사결정 그래프 구축 기능은 /decision-graph 명령어를 통해 실행된다. Claude가 수백 개의 커밋을 읽고 주요 내러티브를 추출하여, 무엇이 구축되었고 무엇이 대체되었는지, 그리고 어디서 전략적 피벗이 발생했는지를 연결된 그래프 형태로 시각화한다. 이 과정은 추측이 아닌 실제 커밋 데이터와 코드에 근거하여 수행되며 모든 작업은 실제 커밋 SHA를 참조한다.

소프트웨어 구축 과정을 정밀하게 묘사하기 위해 7가지 전용 노드 타입을 제공한다. 목표(Goal), 선택지(Option), 결정(Decision), 작업(Action), 결과(Outcome), 관찰(Observation), 재검토(Revisit)로 구성된 어휘 체계는 개발의 논리적 흐름을 구조화한다. 특히 Revisit 노드는 과거의 접근 방식과 새로운 결정을 연결하여 기술적 부채나 설계 변경의 이유를 명확히 기록한다.

deciduous init 명령을 실행하면 Claude Code를 위한 9개의 슬래시 명령어와 3개의 스킬(Skill), 그리고 프로젝트 지침 파일(CLAUDE.md)이 자동으로 생성된다. 이를 통해 Claude는 프로젝트의 의사결정 구조를 학습하고, 개발 세션 시작 시 /recover 명령으로 이전 맥락을 즉시 복구한다. 이는 AI 에이전트가 프로젝트의 설계 원칙을 준수하며 코드를 작성하도록 돕는 핵심 장치이다.

고고학(Archaeology) 뷰는 프로젝트의 역사적 피벗을 추적하는 데 특화되어 있다. 예를 들어 인메모리 캐시에서 Redis로 전환한 과정을 '관찰-재검토-결정'의 체인으로 묶어 관리하며, 기존 접근 방식은 '대체됨(superseded)' 상태로 표시한다. 개발자는 카드 스택 형태의 UI를 통해 과거에 왜 특정 기술적 선택을 포기했는지에 대한 맥락을 키보드 네비게이션으로 빠르게 탐색할 수 있다.

구축된 그래프는 deciduous serve 명령을 통해 로컬 웹 UI에서 시각적으로 탐색 가능하다. DAG(Directed Acyclic Graph), 타임라인, Q&A 인터페이스 등 다양한 뷰를 제공하며, SQLite의 FTS5를 활용한 전문 검색 기능을 통해 과거의 모든 상호작용을 검색할 수 있다. 또한 이벤트 기반의 동기화 기능을 지원하여 팀원 간의 의사결정 이력을 공유하거나 GitHub Pages로 그래프를 배포하는 것이 가능하다.

</> 코드 예제 포함

실무 Takeaway

LLM 에이전트에게 코드뿐만 아니라 '의사결정 맥락'을 그래프 데이터로 제공하여 더 정확한 설계 및 리팩터링 수행을 유도한다.
Git 커밋 메시지에 의사결정 근거를 상세히 기록하는 습관이 Deciduous 그래프의 품질과 AI의 맥락 이해도를 결정하는 핵심 요소가 된다.
복잡한 레거시 프로젝트의 히스토리를 시각화하여 신규 팀원의 온보딩 시간을 단축하고 과거의 잘못된 결정을 반복하지 않도록 방지한다.

언급된 리소스

GitHubDeciduous GitHub Repository