storybloq

문제

AI 코딩 어시스턴트는 상태가 없습니다. 모든 새 세션은 제로에서 시작합니다. 모델은 어제 만든 것이 무엇인지, 무엇이 고장 났는지, 어떤 결정이 내려졌는지, 다음에 무엇을 작업해야 하는지 알지 못합니다. 개발자들은 CLAUDE.md 파일과 흩어진 노트로 이를 보완하지만, 표준 구조도, 세션 연속성도, 도구도 없습니다.

실제 비용은 낭비된 설정 시간이 아닙니다. 반복되는 실수, 다시 쟁론되는 설계 결정, 환각된 컨텍스트, 그리고 복리가 아니라 선형으로만 쌓이는 작업이 바로 그 비용입니다.

Related MCP server: AI Conversation Logger

아이디어

모든 프로젝트는 JSON과 마크다운 파일로 이루어진 .story/ 디렉토리를 갖습니다. 티켓, 이슈, 로드맵 단계, 세션 핸드오버, 그리고 배운 교훈이 모두 이곳에 저장되며, git으로 추적되고 어떤 AI든 읽을 수 있습니다.

• CLI: storybloq - 터미널에서 .story/를 확인하고 변경합니다.

• MCP server: Claude Code와 Codex가 직접 호출할 수 있는 구조화된 도구이며, 로컬 Bus가 활성화되면 추가 도구 5개가 함께 제공됩니다. 서브프로세스를 생성하지 않습니다.

• Skill: Claude Code에서는 /story를, Codex에서는 $story를 사용하면 세션 시작 시 프로젝트 상태가 로드됩니다.

• Mac 앱: .story/를 주시하다가 AI 클라이언트가 작업하는 동안 실시간으로 갱신되는 네이티브 사이드바입니다(별도 제품이며, App Store에서 무료).

설치

npm install -g @storybloq/storybloq@latest
storybloq setup --client all

Node.js 20+ 및 최소 하나의 AI 클라이언트(Claude Code 또는 Codex CLI 0.130.0+)가 필요합니다. 패키지는 npm의 @storybloq/storybloq에 있으며, 릴리리스는 이 저장소 github.com/Storybloq/storybloq/releases에 태그됩니다.

setup --client all은 Claude와 Codex용 Storybloq 스킬을 설치하고, 이 패키지를 MCP 서버로 등록하며, 사용 가능한 클라이언트 훅을 구성합니다. 다시 실행해도 안전합니다. Codex는 설치된 훅을 신뢰등급 unknown으로 보고합니다. Codex에서 /hooks를 열어 확인한 뒤 신뢰하세요. setup-skill은 Claude 전용 설정을 위한 호환 별칭으로 남아 있습니다.

업그레이드

npm install -g @storybloq/storybloq@latest
storybloq setup --client all

새로 설치할 때와 동일한 두 명령이면 됩니다. @latest가 최신 버전을 받아오고, 셋업를 다시 실행하면 Storybloq 스킬 파일이 새로고침되고, MCP 서버가 다시 등록되며, 이전 설치에서 남은 오래된 훅 항목도 정리됩니다.

새 버전이 npm에 올라왔을 때는 다음번 storybloq 실행 시 보통 한 줄 배너가 표시됩니다.

storybloq v1.2.0 is available (you have v1.1.6).
Update: npm install -g @storybloq/storybloq@latest

CLI는 업그레이드 후 첫 실행 시 스킬 디렉토리를 자동으로 새로고침하고, 레거시 훅 항목(예: 이름 변경 전의 @anthropologies/claudestory 패키지)을 마이그레이션합니다 — 수동 정리는 필요하지 않습니다.

Claude Code 플러그인 시스템을 통한 대체 설치는 Storybloq/plugin-archive를 참고하세요(레거시 경로이며, storybloq setup --client all이 권장 설치 방법입니다).

프로젝트 부트스트랩

cd your-project
storybloq init --name "your-project"

다중 저장소 프로젝트는 아래의 Federation을 참고하세요.

다음 구조를 생성합니다.

.story/
├── config.json         project config + recipe overrides
├── roadmap.json        phase ordering + metadata
├── tickets/            T-001.json, T-002.json, ...
├── issues/             ISS-001.json, ISS-002.json, ...
├── notes/              N-001.json, N-002.json, ...
├── lessons/            L-001.json, ...
├── handovers/          YYYY-MM-DD-<slug>.md
└── snapshots/          state snapshots (gitignored)

.story/snapshots/을 제외한 모든 것을 커밋하세요.

일상적인 사용

Claude Code 또는 Codex에서:

• /story in Claude Code 또는 Codex에서 $story — 프로젝트 상태를 로드하고, 최신 핸드오버를 읽으며, 열려 있는 티켓과 이슈를 보여주고, 막혀 있는 작업을 나열하고, 최근 변경 사항을 요약합니다. 클라이언트가 백그라운드 에이전트를 실행할 수 있고 처리 가능한 백로그가 크면, 오케스트레이션 작업 방식을 사전에 표시하기도 합니다(추천이며 명시적 옵트인으로만 작동합니다).

• /story auto T-001 T-002 ISS-013 / $story auto T-001 T-002 ISS-013 — 해당 항목으로 범위를 한정한 자동 모드입니다. 티켓을 계획 -> 계획 검토 -> 구현 -> 테스트 -> 코드 리뷰 -> 커밋 순서로 진행하며 각 체크포인트에서 핸드오버를 남깁니다.

