LLM이 독자인 세상에서 Docs 작성하기
Source: Dev.to
위의 소스 링크 아래에 번역하고자 하는 텍스트를 제공해 주시면, 해당 내용을 한국어로 번역해 드리겠습니다.
1. Google Cloud가 AI를 위해 문서를 어떻게 적용하고 있는가
Google Cloud 개발자 경험 팀은 한 가지 목표에 집중합니다: 개발자가 학습 단계에서 바로 실행 단계로 가능한 한 빨리 이동하도록 돕는 것.
Google Cloud 서비스가 확대되면서 문서를 정확하고 최신 상태로 유지하는 것이 점점 어려워졌습니다. 개발자는 빠르고 정확한 답변을 기대합니다. 문서가 뒤처지면 채택률이 떨어집니다.
Google Cloud는 기술 작가를 대체한 것이 아니라 AI로 보강했습니다.
생성 AI가 이제 문서 작업 흐름의 일부가 되었습니다. 이는 서식 지정, 마크업 변환, 검증을 지원합니다. 일부 문서는 실제 환경에서 문서화된 단계를 실행하여 자동으로 테스트되기도 합니다.
문서는 코드처럼 취급됩니다: 생성되고, 테스트되며, 지속적으로 개선됩니다.
당신이 Google Cloud 규모에서 일하지 않더라도, 동일한 압박은 오늘날 많은 팀에 이미 존재합니다.
2. 문서는 더 이상 인간만 읽는 것이 아니다
개발자들은 여전히 문서를 읽지만, 대부분의 경우 AI가 먼저 읽습니다.
오늘날 개발자들은:
- AI에게 코드를 생성하고 디버깅하도록 요청한다
- AI에게 API와 도구를 조사하게 한다
- 전체 문서 페이지를 프롬프트에 붙여넣는다
인간 독자도 여전히 중요하지만, LLM은 이제 문서의 주요 소비자가 되었습니다. 이러한 현실은 문서를 어떻게 구조화하고 배포해야 하는지를 바꿉니다.
3. 기술 문서 작성자는 AI와 경쟁하지 않는다. 그들은 AI를 가능하게 한다.
AI가 기술 문서 작성자를 대체할까 걱정하기 쉽다. 실제로는 그 반대가 일어나고 있다.
AI는 텍스트를 빠르게 생성할 수 있지만, 무엇이 중요한지, 무엇이 올바른지, 개념을 어떻게 구조화해야 하는지를 결정할 수 없다. 기술 문서 작성자가 그 구조를 제공한다.
기술 문서 작성자는 AI와 경쟁할 필요가 없으며, AI가 올바르게 사용할 수 있도록 지식을 조직해야 한다. 이 변화는 페이지를 쓰는 역할에서 지식 시스템을 설계하는 역할로 이동한다.
이를 수행하는 일반적인 방법 중 하나는 AI 도구에 문서의 구조화된 기계가 읽을 수 있는 버전을 제공하는 것이다. 여기서 llms.txt가 등장한다.
4. llms.txt가 무엇이며 무엇이 아닌가
llms.txt는 문서의 기계가 읽을 수 있는 버전입니다. 보통 Markdown으로 작성되며 AI 도구와 LLM을 위해 설계되었습니다.
이를 번역 레이어라고 생각하면 됩니다:
- 메인 문서는 인간 친화적으로 유지됩니다
llms.txt는 AI에게 동일한 내용의 깔끔하고 구조화된 뷰를 제공합니다
좋은 llms.txt 파일에는 보통 다음이 포함됩니다:
- 핵심 개념 및 용어 정의
- API 개요와 제약 조건
- 인증 및 환경 가정
- 표준 예시
- 알려진 제한 사항 및 엣지 케이스
대체 문서가 아니라는 점을 기억하세요. 문서를 보호하는 역할을 합니다. AI에게 자체 컨텍스트 파일을 제공함으로써 인간 문서를 프롬프트 형태의 콘텐츠로 전환하는 일을 방지합니다. 인간 독자는 명확성을 얻고, AI 도구는 구조를 얻습니다.
5. llms.txt 자동 생성하기
Google Cloud에서 배운 핵심 교훈 중 하나는 자동화입니다. 그들의 문서는 지속적으로 생성·검증·테스트됩니다. llms.txt도 같은 방식을 따라야 합니다.
베스트 프랙티스: 문서가 변경될 때마다 자동으로 생성합니다.
실제 적용 방법:
- 문서 빌드 프로세스의 일부로
llms.txt를 생성하기 - 모든 문서 편집 시마다 재생성하기
- Markdown의 제목, 코드 블록, 링크, 예시를 그대로 보존하기
- 파일이 완전한지 확인하는 간단한 체크 추가하기
왜 중요한가:
- AI는 최신 컨텍스트에 의존합니다
- 수동 업데이트는 시간이 지남에 따라 차이가 발생합니다
- 자동화는 사람과 AI를 일치시킵니다
하나의 진실된 출처. 두 개의 청중. 중복 없음.
6. Google Cloud의 AI 코드 시스템에서 얻은 교훈
Google Cloud도 코드 샘플에 AI를 적용했습니다. 그들은 수천 개의 API, 다양한 언어, 그리고 지속적인 변화를 마주했습니다. 수동 유지보수는 규모를 확장할 수 없었습니다.
그들의 해결책은 다음과 같은 AI 시스템을 사용했습니다:
- 공식 API 정의에서 샘플 생성
- 결과를 자동으로 검토 및 정제
- 게시 전에 코드 테스트
교훈은 간단합니다: AI는 지식이 구조화되고, 근거가 있으며, 검증될 때 가장 잘 작동합니다. 동일한 원칙이 문서에도 적용됩니다. llms.txt는 AI 도구를 위한 그 구조를 제공합니다.
7. llms.txt를 실제로 사용하는 방법
자체적으로 문서를 가져올 수 없는 제한된 기능의 AI 도구에 llms.txt가 특히 유용합니다.
간단한 워크플로우:
docs.example.com/llms.txt열기- 마크다운 파일을 다운로드하거나 복사
- AI 코딩 도구에 업로드
- 도구에 이 컨텍스트를 사용해 분석, 디버그 또는 코드 생성을 요청
이를 통해 AI 출력이 실제 문서와 실제 제약 조건에 맞게 정렬됩니다.
8. 쉽게 찾을 수 있게 만들기
llms.txt가 유용하려면 눈에 보여야 합니다.
추천 방법:
docs.example.com/llms.txt에 게시하기- Markdown 형식으로 유지하기
- 문서에 “AI Context (llms.txt)”와 같은 눈에 띄는 버튼을 추가하여 새 탭에서 열리게 하기
이것은 고급 사용자용 트릭이 아니라 기본 문서 인프라입니다.
9. 마무리 생각
AI는 기술 작가의 필요성을 없애는 것이 아니라 기대치를 높이고 있습니다. 작업은 더 많은 페이지를 쓰는 것에서 다음으로 전환됩니다:
- 지식을 명확하게 구조화하기
- 확장 가능한 시스템 설계하기
- 인간과 기계 모두에게 신뢰할 수 있는 문서 만들기
llms.txt는 작은 파일이지만 실제 변화를 나타냅니다. 현재 문서를 담당하고 있다면, AI가 문서를 읽을지 여부가 문제가 아니라—이미 읽고 있습니다. 진짜 질문은 AI가 올바른 버전을 읽고 있는가 입니다.