DOCS/journey/troubleshooting

Troubleshooting Guide

51124 서버 운용 중 발생한 모든 이슈는 날짜 기반 마크다운 파일(yymmdd_작성자_주제.md)로 저장됩니다. 이 README는 340개가 넘는 문서 중 필요한 정보를 빠르게 찾을 수 있도록 돕습니다.

구조와 네이밍

• 경로: DOCS/troubleshooting/
• 파일명: YYMMDD_author_topic.md
  • 예: 250723_happybell80_Slack_3초룰.md
• 각 문서는 상황 → 원인 → 해결 → 교훈 순서를 기본으로 하며, 교훈 섹션의 규칙은 AGENTS.md에 반영됩니다.

빠르게 찾는 방법

1. 최근 이슈 탐색: ls -t | head로 최신 10건 확인
2. 키워드 검색: rg "Slack 3초" DOCS/troubleshooting 처럼 rg 사용
3. 카테고리 패턴:
   • 네트워크/인프라: *_docker_*, *_nginx_*
   • 인증/보안: *_auth_*, *_JWT_*
   • 스킬별: skill-* 접두사의 문서

필수 참조 문서

주제	문서	비고
Slack 3초 룰	250723_happybell80_Slack_3초룰.md	FastAPI 비동기 패턴
배포 파이프라인	250716_rb8001_deployment_issues.md	Actions + docker compose
Storage/용량	250716_SSD_용량_부족_및_Docker_정리.md	정리 스크립트 가이드
Intent 리뷰 큐	251116_admin_intent_review_queue_api_implementation.md	최신 TDD 사례

문서 작성 시 체크리스트

• 문제 원인/증상 구분
• 명령어/로그는 fenced code block 사용
• 교훈 섹션에 재발 방지 규칙 명시
• 관련 문서/참고 링크를 하단에 추가

자주 쓰는 명령

rg "교훈" DOCS/troubleshooting -n        # 교훈 섹션 검색
rg "Docker" DOCS/troubleshooting -g "*.md" # 도커 관련 문서 검색

다음 단계

• 월별 인덱스 문서 작성 (예: 2025-07.md)
• Slack/Email/Calendar 등 서비스별 태그 파일 정리
• 교훈 섹션 자동 추출 스크립트 추가 (plans/ 디렉토리 예정)