Communitygithub.com

Piyush-Nagar/coding-agents-skills

신뢰성은 주변 시스템이 실패할 때도 서비스가 계속 작동하도록 유지하는 규율입니다. 부분 실패를 먼저 설계하세요; 정상 경로는 저절로 해결됩니다.

coding-agents-skills란 무엇인가요?

이 스킬은 소프트웨어 시스템의 신뢰성을 보장하기 위해 설계된 포괄적인 규칙과 모범 사례 모음입니다. 타임아웃 설정, 멱등성 유지, 서킷 브레이커 도입, 벌크헤드 패턴 적용 등 주요 가이드라인을 제공하여 예상치 못한 장애 상황에서도 시스템이 안정적으로 작동하도록 돕습니다. Claude Code, Cursor, Codex 등 다양한 AI 에이전트 플랫폼에서 사용할 수 있으며, 각 규칙은 구체적인 코드 예시나 설정 방법을 함께 제시합니다. 이 스킬의 핵심은 '부분 실패에 대비하라'는 원칙에 기반하며, 정상 경로는 자동으로 해결된다는 철학을 따릅니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Piyush-Nagar/coding-agents-skills/tree/HEAD/backend/core/nfr/reliability

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

신뢰성

신뢰성은 주변 시스템이 실패할 때도 서비스가 계속 작동하도록 유지하는 규율입니다 — 반드시 실패할 것입니다. 부분 실패를 먼저 설계하세요; 정상 경로는 저절로 해결됩니다.

규칙

  • 모든 외부 호출에 타임아웃을 설정하세요. 예외는 없습니다. 타임아웃이 없으면 스레드 풀 고갈 사고가 발생합니다.
  • 멱등성 연산에만 재시도하세요. 지수 백오프와 지터를 적용하세요. 멱등성이 없는 POST를 재시도하면 중복이 생기고, 카드가 두 번 청구되며, 두 개의 이메일이 발송됩니다.
  • 변경 가능한 퍼블릭 API에는 멱등성 키를 사용하세요. 클라이언트가 네트워크 결함을 넘어 안전하게 재시도할 수 있게 해주며, 서버 측에서 추측할 필요가 없어집니다.
  • 외부 종속성에 서킷 브레이커를 적용하세요. 다운스트림이 아플 때 빠르게 실패하면 당신과 그 시스템 모두를 보호합니다. 무분별한 재시도는 하나의 장애를 두 개로 만듭니다.
  • 중요 경로를 격리하세요. 다운스트림별로 스레드 풀/연결 풀을 분리하여 느린 하나가 전체 서비스를 침수시키는 것을 방지하세요.
  • 정상적 저하가 하드 실패보다 낫습니다. 500 오류 대신 오래된 캐시, 부분 응답 또는 축소된 기능 세트를 제공하세요.
  • 단일 장애점이 없어야 합니다. 모든 상태 저장 컴포넌트에 대해 멀티 AZ, 모든 상태 비저장 컴포넌트에 대해 여러 복제본, 실제로 질병을 감지하는 LB 상태 확인을 사용하세요.
  • 종료는 정상적으로 이루어져야 합니다. 진행 중인 요청을 처리하고, 풀을 닫고, 버퍼를 플러시하세요. SIGTERM → 수신 중단 → 완료 또는 취소 → 종료.
  • 언제든지 안전하게 재시작할 수 있도록 만드세요. 어떤 단일 파드든 언제든지 죽여도 사용자에게 제로 영향을 주어야 합니다. 그렇지 않다면 그것이 수정해야 할 버그입니다.
  • 백업은 복원할 때까지 테스트되지 않은 것입니다. 정기적으로 실제 복원 훈련을 실행하세요.

경고 신호

  • restTemplate.exchange(...) 타임아웃 구성 없음.
  • 상한선과 백오프가 없는 재시도 루프.
  • "재배포하면 작동합니다." (메모리에 숨겨진 상태)
  • SIGTERM 시 요청이 손실되어 실제로 제로 다운타임이 아닌 제로 다운타임 배포.
  • 한 번도 실행되지 않은 재해 복구 런북.

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

관련 스킬