ivada-infra/DOCS

Fork 0

Claude-51124 ac998c782e docs: 원칙 문서 보완 - DB 스키마 변경 동기화, LLM 호출 최적화, 트러블슈팅 경로 수정

2025-12-01 12:24:04 +09:00

4.8 KiB

Raw Blame History

문서 작성 원칙

작성일: 2025-10-13 수정일: 2025-12-01 (트러블슈팅 문서 경로 수정) 참고: CLAUDE.md, 311_FastAPI_구조_원칙.md

1. 문서 종류별 규칙

트러블슈팅 문서

경로: DOCS/journey/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 파일 수정  ← 구체적 내용 없음
```python
# 전체 함수 코드 50줄 복사...  ← 불필요


---

## 3. 문서 구조

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

```markdown
# 제목

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

---

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

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

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

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

아키텍처 문서 구조

# 제목

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

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

4. 파일 크기 제한

규칙

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

예외

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

5. 교훈 작성 규칙

필수 항목

원인: 왜 문제가 발생했는가
교훈: 다음에 어떻게 방지할 것인가
원칙: 위반한 원칙이 있는가 (원칙 문서 참조: 311_FastAPI_구조_원칙.md, 312_문서_작성_원칙.md)

올바른 예시

## 교훈

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

금지 예시

## 교훈

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

6. 비난조 문장 금지

금지 표현

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

권장 표현

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

7. 체크리스트

문서 작성 전:

핵심만 간결하게 정리 (불필요한 설명/중복 제거, 링크로 대체)
파일명:줄번호로 위치 명시 (전체 코드 블록 금지)
확인된 사실만 기록 (추측/의사코드 제거)
파일명 형식 준수 (yymmdd_주제.md)
100줄 이하 확인
교훈 섹션 작성 (트러블슈팅)

문서 작성 후:

한 번 더 읽고 핵심 없는 부분/중복 제거

8. 참고 문서

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

4.8 KiB Raw Blame History