포트폴리오 작성 가이드라인 v3 (깃블로그용)

너는 내 코드베이스를 기반으로 깃블로그에 올릴 포트폴리오 문서를 작성해야 한다.

0. 이 문서의 역할

이 문서는 GitHub README와 역할이 다르다.

GitHub README:

이 문서 (깃블로그):

따라서 이 문서에는 다음을 쓰지 않는다:

문서 하단에 GitHub 레포지토리 링크를 달아서 코드와 기술 문서는 그쪽에서 확인하도록 유도한다.

1. 문서 작성 원칙

톤 & 문체

관점

수치 원칙

2. 코드 분석 방법

내 코드베이스에서 다음을 파악하라

[ ] 이 프로젝트가 해결하려는 문제가 뭔지
    → 입력과 출력을 보면 알 수 있다
    → API 엔드포인트, main 함수, 데이터 흐름을 추적하라

[ ] 전체 파이프라인 흐름이 어떻게 되는지
    → 데이터가 어디서 들어와서 어디로 나가는지
    → 각 단계에서 어떤 처리가 일어나는지
    → 함수 호출 순서를 따라가라

[ ] 어떤 기술/라이브러리를 쓰고 있는지
    → requirements.txt, import문, config 파일 확인
    → 각 기술이 파이프라인의 어느 단계에서 쓰이는지 매핑

[ ] 설계상 특별한 선택이 있는지
    → 단순하게 할 수 있었는데 일부러 복잡하게 한 부분
    → config에서 조정 가능한 파라미터들
    → 주석이나 TODO에 남긴 의도

[ ] 에러 처리, 로깅, 평가 코드가 있는지
    → try/except 패턴
    → 로깅 구조
    → 테스트 코드
    → 평가 스크립트

[ ] 개선의 흔적이 있는지
    → git 히스토리에서 구조 변경
    → 주석 처리된 이전 코드
    → v1, v2 같은 버전 흔적
    → config에서 on/off 가능한 기능들

3. 문서 구조 (이 순서대로 작성하라)

3-1. 프로젝트 한 줄 정의

[무슨 문제]를 [어떻게] 해결한 [무엇]

코드의 목적을 한 문장으로 정의한다.

작성 기준:

예시:

3-2. 배경 및 문제 정의

작성할 내용:

왜 이 프로젝트가 필요했는가?
기존에는 어떻게 하고 있었는가?
그게 왜 부족했는가?

필수 규칙:

코드에서 찾는 방법:

작성 형식:

## 배경

[2~3문장. 구체적 숫자 포함]

## 문제

[각 문제를 단정형으로 서술]

| 문제 | 구체적 상황 |
|------|------------|
| ... | [실제 발생한 상황으로. "~할 수 있다" 금지] |

3-3. 기술적 접근

이 섹션이 문서의 핵심이다.

코드에서 추출할 것:

1. 전체 파이프라인을 단계별로 분리하라
   - 코드의 함수/모듈 구조를 따라가면 자연스럽게 나온다

2. 각 단계에서 어떤 기술적 선택을 했는지 파악하라
   - 어떤 모델을 쓰는지
   - 어떤 파라미터를 설정했는지
   - 어떤 전처리를 하는지

3. 그 선택의 이유를 코드 맥락에서 추론하라
   - config에 여러 옵션이 있으면 → 실험을 거쳐 선택한 것
   - 주석이 있으면 → 의도가 담긴 것
   - 복잡한 처리가 있으면 → 단순 방식이 안 됐기 때문

작성 형식 — 각 기술적 선택마다:

### [단계명 또는 개선 포인트]

**문제:**
[이 단계에서 어떤 문제가 있었는지. 단정형으로.]

**접근:**
[어떤 선택지가 있었고, 뭘 골랐는지]

**선택 이유:**
[왜 이걸 골랐는지. 코드에서 근거를 찾아서 쓴다]

**구현:**
[코드에서 실제로 어떻게 구현되어 있는지 핵심만 간결하게]

**결과:**
[이 개선으로 뭐가 달라졌는지. 수치가 있으면 수치로]

코드 인용 기준:

3-4. 시스템 구조

이 섹션의 목적: 전체 파이프라인의 흐름을 보여주되, README에 있는 기술 스택 나열을 반복하지 않는다.

쓸 것:

쓰지 않을 것:

작성 형식:

## 시스템 구조

[입력] → 단계 1: [무엇을 하는지] → 단계 2: [무엇을 하는지] → … [출력]


[각 단계의 순서가 왜 이렇게 되어야 하는지, 기술 선택이 왜 이것인지를 서술]

3-5. 결과 및 성능

이 섹션의 핵심 규칙:

