dev 백로그 캡처 판단 여섯 사례 (수정중)

1. 들어가며: 캡처는 한 가지 모양이 아니다

개념 편(dev 백로그 캡처의 기본)에서 핵심은 하나였다. 작업 중 발견한 일은 지금 고치기도 까먹기도 아닌 캡처가 정답일 때가 많다는 것. "dev 백로그에 기록용으로" 한마디가 모드를 바꾼다는 것.

그런데 실제로 한 주를 돌아보면, 캡처는 늘 같은 모양이 아니다. 어떤 건 코드를 이미 건드리다가 되돌리고 기록하고, 어떤 건 조사를 끝낸 뒤 기록하고, 어떤 건 이미 있는 항목과 합치고, 어떤 건 너무 커서 에픽으로 묶고, 어떤 건 기록하자마자 바로 구현으로 넘기고, 또 어떤 건 기록하지 않고 그냥 지금 고치는 게 맞다.

이번 강의는 추상론 대신, popax 에서 2026-06-21 하루에 실제로 오간 백로그 대화 6건을 그대로 따라간다. 6건이 각각 다른 판단을 보여준다. 그 판단의 결을 익히는 게 오늘 목표다.

#	발화(요약)	어떤 판단	결과
A	"기능 구현하지 말고, dev 백로그에 기록해줘"	착수했다가 되돌리고 캡처	#D-260621020155
B	(캐싱 미적용 확인 후) "일단 백로그 등록해줘"	조사·검증 후 캡처 + dev→#S 분기	#D-260621135550 → #S-260621143826
C	"일단 백로그에 기록해줄래"	중복 발견 → 기존 항목 갱신	#D-260523121933 (신규 X)
D	"백로그에 화자 이름, 용어 … 기록해야 하는데"	너무 커서 에픽으로 묶음	#D-260621134620 [에픽]
E	"이 사항을 dev 백로그에 기록해줄래"	캡처 즉시 /develop	#D-260621133105 → 구현
F	"원하시면 백로그 등록해 … 이거 정리해줘"	캡처 제안했으나 지금 고치기	(백로그 미등록)

6건 모두 같은 프로젝트(popax docs/backlog/)의 같은 시스템을 쓴다. 다른 건 사람의 판단이다. backlog-manager 는 그 판단을 받아 적고 부수 작업(중복검사·cross-ref·커밋)을 대신할 뿐, "이게 캡처 대상인가, 어떤 모양인가"는 사람이 정한다.

---

2. 사례 A: "구현 말고 기록해", 착수했다가 되돌리고 캡처

가장 교과서적인 "모드 전환"이다. 개념 편의 세션 실황과 같은 장면이 다른 주제(자동 로그인)에서 또 일어났다.

대화 흐름:

• 사용자: "현재 우리 프로젝트에 자동 로그인 기능이 적용되어 있나?" → 순수 조사 질문.
• Claude 가 확인하다가 settings/base.py 에 SESSION_COOKIE_AGE 를 바로 넣기 시작했다.
• 사용자: "기능 구현하지 말고, dev 백로그에 기록해줘."
• Claude: "네, 코드 변경을 되돌리고 백로그로 등록할게요." → settings/base.py 원상복구 → #D-260621020155 등록 (커밋 c9f2e50).

여기서 배울 점은 두 가지다.

첫째, 이미 손댄 코드를 되돌리는 것도 캡처의 일부다. "구현하지 말라"는 말은 단순히 "멈춰"가 아니라 "지금까지 만진 것도 원복하고, 알아낸 걸 기록으로 남겨라"이다. Claude 가 임시로 넣은 SESSION_COOKIE_AGE 를 지우고, 그 구현 방향을 백로그 본문에 적었다.

둘째, 캡처가 "조사 결과"를 박제한다. 등록된 #D-260621020155 본문(docs/backlog/dev/done/D-260621020155-...md)을 보면, 방금 조사로 알아낸 게 그대로 들어 있다.

- **배경**: 현재 popax 는 SESSION_COOKIE_AGE / SESSION_EXPIRE_AT_BROWSER_CLOSE 를
  커스터마이징하지 않아 Django 기본값(2주 세션 …)이 일괄 적용된다. … 365일로 연장하기로 결정.
- **제안**: settings/base.py 에 SESSION_COOKIE_AGE = 60 * 60 * 24 * 365 추가. …
  활성 사용자의 만료를 매 요청마다 갱신(sliding window)하려면 SESSION_SAVE_EVERY_REQUEST = True 도 함께 검토 필요…

이 항목은 이후 /develop 으로 구현돼 지금은 done/ 에 있다 (머지 6359c3d, sliding window 까지 적용). 즉 "되돌리고 캡처" → 나중에 실행의 완결까지 한 바퀴 돈 사례다.

