Skip to content

AGENTS.md

Latest commit

 

History

History
361 lines (249 loc) · 10.1 KB

AGENTS.md

File metadata and controls

361 lines (249 loc) · 10.1 KB
Raw

AGENTS.md

0. 목적

이 문서는 이 백엔드 프로젝트에서 AI와 함께 작업할 때 따르는 전역 작업 계약서다.

역할은 분명하게 나눈다.

  • AGENTS.md: 전역 규칙, 승인 방식, 검증 기준, 결과 보고 형식
  • docs/ai/: AI 협업 절차와 템플릿
  • docs/improvements/{topic}/: 실제 개선 작업 산출물
  • private_docs/: 과거 참고자료와 보관용 문서. 새 작업의 기본 위치로 쓰지 않는다.

1. 우선순위

판단 기준의 우선순위는 아래와 같다.

  1. AGENTS.md
  2. private_docs/prev/specification/Function_Specification.csv
  3. docs/improvements/{topic}/에 정리된 현재 작업 결정
  4. 현재 코드베이스 구조와 제약

명세와 코드가 충돌하면 추측 구현하지 않고 충돌 지점을 먼저 보고하고 승인받는다.

2. 프로젝트 구조

2-1. Gradle 서브프로젝트

  • Apps
    • apps/api-user
    • apps/api-admin
    • apps/transcoder
  • Modules
    • modules/domain
    • modules/common-web
    • modules/common-security
    • modules/infra-db
    • modules/infra-mq
    • modules/infra-s3

2-2. 지원 디렉토리

  • apps/machine: AI 서버
  • apps/monitoring: Prometheus/Grafana/Pinpoint 관련 설정
  • k6/: 부하 테스트 스크립트와 결과 파서
  • docs/ai/: AI 협업 절차
  • docs/improvements/: 주제별 개선 문서

3. 기본 작업 순서

모든 작업은 아래 순서를 기본으로 한다.

  1. 구조 파악
  2. 수정안 또는 문서안 제시
  3. 수정 파일 목록 기준 승인 요청
  4. 수정
  5. 검증
  6. 결과 공유

큰 작업은 단계별로 쪼개서 진행한다.

실패 시에는 아래 순서로 보고한다.

  1. 원인
  2. 재현 명령
  3. 해결안

4. 승인 규칙

  • 모든 파일 수정/생성/삭제는 사전 승인 후 진행한다.
  • 승인 요청은 파일별 목록으로 제시한다.
  • 승인되지 않은 파일은 수정하지 않는다.
  • 작업 도중 설계가 바뀌거나 범위가 커지면 다시 승인받는다.

예외는 없다. 문서 작업도 동일하다.

5. 커뮤니케이션 원칙

  • 답변 맨 처음에 요약을 둔다.
  • 장황한 설명보다 결론, 원인, 다음 액션을 먼저 말한다.
  • 모든 작업은 단계별로 쪼개서 정리한다.
  • 불확실하면 추측하지 말고 현재 코드, 로그, 상태를 먼저 확인한다.
  • 작업 완료 시에는 작업 요약, 다음 작업, 남은 작업을 함께 적는다.

6. 문서 운영 규칙

6-1. 새 문서 위치

  • AI 협업 절차와 템플릿: docs/ai/
  • 실제 개선 산출물: docs/improvements/{topic}/

6-2. topic 문서 기본 구성

작업 규모에 따라 필요한 문서만 만든다.

권장 기본 구성

  • 001-overview.md
  • 002-as-is.md
  • 003-adr.md
  • 004-implementation.md
  • 005-benchmark.md

작은 작업은 001-overview.md, 002-as-is.md, 003-adr.md만으로도 충분하다.

6-3. 문서 작성 원칙

  • 전체 대화 로그를 그대로 남기지 않는다.
  • 측정값, 선택 이유, 버린 대안, 다음 액션이 남아야 한다.
  • "빨라질 것이다"가 아니라 현재 수치와 목표 수치로 적는다.
  • 대안 비교, before/after, 작업 단계, 리스크는 가능하면 Markdown 표로 정리한다.
  • query 세팅처럼 메인이 아닌 보조 단계는 문서를 과하게 늘리지 않고 overview나 adr에 흡수해도 된다.
  • 구현 전 문서에는 가능하면 구체적인 구현 설계도 남긴다.
    • 변경할 메서드/쿼리 시그니처
    • 레이어별 책임
    • 예외/경계 케이스 처리
    • 테스트 시나리오

