---
name: docs-ux-review
description: Use when creating, editing, or reviewing README files, plugin documentation, setup guides, troubleshooting docs, developer onboarding docs, or any user-facing technical document where first-screen value, no-context reader review, concrete visual/output examples, section-level reader questions, unfamiliar terminology, official-doc links, requirements, warnings, or Korean document UX matter. 특히 README UX, 컨텍스트 없는 사용자 관점 점검, 출력 예시, 요구사항/주의사항 분리, 낯선 용어 첫 등장, official docs 링크, technical-writer 결과 검수에 사용.
---

# Docs UX Review

README, 플러그인 문서, 설치 가이드, 개발자 온보딩 문서를 쓸 때 정보 구조와 첫 화면 UX를 점검한다. `technical-writer` 같은 작성자 역할과 별개로, 이 스킬은 문서가 사용자의 판단을 빠르게 돕는지 검수하는 체크리스트다.

## 적용 시점

- README나 사용자-facing 기술 문서를 새로 쓰거나 고칠 때
- 설치/업데이트/요구사항/주의사항/트러블슈팅 섹션을 손볼 때
- 플러그인, CLI, hook, SDK, API 문서처럼 사용자가 실행 결과를 보고 가치를 판단해야 할 때
- `technical-writer` subagent 결과를 검수하거나, subagent에게 문서 작업을 맡기기 전에 기준을 넘길 때

## 먼저 볼 것

문서 상단부에서 사용자가 1분 안에 판단할 수 있어야 한다.

- 이 문서가 다루는 대상과 용도가 첫 화면에 보이는가
- 실제 output, UI, CLI 결과, API response, 에러/경고 예시, 그림, 스크린샷 중 하나가 가치 판단에 도움이 되는 위치에 있는가
- output 예시에는 stdout, stderr, terminal, UI, log, JSON response처럼 사용자가 실제로 보게 되는 위치가 같이 적혀 있는가
- 설치 전에 알아야 할 위험, 권한, 런타임 제약, 운영 영향이 숨겨져 있지 않은가
- “무엇을 하는가”보다 내부 구현 설명이 먼저 나오지 않는가
- 목차가 있다면 소개와 가치 문단 뒤, 출력 예시를 포함한 상세 섹션 앞에 있는가

## 무맥락 사용자 관점

문서를 쓴 사람의 이전 대화, 세션 히스토리, 코드베이스 배경을 모르는 사용자가 처음부터 읽는다고 가정한다.

- 첫 문단만 보고도 “이 문서는 무엇이고, 왜 필요한가, 언제 쓰는가”를 알 수 있는가
- 저장소 안에서만 통하는 이름, 플러그인 이름, 파일명, 정책 이름이 설명 없이 먼저 나오지 않는가
- `guardrail`, `hook`, `MCP`, `staged diff`, `additionalContext`처럼 이 repo나 특정 런타임에 묶인 용어는 첫 등장 때 사용자에게 보이는 효과와 함께 설명했는가
- “보호”, “차단”, “경고”, “검사”, “허용” 같은 동사가 읽기 차단, 쓰기 차단, 실행 차단, 경고 추가 중 무엇인지 분명한가
- output 예시가 실제로 어디에 보이는지 알 수 있는가: terminal stderr, hook stdout JSON, UI, log, 다음 모델 컨텍스트 중 하나로 라벨링한다
- 기본값 파일, 패키지 내부 파일, 개인 수정 파일, 업데이트로 덮어써지는 파일을 구분했는가
- “기본으로 동작한다”와 “개인 설정에 추가해야 동작한다”를 섞어 쓰지 않았는가
- 구현 파일이나 설정 파일을 언급했다면 현재 코드와 실제 파일 내용을 확인했는가

## 정보 구조

- 요구사항에는 환경 조건만 둔다. 요구사항을 만족하지 못했을 때의 동작은 별도 섹션으로 분리한다.
- 역할/출력 예시/설치/설정/동작 방식/문제 해결을 섞지 않는다.
- 목차는 소개 문단 뒤에 두고, 출력 예시는 목차 뒤 첫 본문 섹션으로 둔다. 출력 예시를 상단부에 둔다는 말은 목차보다 앞에 둔다는 뜻이 아니다.
- 사용자가 보는 출력과 내부 구현 설명을 분리한다.
- 설치 명령, 설정 경로, 업데이트 방법은 런타임별 차이가 있을 때만 나눠 쓴다.
- 지원 런타임이나 제품 이름은 필요한 곳에만 쓴다. 소개 문구에서 반복해 지원 범위를 좁혀 보이게 하지 않는다.
- 주의사항은 “무엇이 달라지는지”와 “사용자가 무엇을 해야 하는지”가 같이 보여야 한다.
- 각 섹션은 사용자가 바로 다음에 궁금해할 질문을 하나 이상 막아야 한다.
- 기본 파일과 사용자가 수정할 파일을 분리한다. 업데이트로 덮어써지는 파일과 유지되는 개인 파일을 구분한다.
- 특정 제품의 설정, 권한, hook, 플러그인 런타임, API 동작을 설명하면 공식 문서나 관련 이슈를 링크한다.

## 섹션별 후속 질문

섹션을 쓴 뒤 사용자 입장에서 바로 이어질 질문을 점검한다.

