문서화(Documentation)는 모두가 중요하다고 동의하지만, 아무도 쓰고 싶어 하지 않는 작업입니다. 2년 동안 개발자 대상 제품을 구축하면서, 저는 개발자들이 실제로 읽는 문서 — 즉, /docs 폴더 안에서 가상 먼지만 쌓여가는 그런 문서가 아닌 — 를 만들어내는 AI 보조 워크플로우(AI-assisted workflow)를 정착시켰습니다.

이 시스템이 작동하게 만드는 체계와 프롬프트(Prompts), 그리고 제약 조건(Constraints)을 소개합니다.

AI 생성 문서의 핵심 문제점

대부분의 사람들은 AI를 사용하여 다음과 같이 문서를 작성합니다: "내 API를 위한 문서를 작성해줘." 그 결과물은 모호한 서론, 중복된 섹션, 그리고 컴파일조차 되지 않는 코드 예시가 가득한 2,000단어 분량의 텍스트 벽입니다.

해결책은 더 나은 AI를 사용하는 것이 아닙니다. 더 나은 제약 조건(Constraints)을 설정하는 것입니다. 아래의 모든 프롬프트는 대상(Audience), 형식(Format), 단어 수(Word count), 그리고 결정적으로 — 무엇을 _제외할지(Exclude)_를 명시합니다.

1단계: 문서 구조를 먼저 생성하기

어떤 콘텐츠를 작성하기 전에, 검토하고 승인할 수 있는 목차(Table of contents)를 먼저 생성하세요.

Role: 당신은 개발자 도구(Developer tools)를 위한 문서를 작성하는 기술 작가(Technical writer)입니다.

...

이 방법이 효과적인 이유: "Quickstart 우선" 제약 조건은 개발자 문서에서 가장 중요한 단 하나의 규칙입니다. 개발자들은 문서를 선형적으로 읽지 않습니다. 그들은 10분 이내에 작동하는 통합(Integration)을 구현할 수 있게 해주는 요소를 찾기 위해 훑어봅니다. 만약 그것이 없다면, 그들은 떠납니다.

2단계: Quickstart 작성하기 (개발자들이 읽는 유일한 섹션)

Role: 당신은 Quickstart 가이드를 작성하는 개발자 어드보킷(Developer advocate)입니다.

Context: [PRODUCT]는 [TYPE]입니다. Quickstart는 개발자가
...

이 방법이 효과적인 이유: 복사해서 붙여넣기 가능한(Copy-pasteable) 제약 조건은 가장 흔한 문서화 실패 사례인 '파편화된 코드 예시'를 제거합니다. 만약 개발자가 빈칸을 채워 넣어야 한다면, 그 Quickstart는 Quickstart가 아니라 퍼즐이 되어버립니다.

3단계: API 레퍼런스 항목 작성하기 (포괄적이기보다 일관되게)

Role: 당신은 API 레퍼런스 문서를 제작하는 기술 작가(Technical writer)입니다.

Context: 여기 엔드포인트/함수가 있습니다: [NAME, METHOD, PATH].
...

이 방법이 효과적인 이유: API 레퍼런스 문서 (API reference docs)는 일관성이 없을 때 실패합니다. 어떤 엔드포인트에는 파라미터 테이블 (parameter table)이 있고, 다른 곳에는 없는 경우; 어떤 곳에는 에러 예시 (error examples)가 있고, 다른 곳에는 없는 경우처럼 말이죠. 이 프롬프트는 엄격한 템플릿 (template)을 강제하여 모든 항목이 동일하게 보이도록 만듭니다. 이것이 바로 개발자들이 레퍼런스 자료에서 실제로 원하는 것입니다.

4단계: 트러블슈팅 섹션 (Troubleshooting Section) 작성하기

역할 (Role): 당신은 실제 티켓 데이터 (ticket data)를 기반으로 트러블슈팅 가이드를 작성하는 서포트 엔지니어 (support engineer)입니다.

...

이 방법이 효과적인 이유: 트러블슈팅 문서 (Troubleshooting docs)는 보통 추측에 기반하여 작성됩니다. 즉, "발생할 수도 있는 문제들"을 나열하는 식이죠. 이 프롬프트는 실제 서포트 데이터로부터 시작하도록 강제합니다. 항목당 100단어 제한은 트러블슈팅 페이지를 읽기 어렵게 만드는 장황한 설명을 방지합니다.

5단계: 마이그레이션 가이드 (Migration Guide) 작성하기 (변경 사항으로 인해 문제가 발생할 때)

역할 (Role): 당신은 중대한 변경 사항 (breaking change)에 대한 마이그레이션 가이드를 작성하는 개발자 관계 엔지니어 (developer relations engineer)입니다.

...

이 방법이 효과적인 이유: 마이그레이션 가이드는 가장 리스크가 큰 문서입니다. 잘못 작성하면 사용자의 운영 환경 (production)을 망가뜨릴 수 있습니다. "독립적으로 테스트 가능한 단계 (independently testable steps)"라는 제약 조건은 개발자가 7단계를 모두 수행한 뒤 아무것도 폭발하지 않기를 기도하는 대신, 다음 단계로 넘어가기 전에 각 단계를 검증할 수 있음을 의미합니다.

6단계: 아키텍처 결정 기록 (Architecture Decision Record, ADR) 작성하기

역할 (Role): 당신은 엔지니어링 팀을 위해 ADR을 작성하는 스태프 엔지니어 (staff engineer)입니다.

