Skip to content

feat(review): 리뷰 코멘트 문체 계약 신설 및 top-level 트레일러 통일#431

Merged
JeremyDev87 merged 2 commits into
masterfrom
feature/review-comment-style-contract
Jul 3, 2026
Merged

feat(review): 리뷰 코멘트 문체 계약 신설 및 top-level 트레일러 통일#431
JeremyDev87 merged 2 commits into
masterfrom
feature/review-comment-style-contract

Conversation

@JeremyDev87

Copy link
Copy Markdown
Owner

무엇을 (What)

review 코멘트 산문의 가독성 계약 2종을 추가합니다.

  • references/review-comment-style.md 신규 (양 root must-match): 독자를 "ddalggak reference를 읽지 않은 PR 저자"로 고정하고, 평문 첫 문장 / 증상→근거→제안 순서 / 1문장 1절 / 동사 종결 / 내부 용어 번역표 5규칙과 실제 난해 코멘트의 before/after 변환 예시를 수록
  • top-level comment 형식 개정: 첫 줄은 사람용 한 줄 결론, 기계 트레일러는 마지막 줄로 이동하고 templates/review-brief.md 완료 신호(head=<sha> 필드 추가) 단일 정본으로 통일

왜 (Why)

실제 게시된 리뷰 코멘트 분석에서 난해함 패턴 5종(내부 시스템 어휘 노출, 다절 복문, 명사구 종결체, 결론 후치, 첫 줄 기계 트레일러)을 확인했습니다. 원인은 스킬에 문체 계약이 없어 reference의 계약 문체가 코멘트에 그대로 상속되는 구조였습니다. 트레일러 형식 이원화는 PR #429 리뷰의 미수용 Low finding이기도 합니다.

어떻게 (How)

  • review 경로 토큰 예산 여유(claude 58 / codex 17 tokens)가 없어 본문 배선 대신 exemption(cap 700) + finding signal gate pointer 경유 on-demand 로드로 설계 (PR #430의 knowledge-freshness-contract 전례)
  • parity ledger에 must-match 등록, 커밋 2개 직렬(계약 신설 / 트레일러 통일)
  • 트레일러 템플릿 문자열을 cross-review-loop.md에서 제거하고 review-brief.md 참조로 대체해 형식 정본을 하나로 축소

검증 (Validation)

  • project-runtime-assets --report --admission pass (over-budget 0, 신규 reference 실측 cap 700 이내)
  • npm test smoke 70/70 · ddalggak doctor 0 findings · verify:projections pass (57 parity ledger entries) · verify:codex-skill pass · eval:ddalggak-readiness 29/29
  • 구 트레일러 형식(verdict=) 잔존 0건, REVIEW_DONE PR# 템플릿은 review-brief.md 미러 2곳에만 존재

제외 범위 (Out of scope)

  • start/check 경로 문체 적용, 수용률 추적 루프, 기존 reference 43개 문체 개정 (후속 후보)
  • core/commands/review.yaml·SKILL.md 색인: 트레일러 위치가 등장하지 않아 무수정

JeremyDev87 and others added 2 commits July 4, 2026 00:13
리뷰 코멘트가 스킬 내부 어휘·다절 복문·결론 후치로 난해하다는
실증(리뷰 코멘트 원문 분석)에 따라, 독자를 "reference를 읽지 않은
PR 저자"로 고정하는 문체 계약 reference를 추가한다. review 예산
여유(17 tokens)가 없어 exemption(cap 700) + finding signal gate
pointer 경유 on-demand 로드로 배선하고, parity ledger에 must-match
등록했다.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Ultraworked-With: claude-fable-5
User-Request: 리뷰 코멘트가 난해해서 잘 안 읽히는 부분을 개선
top-level comment의 첫 줄이 기계 트레일러라 가독성을 해치고,
트레일러 형식이 완료 신호 정본과 달라 파싱 표면이 둘이었다
(PR #429 리뷰 Low finding). 사람용 한 줄 결론을 첫 줄로 올리고,
트레일러는 review-brief.md 완료 신호(head=<sha> 필드 추가) 단일
정본을 마지막 줄에서 참조하게 통일했다.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Ultraworked-With: claude-fable-5
User-Request: 리뷰 코멘트가 난해해서 잘 안 읽히는 부분을 개선
@JeremyDev87

Copy link
Copy Markdown
Owner Author

이 변경은 그대로 머지해도 안전합니다. 머지를 막을 문제를 찾지 못했습니다.

검토 범위: 8개 파일 — 리뷰 코멘트 문체 계약 신설, top-level 첫 줄을 사람용 결론으로 변경, 기계 요약 줄을 마지막으로 이동해 한 가지 형식으로 통일.

검증 (리뷰어가 직접 실행):

  • 토큰 예산 검사 통과 (초과 0건, 가장 빠듯한 항목 28,494/28,500)
  • 스모크 테스트 70/70 통과, 자가 진단 0건, 계약·미러 정합 검사 전부 통과
  • 옛 요약 형식(verdict=)은 저장소에 남아 있지 않음을 grep으로 확인
비차단 메모 · CI/승인 경계
  • 메모 1: 새 문체 규칙은 "내부 용어를 본문에 쓰지 않는다"인데, 접이식 상세 블록의 고정 4항목은 여전히 절차 용어를 씁니다. 두 규칙이 충돌로 읽힐 수 있으니, 후속에서 "접이식 상세는 예외"를 한 구절 명시하면 모호함이 사라집니다.
  • 메모 2: 가장 빠듯한 문서 묶음의 예산 여유가 6 tokens입니다. 다음에 이 문서를 조금만 늘려도 검사가 실패하므로, 다음 수정자는 압축이나 예산 조정을 함께 계획해야 합니다.
  • CI: 이 커밋 기준 8/8 통과 (CodeQL, Dependency Review, Node 18/20/22/24 패키지 검증, Budget isolation, Analyze JavaScript).
  • 공식 승인 경계: 저자 자신의 리뷰라서 GitHub 공식 승인은 하지 않습니다. 이 코멘트가 리뷰 결론입니다.
  • 머지를 막는 문제: 없음. 머지는 자동으로 하지 않습니다.
  • 사람이 할 일: draft 해제와 머지는 주인님 판단입니다.

REVIEW_DONE PR#431: APPROVE critical=0 high=0 medium=0 low=0 head=e85472b5b27b441e76f5ae321decf5ff54e9637b

@JeremyDev87 JeremyDev87 self-assigned this Jul 3, 2026
@JeremyDev87 JeremyDev87 added the feat New feature or enhancement label Jul 3, 2026
@JeremyDev87 JeremyDev87 marked this pull request as ready for review July 3, 2026 15:47
@JeremyDev87 JeremyDev87 merged commit f9090ad into master Jul 3, 2026
8 checks passed
@JeremyDev87 JeremyDev87 deleted the feature/review-comment-style-contract branch July 3, 2026 15:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

feat New feature or enhancement

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant