Claude Code를 위한 프로젝트 트래커를 오픈소스로 공개했습니다: .story/ 디렉토리에 티켓, 이슈, 세션 핸드오버를 파일로 저장
I open-sourced a project tracker for Claude Code that lives in .story/ : tickets, issues, and session handovers as files
핵심 요약
Claude Code의 세션 간 맥락 유지 문제를 해결하기 위해 리포지토리 내부에 프로젝트 상태를 파일로 관리하는 오픈소스 도구 'Storybloq' 소개.
- 프로젝트 맥락 유지 — .story/ 디렉토리에 티켓, 이슈, 세션 핸드오버를 JSON과 마크다운으로 저장하여 Claude Code의 기억력 문제 해결.
- 로컬 중심 관리 — 외부 툴 대신 리포지토리 내부에 상태를 저장해 git으로 추적 가능하며, 프로젝트 복제 시에도 맥락이 유지됨.
- 워크플로우 통합 — 세션 시작 시 /story 명령어로 맥락을 로드하고, 종료 시 상태를 자동 저장하여 연속성 확보.
- 오픈소스 도구 — 별도 계정이나 유료 플랜 없이 사용 가능한 오픈소스 프로젝트로, 맥 앱을 통해 실시간 칸반 보드도 제공.
저는 제 Claude Code 워크플로우를 위해 Storybloq(이전 명칭 Claude Story)을 만들었고, Storybloq을 만드는 데 Storybloq 자체를 사용했습니다. 리포지토리의 .story/ 디렉토리는 프로젝트 개발 전반에 걸쳐 모든 티켓, 이슈, 세션 핸드오버를 추적해 왔으므로, 이 도구는 그 자체로 가장 오래 실행된 테스트 케이스입니다. 유용할 것 같아 공유합니다. 무료이며 오픈소스입니다.
문제점: Claude Code는 새로운 세션마다 이전 세션을 잊어버립니다. 그래서 아키텍처를 다시 설명하고, 이미 합의된 트레이드오프를 다시 논의해야 하며, 긴 프로젝트를 진행할수록 코드베이스가 조금씩 어긋나게 됩니다.
Storybloq은 리포지토리에 일반 JSON과 마크다운으로 구성된 .story/ 디렉토리를 제공합니다. 여기에는 티켓, 이슈, 로드맵 단계, 메모, 교훈, 세션 핸드오버가 포함되며, 모두 사람이 수정할 수 있고 git으로 추적됩니다. 세션 시작 시 /story를 입력하면 Claude가 이 모든 것을 불러옵니다. 세션 종료 시 상태가 다시 기록되므로 다음 세션은 이전 세션이 끝난 지점부터 바로 시작할 수 있습니다.
추적 항목:
- 로드맵 단계별로 정리된 티켓
- 세션 도중 발견된 버그에 대한 이슈
- 세션을 거치며 축적되는 메모와 교훈
- 세션 핸드오버(결정 사항, 차단 요소, 다음 단계)
- 현재 상태, 모두 리포지토리 내부에 저장
Claude가 작업함에 따라 업데이트되는 실시간 칸반 보드가 포함된 무료 네이티브 Mac 앱도 있습니다.
설치:
npm install -g @storybloq/storybloq@latest
storybloq setup-skill
이 도구는 팀을 위한 GitHub Issues, Linear, Jira를 대체하려는 것이 아닙니다. 리포지토리 내부에 가벼운 프로젝트 메모를 남기고 싶은 Claude Code 사용 솔로 개발자와 소규모 프로젝트를 위한 것입니다.
공개: 제가 만들었습니다. 무료이고 오픈소스이며, 계정 생성이나 유료 티어, 추천 링크는 없습니다. 데이터는 어떤 편집기에서든 읽을 수 있는 파일 형태로 리포지토리에 남습니다.
Claude Code로 다중 세션 작업을 하시는 분들께 한 가지 궁금한 점이 있습니다. 이 상태를 리포지토리 내부에 파일로 추적하는 것을 선호하시나요, 아니면 외부 도구(Linear, Jira, GitHub Issues)에 보관하고 Claude가 거기서 읽어오게 하는 것을 선호하시나요? 저는 gh repo clone을 해도 데이터가 유지되기 때문에 리포지토리 내부 방식을 선택했지만, 반대 의견도 충분히 이해합니다.
