refactor(slack): 응답 계층 예시를 다양화한다

container/skills/slack-formatting/SKILL.md

@@ -5,20 +5,11 @@ description: Slack 채널·DM·thread에서 사용자에게 보일 응답을 작
 
 # Slack 응답 디자인
 
-Slack에서는 답을 먼저 말하고, 한 번에 읽히는 평문을 기본으로 한다. UI는 이해나 행동을 실제로 개선할 때만 사용한다.
-
-규칙이 충돌하면 다음 순서를 따른다.
-
-1. 정확성·안전·권한
-2. 질문에 대한 직접 답
-3. 사용자의 판단과 다음 행동
-4. 빠른 스캔·가독성·접근성
-5. 간결성
-6. 장식적 표현
+아래 예시는 복사할 고정 양식이 아니다. 현재 답과 정보 관계가 가장 가까운 예시를 고른 뒤, 항목 수·label·emoji·문장 구조는 실제 내용에 맞춘다. 정확성·안전·권한과 사용자의 판단에 필요한 내용은 형식을 줄이기 위해 생략하지 않는다.
 
 ## 출력 형태
 
-한 응답에서 핵심 정보를 표현하는 주 형식은 하나만 선택한다. 파일과 링크는 원문이나 근거를 제공하는 보조 전달물로 함께 사용할 수 있다. 같은 내용을 일반 메시지·카드·파일 설명에 반복하지 않는다.
+평문 하나를 기본으로 하고, 한 응답의 주 형식은 하나만 선택한다. 링크와 파일은 근거·원문을 위한 보조 전달물이다.
 
 | 상황                                       | 주 출력 형태                              |
 | ------------------------------------------ | ----------------------------------------- |
@@ -27,115 +18,181 @@ Slack에서는 답을 먼저 말하고, 한 번에 읽히는 평문을 기본으
 | 자유 형식 답변이 필요한 질문               | 일반 메시지로 한 문장 질문                |
 | 서로 겹치지 않는 제한된 선택지가 꼭 필요함 | `ask_user_question`                       |
 | 짧은 상태·맥락·행동을 한 단위로 훑어야 함  | `send_card`                               |
+| 복잡한 조사·결정·장애 보고                 | 의미별 묶음과 2단계 계층의 일반 메시지    |
 | 긴 분석·큰 표·로그·코드·보고서             | Slack에는 결론과 행동, 원문은 `send_file` |
 
-형태는 길이나 주제명이 아니라 정보 사이의 관계와 사용자가 할 일로 결정한다. 카드와 목록은 압축한 계층을 보여주는 수단이지 원시 정보를 모두 담는 그릇이 아니다.
+## 최소 계약
 
-## 콘텐츠 작성
+- 첫 문장에 답·결과·상태·다음 행동 중 지금 가장 중요한 것을 둔다. 결론을 끝에서 반복하지 않는다.
+- `container/CLAUDE.md`의 친근한 해요체를 유지하고, 고정된 판정 label이나 명사형 보고서 문체를 반복하지 않는다.
+- 공통 상태는 한 번 말하고, 목록은 차이·예외·순서가 읽는 속도를 높일 때만 쓴다. emoji는 `✅` 정상, `⚠️` 주의, `❌` 실패, `⏳` 대기처럼 텍스트 의미를 보조할 때만 쓴다.
+- 복잡한 결과는 첫 문장만 읽어도 판정을 알 수 있게 한다. 이후에는 역할이 다른 정보를 2~4개로 묶고, 근거는 그 아래 한 단계나 링크·파일로 내린다.
+- 일반 메시지는 표준 Markdown을 사용한다. raw `mrkdwn`을 만들지 않고, 외부 문자열·로그·코드는 의도하지 않은 mention이나 서식이 생기지 않게 분리한다.
+- `send_card`와 `ask_user_question`은 실제 schema만 사용한다. 카드는 정보를 보여주고 URL 행동만 제공하며, 답을 받아야 하는 제한된 선택은 질문으로 보낸다.
+- 네이티브 typing을 기본으로 하고, 오래 걸리는 작업의 의미 있는 단계만 `set_status`로 알린다. 같은 접수 상태를 reaction·status·메시지로 겹치지 않는다.
+- 도구 성공을 확인하기 전에 완료를 선언하지 않는다. UI 전송이 즉시 실패하면 핵심만 평문으로 한 번 전달하고, 사용자가 접근할 수 없는 내부 경로는 제시하지 않는다.
 
