이슈 트리아지 — manuscript 인가 build 인가
같은 증상이 원고 문제일 수도, 빌드 깨짐일 수도 있다. 트리아지가 안전 장치다 — 잘못된 곳을 고치면 회귀가 누적된다.
라벨 컨벤션
| 라벨 | 의미 | 누가 붙이나 |
|---|---|---|
editorial | 진입 라벨 — 출판물에 대한 편집 요청 | 이슈 작성자 (또는 자동 라벨링) |
manuscript-fix | 트리아지 결과 — 원고 자체의 문제 | manuscript-architect (R-1) |
build-fix | 트리아지 결과 — 빌드/렌더링의 문제 | manuscript-architect (R-1) |
rejected | 트리아지 결과 — 재현 불가 / 오해 / 의도된 표현 | manuscript-architect (R-1) |
regression | (선택) 이전 fix 가 다른 곳을 깬 경우 | 후속 발견자 |
라벨 토글은 한 이슈에서 진입(
editorial) + 결과(manuscript-fix/build-fix/rejected) 두 개를 같이 유지한다. 진입 라벨을 떼지 않는다 — 통계용.
결정 트리
이슈 본문 + 첨부 스크린샷 정독
│
▼
대상 글의 원고 파일 (manuscript/articles/<>.md) 열기
│
├─ 같은 증상이 원고 본문에 보이나? ─── Yes ── manuscript-fix
│
└─ No
│
▼
로컬에서 copy-from-manuscript + 빌드 산출물 검사
│
├─ 산출물 (docs-docusaurus/build/) 에서 증상 재현 ── Yes ── build-fix
│
└─ No (라이브 사이트에서만 증상)
│
▼
브라우저 캐시 / CDN / Pages 가시성 문제 의심
│
├─ 캐시 강제 새로고침으로 사라짐 ── rejected (캐시)
│
└─ 그래도 남음 ── build-fix (CSS / 자산 누락 / asset 경로)
트리아지 시그널 표
Manuscript-fix 의 전형적 시그널
| 시그널 | 예시 |
|---|---|
| 본문 텍스트의 오탈자/번역 오류/사실 오류 | "테그 라이팅" → "테크 라이팅" |
| 잘못된 인용/링크 | URL 이 다른 문서를 가리킴 |
| 잘못된 코드 예시 | npm istall 오탈자, 작동 안 하는 명령 |
| 약어 정의 누락 | "PR" 첫 등장에서 풀어쓰기 없음 (검수 회귀) |
| 자리표시자 잔존 | [[TYPE: ...]] 가 사이트에 노출 |
| 잘못된 이미지 alt | 이미지와 alt 가 어긋남 |
Build-fix 의 전형적 시그널
| 시그널 | 예시 |
|---|---|
| 사이트에서 이미지 404 | 원고에는 정확한 경로지만 copy-from-manuscript 가 누락 |
| 페이지 자체 404 | sidebar 설정 오류, routeBasePath 충돌 |
| MDX 컴파일 오류 | 본문의 <> / {} escape 실패 |
| 깨진 사이드바 정렬 | order ↔ sidebar_position 매핑 실패 |
| 코드 블록 하이라이팅 깨짐 | prism 언어 식별자 오류 |
| 다크모드에서만 깨지는 색상 | custom.css 의 다크 토큰 누락 |
| 한글 슬러그 인코딩 깨짐 | Docusaurus permalink 처리 |
Rejected 의 시그널
| 시그널 | 조치 |
|---|---|
| 재현 불가 — 환경 의존 (특정 브라우저/모바일) | "이슈 보존, 재현 정보 요청" 코멘트 후 보류 |
| 의도된 표현 (예: 인용된 영문은 일부러 italics) | "의도된 표현 — 본문 의도 설명" 코멘트 |
| 스타일 가이드 변경 요청 | manuscript-architect 가 writing-style-guide.md 갱신 검토로 전환 |
GitHub 명령 컨벤션
트리아지 명령 (manuscript-architect)
# 이슈 목록 확인
gh issue list --label editorial --state open
# 이슈 상세 보기
gh issue view <num> --json title,body,labels,url,author
# 트리아지 결과 적용 — manuscript-fix 인 경우
gh issue edit <num> --add-label manuscript-fix
gh issue comment <num> --body "트리아지: manuscript-fix.
대상 원고: manuscript/articles/<order>-<slug>.md
원고 본문 L<번호> 에 같은 증상 확인됨. R-2A 진행 예정."
# 트리아지 결과 적용 — build-fix 인 경우
gh issue edit <num> --add-label build-fix
gh issue comment <num> --body "트리아지: build-fix.
원고는 정상. 로컬 빌드 산출물에서 증상 재현됨.
docs-docusaurus/<위치> 수정 예정. R-2B 진행."
# 반려
gh issue edit <num> --add-label rejected
gh issue comment <num> --body "트리아지: rejected.
이유: <재현 불가 / 의도된 표현 / 스타일 가이드 변경 안건>"
Close 명령 (docs-publisher, 배포 후)
gh issue close <num> --comment "수정 적용 — vX.Y.Z 배포 완료.
사이트 확인 부탁드립니다.
변경 커밋: <commit-sha>
태그: https://github.com/<owner>/<repo>/releases/tag/vX.Y.Z"
안전 원칙
- manuscript-fix 와 build-fix 를 한 PATCH 에 섞지 않는다 — 회귀 발생 시 원인 식별이 어려워진다
- manuscript-fix 시 status: published 유지 — 롤백이 아니라 같은 글의 새 리비전
- build-fix 후 회귀 점검 의무 — 다른 글의 렌더링도 깨지지 않는지 grep + 로컬 빌드
- rejected 도 반드시 코멘트로 이유 남기기 — 같은 이슈 재발 방지
- 재현 불가 시 보류 + 정보 요청 — 무리한 추정 fix 금지
- 트리아지 라벨은 한 이슈당 1개 (manuscript-fix / build-fix / rejected 중 하나)
통계로 누적되는 학습
라벨 토글이 일관되면 정원지기(tamer)가 주기적으로 패턴 분석 가능:
gh issue list --label manuscript-fix --state closed— 검수에서 놓친 패턴gh issue list --label build-fix --state closed— 빌드 약점 패턴- 전체 비율 → manuscript 측 강화? build 측 강화? 가 데이터로 잡힘
트리아지 라벨은 그 자체가 다음 사이클의 우선순위를 알려주는 신호다.