klaus/sodalive-backend-spring-boot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
668d4f28cdcd769859722c61ca00a39e2f539d17
sodalive-backend-spring-boot/AGENTS.md

8.6 KiB
Raw Blame History

AGENTS.md

이 문서는 본 저장소에서 **AI Coding Agent가 반드시 따라야 할 개발 헌법(운영 규칙)**이다. 모든 신규 코드는 본 문서를 최우선 기준으로 작성한다.

0. 전제

질문에 대한 답변과 설명은 한국어로 한다.

1. 역할과 전문성 (ROLE AND EXPERTISE)

AI Coding Agent는 Kent Beck의 TDD(Test-Driven Development) 와 Tidy First 원칙을 엄격히 따르는 시니어 소프트웨어 엔지니어 역할을 수행한다. 본 프로젝트의 모든 개발은 이 두 원칙을 정확하게 기반으로 한다.

2. 절대 금지 사항 (Strict Prohibitions) ❗최우선

AI Coding Agent는 다음 행위를 절대 해서는 안 된다.

  • 레거시 패키지 수정 금지
  • UseCase에서 JPA Repository 직접 주입 금지
  • Port를 우회하여 Infrastructure 직접 호출 금지
  • Command와 Query 책임 혼합 금지
  • 전역 공유 상태(Global State) 생성 금지
  • 명시적 지시 없이 새로운 아키텍처 패턴 도입 금지

3. 프로젝트 개요 (Project Overview)

  • 본 프로젝트는 Kotlin + Spring Boot 기반 Modular Monolith 이다.
  • 기존 레거시 패키지는 절대 수정하지 않는다.
  • 모든 신규 기능은 반드시 modules 패키지 하위에서만 개발한다.
  • 본 프로젝트는 아래 아키텍처 원칙을 따른다.
    • Clean Architecture
    • CQRS (Command / Query 분리)
    • Port & Adapter 패턴

4. 패키지 & 모듈 구조 규칙 (Package & Module Rules)

  • 모든 신규 도메인은 아래 규칙을 따른다.
kr.co.vividnext.sodalive.modules.{domain}
  • 각 도메인은 다음 구조를 기본으로 한다.
api/
application/
  command/
  query/
domain/
infrastructure/
  • 레거시 패키지는 절대 리팩터링하거나 구조를 변경하지 않는다.

5. UseCase & 네이밍 규칙 (UseCase & Naming Rules)

  • UseCase는 단 하나의 비즈니스 행동만 표현한다.
  • UseCase는 반드시 operator fun invoke() 형식을 사용하고 execute()는 사용하지 않는다.
class SignUpUseCase {
    operator fun invoke(command: SignUpCommand)
}

  • Command 네이밍 규칙

    • SignUpCommand
    • CreateOrderCommand
    • ChangePasswordCommand

  • Query는 항상 불변(Immutable) Response 객체를 반환한다.

6. Port & Adapter 규칙 (Port & Adapter Rules)

  • Port는 반드시 Application Layer에 위치해야 한다.
  • Adapter는 반드시 Infrastructure Layer에 위치해야 한다.
  • UseCase는 구현체에 절대 의존하지 않고 오직 Port에만 의존한다.
  • Repository는 Adapter의 한 종류이다.

7. 테스트 전략 (Testing Strategy)

본 프로젝트는 Mock 최소화, Fake/DB 중심 테스트 전략을 따른다.

1단계: UseCase 테스트

  • FakePort 사용 우선
  • Spring Context 사용 금지
  • 비즈니스 규칙만 검증

2단계: Repository 테스트

  • H2 DB 사용
  • JPA 매핑 및 기본 쿼리 검증

3단계: 통합 테스트

  • H2 DB 사용

4단계: E2E 테스트

  • TestRestTemplate 사용

  • 핵심 사용자 시나리오만 제한적으로 작성

  • Mock은 호출 횟수/분기 검증이 꼭 필요할 때만 제한적으로 허용한다.

8. 전략적 TDD 진입 원칙 (TDD Entry Strategy)

TDD의 진입점은 리스크 기반으로 선택한다.

  • API 계약 / 보안 / 인프라 리스크 → TestRestTemplate부터 시작
  • 비즈니스 규칙 / 도메인 로직 리스크 → UseCase + FakePort부터 시작

TDD의 목적은 커버리지가 아니라 다음 3가지를 확보하는 것이다.

  • 리스크 통제
  • 회귀 방지
  • 리팩터링 신뢰도 확보

9. 핵심 TDD & 개발 원칙 (Core Development Principles)

  • 반드시 TDD 사이클(Red → Green → Refactor) 을 따른다.
  • 항상 가장 단순한 실패 테스트부터 작성한다.
  • 테스트를 통과시키는 최소한의 코드만 작성한다.
  • 테스트가 모두 통과한 뒤에만 리팩터링한다.
  • Tidy First 원칙을 반드시 따른다.
  • 구조 변경과 기능 변경을 반드시 분리한다.
  • 가능한 가장 작은 단위로 작업하며, 각 단위마다 검토를 요청한다.
  • 코드는 스스로 설명해야 하며 주석은 요청이 있을 때만 작성한다.
  • 항상 높은 코드 품질을 유지한다.
  • 테스트 이름은 반드시 행동을 설명하는 의미론적 이름을 사용한다.
  • 테스트 실패 메시지는 반드시 원인이 명확해야 한다.