- 출력 예시: 이 출력은 어디에 보이는가? stdout, stderr, terminal, UI, log, JSON response 중 무엇인가?
- 요구사항: 조건을 만족하지 못하면 차단, 경고, 무시, fallback, fail-open, fail-closed 중 무엇이 되는가?
- 설정 파일: 기본값 파일과 개인 수정 파일 중 사용자는 어디를 고쳐야 하는가?
- 업데이트/제거: 어떤 파일은 덮어써지고, 어떤 개인 파일이나 상태는 남는가?
- 위험/주의사항: 사용자가 지금 해야 할 행동은 무엇인가?

## 예시 정책

- CLI/hook/API 문서에는 실제 출력 예시를 상단부에 둔다.
- 예시는 실제 명령 또는 테스트 가능한 훅/함수 출력과 맞춘다.
- 위험한 명령 예시는 실행하지 말고, stdin payload나 fixture처럼 안전한 방식으로 검증한다.
- 예시가 축약본이면 `...`로 축약 사실을 드러낸다.
- 코드 블록의 언어 태그를 맞춘다: `bash`, `json`, `text`, `kotlin` 등.
- output이 핵심이 아니면 스크린샷, 그림, before/after, 파일 구조 중 하나로 첫 화면 이해를 돕는다.

## 용어와 외부 근거

- 저장소 안에서만 통하는 이름은 첫 등장 시 역할을 짧게 붙인다.
- 특정 도구의 개념이나 설정 이름은 사용자가 이미 안다고 가정하지 않는다.
- `PreToolUse`, `PostToolUse`, `mcp__*`, 환경 변수처럼 런타임별 용어는 사용자가 보는 효과와 함께 설명한다.
- 공식 설정, 권한, API, CLI 동작을 말하면 가능한 경우 공식 문서, 릴리스 노트, 관련 이슈를 링크한다.
- 오래된 이슈나 이미 수정된 이슈는 금지 조항처럼 쓰지 않는다. 현재도 적용되는 제약인지 배경 설명인지 구분한다.

## 동작 유형

도구가 무엇을 실제로 바꾸는지 정확히 구분한다.

- 차단형: 무엇이 실행되지 않는지와 사용자에게 보이는 오류를 적는다.
- 경고형: 원래 결과가 유지되는지와 경고가 어디에 추가되는지 적는다.
- 관찰형: 상태를 바꾸지 않는다는 점을 명시한다.

## README 체크리스트

- 첫 화면에 역할과 가치가 보인다.
- 플러그인/도구 목록은 사용자가 선택해야 하면 요구사항보다 먼저 둔다.
- 목차가 출력 예시나 용어 설명 같은 본문 섹션보다 먼저 나온다.
- output 예시가 추상 설명보다 먼저 또는 같은 수준에 있다.
- 문서를 처음 읽는 사용자가 앞선 대화나 repo 히스토리를 몰라도 핵심 용어와 기본값을 따라갈 수 있다.
- 요구사항과 fallback/실패 동작이 분리되어 있다.
- 섹션별로 사용자의 다음 질문을 예상하고 짧게 답한다.
- 낯선 용어와 저장소 한정 용어가 설명 없이 갑자기 나오지 않는다.
- 특정 툴 설정이나 권한 설명에는 공식 문서나 관련 이슈가 연결되어 있다.
- 개인 설정 파일, 캐시, 새 세션 필요 여부처럼 자주 걸리는 운영 함정이 빠지지 않았다.
- 사용자가 직접 고칠 수 있는 파일 경로와 업데이트로 덮어써지는 파일 경로가 구분되어 있다.
- 제거/업데이트 뒤 남는 개인 파일이나 상태가 있으면 명시되어 있다.

## 문체 체크

- “주입”, “통과시킵니다”, “~용”처럼 직역이나 제품 편향으로 읽히는 표현을 피한다.
- `Claude Code와 Codex에서` 같은 런타임 나열은 설치 명령, 경로 표, 요구사항처럼 필요한 곳에만 쓴다.
- 영어식 안내 제목, 콜론형 헤딩, rhetorical 헤딩은 피한다.
- 긴 한국어 산출물은 마지막에 `korean-tone-review`도 적용한다.

## technical-writer와 같이 쓸 때

`technical-writer`는 문서 작성자 역할이다. README나 개발자 문서 작업을 맡길 때는 다음 기준을 함께 넘긴다.

```text
README/docs UX 기준도 적용하세요:
- 첫 화면에서 가치와 실제 출력 예시가 보이게 하세요.
- 이전 대화나 코드베이스 맥락이 없는 사용자가 처음부터 읽는다고 가정하고, 낯선 이름·기본값·출력 위치를 설명하세요.
- 섹션마다 사용자가 다음에 궁금해할 질문을 예상해 짧게 답하세요.
- 요구사항과 요구사항 미충족 시 동작을 분리하세요.
- 낯선 용어는 첫 등장 시 역할을 설명하고, 특정 툴 설정은 공식 문서나 관련 이슈를 링크하세요.
- 런타임/제품 이름은 필요한 섹션에만 쓰고 소개 문구에 반복하지 마세요.
- 사용자가 보는 출력과 내부 구현 설명을 분리하세요.
- 실제 출력 예시는 가능한 한 로컬 검증 결과와 맞추세요.
```