콘텐츠로 이동

ADR-0013 — 협업 wiki 진입점 (Slack→raw / GitHub Issue→wiki 2단계 정책)

Context

ADR-0012는 "1인 단계" 한정 운영 룰북이었다. 사용자 확인 결과 실제로는 기획자·디자이너·마케터가 이미 결합되어 있고, 본인(사용자) 본인도 일상 wiki 운영을 로컬에서 직접 손대지 않겠다는 입장이다. 결과적으로 ADR-0012의 D1("변경 주체 ingest 책임")·D10("본인 = hub") 양쪽 가정 모두 깨졌다.

단순 자동화(Slack 이모지 1개로 wiki merge까지)는 위험 ↑ — 환각·오해·미공개 협상 유출 사고. 그래서 본 ADR은 2단계 분리 게이트 정책을 채택한다:

  • 1단계: 박제 — Slack @wiki-bot 멘션 또는 #wiki-inbox 게시 → wiki-bot이 raw layer(immutable)에 자동 박제. 사고 위험 낮음 (raw는 hook으로 보호 + git history 추적).
  • 2단계: 반영 — raw → wiki 정식 페이지 반영은 GitHub Issue를 게이트로 통과. 본인이 라벨 review·조정 후 wiki:ready-to-ingest 라벨 부착 시 GitHub Action이 wiki PR 자동 생성, 본인이 review·merge.

본 ADR은 정책·메커니즘만. Slack bot 라이브러리·GitHub Action 구조·Issue 라벨 컨벤션·시크릿·비용 등 인프라 디자인은 ADR-0014로 분리. 디자이너·마케터 워크플로는 ADR-0015로 분리.

Decision

§A — 2단계 분리 흐름도

1단계 (Slack → raw, 자동)
─────────────────────────
[팀원] Slack `@wiki-bot` 멘션 또는 `#wiki-inbox` 게시
   + 본문 / Notion 링크 + 선택 태그
   ↓
