Sharing Backend Work

같은 사실이라도 읽는 사람이 바뀌면 다른 글이 됩니다. 청중을 먼저 정하고, 그 청중이 글을 읽은 뒤 스스로 판단할 수 있도록 구성 요소를 채웁니다.

Local Background

채널 이름은 이 문서에 적지 않고 skills/sharing-backend-work/background.local.md에서 해석합니다. 그 파일은 의도적으로 gitignore되며, 추적되는 템플릿은 skills/sharing-backend-work/background.local.example.md입니다. {전사 채널}, {백엔드 채널}, {배포 기록 채널}, {자동 알림 채널}은 그 파일이 정의하는 역할 이름입니다. 로컬 배경이 없으면 채널을 추측하지 말고 사용자에게 이름을 확인합니다.

경계

• 팀 Slack 공유 글에만 적용합니다. GitLab 이슈 본문, MR description, Wiki 문서에는 적용하지 않습니다.
• 같은 글을 두 채널에 복사하지 않습니다. 조사나 장애 원문을 두 채널에 걸쳐 공유할 때는 {전사 채널}에 결론과 영향만 올리고 {백엔드 채널} 원문을 링크합니다.
• {전사 채널} 글의 상세 링크는 GitLab 이슈나 Swagger 문서입니다. 앱과 웹 담당자가 읽어야 하는 상세를 {백엔드 채널}로 보내지 않습니다.
• 로컬 배경의 자동 알림 채널은 자동 알림이 쌓이는 채널입니다. 사람이 공유 글을 쓰지 않습니다.
• 확인하지 않은 추정을 확정 사실로 쓰지 않습니다. 확인하지 못한 항목은 확인이 필요한 부분에 남깁니다.
• 사용자가 전송을 지시하지 않으면 초안만 제시하고 보내지 않습니다.

1. 청중을 먼저 정한다

"이 글을 읽은 사람이 무엇을 할 수 있어야 하는가"에 답하면 청중이 정해집니다.

청중	채널	읽고 나서 하는 일	그 판단에 필요한 재료
A. 전사	{전사 채널}	자기 플랫폼이 대응할지 결정	엔드포인트, 파라미터, status/code/message, 하위 호환 여부
B. 동료 백엔드	{백엔드 채널}	검증하거나 이어받기	file:line, 수치, 재현 절차, 이슈·MR 링크
C. 리드	{백엔드 채널} + 멘션	방향 결정	증거 체인, 배제한 가설, 추천이 붙은 선택지

A에는 내부 구현 경로, 클러스터 이름, MR 번호를 쓰지 않습니다. 같은 사실을 클라이언트 계약의 언어로 바꿔 씁니다. 배포 완료 알림은 예외로 MR 링크를 답니다.

배포 시각 기록만 남길 때는 {배포 기록 채널}를 씁니다.

2. 첫 줄에 라벨과 대상을 붙인다

[API] [공지] [배포] [요청] [분석] [변경] [승인] [장애] [보고] 중 하나로 시작하고, 대상 환경이나 서비스를 함께 적습니다. 예: [변경] Prometheus 메트릭 수집 설정 · prod.

3. 청중별 구성 요소

각 청중의 글은 아래 부분들로, 이 순서로 이루어집니다.

A. 전사 ({전사 채널})

