Claude-51124 22557e7132 docs: 오래된 트러블슈팅 아카이브 및 구조 정리

- 7-8월 초기 구축 문서 12개를 _archive/troubleshooting/2025_07-08_initial_setup/로 이동
- book/300_architecture/390_human_in_the_loop_intent_learning.md를 journey/research/intent_classification/로 이동 (개발 여정 문서)
- 빈 폴더 제거 (journey/assets/*)

2025-11-17 14:06:05 +09:00

4.1 KiB

Raw Blame History

문서 작성 원칙

작성일: 2025-10-13 참고: CLAUDE.md, 311_FastAPI_구조_원칙.md

1. 문서 종류별 규칙

트러블슈팅 문서

경로: DOCS/troubleshooting/ 파일명: yymmdd_주제.md (예: 251013_coldmail_ir_analyzer_fix.md) 규칙:

주제별 파일 분리 (날짜 중복 허용)
시간순 작성
교훈 섹션 필수
100줄 이하 유지

필수 헤더:

# 제목

**날짜**: 2025-10-13
**작성자**: happybell80
**관련 파일**: `경로/파일명.py`

---

아키텍처 문서

경로: DOCS/300_architecture/ 파일명: 3NN_주제.md (예: 311_FastAPI_구조_원칙.md) 규칙:

작성일/수정일 명시
섹션 번호 사용
표, 다이어그램 권장
코드 예시 (올바름/금지) 포함

계획 문서

경로: DOCS/plans/ 규칙:

미래 계획, 아이디어
구현 완료 시 troubleshooting으로 이동

2. 작성 규칙

절대 금지 사항

금지	이유
의사코드, 추측, 예측	실제 동작하는 코드만 작성
"아마", "것 같다", "추정"	확인된 사실만 기록
불필요한 코드 블록	파일명:줄번호만 명시
이모지 사용	명시적 요청 시만 허용

파일 참조 형식

올바름:

- naverworks_briefing.py:58-74: 폴백 제거
- ir_analyzer.py:28: /api/query → /api/search

금지:

- naverworks_briefing.py에서 폴백 제거
- ir_analyzer.py 파일 수정

코드 블록 최소화

올바름 (파일명:줄번호 + 간단 설명):

**수정 필요:**
- ir_analyzer.py:28: url = f"{SKILL_RAG_FILE_URL}/api/search"
- ir_analyzer.py:29-32: payload에 team_id 추가

금지 (전체 코드 복사):

**수정 필요:**
```python
# ir_analyzer.py 전체 함수 코드 50줄 복사...


---

## 3. 문서 구조

### 트러블슈팅 문서 구조

```markdown
# 제목

**날짜**, **작성자**, **관련 파일**

---

## 문제 상황
- 현상, 에러 메시지

## 해결 방안
- 파일명:줄번호 명시
- 수정 내용 간결히

## 구현 완료 (선택)
- 커밋 해시, 날짜

## 교훈 (필수)
- 왜 발생했는가
- 다음에 어떻게 방지할 것인가

아키텍처 문서 구조

# 제목

**작성일**: 2025-10-13
**수정일**: 2025-10-13 (수정 이유)

## 1. 원칙
## 2. 규칙
## 3. 예시
## 4. 체크리스트
## 5. 참고

4. 파일 크기 제한

규칙

모든 문서: 100줄 이하
초과 시: 주제별 분리 또는 참고/실행용 분리

예외

아키텍처 문서: 200줄까지 허용 (섹션 많은 경우)
단, 분리 가능하면 분리 우선

5. 교훈 작성 규칙

필수 항목

원인: 왜 문제가 발생했는가
교훈: 다음에 어떻게 방지할 것인가
원칙: 위반한 원칙이 있는가

올바른 예시

## 교훈

### API 엔드포인트 검증 부족
- 구현 시 skill-rag-file API 스펙 미확인
- 추측으로 /api/query 사용, 실제는 /api/search
- 교훈: 스킬 통합 전 API 문서 또는 코드 직접 확인 필수

금지 예시

## 교훈

에러가 발생했습니다. 다음에 조심하겠습니다.

6. 비난조 문장 금지

금지 표현

"잘못 작성됨"
"버그가 많음"
"엉망진창"

권장 표현

"수정 필요"
"개선 가능"
"리팩토링 대상"

7. 체크리스트

문서 작성 전:

파일명 형식 준수 (yymmdd_주제.md)
파일명:줄번호로 위치 명시
의사코드/추측 제거
100줄 이하 확인
교훈 섹션 작성 (트러블슈팅)
이모지 제거 (명시 요청 없으면)

8. 참고 문서

CLAUDE.md: 전체 개발 가이드
311_FastAPI_구조_원칙.md: 코드 구조 원칙
troubleshooting/ 폴더: 트러블슈팅 예시

4.1 KiB Raw Blame History