머지한 코드에서 배울 CS 지식을 질문과 해설로 남기는 GitHub·GitLab 학습 봇.
PR/MR이 머지되면 최종 변경을 읽고 기본 수준의 객관식 질문 2개를 댓글로 남깁니다. 답을 고르면 코드 근거와 CS 원리를 함께 설명하고, 더 공부하고 싶을 때 추가 질문 5개를 요청할 수 있습니다.
English · 시작하기 · 댓글 명령 · 설치와 연결 · 운영 가이드
- PR/MR을 머지합니다. 열기·재열기·푸시에는 자동 질문을 만들지 않습니다.
- 질문 2개를 풉니다. Q1은 승인 전에 알아야 할 변경의 효과를, Q2는 이 변경의 정확성이 기대는 원리를 이번 변경의 상황에서 A~D 보기로 묻습니다. 최초 질문에 심화 문제를 섞지 않습니다.
- 해설로 변경을 확인합니다. 해설은 변경 전후의 동작 차이, 그 차이가 중요한 이유, 잘못 이해하면 무엇이 틀어지는지를 설명하고, 오답 해설은 어떤 오독인지와 코드가 실제로 하는 일을 짚습니다. 핵심 구절은 굵게 표시합니다.
- 필요하면 더 풀어봅니다.
/hey whatelse는 이 변경의 트레이드오프·실패 경계·호출부·데이터·운영·호환성 영향·보장 확인 방법을 묻는 심화 질문을 최대 5개 냅니다. CS 개념 자체를 깊게 파는 질문은/hey csinterview·/hey morecs(면접·꼬리)가 맡습니다.
질문과 답변은 한국어로 작성합니다. hey는 코드 이해를 위한 봇이며, 자동 결함 탐색·코드 수정·PR 승인·머지를 수행하지 않습니다.
아래는 결제 재시도에 같은 멱등 키를 전달하는 코드를 가정한 질문 한 개의 예시입니다. 실제 최초 댓글에는 두 문제가 표시됩니다.
A. 재시도마다 새 승인을 만들기 위해서입니다.
B. 동일 요청을 식별해 중복 승인을 막기 위해서입니다.
C. 주문 저장을 생략하기 위해서입니다.
D. 모든 재시도를 금지하기 위해서입니다.
답변 달기:
/hey answer Q1 B
정답·해설 보기: 이 질문 스레드에 답글로/hey showanswer
더 풀어보기:/hey whatelse
질문은 H4 제목으로 구분하고 문제 뒤에 빈 줄을 둡니다. 기준 커밋은 해시 대신 커밋 제목을 링크한 목록으로 표시합니다. 추가 질문은 별도의 묶음 제목이나 [심화] 태그 없이 첫 문제부터 시작합니다.
해설은 정답 보기의 문장을 먼저 보여 주고, 해설 → 보기별 해설 → 코드 근거 순서로 이어집니다. 보기별 설명은 보기 다음 줄에 들여쓰며, 각 설명은 CS 원리와 코드의 조건을 연결하는 1~3문장으로 생성합니다. 내 답과 정답의 보기 문자를 나란히 표시하지 않습니다.
최초 질문 예시 · 심화 질문·채점 예시 · @hey 답변 예시
연결된 PR/MR에 댓글을 남기면 됩니다. 명령 사용자는 GitHub Write 또는 GitLab Developer 이상 권한이 필요합니다. 닫히거나 머지된 PR/MR에서도 명령을 사용할 수 있습니다.
| 하고 싶은 일 | 댓글 |
|---|---|
| 도움말 보기 | /hey help |
| 한 문제 답하기 | /hey answer Q1 B |
| 여러 문제 답하기 | /hey answer Q1 B Q2 A |
| 답글을 남긴 질문 댓글의 정답·해설 보기 | /hey showanswer |
| 이 변경을 더 깊게 묻는 심화 질문 받기(최대 5개) | /hey whatelse |
| 핵심 CS 면접 질문 2개 받기 | /hey csinterview |
| 최근 면접 질문을 파고드는 꼬리 질문 받기 | /hey morecs |
| 질문 다시 만들기 | /hey tryagain |
| 이 변경과 코드에 관해 질문하기 | @hey 재시도할 때 키를 재사용하는 이유가 뭔가요? |
- 답 뒤에 이유를 덧붙일 수 있습니다. 예:
/hey answer Q1 B 같은 요청의 승인을 재사용해야 하기 때문입니다. - 질문 하나가 있는 인라인 스레드에는
B처럼 보기 문자만 답해도 채점합니다. 요약 댓글에서는 질문 번호를 사용하세요. - 보기만 고르면 저장된 정답으로 채점합니다. 이유를 쓰면 모델이 그 이유를 평가합니다. 변경 질문(Q·심화)은 동작·이유·영향 중 무엇을 잘못 읽었는지 코드 근거와 함께 짚고, 정답을 틀린 이유로 고른 경우는 부분 정답으로 알려 줍니다. 면접·꼬리 질문은 개념과 용어를 평가합니다.
- 정답 여부는 저장된 정답이 정하고, 해설과 보기별 해설도 저장된 내용을 그대로 보여 줍니다. 그래서 채점 결과와
/hey showanswer의 해설이 같습니다. /hey showanswer는 저장된 해설을 보여 주며 모델을 호출하거나 답변 완료로 처리하지 않습니다.@hey답변은 질문의 전제가 코드와 다르면 먼저 바로잡고, 답 → 이유 → 코드 근거(코드 링크) → 확인하지 못한 것 순서로 씁니다. 코드에서 찾으면 되는 질문에는 CS 개념 설명을 붙이지 않습니다.- 해설 범위는 답글을 남긴 질문 댓글로 정합니다. 최초 질문 댓글 아래에서 호출하면 최초 질문만, 추가 질문 댓글 아래에서 호출하면 그 묶음만 공개합니다. 개별 번호를 붙이는 형식은 지원하지 않습니다.
- 추가 질문은 묶음마다 새 스레드에 게시합니다. 질문 스레드 밖에서 호출하면 해당 질문 댓글에 답글을 남기도록 안내합니다. 이전 코드 버전이나 여러 질문 묶음이 섞인 옛 스레드에서는 임의로 해설을 선택하지 않습니다.
- GitLab에서는 질문 댓글의 답글을 사용하세요. GitHub의 일반 PR 댓글에는 하위 답글이 없으므로 코드에 달린 질문 스레드를 사용합니다. 추가 질문 묶음은 별도 코드 스레드에 함께 게시하며, 최초 인라인 스레드에서는 그 스레드에 표시된 한 문제만 해설합니다.
추가 질문 번호는 같은 코드 버전에서 심화1~5, 심화6~10처럼 이어집니다. 기준을 통과한 질문이 5개보다 적으면 채우지 않고 사유와 함께 적게 냅니다. PR/MR 전체에서 코드 버전당 최대 5회 요청할 수 있습니다. 이전 코드 버전의 질문·답변 이력은 보존합니다.
/hey csinterview는 이번 변경이 실제로 기대는 가장 핵심적인 CS 개념 2개를 골라 개념마다 4지선다 면접 문항을 하나씩 냅니다. 모든 주니어가 알아야 할 기본기(예: 격리 수준별로 막는 이상 현상, 멱등성과 재시도, 경쟁 조건)를 기본성 > 변경 관련성 > 몰랐을 때의 비용 > 전이성 순으로 고릅니다. 문항은 개념의 한 층 아래(왜 성립하는지, 언제 깨지는지, 무엇을 대가로 치르는지)를 묻고, 개념을 모르는 사람과 정의만 아는 사람이 모두 틀리도록 만듭니다. 이름·정의 고르기, 벤더 옵션·정확한 수치·API·저장소 규칙처럼 찾아보면 되는 세부 사항은 출제하지 않습니다.
/hey morecs는 같은 코드 버전에서 가장 최근의 면접 묶음(처음에는 csinterview 2문항, 그다음에는 직전 morecs 묶음)을 앵커로 삼아 최대 4문항을 냅니다.
- 기본은 꼬리 질문 3개 + 새 면접 질문 1개입니다. 아직 다루지 않은 핵심 개념이 기준을 충족하지 않으면 꼬리 질문 4개를 냅니다.
- 앵커 묶음의 면접 질문마다 꼬리 질문을 하나 이상 답니다. 파고들면 지엽적인 세부로 흐를 앵커는 건너뛰고, 기준을 통과한 문항이 4개보다 적으면 사유와 함께 적게 냅니다.
- 꼬리 질문은
꼬리1,꼬리2…, 새 면접 질문은면접N을 이어 번호를 붙입니다. 꼬리 질문에는↳ 면접2에서 이어짐처럼 어느 질문에서 이어졌는지 표시합니다. - 면접 질문이 아직 없으면 먼저
/hey csinterview를 안내합니다.
공통 규칙:
- 답변:
/hey answer 꼬리2 B 면접3 C처럼 섞어서 답할 수 있습니다. 보기만 고르면 저장된 정답으로 채점하고, 오답이면 고른 보기가 어떤 개념을 혼동했는지 먼저 보여 줍니다. 이유를 덧붙이면 모델이 놓친 개념의 이름과 핵심을 짚어 줍니다. - 해설은 신입이 개념을 배울 수 있도록 개념 이름(한국어·영어)과 정의, 메커니즘, 이번 조건에서의 결론, 결론이 바뀌는 조건을 최대 5문장으로 설명합니다. 오답 해설은 혼동한 개념의 핵심을 최대 두 곳 굵게 표시합니다.
- 해당 질문 스레드에
/hey showanswer로 답글을 남기면 그 묶음의 저장된 정답·해설만 보여 줍니다. 모델을 호출하거나 답변 완료로 처리하지 않습니다. - csinterview와 morecs는 각각 코드 버전당 최대 5회 생성할 수 있고, 이전 질문 전체와 겹치지 않게 출제합니다. 면접·꼬리 질문은 머지 전 답변 완료 조건에 추가되지 않습니다.
면접 질문·해설 예시와 꼬리 질문 예시는 모델을 호출하지 않는 고정 예시입니다. 실제 모델 출력 검증은 docs/verification에 기록합니다. 출제 지침과 구조 검증이 질문·정답의 의미적 정확성까지 보장하지는 않습니다.
Node.js 22 이상, npm, Git이 필요합니다. 서버와 통합 테스트에는 Docker Compose 또는 Docker Compose를 사용할 수 있는 Colima가 필요합니다.
먼저 API 키나 외부 계정 없이 댓글 예시를 만들어 볼 수 있습니다.
git clone https://github.com/thisis-joe/codereviewbot.git
cd codereviewbot
npm ci --ignore-scripts
npm run demo다음 파일을 열어 질문·해설 형식을 확인하세요. 데모는 고정 예시를 사용하며 모델을 호출하지 않습니다.
| 생성 파일 | 내용 |
|---|---|
.local/demo-report.md |
최초 질문 댓글 |
.local/demo-inline.md |
코드 줄에 달리는 질문 |
.local/demo-learning.md |
심화 질문(5개 미만과 사유), 정답을 틀린 이유로 고른 채점, 같은 질문의 정답·해설 |
.local/demo-hey.md |
전제를 바로잡는 @hey 답변 |
.local/demo-csinterview.md |
CS 면접 질문과 스레드 정답·해설 |
.local/demo-morecs.md |
꼬리 질문 묶음, 섞어 답한 채점, 스레드 정답·해설 |
.local/demo-help.md |
전체 명령 도움말 |
node scripts/setup.mjs내부 인증 값과 DB 비밀번호가 담긴 .env, 연결 대상 목록인 config/repositories.yaml을 준비합니다. 기존 값은 유지하며 외부 저장소 연결은 기본적으로 꺼져 있습니다.
.env에 발급받은 GMS 키를 넣으세요.
MODEL_PROVIDER=gms
GMS_KEY=<발급받은 키>
GMS_MODEL=gpt-6.1-sol
GMS_RESPONSES_URL=https://gms.ssafy.io/gmsapi/api.openai.com/v1/responses기본 엔진은 GMS Responses API 직접 호출입니다. MODEL_PROVIDER=gms일 때 Claude CLI를 호출하지 않으며, 오류가 나도 다른 엔진으로 자동 전환하지 않습니다. GMS_KEY가 없으면 실행기가 시작하지 않습니다. 선택적으로 Codex CLI·Claude Code CLI를 사용할 수 있으며, 인증 방법은 연결 가이드에 있습니다.
docker compose build controller runner
docker compose up -dhttp://localhost:5688에서 n8n의 최초 Owner 계정을 설정한 뒤 워크플로를 등록하고 확인합니다.
node scripts/bootstrap-n8n.mjs
node scripts/smoke.mjs컨트롤러 상태는 http://localhost:18092/healthz에서 확인합니다. 스모크 검사는 상태 확인, 내부 인증, n8n에서 컨트롤러로의 호출을 검사하며 실제 모델·GitHub·GitLab 연결까지 검증하지는 않습니다.
연결 가이드에 따라 봇 인증, config/repositories.yaml의 저장소·실제 봇 계정, 웹훅을 설정하고 enabled: true로 켭니다. 환경 값을 바꾸면 해당 서비스 컨테이너를 다시 생성해 적용하세요.
| 플랫폼 | 웹훅 경로 | 질문·명령에 필요한 이벤트 |
|---|---|---|
| GitHub | /webhooks/github |
Pull request, Issue comment, Pull request review comment |
| GitLab | /webhooks/gitlab |
Merge request, Comment/Note |
웹훅에는 서명 인증을 적용합니다. 외부에서 받을 HTTPS 주소가 필요하며 Cloudflare Tunnel을 선택할 수 있습니다. n8n·DB·실행기·내부 API는 공개하지 않습니다. GitLab의 Mattermost 알림은 운영 가이드에서 별도로 설정합니다.
연결 후 작은 PR/MR을 머지해 질문 2개가 생성되는지 확인하고, 답변·해설·추가 질문까지 실행하세요. 이미 머지된 과거 PR/MR을 일괄 출제하지 않으므로 필요하면 /hey tryagain으로 요청합니다.
.env, 토큰, 개인 키와 config/repositories.yaml은 커밋하지 않습니다. 서비스를 일시 중지할 때는 docker compose stop을 사용하세요. docker compose down -v는 DB와 인증·n8n 볼륨을 삭제합니다.
대상 저장소의 기준 브랜치에 .hey.yaml을 두면 출제 범위와 맥락을 지정할 수 있습니다.
version: 1
exclude:
- "generated/**"
pathInstructions:
- path: "src/payments/**"
instructions: "멱등성과 외부 결제 호출의 실패 경계를 묻는다."정책은 기준 브랜치에서 읽으며 PR 안에서 바꾼 정책을 그 PR에 바로 적용하지 않습니다. .hey.yaml이 없으면 .codereviewbot.yaml을 사용합니다. 기준 브랜치의 AGENTS.md, docs/coding-standards.md와 연결된 이슈도 맥락으로 활용합니다.
선택 기능: 머지 전 수동 질문에 답변 완료 조건 적용
.hey.yaml의 requireAnswers: true와 저장소의 필수 상태 검사를 함께 설정하면, 머지 전 수동으로 생성한 최초 질문에 대한 답변 완료를 요구할 수 있습니다. 봇은 codereviewbot/questions 상태를 남기며 실제 차단은 저장소 설정이 담당합니다.
오답이어도 채점 결과가 게시되면 답변으로 인정합니다. 추가 질문과 정답 보기 명령은 완료 조건에 포함되지 않습니다. 자동 질문은 머지 후에 생성하므로 이 조건을 적용하지 않습니다. 권한·보호 규칙 설정은 연결 가이드를 참고하세요.
flowchart LR
Git[GitHub · GitLab] -->|머지 · 댓글 웹훅| Controller[controller]
Controller --> DB[(PostgreSQL)]
Controller -->|작업 도착 알림| N8N[n8n]
N8N -->|준비 · 생성 · 검증 · 게시 · 복구 지시| Controller
Controller -->|고정 코드 스냅샷| Runner[runner]
Runner -->|기본 엔진| GMS[GMS Responses API]
Controller -->|질문 · 해설 댓글| Git
컨트롤러가 웹훅을 인증하고 작업·학습 이력을 저장합니다. n8n이 준비·생성·검증·게시 단계와 완료 대기·재시도·복구를 관리하고, 실행기는 고정된 코드 스냅샷을 읽어 질문을 생성합니다. 게시 전에는 코드 기준과 기존 댓글을 확인해 오래된 결과와 중복 게시를 방지합니다.
단계별 API, n8n 노드 구성과 전환·복구 방법은 n8n 실행 흐름을 참고하세요.
- 모델에는 스냅샷 파일 목록·읽기·검색 도구만 제공합니다. 대상 저장소의 설치 스크립트·코드·테스트를 실행하지 않습니다.
- GMS 호출 시 출제에 필요한 소스를 GMS로 전송합니다. 실행기에는 호스트 홈·Docker 소켓·Git 캐시를 마운트하지 않습니다.
- 질문의 구조, 코드 위치, 정답키 형식을 검사합니다. 모델이 만든 정답의 의미적 정확성까지 보장하지는 않습니다.
- 읽을 수 있는 변경이 없으면 사유를 표시합니다. 크기 제한이나 생성 실패는 댓글에 안내합니다.
npm test # 빌드 + 단위 테스트
node scripts/integration.mjs # 임시 PostgreSQL로 통합 테스트
npm run demo # 모델 호출 없이 댓글 예시 생성이미 테스트 DB가 있다면 TEST_DATABASE_URL을 지정해 npm run test:integration을 실행할 수 있습니다. 통합 테스트에는 운영 DB를 사용하지 마세요.
| 경로 | 역할 |
|---|---|
src/ |
컨트롤러·실행기, GMS 어댑터, 질문·채점·렌더링 |
config/ · ops/ |
연결 예시, DB 초기화와 터널 설정 |
migrations/ |
PostgreSQL 스키마 |
n8n/ · scripts/ |
워크플로, 설치·검증 도구 |
test/ |
단위·통합 테스트 |
docs/ |
연결·운영 가이드, 출력 예시와 구현 기록 |