PR과 본문 YAML

PR 규칙

• 실험 브랜치마다 PR을 하나씩 만듭니다. 실험을 시작할 때 바로 Draft PR로 열어두세요.
• PR의 base는 부모 브랜치로 지정해요. 파생 실험이면 부모 실험 브랜치, research에서 시작했다면 research로 설정합니다.
• PR 제목에는 검증하려는 가설을 한 줄로 알기 쉽게 적어주세요.
• 실험 결론을 낼 때:
  • 채택(adopted): 부모 브랜치(research 또는 부모 실험)로 머지합니다. research로 머지했다면 다음 버전 태그를 꼭 붙여주세요(research 버전 태그).
  • 기각(rejected): 본문에 결론을 남기고 PR을 닫습니다. 이때 브랜치는 지우지 않고 그대로 둬요.
• 여러 후보 아이디어 중 하나가 채택되면 나머지 PR은 모두 닫아서 깔끔하게 정리해요.

PR 본문 형식

PR 본문 맨 위에 yaml 코드 블록을 하나 넣어주세요. 뷰어는 첫 번째 yaml 블록만 읽으므로, 그 아래에는 자유롭게 마크다운으로 작성하면 됩니다.

```yaml
parent: experiment/baseline-moshi
hypothesis: depth transformer lr을 절반으로 줄이면 초반 발산이 줄어든다
change: lr 3e-4 → 1.5e-4
metrics:
  val_loss: 2.31
  wer: 0.184
wandb: https://wandb.ai/...
status: rejected
tags: [lr]
```

## 결론
발산은 줄었지만 수렴이 느려서 기각.

## 메모
...

필드

필드	필수	타입	설명
parent	권장	string	부모 실험 브랜치 이름입니다. research에서 시작했다면 research@vN 형식으로 적고, 비워두면 PR의 base 브랜치를 써요
hypothesis	필수	string	검증하려는 가설을 한 문장으로 적어요
change	권장	string	코드나 설정 변경점 요약
metrics	선택	map<string, number | string>	최종 메트릭입니다. 키 이름은 팀 규칙에 맞춰 적어주세요
wandb	선택	URL	학습 곡선 같은 외부 대시보드 링크예요. 상세 패널의 "학습 기록" 링크로 연결됩니다
status	선택	running | adopted | rejected	PR 상태로 자동 판단된 값을 직접 덮어쓸 때만 사용해요
tags	선택	list<string>	분류용 태그 목록 (예: lr, data, arch)
started	선택	날짜 YYYY-MM-DD	실험 시작일입니다. 비워두면 브랜치 첫 커밋, 그다음 PR 생성 시각을 차례로 확인해요(시간축과 계절)
ended	선택	날짜 YYYY-MM-DD	마지막 작업일입니다. 비워두면 브랜치 마지막 커밋, 그다음 PR 머지/close/수정 시각을 차례로 확인해요
claims	선택	list<string>	이 실험이 검증하는 의도 문서의 주장 id (예: [N1]). 의도·스펙 기반 개발
spec	선택	none	값만 조정해서 스펙을 바꾸지 않는 실험이라는 표시

• 정의되지 않은 낯선 필드가 있어도 무시할 뿐 지우지 않아요. 뷰어나 rt.log()가 본문을 업데이트할 때도 직접 적은 필드나 YAML 아래 마크다운은 안전하게 보존됩니다. 주석과 필드 순서도 그대로 유지돼요.
• ## 결론 섹션은 상세 패널의 "기록 · PR 본문"에 마크다운으로 표시돼요. rt.conclude()를 쓰면 이 섹션을 자동으로 추가하거나 업데이트해 줍니다.

경고 배지

본문에 문제가 있어도 트리는 정상적으로 그려져요. 대신 해당 노드 옆에 경고 배지가 붙습니다.

경고	원인
YAML 블록 없음	본문에 yaml 코드 블록이 없을 때
YAML 파싱 오류	문법이 올바른 YAML이 아니거나 key: value 형식이 아닐 때
가설 없음	hypothesis가 비어 있을 때
잘못된 상태 / 잘못된 필드	status 값이 정해진 세 가지가 아니거나 필드 타입이 맞지 않을 때
고아	트리에서 부모 브랜치를 찾을 수 없을 때 (루트 아래에 붙어요)
순환	부모 관계가 A → B → A 형태로 꼬였을 때 (루트 아래에 붙어요)
없는 버전	parent: research@vN에 적은 버전 태그가 없을 때 (첫 버전에 붙어요)

메트릭 키 권장

연구 초기에는 아래 키를 먼저 맞춰 쓰고, 필요할 때 팀에서 상의해 추가해 보세요.

• val_loss, train_loss
• wer, cer
• steps, gpu_hours

키를 통일해 두면 상세 패널의 메트릭 탭에서 부모 대비 증감(Δ)을 계산해 주고, 섬마다 고르는 라벨 메트릭으로 그 버전의 노드들 위에 같은 메트릭 값을 띄울 수 있어요.