tech-writer

name	tech-writer
description	기술 문서를 정확하고 명확하고 실행 가능하게 작성·윤문하는 스킬. 개발 가이드·API 문서·README·테크 블로그·기술 리포트를 대상으로, 번역투·hype·모호성을 제거하고 전제조건·코드 예제·용어 일관성·구조를 보강한다.
origin	harness
workloads	["report"]

기술 문서 작성·윤문 스킬 (tech-writer)

기술 문서를 정확하고 명확하고 실행 가능하게 작성·개선하는 스킬. 개발 가이드, API 문서, README, 테크 블로그, 기술 리포트, 설계서, 업무 문서를 지원한다.

대상 장르

장르	성격	핵심 품질 축
개발 가이드·튜토리얼	절차 중심	전제조건·번호 목록·복사가능 명령·기대 출력
API 문서·레퍼런스	정밀 명세	파라미터 표·예제·에러 코드·일관 표기
README	진입점	빠른 시작·설치·배지·구조
테크 블로그	설득·설명	흐름·코드 예제·근거·과장 절제
기술 리포트·설계서	의사결정	구조·근거·트레이드오프·중립 톤
업무 문서·메일·공지	전달·요청	간결·실행항목·명확한 의도

언제 사용

• "기술 문서 작성 도와줘"·"API 문서 만들어"·"README 작성"
• "이 초안 다듬어"·"번역투 기술문서 고쳐"·"문서 명확하게 해"
• "테크 블로그 글 작성"·"기술 리포트 윤문"·"개발 가이드 개선"
• "노트를 문서로 만들어"·"이 요점을 글로"
• 기존 문서의 절·예제가 빠져 있을 때 (하이브리드 작업)

작업 모드

작성 (Write)

입력이 개요, 불릿 메모, 요점일 때. 구조와 흐름을 정하고 새 문서를 작성한다.

• 도입부에서 "무엇인가·왜 필요한가·누가 읽나"를 명확히
• 단계별 지시와 코드 예제 포함
• 각 섹션은 독립적이고 스캔 가능한 제목과 요약
• 사실 날조 금지 — 불명확하면 <!-- TODO: 확인 필요 -->로 표시

윤문 (Polish)

입력이 완성된 초안일 때. 다음을 정리한다:

• 번역투, 과장, 모호성 제거
• 코드 예제와 기대 출력 검증
• 헤딩·목록·표 구조 정비
• 용어 일관성 확인
• 단락 길이와 흐름 개선
• 실행가능성 강화

하이브리드 (Hybrid)

초안이 있으나 절과 예제가 비어 있을 때. 빠진 부분을 작성하고 전체 흐름을 다시 본다.

주요 규칙

1. 정확성 최우선 — 코드, 명령, 수치, API 시그니처는 100% 정확. 윤문 모드에서 사실 변경 금지.
2. 실행가능성 — 명령은 복사-실행 가능, 코드는 언어 태그 붙임, 위험 명령은 경고 표시.
3. 구조는 자산 — 헤딩·목록·표·코드블록 제거하지 않기. 없으면 보강.
4. 모호성 제거 — "쉽게·간단히·여러·빠르게" 같은 표현 쓰지 않기.
5. 장르·독자 유지 — 입력 장르와 독자 레벨에서 이탈하지 않기.
6. 전제조건 명시 — 필요한 소프트웨어·지식·환경을 먼저 나열.

예제

개발 가이드 (절차 중심)

## 시작하기

### 전제조건
- Node.js 18+
- npm 또는 yarn
- Git

### 1단계: 저장소 복제
$ git clone https://github.com/example/repo.git
$ cd repo

### 2단계: 의존성 설치
$ npm install

### 3단계: 환경 변수 설정
.env.example 을 .env 로 복사:
$ cp .env.example .env

### 4단계: 서버 시작
$ npm run dev

기대 출력:

Server running on http://localhost:3000

### 다음 단계
[Link to first feature guide]

API 문서 (정밀 명세)

## POST /users

사용자를 생성합니다.

### 요청

| 필드 | 타입 | 필수 | 설명 |
|------|------|------|------|
| name | string | O | 사용자 이름, 1–100자 |
| email | string | O | 이메일 주소, 유효한 형식 |
| role | string | X | "admin" 또는 "user", 기본값 "user" |

### 응답 (201 Created)

```json
{
  "id": "user_123",
  "name": "Alice",
  "email": "[e-mail]",
  "role": "user",
  "createdAt": "2026-06-01T10:30:00Z"
}

에러

상태	설명
400	요청 형식 오류 또는 이메일 중복
500	서버 오류

예제

curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice",
    "email": "[e-mail]"
  }'

## 일반 지침

- **한국어로 작성** (코드와 공식 용어는 영어 유지)
- **기술 용어는 영어와 한글 병행** (처음 사용 시): 컨테이너(container), API(application programming interface)
- **문장은 간결하고 능동태** — "~를 하면 된다" 형태 선호
- **코드 블록은 언어 태그 필수** — ` ```javascript`, ` ```bash`, ` ```sql` 등
- **주의/경고는 명확히** — "주의:", "⚠️ 위험:", "💡 팁:" 등 마크다운 포맷 사용
- **표와 목록으로 정보 정리** — 산문이 너무 길어지지 않기
- **"다음 단계" 또는 "관련 문서" 섹션 포함** — 독자가 다음 할 일을 알 수 있도록

## 최악의 기술 문서

- "이 기능을 쉽게 사용할 수 있습니다" (어떻게? 정확히 뭘 하나?)
- 전제조건 없이 명령 나열 (Node.js 설치 안 된 사용자는?)
- 코드 예제 없이 "다음과 같이 코딩합니다" (정확한 문법은?)
- 화면 스크린샷만 있고 텍스트 설명 없음 (접근성, 검색 불가)
- API 응답 구조를 설명만 하고 실제 JSON 보여 주지 않음

## 관련 스킬

- markdown-writing — 장문의 구조화된 마크다운 작성
- documentation-lookup — 공식 문서 검색
- security-review — 기술 문서의 보안 정확성 검증