Technical Writer — 기술 문서 작성 파이프라인
구조설계→집필→다이어그램→리뷰→버전관리를 에이전트 팀이 협업하여 한 번에 생성한다.
실행 모드
에이전트 팀 — 5명이 SendMessage로 직접 통신하며 교차 검증한다.
에이전트 구성
| 에이전트 |
파일 |
역할 |
타입 |
| info-architect |
.claude/agents/info-architect.md |
구조 설계, 독자 분석, 목차 |
general-purpose |
| doc-writer |
.claude/agents/doc-writer.md |
본문 작성, 코드 예제, 튜토리얼 |
general-purpose |
| diagram-maker |
.claude/agents/diagram-maker.md |
Mermaid 다이어그램, 시각 자료 |
general-purpose |
| tech-reviewer |
.claude/agents/tech-reviewer.md |
정확성, 완전성, 일관성 검증 |
general-purpose |
| version-controller |
.claude/agents/version-controller.md |
메타데이터, 변경 이력, 배포 |
general-purpose |
워크플로우
Phase 1: 준비 (오케스트레이터 직접 수행)
- 사용자 입력에서 추출한다:
- 문서 주제: 무엇에 대한 문서인가
- 문서 유형 (선택): API/튜토리얼/가이드/아키텍처/운영
- 대상 독자 (선택): 역할, 기술 수준
- 참조 자료 (선택): 소스 코드, 기존 문서, 스펙
- 기존 파일 (선택): 기존 문서 초안, 구조안
_workspace/ 디렉토리를 프로젝트 루트에 생성한다
- 입력을 정리하여
_workspace/00_input.md에 저장한다
- 기존 파일이 있으면
_workspace/에 복사하고 해당 Phase를 건너뛴다
- 요청 범위에 따라 실행 모드를 결정한다
Phase 2: 팀 구성 및 실행
| 순서 |
작업 |
담당 |
의존 |
산출물 |
| 1 |
구조 설계 |
architect |
없음 |
_workspace/01_doc_structure.md |
| 2a |
본문 집필 |
writer |
작업 1 |
_workspace/02_doc_draft.md |
| 2b |
다이어그램 작성 |
diagram |
작업 1 |
_workspace/03_diagrams.md |
| 3 |
기술 리뷰 |
reviewer |
작업 2a, 2b |
_workspace/04_review_report.md |
| 4 |
버전 관리 |
version |
작업 1~3 |
_workspace/05_version_meta.md |
작업 2a(본문)와 2b(다이어그램)는 병렬 실행한다. 둘 다 작업 1(구조)에만 의존하므로 동시에 시작할 수 있다.
팀원 간 소통 흐름:
- architect 완료 → writer에게 목차·콘텐츠 전략, diagram에게 다이어그램 요건, version에게 메타데이터 전달
- writer ↔ diagram: 삽입 위치, 캡션 조율
- reviewer는 본문+다이어그램을 교차 검증. 🔴 필수 수정 발견 시 해당 에이전트에게 수정 요청 → 재작업 → 재검증 (최대 2회)
- version은 리뷰 결과를 반영하여 최종 메타데이터 확정
Phase 3: 통합 및 최종 산출물
_workspace/ 내 모든 파일을 확인한다
- 리뷰 보고서의 🔴 필수 수정이 모두 반영되었는지 확인한다
- 최종 요약을 사용자에게 보고한다:
- 문서 구조 —
01_doc_structure.md
- 문서 본문 —
02_doc_draft.md
- 다이어그램 —
03_diagrams.md
- 리뷰 보고서 —
04_review_report.md
- 버전 메타 —
05_version_meta.md
작업 규모별 모드
| 사용자 요청 패턴 |
실행 모드 |
투입 에이전트 |
| "기술 문서 전체 작성" |
풀 파이프라인 |
5명 전원 |
| "문서 구조만 잡아줘" |
설계 모드 |
architect + reviewer |
| "이 내용으로 문서 써줘" (구조 있음) |
집필 모드 |
writer + diagram + reviewer |
| "이 문서에 다이어그램 추가" |
다이어그램 모드 |
diagram + reviewer |
| "이 문서 리뷰해줘" |
리뷰 모드 |
reviewer 단독 |
| "이 문서 업데이트해줘" (기존 버전) |
업데이트 모드 |
writer + reviewer + version |
기존 파일 활용: 기존 문서, 코드, 스펙을 제공하면 해당 단계를 건너뛰거나 기존 자료 기반으로 작업한다.
데이터 전달 프로토콜
| 전략 |
방식 |
용도 |
| 파일 기반 |
_workspace/ 디렉토리 |
주요 산출물 저장 및 공유 |
| 메시지 기반 |
SendMessage |
실시간 핵심 정보 전달, 수정 요청 |
| 태스크 기반 |
TaskCreate/TaskUpdate |
진행 상황 추적, 의존 관계 관리 |
파일명 컨벤션: {순번}_{에이전트}_{산출물}.{확장자}
에러 핸들링
| 에러 유형 |
전략 |
| 문서 주제/범위 불명확 |
독자·목적 후보 제시, 선택 유도 |
| 기술 세부사항 부족 |
[확인 필요] 태그 삽입, 리뷰 시 검증 |
| 코드 예제 검증 불가 |
"검증 필요" 표시, 독자에게 테스트 권고 |
| 에이전트 실패 |
1회 재시도 → 실패 시 해당 산출물 없이 진행, 리뷰 보고서에 누락 명시 |
| 리뷰에서 🔴 발견 |
해당 에이전트에 수정 요청 → 재작업 → 재검증 (최대 2회) |
테스트 시나리오
정상 흐름
프롬프트: "우리 팀의 결제 API를 문서화해줘. 대상은 외부 개발자이고, REST API 5개 엔드포인트가 있어."
기대 결과:
- 구조: API 레퍼런스 유형, 외부 개발자 대상 독자 분석, 엔드포인트별 섹션 설계
- 본문: 인증, 엔드포인트 5개 상세, 에러 코드, 예제 코드
- 다이어그램: 인증 플로우 시퀀스, 결제 프로세스 플로차트
- 리뷰: 기술 정확성·완전성 검증
- 버전: v1.0.0, Published 상태
기존 파일 활용 흐름
프롬프트: "이 문서 구조는 잡혀 있는데, 본문을 작성해줘" + 구조 파일 첨부
기대 결과:
- 집필 모드: writer + diagram + reviewer 투입
- architect는 건너뜀, 기존 구조 기반 작업
에러 흐름
프롬프트: "기술 문서 써줘, 주제는 대충 우리 시스템 전반"
기대 결과:
- 범위 과대 → architect가 문서 분리 제안 (아키텍처 개요, API, 운영 가이드 등)
- 독자 불명확 → 내부 개발자/외부 개발자/운영팀 후보 제시
- 우선순위 문서부터 작업
에이전트별 확장 스킬
각 에이전트의 전문성을 강화하는 도메인 특화 스킬:
| 확장 스킬 |
경로 |
대상 에이전트 |
역할 |
| diagram-patterns |
.claude/skills/diagram-patterns/skill.md |
diagram-maker |
Mermaid 다이어그램 패턴 라이브러리 (아키텍처, 시퀀스, 플로차트, ER, 상태 다이어그램) |
| api-doc-standards |
.claude/skills/api-doc-standards/skill.md |
doc-writer |
REST API 문서 작성 표준 (엔드포인트 템플릿, 에러 코드, 페이지네이션, 인증) |
| code-example-patterns |
.claude/skills/code-example-patterns/skill.md |
doc-writer |
코드 예제 패턴 (5단계 구조, 언어별 스타일, 튜토리얼 구성) |
1---2name: technical-writer-23description: 기술 문서를 에이전트 팀이 협업하여 전문적으로 작성하는 파이프라인. '기술 문서 작성해줘', 'API 문서', '아키텍처 문서', '사용자 가이드', '개발자 문서', 'README 작성', '튜토리얼 만들어줘', '운영 매뉴얼', '기술 블로그', '문서화', 'documentation', '기술 명세서' 등 기술 문서 작성 전반에 이 스킬을 사용한다. 기존 코드나 기존 문서가 있는 경우에도 리뷰와 개선을 지원한다. 단, 소스 코드 작성, 테스트 실행, CI/CD 구축, 실제 문서 호스팅 배포는 이 스킬의 범위가 아니다.4---56# Technical Writer — 기술 문서 작성 파이프라인78구조설계→집필→다이어그램→리뷰→버전관리를 에이전트 팀이 협업하여 한 번에 생성한다.910## 실행 모드1112**에이전트 팀** — 5명이 SendMessage로 직접 통신하며 교차 검증한다.1314## 에이전트 구성1516| 에이전트 | 파일 | 역할 | 타입 |17|---------|------|------|------|18| info-architect | `.claude/agents/info-architect.md` | 구조 설계, 독자 분석, 목차 | general-purpose |19| doc-writer | `.claude/agents/doc-writer.md` | 본문 작성, 코드 예제, 튜토리얼 | general-purpose |20| diagram-maker | `.claude/agents/diagram-maker.md` | Mermaid 다이어그램, 시각 자료 | general-purpose |21| tech-reviewer | `.claude/agents/tech-reviewer.md` | 정확성, 완전성, 일관성 검증 | general-purpose |22| version-controller | `.claude/agents/version-controller.md` | 메타데이터, 변경 이력, 배포 | general-purpose |2324## 워크플로우2526### Phase 1: 준비 (오케스트레이터 직접 수행)27281. 사용자 입력에서 추출한다:29 - **문서 주제**: 무엇에 대한 문서인가30 - **문서 유형** (선택): API/튜토리얼/가이드/아키텍처/운영31 - **대상 독자** (선택): 역할, 기술 수준32 - **참조 자료** (선택): 소스 코드, 기존 문서, 스펙33 - **기존 파일** (선택): 기존 문서 초안, 구조안342. `_workspace/` 디렉토리를 프로젝트 루트에 생성한다353. 입력을 정리하여 `_workspace/00_input.md`에 저장한다364. 기존 파일이 있으면 `_workspace/`에 복사하고 해당 Phase를 건너뛴다375. 요청 범위에 따라 **실행 모드를 결정**한다3839### Phase 2: 팀 구성 및 실행4041| 순서 | 작업 | 담당 | 의존 | 산출물 |42|------|------|------|------|--------|43| 1 | 구조 설계 | architect | 없음 | `_workspace/01_doc_structure.md` |44| 2a | 본문 집필 | writer | 작업 1 | `_workspace/02_doc_draft.md` |45| 2b | 다이어그램 작성 | diagram | 작업 1 | `_workspace/03_diagrams.md` |46| 3 | 기술 리뷰 | reviewer | 작업 2a, 2b | `_workspace/04_review_report.md` |47| 4 | 버전 관리 | version | 작업 1~3 | `_workspace/05_version_meta.md` |4849작업 2a(본문)와 2b(다이어그램)는 **병렬 실행**한다. 둘 다 작업 1(구조)에만 의존하므로 동시에 시작할 수 있다.5051**팀원 간 소통 흐름:**52- architect 완료 → writer에게 목차·콘텐츠 전략, diagram에게 다이어그램 요건, version에게 메타데이터 전달53- writer ↔ diagram: 삽입 위치, 캡션 조율54- reviewer는 본문+다이어그램을 교차 검증. 🔴 필수 수정 발견 시 해당 에이전트에게 수정 요청 → 재작업 → 재검증 (최대 2회)55- version은 리뷰 결과를 반영하여 최종 메타데이터 확정5657### Phase 3: 통합 및 최종 산출물58591. `_workspace/` 내 모든 파일을 확인한다602. 리뷰 보고서의 🔴 필수 수정이 모두 반영되었는지 확인한다613. 최종 요약을 사용자에게 보고한다:62 - 문서 구조 — `01_doc_structure.md`63 - 문서 본문 — `02_doc_draft.md`64 - 다이어그램 — `03_diagrams.md`65 - 리뷰 보고서 — `04_review_report.md`66 - 버전 메타 — `05_version_meta.md`6768## 작업 규모별 모드6970| 사용자 요청 패턴 | 실행 모드 | 투입 에이전트 |71|----------------|----------|-------------|72| "기술 문서 전체 작성" | **풀 파이프라인** | 5명 전원 |73| "문서 구조만 잡아줘" | **설계 모드** | architect + reviewer |74| "이 내용으로 문서 써줘" (구조 있음) | **집필 모드** | writer + diagram + reviewer |75| "이 문서에 다이어그램 추가" | **다이어그램 모드** | diagram + reviewer |76| "이 문서 리뷰해줘" | **리뷰 모드** | reviewer 단독 |77| "이 문서 업데이트해줘" (기존 버전) | **업데이트 모드** | writer + reviewer + version |7879**기존 파일 활용**: 기존 문서, 코드, 스펙을 제공하면 해당 단계를 건너뛰거나 기존 자료 기반으로 작업한다.8081## 데이터 전달 프로토콜8283| 전략 | 방식 | 용도 |84|------|------|------|85| 파일 기반 | `_workspace/` 디렉토리 | 주요 산출물 저장 및 공유 |86| 메시지 기반 | SendMessage | 실시간 핵심 정보 전달, 수정 요청 |87| 태스크 기반 | TaskCreate/TaskUpdate | 진행 상황 추적, 의존 관계 관리 |8889파일명 컨벤션: `{순번}_{에이전트}_{산출물}.{확장자}`9091## 에러 핸들링9293| 에러 유형 | 전략 |94|----------|------|95| 문서 주제/범위 불명확 | 독자·목적 후보 제시, 선택 유도 |96| 기술 세부사항 부족 | [확인 필요] 태그 삽입, 리뷰 시 검증 |97| 코드 예제 검증 불가 | "검증 필요" 표시, 독자에게 테스트 권고 |98| 에이전트 실패 | 1회 재시도 → 실패 시 해당 산출물 없이 진행, 리뷰 보고서에 누락 명시 |99| 리뷰에서 🔴 발견 | 해당 에이전트에 수정 요청 → 재작업 → 재검증 (최대 2회) |100101## 테스트 시나리오102103### 정상 흐름104**프롬프트**: "우리 팀의 결제 API를 문서화해줘. 대상은 외부 개발자이고, REST API 5개 엔드포인트가 있어."105**기대 결과**:106- 구조: API 레퍼런스 유형, 외부 개발자 대상 독자 분석, 엔드포인트별 섹션 설계107- 본문: 인증, 엔드포인트 5개 상세, 에러 코드, 예제 코드108- 다이어그램: 인증 플로우 시퀀스, 결제 프로세스 플로차트109- 리뷰: 기술 정확성·완전성 검증110- 버전: v1.0.0, Published 상태111112### 기존 파일 활용 흐름113**프롬프트**: "이 문서 구조는 잡혀 있는데, 본문을 작성해줘" + 구조 파일 첨부114**기대 결과**:115- 집필 모드: writer + diagram + reviewer 투입116- architect는 건너뜀, 기존 구조 기반 작업117118### 에러 흐름119**프롬프트**: "기술 문서 써줘, 주제는 대충 우리 시스템 전반"120**기대 결과**:121- 범위 과대 → architect가 문서 분리 제안 (아키텍처 개요, API, 운영 가이드 등)122- 독자 불명확 → 내부 개발자/외부 개발자/운영팀 후보 제시123- 우선순위 문서부터 작업124125## 에이전트별 확장 스킬126127각 에이전트의 전문성을 강화하는 도메인 특화 스킬:128129| 확장 스킬 | 경로 | 대상 에이전트 | 역할 |130|----------|------|-------------|------|131| diagram-patterns | `.claude/skills/diagram-patterns/skill.md` | diagram-maker | Mermaid 다이어그램 패턴 라이브러리 (아키텍처, 시퀀스, 플로차트, ER, 상태 다이어그램) |132| api-doc-standards | `.claude/skills/api-doc-standards/skill.md` | doc-writer | REST API 문서 작성 표준 (엔드포인트 템플릿, 에러 코드, 페이지네이션, 인증) |133| code-example-patterns | `.claude/skills/code-example-patterns/skill.md` | doc-writer | 코드 예제 패턴 (5단계 구조, 언어별 스타일, 튜토리얼 구성) |