• /story review T-001 / $story review T-001 — 티켓의 diff에 대해 멀티 렌즈 리뷰를 실행합니다(Storybloq/lenses 참조).

• /story orchestrate / $story orchestrate — 클라이언트가 정확한 호출 가능한 워크플로우/서브에이전트 도구를 노출할 때 다중 리포(또는 대형 단일 리포) 백로그를 구동합니다. Codex는 multi_agent_v1.spawn_agent, 이와 정규화된 multi_agent_v1__spawn_agent 식별자, 또는 정확히 일치하는 spawn_agent 도구를 사용합니다. Claude Agent View 기반 storybloq dispatch 명령은 제공되지만, 제품으로 관리되는 Codex 디스패치 백엔드는 아직 없습니다.

• /story triage / $story triage — 열려 있는 이슈 백로그를 읽기 전용으로 트리거합니다: 고정된 현재 HEAD를 기준으로 각 발견 사항을 검증하고, 이미 수정되었거나 중복된 이슈를 표시하며, 하나의 검증된 근본 원인을 공유하는 이슈를 그룹화하고, 우선순위가 매겨진 티켓 플랜을 권장합니다. 어떠한 이슈나 티켓도 변경하지 않습니다.

• /story bus / $story bus — 작업에 바인딩된 로컬 Bus 끝점을 폴링하여 구현자와 독립적인 리뷰어가 복사 붙여넣기 없이 조언 결과를 주고받을 수 있게 합니다.

• /story handover / $story handover — 결정 시항, 블로커, 다음 단계를 담은 세션 핸드오버를 기록합니다.

두 클라이언트 모두 컨텍스트 로딩, 자동 모드, MCP, 그리고 컴팩션/ 상태 훅을 지원합니다. Codex Desktop은 자동 세션의 소유 작업을 열고 그 작업에 정확한 소유자 응답을 전달할 수 있으며, Codex CLI는 수동 작업 전환으로 안전하게 대체합니다. 자동 코드 리뷰는 기본적으로 12라운드 landing 상한을 적용합니다(티켓 위험도에 따라 위쪽으로 조정됩니다). 해결되지 않은 심각한 발견 사항과 거부는 여전히 블록되지만, 비차단 발견은 상한값에서 후속 이슈로 전환됩니다. recipeOverrides.stages.CODE_REVIEW.maxReviewRounds을 0으로 설정하면 이 상한을 명시적으로 비활성화할 수 있습니다.

recipeOverrides.compactThreshold는 medium, high(기본값), critical을 받습니다. 이 값이 압박 상한과 회전 조건을 모두 결정합니다. medium은 더 낮은 상한을 사용하고 중간 압박에서 회전하며, critical은 더 높은 상한과 함께 임계 압박을 기다립니다. 완결된 COMPLETE 경계에서는 Storybloq가 클라이언트의 컴팩션 명령을 호출할 수 없기 때문에, 상한 압박이 HANDOVER로 이어져 유계 세션이 끝납니다. 클라이언트 자신이 컴팩트하면, PreCompact 및 SessionStart 훅이 동일한 세션을 유지하지만 압력 수준은 SessionStart가 source: compact를 확인한 이후에만 리셋됩니다.

AI 클라이언트 밖에서도 이 동일한 상태는 단 한 번의 storybloq 호출로 접근할 수 있습니다.

사용량 한도 자동 재개

Claude Code 세션은 사용량 한도("You've hit your usage limit")에서 멈추고, 밤새 자동으로 진행되는 작업은 그와 함께 조용히 사라집니다. Storybloq는 Claude Code의 StopFailure 훅을 통한 감지를 하고, 세션 내용에서 재시작 시간을 파싱하며, 전역 원장(~/.claude/storybloq/limit-ledger.json)에 기록하고, 한도가 리셋되면 세션을 재개합니다. 훅이 설치되면 기본으로 활성화됩니다.

• 자동 세션은 컴팩션과 동일한 복구 레인에 놓고 됐다가, 전체 상태 머신으로 헤드리스하게 다시 시작됩니다. 권한 다시 묶기, git-HEAD 검증, 복구 매핑이 모두 적용되므로, 작업 공간이 변경된 뒤의 재개는 맹목적으로 재생되는 되지 않고 검증됩니다. FINALIZE 중간에 멈춘 세션은 절대 자동 재개되지 않습니다(커밋 재실행의 안전이 증명되지 않았습니다). 대신 수동 복구 표시 알림을 받습니다.

• 일반 세션은 리셋 시 데스크톱 알림과 함께 정확한 claude --exec 명령을 받습니다. 프로젝트별 옵트인(limitResume.plainMode: "headless")을 사용하면 그 대신 헤드리스로 시작됩니다.

• 권한 범위는 절대로 확장되지 않습니다. --dangerously-skip-permissions로 실행된 세션은 프로젝트가 명시적으로 옵트인(limitResume.inheritBypass: true)해야만 그 플래그를 유지한 채 재개되며, 그렇지 않으면 알림만 보냅니다.

