docs: separate mission state workflow from decision records

.codex/skills/mission-close/SKILL.md

@@ -1,32 +1,29 @@
 ---
 name: mission-close
-description: Use when the user wants to close out a mission and write or update the mission document in docs/decisions. Trigger on phrases like "문서화하자", "회고 정리하자", or "decisions 문서로 남기자".
+description: Use when the user wants to close out a mission, summarize the active state from MISSIONS.md, and write the final decision document in docs/decisions. Trigger on phrases like "문서화하자", "회고 정리하자", or "decisions 문서로 남기자".
 ---
 
 # Mission Close
 
-이 스킬은 미션을 마무리하고 `docs/decisions` 문서를 정리하는 용도다.
+이 스킬은 미션을 마무리하고 `MISSIONS.md`의 진행 상태를 바탕으로 `docs/decisions` 문서를 정리하는 용도다.
 
 ## 반드시 할 일
 
 1. [AGENTS.md](../../../AGENTS.md)를 먼저 읽고 문서화 원칙을 따른다.
-2. [docs/decisions/README.md](../../../docs/decisions/README.md)와 [docs/templates/decision-record-template.md](../../../docs/templates/decision-record-template.md)를 참고한다.
-3. 현재 미션이 새 문서인지, 기존 문서 갱신인지 먼저 판단한다.
-4. 현재 PR/브랜치의 상태를 복원할 수 있도록 메타데이터를 남긴다.
-   - 관련 PR/브랜치
-   - 기준 브랜치
-   - 현재 상태
-   - 다음 시작점
+2. 루트 `MISSIONS.md`를 먼저 읽고 현재 미션의 목표, 검증, 작업 로그, 남은 이슈를 복원한다. 파일이 없다면 [docs/templates/mission-state-template.md](../../../docs/templates/mission-state-template.md)를 참고해 필요한 항목을 먼저 정리한다.
+3. [docs/decisions/README.md](../../../docs/decisions/README.md)와 [docs/templates/decision-record-template.md](../../../docs/templates/decision-record-template.md)를 참고한다.
+4. 현재 미션이 새 문서인지, 기존 문서 갱신인지 먼저 판단한다.
 5. 문서는 아래 흐름이 보이게 정리한다.
    - 문제
    - 선택
    - 이유
    - 검증
    - 결과와 남은 이슈
+6. 필요하면 `MISSIONS.md`의 현재 미션 상태를 완료 기준에 맞게 정리하거나 다음 미션 준비 상태로 갱신한다.
 
 ## 출력 원칙
 
 - 결과 자랑보다 고민과 판단의 흐름을 먼저 드러낸다.
 - 미션당 문서 하나 원칙을 우선한다.
-- decision 문서를 다음 세션의 상태 저장소처럼 사용할 수 있게 쓴다.
+- decision 문서는 최종 회고와 판단 기록으로만 쓴다.
 - 다음 미션으로 이어질 남은 이슈가 있으면 짧게 남긴다.

.codex/skills/mission-evaluate/SKILL.md

@@ -10,16 +10,17 @@ description: Use when the user says a mission is submitted or asks for explicit
 ## 반드시 할 일
 
 1. [AGENTS.md](../../../AGENTS.md)를 먼저 읽고 평가 기준을 따른다.
-2. 미션 요구사항, 현재 PR의 변경점, 사용자의 접근 방식, 검증 결과를 함께 본다.
-3. 관련 `docs/decisions` 문서가 있으면 거기에 남긴 목표와 남은 이슈도 함께 본다.
-4. 아래 순서로 평가한다.
+2. 루트 `MISSIONS.md`에서 현재 미션의 요구사항, 범위, 검증 계획을 먼저 확인하고, 없으면 [docs/templates/mission-state-template.md](../../../docs/templates/mission-state-template.md)를 기준으로 필요한 평가 기준을 복원한다.
+3. 현재 PR의 변경점, 사용자의 접근 방식, 실제 검증 결과를 함께 본다.
+4. 관련 `docs/decisions` 문서가 있으면 완료된 유사 미션의 판단이나 참고 맥락만 보조적으로 확인한다.
+5. 아래 순서로 평가한다.
    - 정합성과 버그 위험
    - 회귀 위험
    - 안정성
    - 성능
    - 설계