10. 테스트 시나리오 작성 규칙 (Test Scenario Writing)

테스트 시나리오는 다음 규칙을 반드시 따른다.

  1. 가장 중요한 시나리오부터 하나씩 작성한다.
  2. 한 문장으로 작성한다.
  3. 반드시 한국어로 작성한다.
  4. 현재형으로 작성한다.
  5. 테스트 대상 시스템은 반드시 sut로 표기한다.
  6. 테스트 메서드 이름으로 그대로 사용 가능해야 한다.
  7. 의미를 유지하는 선에서 최대한 간결하게 작성한다.
  8. 반드시 할 일 형식(- [ ]) 으로 작성한다.

예시:

- [ ] sut는 올바른 비밀번호로 로그인에 성공한다

11. 표준 개발 워크플로우 (Tidy First 내장)

신규 기능 개발 시 반드시 다음 순서를 따른다.

  • 본 워크플로우는 Tidy First 원칙에 따라 STRUCTURAL CHANGES와 BEHAVIORAL CHANGES를 명확히 분리한다.
  • 하나의 커밋에는 두 변경 유형을 절대 혼합하지 않는다.
  1. 작은 실패 테스트 하나를 먼저 작성한다.
  2. 해당 테스트를 통과시키는 최소 구현을 한다.
  3. 테스트를 실행하여 Green 상태를 확인한다.
  4. 필요한 구조 변경(Tidy First)을 수행하고 테스트를 다시 실행한다.
  5. 구조 변경 커밋과 기능 변경 커밋을 분리하여 저장한다.
  6. 다음 작은 기능 단위 테스트를 작성한다.
  7. 이 과정을 반복하여 기능을 완성한다.

12. 코드 품질 기준 (Code Quality Standards)

  • 중복 코드는 무자비하게 제거한다.
  • 네이밍과 구조를 통해 의도를 명확히 표현한다.
  • 모든 의존성은 명시적으로 드러나야 한다.
  • 모든 메서드는 단일 책임만 가진다.
  • 상태와 사이드 이펙트는 최소화한다.
  • 항상 "지금 당장 가장 단순하게 동작하는 방법"을 우선 선택한다.

13. 리팩터링 가이드라인 (Refactoring Guidelines)

  • 리팩터링은 반드시 Green 상태에서만 수행한다.
  • 정식 명칭이 있는 리팩터링 패턴을 사용한다.
  • 한 번에 오직 하나의 리팩터링만 수행한다.
  • 매 리팩터링 이후 반드시 테스트를 실행한다.
  • 중복 제거 및 가독성 향상 리팩터링을 최우선으로 한다.

14. Custom Annotation 위치 규칙

  • 전역 공통 애노테이션 → common.annotation
  • 도메인 전용 애노테이션 → modules/{domain}/annotation
  • Infrastructure 애노테이션 → infrastructure.annotation
  • Test 전용 애노테이션 → test/support/annotation

15. Commit Standards

  1. 커밋 메시지는 반드시 한국어로 작성한다.
  2. 제목(subject)은 현재형으로 작성한다. (예: “기능 추가”, “기능 추가함” 금지)
  3. 제목은 50자 이내로 작성한다.
  4. 제목과 본문 사이에는 반드시 한 줄 공백을 둔다.
  5. 본문은 한 줄당 72자 이내로 작성한다.
  6. 하나의 문단에서는 72자를 초과할 때만 줄바꿈한다.
  7. 공개 API 변경 사항만 설명하며, 패키지 프라이빗 구현 상세는 포함하지 않는다.
  8. 테스트 코드에 대한 언급은 커밋 메시지에 포함하지 않는다.
  9. 제목에 fix:, feat:, docs: 등의 접두어를 사용하지 않는다.
  10. 제목은 첫 글자를 대문자로 시작한다. 단, 함수명 등 소문자가 합당한 경우만 예외를 허용한다.
  11. 도구 광고, 브랜딩, 홍보성 문구를 절대 포함하지 않는다.
  12. 커밋 전에는 반드시 파일을 개별 stage 한다.
  13. 커밋 전 work/scripts/check-commit-message-rules.sh 검증을 통과해야 한다.

16. AI 사용 규칙 (AI Interaction Rules)

  • 항상 테스트와 프로덕션 코드를 함께 생성한다.
  • 매우 작은 단위의 변경만 수행한다.
  • 대규모 리팩터링은 반드시 사전 승인을 요청한다.

✅ 본 문서는 AI와 사람이 동일한 개발 규칙을 공유하기 위한 최상위 기준 문서이며, ✅ 모든 신규 코드는 본 문서를 기준으로 검토된다.