원문: https://github.com/facebook/astryx/wiki/Blog-Review-Rubric · 번역 기준: 2026-09-03
Astryx 문서 사이트 블로그 포스트(apps/docsite/src/content/blog/posts/<slug>.md)를 리뷰하는 방법입니다. 블로그 포스트는 사람이 직접 쓴 산문입니다(blog 폴더 README 참조); 이 rubric은 그 기준을 지킵니다. 이것은 **권고적(advisory)**입니다 — 리뷰는 scorecard와, 구체적인 수정안이 딸린 인용 가능한 발견 사항을 산출합니다. 머지를 자동으로 막지 않으며, 저자의 목소리(voice)를 다시 쓰지 않습니다.
같은 rubric이 세 개의 표면을 뒷받침하여 포스트가 어디서나 같은 기준으로 읽히게 합니다: 이 페이지(canonical), 블로그 포스트 PR에 자동 적용되는 .github/instructions/blog.instructions.md의 Copilot 리뷰어, 그리고 로컬/인터랙티브 점검용 blog-review 리뷰어 skill입니다.
"AI인가 사람인가"를 탐지하지 마세요. LLM은 저자 판별에 신뢰할 수 없고, "AI가 쓴 느낌"은 검증 가능하지도 실행 가능하지도 않습니다. 관찰 가능한 글쓰기 품질 — 일반적이고, 노력이 부족하고, 근거가 없고, 반복적이고, voice에서 벗어난 — 을 판단하고, 저자에게 고칠 수 있는 구체적인 것을 주세요. 사람 대 AI 판정을 절대 출력하지 마세요.
type을 읽으세요판단하기 전에 처음부터 끝까지 읽으세요. 그 다음 frontmatter의 type을 읽으세요 — 그것이 기준을 정합니다. changelog digest와 철학 에세이는 완전히 다른 방식으로 좋은 글입니다; 하나를 다른 것의 기준으로 판단하지 마세요. 포스트를 프로필에 맞추세요:
type |
프로필 | "좋은 글"의 모습 | 감점하면 안 되는 것 |
|---|---|---|---|
update |
Changelog digest | 훑어보기 좋음; 정확한 명령어/버전 목록; 각 변경이 사용자에게 미치는 효과와 함께 한 번씩 서술됨. 간결함이 장점. | 내러티브, 스토리, 깊은 기술적 여정이 없는 것. |
engineering |
기술 심층 분석 | 구체성: 실제 수치, 명명된 시스템, 코드, 그리고 여정(무엇을 시도했고, 무엇이 깨졌고, trade-off는 무엇이었는지). | 길이가 디테일을 담고 있다면 긴 것. |
design |
디자인 근거 | 명확한 추론, 결정 뒤의 이유, trade-off, 원칙 → 적용. | engineering 포스트보다 확실한 수치가 적은 것. |
guide |
How-to | 독자가 따라 해서 성공할 수 있는 정확하고 완전하며 실행 가능한 단계. | 내러티브가 아니라 설명적/건조한 것. |
perspective / story |
의견 / 내러티브 | 진짜 관점, 진정성 있는 구체성, 커뮤니티 지향의 따뜻함. 개인적이고 느슨해도 괜찮음. | 벤치마크, 코드, 명령어 표가 없는 것. |
type과 내용이 어긋난다면(실제로는 철학 글인데 engineering으로 태그된 포스트), 이를 지적하세요 — 태그나 내용 중 하나가 바뀌어야 합니다.
여러분 자신의 말로 (a) 이 포스트가 왜 존재하는지 — 독자를 위해 하는 일 — 와 (b) 3–5개의 핵심 takeaway를 적으세요. 둘 다 제목이 아니라 내용에서 도출하세요. 이것이 채점의 근거(ground truth)가 됩니다. "왜 존재하는가?"에 답하지 못하는 포스트는 리뷰어가 드러낼 수 있는 가장 깊은 문제를 갖고 있습니다("감사합니다" 이상의 요점이 없는 감사/홍보성 포스트가 전형적인 사례입니다).
모든 감점에 대해 구체적인 줄/인용을 제시하세요. 두 가지가 점수를 type에 따라 갈라지게 합니다: 등급의 상한을 정할 수 있는 accuracy gate와 type별 카테고리 가중치입니다.
블로그 포스트는 세상에 공개됩니다; 잘못된 명령어나 지어낸 API는 실제 독자를 오도하므로, 정확성은 있으면 좋은 것이 아니라 바닥(floor)입니다. 리뷰어는 점검 가능한 주장을 현재 브랜치와 대조하여 검증합니다(CLI/소스를 grep) — 리뷰어가 가장 강한 영역입니다.
이 gate가 "산문은 깔끔한데 명령어는 깨짐"이 좋은 점수를 받을 수 없는 이유입니다: 먼저 사실을 고치고, 그 다음에 글을 평가합니다.