| name | write-korean-technical |
| description | 정확하고 재현 가능한 한국어 기술 문서를 작성하는 스킬. 개발자 가이드, 설치 문서, 튜토리얼, API 설명, 아키텍처 문서, ADR, 운영 런북, 장애 대응 절차, 트러블슈팅 가이드, 변경·마이그레이션 문서를 새로 작성하거나 코드와 로그에서 정리할 때 사용한다. "README 기술 문서를 써 줘", "이 설정을 재현 가능한 가이드로 만들어 줘", "장애 대응 절차를 문서화해 줘", "API 사용법을 한국어로 정리해 줘" 같은 요청에도 사용한다. 환경, 버전, 전제 조건, 명령, 예상 결과, 실패 분기와 검증 증거를 분명히 하고 코드 식별자를 보존한다. |
Write Korean Technical
기술 문서를 독자와 완료 상태 정의 → 실제 환경 확인 → 절차·개념 구조화 → 검증 → 문체 검사 순서로 작성하라.
1. 독자와 재현 조건 정하기
- 독자의 기술 수준과 역할
- 수행할 작업 또는 이해할 개념
- 운영체제, 런타임, 버전과 전제 조건
- 입력, 출력과 완료 상태
- 실패 시 롤백(되돌리기) 또는 진단 방법
- 실제로 검증할 수 있는 범위
저장소나 실행 환경이 제공되면 먼저 실제 파일, 명령, 버전과 현재 경로를 확인하라. 소스 기본값과 실행 중인 설정을 혼동하지 마라.
2. 기술적 사실 보존하기
- 함수명, API 경로, 옵션, 환경 변수, 파일명과 오류 문구를 임의로 바꾸지 마라.
- 실행하지 않은 명령과 확인하지 않은 결과를 성공했다고 쓰지 마라.
- 버전이 변할 수 있는 정보는 현재 환경이나 공식 문서로 확인하라.
- 확인한 사실, 합리적 추론, 미검증 가정을 구분하라.
- 비밀값과 실제 자격 증명을 예시에 넣지 마라.
문서 유형은 references/formats.md에서 선택하라.
3. 독자가 확인할 수 있게 작성하기
절차 문서에는 각 단계의 행동과 확인 방법을 함께 둔다.
행동 → 예상 결과 → 실패하면 확인할 항목
개념 문서는 기능, 이름, 작동 방식, 제약, 예시 순으로 설명하라. 전문용어를 동의어로 계속 바꾸지 말고 처음 등장할 때 정의한 뒤 일관되게 사용하라.
파일 결과물이 필요하면 assets/technical-document-template.md를 필요한 절만 남겨 사용하라. 완료 전 references/quality-gate.md를 적용하라.
4. 문체와 구조 검사하기
CORE_SKILL_DIR은 이 스킬과 같은 상위 폴더의 natural-korean 디렉터리로 해석하라.
uv run "$CORE_SKILL_DIR/scripts/lint.py" path/to/document.md --genre tech
uv run "$CORE_SKILL_DIR/scripts/outline.py" path/to/document.md
uv run "$CORE_SKILL_DIR/scripts/terms.py" path/to/document.md
코드, 로그, 명령과 식별자는 문체 수정 대상에서 제외하라. 공통 검사 스킬이 없으면 quality gate를 수동으로 적용하고 검사 미실행 사실을 밝혀라.
5. 최종 전달하기
완성 문서와 함께 실제로 검증한 명령·환경·결과의 범위를 짧게 적어라. 실행하지 못한 단계는 미검증으로 표시하라. 독자가 실행해야 할 문서에 내부 추론이나 임시 로그를 남기지 마라.