컨텍스트 (Context): 결정 필요 사항: [기술적 결정 사항 기술]. 옵션 (Options)
...

이 방법이 효과적인 이유: "재검토 트리거 (trigger to revisit)" 제약 조건은 좋은 ADR의 비밀 병기입니다. 이 조건이 없으면 거절된 대안들은 사라지고, 팀은 왜 옵션 B가 거절되었는지 아무도 기억하지 못해 6개월 후에 똑같은 결정을 다시 논쟁하게 됩니다. 이 조건이 있으면 ADR은 순환 논쟁을 방지하는 살아있는 문서 (living document)가 됩니다.

7단계: 검토 및 삭제

이것은 모든 섹션을 생성한 후에 실행하는 프롬프트입니다:

역할 (Role): 당신은 무자비한 문서 편집자 (documentation editor)입니다.

컨텍스트 (Context): 여기 제가 생성한 문서가 있습니다: [모든 섹션 붙여넣기].
...

이 방법이 효과적인 이유: AI가 생성한 문서는 과잉 생산되는 경향이 있습니다. 이 검토 프롬프트(Review prompt)는 사용자가 모든 단어를 수동으로 읽지 않아도 가장 흔한 세 가지 실패 모드인 중복성 (Redundancy), 불완전한 코드 (Incomplete code), 모호함 (Vagueness)을 잡아냅니다. 프롬프트를 실행하고 표시된 문제들을 수정하면, 여러분의 문서는 바로 배포 가능한 수준 (Production-ready)이 됩니다.

실제 워크플로우 (The Workflow in Practice)

새로운 기능(Feature)을 위해 제가 이 과정을 처음부터 끝까지 실행하는 방법은 다음과 같습니다:

1. 개요(Outline) 생성 (1단계), 이를 검토하고 독자에게 도움이 되지 않는 섹션은 삭제
2. 퀵스타트 (Quickstart) 작성 (2단계) — 이것이 가치의 80%를 차지합니다
3. 각 엔드포인트(Endpoint)/함수(Function)에 대한 API 레퍼런스 (API reference) 항목 작성 (3단계)
4. 실제 지원 데이터 (Support data)를 바탕으로 문제 해결 (Troubleshooting) 섹션 작성 (4단계)
5. 중대한 변경 사항 (Breaking change)이 아닌 한 마이그레이션 가이드 (Migration guide)는 건너뜀 (5단계)
6. 명확하지 않은 기술적 결정에 대해 ADR (Architecture Decision Record) 작성 (6단계)
7. 검토 프롬프트 (Review prompt) 실행 (7단계), 표시된 문제 수정

중간 규모 기능 기준 총 소요 시간: 약 90분. 이 워크플로우를 도입하기 전에는 동일한 문서를 작성하는 데 꼬박 하루가 걸렸으며 품질도 더 낮았습니다.

피해야 할 일반적인 실수

한 번의 프롬프트로 모든 섹션을 생성하지 마세요. 개요를 먼저 작성하는 방식(Outline-first approach)을 사용하면 콘텐츠에 많은 공을 들이기 전에 방향을 수정할 수 있습니다. 모든 것을 한꺼번에 생성하면 구조가 잘못된 5,000단어짜리 문서가 만들어집니다.

검토 단계(Review step)를 건너뛰지 마세요. 검토 프롬프트(7단계)는 누적되어 발생하는 문제들을 잡아냅니다. 예를 들어, 퀵스타트의 모호한 지침 하나가 연쇄적으로 잘못된 통합 (Broken integration)으로 이어질 수 있습니다.

AI가 예제를 선택하게 두지 마세요. 항상 실제 코드 예제 (Code examples)를 직접 제공하고 AI에게 이를 문서화하도록 요청하세요. 제 테스트 결과, AI가 생성한 코드 예제는 약 60%의 확률로 컴파일(Compile)되지만, 여러분의 실제 코드는 100% 컴파일됩니다.

이 프롬프트들을 가져가서 여러분에 맞게 조정하세요

위의 모든 프롬프트는 동일한 구조를 사용합니다: 역할 (Role) → 컨텍스트 (Context) → 제약 사항 (Constraints) → 출력 (Output). 가치는 바로 제약 사항에서 나옵니다. 이 프레임워크를 복사하여 제품의 세부 정보를 채우고, 여러분의 문서 스타일 가이드 (Documentation style guide)에 맞춰 제약 사항을 조정하세요.

목표는 첫 시도에 완벽한 AI 결과물을 얻는 것이 아닙니다. 80% 정도 정확한 결과물을 얻는 것이 목표이며, 이를 검토한 후 처음부터 작성할 때 걸리는 시간의 아주 일부만 사용하여 배포하는 것입니다.

이와 같은 AI 워크플로우 (AI workflows)를 더 찾고 계신가요? 문서화 (documentation), 엔지니어링 관리 (engineering management), 제품 (product), 마케팅 (marketing)을 위한 프롬프트 라이브러리를 구축해 두었으며, 각 프롬프트는 동일한 방식으로 테스트되었습니다. 전체 프롬프트 팩은 여기에서 확인하세요.

완전한 시스템이 필요한 팀을 위해, AI 스타트업 운영 프롬프트 시스템 (AI Startup Operations Prompt System)은 엔지니어링, 제품, 운영을 아우르는 전체 워크플로우 문서와 함께 50개 이상의 프롬프트를 포함하고 있습니다.