재개는 데몬이 아닌 임시 분리형 웨이커 프로세스가 처리합니다. 이 프로세스는 30초마다 원장을 폴링하고, 실행이 필요한 항목을 재개(정리 상한을 두고, 시차를 두고, 동시성 수를 제한)하며, 대기 중인 항목이 없으면 종료됩니다. 노트북 절전에는 견디지만 재부팅이나 로그아웃에는 생존하지 못합니다. 재부팅 후에는 어떤 프로젝트에서든 다음 storybloq 호출이나 훅 발생이 프로세스를 다시 산성화하므로, 주 단위의 대기 시간도 다음 활동에서 회수됩니다. 이 트레이드오프가 "데몬 없음"의 비용입니다.

storybloq limit-status로 대기열을 확인하고 관리할 수 있습니다 (--cancel <key>는 대기 중인 자동 재개을 취소하고, --requeue <key>는 더은 레코드를 재시도합니다). ~/.claude/storybloq/config.json의 {"limitResume": {"enabled": false}}로 전체 비활성화하거나, .story/config.json의 limitResume으로 프로젝트별로 설정할 수 있습니다 (maxAttempts, staggerMs, maxConcurrent, notify 등도 지원).

선행 연구: 이 탐지 및 재파싱 방식은 unsnooze(MIT)를 모델로 하였으며, unsnooze는 tmux 호스팅 세션에서 트랜스크립트 언어의 한도 감지 및 리셋 시간 파싱을 개척했습니다. Storybloq 버전은 tmux 계층 대신 문서화된 훅 표면을 사용하며, 키 입력 대신 자체 상태 머신으로 자동 세션을 재개합니다.

Storybloq Bus

Storybloq Bus는 하나의 구현자 작업과 하나의 리뷰어 작업을 위한 선택적 로컬 조정 프로토콜입니다. 실행 상태는 gitignore로 무시되는 .story/bus/에 있으며, 확인된 발견 사항은 이슈 알림으로 보내기 전에 지속 가능한 소스 출처와 함께 정식 Storybloq 이슈가 됩니다.

storybloq bus init
storybloq bus join implementer --client codex
storybloq bus join reviewer --client claude
storybloq bus hooks enable --client codex
storybloq bus hooks enable --client claude

Bus 런타임은 로컬이며 gitignore 처리되므로, 참여할 각 체크아웃에서 한 번씩 storybloq bus init을 실행하세요. status와 doctor는 새 체크아웃을 "활성화되었지만 초기화되지 않음"으로 보고합니다. 이 정상 상태에서는 커밋이나 자동 FINALIZE를 차단하하지 않습니다. 나머지 Bus 명령과 MCP 도구는 암시적으로 런타임을 초기화하지 않습니다. 초기화는 심벌릭 링크된 ignore 파일과 부정 패턴을 거부하는데, 그렇지 않으면 git이 전체 런타임을 제외한다는 것을 안전하게 보증할 수 없기 때문입니다.

포그라운드 프로토콜에는 send, poll, acknowledge, thread state, status, doctor, export 및 ship 검사가 포함됩니다. 메시지는 해시 체인된, 아이덴포턴트, 바운드, 작업 단위, 비밀 스크린을 거치며, 크래시 회복 가능한 받는 사서함으로 전달됩니다. 중요한 메시지에는 기본적으로 일치하는 해결되지 않은 심각한 이슈가 요구됩니다. Bus 텍스트는 항상 스타와 같은 조언입니다. 주인 승인을 부여하거나, merge, push, signing, deployment, credentials, spending, destructive actions을 허용하지 않습니다.

V1은 데몬, 프로세스 생성, 헤드리스 재개, 또는 자동 오프라인 웨이크를 Bus 전달 통로로 포함하지 않습니다. 자연적인 SessionStart/Stop 훅과 명시적 폴링이 전달 경로입니다. Codex Desktop는 여전히 깨워지지 않습니다. (위의 사용량 한도 자동 재개는 Bus 외부의 별도 예외입니다. 이 임시 웨이커는 한도에 멈춘 세션만 복구하며 메시지 전달 경로가 아닙니다.)

Federation

페더레이션은 여러 저장소에 걸쳐 AI 에이전트 작업을 조정합니다. 하나의 프로젝트가 오케스트레이터가 됩니다. 시스템의 일부인 저장소(노드), 노드 간의 의존 관계, 런타임 시 통신 방식을 선언합니다. 각 노드는 자체 티켓, 이슈, 핸드오버를 담은 자체 .story/를 유지합니다. 오케스트레이터는 모든 노드를 걸쳐 읽습니다.

# Create an orchestrator
storybloq init --type orchestrator --name "my-platform"

# Register nodes
storybloq node add api --path ../api --stack typescript --role "REST backend"
storybloq node add web --path ../web --stack nextjs --depends-on api
storybloq node add sdk --path ../sdk --stack typescript

노드를 연결하는 세 가지 관계 유형이 있습니다:

• dependsOn 노드 구성: 빌드 순서 엣지. 웹 앱은 API에 의존합니다.

• links 노드 구성: 런타임 통합. 웹 앱은 HTTP를 통해 API를 호출합니다.

• crossNodeBlockedBy 티켓: 한 저장소의 티켓은 다른 저장소의 티켓이 완료될 때까지 차단됩니다. 예: "crossNodeBlockedBy": ["api:T-012"].

오케스트레이터 디렉터리에서:

storybloq status              # aggregated view across all nodes
storybloq recommend           # federation-aware suggestions (bottlenecks, stale nodes, blockers)
storybloq ticket list --node api   # list tickets in the api node without cd-ing

