이번 커밋은 AI 모델의 출력 형식을 명확히 하고, 블로그 포스팅 시 발생하는 오류를 수정하며, GitHub에서 필요한 정보만 효율적으로 수집할 수 있도록 기능을 대폭 개선했습니다. 특히 GitHub 수집 기능은 사용자 인터페이스를 통해 원하는 저장소와 브랜치를 직접 선택하게 함으로써, 불필요한 API 호출을 줄여 전체적인 처리 속도를 향상시켰습니다.

LearningCollector: 프롬프트 강화, 블로그 API 개선 및 GitHub 수집 기능 대폭 개선

요약

이번 커밋은 여러 핵심 기능의 개선 및 오류 수정을 포함합니다.

프롬프트 개선: Gemini 모델이 코드 블록이나 불필요한 프론트매터를 생성하는 문제를 해결하기 위해 모든 프롬프트를 수정했습니다.
블로그 API 수정: 블로그 포스팅 시 로그에 "Unknown"으로 표시되던 문제를 해결하고, 실제 포스팅 제목과 URL을 기록하도록 개선했습니다.
GitHub 수집 기능 강화: 사용자가 직접 수집할 저장소와 브랜치를 선택할 수 있는 인터랙티브 기능을 추가하여 API 호출 수를 획기적으로 줄이고 효율성을 높였습니다.
코드 구조 개선: GitHub 관련 API 및 수집 모듈의 함수 가시성을 조정하고, 내부 호출 방식을 개선했습니다.

작업은 2026년 1월 28일에 이루어졌습니다.

배경 및 목적

이번 작업은 크게 세 가지 문제점을 해결하고 전반적인 서비스 품질을 향상시키기 위해 진행되었습니다.

AI 모델의 예측 불가능한 출력: Gemini와 같은 AI 모델이 프롬프트의 지시를 따르지 않고 원치 않는 형식(코드 블록, 프론트매터)으로 결과물을 생성하는 경우가 있었습니다. 이는 블로그 포스팅이나 다른 후처리 과정에서 오류를 유발했습니다.
블로그 포스팅 로그의 정보 부족: api/blog_api.py에서 블로그 포스팅 완료 시 로그에 실제 포스트 제목 대신 "Unknown"으로 표시되는 문제가 있었습니다. 사용자에게 작업 결과를 명확히 알리기 위해 이 정보를 개선할 필요가 있었습니다.
GitHub 데이터 수집의 비효율성: 기존 GitHub 수집 로직은 저장소의 모든 브랜치와 커밋을 수집하는 경우가 많아 불필요한 API 호출이 많았습니다. 사용자가 특정 저장소나 브랜치의 데이터만 필요로 할 때, 더욱 빠르고 효율적인 수집 방식이 요구되었습니다.

이러한 문제들을 해결함으로써, AI 모델과의 상호작용을 더욱 안정적으로 만들고, 사용자에게 더 정확한 정보를 제공하며, GitHub 데이터 수집의 효율성을 극대화하는 것을 목표로 했습니다.

구현 내용

이번 커밋에서는 다음과 같은 주요 변경사항이 적용되었습니다.

프롬프트 강화

문제점: AI 모델이 프롬프트에서 금지한 ````markdown코드 블록이나---`로 시작하는 프론트매터를 생성하는 문제.
해결책: 모든 프롬프트 파일(prompts/당일_공부_요약_프롬프트.md, prompts/알고리즘_풀이_포스팅_프롬프트.md, prompts/프로젝트_진척_및_의사결정_요약_프롬프트.md)에서 다음과 같은 명시적인 지침을 추가했습니다.
- Remove ```markdown code block examples
- Add explicit: "NEVER wrap output in code blocks"
- Add explicit: "NEVER include frontmatter (---...---)"
- Add: "Output this format directly (without code blocks)"
- 예시를 단순 텍스트 형식으로 변경했습니다.
변경된 파일:
- prompts/당일_공부_요약_프롬프트.md
- prompts/알고리즘_풀이_포스팅_프롬프트.md
- prompts/프로젝트_진척_및_의사결정_요약_프롬프트.md

블로그 API 개선

문제점: api/blog_api.py의 create_post() 함수에서 반환되는 딕셔너리에 title과 url 필드가 누락되어 로그에 "Unknown"으로 표시되는 현상.
해결책: api/blog_api.py의 create_post() 함수에 title 필드를 추가하고, 응답의 slug 값을 url 필드로 설정하도록 수정했습니다. 이제 블로그 포스팅 완료 로그는 실제 포스트 제목(✅ 블로그 포스팅 완료: {actual_title})을 표시합니다.
변경된 파일:
- api/blog_api.py