1. 라벨과 제목. 이슈 번호를 괄호에 답니다. 예: (#1234).
2. 한 줄 요약. 무엇이 어떻게 바뀌는지와, 클라이언트가 해야 할 일을 함께 씁니다.
3. 대상 엔드포인트. METHOD /경로를 빠짐없이 나열합니다. PUT /collections/:id/v2 같은 변형 경로도 함께 적습니다.
4. 계약 본문. 바뀌는 종류에 따라 다릅니다.
   • 응답이나 에러가 늘면 status, code, message 셋을 모두 적습니다. message는 유저에게 그대로 노출 가능한 문구로 씁니다.
   • 파라미터나 필드가 늘면 형식과 예시를 적고, 항목마다 미전달 시 기존과 동일하게 동작 (하위 호환)처럼 하위 호환 여부를 판정합니다.
5. 판정 규칙. 서버가 값을 정규화하면 같은 값으로 판정되는 차이와 다른 값으로 판정되는 차이를 나눠 적습니다.
6. 기존 동작과의 차이. 이전: {동작} → 유저는 {결과} / 이후: {동작}으로 대비시킵니다. 응답 변경에서는 이 칸이 하위 호환 판정을 대신합니다.
7. 함께 바뀌는 동작 (에러 아님, 참고용). 에러는 아니지만 클라이언트가 알아야 할 부수 변화입니다. 각 플랫폼이 자기 처리 방식을 정하는 재료가 되므로 생략하면 스레드에서 되묻습니다.
8. 클라이언트 대응 사항. 플랫폼별로 할 일을 지정하거나, 할 일이 없으면 Client 대응 사항은 없습니다! 한 줄로 끝냅니다. 필요하면, 필요하시면처럼 판단을 상대에게 넘기는 표현 대신 앱에서 409 핸들링 확인 부탁드립니다처럼 행동을 지정합니다. 두 표현을 한 글에 섞지 않습니다.
9. 상세 링크와 서브팀 멘션. 상세는 GitLab 이슈나 Swagger를 답니다.

배포 일정은 시각이 확정됐을 때만 적습니다. 클라이언트용과 어드민용 스펙이 함께 바뀌면 두 글로 나눠 각각 다른 이슈를 답니다.

B. 동료 백엔드 ({백엔드 채널})

1. 라벨과 제목, 대상.
2. 결론 한 줄. 결론부터 말씀드리면으로 시작합니다.
3. 근거 불릿 3~5개. 수치는 이전 → 이후로, 코드는 path/file.ts:줄번호로 씁니다.
4. 영향. 바뀐 것과 바뀌지 않은 것을 함께 적습니다.
5. 조치와 담당자, 기한. 할 일이 없으면 추가 조치 필요 없음이라고 씁니다.
6. 확인이 필요한 부분. 없으면 생략합니다.
7. 이슈, MR, 런북 링크.

본문이 15줄을 넘으면 Canvas로 옮기고 요약과 링크만 남깁니다.

C. 리드 보고 (멘션 + 코드펜스)

1. 결론: 한 줄 판정.
2. 증거 체인. 번호를 붙여 무엇을 조회해 어떤 수치를 얻었는지 적습니다. 조치와 대응은 여기에 넣지 않습니다.
3. 배제된 것. 검토하고 아니라고 판정한 원인을 근거 수치와 함께 적습니다.
4. 해석. 증거가 가리키는 의미와 서비스 영향을 적습니다.
5. 권장 대응. 번호를 붙이고 근본책을 1번, 임시책을 2번에 둡니다. 어느 쪽을 권하는지 밝힙니다.
6. 조사 중 수행한 쓰기 작업 여부.

전체를 코드펜스로 감싸 채널 스크롤에서 분리합니다.

4. 공통 규칙

• Slack 볼드는 별표 하나입니다. *강조*로 씁니다.
• 불릿은 •, 하위 불릿은 ◦를 씁니다.
• 계약 공지와 결과 공유는 첫 줄부터 본론으로 들어갑니다. 협의를 요청하는 글에서는 짧은 인사 한 줄까지가 팀 관행입니다. 맺음말은 어느 쪽에도 붙이지 않습니다.
• 실제 JSON 응답과 로그는 코드블록으로 붙입니다.
• 요청과 질문을 섞을 때는 질문에 (확인 필요)를 붙여 구분합니다.

흔한 실수

실수	고침
청중이 달라도 같은 글을 쓴다	1번 표에서 청중을 먼저 정하고 그 구성 요소만 채운다
전사 채널에 file:line과 MR 번호를 쓴다	엔드포인트와 status/code로 바꿔 쓴다
하위 호환을 "기본값 false"로만 쓴다	항목마다 하위 호환인지 판정해 명시한다
에러 코드만 적고 판정 규칙을 빠뜨린다	같은 값으로 취급되는 차이와 아닌 차이를 나눠 적는다
부수 변화를 생략한다	함께 바뀌는 동작 (에러 아님, 참고용)으로 남겨 각 플랫폼이 판단하게 한다
클라이언트 대응을 "필요하면 반영해 주세요"로 넘긴다	플랫폼별 행동을 지정하거나 없다고 한 줄로 끝낸다
전사 채널 글의 상세를 백엔드 채널로 보낸다	GitLab 이슈나 Swagger를 단다
리드에게 선택지만 나열한다	근본책과 임시책으로 순위를 매기고 추천을 밝힌다
원인을 단정하되 확인 방법이 없다	증거 체인에 조회한 대상과 수치를 적는다
**볼드**를 쓴다	Slack에서는 *볼드*다

필요한 청중의 채움 템플릿과 사례만 읽습니다:

• 전사 채널
• 동료 백엔드
• 리드 보고
• 같은 사건을 세 청중에게 전달하는 비교

전체 예시 인덱스는 기존 진입점으로 유지합니다.