dev 백로그 캡처의 기본 (수정중)

1. 왜 백로그인가: "지금 고칠까, 까먹을까"의 제3의 길

코드를 보다 보면 거의 매번 이런 순간이 온다. 원래는 A를 하려고 들어왔는데, 코드를 읽다가 "어, 이거 이렇게 고치면 더 좋겠는데?" 하는 B가 눈에 들어온다.

이때 보통 둘 중 하나를 한다.

• 지금 바로 B를 고친다 → 하던 A의 흐름이 끊긴다. 머릿속에 쌓아둔 A의 컨텍스트가 날아가고, B도 충분히 안 본 채 손대다 일이 커진다.
• 나중에 하자며 넘긴다 → 30분 뒤면 까먹는다. 까먹지 않아도, 그때의 "어디를 왜 고치려 했는지"가 사라진다.

dev 백로그는 그 사이의 제3의 길이다. 발견한 순간의 컨텍스트(어느 파일·왜·어떻게)를 그대로 박제해서 백로그에 캡처하고, 하던 A는 계속한다. 나중에 그 항목을 꺼내면 컨텍스트가 0이 아니라, 발견했을 때의 머릿속이 통째로 들어 있다.

이번 강의는 추상론 대신 실제 세션 하나(session_018D9ExZJvga9ccVGKJcfbo1, 2026-06-20)를 그대로 따라가며, 이 캡처가 어떻게 일어났고 백로그 시스템이 그걸 어떻게 받아내는지 본다.

2. 세션 실황: "기록용으로"라는 한마디가 모드를 바꾼다

이 세션은 popax 에서 진행됐다. 타임라인은 이렇다.

핵심은 22:14의 "dev 백로그에 기록용으로 알아보는 거야" 한 문장이다.

이 말이 없었으면 그대로 코드를 고치기 시작했을 것이다(실제로 Claude는 파일을 열며 착수했다). 그 한마디가 작업을 "지금 구현"에서 "정확히 기록"으로 돌려세웠다. 지금 당장 회의록 제목을 안 고친다. 대신 방금 조사로 알아낸 것(제목이 어디서 만들어지는지, 폴백이 이미 있는지)을 휘발시키지 않고 백로그에 남긴다.

발견 ≠ 지금 구현. 발견했을 때 해야 할 일은 "고치기"가 아니라 "흐름 안 끊기게 캡처하기"일 때가 많다. "이건 백로그로 빼자" 한마디를 습관으로 만들어라.

3. 무엇이 "좋은 백로그 항목"인가: 등록된 파일을 그대로 본다

backlog-manager 가 만든 실제 파일을 보자. docs/backlog/dev/pending/D-260620131514-meeting_chat-회의록-표시-제목-앞에-회의-날짜-추가-본문에-날짜-없으면-작성일-폴백.md (popax repo):

# D-260620131514 meeting_chat 회의록 표시 제목 앞에 회의 날짜 추가 (본문에 날짜 없으면 회의록 작성일 폴백)

- **앱**: meeting_chat
- **우선순위**: 중간
- **등록일**: 2026-06-20
- **배경**: 현재 회의록 표시 제목(`ChatSession.minutes_title`, `meeting_chat/models.py:82-100`)은
  `pipeline_steps.filename_metadata` 의 `project_name + title` 만 조합한다.
  회의 날짜가 빠져 있어, 목록/상세에서 언제 회의인지 한눈에 식별하기 어렵다.
- **제안**: 표시 제목 앞쪽에 회의 날짜를 추가한다. 예) "2026-06-20 프로젝트명 제목".
  - 날짜 출처: `filename_metadata.date` 사용. 이 값은 이미 `extract_filename_metadata`
    (`meeting_chat/services/filename.py:44-92`)에서 LLM 이 회의록 본문에서 회의 날짜를 추출하고,
    본문에 날짜가 없으면 fallback_date(회의록 작성 날짜)로 폴백하도록 되어 있다.
    따라서 폴백 로직은 이미 존재하므로, 표시 단계에서 그 date 를 제목 앞에 붙이기만 하면 된다.
  - 구현 위치 후보: minutes_title 프로퍼티에서 parts 맨 앞에 meta.get('date') 를 추가.
  - 규모: 작은 변경(표시 로직 한 곳). 마이그레이션 불필요.