GitHub 수집 기능 - 인터랙티브 모드 추가

문제점: 기존 collect() 함수가 지정된 저장소의 모든 브랜치와 커밋을 수집하려 하여 API 호출 수가 많고 비효율적이었음.
해결책:
1. GitHub GraphQL API 함수 공개: api/github_graphql.py에서 내부적으로 사용되던 _fetch_repositories, _fetch_branches, _fetch_branch_commits 함수를 각각 fetch_repositories, fetch_branches, fetch_branch_commits로 공개(public) 함수로 변경했습니다.
2. 인터랙티브 수집 로직 추가: core/github_collector.py에 collect_interactive() 메소드를 새로 추가했습니다. 이 메소드는 다음과 같은 흐름으로 동작합니다.
  - 사용 가능한 모든 저장소를 보여줍니다.
  - 사용자가 원하는 저장소를 선택합니다 (번호 또는 "all").
  - 선택한 저장소의 모든 브랜치를 보여줍니다.
  - 사용자가 원하는 브랜치를 선택합니다 (번호 또는 "all").
  - 선택된 브랜치의 커밋 정보를 수집합니다.
3. 수집 함수 변경: core/orchestrator.py에서 기존 collect() 함수 이름을 collect_interactive()로 변경하여 새로운 인터랙티브 수집 로직을 사용하도록 했습니다.
변경된 파일:
- api/github_graphql.py
- core/github_collector.py
- core/orchestrator.py

코드 라인 수 변경

