From 6d3da8fb9418c0ab82a8287416911e01b71a206c Mon Sep 17 00:00:00 2001
From: Claude-51124 <claude@51124.local>
Date: Wed, 17 Dec 2025 00:05:39 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20Add=20Slack=20API=20=ED=98=B8=EC=B6=9C?=
 =?UTF-8?q?=20=EC=9B=90=EC=B9=99=20=EB=B0=8F=20=ED=85=8C=EC=8A=A4=ED=8A=B8?=
 =?UTF-8?q?=20=EC=9B=90=EC=B9=99=20(thread=5Fts=20=EC=B2=98=EB=A6=AC,=20?=
 =?UTF-8?q?=EC=8B=A4=EC=A0=9C=20=ED=85=8C=EC=8A=A4=ED=8A=B8=20=ED=95=84?=
 =?UTF-8?q?=EC=88=98)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../311_FastAPI_구조_원칙.md              | 42 ++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)

diff --git a/book/300_architecture/311_FastAPI_구조_원칙.md b/book/300_architecture/311_FastAPI_구조_원칙.md
index 763e5cc..e9f90ea 100644
--- a/book/300_architecture/311_FastAPI_구조_원칙.md
+++ b/book/300_architecture/311_FastAPI_구조_원칙.md
@@ -279,7 +279,47 @@ utils
 - 프로덕션 환경에서 표준적인 배포 방식
 - 백엔드와 웹서버의 명확한 역할 분리
 
-## 16. 모범 사례 참고
+## 16. Slack API 호출 원칙
+
+### 필수 원칙
+- **skill-slack API 사용**: rb8001에서 Slack API 호출 시 반드시 skill-slack HTTP API 사용
+- **WebClient 직접 호출 금지**: `slack_sdk.WebClient`를 rb8001 코드에서 직접 사용하지 않음
+- **아키텍처 준수**: rb8001(brain) → skill-slack(hand) 위임 구조 유지
+
+### thread_ts 처리 규칙
+- **조건부 포함**: `thread_ts`는 유효한 값(truthy)일 때만 payload에 포함
+- **None/빈 문자열 제외**: `None`, `""` 등 falsy 값일 때는 payload에 포함하지 않음 (invalid_thread_ts 에러 방지)
+- **올바른 예시**:
+  ```python
+  payload = {"channel": channel, "text": text}
+  if message_ts:  # None이나 빈 문자열이면 포함 안 함
+      payload["thread_ts"] = message_ts
+  ```
+- **잘못된 예시**:
+  ```python
+  payload = {"channel": channel, "text": text, "thread_ts": message_ts}  # message_ts가 None이면 에러
+  ```
+
+### Slack 메시지 업데이트 vs 새 메시지
+- **원본 메시지 업데이트**: 인터랙티브 버튼 응답 등 기존 메시지를 수정해야 할 때는 `/api/v1/update` 사용
+- **새 메시지**: 별도의 새 메시지를 보낼 때는 `/api/v1/send` 사용
+- **예시**: "예/아니오" 버튼에 대한 응답은 원본 메시지를 업데이트하여 버튼을 제거하고 결과 표시
+
+## 17. 테스트 원칙
+
+### 실제 테스트 필수
+- **코드 수정 후 실제 테스트**: 코드만 수정하고 실제 테스트를 수행하지 않으면 안 됨
+- **추측 금지**: "아마 작동할 것이다" 같은 추측 대신 실제 실행으로 검증
+- **테스트 방법**: 
+  - API: `curl`로 직접 호출하여 응답 확인
+  - Slack 기능: 실제 Slack에서 버튼 클릭, 메시지 전송 등 직접 테스트
+  - DB 저장: API 응답뿐만 아니라 DB 직접 조회로 최종 확인
+
+### Git 작업 규칙
+- **각 폴더별 확인**: Git 커밋 히스토리는 각 프로젝트 폴더에서 개별적으로 확인
+- **루트에서 확인 금지**: 루트 디렉토리에서 git log를 확인하려고 하지 않음 (각 폴더는 별도 리포지토리)
+
+## 18. 모범 사례 참고
 
 본 문서는 FastAPI 커뮤니티의 다음 모범 사례를 반영하였습니다: