AI와 협업하는 문서 작성 프로세스

문서를 처음부터 끝까지 혼자 쓰는 시대는 지났습니다. AI와 협업하면 설계에 집중하고 작성은 위임할 수 있습니다. 이 장에서는 AI 협업 문서 작성의 전체 프로세스를 다룹니다.

새로운 문서 라이프사이클

단계	주체	핵심 활동
설계	사람	문서 목적, 대상, 구조 결정
초안 생성	AI	프롬프트 기반 초안 작성
사람 검증	사람	사실 확인, 톤 조정, 누락 보완
AI 검증	AI	구조 점검, 링크 확인, 일관성 검사
발행	사람	최종 승인 후 배포
유지보수	AI	변경 감지, stale 알림, 자동 업데이트 제안

단계별 상세

1단계: 설계

문서를 쓰기 전에 무엇을, 누구를 위해, 어떤 구조로 쓸지 결정합니다.

## 문서 설계 시트

- 목적: (이 문서가 해결하는 문제)
- 대상: (누가 읽는가 — 사람? AI? 둘 다?)
- 유형: (API 문서 / 가이드 / ADR / 런북 / ...)
- 구조: (섹션 목록)
- 참고: (기존 코드, 문서, 스펙)

2단계: AI 초안 생성

설계 시트를 기반으로 AI에게 초안을 요청합니다.

3단계: 사람 검증

AI 초안의 사실 정확성, 프로젝트 맥락 반영, 톤 을 확인합니다.

4단계: AI 검증

구조적 품질을 AI로 자동 검증합니다.

5단계: 발행 & 유지보수

Git 커밋 + CI 파이프라인으로 문서를 배포합니다.

프롬프트 패턴

문서 생성에 효과적인 프롬프트 패턴 5가지입니다.

패턴 1: 역할 + 맥락 + 구조 지정

당신은 시니어 테크니컬 라이터입니다.
다음 API 엔드포인트에 대한 문서를 작성해주세요.

맥락:
- 프로젝트: 결제 시스템
- 대상 독자: 프론트엔드 개발자
- 인증: Bearer 토큰

구조:
1. 엔드포인트 요약 (테이블)
2. 각 엔드포인트별: 설명, 파라미터, 응답, 에러 코드, 예시
3. 인증 흐름

참고 코드: [코드 경로 또는 코드 블록]

패턴 2: Before/After 변환

다음 산문형 문서를 AI-readable 형식으로 변환해주세요.

원칙:
- frontmatter 추가
- 기본지식 설명 제거
- 표와 목록 사용
- 선언적 규칙으로 변환

원본:
[기존 문서 붙여넣기]

패턴 3: 검증 요청

다음 문서를 검증해주세요.

검증 항목:
1. 코드 예시가 실제 동작하는지
2. 링크가 유효한지
3. 용어가 일관적인지
4. 날짜/버전이 최신인지
5. 누락된 섹션이 있는지

문서:
[문서 붙여넣기]

패턴 4: 기존 코드에서 문서 생성

다음 코드를 분석해서 [문서 유형]을 작성해주세요.

코드를 읽고:
1. 주요 기능과 인터페이스를 파악
2. 사용 예시를 도출
3. 주의사항/제약사항을 식별

출력 형식: [해당 유형의 템플릿 참조]

패턴 5: 점진적 개선

다음 문서를 개선해주세요.
변경하지 말아야 할 것: [유지할 내용]
개선할 것: [구체적 개선 포인트]

문서:
[기존 문서]

도구별 워크플로우

# CLAUDE.md에 문서화 규칙 추가
## Documentation Rules
- 코드 변경 시 관련 문서도 함께 업데이트
- 모든 MDX 파일에 frontmatter 필수
- 커밋 전 문서 링크 유효성 확인

# Plan 모드로 문서 설계
/plan API 문서를 AI-readable 형식으로 재작성해줘

# 문서 생성
"src/api/users.ts를 읽고 API 문서를 생성해줘"

# 검증
"docs/ 디렉토리의 모든 내부 링크가 유효한지 확인해줘"

# AGENTS.md에 문서화 에이전트 정의
## Documentation Agent
- role: technical-writer
- tools: Read, Write, Grep
- constraints: 기존 문서 스타일 유지

# exec 모드로 자동 생성
codex exec "src/api/ 디렉토리의 모든 엔드포인트에 대한 API 문서를 생성해줘"

# 배치 처리
codex exec "docs/ 하위 모든 문서의 링크 유효성을 검증해줘"

# .cursorrules에 문서화 규칙 추가
문서 작성 시:
- frontmatter 필수 포함
- 기본지식 설명 생략
- 표와 목록 우선 사용
- 선언적 규칙으로 서술

# Composer에서 문서 생성
@file src/api/users.ts
이 파일의 API 문서를 작성해줘. OpenAPI 형식으로.

# 문서 검증
@folder docs/
이 폴더의 문서들에서 불일치나 누락된 내용을 찾아줘.

비즈니스 문서에 AI 협업 적용하기

기술 문서만이 아니라 비즈니스 문서(회의록, 제안서, 보고서)도 AI 협업 프로세스의 대상입니다.

회의록: AI 자동 생성 → 구조화된 액션 아이템

AI가 회의 녹취를 요약하고 액션 아이템을 추출하는 패턴이 실무에서 가장 많이 사용됩니다.

회의 녹취록/메모를 다음 구조로 정리해줘:

## 회의 요약
- 일시/참석자/주제

## 핵심 결정
1. [결정 내용] — 근거: [이유]

## 액션 아이템
| 항목 | 담당 | 기한 | 상태 |
|---|---|---|---|
| [할 일] | [담당자] | [YYYY-MM-DD] | 미완 |

## 다음 회의 안건
- [안건]

원칙: 논의 과정은 최소화하고, 결정과 액션에 집중

제안서/보고서: 구조 설계 → AI 초안 → 사람 검증

다음 구조로 [제안서/보고서] 초안을 작성해줘:

1. 요약 (Executive Summary) — 3문장 이내
2. 현황/문제 — 데이터 기반
3. 제안/해결책 — 구체적 행동
4. 기대 효과 — 수치로 표현
5. 일정/예산
6. 리스크/대안

톤: 경영진 대상, 간결하고 데이터 중심
참고 자료: [데이터/자료 첨부]

핵심 원칙은 동일

비즈니스 문서도 기술 문서와 같은 원칙을 따릅니다: 설계 먼저 → AI 초안 → 사람이 검증. 차이는 톤(경영진 대상)과 구조(Executive Summary 선행)뿐입니다.

AI 생성 문서의 흔한 문제

문제	증상	해결법
환각 (Hallucination)	존재하지 않는 API, 잘못된 파라미터	코드를 직접 참조하도록 프롬프트
과잉 설명	기본지식까지 장황하게 설명	"기본지식 생략" 명시
구조 불일치	템플릿과 다른 형식으로 출력	템플릿을 프롬프트에 포함
날짜 오류	과거 정보를 최신으로 표기	현재 날짜/버전 명시
일관성 부족	같은 개념을 다른 용어로 표현	용어집을 프롬프트에 포함

검증 체크리스트

사람 검증 (3단계)

항목	확인
사실이 정확한가 (코드와 일치하는가)	☐
프로젝트 맥락이 올바르게 반영되었는가	☐
대상 독자에게 적절한 수준인가	☐
톤과 스타일이 기존 문서와 일관적인가	☐
민감 정보가 포함되지 않았는가	☐

AI 검증 (4단계)

항목	자동화 가능
frontmatter 존재 여부	✅
내부 링크 유효성	✅
외부 링크 유효성	✅
용어 일관성	✅
코드 블록 문법 오류	✅
제목 계층 정합성	✅
날짜/버전 최신성	⚠️ (기준 필요)

새로운 문서 라이프사이클

단계	주체	핵심 활동
설계	사람	문서 목적, 대상, 구조 결정
초안 생성	AI	프롬프트 기반 초안 작성
사람 검증	사람	사실 확인, 톤 조정, 누락 보완
AI 검증	AI	구조 점검, 링크 확인, 일관성 검사
발행	사람	최종 승인 후 배포
유지보수	AI	변경 감지, stale 알림, 자동 업데이트 제안

단계별 상세

1단계: 설계

문서를 쓰기 전에 무엇을, 누구를 위해, 어떤 구조로 쓸지 결정합니다.

## 문서 설계 시트

- 목적: (이 문서가 해결하는 문제)
- 대상: (누가 읽는가 — 사람? AI? 둘 다?)
- 유형: (API 문서 / 가이드 / ADR / 런북 / ...)
- 구조: (섹션 목록)
- 참고: (기존 코드, 문서, 스펙)

2단계: AI 초안 생성

설계 시트를 기반으로 AI에게 초안을 요청합니다.

3단계: 사람 검증

AI 초안의 사실 정확성, 프로젝트 맥락 반영, 톤 을 확인합니다.

4단계: AI 검증

구조적 품질을 AI로 자동 검증합니다.

5단계: 발행 & 유지보수

Git 커밋 + CI 파이프라인으로 문서를 배포합니다.

프롬프트 패턴

문서 생성에 효과적인 프롬프트 패턴 5가지입니다.

패턴 1: 역할 + 맥락 + 구조 지정

당신은 시니어 테크니컬 라이터입니다.
다음 API 엔드포인트에 대한 문서를 작성해주세요.

맥락:
- 프로젝트: 결제 시스템
- 대상 독자: 프론트엔드 개발자
- 인증: Bearer 토큰

구조:
1. 엔드포인트 요약 (테이블)
2. 각 엔드포인트별: 설명, 파라미터, 응답, 에러 코드, 예시
3. 인증 흐름

참고 코드: [코드 경로 또는 코드 블록]

패턴 2: Before/After 변환

다음 산문형 문서를 AI-readable 형식으로 변환해주세요.

원칙:
- frontmatter 추가
- 기본지식 설명 제거
- 표와 목록 사용
- 선언적 규칙으로 변환

원본:
[기존 문서 붙여넣기]

