review

name	review
description	기술 블로그 글의 가독성과 품질을 리뷰한다. 글 피드백 요청, 리뷰 요청, 가독성 점검 요청 시 사용한다. '이 글 피드백해줘', '리뷰해줘', '낯선 사람이 읽으면 어떨까' 등의 요청에도 반응한다.

/review - 기술 블로그 글 리뷰

Triggers

• 블로그 포스트의 가독성/품질 피드백 요청 시
• "이 글 피드백해줘", "리뷰해줘", "읽기 쉬운지 봐줘" 등
• /review 호출 시

Arguments

$ARGUMENTS — 대상 문서 경로 (생략 시 대상 지정 요청)

---

독자 가정

디폴트 독자는 소프트웨어 개발자이지만, 글에서 다루는 도메인(결제, 인프라, DB 등)은 잘 모르는 사람이다. 사용자가 별도로 독자 수준을 지정하면 그에 맞춘다.

---

평가 기준

문제가 없는 기준은 출력에서 생략한다. 문제가 있는 기준만 보고한다. 잘된 점은 언급하지 않는다. 개선이 필요한 부분만 집중한다.

1. 문제 정의 (Problem Statement)

글의 도입부에서 "무엇이 문제인지"가 명확하게 전달되는가.

• 배경 설명 없이 갑자기 해결책부터 시작하지 않는가
• 도메인을 모르는 개발자도 "아, 이런 상황이 있구나"를 파악할 수 있는가
• 문제의 규모/영향이 와닿는가 (왜 이걸 해결해야 하는지)
• 이전 글에 의존하는 전제가 있다면, 이 글만으로도 최소한의 맥락이 전달되는가
• 글의 범위(다루는 것 / 다루지 않는 것)가 도입부에 명시되어 있는가

2. 용어와 개념 (Terminology)

전문 용어나 도메인 특화 개념이 독자에게 전달 가능한 형태인가.

• 설명 없이 갑자기 등장하는 용어가 있는가
• 약어가 풀네임 없이 사용되는가
• 글 안에서만 통용되는 자체 정의 용어가 충분히 설명되는가
• 같은 개념을 다른 단어로 지칭해 혼란을 주지 않는가
• 핵심 메커니즘(패턴, 기법 등)이 이름만 언급되고 동작 원리가 빠져 있지 않은가

3. 논리 흐름 (Logical Flow)

문제 → 분석 → 설계 → 결과 순서가 자연스럽게 이어지는가.

• 섹션 간 비약이 있는가 (앞 내용과 연결 고리 없이 다음 주제로 넘어감)
• 결론이 앞에서 제기한 문제에 대한 답이 되는가
• 독자가 "왜 갑자기 이 얘기?"라고 느낄 수 있는 전환 지점이 있는가
• 문제와 해결책이 명시적으로 대응되는가 (N개의 문제를 제기했으면 N개의 해결이 매핑되는가)

4. 근거와 설득력 (Justification)

설계 결정이나 기술 선택에 대해 "왜?"가 설명되는가.

• "이렇게 했다"만 있고 "왜 이렇게 했는지"가 빠진 부분이 있는가
• 대안을 고려한 흔적이 있는가 (A 대신 B를 선택한 이유)
• 트레이드오프가 명시되어 있는가
• 수치나 설정값(타임아웃, 재시도 횟수 등)에 근거가 있는가

5. 구체성 (Concreteness)

추상적 서술 없이 독자가 머릿속에 그림을 그릴 수 있는가.

• "적절히 처리한다", "효율적으로 관리한다" 같은 모호한 표현이 있는가
• 코드, 다이어그램, 예시 시나리오 등으로 뒷받침되는가
• 관련 개념들의 구체성 수준이 균형 잡혀 있는가 (한쪽은 코드까지, 한쪽은 표만 있는 불균형)
• 복잡한 플로우가 텍스트만으로 설명되어 시각 자료가 필요한 곳이 있는가
• 큰 다이어그램은 주요 분기를 텍스트로 요약하고 있는가

6. 독자 부담 (Cognitive Load)

한 번에 소화해야 하는 정보량이 적절한가.

• 설명 없이 한꺼번에 많은 개념을 쏟아내는 곳이 있는가
• 문장이 지나치게 길거나 중첩 구조가 깊어 한 번에 파악하기 어려운가
• 코드 블록이 너무 길어 핵심이 묻히는가
• 시나리오나 엣지 케이스가 나열될 때, 각각의 핵심 포인트가 미리 요약되어 있는가

7. 완결성 (Completeness)

읽고 나서 "그래서?"라는 질문이 남지 않는가.

• 제기한 문제에 대한 결론이 있는가
• 한계점이나 남은 과제가 언급되는가
• 같은 의미의 제목이 반복되지 않는가 (예: "그 외"가 두 번 등장)

8. 기계적 문체 (AI체)

문법은 맞지만 사람이 쓴 글처럼 읽히지 않는 평면적 문체가 있는가.

• 도입부가 주제의 중요성만 추상적으로 부풀리는가 ("~를 좌우한다", "핵심은 ~에 있다", "가장 ~한 순간")
• 알맹이 없는 강조어로 문장을 채우는가 ("결정적인 역할", "반드시 이해해야 한다")
• 상투적 비유에 기대는가 ("양날의 검", "진가를 발휘한다", "빙산의 일각")
• 섹션 끝에 바로 위 내용을 되풀이하는 군더더기 요약 문장이 붙는가
• 모든 리스트 항목이 똑같은 구문("X하여 Y하고 Z한다")으로 맞춰져 합성된 느낌을 주는가

---

Process

Step 1. Read — 전체 읽기

대상 문서 전체를 읽는다. 첫 인상으로 "어디서 막히는지", "어디서 왜?라는 의문이 드는지"를 기록한다.

Step 2. Review — 기준별 평가

8가지 기준 각각에 대해 문제점을 찾는다. 각 문제점에는 반드시 해당 위치(섹션명 또는 원문 인용)를 포함한다.

Step 3. Report — 결과 보고

아래 Output Format에 따라 출력한다. "~하면 좋겠다" 식의 제안이 아니라, "~가 빠져 있다", "~가 불명확하다" 식으로 문제를 지적한다.

---

Output Format

## [문서명] Review

### [기준명]

- [문제점]: 구체적 위치(섹션명 또는 인용)와 함께 무엇이 문제인지 서술
- [문제점]: ...

### [기준명]

- [문제점]: ...

---

총평: 가장 시급하게 개선이 필요한 1-2가지를 한 문장으로 요약