Development Guide

Development Guide

작업 시작

작업 브랜치는 GitHub Issue와 연결하고 feat/{issue-number} 형식을 사용합니다.

git fetch origin
git checkout -b feat/123 origin/dev

현재 작업 디렉터리에 다른 변경이 있다면 덮어쓰지 않습니다. 별도 worktree를 사용해 작업을 분리합니다.

브랜치

목적	시작점	브랜치	병합 대상
일반 작업	dev	feat/{issue-number}	dev
정식 릴리즈 QA	dev	release/v{MAJOR.MINOR.PATCH}	main
릴리즈 QA 수정	대상 release/v{버전}	fix/{issue-number}	대상 release/v{버전}
긴급 수정	main	hotfix/{issue-number}	main

기능 작업은 Issue를 만든 뒤 feat/*에서 시작합니다. 정식 릴리즈와 hotfix의 버전 결정, QA, 역병합 순서는 Release Management를 따릅니다.

변경 순서

1. 관련 Controller, Service, Repository, DTO와 테스트를 찾습니다.
2. 실패를 재현하는 가장 작은 테스트를 추가합니다.
3. 기존 구조를 유지하며 필요한 코드만 수정합니다.
4. 관련 테스트를 먼저 실행합니다.
5. 설정, 보안, DB, 외부 연동 변경이면 전체 테스트를 실행합니다.
6. 공개 API가 바뀌면 Swagger 문서 인터페이스를 갱신합니다.
7. DB가 바뀌면 Flyway SQL을 추가합니다.

테스트

관련 테스트만 실행합니다.

./gradlew test --tests 'com.chukchuk.haksa.application.portal.PortalLinkJobServiceUnitTests'

전체 테스트를 실행합니다.

./gradlew test

CI와 같은 검증을 실행합니다.

./gradlew check --stacktrace --no-daemon

CI는 dev와 main의 push·PR에서 check를 실행합니다. 실패하면 로그의 첫 번째 원인을 해결한 뒤 전체 명령을 다시 실행합니다.

API 변경

• Controller의 path와 HTTP method를 확인합니다.
• 요청·응답 DTO의 Swagger annotation을 갱신합니다.
• 해당 controller/docs 인터페이스를 갱신합니다.
• 인증 공개 범위가 바뀌면 SecurityConfig를 검토합니다.
• Controller 테스트와 Service 테스트를 함께 갱신합니다.
• 로컬 /v3/api-docs와 Swagger UI에서 변경이 보이는지 확인합니다.

공개 endpoint를 추가하면서 Security 설정을 빼먹으면 인증되지 않은 호출이 401이 됩니다. 반대로 보호 endpoint를 공개 목록에 넣으면 보안 문제가 됩니다.

DB와 Flyway

마이그레이션 파일은 src/main/resources/db/migration에 둡니다. 현재 마지막 버전의 다음 번호를 사용합니다.

V9__describe_the_schema_change.sql

규칙입니다.

• 이미 dev 또는 prod에 적용된 파일은 수정하지 않습니다.
• 수정이 필요하면 다음 버전의 보정 마이그레이션을 추가합니다.
• 테이블, 컬럼, 인덱스, 제약 조건 변경을 Java 코드로만 끝내지 않습니다.
• dev·prod에서 Hibernate ddl-auto를 스키마 변경 수단으로 사용하지 않습니다.
• 대용량 UPDATE나 lock 가능성이 있는 DDL은 적용 시간과 복구 방안을 PR에 적습니다.

배포 전에 GitHub Actions가 flyway info와 migrate를 실행합니다. 마이그레이션이 실패하면 Lambda 배포는 시작하지 않습니다.

포털 연동 변경

포털 연동은 API, DB, SQS, Worker, HMAC, S3가 연결된 흐름입니다. 한 컴포넌트만 보고 완료를 판단하지 않습니다.

확인할 항목입니다.

• Idempotency-Key 재사용과 충돌.
• scrape_jobs와 scrape_job_outbox의 같은 트랜잭션 저장.
• SQS 발행 성공과 queue_message_id 저장.
• 콜백 원문 Body 기반 HMAC 검증.
• S3 Bucket, Prefix, job scope 검증.
• 중복 콜백 멱등성.
• 실패 시 error_code, retryable, 종료 시각 저장.
• 성공 후 사용자·학사·졸업 데이터 반영.

관련 핵심 테스트는 src/test/java/com/chukchuk/haksa/application/portal, infrastructure/portal, infrastructure/security에 있습니다.

로그와 개인정보

• 포털 username·password, request_payload_json, Outbox payload_json을 출력하지 않습니다.
• JWT, OIDC ID Token, HMAC Secret, DB 비밀번호를 출력하지 않습니다.
• 진단에는 jobId, outboxId, workerRequestId, 오류 code, hash를 사용합니다.
• 사용자 식별자가 필요한 Sentry tag는 기존 SentryMdcContext 경로를 사용합니다.

커밋과 PR

커밋 메시지는 Issue 번호, type, 한국어 설명 순서로 작성합니다.

{issue-number} {type}: {message}

type은 변경의 주된 목적을 기준으로 선택합니다.

type	용도
feat	기능 추가
fix	버그 수정
refactor	동작을 유지하는 코드 구조 변경
docs	문서 수정
test	테스트 추가·수정
chore	빌드, 패키지, 개발 환경 설정 변경
comment	주석만 추가·수정
style	동작 변화가 없는 코드 형식 변경
rename	파일·디렉터리 이름 변경
remove	파일·기능 제거

한 커밋은 한 문장으로 설명할 수 있는 변경만 포함합니다. 기능, 문서, 설정처럼 독립적으로 되돌릴 수 있는 변경은 가능한 한 나눕니다.

123 feat: 포털 작업 상태 조회 추가
123 fix: 콜백 중복 처리 보정
123 docs: 운영 장애 대응 절차 추가

PR에는 변경 이유, API·DB 영향, 테스트 명령과 결과, 배포·롤백 방법을 적습니다. Wiki에 영향을 주는 변경이면 수정할 페이지를 함께 적습니다.

기존 API 사용 방식에 영향을 주는 변경은 commit type만으로 표시하지 않습니다. PR 본문에 영향받는 client, 이전 방법, 전환 방법을 구체적으로 적습니다.

문서와 Wiki

문서마다 책임을 분리해 같은 규칙을 여러 위치에서 관리하지 않습니다.

문서	책임
README.md	프로젝트 소개와 주요 문서의 진입점
AGENTS.md	AI Agent가 반드시 지켜야 하는 짧고 지속적인 실행 규칙
Development Guide	사람을 위한 일반 작업 브랜치, 커밋, 테스트, PR, 문서 갱신 절차
Release Management	버전, 정식 릴리즈, hotfix, 태그, GitHub Release, 릴리즈 노트
Project Architecture와 Core Domain Flows	현재 런타임 구조와 핵심 처리 흐름
Deployment and Operations와 Troubleshooting	배포, 관측, 복구 Runbook
Troubleshooting Case Studies	실제 장애의 관측, 원인, 해결, 결과, 재발 방지
Architecture Decision Records	기술 결정의 맥락, 대안, 결과, 재검토 조건

Wiki 갱신 판단

작업을 끝내기 전에 변경 유형과 관련 페이지를 확인합니다.

변경 유형	기본 조치
공개 API, 요청·응답, 오류 code	API and Authentication과 실행 중인 Swagger를 확인합니다.
인증·인가·OIDC·내부 서명	API and Authentication을 갱신하고 결정이 바뀌면 ADR을 추가합니다.
DB schema·Flyway·핵심 domain rule	Development Guide, Project Architecture, Core Domain Flows 중 영향을 받는 페이지를 갱신합니다.
외부 연동·비동기 처리 흐름	Core Domain Flows와 관련 ADR을 갱신합니다.
버전, release·hotfix 흐름, 태그, GitHub Release, 릴리즈 노트	Release Management를 갱신합니다.
배포 실행, rollback·환경 설정	Deployment and Operations를 갱신합니다.
로그·metric·장애 대응 절차	Troubleshooting을 갱신합니다.
재사용할 가치가 있는 장애·성능 개선	Troubleshooting Case Studies에 문제, 관측, 원인, 해결, 결과, 재발 방지를 기록합니다.
새로운 architecture 결정 또는 기존 결정 대체	기존 ADR을 덮어쓰지 않고 새 ADR을 추가합니다.
내부 refactor·test-only·문서에 영향 없는 수정	Wiki를 수정하지 않고 최종 작업 결과에 이유를 적습니다.

Wiki 게시 절차

1. 코드와 설정을 근거로 현재 동작을 확인합니다.
2. 관련 Wiki 페이지만 수정하고 추측한 리소스 이름이나 환경 값을 쓰지 않습니다.
3. secret, token, 사용자 원문 데이터가 포함되지 않았는지 확인합니다.
4. 내부 링크와 외부 참고 링크를 검증합니다.
5. 별도 Wiki 저장소에 문서 변경을 커밋하고 master에 push합니다.
6. GitHub 공개 페이지에서 본문, 목차, Sidebar 링크가 렌더링되는지 확인합니다.
7. 코드 PR에 수정한 Wiki 페이지 링크를 남깁니다.

Wiki 본문을 코드에서 자동 생성하지 않습니다. 작업을 수행하는 개발자나 AI Agent가 실제 코드와 배포 상태를 확인한 뒤 필요한 페이지를 직접 갱신합니다.