추천 엔진은 페더레이션 특화 제안을 생성합니다: 다운스트림 작업을 차단하는 노드, 다른 많은 노드가 의존하는 병목 노드, 2주 동안 핸드오버가 없는 노드. crossNodeBlockedBy 참조가 있는 티켓은 차단 티켓이 완료될 때까지 추천에 표시되지 않습니다.

CLI 참조

모든 명령은 --format json|md(기본값 md)를 허용합니다. 스크립팅을 위해 JSON을 jq로 파이프하고, 마크다운 변형은 직접 읽습니다.

프로젝트

단계

티켓

이슈

메모 및 교훈

핸드오버, 차단기, 스냅샷

Storybloq Bus(옵트인)

페더레이션(오케스트레이터 프로젝트)

팀 (team-mode 프로젝트)

이 명령어들이 작동하는 병합 모델은 팀 모드를 참조하세요.

MCP 서버 참조

Claude Code 또는 Codex에 등록 (setup이 자동 수행):

claude mcp add storybloq -s user -- storybloq --mcp
codex mcp add storybloq --env STORYBLOQ_CLIENT=codex -- storybloq --mcp

서버는 CLI와 동일한 TypeScript 모듈을 직접 임포트하므로 서브프로세스 오버헤드가 없습니다. 작업 디렉터리에서 위로 올라가 가장 가까운 .story/ 상위 디렉터리를 찾아 프로젝트 루트를 자동으로 탐지합니다.

기본 도구는 책임별로 그룹화됩니다. Bus가 활성화된 프로젝트는 MCP 프로세스 시작 시 추가 도구 5개를 등록합니다. storybloq bus init 후 연결된 클라이언트를 재시작하세요.

읽기 (부작용 없음)

storybloq_status · storybloq_phase_list · storybloq_phase_current · storybloq_phase_tickets · storybloq_ticket_list · storybloq_ticket_get · storybloq_ticket_meta_get · storybloq_ticket_next · storybloq_ticket_blocked · storybloq_issue_list · storybloq_issue_get · storybloq_issue_meta_get · storybloq_note_list · storybloq_note_get · storybloq_lesson_list · storybloq_lesson_get · storybloq_lesson_digest · storybloq_handover_list · storybloq_handover_latest · storybloq_handover_get · storybloq_blocker_list · storybloq_validate · storybloq_recap · storybloq_recommend · storybloq_export · storybloq_selftest

쓰기 (.story/ 변경)

storybloq_snapshot · storybloq_handover_create · storybloq_ticket_create · storybloq_ticket_update · storybloq_ticket_meta_set · storybloq_ticket_meta_unset · storybloq_issue_create · storybloq_issue_update · storybloq_issue_meta_set · storybloq_issue_meta_unset · storybloq_note_create · storybloq_note_update · storybloq_lesson_create · storybloq_lesson_update · storybloq_lesson_reinforce · storybloq_phase_create

자율 모드 + 리뷰 + 관찰 가능성

storybloq_autonomous_guide는 자율 상태 머신(PICK_TICKET -> PLAN -> PLAN_REVIEW -> WRITE_TESTS -> IMPLEMENT -> TEST -> CODE_REVIEW -> FINALIZE -> COMPLETE)을 구동합니다.

storybloq_review_lenses_prepare · storybloq_review_lenses_judge · storybloq_review_lenses_synthesize는 다중 렌즈 리뷰 루프를 오케스트레이션합니다 (@storybloq/lenses 필요).

storybloq_session_report · storybloq_register_subprocess · storybloq_unregister_subprocess는 세션 상태를 Mac 앱에 표시합니다.

Storybloq Bus (기능 게이트)

storybloq_bus_send · storybloq_bus_poll · storybloq_bus_ack · storybloq_bus_thread_get · storybloq_bus_thread_update

모든 호출에는 안정적인 엔드포인트 ID와 현재 검증된 클라이언트 작업 ID가 필요합니다. Poll 및 thread 출력은 피어 콘텐츠를 권고 권한으로 표시합니다. storybloq_bus_poll과 storybloq_bus_thread_get은 표준 추적 프로젝트 상태에 대해 읽기 전용입니다. poll은 gitignore된 .story/bus/ 런타임 메타데이터를 조정할 수 있습니다. 나머지 3개는 일반 MCP 쓰기 승인을 유지합니다.

페더레이션 (오케스트레이터 프로젝트)

storybloq_node_init는 오케스트레이터 컨텍스트에서 노드 저장소의 .story/를 부트스트랩합니다.

storybloq_node_add · storybloq_node_list · storybloq_node_update는 오케스트레이터의 노드 레지스트리를 관리합니다.

훅

PreCompact (압축 준비, setup이 설정)

클라이언트가 PreCompact 훅을 지원하는 경우 컨텍스트 압축 전에 storybloq session compact-prepare를 실행하여 스냅샷과 재개 브레드크럼이 최신 상태로 유지되도록 합니다. Codex setup은 manual|auto 매처와 함께 storybloq session compact-prepare --client codex를 사용하여 Codex 훅이 Claude 소유 세션을 압축할 수 없도록 합니다. Claude Code setup은 매처를 비워 둡니다.

{
  "hooks": {
    "PreCompact": [{
      "matcher": "manual|auto",
      "hooks": [{ "type": "command", "command": "storybloq session compact-prepare" }]
    }]
  }
}

storybloq setup --client all --skip-hooks로 건너뜁니다.

