From 0665cdaca864aae2c34fdf3ac681b227b0c7735e Mon Sep 17 00:00:00 2001
From: Klaus <klaus@vividnext.co.kr>
Date: Wed, 29 Apr 2026 16:57:27 +0900
Subject: [PATCH] =?UTF-8?q?docs(agent-guides):=20=EC=BD=94=EB=93=9C=C2=B7?=
 =?UTF-8?q?=ED=85=8C=EC=8A=A4=ED=8A=B8=C2=B7=EB=B3=B4=EC=95=88=20=EA=B0=80?=
 =?UTF-8?q?=EC=9D=B4=EB=93=9C=EB=A5=BC=20=EB=B6=84=EB=A6=AC=ED=95=9C?=
 =?UTF-8?q?=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/agent-guides/설정보안.md     |  6 ++++
 docs/agent-guides/코드스타일.md   | 59 +++++++++++++++++++++++++++++++
 docs/agent-guides/테스트스타일.md |  9 +++++
 3 files changed, 74 insertions(+)
 create mode 100644 docs/agent-guides/설정보안.md
 create mode 100644 docs/agent-guides/코드스타일.md
 create mode 100644 docs/agent-guides/테스트스타일.md

diff --git a/docs/agent-guides/설정보안.md b/docs/agent-guides/설정보안.md
new file mode 100644
index 00000000..c54a2999
--- /dev/null
+++ b/docs/agent-guides/설정보안.md
@@ -0,0 +1,6 @@
+# 설정 보안
+
+## 설정/보안 유의사항
+- `application.yml`은 다수의 `${ENV_VAR}`를 사용한다.
+- 비밀값(API Key, Secret, Token, DB 비밀번호)을 코드/문서/로그에 평문으로 남기지 않는다.
+- 환경변수/시크릿 파일은 커밋 대상에서 제외한다.
diff --git a/docs/agent-guides/코드스타일.md b/docs/agent-guides/코드스타일.md
new file mode 100644
index 00000000..953e5eb2
--- /dev/null
+++ b/docs/agent-guides/코드스타일.md
@@ -0,0 +1,59 @@
+# 코드 스타일
+
+## 코드 스타일 규칙
+
+### 1) 포맷/기본 규칙
+- `.editorconfig` 기준을 준수한다.
+- 인덴트: 공백 4칸.
+- 줄바꿈: LF.
+- 최대 라인 길이: 130.
+- 파일 끝 개행 유지, trailing whitespace 제거.
+
+### 2) import 규칙
+- 와일드카드 import(`*`)를 사용하지 않는다.
+- 사용하지 않는 import를 남기지 않는다.
+- import alias(`as`)는 현재 코드베이스에서 사용 사례가 없으므로 지양한다.
+- 기존 파일의 import 정렬/그룹 스타일을 그대로 맞춘다.
+
+### 3) 네이밍 규칙
+- 클래스/인터페이스/enum: PascalCase.
+- 함수/변수/파라미터: camelCase.
+- 상수: UPPER_SNAKE_CASE (`companion object` 내부 `const val`).
+- Request/Response DTO는 `...Request`, `...Response` 접미사를 유지한다.
+- 서비스/컨트롤러/리포지토리 명명은 역할 접미사(`Service`, `Controller`, `Repository`)를 유지한다.
+
+### 4) 타입/널 처리
+- Kotlin 타입 시스템을 활용하고 nullable(`?`)를 명시한다.
+- 불필요한 `Any`/약한 타입을 피하고 구체 타입을 우선한다.
+- 기존 코드에서 `!!` 사용이 많지만, 신규 코드는 가능한 안전 호출/가드절/명시적 예외로 대체를 우선 고려한다.
+
+### 5) API/응답 규칙
+- API 응답은 `ApiResponse.ok(...)`, `ApiResponse.error(...)` 패턴을 따른다.
+- 컨트롤러는 도메인 예외를 직접 포맷하지 말고 `SodaException`을 던진다.
+- 인증 사용자 필요 시 `@AuthenticationPrincipal(... ) member: Member?` 패턴 + null 가드절을 사용한다.
+
+### 6) 예외 처리 규칙
+- 비즈니스 예외는 `SodaException(messageKey = "...")` 우선 사용.
+- 사용자 노출 문구는 하드코딩보다 `messageKey` 기반 i18n을 우선한다.
+- 공통 예외 변환은 `SodaExceptionHandler`에서 수행하므로, 개별 컨트롤러에서 중복 처리하지 않는다.
+- 예외를 삼키는 빈 `catch` 블록을 금지한다.
+
+### 7) 트랜잭션 규칙
+- 서비스 계층에서 `@Transactional`을 사용한다.
+- 조회 위주 메서드는 `@Transactional(readOnly = true)`를 우선한다.
+- 쓰기 로직은 메서드 단위 `@Transactional`로 경계를 명확히 한다.
+
+### 8) 비동기/동시성 규칙
+- 비동기 처리는 Kotlin Coroutines 패턴을 따른다.
+- `CoroutineScope(Dispatchers.IO)` + `launch` + 예외 처리 패턴을 일관되게 유지한다.
+- 생명주기 종료 시 scope 정리(`@PreDestroy`) 패턴을 참고한다.
+
+### 9) 의존성 주입
+- 생성자 주입(primary constructor + `private val`)을 기본으로 사용한다.
+- 필드 주입보다 명시적 생성자 주입을 우선한다.
+
+### 10) 주석
+- 의미 단위별로 주석을 작성한다.
+- 주석은 한 문장으로 간결하게 작성한다.
+- 주석은 코드의 의도와 구조를 설명한다.
+- 주석은 코드 변경 시 업데이트를 잊지 않는다.
diff --git a/docs/agent-guides/테스트스타일.md b/docs/agent-guides/테스트스타일.md
new file mode 100644
index 00000000..db000809
--- /dev/null
+++ b/docs/agent-guides/테스트스타일.md
@@ -0,0 +1,9 @@
+# 테스트 스타일
+
+## 테스트 스타일 규칙
+- 테스트 프레임워크: JUnit 5 (`useJUnitPlatform()`)
+- 목킹: Mockito 사용 패턴 존재 (`Mockito.mock`, ``Mockito.`when`(...)``)
+- 검증: `assertEquals`, `assertThrows` 패턴 준수.
+- 테스트 이름은 의도가 드러나는 영어 문장형(`should...`)을 유지한다.
+- 테스트는 DisplayName으로 한국어 설명을 추가한다.
+- 예외 상황이 있는지 확인하고 예외 상황에 대한 테스트 케이스를 추가한다.