핵심: 발견 ≠ 지금 구현. 손이 먼저 나갔으면 되돌리고, 머릿속에 있는 조사 결과를 백로그에 박는다.

---

3. 사례 B: 조사부터 끝내고 캡처, 그리고 dev 가 #S 를 낳다

사례 A 와 닮았지만 한 단계 더 있다. "진짜 문제인지 먼저 검증한 뒤" 캡처하고, 그 결과 dev(#D) 항목이 standarda(#S) 항목을 파생시켰다.

대화 흐름:

• 사용자: "우리 프로젝트는 지금 주로 anthropic LLM 을 쓰는 거지? 확인해줄래." → 조사.
• 이어 prompt caching 적용 여부를 확인 → Claude: "결론부터: LLM prompt caching 로직은 적용되어 있지 않습니다." (세 층 모두 캐싱 코드 부재를 코드로 확인).
• 사용자: "일단 백로그 등록해줘." → #D-260621135550 등록 (커밋 362a364).

좋은 캡처의 전제는 "문제가 실재함을 코드로 확인" 하는 것이다. "캐싱이 없는 것 같다"가 아니라, standarda-core/standarda_core/llm.py 의 get_anthropic_llm 이 model_kwargs/extra_headers/cache_control 을 안 넣는다는 걸 눈으로 확인한 뒤 등록했다. 그래서 본문 배경이 추측이 아니라 사실의 목록이다.

그리고 이 사례의 진짜 교훈은 도메인 분기다. 등록된 #D-260621135550 본문에 이런 줄이 있다.

- **제안**: get_anthropic_llm 공용 함수 시그니처를 일괄 변경하기보다(타 프로젝트 영향이 커 신중해야 함),
  캐싱 가치가 큰 호출부에서 … cache_control 마커를 붙이는 방식을 검토. …
  - (필요 시) standarda-core 함수 변경은 #S 백로그로 분리 검토
- **참고**: … standarda-core 함수 변경이 필요해지면 [[#S006]] 등 standarda 백로그 연계 검토.

popax 한 곳만의 일이면 #D(dev), 여러 프로젝트가 공유하는 standarda-core/standarda-template 를 건드리면 #S(standarda) 로 가른다(개념 편의 시스템 구조 참고). 이 건은 호출부 적용(popax)과 공용 헬퍼 정본화(standarda-core)가 섞여 있어, 실제로 구현 단계에서 #S-260621143826("LLM prompt caching 공통화, core 캐싱헬퍼") 가 따로 등록됐고, 지금 둘 다 done/ 이다.

핵심: 캡처 전에 "정말 문제인가"를 코드로 확인하면 본문이 사실이 된다. 그리고 영향 범위가 공유 패키지에 닿으면 #D 와 별개로 #S 로 쪼갠다.

---

4. 사례 C: 이미 있던 항목과 합치기 (중복 대신 갱신)

캡처가 항상 새 파일을 만드는 건 아니다. 같은 주제가 이미 있으면 합치는 게 맞다.

대화 흐름:

• 사용자: 회의록을 채팅으로만 고치는 지금 방식 외에, 사용자가 직접 편집하는 기능을 어떻게 구현하면 좋을지 제안 요청 → 논의.
• 사용자: "일단 백로그에 기록해줄래."
• Claude: "이미 같은 주제의 항목(#D-260523121933)이 있는데, 이번 조사 내용이 훨씬 구체적입니다. 기존 ID를 보존하면서 갱신하는 게 가장 깔끔하니 그렇게 진행하겠습니다."
• 결과: 신규 등록 대신 기존 #D-260523121933 본문을 이번 조사 내용으로 교체(커밋 a44674b).

backlog-manager 는 받아 적기 전에 기존 항목과 제목·배경 유사도를 검사한다(개념 편 참고). 여기서 #D-260523121933("회의록 본문 직접 편집/저장 기능")이 같은 주제임을 찾아냈다. 그래서 중복 파일을 만들지 않고, ID 를 보존한 채 더 구체화된 확정안(전체 textarea 편집 토글, minutes_version +1 버전 처리 등)으로 본문만 갈아끼웠다.

왜 이게 중요한가? 같은 주제로 #D-A, #D-B 두 개가 생기면, 나중에 /develop 으로 꺼낼 때 어느 게 최신인지 헷갈리고 한쪽이 방치된다. ID 보존 + 본문 갱신은 "기록의 이력"을 한 줄로 유지하는 방법이다.

핵심: "기록해줘"가 늘 새 파일을 뜻하진 않는다. 같은 주제가 있으면 합친다. 사람이 안 챙겨도 backlog-manager 가 유사도 검사로 잡아준다. (이 항목은 이후 구현돼 지금 done/.)

---

5. 사례 D: 너무 커서 "에픽"으로 묶기 + cross-ref

어떤 발견은 한 항목으로 담기엔 너무 크다. 그러면 에픽(epic)(여러 하위 항목을 묶는 상위 설계)으로 캡처한다.

대화 흐름:

• 사용자(요지): 트랜스링크 박희덕 대표가 전사문에서 "박해덕"으로 오기되는데, 맥락상 박희덕임을 알면 교정 가능하다. 그런데 "박해덕→박희덕" 교정을 요청하면 그게 다음에 "박히덕" 같은 새 변형으로 나오면 또 못 잡는다. "이 업데이트 필요 사항을 백로그에 기록해야 하는데…"
• Claude: 바로 적지 않고 세 갈래 병렬 조사 (현재 메모리 구조 / 검증 로직 / knowclaw 참고 자산) → 구조적 원인을 코드로 확인.
• 결과: #D-260621134620 [에픽] 회의록 화자명·용어 표기: 맥락 기반 교정 학습 루프 등록 (우선순위 높음, 지금도 pending/).

이 항목이 그냥 "이름 교정 고치기" 한 줄이 아닌 이유는, 조사에서 근본 원인이 하나가 아니라 구조임을 찾았기 때문이다.

## 제안 (3개 메커니즘으로 분리)
① 엔티티 맥락 위키 (데이터): 인물·조직·용어마다 canonical 표기 + 맥락 + 알려진 오기 …
② agents.md 룰 (행동): "맥락상 가까운 토큰이 나오면 canonical 로 교정" …
③ 교정 캡처 경로 수정 (접착제): forbidden_label 죽은 규칙 대신 엔티티 canonical 로 …

그리고 에픽의 핵심 장치는 cross-ref 다. 본문이 기존 항목 7건을 [[...]] 로 엮는다.

## 기존 항목과의 관계 (cross-ref, 본 에픽이 묶는 하위 축)
- [[D-260618110606]] (회의록 맥락 위키 …): ① 엔티티 위키의 토대.
- [[D-260618200121]] (agents.md 룰 콘텐츠) + [[D-260522141630]] (룰 외부화 메커니즘): ② 룰 축.
- [[D-260524125707]] (화자 구분 가설→확인): 화자명 교정 학습의 입력 소스.
- …

즉 에픽은 흩어져 있던 관련 항목들을 하나의 설계 의도 아래 묶고, 실제 구현은 하위 항목으로 분해해 진행한다. 실제로 이 에픽의 첫 조각은 이미 손이 닿아, popax 최신 커밋 19237c0("회의록 생성 시 엔티티 메모리 주입으로 표기 정규화 (#D-260621134620 ①-a)")로 반영됐다.

핵심: 발견이 "단일 작업"이 아니라 "구조 문제"면, 한 줄 항목 대신 에픽으로 묶고 기존 항목을 cross-ref 한다. 에픽은 구현 단위가 아니라 설계·오케스트레이션 단위다.

---

6. 사례 E: 캡처하자마자 /develop 으로 넘기기

캡처와 실행이 항상 며칠 떨어져 있는 건 아니다. 어떤 건 기록 → 곧장 구현이다.

대화 흐름:

• 사용자: "조직 메모리를 조직 멤버들도 수정할 수 있어야 하고, 회의록 채팅 사이드패널에서 추가·수정·삭제·활성 토글이 가능해야 할 거 같아. 이 사항을 dev 백로그에 기록해줄래."
• Claude: #D-260621133105("조직 메모리 권한 및 사이드패널 편집 지원 확장") 등록 (커밋 3deb62c).
• 사용자: "develop 으로 구현해줘." → Claude 가 곧바로 /develop 워크플로우 시작 (app: meeting_chat, 백로그 ID #D-260621133105).

왜 굳이 먼저 백로그에 적고 바로 구현하나? 어차피 지금 할 건데? 백로그 항목이 /develop 의 입력이기 때문이다. /develop 한 사이클(실행 편)은 백로그 항목을 받아 스펙→구현→검증→머지로 간다. 캡처는 "나중을 위한 메모"일 뿐 아니라, 지금 바로 실행하더라도 그 실행의 출발점이 된다.

이게 개념 편에서 말한 캡처와 실행이 백로그의 앞뒤 절반이라는 말의 실제 모습이다. 여기선 그 두 절반이 같은 대화 안에서 연달아 일어났다.

핵심: "기록해줘" 다음에 "develop 으로 구현해줘"가 바로 와도 이상하지 않다. 캡처는 미래용 메모이자 /develop 의 입력 규격이다. (이 항목도 지금 done/.)

---

7. 사례 F: 캡처하지 말고 지금 고치는 게 맞을 때

마지막은 반례다. 모든 발견이 백로그로 가야 하는 건 아니다.

대화 흐름:

• Claude 가 작업 끝에 두 가지를 보고: "① meeting_chat 테스트 6개가 기본 모델 Claude 전환 후 깨진 채 방치돼 있습니다(get_google_llm 패치 → 실제 get_anthropic_llm/resolve_llm 호출). 원하시면 백로그 등록해 따로 정리하겠습니다."
• 사용자: "이거 정리해줘." → 백로그가 아니라 지금 바로 수정 (테스트를 graph.get_google_llm → graph.resolve_llm 등으로 패치).

여기서 Claude 는 캡처를 제안했지만, 사용자는 지금 고치기를 골랐다. 그게 옳았다.

개념 편의 "지금 고칠까 / 까먹을까 / 캡처할까" 3지선다에서, 캡처가 정답이 아닌 경우를 가르는 기준은 대략 이렇다.

캡처가 맞다	지금 고치기가 맞다 (사례 F)
하던 일(A)의 흐름을 끊는 곁가지 발견	이미 깨져 있는 것 (신규 발견 아님, 부채)
규모·방향에 판단/설계가 더 필요	원인이 명확하고 국소적(테스트 패치 한 곳)
지금 당장 안 해도 됨	방치하면 다른 작업의 신뢰를 깎음(깨진 테스트)

깨진 테스트 6개는 "조사하다 떠오른 더 좋은 아이디어(곁가지)"가 아니라, 모델 전환 때 같이 고쳤어야 할 부채다. 원인도 명확(옛 심볼 패치)하고 수정 범위도 국소적이다. 이런 건 백로그에 넣어 미루는 게 오히려 비용이다. 그래서 "이거 정리해줘"가 맞다.

핵심: 캡처는 만능이 아니다. 이미 깨진 부채 + 원인 명확 + 국소 수정이면 백로그가 아니라 지금 고친다. "원하시면 백로그 등록할까요?"에 "그냥 고쳐"라고 답하는 판단도 똑같이 중요하다.

---

8. 한 장으로: 발견을 만났을 때의 결정 흐름

오늘 6건을 결정 트리로 압축하면 이렇다.

발견/요청이 들어옴
│
├─ 이미 깨진 부채 + 원인 명확 + 국소 수정?  → 지금 고친다 (사례 F)
│
├─ 캡처한다
│   ├─ 손이 먼저 나갔으면 → 되돌리고 캡처 (사례 A)
│   ├─ 진짜 문제인지 → 코드로 먼저 확인 후 캡처 (사례 B)
│   ├─ 공유 패키지(core/template)에 닿으면 → #D 와 별개로 #S 분리 (사례 B)
│   ├─ 같은 주제가 이미 있으면 → 신규 X, 기존 ID 갱신 (사례 C)
│   └─ 한 항목에 안 담길 만큼 크면 → 에픽 + cross-ref (사례 D)
│
└─ 캡처 직후 바로 할 거면 → 그 항목을 입력으로 /develop (사례 E)

backlog-manager 가 대신 해주는 것(도메인 판정·중복검사·cross-ref·ID 생성·자동 커밋)과, 사람이 정해야 하는 것(캡처할지 / 고칠지, 합칠지 / 에픽으로 묶을지)이 어디서 갈리는지 보이면 오늘은 충분하다.

---

오늘 정리 + 다음

• 정리: 캡처는 한 가지 모양이 아니다. 같은 docs/backlog/ 시스템 위에서도, 하루 6건이 각각 다른 판단을 보였다(되돌리고 캡처(A) / 검증 후 캡처·#S 분기(B) / 기존 갱신(C) / 에픽 묶기(D) / 즉시 /develop(E) / 캡처 말고 고치기(F)). backlog-manager 는 부수 작업을 대신하고, "캡처할지·어떤 모양인지"는 사람이 정한다.
• 흔한 함정: ① "기록해줘 = 무조건 새 파일"로 알고 같은 주제를 중복 등록(→ 사례 C 처럼 합쳐야 함). ② 반대로 모든 걸 백로그로 미루는 것. 이미 깨진 부채는 사례 F 처럼 지금 고치는 게 맞다.
• 이어지는 흐름: 이렇게 쌓이고 정리된 pending 항목 하나(예: 사례 D 에픽의 하위 조각)를 실제로 꺼내 /develop 한 사이클로 머지까지 가 본다. 실행 편 와 이어진다.
• 자습 권장: popax docs/backlog/dev/{pending,done}/ 를 열어 오늘 본 6개 ID(#D-260621020155·#D-260621135550·#D-260523121933·#D-260621134620·#D-260621133105)의 실제 본문을 읽고, "이건 왜 에픽일까 / 왜 갱신했을까"를 각자 판별해 본다. 그리고 standarda 백로그(docs/backlog/standarda/done/S-260621143826-...)와 짝지어 #D↔#S 분기를 확인한다.