SessionStart (재개 프롬프트 주입)

압축 인식 재개 프롬프트를 주입합니다. Codex setup은 --codex-hook-json 및 startup|resume|clear|compact 매처와 함께 동일한 명령어를 사용합니다. 해당 훅 JSON에는 현재 작업 ID도 포함되어 있어 동일 작업 COMPACT 복구가 복사/붙여넣기 Resume 토큰 없이 계속될 수 있습니다. setup은 훅 신뢰를 검증할 수 없으므로 설치 후 Codex에서 /hooks를 확인하세요.

{
  "hooks": {
    "SessionStart": [{
      "matcher": "compact",
      "hooks": [{ "type": "command", "command": "storybloq session resume-prompt" }]
    }]
  }
}

storybloq bus hooks enable은 별도의 프로젝트 옵트인입니다. SessionStart에 엔드포인트 메타데이터와 대기 중 개수를 추가하고, 동기식 Stop 훅이 새 사서함 커서마다 한 번씩 차단할 수 있게 합니다. 피어 페이로드 바이트는 훅 출력에 절대 나타나지 않습니다. Claude의 공유 훅 구조는 한 번 업그레이드되며 프로젝트 로컬 정책에 의해 계속 보호됩니다. Codex는 storybloq hook-status --client codex를 사용합니다.

Stop (Mac 앱용 실시간 상태)

매 턴이 끝날 때마다 storybloq hook-status를 실행하여 Mac 앱과 iOS 동반 앱이 읽는 gitignore된 .story/status.json을 새로 고칩니다.

쓰기는 콘텐츠 게이트가 적용됩니다. 페이로드가 파일에 이미 있는 내용과 동일한 경우(관찰 타임스탬프와 작성자를 무시) 아무것도 쓰지 않으며 파일의 타임스탬프와 inode는 그대로 둡니다. 따라서 유휴 턴은 작업 트리를 완전히 건드리지 않습니다. 실제 변경(워크플로 전환, 새 MCP 호출, 상태 또는 임대 변경)은 즉시 기록됩니다.

테스트 하니스가 실행 중 쓰기를 실패로 간주하는 프로젝트는 턴 종료 작성기를 완전히 끌 수 있습니다:

{ "statusWriter": { "stopHook": false } }

.story/config.json에 추가합니다. 그러면 훅은 상태 작업을 전혀 수행하지 않습니다: 세션 스캔 없음, 페이로드 빌드 없음, gitignore 자가 치유 없음, 쓰기 없음. 자율 세션은 자체 MCP 전환에서 상태를 계속 새로 고치므로 Mac 앱은 세션 실행 중에도 실시간 상태를 표시합니다. 단, 일반 대화형 작업의 턴 사이에는 업데이트가 중지됩니다. 이 플래그는 기본적으로 켜져 있으며, 읽을 수 없거나 잘못된 구성이 있어도 켜진 상태로 유지됩니다.

StopFailure (사용량 한도 감지)

Claude Code 세션이 속도 제한으로 중지될 때 storybloq session limit-stop을 실행하여 자동 재개를 위해 중지를 기록합니다 (위의 사용량 한도 자동 재개 참조). setup은 또한 동일한 session resume-prompt 명령어를 전달하는 두 번째 SessionStart 매처 그룹("resume")을 추가하여 한도 중지 세션을 수동으로 다시 열 때 한도 인식 안내를 받을 수 있게 합니다. 두 항목 모두 Claude 전용이며, 업그레이드 시마다 조정되고, 전역 킬 스위치가 설정되면 자동으로 제거됩니다.

{
  "hooks": {
    "StopFailure": [{
      "matcher": "rate_limit",
      "hooks": [{ "type": "command", "command": "storybloq session limit-stop" }]
    }]
  }
}

라이브러리 사용

import { loadProject } from "@storybloq/storybloq";

const { state, warnings } = await loadProject("/path/to/project");
console.log(state.tickets.length);           // all tickets
console.log(state.phaseTickets("p1"));       // leaf tickets in phase p1
console.log(state.umbrellaChildren("T-014")); // children of an umbrella

전체 타입 정의는 패키지와 함께 제공됩니다 (exports.types).

파일 형식 예시

티켓 (.story/tickets/T-001.json):

{
  "id": "T-001",
  "title": "Add search to sidebar",
  "type": "task",
  "status": "inprogress",
  "phase": "p2",
  "order": 10,
  "description": "Fuzzy match over ticket title + description.",
  "createdDate": "2026-04-12",
  "completedDate": null,
  "blockedBy": [],
  "parentTicket": null,
  "crossNodeBlockedBy": []
}

이슈 (.story/issues/ISS-001.json):

{
  "id": "ISS-001",
  "title": "Drag handle hit target too small on trackpad",
  "status": "open",
  "severity": "medium",
  "components": ["mac-app"],
  "impact": "Dragging tickets on trackpad requires multiple tries.",
  "location": ["macos/Views/KanbanCard.swift:42"],
  "sourceRefs": [{
    "path": "macos/Views/KanbanCard.swift",
    "startLine": 42,
    "revision": "5ac37f94f7023b18f72d8e3fcf43dd64f54c11d7",
    "contentHash": "f5b1b1b65dca3d9d86adf7c5d49082aa4dc09e7903ab46ce50e8cc6b4812e4cf",
    "reviewId": "review-2026-04-15"
  }],
  "dedupeKey": "review-2026-04-15:finding-3",
  "createdBy": "external-reviewer",
  "discoveredDate": "2026-04-15",
  "resolvedDate": null,
  "relatedTickets": []
}