-- 첫 문장에 답, 결과, 현재 상태 또는 다음 행동을 둔다.
-- 서론, 의례적인 인사, 요청 재진술, 내부 작업 과정, 결론 반복을 생략한다.
-- 서로 다른 주장이나 행동을 한 문장에 과도하게 겹치지 않는다. 문단은 모바일에서 한눈에 읽히는 길이로 유지한다.
-- `container/CLAUDE.md`의 공통 높임법 규칙을 유지하면서 사용자의 어휘와 현재 thread의 흐름을 잇는다. 사용자가 요청하지 않았다면 갑자기 보고서체나 반말로 바꾸지 않는다.
-- 결론 다음에는 판단이나 행동에 필요한 내용만 두고, 근거와 상세는 필요할 때만 펼친다.
-- 영향, 위험, 차단 요인, 불확실성, 필수 행동은 길이를 줄이려고 누락하지 않는다.
-- 여러 항목에 같은 판정이 적용되면 공통 상태는 상위에서 한 번 말하고, 각 항목에는 차이·예외·결정을 바꾸는 근거만 둔다.
-- 원시 로그, 긴 경로, 예외명, 재현·감사용 상세는 파일이나 설명형 링크로 분리한다.
+## 응답 예시
 
-둘 이상의 병렬 항목을 문장보다 빠르게 훑을 수 있을 때 목록을 쓴다. 한두 개의 짧은 내용을 관성적으로 목록으로 만들지는 않는다. 번호 목록은 순서가 중요할 때, task list는 사용자가 실제로 추적할 작업에만 쓴다. 작은 비교만 표로 만들고 모바일에서 읽기 어려우면 목록으로 바꾼다. 섹션 수나 문장 수보다 정확성과 자연스러움을 우선한다.
+### 한 가지 답
 
-## Markdown 계약
+```markdown
+아직 배포 전이에요. 테스트는 끝났고 운영 반영만 남았습니다.
+```
 
-일반 메시지는 AimClaw adapter가 지원하는 표준 Markdown으로 작성한다. Slack의 raw `mrkdwn` 문법을 직접 흉내 내지 않는다.
+또는:
 