config 값(threshold, retry 횟수, k값, chunk 크기 등)은 결과가 아니다. config 값은 “기술적 접근”에서 이미 언급되었다. 결과 섹션에는 “그래서 뭐가 달라졌는가”만 쓴다.

반드시 포함할 내용:

1) 정성적 개선 (before/after 비교 필수)

| 항목 | 개선 전 | 개선 후 |
|------|---------|---------|
| [문제 항목] | [이전에는 어땠는지] | [지금은 어떻게 바뀌었는지] |

2) 운영 지표

3) 정량 평가 계획 (아직 없는 경우)

3-6. 설계 판단 요약

프로젝트에서 내린 주요 기술적 판단을 표로 정리한다.

## 주요 설계 판단

| 문제 상황 | 선택지 | 선택 | 이유 |
|-----------|--------|------|------|
| [뭐가 문제였는지] | [A / B / C] | [뭘 골랐는지] | [왜] |

코드에서 찾는 방법:

3-7. 한계 및 개선 방향

## 현재 한계

- [한계 1]: [왜 한계인지] → [개선 방향]

코드에서 찾는 방법:

주의:

3-8. 회고

이 섹션은 사고의 깊이를 보여주는 곳이다.

필수 규칙:

작성 형식:

## 회고

### 가장 어려웠던 기술적 판단
[3~5문장. 무엇이 어려웠고, 왜 어려웠고, 어떤 시행착오를 거쳤고, 최종적으로 어떻게 결정했는지]

### 처음 가정과 달랐던 부분
[3~5문장. 처음에 뭘 가정했고, 실제로 돌려보니 뭐가 달랐고, 그래서 뭘 바꿨는지]

### 다시 만든다면 바꿀 부분
[3~5문장. 뭘 바꿀지, 왜 바꿀지, 그러면 뭐가 달라질지]

나쁜 예시 (한 줄짜리):

- 가장 어려웠던 판단: 검색 결합 방식 선택이었다.

좋은 예시 (흐름이 보이는):

요약 문서 검색과 원문 검색을 어떻게 결합할지가 가장 오래 걸렸다.
요약만 검색하면 속도는 빠르지만 원문 위치 연결이 약해졌다.
원문을 직접 검색하면 근거는 강해지지만 chunk 수가 많아져서 노이즈가 늘었다.
결국 요약으로 후보를 좁히고 원문으로 근거를 보강하는 2단계 구조로 결정했다.
이 판단을 내리기까지 단일 검색기로 여러 번 실패한 후였다.

3-9. 코드 링크

문서 하단에 반드시 GitHub 레포지토리 링크를 넣는다.

## 코드