각 레코드는 자체 파일입니다. ID는 유형 내에서 순차적입니다 (T-001, T-002, ...). 관계는 단일 표준 소유자입니다: 티켓의 blockedBy 필드는 차단 티켓을 가리키며, 역방향(누가 나를 차단하는지)은 스캔을 통해 파생됩니다.

생성 작업은 병렬로 실행해도 안전합니다. ID 할당과 생성 쓰기는 프로젝트 잠금 아래에서 함께 발생하므로 동시 생성자는 직렬화되고 각각 고유한 순차 ID를 받습니다. 생성이 기존 레코드를 조용히 덮어쓸 수 없습니다. 심한 동시 경합 상황에서는 충돌 대신 생성자가 오류와 함께 명시적으로 실패합니다.

이슈 sourceRefs는 변경 가능한 path:line 표시 문자열과 독립적으로 리뷰 증거를 보존합니다. Storybloq는 정규화된 참조 줄 범위만 해시하며 소스 발췌문을 저장하지 않습니다. 제공된 리비전은 Git 커밋으로 해석됩니다. 그렇지 않으면 Storybloq는 작업 트리 범위를 캡처하고 해당 바이트가 일치하는 경우에만 HEAD를 기록합니다. storybloq validate는 원본 증거를 해석할 수 없으면 오류를, 유효한 과거 증거가 HEAD에서 이동하거나 변경된 경우 경고를, 여전히 일치하면 결과 없음을 보고합니다.

손상된 config.json 또는 roadmap.json으로 인해 정상 로딩이 불가능한 경우 storybloq validate --integrity-only를 사용하세요. 이 읽기 전용 사전 점검은 모든 .story/**/*.json 파일을 한 번에 스캔하고, 가능한 경우 파서 위치를 보고하며, 심각한 단일 항목 실패와 건너뛸 수 있는 항목 및 보조 파일 실패를 구분합니다. 손상된 파일을 다시 쓰지 않습니다.

확인된 수동 또는 외부 리뷰 결과는 열린 이슈로 직접 제출해야 합니다. 먼저 검색하고, createdBy에 리뷰어 속성을 전달하고, sourceRefs를 통해 리뷰 ID와 리비전을 첨부하고, <review-id>:<finding-id>와 같은 안정적인 dedupeKey를 사용하여 재시도가 멱등적이도록 하세요. 불확실한 설계 질문은 노트 또는 소유자 질문으로 유지하세요. 구현 에이전트가 이슈 상태와 해결을 담당합니다.

티켓 및 이슈 레코드는 알 수 없는 JSON 필드를 보존합니다. storybloq ticket meta 및 storybloq issue meta를 사용하여 핵심 Storybloq 필드를 건드리지 않고 사용자 지정 패스스루 필드를 읽거나 변경하세요. 값은 JSON이며, 점 경로는 중첩 객체를 주소 지정합니다. 예: storybloq ticket meta set T-001 integration.linear '"ABC-123"'.

자동 계획 검토 깊이는 티켓별로 reviewRisk 메타데이터(low, medium, 또는 high)로 설정할 수 있습니다. 예를 들어 storybloq ticket meta set T-001 reviewRisk '"high"'는 최소 세 번의 계획 검토 라운드를 요구합니다. 레거시 risk 메타데이터도 인식되지만 reviewRisk가 표준 키입니다. 이 설정은 검토 깊이만 변경하며 검토 단계를 건너뛰지 않습니다.

예제 워크플로우

# Initialize
storybloq init --name "my-app"

# Add the first phase
storybloq phase create --id bootstrap --name "Bootstrap" --label "PHASE 1" \
  --description "Get the app running end-to-end"

# Add a ticket
storybloq ticket create --title "Scaffold Next.js" --type task --phase bootstrap

# Start Claude Code and type /story, or invoke $story in Codex, then work on it
# (or go autonomous: /story auto T-001 / $story auto T-001)

# At the end of a session, commit your changes including .story/
git add .
git commit -m "T-001: scaffold Next.js"

# Session ends. Next session starts with /story or $story and picks up with full context.

팀 모드

.story/는 git으로 추적되는 일반 JSON이므로, 이를 공유하는 팀은 공유 상태가 겪는 것과 동일한 두 가지 문제, 즉 같은 레코드에 대한 동시 편집과 새 레코드의 동시 생성을 겪게 됩니다. 팀 모드는 이 두 가지를 모두 해결합니다.

storybloq team init     # once per project; commit the result
storybloq team setup    # once per clone, by every teammate

team init은 팀 작업을 위해 프로젝트를 구성하고(스키마 버전, 클레임 만료, ID 할당자, 필수 클라이언트 기능) 자신의 클론에 대한 설정을 실행합니다. team setup은 storybloq-json git 병합 드라이버를 클론의 로컬 git config에 설치하고 .story/.gitattributes를 작성하여 .story/ JSON 파일이 해당 드라이버를 거치도록 합니다. git config는 클론별로 적용되므로 각 팀원은 각 체크아웃에서 setup을 한 번 실행해야 합니다. storybloq team doctor는 전체 구성을 확인하고(중복 표시 ID, 해결되지 않은 충돌, 오래된 클레임, 병합 드라이버 설치 여부) --ci 사용 시 오류가 있으면 0이 아닌 종료 코드로 종료합니다. 병합 게이트 워크플로우는 아래 팀 CI를 참조하세요.

