From 3a2c21c8961364a512ed24aed9b02fec1ff23428 Mon Sep 17 00:00:00 2001 From: Klaus Date: Thu, 14 May 2026 11:43:41 +0900 Subject: [PATCH] =?UTF-8?q?docs(agent):=20=EC=BD=94=EB=93=9C=20=EB=B0=B0?= =?UTF-8?q?=EC=B9=98=20=EA=B7=9C=EC=B9=99=EC=9D=84=20=EB=AC=B8=EC=84=9C?= =?UTF-8?q?=ED=99=94=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/agent-guides/코드스타일.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/agent-guides/코드스타일.md b/docs/agent-guides/코드스타일.md index 953e5eb2..5dafc249 100644 --- a/docs/agent-guides/코드스타일.md +++ b/docs/agent-guides/코드스타일.md @@ -22,37 +22,41 @@ - Request/Response DTO는 `...Request`, `...Response` 접미사를 유지한다. - 서비스/컨트롤러/리포지토리 명명은 역할 접미사(`Service`, `Controller`, `Repository`)를 유지한다. -### 4) 타입/널 처리 +### 4) 패키지/코드 배치 규칙 +- 기존 로직을 수정하는 경우에는 기존 패키지 구조를 따른다. +- 기존 로직 수정이 아닌 신규 API나 하위 코드는 `kr.co.vividnext.sodalive.v2` 패키지 하위에 작성한다. + +### 5) 타입/널 처리 - Kotlin 타입 시스템을 활용하고 nullable(`?`)를 명시한다. - 불필요한 `Any`/약한 타입을 피하고 구체 타입을 우선한다. - 기존 코드에서 `!!` 사용이 많지만, 신규 코드는 가능한 안전 호출/가드절/명시적 예외로 대체를 우선 고려한다. -### 5) API/응답 규칙 +### 6) API/응답 규칙 - API 응답은 `ApiResponse.ok(...)`, `ApiResponse.error(...)` 패턴을 따른다. - 컨트롤러는 도메인 예외를 직접 포맷하지 말고 `SodaException`을 던진다. - 인증 사용자 필요 시 `@AuthenticationPrincipal(... ) member: Member?` 패턴 + null 가드절을 사용한다. -### 6) 예외 처리 규칙 +### 7) 예외 처리 규칙 - 비즈니스 예외는 `SodaException(messageKey = "...")` 우선 사용. - 사용자 노출 문구는 하드코딩보다 `messageKey` 기반 i18n을 우선한다. - 공통 예외 변환은 `SodaExceptionHandler`에서 수행하므로, 개별 컨트롤러에서 중복 처리하지 않는다. - 예외를 삼키는 빈 `catch` 블록을 금지한다. -### 7) 트랜잭션 규칙 +### 8) 트랜잭션 규칙 - 서비스 계층에서 `@Transactional`을 사용한다. - 조회 위주 메서드는 `@Transactional(readOnly = true)`를 우선한다. - 쓰기 로직은 메서드 단위 `@Transactional`로 경계를 명확히 한다. -### 8) 비동기/동시성 규칙 +### 9) 비동기/동시성 규칙 - 비동기 처리는 Kotlin Coroutines 패턴을 따른다. - `CoroutineScope(Dispatchers.IO)` + `launch` + 예외 처리 패턴을 일관되게 유지한다. - 생명주기 종료 시 scope 정리(`@PreDestroy`) 패턴을 참고한다. -### 9) 의존성 주입 +### 10) 의존성 주입 - 생성자 주입(primary constructor + `private val`)을 기본으로 사용한다. - 필드 주입보다 명시적 생성자 주입을 우선한다. -### 10) 주석 +### 11) 주석 - 의미 단위별로 주석을 작성한다. - 주석은 한 문장으로 간결하게 작성한다. - 주석은 코드의 의도와 구조를 설명한다.