패턴 3: 검증 요청

다음 문서를 검증해주세요.

검증 항목:
1. 코드 예시가 실제 동작하는지
2. 링크가 유효한지
3. 용어가 일관적인지
4. 날짜/버전이 최신인지
5. 누락된 섹션이 있는지

문서:
[문서 붙여넣기]

패턴 4: 기존 코드에서 문서 생성

다음 코드를 분석해서 [문서 유형]을 작성해주세요.

코드를 읽고:
1. 주요 기능과 인터페이스를 파악
2. 사용 예시를 도출
3. 주의사항/제약사항을 식별

출력 형식: [해당 유형의 템플릿 참조]

패턴 5: 점진적 개선

다음 문서를 개선해주세요.
변경하지 말아야 할 것: [유지할 내용]
개선할 것: [구체적 개선 포인트]

문서:
[기존 문서]

도구별 워크플로우

# CLAUDE.md에 문서화 규칙 추가
## Documentation Rules
- 코드 변경 시 관련 문서도 함께 업데이트
- 모든 MDX 파일에 frontmatter 필수
- 커밋 전 문서 링크 유효성 확인

# Plan 모드로 문서 설계
/plan API 문서를 AI-readable 형식으로 재작성해줘

# 문서 생성
"src/api/users.ts를 읽고 API 문서를 생성해줘"

# 검증
"docs/ 디렉토리의 모든 내부 링크가 유효한지 확인해줘"

# AGENTS.md에 문서화 에이전트 정의
## Documentation Agent
- role: technical-writer
- tools: Read, Write, Grep
- constraints: 기존 문서 스타일 유지

# exec 모드로 자동 생성
codex exec "src/api/ 디렉토리의 모든 엔드포인트에 대한 API 문서를 생성해줘"

# 배치 처리
codex exec "docs/ 하위 모든 문서의 링크 유효성을 검증해줘"

# .cursorrules에 문서화 규칙 추가
문서 작성 시:
- frontmatter 필수 포함
- 기본지식 설명 생략
- 표와 목록 우선 사용
- 선언적 규칙으로 서술

# Composer에서 문서 생성
@file src/api/users.ts
이 파일의 API 문서를 작성해줘. OpenAPI 형식으로.

# 문서 검증
@folder docs/
이 폴더의 문서들에서 불일치나 누락된 내용을 찾아줘.

비즈니스 문서에 AI 협업 적용하기

기술 문서만이 아니라 비즈니스 문서(회의록, 제안서, 보고서)도 AI 협업 프로세스의 대상입니다.

회의록: AI 자동 생성 → 구조화된 액션 아이템

AI가 회의 녹취를 요약하고 액션 아이템을 추출하는 패턴이 실무에서 가장 많이 사용됩니다.

회의 녹취록/메모를 다음 구조로 정리해줘:

## 회의 요약
- 일시/참석자/주제

## 핵심 결정
1. [결정 내용] — 근거: [이유]

## 액션 아이템
| 항목 | 담당 | 기한 | 상태 |
|---|---|---|---|
| [할 일] | [담당자] | [YYYY-MM-DD] | 미완 |

## 다음 회의 안건
- [안건]

원칙: 논의 과정은 최소화하고, 결정과 액션에 집중

제안서/보고서: 구조 설계 → AI 초안 → 사람 검증

다음 구조로 [제안서/보고서] 초안을 작성해줘:

1. 요약 (Executive Summary) — 3문장 이내
2. 현황/문제 — 데이터 기반
3. 제안/해결책 — 구체적 행동
4. 기대 효과 — 수치로 표현
5. 일정/예산
6. 리스크/대안

톤: 경영진 대상, 간결하고 데이터 중심
참고 자료: [데이터/자료 첨부]

핵심 원칙은 동일

AI 생성 문서의 흔한 문제

문제	증상	해결법
환각 (Hallucination)	존재하지 않는 API, 잘못된 파라미터	코드를 직접 참조하도록 프롬프트
과잉 설명	기본지식까지 장황하게 설명	"기본지식 생략" 명시
구조 불일치	템플릿과 다른 형식으로 출력	템플릿을 프롬프트에 포함
날짜 오류	과거 정보를 최신으로 표기	현재 날짜/버전 명시
일관성 부족	같은 개념을 다른 용어로 표현	용어집을 프롬프트에 포함

검증 체크리스트

사람 검증 (3단계)

항목	확인
사실이 정확한가 (코드와 일치하는가)	☐
프로젝트 맥락이 올바르게 반영되었는가	☐
대상 독자에게 적절한 수준인가	☐
톤과 스타일이 기존 문서와 일관적인가	☐
민감 정보가 포함되지 않았는가	☐

AI 검증 (4단계)

항목	자동화 가능
frontmatter 존재 여부	✅
내부 링크 유효성	✅
외부 링크 유효성	✅
용어 일관성	✅
코드 블록 문법 오류	✅
제목 계층 정합성	✅
날짜/버전 최신성	⚠️ (기준 필요)

AI와 협업하는 문서 작성 프로세스

목차

AI와 협업하는 문서 작성 프로세스

목차