동시 편집: 병합 모델

git이 같은 .story/ 레코드를 건드린 두 브랜치를 병합하면, 병합 드라이버는 줄 단위 텍스트 병합 대신 레코드별로 구조화된 3-way 병합을 실행합니다. 필드는 독립적으로 병합됩니다. 한 팀원이 티켓의 status를 변경하고 다른 팀원이 description을 편집했다면 두 변경 모두 반영됩니다. 같은 필드가 양쪽에서 다르게 변경된 경우 드라이버는 어느 쪽도 선택하지 않습니다. 그 불일치를 레코드 내부의 구조화된 _conflicts 블록으로 기록하므로 파일은 충돌 마커 없이 유효한 JSON으로 유지됩니다. git은 여전히 해당 경로를 충돌로 보고하므로 파일을 git add하고 커밋하여 병합을 마무리한 다음, 기록된 충돌을 필요할 때 해결하면 됩니다(해결될 때까지 이후 병합에도 계속 이월됩니다). 해결되지 않은 _conflicts가 있는 프로젝트는 모든 충돌이 해결될 때까지 쓰기가 차단됩니다:

storybloq conflicts list                     # every item with unresolved conflicts
storybloq conflicts show T-042               # field-level detail: base, ours, theirs
storybloq resolve T-042 --field status --use theirs
storybloq resolve T-042 --field title --value '"Merged title"'
storybloq resolve config                     # config.json merges the same way
storybloq resolve roadmap                    # so does roadmap.json

동시 생성: 표시 ID 충돌

병렬 브랜치에서 두 팀원이 항목을 생성하는 것은 또 다른 실패 모드입니다. 새 레코드는 무작위 표준 ID 파일명(예: t-8f2kq0v3n1xw9d4e.json)으로 저장되므로 독립적으로 생성된 항목은 파일 수준에서 절대 충돌하지 않습니다. 표준 ID 이전 프로젝트의 레거시 순차 파일명(ISS-041.json)만 경로 충돌이 발생할 수 있습니다. 충돌할 수 있는 것은 사람이 보는 표시 ID입니다. 두 브랜치 모두 로컬에서 "다음 빈 번호"를 계산하고 둘 다 T-042를 발행합니다. 이는 병합 충돌이 아니라 중복이며, 이를 위한 전용 도구가 있습니다:

storybloq reconcile          # renumber duplicates; the copy already on the protected ref, else the earlier one, keeps the number
storybloq reconcile --ci     # detect only: exit non-zero if duplicates exist, mutate nothing

번호가 다시 매겨진 항목은 이전 표시 ID를 previousDisplayIds에 유지하므로 기존 번호에 대한 참조도 계속 확인됩니다.

ID 할당자 선택

team init --id-allocator local|git-refs는 표시 ID 할당 방식을 선택합니다. 트레이드오프는 다음과 같습니다:

git-refs를 사용하면 team init은 remote-ref-reservations를 team.requiredFeatures에도 추가합니다. 따라서 해당 기능을 선언하지 않은 클라이언트는 git-refs 팀에서 로컬로 할당하여 충돌을 일으키는 대신 항목 생성을 거부합니다. 한 가지 주의: 현재 Mac 앱 릴리스는 예약(reservations) 기능이 도입되기 전 버전이면서도 이 기능을 선언하고 있습니다. 따라서 Mac 쪽 업데이트가 배포될 때까지 git-refs 팀에서는 Mac 앱으로 항목을 생성하지 마세요. storybloq team reserve tickets --count 5는 ID 배치를 미리 예약합니다.

스키마 버전과 이전 클라이언트

team init은 .story/config.json에 schemaVersion: 3을 기록합니다. 1.5.0 이전 CLI 릴리스는 읽기와 쓰기 모두에서 schemaVersion-3 프로젝트를 명확하게 거부하고 업그레이드 메시지를 표시합니다(Config schemaVersion 3 exceeds max supported 2. Run: npm update -g @storybloq/storybloq). 하드 실패는 의도적입니다. 해당 클라이언트는 팀 모드 데이터를 이해하지 못하며, 혼합 버전 팀에서는 이전에 오류 대신 조용한 부분 읽기를 생성했기 때문입니다.

이 차단선 이전에 생성된 팀 저장소는 schemaVersion: 2를 보유합니다. 기존 팀 저장소를 업그레이드하려면: 모든 팀원이 1.5.0+ CLI를 실행할 때까지 기다린 다음 schemaVersion을 수동으로 3으로 설정하세요(또는 동일한 업그레이드를 수행하는 storybloq team init을 다시 실행하세요). 이전 Mac 앱 빌드는 업데이트할 때까지 schemaVersion-3 프로젝트를 읽기 전용으로 표시합니다. 데이터 손실은 없습니다.

.story/.gitignore 도입 이전 저장소 업그레이드

team init과 team setup은 머신 로컬 파일들(sessions/, snapshots/, status.json, federation-cache.json, channel-inbox/)을 포함하는 .story/.gitignore를 작성합니다. gitignore는 이미 추적 중인 파일을 추적에서 해제하지 않습니다. 따라서 gitignore가 존재하기 전에 storybloq를 도입한 프로젝트는 git 히스토리에 임시 파일이 이미 포함되어 있을 수 있습니다. 한 번 확인하고 추적을 해제하세요:

