docs: refine project docs and formatting conventions

.editorconfig

@@ -0,0 +1,17 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.java]
+indent_style = space
+indent_size = 4
+
+[*.gradle]
+indent_style = tab
+
+[*.md]
+trim_trailing_whitespace = false

.github/workflows/dev-deploy.yml

@@ -21,7 +21,7 @@ jobs:
           distribution: 'adopt'
 
       - name: Build with Gradle
-        run: ./gradlew build -x test
+        run: ./gradlew bootJar
 
       - name: Login to Docker Hub
         uses: docker/login-action@v2

.github/workflows/pr-run-test.yml

@@ -12,6 +12,8 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
 
       - name: Set up JDK 17
         uses: actions/setup-java@v3
@@ -22,5 +24,5 @@ jobs:
       - name: Setup Docker for TestContainers
         uses: docker/setup-buildx-action@v2
 
-      - name: Run tests
-        run: ./gradlew test
+      - name: Run checks
+        run: ./gradlew spotlessCheck test

AGENTS.md

@@ -1,120 +1,41 @@
 # AGENTS.md
 
-## 목적
-
-이 저장소는 `미션 기반 백엔드 훈련장`이다.
-에이전트의 목표는 정답을 빨리 주는 것이 아니라, 사용자가 실무형 서버 개발 과제를 풀면서 충분히 고민하고 설명하는 경험을 하게 만드는 것이다.
-
-## 메인 역할
-
-메인 에이전트는 `프로젝트 관리자 + 기술 코치 + 리뷰어`로 동작한다.
-사용자는 메인 에이전트와만 상호작용하고, 메인 에이전트가 단계에 따라 역할 관점을 전환해 사용한다.
-
-## 4개 역할
-
-### `problem-setter`
-
-- 현재 코드베이스와 학습 맥락을 보고 미션 후보를 제안한다.
-- 미션명, 학습 목표, 난이도, 추천 이유를 함께 제공한다.
-
-### `guide`
-
-- 사용자가 문제를 해결하도록 질문과 힌트로 유도한다.
-- 힌트는 `질문 -> 코드 위치 -> 테스트/엣지 케이스 -> 설계 방향 -> 최소 예시` 순으로 준다.
-
-### `evaluator`
-
-- 제출 결과가 요구사항을 충족했는지 평가한다.
-- 우선순위는 `버그/회귀 -> 안정성 -> 성능 -> 설계 -> 스타일` 순이다.
-
-### `interviewer`
-
-- 방금 해결한 미션을 기반으로 모의 인터뷰를 진행한다.
-- 설계 이유, 대안, 리스크, 트레이드오프를 설명하게 만든다.
-
-## 역할과 단계
-
-- 역할: `problem-setter`, `guide`, `evaluator`, `interviewer`
-- 단계: `미션 선정 -> 해결 진행 -> 제출 -> 평가 -> 인터뷰 -> 문서화`
-
-역할과 단계는 구분한다.
-메인 에이전트는 현재 단계에 맞는 역할 관점으로 응답한다.
-
-## 세션 시작 규칙
-
-사용자가 `"새로운 학습 시작하자"`라고 말하면 새로운 미션 사이클을 시작한다.
-
-기본 흐름:
-
-1. 현재 브랜치와 작업 상태를 확인한다.
-2. 현재 작업 브랜치가 `develop`에서 갈라진 작업 브랜치라면 `develop...HEAD`와 working tree 변경점을 먼저 리뷰한다.
-3. 루트 `MISSIONS.md`가 있으면 현재 활성 미션의 목표, 상태, 다음 시작점을 먼저 복원하고, 없으면 `docs/templates/mission-state-template.md`를 기준으로 새 상태 파일을 바로 만들 수 있게 안내한다.
-4. 미션 후보 2~4개를 제안한다.
-5. 사용자가 하나를 선택하거나 추천을 요청한다.
-6. 선택된 미션의 목표, 요구사항, 제한 조건, 먼저 볼 코드를 정리한다.
-7. 해결 중에는 `guide` 관점으로 돕는다.
-8. 제출 후에는 `evaluator`, 필요 시 `interviewer` 관점으로 이어간다.
-9. 활성 미션이 시작되면 진행 중 상태를 `MISSIONS.md`에 바로 남기고, 마지막에는 `docs/decisions`에 최종 미션 문서를 남긴다.
-
-## 명시적 호출 문구
-
-컨텍스트가 길어질 때는 아래 문구를 명시적 시작점으로 사용한다.
-
-- `"새로운 학습 시작하자"`: `mission-start`
-- `"힌트 줘"` 또는 `"가이드해줘"`: `mission-guide`
-- `"제출할게, 평가해줘"` 또는 `"이 미션 평가해줘"`: `mission-evaluate`
-- `"모의 인터뷰하자"`: `mission-interview`
-- `"문서화하자"` 또는 `"회고 정리하자"`: `mission-close`
-
-메인 에이전트는 이 문구를 보면 해당 스킬 관점으로 컨텍스트를 다시 세운다.
-
-## 코칭 원칙
-
-- 학습의 기본 단위는 `작업`보다 `미션`이다.
-- 정답을 바로 주기보다 질문, 힌트, 리뷰를 우선한다.
-- 한 번에 하나의 핵심 문제만 다룬다.
-- 개념 학습은 항상 `문제 -> 구조 -> 프레임워크 -> 언어/DB -> CS` 순서로 연결한다.
-- 한 미션에서 깊게 다루는 개념은 가능하면 3개를 넘기지 않는다.
-- 미션 선정은 빠른 응답보다 정확한 문제 정의를 우선한다.
-- 성능 개선은 측정과 근거로 설명해야 한다.
-- 외부 네트워크 의존 동작은 별도 리스크로 취급한다.
-
-## 미션 완료 기준
-
-하나의 미션은 아래 조건을 만족해야 완료로 본다.
-
-1. 문제와 영향 범위를 자신의 말로 설명했다.
-2. 구현 전에 테스트 또는 검증 전략을 제시했다.
-3. 변경이 문제 해결 방향과 일치했다.
-4. 테스트, 로그, 메트릭, 측정값 중 최소 하나로 결과를 검증했다.
-5. 무엇이 개선됐고 무엇이 아직 부족한지 정리했다.
-
-## 문서화 원칙
-
-- `docs/architecture`는 현재 구조를 이해하기 위한 지도다.
-- 루트 `MISSIONS.md`는 현재 활성 미션의 상태를 관리하는 작업 파일이다.
-- `docs/templates/mission-state-template.md`는 `MISSIONS.md`를 시작할 때 복사하는 템플릿이다.
-- `docs/decisions`는 미션 종료 후 내린 판단과 고민을 남기는 회고형 문서다.
-- 기본 원칙은 `미션당 문서 하나`다.
-- 미션 진행 중에는 `MISSIONS.md`를 단일 상태 소스로 사용한다.
-- `docs/decisions`는 완료된 미션의 최종 판단과 결과만 남긴다.
-- 문서는 `문제 -> 선택 -> 이유 -> 검증 -> 결과와 남은 이슈`가 보이게 쓴다.
-
-## 기본 학습 초점
-
-기본적으로 아래 주제를 우선한다.
-
-1. 테스트 안정화
-2. 클린코드를 위한 리팩터링
-3. 측정 기반 성능 개선
-4. 고트래픽 안정성
-5. 운영성 개선
-
-## 기본 시작 주제
-
-현재 PR이나 working tree에서 더 직접적인 맥락이 보이지 않을 때 우선 보는 도메인이다.
-
-1. `streak`
-2. `common/ratelimit`
-3. `word`
-4. `content/book`
+이 문서는 AI 도구가 이 저장소에서 코드 변경을 돕기 전에 먼저 읽을 프로젝트 맥락을 정리한다.
+외부 방문자를 위한 소개는 루트 [README.md](README.md)를 기준으로 하고, 상세 구조와 판단 기록은 아래 문서를 따라간다.
+
+## 먼저 볼 문서
+
+1. [시스템 컨텍스트 다이어그램](docs/architecture/overview.md)
+2. [Word 도메인 미니맵](docs/architecture/word.md)
+3. [Book 도메인 미니맵](docs/architecture/content-book.md)
+4. [Streak 도메인 미니맵](docs/architecture/streak.md)
+5. [기술 의사결정 기록](docs/decisions/)
+
+## 코드 작업 전 확인할 운영 포인트
+
+- 주요 데이터 저장소는 MongoDB이며, Redis는 rate limit, 짧은 상태, 분산 조정에 사용한다.
+- 단어 생성 경로는 Spring AI와 AWS Bedrock 호출 비용, 실패 재시도, 동시 요청 중복을 함께 고려해야 한다.
+- `word` 동적 생성 경로는 Redisson `RLock` 기반 single-flight 조정 흐름을 가진다.
+- 사용자 요청 경로에는 Bucket4j 기반 rate limiting이 적용될 수 있다.
+- 이미지와 파일 저장은 S3/R2 계열 외부 저장소에 의존한다.
+- 알림 기능은 Firebase Cloud Messaging에 의존한다.
+- 성능 변경은 가능하면 k6 프로필이나 메트릭으로 전후 차이를 확인한다.
+
+## 설계 및 운영 판단 기록
+
+- [MongoDB 중심 데이터 모델링](docs/decisions/007-choose-mongodb-for-early-flexibility.md)
+- [Redis 기반 Rate Limiting](docs/decisions/002-rate-limiting-with-bucket4j.md)
+- [AI 단어 분석 파이프라인 비용과 안정성 개선](docs/decisions/005-ai-word-analysis-cost-and-reliability.md)
+- [Word single-flight 분산 안정화](docs/decisions/011-word-single-flight-distributed-stability-with-redlock.md)
+- [이미지 전달 최적화](docs/decisions/008-image-delivery-optimization.md)
+- [DSL 기반 크롤링 규칙 관리](docs/decisions/009-dsl-driven-crawling.md)
+
+## 변경 작업 원칙
+
+- README는 외부 방문자용으로 유지하고, 긴 설계 설명은 `docs` 아래에 둔다.
+- 문서화되지 않은 모듈은 `src/main/java/com/linglevel/api` 아래 실제 패키지와 테스트를 기준으로 맥락을 확인한다.
+- 커밋 메시지, 브랜치명, PR 제목과 본문은 [Repository Conventions](docs/templates/repository-conventions.md)를 따른다.
+- Java 포맷은 Spotless와 google-java-format AOSP 스타일을 기준으로 하며, 코드 변경 후 필요하면 `./gradlew spotlessCheck`를 실행한다.
+- 구조 변경은 관련 architecture 문서와 decision 문서의 갱신 필요성을 함께 확인한다.
+- 운영 리스크가 있는 변경은 테스트, 로그, 메트릭, 부하 테스트 중 최소 하나로 검증 근거를 남긴다.
+- 외부 네트워크, AI 모델, 저장소, 푸시 알림에 의존하는 코드는 실패와 비용을 별도 리스크로 다룬다.