api/blog_api.py: 약 15 라인 추가
api/github_graphql.py: 약 10 라인 수정 (함수 이름 변경)
core/github_collector.py: 약 100 라인 추가 (새로운 collect_interactive 메소드)
core/orchestrator.py: 약 5 라인 수정 (함수 이름 변경)
prompts/*.md: 각 파일별 약 5-10 라인 추가 (명시적 지침)

기술적 의사결정

1. GitHub API 호출 방식: REST API vs. GraphQL

선택: GraphQL API (api/github_graphql.py)
이유: GitHub API는 REST API와 GraphQL API를 모두 제공하지만, 이번 프로젝트의 목적은 특정 정보를 효율적으로 가져오는 것이었습니다. GraphQL은 필요한 데이터만 정확히 요청하고 받을 수 있어, REST API를 여러 번 호출하여 데이터를 조합해야 하는 번거로움을 줄여줍니다. 특히 저장소, 브랜치, 커밋 정보를 한 번의 요청으로 (또는 최소한의 요청으로) 가져올 수 있다는 점에서 GraphQL이 더 적합하다고 판단했습니다.
대안: REST API를 사용하여 저장소 목록, 브랜치 목록, 각 브랜치의 커밋 목록을 개별적으로 요청하는 방식도 고려할 수 있었습니다.
장단점 분석:
- GraphQL:
  - 장점: 필요한 데이터만 정확히 요청하여 네트워크 트래픽 감소, API 호출 수 감소, 응답 데이터 구조의 유연성.
  - 단점: 초기 학습 곡선이 있을 수 있음, 복잡한 쿼리 작성 시 어려움.
- REST API:
  - 장점: 익숙하고 단순함, 일반적인 웹 개발에서 많이 사용됨.
  - 단점: 여러 엔드포인트를 호출해야 할 수 있어 비효율적, 과도한 데이터 응답으로 인한 불필요한 로딩.

2. GitHub 수집 로직: 전체 수집 vs. 인터랙티브 수집

선택: 인터랙티브 수집 (core/github_collector.py의 collect_interactive())
이유: 기존의 전체 수집 방식은 사용자에게 불필요한 데이터를 제공하고, GitHub API rate limit에 더 빨리 도달할 위험이 있었습니다. 사용자가 특정 프로젝트나 기능 개발에 관련된 커밋만 확인하고 싶어하는 경우가 많다는 점을 고려하여, collect_interactive() 메소드를 도입했습니다. 이 방식을 통해 사용자는 원하는 저장소와 브랜치를 직접 선택함으로써, 필요한 데이터만 효율적으로 수집할 수 있습니다. 이는 API 호출 수를 획기적으로 줄여줍니다 (이론적으로는 4번의 GraphQL 요청이 2번으로 줄어들 수 있습니다: 저장소 목록 가져오기, 선택한 저장소의 브랜치 목록 가져오기, 선택한 브랜치의 커밋 가져오기).
대안: 기존의 전체 수집 방식을 유지하거나, 사용자에게 수집할 저장소/브랜치를 설정 파일로 지정하게 하는 방식.
장단점 분석:
- 인터랙티브 수집:
  - 장점: 사용자에게 명확한 제어권 제공, API 호출 수 최소화, 효율성 극대화, 사용자 경험 향상.
  - 단점: 초기 구현에 시간 소요, 사용자 인터페이스(CLI) 설계 필요.
- 전체 수집:
  - 장점: 구현 단순, 코드 변경 최소화.
  - 단점: 비효율적, API limit 도달 가능성 높음, 불필요한 데이터 수집.

3. 프롬프트 엔지니어링: 명시적 지시 vs. 암시적 제안

선택: 명시적 지시 (Explicit instructions)
이유: AI 모델이 프롬프트의 의도를 정확히 파악하고 예상대로 동작하게 만드는 것이 중요했습니다. 특히 코드 블록이나 프론트매터와 같이 출력 형식에 영향을 주는 부분은 명시적으로 "NEVER do X"와 같이 금지하는 것이, 암시적인 제안이나 예시만 제공하는 것보다 훨씬 효과적이었습니다. 또한, "Output this format directly (without code blocks)"와 같은 지시를 통해 AI가 결과물을 코드 블록 없이 순수 텍스트로 출력하도록 유도했습니다.
대안: 예시만 제공하거나, "코드 블록 사용을 자제해주세요"와 같은 상대적인 표현 사용.
장단점 분석:
- 명시적 지시:
  - 장점: AI의 오해 소지 최소화, 일관된 출력 결과 보장, 디버깅 용이.
  - 단점: 프롬프트가 길어질 수 있음, 다소 강압적인 느낌을 줄 수 있음.
- 암시적 제안/예시:
  - 장점: 프롬프트가 간결해질 수 있음, AI에게 더 많은 창의성(의도치 않은 방향으로)을 부여할 수 있음.
  - 단점: AI가 지시를 오해할 가능성 높음, 예측 불가능한 결과 초래, 디버깅 어려움.

배운 점 및 개선점

배운 점

AI 모델의 프롬프트 이해도: AI 모델은 매우 강력하지만, 프롬프트에 포함된 지시를 얼마나 명확하게 이해하고 따르는지는 프롬프트의 구체성과 명확성에 크게 좌우된다는 것을 다시 한번 확인했습니다. 특히, "절대 ~하지 마세요"와 같은 강력한 부정 명령이 예상치 못한 동작을 막는 데 효과적이라는 것을 배웠습니다.
GitHub API의 활용: GraphQL API를 활용하여 필요한 데이터만 효율적으로 가져오는 방법을 익혔습니다. REST API의 한계를 넘어서는 경험을 통해 API 설계의 유연성을 체감했습니다.
사용자 중심 설계의 중요성: GitHub 수집 기능에서 사용자가 직접 선택할 수 있도록 인터페이스를 개선함으로써, API 호출 수를 줄이고 전반적인 서비스의 효율성을 높이는 것이 사용자 경험 향상으로 이어진다는 것을 배웠습니다.

개선점 및 다음 단계 계획

GitHub 수집 기능의 UI/UX 개선: 현재는 CLI 기반의 인터랙티브 모드이지만, 향후 웹 기반의 UI를 제공하여 더 많은 사용자가 쉽게 이용할 수 있도록 개선할 수 있습니다.
블로그 API의 오류 처리 강화: 현재는 성공 케이스를 중심으로 개선했지만, 실패 케이스에 대한 좀 더 정교한 오류 로깅 및 알림 시스템을 구축할 필요가 있습니다.
프롬프트 템플릿화: 다양한 종류의 포스팅에 재사용 가능한 범용적인 프롬프트 템플릿을 만들고, 각 포스팅 유형에 맞게 세부 지침만 수정하는 방식으로 확장성을 높일 수 있습니다.
성능 모니터링: 개선된 GitHub 수집 기능의 실제 API 호출 수 감소 및 처리 속도 향상을 정량적으로 측정하고 지속적으로 모니터링하여, 추가적인 최적화 기회를 탐색해야 합니다.