|
| 1 | +# ko-tech-doc-audit |
| 2 | + |
| 3 | +## When to use |
| 4 | +한국어 기술 문서·README·PR 설명·기술 노트의 **내용 완성도**를 검증하거나 개선할 때. "다 읽고 나서 뭘 읽은 건지 모르겠다"는 느낌을 유발하는 공허한 주장, 빠진 근거, 실행 불가 문장을 잡는 것이 목적이다. |
| 5 | + |
| 6 | +Good triggers: "이 문서 검토해줘", "내용이 비어 보여", "그럴싸한데 알맹이가 없어", "AI가 쓴 것 같아서 다시 봐줘". |
| 7 | + |
| 8 | +Do not use for: 단순 맞춤법·오타(기본 절차로 충분), 코드 품질 리뷰(`review-two-axis`), 영문 문서. |
| 9 | + |
| 10 | +## Persona |
| 11 | +기본 페르소나: **한국어 기술 문서 편집자** — 읽고 나서 "그래서 뭘 읽은 거지?"라는 느낌이 들지 않게 고치는 편집자. |
| 12 | + |
| 13 | +cast 시점에 다른 페르소나를 주입할 수 있다: |
| 14 | +- `"보안 엔지니어"` → 보안 주장·위협 모델·실패 조건에 집중 |
| 15 | +- `"도메인 처음 보는 주니어 독자"` → 용어 설명·전제 명시·실행 가능성에 집중 |
| 16 | +- `"운영 온콜 엔지니어"` → 장애 재현·롤백·실패 조건에 집중 |
| 17 | + |
| 18 | +**페르소나는 검토 관점·강조점·어조만 바꾼다. 아래 합격 기준(주장-근거 연결, 7대 기준)은 페르소나와 무관하게 고정이다.** 선택된 페르소나는 `.tink/current/answers.md`에 기록한다. |
| 19 | + |
| 20 | +## Ask first |
| 21 | +- 검토 대상 문서 경로 또는 내용은 무엇인가? |
| 22 | +- 적용할 페르소나는? (미지정 시 기본값: "한국어 기술 문서 편집자") |
| 23 | +- 산출물 형태: 지적 목록만 / 지적 + 수정본 |
| 24 | +- 원문에 없는 사실을 추가해도 되는 범위 (기본값: 금지) |
| 25 | + |
| 26 | +`.tink/current/answers.md`에 이미 답한 질문은 반복하지 않는다. |
| 27 | + |
| 28 | +## Plan |
| 29 | +1. 문서의 목적과 독자를 확인한다. 없으면 그것부터 지적한다. |
| 30 | +2. 핵심 주장을 추출한다. |
| 31 | +3. 각 주장을 **근거·실행 절차·검증 방법·실패 조건 중 최소 하나와 연결**한다. 연결 안 되는 주장은 공허한 주장으로 표시한다. |
| 32 | +4. vague-phrase를 탐지한다. 근거 없이 쓰인 아래 표현들은 금지가 아니라 **근거 요구** 대상이다: "효과적입니다", "안정성을 높입니다", "확장성을 제공합니다", "유지보수가 쉬워집니다", "필요에 따라", "적절히", "일반적으로", "결론적으로", "성능이 개선", "정상적으로 동작", "효율적", "유연한 구조". |
| 33 | +5. 실행 불가능한 문장, 빠진 검증 방법, 빠진 실패 조건을 표시한다. |
| 34 | +6. 7대 기준으로 점검한다: 목적 / 독자 / 주장 / 근거 / 실행 / 검증 / 한계. 빠진 항목이 있으면 권장 섹션 위치를 안내한다. |
| 35 | +7. **마지막에만** 문체·AI 티 정리: `/patina --lang ko --tone professional`에 위임한다. Patina는 구조·주장·숫자·인과관계를 보존하고 fidelity floor 미달 시 원복하므로 감사 결과를 재포장하지 않는다. Patina 미설치 시 `/plugin install patina@patina` 안내 후 재실행을 권장한다. 그래도 없으면 번역투·과한 요약문·기계적 반복을 최소 인라인으로 정리한다. |
| 36 | + |
| 37 | +**금지**: 원문에 없는 성능 개선·보안 강화·유지보수성 향상을 사실처럼 추가하지 않는다. 코드·설정·로그·테스트 명령이 필요한 곳을 추상 설명으로 대체하지 않는다. |
| 38 | + |
| 39 | +## Checks |
| 40 | +- 모든 핵심 주장이 근거·실행·검증·실패조건 중 하나 이상에 연결됨 |
| 41 | +- 공허한 주장·실행 불가 문장·빠진 검증·빠진 실패조건이 목록으로 보고됨 |
| 42 | +- 7대 기준 점검 결과가 명시됨 |
| 43 | +- 원문에 없는 사실이 추가되지 않음 |
| 44 | +- 페르소나가 합격 기준을 약화시키지 않음 |
| 45 | + |
| 46 | +## Done means |
| 47 | +산출물(지적 모드): ① 핵심 주장 목록 ② 공허한 주장 목록 ③ 실행 불가 문장 목록 ④ 빠진 검증 방법 ⑤ 빠진 실패 조건. 수정본 모드 선택 시 ⑥ 수정본도 포함. 독자가 읽고 나서 "뭘 읽었는지"가 명확해진 상태. |
| 48 | + |
| 49 | +## If it fails, Tink back |
| 50 | +- 문서의 목적·독자가 불명확하면 그 지점에서 멈추고 사용자에게 확인한다. |
| 51 | +- 원문에 근거가 없어 주장을 검증할 수 없으면 추측으로 채우지 말고 "근거 필요"로 표시한다. |
| 52 | +- Patina 설치 전이라면 문체 정리 단계를 건너뛰고 내용 감사 결과만 보고한다. |
| 53 | + |
| 54 | +## 선택적 CI 강화 |
| 55 | +반복 자동 강제가 필요하면 아래 조합으로 구성할 수 있다. 설치 강제 아님. |
| 56 | + |
| 57 | +```yaml |
| 58 | +# .github/workflows/docs-quality.yml |
| 59 | +name: docs-quality |
| 60 | +on: |
| 61 | + pull_request: |
| 62 | + paths: ["**/*.md", "docs/**"] |
| 63 | +jobs: |
| 64 | + docs-quality: |
| 65 | + runs-on: ubuntu-latest |
| 66 | + steps: |
| 67 | + - uses: actions/checkout@v4 |
| 68 | + - name: Markdown lint |
| 69 | + run: npx markdownlint-cli2 "**/*.md" |
| 70 | + - name: Vale (공허한 주장·AI식 표현) |
| 71 | + run: vale docs README.md |
| 72 | +``` |
| 73 | +
|
| 74 | +Vale 룰 시작점 (`styles/ko-tech/VagueClaims.yml`): |
| 75 | +```yaml |
| 76 | +extends: existence |
| 77 | +level: error |
| 78 | +tokens: ["성능이 개선", "안정성이 향상", "보안이 강화", "정상적으로 동작", "효율적", "유연한 구조"] |
| 79 | +message: "추상적 주장입니다. 수치·코드 위치·로그·테스트 명령·실패 조건 중 하나를 추가하세요." |
| 80 | +``` |
0 commit comments