메뉴
ddan-ddan-server의 layered 아키텍처 의존 규칙과 패키지 구조 가이드. domain/application/infrastructure/presentation 4개 레이어의 책임, 의존 방향, Gateway 패턴(폐기 예정) 처리 방침을 다룬다. 새 코드 추가, 리팩토링, 코드 리뷰 시 반드시 참조할 것 — 레이어 의존 위반은 가장 흔하고 가장 치명적인 결함이다.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | layered-architecture-guide |
| description | ddan-ddan-server의 layered 아키텍처 의존 규칙과 패키지 구조 가이드. domain/application/infrastructure/presentation 4개 레이어의 책임, 의존 방향, Gateway 패턴(폐기 예정) 처리 방침을 다룬다. 새 코드 추가, 리팩토링, 코드 리뷰 시 반드시 참조할 것 — 레이어 의존 위반은 가장 흔하고 가장 치명적인 결함이다. |
notbe.tmtm.ddanddanserver
├── domain/ (가장 안쪽, 다른 레이어를 모름)
├── application/ (domain에만 의존)
├── infrastructure/ (domain에 의존, 외부 시스템 연결)
└── presentation/ (application에 의존, 외부 노출)
presentation ──► application ──► domain ◄── infrastructure
도메인은 누구도 import하지 않는다. application과 infrastructure가 도메인을 사용한다. presentation은 application까지만 안다.
domain → 그 외 어떤 레이어든 importapplication → presentation, infrastructure (단, 인터페이스 의존은 OK — 아래 Gateway 항목 참조)presentation → infrastructure, domain 직접 참조 (DTO ↔ 도메인 변환은 application 또는 매퍼에서)| 디렉토리 | 책임 |
|---|---|
model/ | 비즈니스 도메인 객체 — 풍부 모델, 비즈니스 규칙은 여기 |
exception/ | 도메인별 커스텀 예외 (예: CheerAlreadyExistsException) |
gateway/ | (폐기 예정) 외부 의존에 대한 인터페이스 — 새 코드는 가급적 사용 금지 |
규칙:
@Service, @Component, @Document 등 모두 X)| 디렉토리 | 책임 |
|---|---|
service/ | 유스케이스 단위의 조정 로직 (@Service) |
processor/ | OAuth 등 Factory 패턴이 필요한 처리기 |
규칙:
@Service + 생성자 주입 + valCheerRepository, PushClient)| 디렉토리 | 책임 |
|---|---|
database/ | MongoDB 엔티티(@Document), Repository |
api/ | 외부 API 클라이언트 (Kakao, Apple, Slack) |
client/ | 내부 정의된 클라이언트 추상화 (예: PushClient) |
규칙:
@Document 엔티티는 반드시 infrastructure에만 둔다| 디렉토리 | 책임 |
|---|---|
controller/ | REST API (@RestController) |
dto/ | 요청/응답 DTO (record/data class) |
filter/ | JWT 인증, 로깅, 버전 필터 |
scheduler/ | @Scheduled 정기 작업 |
규칙:
@Operation, @Parameter, @ApiResponse) 필수domain/gateway/와 infrastructure/gateway/는 향후 제거 대상이다 (AGENTS.md 명시).
새 코드 작성 시:
기존 Gateway 코드 수정 시:
각 기능은 레이어 안에서 별도 하위 패키지로 분리된다:
domain/model/cheer/ ← Cheer 도메인 모델
application/service/CheerService.kt
infrastructure/database/repository/CheerRepository.kt
presentation/controller/CheerController.kt
presentation/dto/cheer/ ← cheer 관련 DTO
새 기능 추가 시 체크리스트:
domain/model/{feature}/에 도메인 모델domain/exception/에 커스텀 예외 (필요 시)application/service/{Feature}Service.ktinfrastructure/database/에 Document + Repository (필요 시)presentation/controller/{Feature}Controller.ktpresentation/dto/{feature}/에 요청/응답 DTO| 위반 | 권고 |
|---|---|
service가 @Document 엔티티를 그대로 반환 | Repository에서 도메인 모델로 변환해 반환 |
| 컨트롤러에서 비즈니스 분기 | service 메서드로 이동 |
도메인 객체에 @JsonProperty | DTO를 별도로 두고 매핑 |
| 도메인 예외를 컨트롤러에서 try/catch | WebExceptionHandler에 매핑 추가 |
| application/service가 다른 service의 컨트롤러를 호출 | service 간 직접 호출 또는 도메인 이벤트 |
ddan-ddan-server의 기능 개발/버그 수정/리팩토링 워크플로우 오케스트레이터. 이슈 분석 → 설계 → 구현 → 테스트·API 문서 → 리뷰 → PR 생성을 6개 전문 에이전트(issue-analyzer, backend-architect, kotlin-spring-implementer, test-engineer, api-documenter, code-reviewer)가 협업하여 자동화한다. 다음 표현이 등장하면 반드시 트리거할 것 - "기능 추가", "API 만들어줘", "이슈
ddan-ddan-server의 한국어 이슈/브랜치/PR 컨벤션. 이슈 제목 형식 [작업타입] 설명, 브랜치명 타입/#번호-설명, PR 제목 타입 설명, PR 본문 템플릿(작업 내용/기타/close 이슈) 패턴을 다룬다. 이슈 생성, 브랜치 생성, PR 생성 시 반드시 참조 — 팀 컨벤션 위반은 PR이 즉시 반려되는 사유다.
ddan-ddan-server의 테스트 작성 가이드. Kotest 5.9.1 FunSpec + MockK 1.13.11 조합, beforeEach 초기화, 한국어 테스트명, shouldBe/shouldThrow assertion DSL을 다룬다. 모든 테스트 코드 작성/수정 시 반드시 참조 — 이 프로젝트는 JUnit 어노테이션 스타일이 아닌 Kotest FunSpec 스타일을 표준으로 사용한다.
ddan-ddan-server의 Kotlin/Spring Boot/MongoDB 코드 컨벤션. 생성자 주입, @Document 엔티티, JWT 인증, WebExceptionHandler 글로벌 예외 처리, LoggingFilter, OpenAPI 문서화 패턴을 다룬다. 새 코드 작성과 코드 리뷰 시 반드시 참조 — 컨벤션 위반은 PR 리뷰의 가장 잦은 지적 사유다.
ddan-ddan-server의 기능 개발/버그 수정/리팩토링 워크플로우 오케스트레이터. 이슈 분석 → 설계 → 구현 → 테스트 → 리뷰 → PR 생성을 5개 전문 에이전트(issue-analyzer, backend-architect, kotlin-spring-implementer, test-engineer, code-reviewer)가 협업하여 자동화한다. 다음 표현이 등장하면 반드시 트리거할 것 - "기능 추가", "API 만들어줘", "이슈
ddan-ddan-server의 한국어 이슈/브랜치/PR 컨벤션. 이슈 제목 형식 [작업타입] 설명, 브랜치명 타입/#번호-설명, PR 제목 타입 설명, PR 본문 템플릿(작업 내용/기타/close 이슈) 패턴을 다룬다. 이슈 생성, 브랜치 생성, PR 생성 시 반드시 참조 — 팀 컨벤션 위반은 PR이 즉시 반려되는 사유다.