-5. 잘한 점보다 부족한 점과 남은 리스크를 먼저 정리한다.
-6. 미션 완료 기준을 충족했는지 분명히 말한다.
+6. 잘한 점보다 부족한 점과 남은 리스크를 먼저 정리한다.
+7. 미션 완료 기준을 충족했는지 분명히 말한다.
 
 ## 출력 원칙
 

.codex/skills/mission-guide/SKILL.md

@@ -10,15 +10,16 @@ description: Use when the user is actively solving the current mission and asks
 ## 반드시 할 일
 
 1. [AGENTS.md](../../../AGENTS.md)를 먼저 읽고 현재 미션 단계가 `guide` 관점인지 확인한다.
-2. 관련 `docs/decisions` 문서가 있으면 현재 PR/브랜치의 목표와 남은 이슈를 먼저 확인한다.
-3. 사용자의 현재 가설, 설계, 구현 상태를 먼저 요약한다.
-4. 바로 정답을 주지 말고 아래 순서를 우선한다.
+2. 루트 `MISSIONS.md`가 있으면 현재 목표, 진행 상태, 다음 시작점을 먼저 확인하고, 없으면 [docs/templates/mission-state-template.md](../../../docs/templates/mission-state-template.md)를 참고해 필요한 섹션을 먼저 세운다.
+3. 완료된 미션의 과거 판단이 필요할 때만 관련 `docs/decisions` 문서를 보조 자료로 참고한다.
+4. 사용자의 현재 가설, 설계, 구현 상태를 먼저 요약한다.
+5. 바로 정답을 주지 말고 아래 순서를 우선한다.
    - 질문
    - 코드 위치
    - 테스트/엣지 케이스
    - 설계 방향
    - 최소 예시
-5. 필요하면 함께 봐야 할 개념을 최대 3개 이하로만 연결한다.
+6. 필요하면 함께 봐야 할 개념을 최대 3개 이하로만 연결한다.
 
 ## 출력 원칙
 

.codex/skills/mission-interview/SKILL.md

@@ -10,15 +10,16 @@ description: Use when the user wants a mock interview after finishing a mission.
 ## 반드시 할 일
 
 1. [AGENTS.md](../../../AGENTS.md)를 먼저 읽고 `interviewer` 관점으로 전환한다.
-2. 관련 `docs/decisions` 문서가 있으면 직전 미션의 문제, 선택, 검증 결과, 남은 리스크를 거기서 먼저 복기한다.
-3. 직전 미션의 핵심 맥락을 짧게 정리한다.
-4. 질문은 아래 주제를 우선한다.
+2. 루트 `MISSIONS.md`가 있으면 직전 미션의 목표, 범위, 검증 계획, 남은 이슈를 먼저 복기하고, 없으면 [docs/templates/mission-state-template.md](../../../docs/templates/mission-state-template.md)를 기준으로 핵심 항목을 복원한다.
+3. 관련 `docs/decisions` 문서가 있으면 완료된 판단과 결과를 보조적으로 확인한다.
+4. 직전 미션의 핵심 맥락을 짧게 정리한다.
+5. 질문은 아래 주제를 우선한다.
    - 왜 이 문제를 그렇게 정의했는가
    - 왜 그 설계를 택했는가
    - 대안은 무엇이었는가
    - 실패/장애/고트래픽 상황에서는 어떻게 되는가
    - 무엇을 다시 개선할 것인가
-5. 질문은 한 번에 너무 많이 주지 말고, 답변 후 꼬리 질문이 가능하게 구성한다.
+6. 질문은 한 번에 너무 많이 주지 말고, 답변 후 꼬리 질문이 가능하게 구성한다.
 
 ## 출력 원칙
 

.codex/skills/mission-start/SKILL.md

