ivada-infra/DOCS
3
0
Fork 0
Code Issues 1 Pull Requests 5 Actions Packages Projects Releases Wiki Activity
DOCS/book/300_architecture/312_문서_작성_원칙.md

15 KiB
Raw Blame History

문서 작성 원칙

작성일: 2025-10-13 수정일: 2026-02-04 (아이디어·시나리오 관리 원칙 추가) 참고: AGENTS.md, 311_백엔드_구조_원칙.md

1. 문서 종류별 규칙

트러블슈팅 문서

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

  • 주제별 파일 분리 (날짜 중복 허용)
  • 시간순 작성
  • 교훈 섹션 필수
  • 크기 제한: 섹션 4 참조
  • ⚠️ 절대 금지: 남은 작업 기록 - 남은 작업을 troubleshooting 문서에 기록하면 다음 작업 시 계획이 어수선해짐. 남은 작업은 반드시 plans/ 문서의 "남은 작업" 섹션에만 기록

필수 헤더:

# 제목

**날짜**: 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 용도: 해당 폴더의 문서 인덱스 및 목차 역할

규칙:

  • 인덱스/목차 역할만 - 문서 목록과 간단한 설명
  • 상세 내용은 링크로 참조 - 트러블슈팅, 계획 등 실제 문서로 링크
  • 핵심 키워드만 - 각 문서의 핵심만 간단히 나열
  • README 본문 상세 금지 - 상태/목표/필요작업/결론의 상세 본문은 원문 문서에만 작성
  • README 중복 금지 - 특정 계획 문서의 본문 3~5줄 요약 템플릿(상태/목표/참고)을 반복 복사하지 않음
  • 중복 작성 금지: 섹션 2 핵심 원칙 참조
  • 크기 제한: 섹션 4 참조

예시:

## 성능 비교 테스트
- [하이브리드 의도 분류 성능 비교](../troubleshooting/260103_하이브리드_의도_분류_성능_비교_테스트.md)
  - 초기: FastPath 49.6%, 제로샷 임베딩 23.4%
  - 개선: 제로샷 임베딩 70.2% (+46.8%p)

금지 사례: 상세 내용 재작성, 코드/테스트 결과 상세 재현, "교훈" 섹션 전체 복사

아이디어 문서

경로: DOCS/journey/ideas/ 규칙:

  • 미구현 아이디어만 유지: 구현 결과가 troubleshooting·plans에 정리되면 ideas 문서 삭제(또는 deprecated/로 이동)
  • 핵심만 기록: 간단한 흐름·배경만 남기고 상세 구현 내용은 계획/트러블슈팅으로 이동

시나리오 문서

경로: DOCS/journey/scenarios/ 규칙:

  • 문서 상단에 상태: 완료 / 부분 / 미구현을 명시
  • 구현 완료 시 대응되는 troubleshooting·plans 링크를 함께 표기
  • UX 흐름만 기록하고 내부 구현 세부 설명은 링크로 참조
  • 사용자/운영자 행동 기준으로 작성 (누가, 언제, 무엇을 하려다, 어디서 막히는지)
  • 기술 용어보다 체감 결과를 우선 기록 (기다림, 재시도, 업무 지연, 실행 실패)
  • 수치는 현재 관측값과 개선 목표를 분리해 표기하고, 달성 전에는 목표를 결과처럼 쓰지 않음
  • 한 시나리오는 반드시 실패 장면 1개와 개선 후 장면 1개를 같은 맥락으로 짝지어 기록

2. 작성 규칙

핵심 원칙 (최우선)

"핵심만 간결하게 정리" - 문서의 모든 내용은 이 원칙을 준수해야 함

  • 불필요한 설명, 중복 내용, 장황한 문장 제거
  • 필요한 정보만 간결하게 기록
  • 관련 정보는 링크로 참조 (중복 작성 금지, 같은 내용이면 새 파일 생성하지 말고 기존 파일 수정)

링크 작성 원칙 (필수)

  • 같은 저장소 문서 링크는 상대경로 Markdown 링크를 사용합니다.
    • 예: [문서명](./파일.md), [상위 문서](../README.md)
  • 다른 저장소 문서 링크는 GitHub 절대 URL을 사용합니다.
    • 예: https://github.com/<org>/<repo>/blob/<branch>/...
  • 로컬 절대경로(/home/..., C:\\...)와 위키링크([[...]])는 GitHub 렌더링 호환성 이슈가 있어 기본 문서 본문에서 사용하지 않습니다.
  • 문서 추가/수정 시 링크 클릭 동작을 반드시 확인한 뒤 커밋합니다.

