Plan: 뉴스브리핑 LangGraph 전환 계획 추가
- 260202_뉴스브리핑_LangGraph_전환.md 생성 (311 원칙 준수) - 260202_동남아_뉴스_수집_및_로그_개선.md → archive 이동 (완료) Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Claude-51124
parent
5a1fab4297
commit
23e43aa993
@ -1,345 +1,345 @@
|
|||||||
# 문서 작성 원칙
|
# 문서 작성 원칙
|
||||||
|
|
||||||
**작성일**: 2025-10-13
|
**작성일**: 2025-10-13
|
||||||
**수정일**: 2026-01-21 (문서 크기 제한 완화: 트러블슈팅 100→150줄, 계획 150→200줄 등)
|
**수정일**: 2026-01-21 (문서 크기 제한 완화: 트러블슈팅 100→150줄, 계획 150→200줄 등)
|
||||||
**참고**: AGENTS.md, 311_백엔드_구조_원칙.md
|
**참고**: AGENTS.md, 311_백엔드_구조_원칙.md
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 1. 문서 종류별 규칙
|
## 1. 문서 종류별 규칙
|
||||||
|
|
||||||
### 트러블슈팅 문서
|
### 트러블슈팅 문서
|
||||||
|
|
||||||
**경로**: `DOCS/journey/troubleshooting/`
|
**경로**: `DOCS/journey/troubleshooting/`
|
||||||
**파일명**: `yymmdd_주제.md` (예: 251013_coldmail_ir_analyzer_fix.md)
|
**파일명**: `yymmdd_주제.md` (예: 251013_coldmail_ir_analyzer_fix.md)
|
||||||
**규칙**:
|
**규칙**:
|
||||||
- 주제별 파일 분리 (날짜 중복 허용)
|
- 주제별 파일 분리 (날짜 중복 허용)
|
||||||
- 시간순 작성
|
- 시간순 작성
|
||||||
- 교훈 섹션 필수
|
- 교훈 섹션 필수
|
||||||
- 크기 제한: 섹션 4 참조
|
- 크기 제한: 섹션 4 참조
|
||||||
- **⚠️ 절대 금지: 남은 작업 기록** - 남은 작업을 troubleshooting 문서에 기록하면 다음 작업 시 계획이 어수선해짐. 남은 작업은 반드시 `plans/` 문서의 "남은 작업" 섹션에만 기록
|
- **⚠️ 절대 금지: 남은 작업 기록** - 남은 작업을 troubleshooting 문서에 기록하면 다음 작업 시 계획이 어수선해짐. 남은 작업은 반드시 `plans/` 문서의 "남은 작업" 섹션에만 기록
|
||||||
|
|
||||||
**필수 헤더**:
|
**필수 헤더**:
|
||||||
```markdown
|
```markdown
|
||||||
# 제목
|
# 제목
|
||||||
|
|
||||||
**날짜**: 2025-10-13
|
**날짜**: 2025-10-13
|
||||||
**작성자**: happybell80
|
**작성자**: happybell80
|
||||||
**관련 파일**: `경로/파일명.py`
|
**관련 파일**: `경로/파일명.py`
|
||||||
|
|
||||||
---
|
---
|
||||||
```
|
```
|
||||||
|
|
||||||
### 아키텍처 문서
|
### 아키텍처 문서
|
||||||
|
|
||||||
**경로**: `DOCS/300_architecture/`
|
**경로**: `DOCS/300_architecture/`
|
||||||
**파일명**: `3NN_주제.md` (예: 311_백엔드_구조_원칙.md)
|
**파일명**: `3NN_주제.md` (예: 311_백엔드_구조_원칙.md)
|
||||||
**규칙**:
|
**규칙**:
|
||||||
- 작성일/수정일 명시
|
- 작성일/수정일 명시
|
||||||
- 섹션 번호 사용
|
- 섹션 번호 사용
|
||||||
- 표, 다이어그램 권장
|
- 표, 다이어그램 권장
|
||||||
- 코드 예시 (올바름/금지) 포함
|
- 코드 예시 (올바름/금지) 포함
|
||||||
|
|
||||||
### 계획 문서
|
### 계획 문서
|
||||||
|
|
||||||
**경로**: `DOCS/journey/plans/`
|
**경로**: `DOCS/journey/plans/`
|
||||||
**파일명**: `yymmdd_주제.md`
|
**파일명**: `yymmdd_주제.md`
|
||||||
**용도**: 미래 계획, 아이디어만 (아직 구현 안 됨)
|
**용도**: 미래 계획, 아이디어만 (아직 구현 안 됨)
|
||||||
|
|
||||||
**규칙** (⚠️ **핵심 원칙 - 절대 위반 금지**):
|
**규칙** (⚠️ **핵심 원칙 - 절대 위반 금지**):
|
||||||
- **구현 완료 시 즉시 `journey/plans/archive/`로 이동** (필수, 지연 금지) - `plans/`에는 미구현 계획만 남김
|
- **구현 완료 시 즉시 `journey/plans/archive/`로 이동** (필수, 지연 금지) - `plans/`에는 미구현 계획만 남김
|
||||||
- **모든 구현 완료 섹션은 즉시 삭제** - "→ 상세: troubleshooting/yymmdd_*.md" 링크로만 대체 (상세 완료 사항 나열 금지)
|
- **모든 구현 완료 섹션은 즉시 삭제** - "→ 상세: troubleshooting/yymmdd_*.md" 링크로만 대체 (상세 완료 사항 나열 금지)
|
||||||
- **배포/테스트 완료 후 바로 archive 이동** - troubleshooting 문서 작성과 동시에 또는 그 직후 즉시 처리
|
- **배포/테스트 완료 후 바로 archive 이동** - troubleshooting 문서 작성과 동시에 또는 그 직후 즉시 처리
|
||||||
- **구현 코드 파일 금지** - SQL 마이그레이션 파일(.sql), 코드 파일(.py, .js 등) 등 실제 구현 파일은 `plans/`에 두지 않고 해당 서비스 코드베이스에 위치
|
- **구현 코드 파일 금지** - SQL 마이그레이션 파일(.sql), 코드 파일(.py, .js 등) 등 실제 구현 파일은 `plans/`에 두지 않고 해당 서비스 코드베이스에 위치
|
||||||
- **명확한 행동강령만 기록** - 불확실한 표현("예상", "가능", "고려", "검토", "추후", "나중", "필요시", "선택", "옵션", "또는", "아마", "것 같", "추정") 금지
|
- **명확한 행동강령만 기록** - 불확실한 표현("예상", "가능", "고려", "검토", "추후", "나중", "필요시", "선택", "옵션", "또는", "아마", "것 같", "추정") 금지
|
||||||
- **여지가 있는 내용은 아이디어 폴더로 이동** - 불확실한 아이디어는 `journey/ideas/`에 기록
|
- **여지가 있는 내용은 아이디어 폴더로 이동** - 불확실한 아이디어는 `journey/ideas/`에 기록
|
||||||
- **아키텍처/Phase/필요작업만** - 장황한 구현 코드 예시 최소화
|
- **아키텍처/Phase/필요작업만** - 장황한 구현 코드 예시 최소화
|
||||||
- **Phase별 분리 가능**: 복잡한 계획은 Phase 1/2/3으로 분리 가능
|
- **Phase별 분리 가능**: 복잡한 계획은 Phase 1/2/3으로 분리 가능
|
||||||
- 크기 제한 및 초과 시 처리: 섹션 4 참조
|
- 크기 제한 및 초과 시 처리: 섹션 4 참조
|
||||||
|
|
||||||
**부분 완료 문서 처리** (⚠️ **핵심 원칙**):
|
**부분 완료 문서 처리** (⚠️ **핵심 원칙**):
|
||||||
- **부분 완료 문서는 `plans/`에 유지** - 전체 완료 시에만 archive로 이동
|
- **부분 완료 문서는 `plans/`에 유지** - 전체 완료 시에만 archive로 이동
|
||||||
- **완료된 섹션은 삭제하고 troubleshooting 링크로만 대체** - "→ 상세: troubleshooting/yymmdd_*.md" 형식 (상세 완료 사항 나열 금지)
|
- **완료된 섹션은 삭제하고 troubleshooting 링크로만 대체** - "→ 상세: troubleshooting/yymmdd_*.md" 형식 (상세 완료 사항 나열 금지)
|
||||||
- **미구현 항목만 "남은 작업" 섹션에 남기기** - 아키텍처/Phase/필요작업만 기록
|
- **미구현 항목만 "남은 작업" 섹션에 남기기** - 아키텍처/Phase/필요작업만 기록
|
||||||
|
|
||||||
**구분** (⚠️ **명확히 구분 필수**):
|
**구분** (⚠️ **명확히 구분 필수**):
|
||||||
- `plans/`: 미구현 계획만 (will do) - 부분 완료 포함, **구현 완료 섹션 절대 금지**, **남은 작업 기록 위치**
|
- `plans/`: 미구현 계획만 (will do) - 부분 완료 포함, **구현 완료 섹션 절대 금지**, **남은 작업 기록 위치**
|
||||||
- `plans/archive/`: 전체 구현 완료된 계획 (참고용 보관)
|
- `plans/archive/`: 전체 구현 완료된 계획 (참고용 보관)
|
||||||
- `troubleshooting/`: 구현 완료 + 문제 해결 (did + learned), **남은 작업 기록 절대 금지** (남은 작업을 troubleshooting에 기록하면 다음 작업 시 계획이 어수선해짐)
|
- `troubleshooting/`: 구현 완료 + 문제 해결 (did + learned), **남은 작업 기록 절대 금지** (남은 작업을 troubleshooting에 기록하면 다음 작업 시 계획이 어수선해짐)
|
||||||
|
|
||||||
### 인덱스 README.md
|
### 인덱스 README.md
|
||||||
|
|
||||||
**경로**: `DOCS/journey/research/`, `DOCS/journey/ideas/` 등 폴더 내부
|
**경로**: `DOCS/journey/research/`, `DOCS/journey/ideas/` 등 폴더 내부
|
||||||
**파일명**: `README.md`
|
**파일명**: `README.md`
|
||||||
**용도**: 해당 폴더의 문서 인덱스 및 목차 역할
|
**용도**: 해당 폴더의 문서 인덱스 및 목차 역할
|
||||||
|
|
||||||
**규칙**:
|
**규칙**:
|
||||||
- **인덱스/목차 역할만** - 문서 목록과 간단한 설명
|
- **인덱스/목차 역할만** - 문서 목록과 간단한 설명
|
||||||
- **상세 내용은 링크로 참조** - 트러블슈팅, 계획 등 실제 문서로 링크
|
- **상세 내용은 링크로 참조** - 트러블슈팅, 계획 등 실제 문서로 링크
|
||||||
- **핵심 키워드만** - 각 문서의 핵심만 간단히 나열
|
- **핵심 키워드만** - 각 문서의 핵심만 간단히 나열
|
||||||
- 중복 작성 금지: 섹션 2 핵심 원칙 참조
|
- 중복 작성 금지: 섹션 2 핵심 원칙 참조
|
||||||
- 크기 제한: 섹션 4 참조
|
- 크기 제한: 섹션 4 참조
|
||||||
|
|
||||||
**예시**:
|
**예시**:
|
||||||
```markdown
|
```markdown
|
||||||
## 성능 비교 테스트
|
## 성능 비교 테스트
|
||||||
- [하이브리드 의도 분류 성능 비교](../troubleshooting/260103_하이브리드_의도_분류_성능_비교_테스트.md)
|
- [하이브리드 의도 분류 성능 비교](../troubleshooting/260103_하이브리드_의도_분류_성능_비교_테스트.md)
|
||||||
- 초기: FastPath 49.6%, 제로샷 임베딩 23.4%
|
- 초기: FastPath 49.6%, 제로샷 임베딩 23.4%
|
||||||
- 개선: 제로샷 임베딩 70.2% (+46.8%p)
|
- 개선: 제로샷 임베딩 70.2% (+46.8%p)
|
||||||
```
|
```
|
||||||
|
|
||||||
**금지 사례**: 상세 내용 재작성, 코드/테스트 결과 상세 재현, "교훈" 섹션 전체 복사
|
**금지 사례**: 상세 내용 재작성, 코드/테스트 결과 상세 재현, "교훈" 섹션 전체 복사
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 2. 작성 규칙
|
## 2. 작성 규칙
|
||||||
|
|
||||||
### 핵심 원칙 (최우선)
|
### 핵심 원칙 (최우선)
|
||||||
|
|
||||||
**"핵심만 간결하게 정리"** - 문서의 모든 내용은 이 원칙을 준수해야 함
|
**"핵심만 간결하게 정리"** - 문서의 모든 내용은 이 원칙을 준수해야 함
|
||||||
- 불필요한 설명, 중복 내용, 장황한 문장 제거
|
- 불필요한 설명, 중복 내용, 장황한 문장 제거
|
||||||
- 필요한 정보만 간결하게 기록
|
- 필요한 정보만 간결하게 기록
|
||||||
- 관련 정보는 링크로 참조 (중복 작성 금지, 같은 내용이면 새 파일 생성하지 말고 기존 파일 수정)
|
- 관련 정보는 링크로 참조 (중복 작성 금지, 같은 내용이면 새 파일 생성하지 말고 기존 파일 수정)
|
||||||
|
|
||||||
### 구조화된 정보 형식 (AI/사람 모두 읽기 좋게)
|
### 구조화된 정보 형식 (AI/사람 모두 읽기 좋게)
|
||||||
|
|
||||||
**권장 형식**:
|
**권장 형식**:
|
||||||
- **표**: 비교, 목록, 역할 구분 등 구조화된 정보 표현
|
- **표**: 비교, 목록, 역할 구분 등 구조화된 정보 표현
|
||||||
- **파일명:줄번호**: 코드 위치 명확히 참조
|
- **파일명:줄번호**: 코드 위치 명확히 참조
|
||||||
- **명확한 키워드**: 검색 가능하도록 핵심 단어 명시
|
- **명확한 키워드**: 검색 가능하도록 핵심 단어 명시
|
||||||
- **목록/부제목**: 정보 계층 구조화
|
- **목록/부제목**: 정보 계층 구조화
|
||||||
|
|
||||||
**금지 형식**:
|
**금지 형식**:
|
||||||
- JSON/XML 같은 기계적 형식 (사람이 읽기 어려움)
|
- JSON/XML 같은 기계적 형식 (사람이 읽기 어려움)
|
||||||
- 암호화된 코드나 해시값 직접 노출
|
- 암호화된 코드나 해시값 직접 노출
|
||||||
|
|
||||||
### 절대 금지 사항
|
### 절대 금지 사항
|
||||||
|
|
||||||
| 금지 | 이유 |
|
| 금지 | 이유 |
|
||||||
|------|------|
|
|------|------|
|
||||||
| 핵심 없는 장황한 설명 | 핵심만 간결하게 정리 원칙 위반, 관련 문서 링크로 대체 |
|
| 핵심 없는 장황한 설명 | 핵심만 간결하게 정리 원칙 위반, 관련 문서 링크로 대체 |
|
||||||
| 전체 코드 블록 | 파일명:줄번호만 명시 (파일 참조 형식 섹션 참조) |
|
| 전체 코드 블록 | 파일명:줄번호만 명시 (파일 참조 형식 섹션 참조) |
|
||||||
| 의사코드, 추측, 예측 ("아마", "것 같다") | 확인된 사실만 기록 |
|
| 의사코드, 추측, 예측 ("아마", "것 같다") | 확인된 사실만 기록 |
|
||||||
| 이모지 사용 | 명시적 요청 시만 허용 |
|
| 이모지 사용 | 명시적 요청 시만 허용 |
|
||||||
| 민감정보 직접 기록 (API 키, 비밀번호, JWT Secret Key, 토큰, DB 연결 정보 등) | 보안 위험, 환경변수나 설정 파일로 분리하여 관리 |
|
| 민감정보 직접 기록 (API 키, 비밀번호, JWT Secret Key, 토큰, DB 연결 정보 등) | 보안 위험, 환경변수나 설정 파일로 분리하여 관리 |
|
||||||
| troubleshooting 문서에 남은 작업 기록 | 다음 작업 시 계획이 어수선해짐, 남은 작업은 반드시 `plans/` 문서에 기록 |
|
| troubleshooting 문서에 남은 작업 기록 | 다음 작업 시 계획이 어수선해짐, 남은 작업은 반드시 `plans/` 문서에 기록 |
|
||||||
|
|
||||||
### 파일 참조 형식
|
### 파일 참조 형식
|
||||||
|
|
||||||
**올바름** (파일명:줄번호 + 간단 설명):
|
**올바름** (파일명:줄번호 + 간단 설명):
|
||||||
```markdown
|
```markdown
|
||||||
- naverworks_briefing.py:58-74: 폴백 제거
|
- naverworks_briefing.py:58-74: 폴백 제거
|
||||||
- ir_analyzer.py:28: /api/query → /api/search
|
- ir_analyzer.py:28: /api/query → /api/search
|
||||||
```
|
```
|
||||||
|
|
||||||
**금지** (전체 코드 복사, 추상적 표현):
|
**금지** (전체 코드 복사, 추상적 표현):
|
||||||
```markdown
|
```markdown
|
||||||
- naverworks_briefing.py에서 폴백 제거 ← 구체적 위치 없음
|
- naverworks_briefing.py에서 폴백 제거 ← 구체적 위치 없음
|
||||||
- ir_analyzer.py 파일 수정 ← 구체적 내용 없음
|
- ir_analyzer.py 파일 수정 ← 구체적 내용 없음
|
||||||
```python
|
```python
|
||||||
# 전체 함수 코드 50줄 복사... ← 불필요
|
# 전체 함수 코드 50줄 복사... ← 불필요
|
||||||
```
|
```
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 3. 문서 구조
|
## 3. 문서 구조
|
||||||
|
|
||||||
### 트러블슈팅 문서 구조
|
### 트러블슈팅 문서 구조
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
# 제목
|
# 제목
|
||||||
|
|
||||||
**날짜**, **작성자**, **관련 파일**
|
**날짜**, **작성자**, **관련 파일**
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 문제 상황
|
## 문제 상황
|
||||||
- 현상, 에러 메시지
|
- 현상, 에러 메시지
|
||||||
|
|
||||||
## 해결 방안
|
## 해결 방안
|
||||||
- 파일명:줄번호 명시
|
- 파일명:줄번호 명시
|
||||||
- 수정 내용 간결히
|
- 수정 내용 간결히
|
||||||
|
|
||||||
## 구현 완료 (선택)
|
## 구현 완료 (선택)
|
||||||
- 커밋 해시, 날짜
|
- 커밋 해시, 날짜
|
||||||
|
|
||||||
## 교훈 (필수)
|
## 교훈 (필수)
|
||||||
- 왜 발생했는가
|
- 왜 발생했는가
|
||||||
- 다음에 어떻게 방지할 것인가
|
- 다음에 어떻게 방지할 것인가
|
||||||
|
|
||||||
⚠️ **절대 금지**: "남은 작업" 섹션 추가 금지. 남은 작업은 반드시 `plans/` 문서에 기록
|
⚠️ **절대 금지**: "남은 작업" 섹션 추가 금지. 남은 작업은 반드시 `plans/` 문서에 기록
|
||||||
```
|
```
|
||||||
|
|
||||||
### 아키텍처 문서 구조
|
### 아키텍처 문서 구조
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
# 제목
|
# 제목
|
||||||
|
|
||||||
**작성일**: 2025-10-13
|
**작성일**: 2025-10-13
|
||||||
**수정일**: 2025-10-13 (수정 이유)
|
**수정일**: 2025-10-13 (수정 이유)
|
||||||
|
|
||||||
## 1. 원칙
|
## 1. 원칙
|
||||||
## 2. 규칙
|
## 2. 규칙
|
||||||
## 3. 예시
|
## 3. 예시
|
||||||
## 4. 체크리스트
|
## 4. 체크리스트
|
||||||
## 5. 참고
|
## 5. 참고
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 4. 파일 크기 제한
|
## 4. 파일 크기 제한
|
||||||
|
|
||||||
### 문서 유형별 크기 제한
|
### 문서 유형별 크기 제한
|
||||||
|
|
||||||
| 문서 유형 | 크기 제한 | 비고 |
|
| 문서 유형 | 크기 제한 | 비고 |
|
||||||
|----------|----------|------|
|
|----------|----------|------|
|
||||||
| 트러블슈팅 문서 | 150줄 이하 | 단일 이슈 중심, 초과 시 주제별 분리 |
|
| 트러블슈팅 문서 | 150줄 이하 | 단일 이슈 중심, 초과 시 주제별 분리 |
|
||||||
| 계획 문서 | 200줄 이하 | Phase별로 분리 가능 |
|
| 계획 문서 | 200줄 이하 | Phase별로 분리 가능 |
|
||||||
| 인덱스 README.md | 150줄 이하 | 목차/인덱스 역할만 |
|
| 인덱스 README.md | 150줄 이하 | 목차/인덱스 역할만 |
|
||||||
| 리서치 문서 | 250줄 이하 | 논문 요약 등 긴 내용 허용 |
|
| 리서치 문서 | 250줄 이하 | 논문 요약 등 긴 내용 허용 |
|
||||||
| 아키텍처 문서 | 250줄 이하 | 섹션 많은 경우, 분리 가능하면 분리 우선 |
|
| 아키텍처 문서 | 250줄 이하 | 섹션 많은 경우, 분리 가능하면 분리 우선 |
|
||||||
|
|
||||||
### 초과 시 처리 방법
|
### 초과 시 처리 방법
|
||||||
|
|
||||||
**트러블슈팅 문서**:
|
**트러블슈팅 문서**:
|
||||||
- 단일 이슈 중심, 핵심만 간결하게 (초과 시 불필요한 설명/중복 제거 또는 주제별 분리)
|
- 단일 이슈 중심, 핵심만 간결하게 (초과 시 불필요한 설명/중복 제거 또는 주제별 분리)
|
||||||
|
|
||||||
**계획 문서**:
|
**계획 문서**:
|
||||||
- Phase 1/2/3으로 단계별 분리 가능
|
- Phase 1/2/3으로 단계별 분리 가능
|
||||||
- 또는 관련 troubleshooting 문서로 링크
|
- 또는 관련 troubleshooting 문서로 링크
|
||||||
|
|
||||||
**리서치/아키텍처 문서**:
|
**리서치/아키텍처 문서**:
|
||||||
- 분리 가능하면 주제별 섹션 분리
|
- 분리 가능하면 주제별 섹션 분리
|
||||||
- 또는 관련 문서로 링크 참조
|
- 또는 관련 문서로 링크 참조
|
||||||
|
|
||||||
### 기존 문서 처리
|
### 기존 문서 처리
|
||||||
|
|
||||||
- **기존 100줄 초과 문서는 과도적 예외로 인정**
|
- **기존 100줄 초과 문서는 과도적 예외로 인정**
|
||||||
- 신규 작성 시부터 위 원칙 적용
|
- 신규 작성 시부터 위 원칙 적용
|
||||||
- 기존 문서 수정 시 가능하면 원칙 준수하도록 간소화 권장
|
- 기존 문서 수정 시 가능하면 원칙 준수하도록 간소화 권장
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 5. 교훈 작성 규칙
|
## 5. 교훈 작성 규칙
|
||||||
|
|
||||||
### 필수 항목
|
### 필수 항목
|
||||||
1. **원인**: 왜 문제가 발생했는가
|
1. **원인**: 왜 문제가 발생했는가
|
||||||
2. **교훈**: 다음에 어떻게 방지할 것인가
|
2. **교훈**: 다음에 어떻게 방지할 것인가
|
||||||
3. **원칙**: 위반한 원칙이 있는가 (원칙 문서 참조: `311_백엔드_구조_원칙.md`, `312_문서_작성_원칙.md`)
|
3. **원칙**: 위반한 원칙이 있는가 (원칙 문서 참조: `311_백엔드_구조_원칙.md`, `312_문서_작성_원칙.md`)
|
||||||
|
|
||||||
### 올바른 예시
|
### 올바른 예시
|
||||||
```markdown
|
```markdown
|
||||||
## 교훈
|
## 교훈
|
||||||
|
|
||||||
### API 엔드포인트 검증 부족
|
### API 엔드포인트 검증 부족
|
||||||
- 구현 시 skill-rag-file API 스펙 미확인
|
- 구현 시 skill-rag-file API 스펙 미확인
|
||||||
- 추측으로 /api/query 사용, 실제는 /api/search
|
- 추측으로 /api/query 사용, 실제는 /api/search
|
||||||
- 교훈: 스킬 통합 전 API 문서 또는 코드 직접 확인 필수
|
- 교훈: 스킬 통합 전 API 문서 또는 코드 직접 확인 필수
|
||||||
```
|
```
|
||||||
|
|
||||||
### 금지 예시
|
### 금지 예시
|
||||||
```markdown
|
```markdown
|
||||||
## 교훈
|
## 교훈
|
||||||
|
|
||||||
에러가 발생했습니다. 다음에 조심하겠습니다.
|
에러가 발생했습니다. 다음에 조심하겠습니다.
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 6. 비난조 문장 금지
|
## 6. 비난조 문장 금지
|
||||||
|
|
||||||
### 금지 표현
|
### 금지 표현
|
||||||
- "잘못 작성됨"
|
- "잘못 작성됨"
|
||||||
- "버그가 많음"
|
- "버그가 많음"
|
||||||
- "엉망진창"
|
- "엉망진창"
|
||||||
|
|
||||||
### 권장 표현
|
### 권장 표현
|
||||||
- "수정 필요"
|
- "수정 필요"
|
||||||
- "개선 가능"
|
- "개선 가능"
|
||||||
- "리팩토링 대상"
|
- "리팩토링 대상"
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 7. 체크리스트
|
## 7. 체크리스트
|
||||||
|
|
||||||
문서 작성 전:
|
문서 작성 전:
|
||||||
- [ ] **핵심만 간결하게 정리** (섹션 2 핵심 원칙 참조)
|
- [ ] **핵심만 간결하게 정리** (섹션 2 핵심 원칙 참조)
|
||||||
- [ ] 파일명:줄번호로 위치 명시 (섹션 2 파일 참조 형식 참조)
|
- [ ] 파일명:줄번호로 위치 명시 (섹션 2 파일 참조 형식 참조)
|
||||||
- [ ] 확인된 사실만 기록 (추측/의사코드 제거)
|
- [ ] 확인된 사실만 기록 (추측/의사코드 제거)
|
||||||
- [ ] 파일명 형식 준수 (yymmdd_주제.md)
|
- [ ] 파일명 형식 준수 (yymmdd_주제.md)
|
||||||
- [ ] 문서 유형별 크기 제한 확인 (섹션 4 참조)
|
- [ ] 문서 유형별 크기 제한 확인 (섹션 4 참조)
|
||||||
- [ ] 교훈 섹션 작성 (트러블슈팅, 섹션 5 참조)
|
- [ ] 교훈 섹션 작성 (트러블슈팅, 섹션 5 참조)
|
||||||
- [ ] **troubleshooting 문서 작성 시: 남은 작업 섹션 추가 금지** (남은 작업은 반드시 `plans/` 문서에 기록)
|
- [ ] **troubleshooting 문서 작성 시: 남은 작업 섹션 추가 금지** (남은 작업은 반드시 `plans/` 문서에 기록)
|
||||||
|
|
||||||
문서 작성 후:
|
문서 작성 후:
|
||||||
- [ ] 한 번 더 읽고 핵심 없는 부분/중복 제거 (섹션 2 핵심 원칙 참조)
|
- [ ] 한 번 더 읽고 핵심 없는 부분/중복 제거 (섹션 2 핵심 원칙 참조)
|
||||||
- [ ] **troubleshooting 문서 검토: "남은 작업" 섹션이 있다면 삭제하고 `plans/` 문서로 이동**
|
- [ ] **troubleshooting 문서 검토: "남은 작업" 섹션이 있다면 삭제하고 `plans/` 문서로 이동**
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 8. 개발 과정에서 문서 정리 원칙
|
## 8. 개발 과정에서 문서 정리 원칙
|
||||||
|
|
||||||
### 기능 개발 시 문서화 흐름
|
### 기능 개발 시 문서화 흐름
|
||||||
|
|
||||||
새로운 기능을 만들 때 다음 순서로 문서를 작성/업데이트합니다:
|
새로운 기능을 만들 때 다음 순서로 문서를 작성/업데이트합니다:
|
||||||
|
|
||||||
1. **`journey/scenarios/`**: UX 시나리오 작성 (만들기 전)
|
1. **`journey/scenarios/`**: UX 시나리오 작성 (만들기 전)
|
||||||
- 사용자 경험 관점에서 기능 정의
|
- 사용자 경험 관점에서 기능 정의
|
||||||
- "어떤 기능을 만들지" 먼저 정의
|
- "어떤 기능을 만들지" 먼저 정의
|
||||||
|
|
||||||
2. **계획 문서** (`journey/plans/`): 구현 계획 작성 (만들기 전)
|
2. **계획 문서** (`journey/plans/`): 구현 계획 작성 (만들기 전)
|
||||||
- 아키텍처/Phase/필요작업만 기록 (섹션 1 참조)
|
- 아키텍처/Phase/필요작업만 기록 (섹션 1 참조)
|
||||||
- 구현 완료 시 `plans/archive/`로 이동하고 troubleshooting 문서와 링크 연결
|
- 구현 완료 시 `plans/archive/`로 이동하고 troubleshooting 문서와 링크 연결
|
||||||
|
|
||||||
3. **트러블슈팅 문서** (`journey/troubleshooting/`): 구현 과정 기록 (만들면서/만든 후)
|
3. **트러블슈팅 문서** (`journey/troubleshooting/`): 구현 과정 기록 (만들면서/만든 후)
|
||||||
- 문제 해결, 교훈, 테스트 결과 기록 (섹션 1 참조)
|
- 문제 해결, 교훈, 테스트 결과 기록 (섹션 1 참조)
|
||||||
- 크기 제한 및 초과 시 처리: 섹션 4 참조
|
- 크기 제한 및 초과 시 처리: 섹션 4 참조
|
||||||
- **⚠️ 절대 금지: 남은 작업 기록** - 남은 작업은 반드시 `plans/` 문서에 기록
|
- **⚠️ 절대 금지: 남은 작업 기록** - 남은 작업은 반드시 `plans/` 문서에 기록
|
||||||
|
|
||||||
4. **서비스 README.md**: 서비스별 핵심 사항 업데이트 (만든 후)
|
4. **서비스 README.md**: 서비스별 핵심 사항 업데이트 (만든 후)
|
||||||
- 엔드포인트, 환경변수, 사용 방법 등 구체적 정보 기록
|
- 엔드포인트, 환경변수, 사용 방법 등 구체적 정보 기록
|
||||||
|
|
||||||
5. **인덱스 README.md**: 폴더별 문서 인덱스 업데이트 (만든 후)
|
5. **인덱스 README.md**: 폴더별 문서 인덱스 업데이트 (만든 후)
|
||||||
- 문서 목록과 간단한 설명 기록 (섹션 1 참조)
|
- 문서 목록과 간단한 설명 기록 (섹션 1 참조)
|
||||||
|
|
||||||
6. **`book/`**: 원칙 변경 시 업데이트 (필요시)
|
6. **`book/`**: 원칙 변경 시 업데이트 (필요시)
|
||||||
- 아키텍처 원칙이 바뀌면 반영
|
- 아키텍처 원칙이 바뀌면 반영
|
||||||
- `guidelines/`에 개발 가이드라인 추가/수정
|
- `guidelines/`에 개발 가이드라인 추가/수정
|
||||||
|
|
||||||
7. **`AGENTS.md`**: 개발 원칙/운영 규칙 변경 시 업데이트 (필요시)
|
7. **`AGENTS.md`**: 개발 원칙/운영 규칙 변경 시 업데이트 (필요시)
|
||||||
- 새로운 작업 규칙이 생기면 반영
|
- 새로운 작업 규칙이 생기면 반영
|
||||||
|
|
||||||
### 문서 역할 구분
|
### 문서 역할 구분
|
||||||
|
|
||||||
| 문서 종류 | 역할 | 변경 빈도 |
|
| 문서 종류 | 역할 | 변경 빈도 |
|
||||||
|----------|------|----------|
|
|----------|------|----------|
|
||||||
| `book/` | 항상성, 원칙, 철학 | 거의 변하지 않음 |
|
| `book/` | 항상성, 원칙, 철학 | 거의 변하지 않음 |
|
||||||
| `journey/` | 진화 과정 (scenarios → ideas → research → plans → troubleshooting) | 계속 추가됨 |
|
| `journey/` | 진화 과정 (scenarios → ideas → research → plans → troubleshooting) | 계속 추가됨 |
|
||||||
| 서비스 README.md | 현재 상태 (포트, 엔드포인트, 환경변수) | 자주 변함 |
|
| 서비스 README.md | 현재 상태 (포트, 엔드포인트, 환경변수) | 자주 변함 |
|
||||||
| 인덱스 README.md (research/, ideas/ 등) | 문서 목차/인덱스, 상세는 링크 참조 | 새 문서 추가 시 |
|
| 인덱스 README.md (research/, ideas/ 등) | 문서 목차/인덱스, 상세는 링크 참조 | 새 문서 추가 시 |
|
||||||
| `AGENTS.md` | 개발자별 룰, 운영 규칙 | 필요시 변경 |
|
| `AGENTS.md` | 개발자별 룰, 운영 규칙 | 필요시 변경 |
|
||||||
|
|
||||||
### Journey 내부 흐름
|
### Journey 내부 흐름
|
||||||
|
|
||||||
```
|
```
|
||||||
scenarios/ (UX 정의)
|
scenarios/ (UX 정의)
|
||||||
↓
|
↓
|
||||||
ideas/ (아이디어 탐색)
|
ideas/ (아이디어 탐색)
|
||||||
↓
|
↓
|
||||||
research/ (이론적 기반)
|
research/ (이론적 기반)
|
||||||
↓
|
↓
|
||||||
plans/ (구현 계획)
|
plans/ (구현 계획)
|
||||||
↓
|
↓
|
||||||
troubleshooting/ (실제 구현)
|
troubleshooting/ (실제 구현)
|
||||||
```
|
```
|
||||||
|
|
||||||
**참고**: 각 단계는 필수가 아니며, 필요에 따라 생략 가능
|
**참고**: 각 단계는 필수가 아니며, 필요에 따라 생략 가능
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 9. 참고 문서
|
## 9. 참고 문서
|
||||||
|
|
||||||
- AGENTS.md: 전체 개발 가이드
|
- AGENTS.md: 전체 개발 가이드
|
||||||
- 311_백엔드_구조_원칙.md: 코드 구조 원칙
|
- 311_백엔드_구조_원칙.md: 코드 구조 원칙
|
||||||
- troubleshooting/ 폴더: 트러블슈팅 예시
|
- troubleshooting/ 폴더: 트러블슈팅 예시
|
||||||
|
|||||||
88
journey/plans/260202_뉴스브리핑_LangGraph_전환.md
Normal file
88
journey/plans/260202_뉴스브리핑_LangGraph_전환.md
Normal file
@ -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)
|
||||||
|
- [ ] 배포 및 스케줄 실행 검증
|
||||||
45
journey/plans/archive/260202_동남아_뉴스_수집_및_로그_개선.md
Normal file
45
journey/plans/archive/260202_동남아_뉴스_수집_및_로그_개선.md
Normal file
@ -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. <url|제목>`, `02. <url|제목>`, `03. <url|제목>` (한국어 번역된 제목, 링크 포함).
|
||||||
|
- **검증**: `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`)
|
||||||
|
- [ ] 기존 메시지 삭제 후 재전송
|
||||||
Loading…
x
Reference in New Issue
Block a user