-````markdown
-**중요한 결론**
+```markdown
+반영했어요. 다음 배포부터 새 규칙으로 답합니다.
+```
+
+제목, 목록, 상태 emoji가 없어도 답이 충분하면 여기서 끝낸다.
+
+### 후속 코드 검토
+
+```markdown
+코드 수준의 설명은 맞아요. 다만 실제 계정이 이 조건에 해당했는지는 아직 확인되지 않았습니다.
 
-- 병렬 항목
-- [관련 문서](https://example.com)
+**확인된 흐름**
 
-```ts
-const ready = true;
+- **이메일 변경**
+  - 화면은 대상 플랜에 연결 중단 경고를 보여줘요. [화면 코드](https://example.com/frontend)
+  - API는 사용자 이메일만 바꿔요. [변경 로직](https://example.com/update)
+- **이메일 기반 연결**
+  - 관리자는 회사의 관리자 이메일과 정확히 일치해야 해요.
+  - 플랜 사용자는 이메일과 이름이 모두 일치해야 해요. [조회 로직](https://example.com/matching)
+
+**남은 확인**
+
+- 해당 계정의 실제 회사·플랜 데이터가 불일치했는지는 DB 조회가 필요해요.
+
+확인 기준: [commit](https://example.com/commit)
+```
+
+원시 method chain을 나열하지 않고 `변경`과 `연결`이라는 상위 흐름으로 묶는다. 미확인 범위는 확인된 근거 아래에 섞지 않는다.
+
+### 모두 같은 상태
+
+```markdown
+Slack 연결, 서비스, provider 설정은 모두 정상이에요. 지금 필요한 조치는 없습니다.
 ```
-````
 
-- `send_card`와 `ask_user_question`의 각 필드는 실제 도구 schema를 따른다. 일반 메시지와 같은 Markdown 처리를 임의로 가정하지 않는다.
-- Markdown 지원 여부가 불확실하면 평문, 줄바꿈, 단순 bullet, code block을 사용한다.
-- header는 실제로 긴 메시지의 섹션을 나눌 때만 쓰고 H1~H6의 시각적 크기 차이에 의존하지 않는다.
-- 사용자 입력, 로그, 외부 응답을 그대로 mention이나 Markdown으로 실행하지 않는다. 의도하지 않은 알림이나 서식이 생길 문자열은 code block이나 inline code로 분리한다.
-- `@channel`, `@here`, 개인 mention은 확인된 대상에게 실제 알림이 필요할 때만 생성한다.
-- 자동 분할에 기대지 않는다. 긴 결과는 판단에 필요한 요약과 원문 파일로 나눈다.
+항목마다 `✅`와 `정상`을 되풀이하지 않는다. 서로 다른 증거를 꼭 비교해야 할 때만 emoji 없는 목록이나 근거 링크를 덧붙인다.
+
+### 상태가 섞인 점검
+
+```markdown
+결제와 알림은 정상이에요. 이미지 업로드만 조치가 필요합니다.
 
-## 카드, 질문, 파일
+- 결제 webhook은 최근 24시간 실패가 없었어요.
+- 알림 지연은 p95 1.2초로 평소 범위예요.
+- ⚠️ 이미지 업로드 재시도율이 8%로 올랐어요. [관련 로그](https://example.com/logs)
 
-`send_card`는 Slack 네이티브 card block을 직접 작성하는 API가 아니라 AimClaw이 플랫폼별 UI로 변환하는 카드 추상화다. 실제 도구 schema에 정의된 필드만 사용한다.
+업로드 실패 원인부터 확인하는 게 좋겠어요.
+```
 
-- title은 짧게, subtitle은 시간·환경·범위 같은 보조 맥락에만 쓴다.
-- description에는 결론이나 상태를 한두 문장으로 쓴다.
-- fields는 상태·담당자·버전처럼 비교할 짧은 key-value 정보에 쓴다.
-- children에는 핵심 근거만 두고, 이미지는 의미를 설명하는 `alt`를 포함한다.
-- actions는 URL 버튼만 지원한다. 답을 반환해야 하는 선택에는 `ask_user_question`을 쓴다.
-- `fallbackText`만 읽어도 핵심 내용과 다음 행동을 이해할 수 있게 쓴다.
+예외만 시각적으로 두드러지게 하고, 모든 줄을 같은 배지·label 틀에 넣지 않는다.
 
-`ask_user_question`은 선택에 따라 결과나 실행 범위가 달라지고, 안전하게 기본값을 추론할 수 없거나 정책상 명시적 확인이 필요할 때 사용한다. 선택지는 서로 겹치지 않는 적은 수로 제한한다. 자유 형식 설명·날짜·수치·파일을 받아야 하면 일반 메시지로 묻는다. 되돌릴 수 없는 행동은 실행과 취소 선택을 함께 제시하고, 사용자가 이미 선택 기준이나 명시적 승인을 줬다면 같은 결정을 다시 묻지 않는다.
+### 병렬 영향
 
-긴 결과를 파일로 보낼 때도 Slack 본문에는 한 줄 결론, 중요한 위험, 사용자의 다음 행동을 남긴다.
+```markdown
+이번 변경으로 사용자가 체감하는 차이는 세 가지예요.
 
-## 진행 표시와 reaction
+- 새 요청부터 응답이 thread에 모입니다.
+- 처리 중에는 별도 메시지 대신 typing 상태가 보입니다.
+- 실패하면 기존 서비스가 유지되는지도 함께 알려줍니다.
+```
 
-AimClaw 호스트가 제공하는 네이티브 typing 또는 접수 표시를 기본으로 보고, 같은 의미의 reaction이나 “확인 중” 메시지를 추가하지 않는다.
+상태 판정이 아니라 서로 다른 영향을 설명하므로 emoji를 붙이지 않는다.
 
-- 실제 대기가 긴 외부 조회·설치·빌드·테스트가 시작되면 `set_status`로 짧은 현재 단계를 알린다.
-- 단계가 사용자 관점에서 의미 있게 바뀔 때만 status를 갱신한다. 도구 호출마다 바꾸지 않는다.
-- 사용자가 바로 활용할 부분 결과나 알아야 할 단계 변화가 있을 때만 중간 메시지를 한 번 보낸다.
-- 앞선 전송 결과에서 수정 가능한 message ID를 받은 경우에만 `edit_message`로 갱신한다.
-- `add_reaction`은 동의, 승인, 완료처럼 별도 설명이 필요 없는 최종 확인에 쓴다. 중요한 결과, 실패, 판단 근거를 reaction만으로 전달하지 않는다.
-- `thumbs_up`은 동의나 승인 확인, `white_check_mark`는 완료 여부만 전달할 때 쓴다.
+### 설계 선택과 도입 조건
 
-진행 status와 접수 메시지를 동시에 사용하지 않는다.
+```markdown
+지금은 A안이 더 적합해요. 기존 흐름을 유지하면서 필요한 부분만 바꿀 수 있기 때문입니다.
 
-## 의미 기반 시각 표현
+**현재 조건**
 
-본문에서 상태, 위험, 진행 여부를 빠르게 구분하는 emoji는 장식이 아니라 정보 표현으로 취급한다.
+- 운영 에이전트는 하나이고 팀별 동작 차이도 아직 없어요.
+- A안은 이 조건에 잘 맞아요.
+  - 변경 범위가 작고 기존 배포 흐름을 그대로 써요.
+  - 별도 동기화 계층을 운영하지 않아도 돼요.
 
-- 상태를 비교하는 목록에서는 항목마다 스캔이 빨라질 때 상태 emoji를 사용한다. 한 항목에는 하나만 쓰고, 같은 응답에서는 같은 emoji에 같은 의미를 부여한다.
-- 기본 의미는 `✅` 정상·완료, `⚠️` 주의·조치 필요, `❌` 실패·차단, `⏳` 진행·대기로 유지한다.
-- emoji만으로 상태를 전달하지 않고 짧은 텍스트 상태나 설명을 함께 둔다.
-- 모든 항목의 상태가 같으면 공통 상태 옆에 한 번만 표현한다.
-- 일반 설명이나 모든 bullet에 emoji를 장식적으로 붙이지 않는다. 축하·감정 표현은 현재 대화의 어조에 자연스러울 때만 쓴다.
+**B안이 필요해지는 조건**
 
-## 도구 실패와 접근성
+- 팀마다 독립된 정책이 반복해서 생길 때
+- 서로 다른 배포 주기나 권한 경계가 필요할 때
 
-- 도구가 없거나 호출이 전송 전에 즉시 오류를 반환하면 평문 메시지로 답한다.
-- 카드 호출이 즉시 실패하면 핵심 내용을 일반 메시지로 한 번 전달한다.
-- 선택 UI를 만들기 전에 호출이 실패하면 번호 목록으로 묻고, 메시지 수정이 실패하면 중복을 피한 새 최종 메시지를 보낸다.
-- 파일 전송이 실패하면 요약과 실패 사실을 알리고 사용자가 실제로 접근할 수 있다고 확인된 링크나 경로만 제시한다. 내부 경로나 임시 저장 위치는 노출하지 않는다.
-- 도구가 성공을 반환했거나 전송 대기 상태라면 실패를 추측해 같은 내용을 다시 보내지 않는다.
-- 도구의 성공 응답을 확인하기 전에는 완료했다고 말하지 않고, 실패한 호출을 무한 재시도하지 않는다.
-- 버튼과 링크 label은 눌렀을 때 일어나는 행동을 말한다. `여기`, `클릭` 같은 label은 피한다.
+지금은 A안으로 적용하고, 위 조건이 실제로 생기면 B안을 다시 검토하면 됩니다.
+```
 
-## 예시
+장단점을 같은 무게로 모두 펼치지 않고, 현재 결정을 지지하는 조건과 결정을 바꾸는 조건을 분리한다.
 
-간단한 완료 답변:
+### 장애 상태와 복구 계층
 
 ```markdown
-반영했어요. 다음 배포부터 새 규칙으로 답합니다.
+전체 장애는 해소됐고 이미지 업로드만 지연되고 있어요. 일반 문서 조회와 결제에는 영향이 없습니다.
+
+**사용자 영향**
+
+- 문서 조회·결제: 정상
+- 이미지 업로드: 처리 시간이 평소보다 길고 일부 요청은 재시도 중
+
+**복구 상태**
+
+- 완료
+  - 오류를 만든 새 worker 배포를 되돌렸어요.
+  - 대기열 증가는 멈췄어요.
+- 진행 중
+  - 남은 요청 약 1,200건을 순서대로 처리하고 있어요.
+  - 현재 속도라면 약 20분이 더 필요해요.
+
+다음 갱신은 대기열이 절반 이하로 줄거나 예상 시간이 달라질 때 남길게요.
 ```
 
-여러 상태가 섞인 점검 결과:
+서비스 전체 상태, 사용자가 겪는 예외, 복구 세부사항을 서로 다른 층에 둔다. 개별 로그와 worker ID는 본문에서 제외한다.
+
+### 배포 준비도와 실행 순서
 
 ```markdown
-점검 3건 중 2건은 정상이고, 1건은 조치가 필요해요.
+지금 배포는 보류하는 게 맞아요. 결제 callback 회귀 한 건이 출시를 막고 있고, 나머지 핵심 경로는 통과했습니다.
+
+**배포를 막는 문제**
+
+- 결제 callback이 중복 처리될 수 있어요.
+  - 영향: 같은 주문에 완료 이벤트가 두 번 기록될 수 있어요.
+  - 해제 조건: 멱등성 수정 후 중복 callback 테스트 통과
+
+**통과한 범위**
 
-- ✅ **결제 webhook** · 정상 · 최근 24시간 실패 0건
-- ✅ **알림 발송** · 정상 · 지연 p95 1.2초
-- ⚠️ **이미지 업로드** · 조치 필요 · 재시도율 8%로 상승 · [관련 로그](https://example.com)
+- 인증·권한
+  - 관리자와 일반 사용자 시나리오 통과
+- 메시지 전달
+  - Slack thread 응답과 실패 fallback 통과
+- 데이터 변경
+  - 기존 주문 migration 검증 통과
 
-**다음:** 이미지 업로드 재시도율 상승 원인부터 확인하는 게 좋겠어요.
+**진행 순서**
+
+1. callback 멱등성 수정
+2. 결제 회귀 테스트 재실행
+3. 통과하면 staging smoke test 후 배포
 ```
 
-도구 선택 예:
+판정을 바꾸는 blocker는 상세히, 이미 통과한 범위는 도메인 단위로 압축한다. 전체 테스트 표와 로그는 `send_file`로 한 번 첨부한다.
+
+위 고밀도 예시들은 서로 다른 section label을 쓴다. `확인된 흐름`·`현재 조건`·`복구 상태` 같은 이름을 고정 template으로 복사하지 말고, 이번 답에서 정보가 맡는 역할에 맞춰 붙인다.
+
+### UI를 쓰는 경우
 
 - 사용자의 마지막 메시지가 단순한 동의나 감사이고 추가 정보가 필요하지 않다면 일반 메시지 대신 `thumbs_up` reaction만 추가한다.
 - 배포 범위를 선택해야만 진행할 수 있다면 `ask_user_question`으로 `스테이징`, `전체 배포`, `취소`를 제시한다.
-- 긴 분석은 Slack에 결론·영향·조치를 남기고 전체 로그와 근거는 `send_file`로 전달한다.
+- 짧은 상태·담당자·관련 링크를 한 덩어리로 훑는 편이 빠를 때만 `send_card`를 쓴다. `fallbackText`에는 결론과 행동을 함께 적는다.
+
+## 피할 표면 패턴
+
+| 반복하기 쉬운 형식                             | 바꿀 방향                                        |
+| ---------------------------------------------- | ------------------------------------------------ |
+| 모든 bullet에 같은 `✅`·굵은 label·명사형 판정 | 공통 판정은 첫 문장 한 번, 항목에는 차이만       |
+| 매번 `결론`·`근거`·`주의`·`다음` 섹션          | 실제로 다른 정보 덩어리만 문단이나 목록으로 분리 |
+| 긴 method chain과 경로를 본문에 나열           | 사람 언어로 요약하고 설명형 고정 링크로 이동     |
+| 평문·카드·파일 설명에 같은 내용을 복제         | 주 형식 하나와 필요한 근거 링크·원문만 유지      |