구조화된 정보 형식 (AI/사람 모두 읽기 좋게)

권장 형식:

  • 표: 비교, 목록, 역할 구분 등 구조화된 정보 표현
  • 파일명:줄번호: 코드 위치 명확히 참조
  • 명확한 키워드: 검색 가능하도록 핵심 단어 명시
  • 목록/부제목: 정보 계층 구조화

금지 형식:

  • JSON/XML 같은 기계적 형식 (사람이 읽기 어려움)
  • 암호화된 코드나 해시값 직접 노출

절대 금지 사항

금지 이유
핵심 없는 장황한 설명 핵심만 간결하게 정리 원칙 위반, 관련 문서 링크로 대체
전체 코드 블록 파일명:줄번호만 명시 (파일 참조 형식 섹션 참조)
의사코드, 추측, 예측 ("아마", "것 같다") 확인된 사실만 기록
이모지 사용 명시적 요청 시만 허용
민감정보 직접 기록 (API 키, 비밀번호, JWT Secret Key, 토큰, DB 연결 정보 등) 보안 위험, 환경변수나 설정 파일로 분리하여 관리
troubleshooting 문서에 남은 작업 기록 다음 작업 시 계획이 어수선해짐, 남은 작업은 반드시 plans/ 문서에 기록

파일 참조 형식

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

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

금지 (전체 코드 복사, 추상적 표현):

- naverworks_briefing.py에서 폴백 제거  ← 구체적 위치 없음
- ir_analyzer.py 파일 수정  ← 구체적 내용 없음
```python
# 전체 함수 코드 50줄 복사...  ← 불필요


---

## 3. 문서 구조

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

```markdown
# 제목

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

---

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

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

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

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

⚠️ **절대 금지**: "남은 작업" 섹션 추가 금지. 남은 작업은 반드시 `plans/` 문서에 기록

아키텍처 문서 구조

# 제목

**작성일**: 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)

올바른 예시

## 교훈

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

금지 예시

## 교훈

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

6. 비난조 문장 금지

금지 표현

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

권장 표현

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

7. 체크리스트

문서 작성 전:

  • 핵심만 간결하게 정리 (섹션 2 핵심 원칙 참조)
  • 파일명:줄번호로 위치 명시 (섹션 2 파일 참조 형식 참조)
  • 확인된 사실만 기록 (추측/의사코드 제거)
  • 파일명 형식 준수 (yymmdd_주제.md)
  • 문서 유형별 크기 제한 확인 (섹션 4 참조)
  • 교훈 섹션 작성 (트러블슈팅, 섹션 5 참조)
  • troubleshooting 문서 작성 시: 남은 작업 섹션 추가 금지 (남은 작업은 반드시 plans/ 문서에 기록)

문서 작성 후:

  • 한 번 더 읽고 핵심 없는 부분/중복 제거 (섹션 2 핵심 원칙 참조)
  • troubleshooting 문서 검토: "남은 작업" 섹션이 있다면 삭제하고 plans/ 문서로 이동

원칙 실행 시: 선택적 독해·단계 압축 방지

원칙을 실행할 때 다음을 반드시 지킨다.

  1. 체크리스트 강제 실행: 해당 문서(예: 312 본문 270~276줄)의 체크리스트를 작업 시작 전에 읽고, 각 항목을 순서대로 확인한 뒤 실행한다. 사용자 지시(예: "푸시해")만 보고 단계를 건너뛰지 않는다.
  2. 키워드 검색 후 전체 문장 읽기: 원칙에서 키워드(예: "archive 이동")를 찾았으면 해당 줄만 보지 말고, 앞뒤 3줄을 포함해 조건절(예: "troubleshooting 문서 작성과 동시에")이 있는지 확인한 뒤 실행한다.
  3. 완료 조건 명시적 확인: "완료"라고 판단하기 전에, 해당 원칙에서 완료의 정의(필수 단계 목록)를 찾아 누락 단계가 없는지 확인한 뒤 완료 처리한다.

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/ 폴더: 트러블슈팅 예시