From bdc5e8020cbacb60f0f71fc51e7593d5e060a257 Mon Sep 17 00:00:00 2001 From: klaus Date: Thu, 14 May 2026 20:39:04 +0900 Subject: [PATCH] =?UTF-8?q?docs(agent):=20=EC=BD=94=EB=93=9C=20=EC=8A=A4?= =?UTF-8?q?=ED=83=80=EC=9D=BC=20=EA=B0=80=EC=9D=B4=EB=93=9C=EB=A5=BC=20?= =?UTF-8?q?=EB=B6=84=EB=A6=AC=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 3 +- docs/agent-guides/build-test-style.md | 42 +-------------------- docs/agent-guides/code-style.md | 43 ++++++++++++++++++++++ docs/agent-guides/workflow-docs-commits.md | 2 +- 4 files changed, 47 insertions(+), 43 deletions(-) create mode 100644 docs/agent-guides/code-style.md diff --git a/AGENTS.md b/AGENTS.md index 77b09dc9..ec28c183 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -132,7 +132,8 @@ Strong success criteria let you loop independently. Weak criteria ("make it work - PRD 문서는 `docs/prd/`, 계획/TASK 문서는 `docs/plan-task/` 아래에 둔다. ## 상세 참조 문서 -- 빌드/린트/테스트/코드 스타일은 `docs/agent-guides/build-test-style.md`를 참고한다. +- 빌드/린트/테스트는 `docs/agent-guides/build-test-style.md`를 참고한다. +- 코드 스타일/구조는 `docs/agent-guides/code-style.md`를 참고한다. - 작업 절차/docs/커밋 규칙은 `docs/agent-guides/workflow-docs-commits.md`를 참고한다. - 저장소 세부 규칙/보안/Git 안전 수칙은 `docs/agent-guides/safety-repo-rules.md`를 참고한다. diff --git a/docs/agent-guides/build-test-style.md b/docs/agent-guides/build-test-style.md index 56b575b0..b4dfc62a 100644 --- a/docs/agent-guides/build-test-style.md +++ b/docs/agent-guides/build-test-style.md @@ -1,6 +1,6 @@ # build-test-style -`SodaLive` 저장소에서 빌드, 테스트, 린트, 코드 스타일 관련 세부 규칙을 정리한 문서다. +`SodaLive` 저장소에서 빌드, 테스트, 린트 관련 세부 규칙을 정리한 문서다. ## 저장소 범위 보충 - 추측하지 말고 근거 파일(`settings.gradle`, `build.gradle`, `app/build.gradle`, 소스 코드)을 읽고 결정한다. @@ -75,43 +75,3 @@ ADB 대안: ```bash adb shell am instrument -w -e class kr.co.vividnext.sodalive.SomeInstrumentedTest#someMethod / ``` - -## 코드 스타일 가이드 -### 1) 포맷/기본 규칙 -- `.editorconfig` 기준을 준수한다. -- 인덴트: 공백 4칸, 줄바꿈: LF, 최대 라인 길이: 130. -- 파일 끝 개행 유지, trailing whitespace 제거. -- Kotlin/KTS에서 `import-ordering` ktlint 규칙은 비활성화되어 있으므로 기존 파일 정렬 스타일을 우선 따른다. - -### 2) import 규칙 -- 신규 코드에서는 와일드카드 import(`*`)를 기본적으로 지양한다. -- 사용하지 않는 import를 남기지 않는다. -- import alias(`as`)는 필요한 경우(이름 충돌 회피) 최소 범위로만 사용한다. -- 기존 파일에 와일드카드/alias가 있으면 대규모 정렬 리팩터링 없이 주변 스타일에 맞춘다. - -### 3) 네이밍/레이어 -- UI: `*Activity`, `*Fragment`, dialog/sheet suffix -- 상태/도메인: `*ViewModel` (주로 `BaseViewModel` 상속) -- 데이터 계층: `*Repository`, Retrofit `*Api` -- DTO: `data class` + `*Request`, `*Response` suffix -- 레이어 흐름: `Api` -> `Repository` -> `ViewModel` -> `Activity`/`Fragment` -- DI는 `app/src/main/java/kr/co/vividnext/sodalive/di/AppDI.kt`의 Koin 구성을 따른다. -- 기존 로직 수정이 아닌 신규 `Activity`, `Fragment`, `ViewModel` 파일 및 코드와 그에 연결된 하위 코드(예: Repository, Api, DTO, adapter/helper 등)는 `app/src/main/java/kr/co/vividnext/sodalive/v2` 경로의 `kr.co.vividnext.sodalive.v2` 패키지 하위에 작성한다. - -### 4) 타입/계약/에러 처리 -- nullability와 제네릭 타입을 의미가 바뀌지 않게 유지한다. -- 공개 API/스키마/리소스 계약은 요청 없이 변경하지 않는다. -- 응답 처리 시 기존 `ApiResponse`와 Rx 타입(`Single`, `Flowable`)을 우선 재사용한다. -- 빈 `catch` 블록을 새로 추가하지 않는다. -- 예외를 조용히 삼키지 않고 로그/주석/대체 흐름 중 하나를 남긴다. - -### 5) 테스트 관례 -- 단위 테스트는 `app/src/test`에 위치하며 클래스명은 `*Test`를 사용한다. -- 기본 스택은 JUnit4 + MockK/Mockito다. -- 테스트 추가 시 단일 실행 명령 예시도 본 문서에 갱신한다. - -### 6) 주석 -- 의미 단위별로 주석을 작성한다. -- 주석은 한 문장으로 간결하게 작성한다. -- 주석은 코드의 의도와 구조를 설명한다. -- 주석은 코드 변경 시 업데이트를 잊지 않는다. diff --git a/docs/agent-guides/code-style.md b/docs/agent-guides/code-style.md new file mode 100644 index 00000000..f7b0749a --- /dev/null +++ b/docs/agent-guides/code-style.md @@ -0,0 +1,43 @@ +# code-style + +`SodaLive` 저장소에서 코드 스타일, 네이밍, 레이어, 타입/계약/에러 처리 관련 세부 규칙을 정리한 문서다. + +## 코드 스타일 가이드 +### 1) 포맷/기본 규칙 +- `.editorconfig` 기준을 준수한다. +- 인덴트: 공백 4칸, 줄바꿈: LF, 최대 라인 길이: 130. +- 파일 끝 개행 유지, trailing whitespace 제거. +- Kotlin/KTS에서 `import-ordering` ktlint 규칙은 비활성화되어 있으므로 기존 파일 정렬 스타일을 우선 따른다. + +### 2) import 규칙 +- 신규 코드에서는 와일드카드 import(`*`)를 기본적으로 지양한다. +- 사용하지 않는 import를 남기지 않는다. +- import alias(`as`)는 필요한 경우(이름 충돌 회피) 최소 범위로만 사용한다. +- 기존 파일에 와일드카드/alias가 있으면 대규모 정렬 리팩터링 없이 주변 스타일에 맞춘다. + +### 3) 네이밍/레이어 +- UI: `*Activity`, `*Fragment`, dialog/sheet suffix +- 상태/도메인: `*ViewModel` (주로 `BaseViewModel` 상속) +- 데이터 계층: `*Repository`, Retrofit `*Api` +- DTO: `data class` + `*Request`, `*Response` suffix +- 레이어 흐름: `Api` -> `Repository` -> `ViewModel` -> `Activity`/`Fragment` +- DI는 `app/src/main/java/kr/co/vividnext/sodalive/di/AppDI.kt`의 Koin 구성을 따른다. +- 기존 로직 수정이 아닌 신규 `Activity`, `Fragment`, `ViewModel` 파일 및 코드와 그에 연결된 하위 코드(예: Repository, Api, DTO, adapter/helper 등)는 `app/src/main/java/kr/co/vividnext/sodalive/v2` 경로의 `kr.co.vividnext.sodalive.v2` 패키지 하위에 작성한다. + +### 4) 타입/계약/에러 처리 +- nullability와 제네릭 타입을 의미가 바뀌지 않게 유지한다. +- 공개 API/스키마/리소스 계약은 요청 없이 변경하지 않는다. +- 응답 처리 시 기존 `ApiResponse`와 Rx 타입(`Single`, `Flowable`)을 우선 재사용한다. +- 빈 `catch` 블록을 새로 추가하지 않는다. +- 예외를 조용히 삼키지 않고 로그/주석/대체 흐름 중 하나를 남긴다. + +### 5) 테스트 관례 +- 단위 테스트는 `app/src/test`에 위치하며 클래스명은 `*Test`를 사용한다. +- 기본 스택은 JUnit4 + MockK/Mockito다. +- 테스트 추가 시 단일 실행 명령 예시도 `docs/agent-guides/build-test-style.md`에 갱신한다. + +### 6) 주석 +- 의미 단위별로 주석을 작성한다. +- 주석은 한 문장으로 간결하게 작성한다. +- 주석은 코드의 의도와 구조를 설명한다. +- 주석은 코드 변경 시 업데이트를 잊지 않는다. diff --git a/docs/agent-guides/workflow-docs-commits.md b/docs/agent-guides/workflow-docs-commits.md index 0f570c5b..485f02b8 100644 --- a/docs/agent-guides/workflow-docs-commits.md +++ b/docs/agent-guides/workflow-docs-commits.md @@ -40,7 +40,7 @@ ## 문서 유지보수 규칙 - `build.gradle`/`app/build.gradle`/`settings.gradle` 변경 시 실행 명령 섹션을 함께 갱신한다. - 테스트 클래스 추가/이동 시 단일 테스트 실행 예시를 최신 상태로 유지한다. -- `.editorconfig` 변경 시 포맷 규칙 섹션을 동기화한다. +- `.editorconfig` 변경 시 `docs/agent-guides/code-style.md`의 포맷 규칙 섹션을 동기화한다. - 문서 변경 후 최소 한 번 `./gradlew tasks --all`로 명령 유효성을 확인한다. - 불확실한 규칙은 추측으로 채우지 말고 근거 파일 경로를 먼저 확인한다. - 에이전트 안내 문구는 한국어 중심으로 유지한다.