[wiki-bot] (자동)
   - Notion 링크 있으면 → /sync-notion → raw/notion/<page>.md
   - 본문만이면 → raw/meetings/<yyyy-mm-dd>-<slug>.md
   - 가드레일 자동 분류 (반영 / 참고 / 금지)
   - GitHub Issue 자동 생성 (요약 + 분류 라벨 + raw 경로)
   - Slack 알림 broadcast (thread reply + #wiki-notify):
     "raw/<...> 박제 완료 / Issue #N 생성 / 자동 분류: {반영|참고|금지}"
   ↓
[raw layer 갱신 완료] — wiki는 아직 안 건드림

2단계 (GitHub Issue → wiki, review 게이트)
─────────────────────────────────────────
[GitHub Issue (자동 생성)]
   - 제목: "[wiki:{category}] {raw 요약}"
   - 본문: raw 변경 요약 + 영향 wiki 페이지 후보 + ingest 카테고리 판정 사유
   - 라벨: wiki:반영 / wiki:참고 / wiki:금지 + 선택 태그 (#plan #meeting 등)
   ↓
[본인] Issue review
   - 라벨 조정 (반영 ↔ 참고 ↔ 금지 재분류 가능)
   - 코멘트로 ingest 지침 ("이 페이지 강조해줘" 등)
   - "wiki:ready-to-ingest" 라벨 추가 → trigger
   ↓
[GitHub Action 'wiki-ingest-from-issue.yml']
   - Claude Code agent가 Issue 본문·코멘트·라벨 읽어 wiki PR 생성
   - PR 본문: Issue 링크 + 변경 페이지 list + log.md draft entry
   ↓
[본인] PR review + merge
   ↓
[wiki 갱신 완료] + /log-append 자동 + Issue 자동 close
   ↓
[wiki-bot] Slack 알림 broadcast (#wiki-notify):
   "wiki/<...> 갱신 완료 / Issue #N close / log entry +1 / PR 링크"

라벨 변경(반영 ↔ 참고 ↔ 금지 재분류, wiki:ready-to-ingest 부착·제거, wiki:stale 부착)도 모두 Slack 알림 broadcast — 본인·팀원이 wiki 상태를 별도 모니터링 없이 추적 가능.

§B — 1단계 (Slack → raw) 정책

  • raw/notion/ · raw/meetings/는 immutable + deny-raw-write.sh hook 보호 (CLAUDE.md §12)
  • wiki-bot은 /sync-notion skill 또는 heredoc 우회 패턴으로만 raw 작성 (사람·LLM 일반 쓰기 차단 일관)
  • 1단계 자동화는 본인 승인 게이트 없음 — raw 자체가 immutable이라 사고 위험 낮음. 잘못 박혀도 wiki 미반영 + git history로 추적·복구 가능
  • 분당 메시지 빈도가 임계 넘으면 (남용·DDoS) wiki-bot rate limit (ADR-0014 인프라)

§C — 2단계 (GitHub Issue → wiki) 정책

  • 모든 wiki 본문 변경은 GitHub Issue를 게이트로 통과. Issue 없이 wiki 직접 갱신 금지 (개발자 GitHub PR 경유 코드/spec 변경은 예외 — §E)
  • Issue 자동 생성 → 본인 라벨 review → wiki:ready-to-ingest 라벨 추가 시 GitHub Action 트리거
  • wiki PR은 Claude Code agent가 Issue 컨텍스트(본문·코멘트·라벨) 읽어 생성. 본인 review + merge
  • Issue close 시점: wiki PR merge 완료 시 자동
  • Issue가 1주 이상 미처리면 wiki:stale 라벨 자동 부착 + Slack 알림 (ADR-0014 정책 디테일)

§D — 가드레일 3카테고리

카테고리 의미 wiki 반영 처리
반영 의사결정·도메인 모델·API·가격·컴플라이언스·ADR 트리거 사유 정식 wiki 페이지(concepts·domains·decisions) 갱신 PR
참고 보조 자료·추후 의사결정 후보·검증 필요·맥락만 보존 wiki/inbox/<yyyy-mm-dd>-<slug>.md 또는 draft 상태(status: drafted)로만. 정식 페이지 X
금지 PII·미공개 협상(가격/계약/채용)·credentials·trade secret·험담·검증 안 된 추측 wiki 격리. raw에만 보관. Issue는 만들지만 wiki:금지 라벨로 close. wiki PR 트리거 X

이 카테고리는 ADR-0012 §C "반드시·보류·금지"의 사용자 표현 명확화 — 본 ADR로 명명 통일. 봇이 자동 분류 → 본인이 Issue에서 라벨 수정으로 재분류 가능. 카테고리 변경 시 처리 로직 자동 재실행.

§E — 역할별 워크플로

역할 1단계 (Slack → raw) 2단계 (Issue → wiki)
기획자 Notion PRD 작성 → @wiki-bot 멘션 + Notion 링크 + #plan 태그 Issue 자동 생성. 본인이 라벨 조정 + wiki:ready-to-ingest
회의 진행자 회의 종료 → @wiki-bot 멘션 + 본문/메모 링크 + #meeting 태그 자동 Issue. 가드레일 자동 분류 (PII 감지 시 wiki:금지 자동)
개발자 Slack 경유 X 코드 PR + mvp-{back,front}/docs/frd/<X>/spec.md + wiki/domains 같이 작성. PR template 체크박스 (별도 가벼운 라운드)
디자이너·마케터 ADR-0015 분리 ADR-0015 분리

§F — 양방향 Slack 알림 정책

이벤트 알림 대상 알림 내용
1단계 raw 박제 완료 멘션 thread reply + #wiki-notify 채널 raw 경로 / 자동 분류 결과 / Issue #
Issue 자동 생성 #wiki-notify 채널 Issue 링크 + 라벨 + 요약
Issue 라벨 변경 (본인 또는 봇) #wiki-notify 채널 Issue # / 변경 전·후 라벨
wiki:ready-to-ingest 부착 #wiki-notify 채널 "wiki PR 생성 트리거"
wiki PR 생성 #wiki-notify 채널 PR 링크 + 변경 파일 list
wiki PR merge → wiki 갱신 완료 #wiki-notify 채널 변경 페이지 list + log entry + PR 링크
Issue 1주 미처리 → wiki:stale 자동 부착 #wiki-notify 채널 stale Issue list
wiki:금지 라벨 → auto-close #wiki-notify 채널 "금지 카테고리, PR 생성 X"

알림 채널·포맷·rate limit·DM vs 채널 등 디테일은 ADR-0014 인프라 라운드.

§G — 가드레일 = Issue 라벨링 강제 메커니즘

  • 본인 의사결정 = Issue 라벨 클릭. 코드·CLI 손댈 일 0
  • 라벨 조합이 자동화 트리거 조건:
  • wiki:반영 + wiki:ready-to-ingest → 정식 wiki PR (concepts·domains·decisions 갱신)
  • wiki:참고 + wiki:ready-to-ingest → wiki/inbox/<slug>.md 또는 status: drafted로만
  • wiki:금지 → auto-close, PR 트리거 X. raw는 그대로 유지
  • 봇 자동 분류 라벨을 본인이 재분류 시 처리 로직 자동 재실행 (예: 반영 → 참고 이동)
  • Issue 검색·필터로 의사결정 누적 트래커 효과 (Stripe Spec-Kit·ThoughtWorks LADR 패턴 부분 채용)

§H — 봇·Issue 인프라 (ADR-0014 분리)

봇 이름·채널·이슈 라벨 컨벤션·GitHub Action 구조·시크릿 매트릭스·비용 추정·보안 모두 ADR-0014에서 결정.

본 ADR 시점 placeholder: @wiki-bot, #wiki-inbox, #wiki-notify, 라벨 wiki:반영/wiki:참고/wiki:금지/wiki:ready-to-ingest/wiki:stale.

Consequences

긍정

  • 2단계 분리로 사고 위험 ↓ — raw는 immutable, wiki 반영은 Issue review 게이트
  • 의사결정 누적 — 모든 wiki 변경 사유가 GitHub Issue로 영구 트래커 (Karpathy "compounding artifact" + ThoughtWorks ADR "git history" 두 패턴 모두 만족)
  • 본인 일상 부담 = Issue 라벨 클릭 + PR merge만
  • 양방향 Slack 알림으로 별도 모니터링 불필요
  • 가드레일 3카테고리가 명확 — 봇·사람·LLM 모두 같은 분류 체계
  • 자동 stale 라벨로 누락 보완

부정

  • 2단계 통과 latency ↑ — Slack → Issue → 본인 review → ready-to-ingest → PR → merge. 분 단위 → 시간·일 단위 가능
  • Issue 라벨·코멘트 컨벤션이 잘못 사용되면 봇이 잘못 트리거. 라벨 일관성 모니터링 필요
  • 봇·Issue·GitHub Action·시크릿 운영 부담 (ADR-0014에서 구체화). 인프라 초기 비용 ↑
  • 봇 자동 분류 LLM이 카테고리 잘못 판정 시 본인이 라벨 매번 수정 (false positive 누적 위험)
  • Slack 알림 noise — #wiki-notify 채널이 자주 울리면 본인 알림 피로

Alternatives 거부

옵션 평가
Slack 이모지 1개로 PR merge까지 자동 (검토했던 안) ❌ 환각·오해 위험. wiki 반영은 의사결정 누적이라 review 게이트 필수
본인이 hub (ADR-0012 D1 그대로) ❌ 사용자 명시 거부. 본인 일상 부담 ↑
GitHub Issue 게이트 없이 PR 자동 머지 ❌ Issue가 의사결정 트래커 역할 — 빼면 사유 휘발. 6개월 후 "왜 이 변경?" 답 불가
Slack 스레드 자체를 의사결정 트래커로 ❌ Slack 메시지는 검색·라벨·자동화 약함. 무료 플랜 90일 archive 한계. PII 제어 어려움
모든 wiki 변경에 사람 직접 작성 ❌ ADR-0011 LLM=librarian 폐기. 시간 부담 ↑
디자이너·마케터도 본 ADR에 포함 ❌ 워크플로 미정 — ADR-0015로 분리 (사용자 확정)
Granola·Otter·Fireflies 자동 transcript 즉시 도입 ❌ 사용자 현재 도구는 수동 메모 (Notion/Slack). 별도 라운드 평가

향후 검토 항목

  1. ADR-0014 자동화 인프라 디자인
  2. Slack bot 라이브러리 비교 (Slack Bolt / Workflow Builder / Zapier·Make / n8n)
  3. GitHub Action 구조 (.github/workflows/wiki-ingest-from-issue.yml)
  4. Issue 라벨 컨벤션 + 자동 라벨링·stale·close 로직
  5. 시크릿: Slack bot token, GitHub PAT (issues:write + contents:write), Notion API
  6. 비용 추정 (월 Slack bot 호스팅, Claude API, GitHub Action 분, Issue·PR 수)
  7. 보안: Slack 입력 → GitHub 권한 escalation 차단, PII auto-redact (NIST AI RMF)
  8. rate limit·timeout·재시도 정책
  9. ADR-0015 디자이너·마케터 워크플로 — 같은 Slack→Issue 2단계 적용 가능성 확인
  10. PR template 체크박스 (별도 가벼운 라운드 — 개발자 워크플로 보강)
  11. Claude Code Hook 본인 적용 (PostToolUse Edit) — 본인 코드 작업 시 관련 wiki surface

Status

  • 2026-05-25: accepted

Date

2026-05-25