DOCS/troubleshooting/251023_code_alignment_with_rules.md

[트러블슈팅] CLAUDE 코드 작성 원칙 정렬 체크리스트 (2025-10-23)

본 문서는 현재 코드가 CLAUDE 원칙(FP 100%, 하드코딩 0%, 계층 분리, UUID 중심, 비동기 안전)에 어긋나는 지점을 정리하고, 수정 시 참고할 구체 체크리스트를 제공합니다. 실제 코드 수정은 포함하지 않습니다.

• 비동기 이벤트 루프 생성 금지 위반
  • rb8001/app/core/emotion/emotion_classifier.py:52 — 동기 predict()가 asyncio.new_event_loop() 사용. 비동기 API 통일 또는 안전 래핑 필요.
• Slack SDK 동기 호출 사용(요청 루프 블로킹)
  • rb8001/app/router/slack_handler.py:177, 299, 314 등 — WebClient 동기 호출. AsyncWebClient 전환 및 await 적용 필요.
  • rb8001/app/skills/dm_skill.py:97, 176, 520 등 — DM 전송·메시지 업데이트 동기 호출 제거.
• 라우터 계층의 직접 DB 접근(계층 분리 위반)
  • rb8001/app/router/slack_handler.py:13, 73-85, 198-206 — SessionLocal과 SQL 직접 실행. 팀 UUID 매핑 로직을 서비스/레포지토리로 이동.
  • rb8001/app/skills/dm_skill.py:421-459 — 사용자 키워드 조회의 DB 접근을 서비스→state로 이관.
  • rb8001/app/services/naverworks_file_processor.py:12, 26-39 — 팀 UUID 조회 DB 접근 분리.
  • rb8001/app/router/message_router.py:20-23 — 최근 대화 조회는 서비스 헬퍼를 통해 state 호출만 수행하도록 정리.
• 하드코딩된 URL/포트 제거 필요(환경설정 일원화)
  • rb8001/app/router/slack_handler.py:64 — http://localhost:8508/api/upload → settings.SKILL_RAG_FILE_URL 기반 구성.
  • rb8001/app/router/slack_handler.py:366 — http://localhost:8508/api/search → 설정 사용.
  • rb8001/app/skills/dm_skill.py:134, 168, 362 — SKILL_EMAIL_URL, 뉴스 검색 localhost 기본값 제거 → 설정만 사용.
  • rb8001/app/commands/skill_commands.py:16-17 — http://localhost:8502/8505 기본값 제거 → 전역 설정 사용.
  • rb8001/app/skills/email_integration.py:366 — llm_callback에 http://localhost:8001 하드코딩 제거 → 게이트웨이/자기 호스트 설정 사용.
  • rb8001/app/skills/startup_news_skill.py:20-34 — Mistral API URL/모델 환경설정화.
  • rb8001/app/commands/skill_commands.py:279-285 — Tavily API URL 설정화.
  • auth-server/app/api/slack_router.py:125 — 컨테이너 라우팅 http://localhost:{port} 설정화.
  • skill-email/services/naverworks_provider.py:33-34 — 사설 IP 기본값 제거, 환경필수화.
• UUID 중심 식별 일관화
  • rb8001/app/skills/dm_skill.py:125-136, 168-175 — 이메일 조회에 Slack ID 직접 사용 금지. 매핑 후 UUID만 전달.
  • rb8001/app/router/slack_handler.py:282-287 — 로깅/컨텍스트에서도 UUID 우선 유지 점검.
• 동기 HTTP 호출 제거/비동기화
  • rb8001/app/memory/embedding_client.py:28-33 — requests.post 동기 호출을 비동기(httpx.AsyncClient)로 전환 또는 실행자 활용.
• JSONB 저장 규칙 준수(::jsonb 캐스팅)
  • rb8001/app/services/startup_valuation.py:475-486 — metadata 저장 시 json.dumps(...) + $7::jsonb 캐스팅 반영 필요.

권장 진행 순서: (1) URL/설정 일원화 → (2) 라우터 DB 접근 분리 → (3) Slack/HTTP 비동기화 → (4) UUID 일관화 → (5) JSONB 캐스팅 정리.