From ecfb014abba45112cd10eac5c0e19fb5aefe4767 Mon Sep 17 00:00:00 2001 From: solfe Date: Sun, 29 Mar 2026 23:18:06 +0900 Subject: [PATCH 1/2] docs: simplify decision record metadata --- docs/decisions/001-chapter-query-aggregation.md | 13 +++++-------- docs/decisions/002-rate-limiting-with-bucket4j.md | 13 +++++-------- ...03-migrate-dev-infrastructure-to-on-premise.md | 13 +++++-------- docs/decisions/004-disable-r2-chunked-encoding.md | 13 +++++-------- .../005-ai-word-analysis-cost-and-reliability.md | 13 +++++-------- ...personalized-push-notification-and-tracking.md | 13 +++++-------- .../007-choose-mongodb-for-early-flexibility.md | 13 +++++-------- docs/decisions/008-image-delivery-optimization.md | 13 +++++-------- docs/decisions/009-dsl-driven-crawling.md | 13 +++++-------- .../010-mission-oriented-agent-guidelines.md | 15 ++++++--------- docs/decisions/README.md | 3 +-- docs/templates/decision-record-template.md | 13 +++++-------- 12 files changed, 57 insertions(+), 91 deletions(-) diff --git a/docs/decisions/001-chapter-query-aggregation.md b/docs/decisions/001-chapter-query-aggregation.md index 8e22077..0cef85e 100644 --- a/docs/decisions/001-chapter-query-aggregation.md +++ b/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) diff --git a/docs/decisions/002-rate-limiting-with-bucket4j.md b/docs/decisions/002-rate-limiting-with-bucket4j.md index ed5097e..ec0a7c5 100644 --- a/docs/decisions/002-rate-limiting-with-bucket4j.md +++ b/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) diff --git a/docs/decisions/003-migrate-dev-infrastructure-to-on-premise.md b/docs/decisions/003-migrate-dev-infrastructure-to-on-premise.md index 7c5b244..2a5f78c 100644 --- a/docs/decisions/003-migrate-dev-infrastructure-to-on-premise.md +++ b/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) diff --git a/docs/decisions/004-disable-r2-chunked-encoding.md b/docs/decisions/004-disable-r2-chunked-encoding.md index 6ed51c2..05fb4d3 100644 --- a/docs/decisions/004-disable-r2-chunked-encoding.md +++ b/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) diff --git a/docs/decisions/005-ai-word-analysis-cost-and-reliability.md b/docs/decisions/005-ai-word-analysis-cost-and-reliability.md index 662f7fc..a47882a 100644 --- a/docs/decisions/005-ai-word-analysis-cost-and-reliability.md +++ b/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) diff --git a/docs/decisions/006-personalized-push-notification-and-tracking.md b/docs/decisions/006-personalized-push-notification-and-tracking.md index c4e77a0..0c73fb6 100644 --- a/docs/decisions/006-personalized-push-notification-and-tracking.md +++ b/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) diff --git a/docs/decisions/007-choose-mongodb-for-early-flexibility.md b/docs/decisions/007-choose-mongodb-for-early-flexibility.md index 561afd9..3a2b5ef 100644 --- a/docs/decisions/007-choose-mongodb-for-early-flexibility.md +++ b/docs/decisions/007-choose-mongodb-for-early-flexibility.md @@ -1,13 +1,5 @@ # 서비스 초기 데이터 저장소를 MongoDB 중심으로 고정 -## 미션 메타데이터 - -- 관련 PR: 미상 -- 작업 브랜치: `미상` -- 기준 브랜치: `develop` -- 현재 상태: 초기 저장소 전략에 대한 회고 정리 완료. 저장소 분리 기준과 MongoDB 활용 경계 정리는 남아 있다. -- 다음 시작점: Aggregation·인덱스·문서 구조 튜닝 기준을 정리하고, 관계형 저장소 분리 신호와 MongoDB 활용 범위를 명확히 한다. - ## 문제 서비스 초기에는 기능 요구사항과 응답 형태가 빠르게 바뀌는 반면, 운영 비용은 제한적이었다. @@ -36,3 +28,8 @@ - 조회가 복잡해질수록 Aggregation, 인덱스, 문서 구조 튜닝이 더 중요해지므로 MongoDB의 비용이 뒤늦게 커질 수 있다. - 관계형 쿼리에 더 잘 맞는 영역이 생기면 저장소를 분리할지 다시 판단해야 한다. - TTL, 벡터 저장, 로그 저장 등 MongoDB 활용 범위는 실제 운영 패턴에 맞춰 더 명확히 구분할 필요가 있다. + +## 연관 이슈 및 PR + +- 관련 이슈: 없음 +- 관련 PR: 없음 diff --git a/docs/decisions/008-image-delivery-optimization.md b/docs/decisions/008-image-delivery-optimization.md index 8b3fc0b..bc8aa3b 100644 --- a/docs/decisions/008-image-delivery-optimization.md +++ b/docs/decisions/008-image-delivery-optimization.md @@ -1,13 +1,5 @@ # 글로벌 이미지 전달 성능 최적화 -## 미션 메타데이터 - -- 관련 PR: [#160](https://github.com/SWM16-ASAP/back-server/pull/160) -- 작업 브랜치: `미상` -- 기준 브랜치: `develop` -- 현재 상태: 글로벌 이미지 전달 최적화 회고 정리 완료. 인프라 운영 문서와 포맷 전략 확장은 남아 있다. -- 다음 시작점: CDN·Lambda@Edge·저장소 운영 문서를 보강하고, 이미지 종류별 전처리 규격과 포맷 대응 범위를 다시 검토한다. - ## 문제 정적 이미지가 미국 리전에 가까운 저장소 기준으로 제공되면서 아시아 사용자 입장에서는 로딩 지연이 컸다. @@ -36,3 +28,8 @@ CDN과 Lambda@Edge 기반 WebP 변환 전략을 도입하고, 자주 쓰는 썸 - CDN, Lambda@Edge, 저장소 구성은 코드 저장소 밖 인프라 설정도 포함하므로 별도 운영 문서와 함께 관리하는 편이 좋다. - 이미지 종류별로 전처리 규격을 더 세분화할지, 혹은 WebP 외 포맷 대응을 늘릴지는 다시 검토할 수 있다. - 현재 R2 호환성 같은 저장소 세부 이슈는 별도 기록으로 분리되어 있으므로, 상위 전략과 하위 호환성 기록을 함께 유지해야 한다. + +## 연관 이슈 및 PR + +- 관련 이슈: 없음 +- 관련 PR: [#160](https://github.com/SWM16-ASAP/back-server/pull/160) diff --git a/docs/decisions/009-dsl-driven-crawling.md b/docs/decisions/009-dsl-driven-crawling.md index 434ec24..b3ae6d2 100644 --- a/docs/decisions/009-dsl-driven-crawling.md +++ b/docs/decisions/009-dsl-driven-crawling.md @@ -1,13 +1,5 @@ # DSL 기반 크롤링 규칙 관리 구조 도입 -## 미션 메타데이터 - -- 관련 PR: [#100](https://github.com/SWM16-ASAP/back-server/pull/100), [#120](https://github.com/SWM16-ASAP/back-server/pull/120), [#284](https://github.com/SWM16-ASAP/back-server/pull/284) -- 작업 브랜치: `미상` -- 기준 브랜치: `develop` -- 현재 상태: DSL 기반 크롤링 규칙 관리 구조 회고 정리 완료. 변화 탐지와 실패 알림 자동화는 남아 있다. -- 다음 시작점: 사이트 구조 변화 탐지와 규칙 실패 알림을 자동화하고, 서버·클라이언트·RSS fallback 책임 경계를 더 선명하게 나눈다. - ## 문제 특정 사이트를 크롤링해 콘텐츠를 재가공하는 구조에서는 사이트 DOM이 바뀌면 곧바로 장애가 발생할 수 있다. @@ -36,3 +28,8 @@ HTML 추출 규칙을 코드에 하드코딩하지 않고 자체 DSL로 표현 - DSL 문법이 커질수록 검증기와 에러 메시지 품질도 같이 좋아져야 운영이 편해진다. - 외부 사이트 구조 변화 탐지와 규칙 실패 알림은 아직 더 자동화할 수 있다. - 서버 크롤링, 클라이언트 크롤링, RSS fallback이 섞이는 영역은 추후 책임 경계를 더 선명하게 나눌 수 있다. + +## 연관 이슈 및 PR + +- 관련 이슈: 없음 +- 관련 PR: [#100](https://github.com/SWM16-ASAP/back-server/pull/100), [#120](https://github.com/SWM16-ASAP/back-server/pull/120), [#284](https://github.com/SWM16-ASAP/back-server/pull/284) diff --git a/docs/decisions/010-mission-oriented-agent-guidelines.md b/docs/decisions/010-mission-oriented-agent-guidelines.md index 24dd471..b971a73 100644 --- a/docs/decisions/010-mission-oriented-agent-guidelines.md +++ b/docs/decisions/010-mission-oriented-agent-guidelines.md @@ -1,13 +1,5 @@ # 미션 기반 Codex 에이전트 운영 규칙 정리 -## 미션 메타데이터 - -- 관련 PR: 미정 -- 작업 브랜치: `refactor/strengthen-agent-guidelines` -- 기준 브랜치: `develop` -- 현재 상태: `AGENTS.md`, repo-local mission skill, decision 템플릿 규칙 정리와 기존 decision 문서 메타데이터 backfill 완료 -- 다음 시작점: 현재 PR과 연결된 decision 문서를 더 잘 찾는 규칙을 보강하고, 템플릿과 실제 사용 규칙의 차이를 더 줄인다. - ## 문제 이 저장소는 미션 기반 백엔드 훈련장으로 쓰고 싶었지만, 기존 에이전트 규칙은 실습 흐름보다 일반적인 저장소 운영 안내에 더 가까웠다. @@ -36,6 +28,11 @@ ## 결과와 남은 이슈 - 미션 기반 에이전트 설계의 방향과 출력 규칙은 한 문서 집합으로 정리되었고, 현재 PR 변경점 기반 미션 선정 흐름도 명시됐다. -- decision 문서는 회고뿐 아니라 다음 세션 복원을 위한 상태 저장소 역할까지 맡도록 확장됐다. +- decision 문서는 미션 종료 후 판단과 회고를 남기는 기록으로 정리됐다. - 아직 기존 decision 문서들은 새 메타데이터 포맷으로 backfill되지 않았다. - 현재 PR과 연결된 decision 문서를 자동으로 찾는 규칙은 더 구체화할 수 있다. + +## 연관 이슈 및 PR + +- 관련 이슈: 없음 +- 관련 PR: 없음 diff --git a/docs/decisions/README.md b/docs/decisions/README.md index bd13e2f..7fd3f80 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -15,8 +15,7 @@ - 자잘한 구현 선택은 기록하지 않는다. - 문제, 선택, 이유, 검증, 결과와 남은 이슈 중심으로 짧게 정리한다. - 기본 원칙은 `미션당 문서 하나`다. -- 미션은 가능하면 PR 단위로 보고, decision 문서를 그 PR의 상태 저장소처럼 유지한다. -- 문서 앞부분에는 최소한 `관련 PR/브랜치`, `기준 브랜치`, `현재 상태`, `다음 시작점`을 남긴다. +- 문서 하단에는 `연관 이슈 및 PR` 섹션을 두고, 추적 가능한 이슈와 PR을 남긴다. - 구현 자체보다 왜 그런 선택을 했는지와 그 결과를 이해할 수 있게 적는다. - 구현보다 고민과 판단의 맥락이 먼저 보이게 적는다. diff --git a/docs/templates/decision-record-template.md b/docs/templates/decision-record-template.md index f436b7d..421c126 100644 --- a/docs/templates/decision-record-template.md +++ b/docs/templates/decision-record-template.md @@ -1,13 +1,5 @@ # Decision Record Template -## 미션 메타데이터 - -- 관련 PR: -- 작업 브랜치: -- 기준 브랜치: `develop` -- 현재 상태: -- 다음 시작점: - ## 제목 짧고 명확한 결정 제목 또는 회고 제목 @@ -39,3 +31,8 @@ ## 결과와 남은 이슈 무엇이 좋아졌는지와 아직 남아 있는 리스크, 후속 작업, 추후 다시 검토할 지점을 함께 적는다. + +## 연관 이슈 및 PR + +- 관련 이슈: +- 관련 PR: From a1d92cff368e475582ade2ef31e57190b3c9e377 Mon Sep 17 00:00:00 2001 From: solfe Date: Sun, 29 Mar 2026 23:52:14 +0900 Subject: [PATCH 2/2] docs: add mission state workflow --- .codex/skills/mission-close/SKILL.md | 17 +++--- .codex/skills/mission-evaluate/SKILL.md | 11 ++-- .codex/skills/mission-guide/SKILL.md | 9 ++-- .codex/skills/mission-interview/SKILL.md | 9 ++-- .codex/skills/mission-start/SKILL.md | 5 +- .gitignore | 3 +- AGENTS.md | 12 +++-- README.md | 1 + docs/README.md | 1 + .../010-mission-oriented-agent-guidelines.md | 16 +++--- docs/templates/mission-state-template.md | 54 +++++++++++++++++++ 11 files changed, 100 insertions(+), 38 deletions(-) create mode 100644 docs/templates/mission-state-template.md diff --git a/.codex/skills/mission-close/SKILL.md b/.codex/skills/mission-close/SKILL.md index eb10874..fa5173a 100644 --- a/.codex/skills/mission-close/SKILL.md +++ b/.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 문서는 최종 회고와 판단 기록으로만 쓴다. - 다음 미션으로 이어질 남은 이슈가 있으면 짧게 남긴다. diff --git a/.codex/skills/mission-evaluate/SKILL.md b/.codex/skills/mission-evaluate/SKILL.md index e16acc6..0375be4 100644 --- a/.codex/skills/mission-evaluate/SKILL.md +++ b/.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. 미션 완료 기준을 충족했는지 분명히 말한다. ## 출력 원칙 diff --git a/.codex/skills/mission-guide/SKILL.md b/.codex/skills/mission-guide/SKILL.md index e1674c8..dab1194 100644 --- a/.codex/skills/mission-guide/SKILL.md +++ b/.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개 이하로만 연결한다. ## 출력 원칙 diff --git a/.codex/skills/mission-interview/SKILL.md b/.codex/skills/mission-interview/SKILL.md index 7da4d03..df436b5 100644 --- a/.codex/skills/mission-interview/SKILL.md +++ b/.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. 질문은 한 번에 너무 많이 주지 말고, 답변 후 꼬리 질문이 가능하게 구성한다. ## 출력 원칙 diff --git a/.codex/skills/mission-start/SKILL.md b/.codex/skills/mission-start/SKILL.md index 85ede6e..ea0f9b5 100644 --- a/.codex/skills/mission-start/SKILL.md +++ b/.codex/skills/mission-start/SKILL.md @@ -12,7 +12,7 @@ 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. 각 후보에 대해 아래만 짧게 제시한다. - 미션명 @@ -20,7 +20,8 @@ description: Use when the user explicitly starts a new backend training mission, - 학습 포인트 - 난이도 7. 가능하면 추천 미션 1개를 함께 제시한다. -8. 현재 PR의 변경점과 직접 연결되는 미션이 있으면 우선순위를 높인다. +8. 미션이 선택되면 `MISSIONS.md`에 현재 활성 미션 상태를 바로 남길 수 있게 목표와 다음 시작점을 분명하게 정리한다. +9. 현재 PR의 변경점과 직접 연결되는 미션이 있으면 우선순위를 높인다. ## 출력 원칙 diff --git a/.gitignore b/.gitignore index 7ccbad4..731afaf 100644 --- a/.gitignore +++ b/.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/** \ No newline at end of file +k6/scripts/** diff --git a/AGENTS.md b/AGENTS.md index 3ab8d82..cd80c2e 100644 --- a/AGENTS.md +++ b/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`는 완료된 미션의 최종 판단과 결과만 남긴다. - 문서는 `문제 -> 선택 -> 이유 -> 검증 -> 결과와 남은 이슈`가 보이게 쓴다. ## 기본 학습 초점 diff --git a/README.md b/README.md index 68bc35e..32ab91a 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ Ling Level API는 학습 콘텐츠, 단어 학습, 스트릭, 추천, 알림 기 ## 문서 - [프로젝트 문서 허브](docs/README.md) +- 활성 미션 상태 파일: 로컬 루트 `MISSIONS.md` (`docs/templates/mission-state-template.md` 기준) - [아키텍처 문서 모음](docs/architecture/) - [의사결정 기록 모음](docs/decisions/) diff --git a/docs/README.md b/docs/README.md index 09509a1..924e2c6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -13,6 +13,7 @@ - 현재 구조, 도메인 관계, 대표 흐름을 정리할 때: [architecture](architecture/) - 미션을 수행하며 내린 큰 판단과 고민을 미션당 문서 하나로 남길 때: [decisions](decisions/) - 새 문서를 시작할 때: [templates](templates/) +- 활성 미션 상태 파일이 필요할 때: [mission-state-template.md](templates/mission-state-template.md) 를 복사해 루트 `MISSIONS.md`로 사용 ## 기본 원칙 diff --git a/docs/decisions/010-mission-oriented-agent-guidelines.md b/docs/decisions/010-mission-oriented-agent-guidelines.md index b971a73..532cfbd 100644 --- a/docs/decisions/010-mission-oriented-agent-guidelines.md +++ b/docs/decisions/010-mission-oriented-agent-guidelines.md @@ -9,28 +9,30 @@ ## 선택 에이전트 규칙을 `미션 선정 -> 해결 진행 -> 제출 -> 평가 -> 인터뷰 -> 문서화` 사이클 기준으로 다시 정리하고, 각 단계에 대응하는 repo-local skill을 명시적으로 분리했다. -미션 시작은 `develop...HEAD`와 working tree 변경점 리뷰를 먼저 보도록 바꾸고, 미션 상태는 `docs/decisions` 문서의 메타데이터로 복원 가능하게 관리하기로 했다. +미션 시작은 `develop...HEAD`와 working tree 변경점 리뷰를 먼저 보도록 바꾸고, 활성 미션 상태는 루트 `MISSIONS.md`에서 관리하기로 했다. +`docs/decisions`는 미션 종료 후 핵심 판단과 검증 결과를 남기는 최종 기록으로만 사용한다. ## 이유 학습 품질은 좋은 정답보다 좋은 문제 정의와 일관된 피드백 루프에서 나온다. 그래서 에이전트가 “무엇을 구현할지”보다 “지금 어떤 미션 단계에 있는지”를 먼저 인식하게 만드는 편이 맞았다. 또한 현재 브랜치의 변경점을 먼저 보면 실제 PR과 연결된 미션을 제안할 수 있어, 미션의 정확도와 리뷰 가능성이 같이 좋아진다. -상태 저장을 별도 메모리 대신 decision 문서에 남기면, PR 단위 기록과 다음 세션 복원을 같은 아티팩트로 관리할 수 있다. +활성 상태와 최종 회고를 같은 문서에 섞으면 진행 중 메모와 완료된 판단의 책임이 흐려진다. +그래서 진행 중 상태는 `MISSIONS.md`에 두고, 미션 종료 후에만 `docs/decisions`로 요약하는 편이 더 단순하고 덜 흔들린다. ## 검증 - [AGENTS.md](../../AGENTS.md) 에서 역할, 단계, 세션 시작 규칙, 문서화 원칙이 미션 중심으로 정리되었는지 확인한다. -- [mission-start/SKILL.md](../../.codex/skills/mission-start/SKILL.md) 와 [mission-evaluate/SKILL.md](../../.codex/skills/mission-evaluate/SKILL.md) 에서 `develop...HEAD` 리뷰 우선 규칙과 명시적 평가 트리거를 확인한다. -- [docs/decisions/README.md](README.md) 와 [decision-record-template.md](../templates/decision-record-template.md) 에서 PR/브랜치 상태 메타데이터 규칙을 확인한다. +- [mission-state-template.md](../templates/mission-state-template.md) 에서 활성 미션 상태 파일의 기본 템플릿을 확인한다. +- [mission-start/SKILL.md](../../.codex/skills/mission-start/SKILL.md) 와 [mission-evaluate/SKILL.md](../../.codex/skills/mission-evaluate/SKILL.md) 에서 `develop...HEAD` 리뷰 우선 규칙과 `MISSIONS.md` 참조 흐름을 확인한다. +- [docs/decisions/README.md](README.md) 와 [decision-record-template.md](../templates/decision-record-template.md) 에서 종료 후 회고 문서 규칙을 확인한다. - 실제 대화 dry-run으로 `mission-start`, `mission-evaluate`, `mission-close` 출력이 이전보다 덜 흔들리는지 검토한다. ## 결과와 남은 이슈 - 미션 기반 에이전트 설계의 방향과 출력 규칙은 한 문서 집합으로 정리되었고, 현재 PR 변경점 기반 미션 선정 흐름도 명시됐다. -- decision 문서는 미션 종료 후 판단과 회고를 남기는 기록으로 정리됐다. -- 아직 기존 decision 문서들은 새 메타데이터 포맷으로 backfill되지 않았다. -- 현재 PR과 연결된 decision 문서를 자동으로 찾는 규칙은 더 구체화할 수 있다. +- `MISSIONS.md`가 활성 미션 상태의 단일 소스로 추가됐고, decision 문서는 미션 종료 후 판단과 회고를 남기는 기록으로 정리됐다. +- `MISSIONS.md`와 mission 스킬 사이의 자동 동기화 규칙은 더 구체화할 수 있다. ## 연관 이슈 및 PR diff --git a/docs/templates/mission-state-template.md b/docs/templates/mission-state-template.md new file mode 100644 index 0000000..b56bbc5 --- /dev/null +++ b/docs/templates/mission-state-template.md @@ -0,0 +1,54 @@ +# Mission State Template + +이 템플릿은 루트 `MISSIONS.md`를 새로 만들 때 복사해서 쓰는 용도다. +`MISSIONS.md`는 활성 미션의 상태를 관리하는 로컬 작업 파일이고, 완료된 미션의 회고는 `docs/decisions`에 남긴다. + +## 운영 원칙 + +- 활성 미션 상태의 단일 소스는 루트 `MISSIONS.md`다. +- 한 번에 하나의 활성 미션만 관리한다. +- 세션이 바뀌면 이 파일을 먼저 읽고 현재 상태를 복원한다. +- 완료된 미션의 회고는 `docs/decisions`에 남긴다. + +## 현재 활성 미션 + +- 미션명: +- 단계: +- 관련 이슈: +- 관련 PR: + +## 목표 + +- + +## 범위 + +- + +## 비범위 + +- + +## 요구사항 + +- + +## 검증 계획 + +- + +## 현재 이해 + +- + +## 작업 로그 + +- YYYY-MM-DD: + +## 다음 시작점 + +- + +## decision 문서로 옮길 핵심 판단 + +-