@@ -12,15 +12,16 @@ description: Use when the user explicitly starts a new backend training mission,
 1. [AGENTS.md](../../../AGENTS.md)를 먼저 읽고 현재 운영 규칙을 따른다.
 2. 현재 브랜치와 작업 상태를 확인한다.
 3. 현재 작업 브랜치가 `develop`에서 갈라진 작업 브랜치라면 `develop...HEAD`와 working tree 변경점을 먼저 리뷰한다.
-4. 직전 미션이나 관련 `docs/decisions` 문서에서 이어서 볼 만한 맥락이 있으면 짧게 상기한다.
+4. 루트 `MISSIONS.md`가 있으면 직전 미션의 상태와 다음 시작점을 먼저 확인하고, 없으면 [docs/templates/mission-state-template.md](../../../docs/templates/mission-state-template.md)를 참고해 상태 파일을 바로 시작한다. 완료된 미션의 맥락이 필요할 때만 관련 `docs/decisions` 문서를 참고한다.
 5. 현재 저장소 기준으로 미션 후보 2~4개를 제안한다.
 6. 각 후보에 대해 아래만 짧게 제시한다.
    - 미션명
    - 왜 지금 적절한지
    - 학습 포인트
    - 난이도
 7. 가능하면 추천 미션 1개를 함께 제시한다.
-8. 현재 PR의 변경점과 직접 연결되는 미션이 있으면 우선순위를 높인다.
+8. 미션이 선택되면 `MISSIONS.md`에 현재 활성 미션 상태를 바로 남길 수 있게 목표와 다음 시작점을 분명하게 정리한다.
+9. 현재 PR의 변경점과 직접 연결되는 미션이 있으면 우선순위를 높인다.
 
 ## 출력 원칙
 

.gitignore

@@ -41,6 +41,7 @@ out/
 
 ### env ###
 .env.local
+MISSIONS.md
 
 ### firebase key ###
 firebase.json
