From 23e43aa993cf06bf73d1c96df41e1ea9eece6bca Mon Sep 17 00:00:00 2001 From: Claude-51124 Date: Mon, 2 Feb 2026 10:30:29 +0900 Subject: [PATCH] =?UTF-8?q?Plan:=20=EB=89=B4=EC=8A=A4=EB=B8=8C=EB=A6=AC?= =?UTF-8?q?=ED=95=91=20LangGraph=20=EC=A0=84=ED=99=98=20=EA=B3=84=ED=9A=8D?= =?UTF-8?q?=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 260202_뉴스브리핑_LangGraph_전환.md 생성 (311 원칙 준수) - 260202_동남아_뉴스_수집_및_로그_개선.md → archive 이동 (완료) Co-authored-by: Cursor --- .../312_문서_작성_원칙.md | 690 +++++++++--------- ...260202_뉴스브리핑_LangGraph_전환.md | 88 +++ ...남아_뉴스_수집_및_로그_개선.md | 45 ++ 3 files changed, 478 insertions(+), 345 deletions(-) create mode 100644 journey/plans/260202_뉴스브리핑_LangGraph_전환.md create mode 100644 journey/plans/archive/260202_동남아_뉴스_수집_및_로그_개선.md diff --git a/book/300_architecture/312_문서_작성_원칙.md b/book/300_architecture/312_문서_작성_원칙.md index 95fba88..7a23661 100644 --- a/book/300_architecture/312_문서_작성_원칙.md +++ b/book/300_architecture/312_문서_작성_원칙.md @@ -1,345 +1,345 @@ -# 문서 작성 원칙 - -**작성일**: 2025-10-13 -**수정일**: 2026-01-21 (문서 크기 제한 완화: 트러블슈팅 100→150줄, 계획 150→200줄 등) -**참고**: AGENTS.md, 311_백엔드_구조_원칙.md - ---- - -## 1. 문서 종류별 규칙 - -### 트러블슈팅 문서 - -**경로**: `DOCS/journey/troubleshooting/` -**파일명**: `yymmdd_주제.md` (예: 251013_coldmail_ir_analyzer_fix.md) -**규칙**: -- 주제별 파일 분리 (날짜 중복 허용) -- 시간순 작성 -- 교훈 섹션 필수 -- 크기 제한: 섹션 4 참조 -- **⚠️ 절대 금지: 남은 작업 기록** - 남은 작업을 troubleshooting 문서에 기록하면 다음 작업 시 계획이 어수선해짐. 남은 작업은 반드시 `plans/` 문서의 "남은 작업" 섹션에만 기록 - -**필수 헤더**: -```markdown -# 제목 - -**날짜**: 2025-10-13 -**작성자**: happybell80 -**관련 파일**: `경로/파일명.py` - ---- -``` - -### 아키텍처 문서 - -**경로**: `DOCS/300_architecture/` -**파일명**: `3NN_주제.md` (예: 311_백엔드_구조_원칙.md) -**규칙**: -- 작성일/수정일 명시 -- 섹션 번호 사용 -- 표, 다이어그램 권장 -- 코드 예시 (올바름/금지) 포함 - -### 계획 문서 - -**경로**: `DOCS/journey/plans/` -**파일명**: `yymmdd_주제.md` -**용도**: 미래 계획, 아이디어만 (아직 구현 안 됨) - -**규칙** (⚠️ **핵심 원칙 - 절대 위반 금지**): -- **구현 완료 시 즉시 `journey/plans/archive/`로 이동** (필수, 지연 금지) - `plans/`에는 미구현 계획만 남김 -- **모든 구현 완료 섹션은 즉시 삭제** - "→ 상세: troubleshooting/yymmdd_*.md" 링크로만 대체 (상세 완료 사항 나열 금지) -- **배포/테스트 완료 후 바로 archive 이동** - troubleshooting 문서 작성과 동시에 또는 그 직후 즉시 처리 -- **구현 코드 파일 금지** - SQL 마이그레이션 파일(.sql), 코드 파일(.py, .js 등) 등 실제 구현 파일은 `plans/`에 두지 않고 해당 서비스 코드베이스에 위치 -- **명확한 행동강령만 기록** - 불확실한 표현("예상", "가능", "고려", "검토", "추후", "나중", "필요시", "선택", "옵션", "또는", "아마", "것 같", "추정") 금지 -- **여지가 있는 내용은 아이디어 폴더로 이동** - 불확실한 아이디어는 `journey/ideas/`에 기록 -- **아키텍처/Phase/필요작업만** - 장황한 구현 코드 예시 최소화 -- **Phase별 분리 가능**: 복잡한 계획은 Phase 1/2/3으로 분리 가능 -- 크기 제한 및 초과 시 처리: 섹션 4 참조 - -**부분 완료 문서 처리** (⚠️ **핵심 원칙**): -- **부분 완료 문서는 `plans/`에 유지** - 전체 완료 시에만 archive로 이동 -- **완료된 섹션은 삭제하고 troubleshooting 링크로만 대체** - "→ 상세: troubleshooting/yymmdd_*.md" 형식 (상세 완료 사항 나열 금지) -- **미구현 항목만 "남은 작업" 섹션에 남기기** - 아키텍처/Phase/필요작업만 기록 - -**구분** (⚠️ **명확히 구분 필수**): -- `plans/`: 미구현 계획만 (will do) - 부분 완료 포함, **구현 완료 섹션 절대 금지**, **남은 작업 기록 위치** -- `plans/archive/`: 전체 구현 완료된 계획 (참고용 보관) -- `troubleshooting/`: 구현 완료 + 문제 해결 (did + learned), **남은 작업 기록 절대 금지** (남은 작업을 troubleshooting에 기록하면 다음 작업 시 계획이 어수선해짐) - -### 인덱스 README.md - -**경로**: `DOCS/journey/research/`, `DOCS/journey/ideas/` 등 폴더 내부 -**파일명**: `README.md` -**용도**: 해당 폴더의 문서 인덱스 및 목차 역할 - -**규칙**: -- **인덱스/목차 역할만** - 문서 목록과 간단한 설명 -- **상세 내용은 링크로 참조** - 트러블슈팅, 계획 등 실제 문서로 링크 -- **핵심 키워드만** - 각 문서의 핵심만 간단히 나열 -- 중복 작성 금지: 섹션 2 핵심 원칙 참조 -- 크기 제한: 섹션 4 참조 - -**예시**: -```markdown -## 성능 비교 테스트 -- [하이브리드 의도 분류 성능 비교](../troubleshooting/260103_하이브리드_의도_분류_성능_비교_테스트.md) - - 초기: FastPath 49.6%, 제로샷 임베딩 23.4% - - 개선: 제로샷 임베딩 70.2% (+46.8%p) -``` - -**금지 사례**: 상세 내용 재작성, 코드/테스트 결과 상세 재현, "교훈" 섹션 전체 복사 - ---- - -## 2. 작성 규칙 - -### 핵심 원칙 (최우선) - -**"핵심만 간결하게 정리"** - 문서의 모든 내용은 이 원칙을 준수해야 함 -- 불필요한 설명, 중복 내용, 장황한 문장 제거 -- 필요한 정보만 간결하게 기록 -- 관련 정보는 링크로 참조 (중복 작성 금지, 같은 내용이면 새 파일 생성하지 말고 기존 파일 수정) - -### 구조화된 정보 형식 (AI/사람 모두 읽기 좋게) - -**권장 형식**: -- **표**: 비교, 목록, 역할 구분 등 구조화된 정보 표현 -- **파일명:줄번호**: 코드 위치 명확히 참조 -- **명확한 키워드**: 검색 가능하도록 핵심 단어 명시 -- **목록/부제목**: 정보 계층 구조화 - -**금지 형식**: -- JSON/XML 같은 기계적 형식 (사람이 읽기 어려움) -- 암호화된 코드나 해시값 직접 노출 - -### 절대 금지 사항 - -| 금지 | 이유 | -|------|------| -| 핵심 없는 장황한 설명 | 핵심만 간결하게 정리 원칙 위반, 관련 문서 링크로 대체 | -| 전체 코드 블록 | 파일명:줄번호만 명시 (파일 참조 형식 섹션 참조) | -| 의사코드, 추측, 예측 ("아마", "것 같다") | 확인된 사실만 기록 | -| 이모지 사용 | 명시적 요청 시만 허용 | -| 민감정보 직접 기록 (API 키, 비밀번호, JWT Secret Key, 토큰, DB 연결 정보 등) | 보안 위험, 환경변수나 설정 파일로 분리하여 관리 | -| troubleshooting 문서에 남은 작업 기록 | 다음 작업 시 계획이 어수선해짐, 남은 작업은 반드시 `plans/` 문서에 기록 | - -### 파일 참조 형식 - -**올바름** (파일명:줄번호 + 간단 설명): -```markdown -- naverworks_briefing.py:58-74: 폴백 제거 -- ir_analyzer.py:28: /api/query → /api/search -``` - -**금지** (전체 코드 복사, 추상적 표현): -```markdown -- naverworks_briefing.py에서 폴백 제거 ← 구체적 위치 없음 -- ir_analyzer.py 파일 수정 ← 구체적 내용 없음 -```python -# 전체 함수 코드 50줄 복사... ← 불필요 -``` -``` - ---- - -## 3. 문서 구조 - -### 트러블슈팅 문서 구조 - -```markdown -# 제목 - -**날짜**, **작성자**, **관련 파일** - ---- - -## 문제 상황 -- 현상, 에러 메시지 - -## 해결 방안 -- 파일명:줄번호 명시 -- 수정 내용 간결히 - -## 구현 완료 (선택) -- 커밋 해시, 날짜 - -## 교훈 (필수) -- 왜 발생했는가 -- 다음에 어떻게 방지할 것인가 - -⚠️ **절대 금지**: "남은 작업" 섹션 추가 금지. 남은 작업은 반드시 `plans/` 문서에 기록 -``` - -### 아키텍처 문서 구조 - -```markdown -# 제목 - -**작성일**: 2025-10-13 -**수정일**: 2025-10-13 (수정 이유) - -## 1. 원칙 -## 2. 규칙 -## 3. 예시 -## 4. 체크리스트 -## 5. 참고 -``` - ---- - -## 4. 파일 크기 제한 - -### 문서 유형별 크기 제한 - -| 문서 유형 | 크기 제한 | 비고 | -|----------|----------|------| -| 트러블슈팅 문서 | 150줄 이하 | 단일 이슈 중심, 초과 시 주제별 분리 | -| 계획 문서 | 200줄 이하 | Phase별로 분리 가능 | -| 인덱스 README.md | 150줄 이하 | 목차/인덱스 역할만 | -| 리서치 문서 | 250줄 이하 | 논문 요약 등 긴 내용 허용 | -| 아키텍처 문서 | 250줄 이하 | 섹션 많은 경우, 분리 가능하면 분리 우선 | - -### 초과 시 처리 방법 - -**트러블슈팅 문서**: -- 단일 이슈 중심, 핵심만 간결하게 (초과 시 불필요한 설명/중복 제거 또는 주제별 분리) - -**계획 문서**: -- Phase 1/2/3으로 단계별 분리 가능 -- 또는 관련 troubleshooting 문서로 링크 - -**리서치/아키텍처 문서**: -- 분리 가능하면 주제별 섹션 분리 -- 또는 관련 문서로 링크 참조 - -### 기존 문서 처리 - -- **기존 100줄 초과 문서는 과도적 예외로 인정** -- 신규 작성 시부터 위 원칙 적용 -- 기존 문서 수정 시 가능하면 원칙 준수하도록 간소화 권장 - ---- - -## 5. 교훈 작성 규칙 - -### 필수 항목 -1. **원인**: 왜 문제가 발생했는가 -2. **교훈**: 다음에 어떻게 방지할 것인가 -3. **원칙**: 위반한 원칙이 있는가 (원칙 문서 참조: `311_백엔드_구조_원칙.md`, `312_문서_작성_원칙.md`) - -### 올바른 예시 -```markdown -## 교훈 - -### API 엔드포인트 검증 부족 -- 구현 시 skill-rag-file API 스펙 미확인 -- 추측으로 /api/query 사용, 실제는 /api/search -- 교훈: 스킬 통합 전 API 문서 또는 코드 직접 확인 필수 -``` - -### 금지 예시 -```markdown -## 교훈 - -에러가 발생했습니다. 다음에 조심하겠습니다. -``` - ---- - -## 6. 비난조 문장 금지 - -### 금지 표현 -- "잘못 작성됨" -- "버그가 많음" -- "엉망진창" - -### 권장 표현 -- "수정 필요" -- "개선 가능" -- "리팩토링 대상" - ---- - -## 7. 체크리스트 - -문서 작성 전: -- [ ] **핵심만 간결하게 정리** (섹션 2 핵심 원칙 참조) -- [ ] 파일명:줄번호로 위치 명시 (섹션 2 파일 참조 형식 참조) -- [ ] 확인된 사실만 기록 (추측/의사코드 제거) -- [ ] 파일명 형식 준수 (yymmdd_주제.md) -- [ ] 문서 유형별 크기 제한 확인 (섹션 4 참조) -- [ ] 교훈 섹션 작성 (트러블슈팅, 섹션 5 참조) -- [ ] **troubleshooting 문서 작성 시: 남은 작업 섹션 추가 금지** (남은 작업은 반드시 `plans/` 문서에 기록) - -문서 작성 후: -- [ ] 한 번 더 읽고 핵심 없는 부분/중복 제거 (섹션 2 핵심 원칙 참조) -- [ ] **troubleshooting 문서 검토: "남은 작업" 섹션이 있다면 삭제하고 `plans/` 문서로 이동** - ---- - -## 8. 개발 과정에서 문서 정리 원칙 - -### 기능 개발 시 문서화 흐름 - -새로운 기능을 만들 때 다음 순서로 문서를 작성/업데이트합니다: - -1. **`journey/scenarios/`**: UX 시나리오 작성 (만들기 전) - - 사용자 경험 관점에서 기능 정의 - - "어떤 기능을 만들지" 먼저 정의 - -2. **계획 문서** (`journey/plans/`): 구현 계획 작성 (만들기 전) - - 아키텍처/Phase/필요작업만 기록 (섹션 1 참조) - - 구현 완료 시 `plans/archive/`로 이동하고 troubleshooting 문서와 링크 연결 - -3. **트러블슈팅 문서** (`journey/troubleshooting/`): 구현 과정 기록 (만들면서/만든 후) - - 문제 해결, 교훈, 테스트 결과 기록 (섹션 1 참조) - - 크기 제한 및 초과 시 처리: 섹션 4 참조 - - **⚠️ 절대 금지: 남은 작업 기록** - 남은 작업은 반드시 `plans/` 문서에 기록 - -4. **서비스 README.md**: 서비스별 핵심 사항 업데이트 (만든 후) - - 엔드포인트, 환경변수, 사용 방법 등 구체적 정보 기록 - -5. **인덱스 README.md**: 폴더별 문서 인덱스 업데이트 (만든 후) - - 문서 목록과 간단한 설명 기록 (섹션 1 참조) - -6. **`book/`**: 원칙 변경 시 업데이트 (필요시) - - 아키텍처 원칙이 바뀌면 반영 - - `guidelines/`에 개발 가이드라인 추가/수정 - -7. **`AGENTS.md`**: 개발 원칙/운영 규칙 변경 시 업데이트 (필요시) - - 새로운 작업 규칙이 생기면 반영 - -### 문서 역할 구분 - -| 문서 종류 | 역할 | 변경 빈도 | -|----------|------|----------| -| `book/` | 항상성, 원칙, 철학 | 거의 변하지 않음 | -| `journey/` | 진화 과정 (scenarios → ideas → research → plans → troubleshooting) | 계속 추가됨 | -| 서비스 README.md | 현재 상태 (포트, 엔드포인트, 환경변수) | 자주 변함 | -| 인덱스 README.md (research/, ideas/ 등) | 문서 목차/인덱스, 상세는 링크 참조 | 새 문서 추가 시 | -| `AGENTS.md` | 개발자별 룰, 운영 규칙 | 필요시 변경 | - -### Journey 내부 흐름 - -``` -scenarios/ (UX 정의) - ↓ -ideas/ (아이디어 탐색) - ↓ -research/ (이론적 기반) - ↓ -plans/ (구현 계획) - ↓ -troubleshooting/ (실제 구현) -``` - -**참고**: 각 단계는 필수가 아니며, 필요에 따라 생략 가능 - ---- - -## 9. 참고 문서 - -- AGENTS.md: 전체 개발 가이드 -- 311_백엔드_구조_원칙.md: 코드 구조 원칙 -- troubleshooting/ 폴더: 트러블슈팅 예시 +# 문서 작성 원칙 + +**작성일**: 2025-10-13 +**수정일**: 2026-01-21 (문서 크기 제한 완화: 트러블슈팅 100→150줄, 계획 150→200줄 등) +**참고**: AGENTS.md, 311_백엔드_구조_원칙.md + +--- + +## 1. 문서 종류별 규칙 + +### 트러블슈팅 문서 + +**경로**: `DOCS/journey/troubleshooting/` +**파일명**: `yymmdd_주제.md` (예: 251013_coldmail_ir_analyzer_fix.md) +**규칙**: +- 주제별 파일 분리 (날짜 중복 허용) +- 시간순 작성 +- 교훈 섹션 필수 +- 크기 제한: 섹션 4 참조 +- **⚠️ 절대 금지: 남은 작업 기록** - 남은 작업을 troubleshooting 문서에 기록하면 다음 작업 시 계획이 어수선해짐. 남은 작업은 반드시 `plans/` 문서의 "남은 작업" 섹션에만 기록 + +**필수 헤더**: +```markdown +# 제목 + +**날짜**: 2025-10-13 +**작성자**: happybell80 +**관련 파일**: `경로/파일명.py` + +--- +``` + +### 아키텍처 문서 + +**경로**: `DOCS/300_architecture/` +**파일명**: `3NN_주제.md` (예: 311_백엔드_구조_원칙.md) +**규칙**: +- 작성일/수정일 명시 +- 섹션 번호 사용 +- 표, 다이어그램 권장 +- 코드 예시 (올바름/금지) 포함 + +### 계획 문서 + +**경로**: `DOCS/journey/plans/` +**파일명**: `yymmdd_주제.md` +**용도**: 미래 계획, 아이디어만 (아직 구현 안 됨) + +**규칙** (⚠️ **핵심 원칙 - 절대 위반 금지**): +- **구현 완료 시 즉시 `journey/plans/archive/`로 이동** (필수, 지연 금지) - `plans/`에는 미구현 계획만 남김 +- **모든 구현 완료 섹션은 즉시 삭제** - "→ 상세: troubleshooting/yymmdd_*.md" 링크로만 대체 (상세 완료 사항 나열 금지) +- **배포/테스트 완료 후 바로 archive 이동** - troubleshooting 문서 작성과 동시에 또는 그 직후 즉시 처리 +- **구현 코드 파일 금지** - SQL 마이그레이션 파일(.sql), 코드 파일(.py, .js 등) 등 실제 구현 파일은 `plans/`에 두지 않고 해당 서비스 코드베이스에 위치 +- **명확한 행동강령만 기록** - 불확실한 표현("예상", "가능", "고려", "검토", "추후", "나중", "필요시", "선택", "옵션", "또는", "아마", "것 같", "추정") 금지 +- **여지가 있는 내용은 아이디어 폴더로 이동** - 불확실한 아이디어는 `journey/ideas/`에 기록 +- **아키텍처/Phase/필요작업만** - 장황한 구현 코드 예시 최소화 +- **Phase별 분리 가능**: 복잡한 계획은 Phase 1/2/3으로 분리 가능 +- 크기 제한 및 초과 시 처리: 섹션 4 참조 + +**부분 완료 문서 처리** (⚠️ **핵심 원칙**): +- **부분 완료 문서는 `plans/`에 유지** - 전체 완료 시에만 archive로 이동 +- **완료된 섹션은 삭제하고 troubleshooting 링크로만 대체** - "→ 상세: troubleshooting/yymmdd_*.md" 형식 (상세 완료 사항 나열 금지) +- **미구현 항목만 "남은 작업" 섹션에 남기기** - 아키텍처/Phase/필요작업만 기록 + +**구분** (⚠️ **명확히 구분 필수**): +- `plans/`: 미구현 계획만 (will do) - 부분 완료 포함, **구현 완료 섹션 절대 금지**, **남은 작업 기록 위치** +- `plans/archive/`: 전체 구현 완료된 계획 (참고용 보관) +- `troubleshooting/`: 구현 완료 + 문제 해결 (did + learned), **남은 작업 기록 절대 금지** (남은 작업을 troubleshooting에 기록하면 다음 작업 시 계획이 어수선해짐) + +### 인덱스 README.md + +**경로**: `DOCS/journey/research/`, `DOCS/journey/ideas/` 등 폴더 내부 +**파일명**: `README.md` +**용도**: 해당 폴더의 문서 인덱스 및 목차 역할 + +**규칙**: +- **인덱스/목차 역할만** - 문서 목록과 간단한 설명 +- **상세 내용은 링크로 참조** - 트러블슈팅, 계획 등 실제 문서로 링크 +- **핵심 키워드만** - 각 문서의 핵심만 간단히 나열 +- 중복 작성 금지: 섹션 2 핵심 원칙 참조 +- 크기 제한: 섹션 4 참조 + +**예시**: +```markdown +## 성능 비교 테스트 +- [하이브리드 의도 분류 성능 비교](../troubleshooting/260103_하이브리드_의도_분류_성능_비교_테스트.md) + - 초기: FastPath 49.6%, 제로샷 임베딩 23.4% + - 개선: 제로샷 임베딩 70.2% (+46.8%p) +``` + +**금지 사례**: 상세 내용 재작성, 코드/테스트 결과 상세 재현, "교훈" 섹션 전체 복사 + +--- + +## 2. 작성 규칙 + +### 핵심 원칙 (최우선) + +**"핵심만 간결하게 정리"** - 문서의 모든 내용은 이 원칙을 준수해야 함 +- 불필요한 설명, 중복 내용, 장황한 문장 제거 +- 필요한 정보만 간결하게 기록 +- 관련 정보는 링크로 참조 (중복 작성 금지, 같은 내용이면 새 파일 생성하지 말고 기존 파일 수정) + +### 구조화된 정보 형식 (AI/사람 모두 읽기 좋게) + +**권장 형식**: +- **표**: 비교, 목록, 역할 구분 등 구조화된 정보 표현 +- **파일명:줄번호**: 코드 위치 명확히 참조 +- **명확한 키워드**: 검색 가능하도록 핵심 단어 명시 +- **목록/부제목**: 정보 계층 구조화 + +**금지 형식**: +- JSON/XML 같은 기계적 형식 (사람이 읽기 어려움) +- 암호화된 코드나 해시값 직접 노출 + +### 절대 금지 사항 + +| 금지 | 이유 | +|------|------| +| 핵심 없는 장황한 설명 | 핵심만 간결하게 정리 원칙 위반, 관련 문서 링크로 대체 | +| 전체 코드 블록 | 파일명:줄번호만 명시 (파일 참조 형식 섹션 참조) | +| 의사코드, 추측, 예측 ("아마", "것 같다") | 확인된 사실만 기록 | +| 이모지 사용 | 명시적 요청 시만 허용 | +| 민감정보 직접 기록 (API 키, 비밀번호, JWT Secret Key, 토큰, DB 연결 정보 등) | 보안 위험, 환경변수나 설정 파일로 분리하여 관리 | +| troubleshooting 문서에 남은 작업 기록 | 다음 작업 시 계획이 어수선해짐, 남은 작업은 반드시 `plans/` 문서에 기록 | + +### 파일 참조 형식 + +**올바름** (파일명:줄번호 + 간단 설명): +```markdown +- naverworks_briefing.py:58-74: 폴백 제거 +- ir_analyzer.py:28: /api/query → /api/search +``` + +**금지** (전체 코드 복사, 추상적 표현): +```markdown +- naverworks_briefing.py에서 폴백 제거 ← 구체적 위치 없음 +- ir_analyzer.py 파일 수정 ← 구체적 내용 없음 +```python +# 전체 함수 코드 50줄 복사... ← 불필요 +``` +``` + +--- + +## 3. 문서 구조 + +### 트러블슈팅 문서 구조 + +```markdown +# 제목 + +**날짜**, **작성자**, **관련 파일** + +--- + +## 문제 상황 +- 현상, 에러 메시지 + +## 해결 방안 +- 파일명:줄번호 명시 +- 수정 내용 간결히 + +## 구현 완료 (선택) +- 커밋 해시, 날짜 + +## 교훈 (필수) +- 왜 발생했는가 +- 다음에 어떻게 방지할 것인가 + +⚠️ **절대 금지**: "남은 작업" 섹션 추가 금지. 남은 작업은 반드시 `plans/` 문서에 기록 +``` + +### 아키텍처 문서 구조 + +```markdown +# 제목 + +**작성일**: 2025-10-13 +**수정일**: 2025-10-13 (수정 이유) + +## 1. 원칙 +## 2. 규칙 +## 3. 예시 +## 4. 체크리스트 +## 5. 참고 +``` + +--- + +## 4. 파일 크기 제한 + +### 문서 유형별 크기 제한 + +| 문서 유형 | 크기 제한 | 비고 | +|----------|----------|------| +| 트러블슈팅 문서 | 150줄 이하 | 단일 이슈 중심, 초과 시 주제별 분리 | +| 계획 문서 | 200줄 이하 | Phase별로 분리 가능 | +| 인덱스 README.md | 150줄 이하 | 목차/인덱스 역할만 | +| 리서치 문서 | 250줄 이하 | 논문 요약 등 긴 내용 허용 | +| 아키텍처 문서 | 250줄 이하 | 섹션 많은 경우, 분리 가능하면 분리 우선 | + +### 초과 시 처리 방법 + +**트러블슈팅 문서**: +- 단일 이슈 중심, 핵심만 간결하게 (초과 시 불필요한 설명/중복 제거 또는 주제별 분리) + +**계획 문서**: +- Phase 1/2/3으로 단계별 분리 가능 +- 또는 관련 troubleshooting 문서로 링크 + +**리서치/아키텍처 문서**: +- 분리 가능하면 주제별 섹션 분리 +- 또는 관련 문서로 링크 참조 + +### 기존 문서 처리 + +- **기존 100줄 초과 문서는 과도적 예외로 인정** +- 신규 작성 시부터 위 원칙 적용 +- 기존 문서 수정 시 가능하면 원칙 준수하도록 간소화 권장 + +--- + +## 5. 교훈 작성 규칙 + +### 필수 항목 +1. **원인**: 왜 문제가 발생했는가 +2. **교훈**: 다음에 어떻게 방지할 것인가 +3. **원칙**: 위반한 원칙이 있는가 (원칙 문서 참조: `311_백엔드_구조_원칙.md`, `312_문서_작성_원칙.md`) + +### 올바른 예시 +```markdown +## 교훈 + +### API 엔드포인트 검증 부족 +- 구현 시 skill-rag-file API 스펙 미확인 +- 추측으로 /api/query 사용, 실제는 /api/search +- 교훈: 스킬 통합 전 API 문서 또는 코드 직접 확인 필수 +``` + +### 금지 예시 +```markdown +## 교훈 + +에러가 발생했습니다. 다음에 조심하겠습니다. +``` + +--- + +## 6. 비난조 문장 금지 + +### 금지 표현 +- "잘못 작성됨" +- "버그가 많음" +- "엉망진창" + +### 권장 표현 +- "수정 필요" +- "개선 가능" +- "리팩토링 대상" + +--- + +## 7. 체크리스트 + +문서 작성 전: +- [ ] **핵심만 간결하게 정리** (섹션 2 핵심 원칙 참조) +- [ ] 파일명:줄번호로 위치 명시 (섹션 2 파일 참조 형식 참조) +- [ ] 확인된 사실만 기록 (추측/의사코드 제거) +- [ ] 파일명 형식 준수 (yymmdd_주제.md) +- [ ] 문서 유형별 크기 제한 확인 (섹션 4 참조) +- [ ] 교훈 섹션 작성 (트러블슈팅, 섹션 5 참조) +- [ ] **troubleshooting 문서 작성 시: 남은 작업 섹션 추가 금지** (남은 작업은 반드시 `plans/` 문서에 기록) + +문서 작성 후: +- [ ] 한 번 더 읽고 핵심 없는 부분/중복 제거 (섹션 2 핵심 원칙 참조) +- [ ] **troubleshooting 문서 검토: "남은 작업" 섹션이 있다면 삭제하고 `plans/` 문서로 이동** + +--- + +## 8. 개발 과정에서 문서 정리 원칙 + +### 기능 개발 시 문서화 흐름 + +새로운 기능을 만들 때 다음 순서로 문서를 작성/업데이트합니다: + +1. **`journey/scenarios/`**: UX 시나리오 작성 (만들기 전) + - 사용자 경험 관점에서 기능 정의 + - "어떤 기능을 만들지" 먼저 정의 + +2. **계획 문서** (`journey/plans/`): 구현 계획 작성 (만들기 전) + - 아키텍처/Phase/필요작업만 기록 (섹션 1 참조) + - 구현 완료 시 `plans/archive/`로 이동하고 troubleshooting 문서와 링크 연결 + +3. **트러블슈팅 문서** (`journey/troubleshooting/`): 구현 과정 기록 (만들면서/만든 후) + - 문제 해결, 교훈, 테스트 결과 기록 (섹션 1 참조) + - 크기 제한 및 초과 시 처리: 섹션 4 참조 + - **⚠️ 절대 금지: 남은 작업 기록** - 남은 작업은 반드시 `plans/` 문서에 기록 + +4. **서비스 README.md**: 서비스별 핵심 사항 업데이트 (만든 후) + - 엔드포인트, 환경변수, 사용 방법 등 구체적 정보 기록 + +5. **인덱스 README.md**: 폴더별 문서 인덱스 업데이트 (만든 후) + - 문서 목록과 간단한 설명 기록 (섹션 1 참조) + +6. **`book/`**: 원칙 변경 시 업데이트 (필요시) + - 아키텍처 원칙이 바뀌면 반영 + - `guidelines/`에 개발 가이드라인 추가/수정 + +7. **`AGENTS.md`**: 개발 원칙/운영 규칙 변경 시 업데이트 (필요시) + - 새로운 작업 규칙이 생기면 반영 + +### 문서 역할 구분 + +| 문서 종류 | 역할 | 변경 빈도 | +|----------|------|----------| +| `book/` | 항상성, 원칙, 철학 | 거의 변하지 않음 | +| `journey/` | 진화 과정 (scenarios → ideas → research → plans → troubleshooting) | 계속 추가됨 | +| 서비스 README.md | 현재 상태 (포트, 엔드포인트, 환경변수) | 자주 변함 | +| 인덱스 README.md (research/, ideas/ 등) | 문서 목차/인덱스, 상세는 링크 참조 | 새 문서 추가 시 | +| `AGENTS.md` | 개발자별 룰, 운영 규칙 | 필요시 변경 | + +### Journey 내부 흐름 + +``` +scenarios/ (UX 정의) + ↓ +ideas/ (아이디어 탐색) + ↓ +research/ (이론적 기반) + ↓ +plans/ (구현 계획) + ↓ +troubleshooting/ (실제 구현) +``` + +**참고**: 각 단계는 필수가 아니며, 필요에 따라 생략 가능 + +--- + +## 9. 참고 문서 + +- AGENTS.md: 전체 개발 가이드 +- 311_백엔드_구조_원칙.md: 코드 구조 원칙 +- troubleshooting/ 폴더: 트러블슈팅 예시 diff --git a/journey/plans/260202_뉴스브리핑_LangGraph_전환.md b/journey/plans/260202_뉴스브리핑_LangGraph_전환.md new file mode 100644 index 0000000..52b8da8 --- /dev/null +++ b/journey/plans/260202_뉴스브리핑_LangGraph_전환.md @@ -0,0 +1,88 @@ +# 뉴스 브리핑 LangGraph 워크플로우 전환 + +**날짜**: 2026-02-02 +**작성자**: Claude +**관련 파일**: `rb8001/app/services/skills/startup_news_skill.py`, `skill_news/app/services/sea_news_collector.py` +**원칙 참조**: `311_백엔드_구조_원칙.md` (섹션 5: LangGraph 워크플로우) + +--- + +## 1. 현재 문제 + +- **원칙 위반**: 뉴스 브리핑은 수집→필터→번역→포맷→전송 다단계 처리인데, 일반 함수로 구현되어 있음. 311 원칙 "복잡한 다단계 처리는 LangGraph 적극 활용" 위반. +- **추적성 부족**: 각 단계별 실패 지점, 중간 상태, 실행 시간 등이 로그에 체계적으로 남지 않음. +- **복구 불가**: 중간 단계 실패 시 처음부터 재실행해야 함 (체크포인트 없음). + +--- + +## 2. LangGraph 전환 설계 + +### 2.1 상태 모델 (HeadlinesState) + +```python +class HeadlinesState(TypedDict): + channel_id: str + naver_items: List[Dict] # 깡프로 헤드라인 + sea_items: List[Dict] # 동남아 뉴스 + terms: Optional[List[str]] # 추출된 용어 + formatted_text: str # 최종 Slack 텍스트 + message_ts: Optional[str] # 전송된 메시지 ts + errors: List[str] # 각 단계 에러 +``` + +### 2.2 노드 구성 + +1. **fetch_naver_node**: skill-news API 호출 → `naver_items` 반환 +2. **fetch_sea_node**: skill-news SEA API 호출 → `sea_items` 반환 (실패 시 빈 리스트, 에러 기록) +3. **extract_terms_node**: Gemini로 용어 추출 → `terms` 반환 (환경변수 체크) +4. **format_node**: 깡프로 + 동남아 + 용어 섹션 조합 → `formatted_text` 반환 +5. **send_node**: Slack 전송 → `message_ts` 반환 및 로그 기록 + +### 2.3 라우팅 + +``` +START → fetch_naver → fetch_sea → extract_terms → format → send → END +``` + +- `fetch_sea` 실패 시에도 계속 진행 (graceful degradation) +- `extract_terms` 환경변수 false면 skip +- 각 노드 실패는 `errors` 리스트에 기록 + +### 2.4 체크포인터 + +- **AsyncSqliteSaver** 사용 (경량 워크플로우, 서버 재시작 시 재개 불필요) +- DB 경로: `/code/checkpoints/headlines_workflow.db` +- thread_id: `f"headlines_{channel_id}_{date}"` + +--- + +## 3. Phase별 작업 + +### Phase 1: 워크플로우 파일 생성 +- **파일**: `rb8001/app/services/workflows/headlines_workflow.py` (신규) +- **내용**: HeadlinesState, 5개 노드, StateGraph 정의 + +### Phase 2: startup_news_skill.py 리팩토링 +- **기존**: `run_headlines_job()` 함수 → **변경**: LangGraph 워크플로우 호출 +- **로그**: 각 노드별 실행 로그 + 최종 message_ts 로그 + +### Phase 3: TDD 테스트 +- **파일**: `rb8001/tests/test_headlines_workflow.py` (신규) +- **시나리오**: + - 정상 플로우 (깡프로 + 동남아 + 용어) + - 동남아 실패 시 graceful degradation + - 용어 추출 skip + - message_ts 로그 확인 + +### Phase 4: 배포 및 검증 +- **배포**: `git push origin main` (rb8001) → Gitea Actions 자동 배포 +- **검증**: 내일 아침 09:10 스케줄 실행 시 로그에 노드별 실행 + message_ts 확인 + +--- + +## 4. 남은 작업 + +- [ ] `headlines_workflow.py` 생성 (LangGraph StateGraph) +- [ ] `startup_news_skill.py` 리팩토링 (워크플로우 호출) +- [ ] `test_headlines_workflow.py` 작성 (TDD) +- [ ] 배포 및 스케줄 실행 검증 diff --git a/journey/plans/archive/260202_동남아_뉴스_수집_및_로그_개선.md b/journey/plans/archive/260202_동남아_뉴스_수집_및_로그_개선.md new file mode 100644 index 0000000..4ccf852 --- /dev/null +++ b/journey/plans/archive/260202_동남아_뉴스_수집_및_로그_개선.md @@ -0,0 +1,45 @@ +# 동남아 뉴스 수집 복구 및 메시지 로그 개선 계획 + +**날짜**: 2026-02-02 +**작성자**: Claude +**관련 파일**: `rb8001/app/services/skills/startup_news_skill.py`, `skill_news/app/services/sea_news_collector.py` + +--- + +## 1. 문제 상황 +- **수집 실패**: Google News HTML 구조 변경으로 인해 동남아 뉴스 수집량이 0건으로 떨어짐. +- **추적 불가**: 뉴스 브리핑 송출 시 Slack 메시지의 타임스탬프(ts)를 로그에 남기지 않아, 잘못된 메시지 삭제 등 사후 처리가 어려움. + +## 2. 해결 단계 (Phase) + +### Phase 1: 송출 로그 개선 (로그에 ts 포함) +- **목표**: 뉴스 브리핑 전송 성공 시 Slack이 반환하는 `ts`를 반드시 로그에 기록. +- **작업**: `startup_news_skill.py`의 `slack_client.chat_postMessage` 호출 결과에서 `ts`를 추출하여 `logger.info`로 출력. +- **기대효과**: 문제 발생 시 로그만 보고도 해당 메시지를 식별하여 삭제 가능. + +### Phase 2: 수집기 셀렉터 복구 +- **목표**: 변경된 Google News 구조에 맞춰 뉴스 제목과 링크를 다시 수집. +- **작업**: `sea_news_collector.py`의 셀렉터를 `article`에서 `a[class*="JtKRv"]` 기반으로 업데이트. +- **기대효과**: 24시간 이내의 정확한 동남아 스타트업 뉴스 수집 재개. + +### Phase 2.5: 동남아 뉴스 형식 검증 +- **목표**: 수집된 뉴스가 Slack 표시 형식에 맞는지 확인. +- **형식**: `01. `, `02. `, `03. ` (한국어 번역된 제목, 링크 포함). +- **검증**: `sea_news_service.py`의 `format_sea_news_for_slack` 결과에 URL·제목이 정상 포함되는지 확인. + +### Phase 3: 수집 안정성 강화 (RSS 폴백) +- **목표**: Google News 스크래핑 실패 시에도 최소한의 뉴스를 보장. +- **작업**: `ASEAN UP` 등 RSS 피드를 보조 수집원으로 추가. 0건일 경우 RSS에서 가져와 LLM 필터링 후 제공. +- **기대효과**: 스크래핑 엔진이 깨져도 브리핑 섹션이 비어 나가는 현상 방지. + +## 3. 삭제 및 재전송 절차 +- **대상 메시지**: ts=`1769991030.415619`, 채널=`C09C98KK2TT` (Slack URL: `.../C09C98KK2TT/p1769991030415619`). +- **삭제**: `chat.delete` API 호출 (`channel=C09C98KK2TT`, `ts=1769991030.415619`). **토큰**: `COMPANYX_SLACK_BOT_TOKEN` 사용 (startup_news_skill과 동일, 참조: `troubleshooting/250915_happybell80_Slack_메시징_운영_런북.md`). +- **재전송**: `run_headlines_job("C09C98KK2TT")` 수동 호출 또는 스케줄러 엔드포인트 `POST /api/schedule/run/daily_headlines` 실행. +- **순서**: Phase 1~2 완료 후 → 삭제 → 재전송. + +## 4. 남은 작업 +- [ ] `startup_news_skill.py` 수정 (로그 추가) +- [ ] `sea_news_collector.py` 수정 (셀렉터 업데이트) +- [ ] 동남아 뉴스 형식 검증 (`format_sea_news_for_slack`) +- [ ] 기존 메시지 삭제 후 재전송