7. 코드/모듈 구조 원칙

  • 공통 DTO, 응답, 예외는 modules/common-web에 둔다.
  • 도메인 엔티티와 enum은 modules/domain에 둔다.
  • 인프라 구현은 modules/infra-*에 둔다.
  • 앱은 공통 모듈을 의존해서 사용한다.
  • 앱에 중복 DTO/유틸을 만들지 않는다.

API 규칙

  • 엔티티 직접 응답 금지
  • DTO로 변환 후 반환
  • 공통 응답 포맷을 우선 사용
  • Page, Pageable 변환은 서비스 레이어에서 처리
  • 서비스에서 PageInfo.builder()로 조합 후 응답 전달

네이밍 규칙

  • 컬렉션 변수명은 의미 + List 접미사 형태를 사용한다.
  • 단순 복수형으로 끝나는 이름은 지양한다.

8. 핵심 기능 불변조건

아래는 작업 중 깨지면 안 되는 핵심 규칙이다.

인증/권한

  • 사용자 로그인: 카카오 OAuth2 기반
  • 관리자 로그인: 사용자 로그인과 분리된 경로
  • 권한: USER, EDITOR, ADMIN 구분을 API 단에서 강제
  • EDITOR는 백오피스 접근 가능하지만 롱폼 업로드, 시리즈 관리, 사용자 관리, 대시보드는 제한

홈/검색

  • 인기 차트 기준: 북마크 수
  • 검색: 제목 부분일치, 숏폼 제외
  • 섹션 최대 노출: 20개 기준

콘텐츠 상호작용

  • 댓글 최대 100자
  • 댓글 목록 최신순
  • 스포일러는 작성 시 플래그, 기본 숨김
  • 시리즈 에피소드 좋아요/북마크는 시리즈 단위 저장/집계

플레이어/Playback

  • HLS(m3u8) 기반
  • 롱폼: auto/1080p/720p/360p
  • 숏폼: 자동 화질만, 이어보기 미지원
  • 이어보기 저장 간격 기본값: 10초

마이페이지

  • 시청 이력 조회 범위: 최근 3개월
  • 태그 통계는 태그명 기준 합산

백오피스/업로드

  • 시리즈 등록 시 포스터/썸네일 모두 필수
  • 에피소드 업로드 시 카테고리/태그는 시리즈를 따름
  • 숏폼 업로드: EDITOR, ADMIN
  • 롱폼 업로드: ADMIN만 가능

인제스트

  • 상태 전이: UPLOADING -> ANALYZING -> TRANSCODING -> PACKAGING -> DONE|FAILED|CANCELED
  • 이벤트는 재처리 가능하고 중복 안전해야 한다.

9. Media 전환 규칙

Media 전환 이후 신규 코드는 아래를 따른다.

  • series, contents, short_form의 공통 속성은 media 경유 접근을 기본으로 한다.
  • 구 상세 테이블 컬럼 직접 참조를 신규 코드에서 만들지 않는다.
  • 태그/조회 로직은 media_tag 기준을 우선 고려한다.
  • DDL 변경 시 엔티티, 리포지토리, API 매퍼를 같은 변경 단위로 반영한다.

운영 전제

  • V2__media_table_inheritance.sql은 빈 DB 전용 마이그레이션으로 간주한다.
  • 기존 데이터가 있는 환경에서는 직접 적용하지 않는다.

10. DB / Flyway / 실행 규칙

DB / Flyway

  • 마이그레이션 위치: modules/infra-db/src/main/resources/db/migration
  • 파일명: V{version}__{desc}.sql
  • 운영 기준: ddl-auto: validate
  • Flyway 실행 주체: api-user
  • 스키마 변경 시 SQL, 엔티티, 영향 범위를 함께 보고한다.