@@ -56,4 +57,4 @@ monitoring/alertmanager.yml
 ### K6 data ###
 k6/data/**
 k6/reports/**
-k6/scripts/**
+k6/scripts/**

AGENTS.md

@@ -48,13 +48,13 @@
 
 1. 현재 브랜치와 작업 상태를 확인한다.
 2. 현재 작업 브랜치가 `develop`에서 갈라진 작업 브랜치라면 `develop...HEAD`와 working tree 변경점을 먼저 리뷰한다.
-3. 관련 `docs/decisions` 문서가 있으면 현재 PR/브랜치의 맥락과 남은 이슈를 짧게 상기한다.
+3. 루트 `MISSIONS.md`가 있으면 현재 활성 미션의 목표, 상태, 다음 시작점을 먼저 복원하고, 없으면 `docs/templates/mission-state-template.md`를 기준으로 새 상태 파일을 바로 만들 수 있게 안내한다.
 4. 미션 후보 2~4개를 제안한다.
 5. 사용자가 하나를 선택하거나 추천을 요청한다.
 6. 선택된 미션의 목표, 요구사항, 제한 조건, 먼저 볼 코드를 정리한다.
 7. 해결 중에는 `guide` 관점으로 돕는다.
 8. 제출 후에는 `evaluator`, 필요 시 `interviewer` 관점으로 이어간다.
-9. 마지막에는 `docs/decisions`에 미션 문서를 남긴다.
+9. 활성 미션이 시작되면 진행 중 상태를 `MISSIONS.md`에 바로 남기고, 마지막에는 `docs/decisions`에 최종 미션 문서를 남긴다.
 
 ## 명시적 호출 문구
 
@@ -92,10 +92,12 @@
 ## 문서화 원칙
 
 - `docs/architecture`는 현재 구조를 이해하기 위한 지도다.
-- `docs/decisions`는 미션 수행 중 내린 판단과 고민을 남기는 회고형 문서다.
+- 루트 `MISSIONS.md`는 현재 활성 미션의 상태를 관리하는 작업 파일이다.
+- `docs/templates/mission-state-template.md`는 `MISSIONS.md`를 시작할 때 복사하는 템플릿이다.
+- `docs/decisions`는 미션 종료 후 내린 판단과 고민을 남기는 회고형 문서다.
 - 기본 원칙은 `미션당 문서 하나`다.
-- 미션은 가능하면 PR 단위로 관리하고, 관련 `docs/decisions` 문서를 그 미션의 상태 저장소처럼 사용한다.
-- decision 문서에는 최소한 `관련 PR/브랜치`, `기준 브랜치`, `현재 상태`, `다음 시작점`을 남긴다.
+- 미션 진행 중에는 `MISSIONS.md`를 단일 상태 소스로 사용한다.
+- `docs/decisions`는 완료된 미션의 최종 판단과 결과만 남긴다.
 - 문서는 `문제 -> 선택 -> 이유 -> 검증 -> 결과와 남은 이슈`가 보이게 쓴다.
 
 ## 기본 학습 초점

README.md

@@ -9,6 +9,7 @@ Ling Level API는 학습 콘텐츠, 단어 학습, 스트릭, 추천, 알림 기
 ## 문서
 
 - [프로젝트 문서 허브](docs/README.md)
+- 활성 미션 상태 파일: 로컬 루트 `MISSIONS.md` (`docs/templates/mission-state-template.md` 기준)
 - [아키텍처 문서 모음](docs/architecture/)
 - [의사결정 기록 모음](docs/decisions/)
 

docs/README.md

@@ -13,6 +13,7 @@
 - 현재 구조, 도메인 관계, 대표 흐름을 정리할 때: [architecture](architecture/)
 - 미션을 수행하며 내린 큰 판단과 고민을 미션당 문서 하나로 남길 때: [decisions](decisions/)
 - 새 문서를 시작할 때: [templates](templates/)
+- 활성 미션 상태 파일이 필요할 때: [mission-state-template.md](templates/mission-state-template.md) 를 복사해 루트 `MISSIONS.md`로 사용
 
 ## 기본 원칙
 

docs/decisions/001-chapter-query-aggregation.md

@@ -1,13 +1,5 @@
 # Chapter 조회 N+1 문제를 Aggregation으로 해소
 
-## 미션 메타데이터
-
-- 관련 PR: [#197](https://github.com/SWM16-ASAP/back-server/pull/197)
-- 작업 브랜치: `미상`
-- 기준 브랜치: `develop`
-- 현재 상태: Aggregation 기반 조회 개선 회고 정리 완료. 추가 성능 측정과 주변 조회 패턴 점검은 남아 있다.
-- 다음 시작점: `content/book` 영역의 유사 반복 조회를 점검하고, 쿼리 로그나 부하 테스트로 실제 개선 폭을 측정한다.
-
 ## 문제
 
 `GET /api/books/{bookId}/chapters` 조회 시 챕터 목록을 가져온 뒤 각 챕터별 청크 개수를 다시 조회하는 구조였다.
@@ -35,3 +27,8 @@ Aggregation은 현재 MongoDB 구조를 크게 바꾸지 않으면서도 쿼리
 - `content/book` 영역 전체에서 비슷한 반복 조회가 더 있는지 추가 점검이 필요하다.
 - 실제 트래픽 기준 성능 개선 폭은 쿼리 로그나 부하 테스트로 별도 측정해두는 편이 좋다.
 - 집계 결과가 더 복잡해지면 응답 조합 로직을 별도 조회 모델로 분리할지 다시 검토할 수 있다.
+
+## 연관 이슈 및 PR
+
+- 관련 이슈: 없음
+- 관련 PR: [#197](https://github.com/SWM16-ASAP/back-server/pull/197)

docs/decisions/002-rate-limiting-with-bucket4j.md

@@ -1,13 +1,5 @@
 # Bucket4j와 Redis 기반 Rate Limiting 도입
 
-## 미션 메타데이터
-
-- 관련 PR: [#191](https://github.com/SWM16-ASAP/back-server/pull/191)
-- 작업 브랜치: `미상`
-- 기준 브랜치: `develop`
-- 현재 상태: Bucket4j와 Redis 기반 rate limit 도입 회고 정리 완료. 응답 형식 통일과 운영 데이터 기반 튜닝은 남아 있다.
-- 다음 시작점: 429 응답을 공통 예외 형식으로 맞추고, rate limit hit 메트릭을 노출해 정책 조정 근거를 만든다.
-
 ## 문제
 
 짧은 시간 안에 특정 사용자나 IP가 많은 요청을 보내면 서버 부하가 커지고, 악의적 요청에도 취약해질 수 있었다.
@@ -35,3 +27,8 @@ Redis는 이미 운영 중인 인프라였고, Bucket4j는 토큰 버킷 알고
 - 현재 429 응답은 단순 문자열 JSON이라 공통 예외 응답 형식과 통일할 여지가 있다.
 - 경로별 정책, 관리자 API 예외, burst 허용량 같은 세부 전략은 운영 데이터 기준으로 조정이 필요하다.
 - rate limit hit 수를 메트릭으로 노출하면 운영성과 튜닝 근거가 더 좋아진다.
+
+## 연관 이슈 및 PR
+
+- 관련 이슈: 없음
+- 관련 PR: [#191](https://github.com/SWM16-ASAP/back-server/pull/191)

docs/decisions/003-migrate-dev-infrastructure-to-on-premise.md

@@ -1,13 +1,5 @@
 # 개발 배포 환경을 온프레미스 기반으로 전환
 
-## 미션 메타데이터
-
-- 관련 PR: [#312](https://github.com/SWM16-ASAP/back-server/pull/312)
-- 작업 브랜치: `미상`
-- 기준 브랜치: `develop`
-- 현재 상태: 개발 배포 환경의 온프레미스 전환 회고 정리 완료. 운영 경계와 runbook 보강은 남아 있다.
-- 다음 시작점: 브랜치 트리거와 환경 문서를 정리하고, 백업·재시작·모니터링 기준을 runbook으로 남긴다.
-
 ## 문제
 
 기존 개발 배포 환경은 비용과 운영 방식 측면에서 현재 사용 패턴에 비해 무겁고 비효율적이었다.
@@ -35,3 +27,8 @@
 - 개발 배포와 운영 배포의 경계가 더 명확해야 하므로 브랜치 트리거와 환경 문서를 계속 정리할 필요가 있다.
 - 온프레미스 서버의 백업, 재시작 정책, 모니터링 기준은 runbook 형태로 추가 정리하는 편이 좋다.
 - R2 호환성 이슈처럼 저장소별 세부 설정 차이는 별도 기록으로 분리해 관리하는 것이 낫다.
+
+## 연관 이슈 및 PR
+
+- 관련 이슈: 없음
+- 관련 PR: [#312](https://github.com/SWM16-ASAP/back-server/pull/312)

docs/decisions/004-disable-r2-chunked-encoding.md

@@ -1,13 +1,5 @@
 # R2 서명 불일치를 피하기 위해 Chunked Encoding 비활성화
 
-## 미션 메타데이터
-
-- 관련 PR: [#314](https://github.com/SWM16-ASAP/back-server/pull/314)
-- 작업 브랜치: `미상`
-- 기준 브랜치: `develop`
-- 현재 상태: R2 호환 설정 조정 회고 정리 완료. 대용량 업로드 검증과 외부 스토리지 fallback 전략은 남아 있다.
-- 다음 시작점: 멀티파트와 대용량 업로드 호환성을 점검하고, 스토리지 장애나 지연에 대한 대응 전략을 분리 정리한다.
-
 ## 문제
 
 Cloudflare R2를 정적 파일 저장소로 사용하면서 S3 호환 API 요청의 서명이 맞지 않는 문제가 발생했다.
@@ -35,3 +27,8 @@ R2는 S3 호환이지만 완전 동일 구현이 아니므로, 서명 방식에
 - R2 전용 설정 항목이 늘어나면 `S3Config`를 저장소별 설정 클래스로 더 분리할 필요가 있다.
 - 멀티파트 업로드나 큰 파일 업로드에서 추가 호환성 이슈가 없는지 별도 확인이 필요하다.
 - 외부 스토리지 장애나 응답 지연에 대한 fallback 전략은 아직 별도 정리되지 않았다.
+
+## 연관 이슈 및 PR
+
+- 관련 이슈: 없음
+- 관련 PR: [#314](https://github.com/SWM16-ASAP/back-server/pull/314)

docs/decisions/005-ai-word-analysis-cost-and-reliability.md

@@ -1,13 +1,5 @@
 # AI 단어 분석 파이프라인의 비용과 안정성 개선
 
-## 미션 메타데이터
-
-- 관련 PR: [#185](https://github.com/SWM16-ASAP/back-server/pull/185), [#209](https://github.com/SWM16-ASAP/back-server/pull/209), [#211](https://github.com/SWM16-ASAP/back-server/pull/211)
-- 작업 브랜치: `미상`
-- 기준 브랜치: `develop`
-- 현재 상태: AI 단어 분석 비용·안정성 개선 회고 정리 완료. 실험 자료 분리 관리와 실패 유형 세분화는 남아 있다.
-- 다음 시작점: 비용 측정 자료를 별도 기록으로 분리하고, 단어 분석 실패 유형과 사용자 경험 fallback 전략을 보강한다.
-
 ## 문제
 
 영어 학습 서비스의 핵심 기능인 단어 검색과 단어장 생성은 AI 응답 품질에 직접 의존했다.
@@ -37,3 +29,8 @@ Spring AI와 Bedrock 기반 단어 분석 파이프라인을 도입하고, `homo
 - 모델 선택과 비용 비교 결과는 코드가 아니라 실험 기록 성격이 강하므로 별도 측정 자료와 함께 관리하는 편이 좋다.
 - 번역 fallback 같은 사용자 경험 보완 로직은 현재 저장소 문서와 별도로 다시 정리할 필요가 있다.
 - 단어 분석 실패 유형을 더 세분화하면 프롬프트 수정과 운영 대응이 더 빨라질 수 있다.
+
+## 연관 이슈 및 PR
+
+- 관련 이슈: 없음
+- 관련 PR: [#185](https://github.com/SWM16-ASAP/back-server/pull/185), [#209](https://github.com/SWM16-ASAP/back-server/pull/209), [#211](https://github.com/SWM16-ASAP/back-server/pull/211)

docs/decisions/006-personalized-push-notification-and-tracking.md

@@ -1,13 +1,5 @@
 # 개인화된 추천 PUSH와 캠페인 추적 체계 도입
 
-## 미션 메타데이터
-
-- 관련 PR: [#222](https://github.com/SWM16-ASAP/back-server/pull/222), [#253](https://github.com/SWM16-ASAP/back-server/pull/253), [#288](https://github.com/SWM16-ASAP/back-server/pull/288)
-- 작업 브랜치: `미상`
-- 기준 브랜치: `develop`
-- 현재 상태: 개인화 PUSH와 캠페인 추적 체계 도입 회고 정리 완료. 실험 설계와 빈도 제한 정책은 남아 있다.
-- 다음 시작점: 캠페인별 실험 기준과 A/B 구조를 정리하고, 사용자 피로도 기반 알림 빈도 제한 정책을 설계한다.
-
 ## 문제
 
 기존 PUSH 알림은 일괄 리마인드 성격이 강해서 사용자별 선호나 학습 패턴을 충분히 반영하지 못했다.
@@ -37,3 +29,8 @@
 - 리텐션 상승은 제품 전체 변화의 영향도 섞일 수 있으므로, 캠페인별 실험 기준을 더 분리할 필요가 있다.
 - 추천 점수와 메시지 전략을 실험할 A/B 구조는 아직 별도 체계가 없다.
 - 사용자 피로도와 알림 빈도 제한 정책은 추후 rate limit 성격으로 다시 정리할 수 있다.
+
+## 연관 이슈 및 PR
+
+- 관련 이슈: 없음
+- 관련 PR: [#222](https://github.com/SWM16-ASAP/back-server/pull/222), [#253](https://github.com/SWM16-ASAP/back-server/pull/253), [#288](https://github.com/SWM16-ASAP/back-server/pull/288)