git ls-files .story/ | grep -E 'sessions/|snapshots/|status\.json|federation-cache\.json|channel-inbox/'
git rm -r --cached --ignore-unmatch .story/sessions .story/snapshots .story/status.json .story/federation-cache.json .story/channel-inbox

삭제를 커밋하세요. 세션 상태는 절대 경로(사용자 이름 포함)를 기록하므로, 첫 공유 푸시 전에 이 작업을 수행하는 것이 좋습니다.

삭제는 툼스톤을 남깁니다

팀 모드에서 티켓, 이슈, 노트 또는 레슨을 삭제해도 공유 저장소에서 제거되지 않습니다. 파일은 전체 원본 콘텐츠와 함께 유지되며, 수명 주기 표시(lifecycle: "deleted"), deletedAt 타임스탬프, 그리고 삭제한 사람의 git user.email로 설정된 deletedBy를 추가로 포함합니다. 삭제-대-편집 충돌을 해결할 때도 해결자의 이메일을 deletedBy로 기록한 합성 툼스톤이 생성될 수 있습니다. 툼스톤은 누군가 storybloq gc --apply를 실행할 때까지 저장소에 남아 있습니다(기본 30일 보존).

요점: 항목을 삭제하면 일반 보기에서는 숨겨지지만, 팀원의 클론에서 콘텐츠나 신원 표시가 제거되지는 않습니다. storybloq gc를 실행하여 삭제 대상 툼스톤을 미리 확인한 다음, 보존 기간이 지나면 storybloq gc --apply를 실행하여 제거하세요.

팀이 보는 내용

팀 모드는 저장소를 통해 상태를 공유하므로 .story/ 아래에 커밋된 모든 것은 저장소 접근 권한이 있는 모든 사람에게 보입니다:

• 티켓, 이슈, 노트, 레슨과 모든 자유 텍스트 필드.

• 핸드오버: 서술형 세션 문서로, 무슨 일이 왜 일어났는지에 대한 가장 상세한 기록인 경우가 많습니다.

• 진행 중 항목의 클레임 블록: 클레임한 팀원의 git 신원(user.email), 브랜치 이름, 클레임 타임스탬프, 그리고 자율 세션이 항목을 작업하는 동안의 claimedBySession UUID.

• 해결되지 않은 병합 충돌: 분기 병합 후 영향받은 레코드는 누군가 해결할 때까지 _conflicts 블록 안에 양쪽(base, ours, theirs)의 충돌 값을 보유합니다. 팀원이 작성했지만 나중에 중재 과정에서 유실된 텍스트는 해결될 때까지 파일에 계속 표시됩니다.

gitignore가 적용되면 머신 로컬 파일은 저장소에 포함되지 않습니다: sessions/(각 세션의 events.log를 포함한 자율 세션 상태), snapshots/, status.json, federation-cache.json, channel-inbox/. 커밋된 .story/ 콘텐츠는 커밋 메시지와 코드 주석처럼 주의해서 다루세요. 저장소와 함께 이동합니다.

팀 CI

팀 모드 프로젝트의 경우, 병합 전에 중복 displayIds와 오래된 참조를 잡아내는 CI 검증을 추가하세요. 바로 사용할 수 있는 GitHub Actions 워크플로우는 TEAM_CI.md를 참조하세요.

관련 프로젝트

• @storybloq/lenses - 멀티 렌즈 코드 리뷰 MCP 서버 및 라이브러리. 9개의 특화된 리뷰어가 병렬로 실행되어 구조화된 판정을 반환합니다. storybloq 자율 렌즈 백엔드가 이를 직접 사용합니다.

• Storybloq for Mac - .story/를 감시하고 AI 클라이언트가 작업하는 동안 실시간으로 업데이트하는 네이티브 macOS 앱. Mac App Store에서 무료로 제공됩니다.

지원

무엇이든 shayegh@me.com으로 이메일을 보내세요: 설정 문제, 질문, 기능 요청, 또는 단순히 무엇을 만들고 있는지 알려주시는 것도 좋습니다. 버그 보고는 GitHub issues로도 환영합니다.

기여

이슈와 PR을 환영합니다. 사소하지 않은 변경의 경우 방향을 맞추기 위해 먼저 이슈를 열어주세요.

개발 설정:

git clone https://github.com/Storybloq/storybloq.git
cd storybloq
npm install
npm test
npm run build

라이선스

PolyForm Shield 1.0.0 - 소스 제공(source-available)형 비경쟁(non-compete) 라이선스(OSI 오픈소스 아님).

storybloq는 다음을 포함한 어떤 목적으로든 사용할 수 있습니다:

• 개인 및 취미 프로젝트

• 오픈소스 프로젝트

• 회사 내부 사용

• 구축 중인 상용 소프트웨어

별도 라이선스 없이는 storybloq와 경쟁하는 제품을 만드는 데 storybloq를 사용할 수 없습니다: 재포장, 재판매, 관리형 서비스로의 호스팅, 또는 화이트 라벨링. 해당 내용은 shayegh@me.com으로 문의하세요.

전체 텍스트는 LICENSE를, 재배포 시 반드시 전파해야 하는 저작권 고지는 NOTICE를 참조하세요.