Docker

  • 시작: docker compose up -d --build
  • 상태: docker compose ps -a
  • 로그: docker compose logs -f [service]
  • 종료: docker compose down
  • 완전 초기화: docker compose down -v

장애 패턴 메모

  • api-admin 또는 transcoder만 죽으면 Flyway validate 레이스를 먼저 의심한다.
  • flyway_schema_history가 비어 있으면 마이그레이션 포함 여부와 api-user 로그를 먼저 본다.

11. 검증 규칙

기본 검증 명령

  • 컴파일: ./gradlew clean build -x test
  • 전체 테스트: ./gradlew test
  • 모듈 테스트
    • ./gradlew :apps:api-user:test
    • ./gradlew :apps:api-admin:test
    • ./gradlew :apps:transcoder:test

가능하면 실행 로그 또는 핵심 출력까지 확인해서 공유한다.

DB 변경이 있으면 아래도 확인한다.

  • Flyway 적용 로그
  • api-user 부팅 성공 여부

12. 성능/구조 개선 작업 규칙

성능 또는 구조 개선은 가능하면 아래 순서를 유지한다.

  1. 측정
  2. 원인 가설
  3. 대안 비교
  4. 사용자 승인
  5. 구현
  6. 재측정

금지 사항

  • 측정 없이 "개선되었다"고 쓰지 않는다.
  • 대안 없이 바로 구현하지 않는다.
  • 현재 작업 중 나온 새 아이디어를 범위에 끼워 넣지 않는다.

13. 결과 보고 형식

작업 결과는 아래 형식을 기본으로 한다.

  • 결론: 무엇을 왜 바꿨는지
  • 변경 파일: 경로 목록
  • 검증: 실행 명령, 성공/실패, 핵심 로그
  • 명세 반영 체크: 어떤 규칙을 충족했는지
  • 리스크/미결정: 남은 이슈와 확인 필요 사항
  • 다음 액션: 바로 이어서 할 수 있는 작업
  • 남은 작업
  • 바로 다음 작업 계획 및 승인 요청

13-1. Commit / PR 규칙

  • 커밋 메시지는 현재 저장소 관례에 맞춰 [TYPE]: 요약 형식을 기본으로 사용한다.
  • 권장 TYPE
    • [FEAT]
    • [FIX]
    • [REFACTOR]
    • [DOCS]
    • [TEST]
    • [CHORE]
  • 가능하면 한 커밋에는 한 가지 주제만 담는다.
  • PR 작성 시에는 .github/PULL_REQUEST_TEMPLATE.md를 기준으로 내용을 채운다.
  • PR 또는 최종 공유에는 아래 항목이 드러나야 한다.
    • 무엇을 바꿨는가
    • 왜 바꿨는가
    • 어떻게 검증했는가
    • 남은 리스크가 무엇인가
    • DB/Flyway 영향이 있는가

14. 완료 기준

작업 완료로 보려면 아래를 만족해야 한다.

  • 요구 기능 또는 목적이 명세와 합치된다.
  • 권한, 검증, 예외 케이스가 반영된다.
  • 관련 테스트가 추가 또는 갱신된다.
  • 빌드/테스트/실행 검증 결과를 보고한다.
  • 남은 리스크와 후속 작업을 명시한다.

15. Pre-PR Self Review Checklist

PR 또는 최종 변경 전에는 현재 diff 기준으로 아래를 점검한다.

P0

  • 컴파일/부팅 실패 없는가
  • 트랜잭션 경계가 명확한가
  • 데이터 정합성/무결성에 문제 없는가
  • 동시성/멱등성 문제 없는가
  • 권한/보안 누락 없는가
  • DB 마이그레이션이 안전한가

P1

  • API 계약 일관성 유지되는가
  • 조회/페이징/쿼리 품질 문제 없는가
  • 시간/상태 처리 경계가 타당한가
  • 외부 연동 실패 시 장애 내성이 있는가

P2

  • 모듈 경계 준수
  • 중복 코드/매직넘버 최소화
  • 핵심 로그/관측성 보강 여부
  • 테스트 가독성

최종 공유 시에는 가능하면 P0/P1/P2 + 근거 파일/라인 + 수정안 형식으로 정리한다.