이 파일은 코딩 도구가 읽는 공통 지침이지, 별도의 실행 에이전트가 아니다.
- 현재 구현과 계획을 구분한다.
docs/CURRENT_STATE.md를 진입점으로 읽고PLAN.md의 관련 단계와docs/PROGRESS.md의 최신/관련 기록을 확인한다. 긴 이력 전체를 매번 읽지 않는다. - 커밋/브랜치/PR 작성 전
CONTRIBUTING.md를 읽고 따른다. 타입/영역은 영문 소문자, 설명은 한글로 작성한다. - 기능과 해당 테스트는 같은 논리적 커밋에 포함할 수 있다. 관련 없는 변경은 분리한다.
- 기본은 main 직접 개발이며 작업 브랜치와 PR은 선택 사항이다. 로컬 검증/커밋 후 사용자가 변경과 결과를 검토하고 푸시를 승인할 때까지 기다린다.
- PR 작성 시
.github/pull_request_template.md를 사용하고 검증 결과/미검증 항목을 기록한다. - 원격 상태와 권한을 확인하기 전 커밋/푸시/PR/병합 완료를 주장하지 않는다. 비밀정보와 무관한 파일을 스테이징하지 않는다.
- Java 21 / Spring Boot 기반으로 작은 단계 하나씩 구현하고 검증 결과를 남긴다.
- 한 저장소에서 시작한다. 외부 저장소 생성, 실푸시, 유료 AWS 자원 생성, 공개 배포는 별도 요청 없이 하지 않는다.
- Mock은 수락 성공만 의미한다. 단말 도착 또는 exactly-once를 보장했다고 표현하지 않는다.
- 수신자, 토큰, 알림 본문을 로그나 메트릭 label에 넣지 않는다. ID도 고카디널리티 메트릭 label에 넣지 않는다.
- 메모리 대기열, 동시 요청, 재시도 횟수에는 상한을 둔다.
- DB와 Kafka 도입 후 두 시스템의 쓰기를 하나의 로컬 트랜잭션으로 간주하지 않는다.
- Kafka publish future 성공 확인 전 Outbox를 PUBLISHED로 변경하지 않는다.
- 비동기 컨슈머 도입 시 미완료 offset을 건너뛰지 않으며, 오류를 삼키고 성공 커밋하지 않는다.
- 멱등성은 exists 조회만으로 구현하지 않는다. 원자적인 DB 제약/상태 변경을 검증한다.
- 불필요한 MSA 분리, 분산락, 샤딩, Service Mesh를 선제적으로 넣지 않는다.
- 독립적인 조건을 한 번에 하나씩 바꾸고 변경 전후 지표를 비교한다.
- 작업 후 테스트를 실행한다. 실행하지 못한 테스트를 통과로 기록하지 않는다.
- 사용자 요청 없이 별도 서브에이전트나 외부 AI 세션을 만들지 않는다.
- 실행:
./gradlew test. Windows에서는gradlew.bat test. - Outbox·재시도·멱등성·Worker offset·공급자 보호 변경에는
notification-reliability스킬로 관련 실패 경계와 검증 범위를 확인한다. - 단계의 완료 상태나 다음 작업이 바뀌면
docs/CURRENT_STATE.md도 갱신하고 상세 근거는 기존 계획/실험 문서에 남긴다.