- **연관 파일**: meeting_chat/models.py (minutes_title L82-100, display_title L102-132),
  meeting_chat/services/filename.py (extract_filename_metadata L44-92)
- **참고**: [[#D-260615182247]] (세션 리스트 제목을 회의록 제목으로 표시). 같은 minutes_title 다루므로 함께 작업하면 효율적

이 13줄이 좋은 항목인 이유는, "나중의 나"가 컨텍스트 0에서 시작하지 않게 해주기 때문이다.

• 배경(왜): 단순히 "날짜 추가"가 아니라 왜 필요한지(식별이 어렵다)를 적는다. 우선순위 판단의 근거가 된다.
• 제안(어떻게): 방금 조사로 알아낸 구현 스케치가 들어 있다. 특히 "폴백 로직은 이미 존재한다" 는 발견이 박제됐다. 이게 없으면 나중에 또 처음부터 코드를 파야 한다.
• 연관 파일 + 경로:라인: models.py:82-100, filename.py:44-92. 꺼내 들면 바로 그 줄을 연다.
• 참고(cross-ref): 관련 기존 항목을 [[#D-260615182247]] 로 잇는다(다음 절).

반대로 나쁜 항목은 "제목에 날짜 추가" 한 줄이다. 한 달 뒤 이 줄을 보면 어느 제목인지, 왜 인지, 어디를 고쳐야 하는지 전부 다시 조사해야 한다. 캡처의 가치는 지금 머릿속에 있는 코드 위치·판단을 같이 박는 것에 있다.

4. backlog-manager 가 더 해주는 것: 중복 검사·연결·자동 커밋

백로그 등록은 직접 파일을 만드는 게 아니라 backlog-manager 서브에이전트(.claude/agents/backlog-manager.md)에 위임한다. 이 에이전트는 받아 적기만 하지 않고, 사람이 빼먹기 쉬운 일을 대신 해준다.

• 도메인 판정: popax 앱(meeting_chat) 이야기라 자동으로 dev 도메인(#D)으로 분류. 여러 프로젝트 공유분이면 standarda(#S)로.
• 중복·연관 검사: 기존 항목들과 제목·배경 유사도를 본다. 이번엔 #D-260615182247("세션 리스트 제목을 회의록 제목으로 표시")가 같은 minutes_title 프로퍼티를 건드린다는 걸 찾아내 참고 에 cross-ref 로 걸었다. → 중복이 아니라 "함께 하면 효율적" 인 묶음을 발견.
• ID·파일 생성: D-YYMMDDHHMMSS 타임스탬프로 ID를 만들고 pending/ 에 파일 생성.
• 자동 커밋·push: 등록/완료의 마지막 단계에서 직접 git add → commit → push (d46c212). 사용자가 따로 "커밋해줘" 안 해도 된다.

즉 캡처를 위임하면, 등록 자체뿐 아니라 "이거 이미 있나? 관련된 게 뭐지?" 까지 같이 처리된다.

5. dev 백로그 시스템 구조: docs/backlog/

backlog-manager 가 관리하는 실제 디렉토리는 이렇게 생겼다 (popax docs/backlog/).

docs/backlog/
├── dev/                # popax 프로젝트 자체 개발 항목 (ID 접두사 #D)
│   ├── pending/        # 대기 중: D-260620131514-....md, D007-....md ...
│   └── done/           # 완료: D-260617045404-....md ...
└── standarda/          # standarda-core/template 반영 항목 (ID 접두사 #S)
    ├── pending/
    └── done/

핵심 규칙 네 가지.

• entry 1개 = 파일 1개. 예전엔 pending.md 한 파일에 다 모았는데, 여러 세션이 동시에 등록하면 충돌이 났다. 그래서 항목마다 별도 파일로 쪼갰다.
• 도메인 분리. dev(이 프로젝트만의 일, #D) vs standarda(여러 프로젝트가 공유하는 standarda-template·standarda-core·hook, #S). standarda 항목은 standarda-template / standarda-core 쪽 반영 대상이다.
• 상태 = 폴더 위치. 본문에 status: 같은 필드가 없다. pending/ → done/ 로 파일을 옮기는 것(git mv)이 곧 상태 전환이다. 완료 처리 때 본문에 완료일·머지 커밋·산출물 메타가 덧붙는다.
• 파일명 = {ID}-{kebab-slug}.md. 신규 ID는 D-YYMMDDHHMMSS(등록 시각). 옛 항목은 D001~D044 처럼 zero-padded 인데, 재명명하지 않고 그대로 둔다.

본문 포맷(pending)은 §3에서 본 그대로다: 앱 / 우선순위 / 등록일 / 배경 / 제안 / 연관 파일 / 참고. 프론트매터 없이 - **키**: 값 불릿이다.

6. 실전: 어떻게 등록하고 꺼내 쓰나

backlog-manager 는 슬래시 커맨드가 아니다. 자연어로 말하면 Claude Code 가 문맥을 보고 이 에이전트에 위임한다.

이번 세션에서 사용자가 한 건 사실상 "dev 백로그에 기록용으로" 한 문장이 전부다. 나머지(도메인 판정·중복 검사·파일 생성·cross-ref·커밋)는 에이전트가 했다.

그렇게 pending/ 에 쌓인 항목은 나중에 /develop 한 사이클로 꺼내 스펙→구현→머지까지 간다. 그 파이프라인은 /develop 한 사이클에서 다뤘다. 즉 캡처와 실행이 백로그의 앞뒤 절반이다.

7. ⚠️ 주의: 이름이 같은 "Dev 백로그"가 둘 있다

헷갈리기 쉬운 함정이 하나 있다. 팝업스튜디오에는 이름이 비슷한 "dev 백로그"가 두 개 있는데, 이 강의에서 다룬 것과는 전혀 다른 시스템이 하나 더 있다.

Notion 쪽 자동 실행 시스템은 이 강의 범위가 아니다. 별도 문서(팀 wiki infrastructure/dev-backlog-runner.md)로 정리돼 있다. 여기선 "이름이 같지만 다른 것"이라는 점만 알면 된다.

실전 함정: Claude Code 에게 그냥 "dev 백로그 목록 보여줘" 라고 하면, 때때로 Notion DB(자동 실행 큐)의 항목을 읽어 보여주는 경우가 있다. 이 강의에서 다룬 프로젝트 레벨 백로그(docs/backlog/dev/)를 보고 싶으면, 그렇게 명시해서 요청한다.

• ✅ "이 프로젝트의 dev 백로그(docs/backlog/dev/pending) 보여줘"
• ✅ "backlog-manager 로 dev 백로그 pending 목록 보여줘"
• ⚠️ "dev 백로그 보여줘" → Notion DB 를 읽어올 수 있음 (의도와 다른 결과)

오늘 정리 + 다음

• 정리: 작업 중 발견한 할 일은 지금 고치기도 까먹기도 아닌 캡처가 정답일 때가 많다. 발견 순간의 컨텍스트(왜·어디·어떻게)를 backlog-manager 로 docs/backlog/{dev|standarda}/pending/ 에 박제하고, 하던 일은 계속한다. "백로그에 기록용으로" 한마디가 그 스위치다.
• 흔한 함정: 백로그에 한 줄만 적는 것("제목에 날짜 추가"). 나중에 왜·어디인지 다 까먹어 결국 처음부터 다시 조사한다. §3의 13줄처럼 코드 위치(경로:라인)와 판단을 같이 박아라.
• 이어지는 흐름: 이렇게 쌓인 pending 항목을 실제로 꺼내 머지까지 가는 흐름(/develop 한 사이클)과 연결해, 백로그 한 건의 생애(등록 → /develop → done 이동)를 한 바퀴 돈다.
• 자습 권장: popax docs/backlog/dev/pending/ 를 열어 좋은 항목과 빈약한 항목을 비교해 보고, 자기 프로젝트에서 "지금 고칠까 말까" 망설였던 일 하나를 backlog 로 캡처해 본다.