📦 [GitHub Repository](https://github.com/사용자명/프로젝트명)

코드 상세, 기술 스택, 설치법, API 문서는 GitHub README에서 확인할 수 있도록 유도한다.

3-10. 시각 자료 배치 규칙 (GIF/MP4/PNG/JPG)

시각 자료의 목적은 “예쁘게 보이기”가 아니라, 독자가 문서를 읽는 순서에서 이해 속도를 높이는 것이다.

배치 기준은 ‘독자 질문’ 순서다:

  1. 무엇을 만들었나?
    위치: 프로젝트 한 줄 정의 바로 아래
    자료: 최종 결과 PNG/JPG 1장
  2. 무엇이 문제였나?
    위치: 배경/문제 정의 끝
    자료: 문제 재현 PNG/JPG 1장
  3. 어떤 핵심 동작이 차별점인가?
    위치: 기술적 접근의 핵심 단계 직후
    자료: 짧은 MP4 1개 (10~25초)
  4. 그래서 실제로 얼마나 달라졌나?
    위치: 결과/성능 표 바로 아래
    자료: before/after 비교 PNG/JPG 1세트 또는 짧은 GIF 1개
  5. 회고/설계 판단 섹션은 왜 이미지가 없나?
    이유: 이 구간은 추론과 판단 설명 구간이라 텍스트 집중이 더 효과적이다

밀도 규칙:

형식 규칙:

레포 적용 규칙:

4. 최종 체크리스트

문서 작성 후 아래 항목을 모두 확인하라:

문체/톤:
  □ "~했습니다" 체가 아닌 "~했다" 체로 통일되었는가
  □ "~할 수 있다", "~될 수 있다" 같은 가능성 표현이 없는가
  □ "다양한", "혁신적인", "활용하여" 같은 표현이 없는가
  □ "좋은 경험이었다" 류의 감상이 없는가
  □ 한 문장에 정보가 하나만 있는가

한 줄 정의:
  □ 15단어 이내인가
  □ 구현 디테일(모델명, 검색 방식명)이 아닌 문제+결과 중심인가

배경/문제:
  □ 구체적 숫자가 포함되었는가 (문서 수, 폴더 수, 컬렉션 수 등)
  □ 문제 서술이 "~했다"로 단정되었는가 ("~할 수 있다" 아닌지)
  □ 문제 테이블의 "구체적 상황"도 단정형인가

결과 섹션:
  □ config 값(threshold, k, retry 등)이 결과로 들어가지 않았는가
  □ before/after 정성적 비교 표가 있는가
  □ 운영 지표가 실측값 또는 솔직한 "미측정"으로 되어 있는가
  □ 정량 평가 계획이 구체적인가 (평가셋 규모, 지표, 목표 기준)

시스템 구조:
  □ 기술 스택 단순 나열 표가 없는가 (README에 이미 있다)
  □ 기술을 언급할 때 선택 이유가 함께 있는가
  □ 디렉토리 구조, API 스펙이 없는가 (README에 이미 있다)

회고:
  □ 각 항목이 최소 3~5문장인가 (한 줄로 끝나지 않았는가)
  □ 사고 흐름이 보이는가 (어려웠던 이유 → 시행착오 → 결론)

코드 인용:
  □ 전체 코드를 붙이지 않고 핵심만 발췌했는가
  □ 코드 블록 위아래에 맥락 설명이 있는가

README 분리:
  □ 설치법, 실행법이 들어가지 않았는가
  □ API 엔드포인트 목록이 없는가
  □ 프로젝트 디렉토리 구조 전체가 없는가
  □ 문서 하단에 GitHub 링크가 있는가

시각 자료:
  □ 시각 자료가 독자 질문 순서(무엇/문제/핵심동작/결과)에 맞게 배치되었는가
  □ 한 섹션당 1개, 문서 전체 3~4개 밀도를 지켰는가
  □ 카드(`header.teaser`)는 정적 이미지, 본문 데모는 MP4 우선으로 구성했는가
  □ 모든 시각 자료에 1문장 캡션이 있는가
  □ GIF가 5MB를 넘지 않는가 (초과 시 MP4 대체)

5. 절대 하지 말아야 할 것

1. 기술 스택만 나열하고 끝내지 마라
   → 기술은 반드시 "왜 이걸 선택했는지"와 함께

2. 코드 전체를 붙이지 마라
   → 코드는 GitHub 링크로 충분하다
   → 문서에는 핵심 로직 발췌만

3. 튜토리얼처럼 쓰지 마라
   → "먼저 ~를 설치합니다. 다음으로 ~를 합니다" ❌

4. 모든 게 완벽하다고 쓰지 마라
   → 한계를 모르는 것처럼 보이면 신뢰가 떨어진다

5. 학습 과정을 쓰지 마라
   → "처음에 이 개념을 몰랐는데 공부해서 알게 되었다" ❌
   → 포트폴리오는 학습 일기가 아니다

6. 결과 섹션에 config 파라미터를 나열하지 마라
   → threshold, k, retry 횟수 등은 "기술적 접근"에서 이미 다뤘다
   → 결과에는 "뭐가 달라졌는가"만 쓴다

7. 가능성으로 쓰지 마라
   → "~할 수 있다"는 겪어보지 않은 사람의 표현이다
   → "~했다"로 써야 경험에서 나온 문제라는 인상이 생긴다

8. README에 이미 있는 내용을 반복하지 마라
   → 기술 스택 표, 설치법, API 목록, 디렉토리 구조는 README의 영역이다
   → 블로그에서는 "왜 이 기술을 골랐는지"만 다룬다
   → 상세 코드와 구조는 하단 GitHub 링크로 연결한다

6. 최종 문서 목차 요약

1. 프로젝트 한 줄 정의 (15단어 이내, 문제+결과 중심)
2. 배경 및 문제 정의 (구체적 숫자, 단정형 서술)
3. 기술적 접근 (핵심 — 가장 길게. 문제→접근→이유→구현→결과)
4. 시스템 구조 (파이프라인 흐름도. 기술 선택 이유 중심. 스택 나열은 README 참조)
5. 결과 및 성능 (before/after 비교 + 운영 지표 + 평가 계획. config 나열 금지)
6. 주요 설계 판단 (선택지 비교 표)
7. 한계 및 개선 방향 (한계 + 반드시 개선 방향)
8. 회고 (각 항목 3~5문장, 사고 흐름)
9. 코드 링크 (GitHub Repository)
10. 시각 자료 배치 점검 (독자 질문 순서 기준)

이 가이드라인을 기반으로 내 현재 코드베이스를 분석하고, 위 구조에 맞는 깃블로그용 포트폴리오 문서 초안을 작성해줘.