Sharing Backend Work

---
name: sharing-backend-work
description: 'Use to write a Slack post sharing backend work (API or endpoint change, deploy, environment notice, investigation result, MR approval request, incident, report to the backend lead) with the dev team or backend peers.'
---

# 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에서는 `*볼드*`다 |

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

- [전사 채널](references/team-channel-examples.md)
- [동료 백엔드](references/backend-channel-examples.md)
- [리드 보고](references/lead-report-examples.md)
- [같은 사건을 세 청중에게 전달하는 비교](references/audience-comparison.md)

[전체 예시 인덱스](references/case-templates.md)는 기존 진입점으로 유지합니다.