How We Made Our Docs Test Themselves

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

LangChain은 Deep Agents CLI와 재사용 가능한 Skills로 문서의 인라인 코드 예제를 실행·테스트 가능한 파일로 전환하는 작업을 위임하고, CI로 지속 검증하는 방식을 소개한다.

📌 핵심 요약

• 의존성·API·모델·SDK와 권장 방식이 바뀌면 문서의 코드 예제가 작동하지 않을 수 있으며, AI·LLM 분야의 빠른 변화가 이 문제를 심화한다.
• 문서 예제를 CI에서 실행하고 정상 동작을 검증하며 실패 시 빌드를 중단하면 오류를 감지할 수 있지만, 예제를 테스트 가능한 형태로 만드는 데 초기 투자가 필요하다.
• LangChain은 Deep Agents CLI와 docs-code-samples 스킬을 사용해 코드 분리, 설정·정리 코드 추가, 린트, 구간 표시, 실행 검증과 문서 반영 작업을 위임했다.
• 코드는 src/code-samples/{product} 아래에 제품별로 배치하며, Bluehawk가 표시된 구간을 추출하고 생성된 파일을 Mintlify 스니펫으로 MDX 문서에 포함하는 구조를 사용한다.
• 스킬은 .agents/skills/docs-code-samples/SKILL.md에 저장되며, 에이전트의 전환 작업에 더해 테스트를 정기 실행하고 실패 시 티켓을 생성하는 GitHub Action이 필요하다.

🧩 주요 포인트

1. 정적인 인라인 예제는 API 변경을 놓치기 쉬움 → 실행 가능한 파일과 CI 검증으로 문서 코드에도 회귀 감지를 적용한다.
2. 전환에 필요한 반복 절차를 docs-code-samples 스킬로 명문화 → Deep Agents CLI에 작업을 위임해 수작업 부담을 줄이는 접근이다.
3. 실행용 코드와 문서에 표시할 구간을 분리 → 설정·정리 코드를 갖춘 테스트와 필요한 코드만 보여 주는 문서 구성을 함께 지원한다.

🧠 상세 정리

1. 빠른 변화로 낡아지는 문서 코드

글은 튜토리얼, API 가이드, 통합 예제를 제공하는 팀이라면 의존성과 API 변화로 예제가 깨지는 문제를 겪게 된다는 설명에서 출발한다. LangChain에서도 같은 문제가 발생하며, 제품과 AI·LLM 분야의 빠른 변화가 이를 더 심화한다고 본다. 새로운 모델, SDK 업데이트, 권장 방식의 변화 때문에 지난달에 작동하던 코드가 오늘은 작동하지 않을 수 있다는 것이다. 해결 방향은 문서 예제를 CI에서 실행하고 정상 동작을 검증하며, 실패하면 빌드를 중단하도록 만드는 데 있다. 다만 예제를 테스트 가능한 상태로 준비하는 초기 작업이 만만치 않아 도입 자체가 미뤄질 수 있으며, 글은 이 부담을 에이전트에 위임하자고 제안한다.

2. 인라인 예제를 테스트 가능한 파일로 전환

인라인 코드 예제는 코드를 시험한 뒤 필요한 부분만 복사해 마크다운 등의 문서 파일에 붙여 넣으면 되므로 작성하기 편리하다. 그러나 문서에 들어간 코드는 정적인 상태로 남아 있어, 사용 중인 API가 바뀌어도 수정이 누락될 수 있다. 글은 애플리케이션 코드처럼 문서 코드에도 자동 검사와 회귀 감지를 적용해야 한다고 주장한다. 이를 위한 수작업 절차는 인라인 코드를 독립 파일로 추출하고 설정·정리 코드를 추가한 다음, 문서에 표시할 구간을 마크업으로 지정하고 도구로 추출해 재사용 가능한 스니펫으로 포함하는 것이다. 이어 CI에서 정기적으로, 그리고 예제가 변경될 때 실행하도록 연결하며, LangChain은 이 전환 작업을 Deep Agents CLI에 맡겼다고 설명한다.

3. Skills로 반복 작업을 에이전트에 위임

Deep Agents CLI는 대화할 수 있는 명령줄 에이전트이며, 작업에 맞는 스킬의 정보를 활용하는 기능을 제공한다. 스킬은 작업이 설명과 일치할 때 에이전트가 불러오는 재사용 가능한 지침으로, 동료에게 전달할 단계별 업무 설명처럼 작성할 수 있다. LangChain은 문서 코드 전환에 필요한 절차를 이러한 지침으로 정리해 에이전트가 수행하도록 했다. 글에서 제시하는 핵심은 전환 절차를 한 번 작성해 두고 반복 실행을 위임하는 방식이며, 이 사례에서는 별도의 코딩 없이 마이그레이션 작업을 맡겼다고 설명한다. 다만 스킬과 지침을 준비하는 과정은 여전히 필요하므로, 초기 준비 없이 모든 작업이 자동으로 해결된다는 주장으로 확대할 수는 없다.

4. 실행 코드와 문서용 구간을 함께 관리

스킬의 구체적인 지침은 코드를 제품 영역별로 src/code-samples/{product} 아래의 독립 파일에 옮기는 것부터 시작한다. 이어 설정·정리 코드를 추가해 완전히 실행 가능한 예제로 만들고, 저장소에 설정된 린터로 코드를 검사한다. 문서에 표시할 부분은 :snippet-start:와 :snippet-end: 태그로 지정하며, 표시 구간 안에서 제외할 코드는 :remove-start:와 :remove-end:로 표시할 수 있다. 에이전트는 코드 예제를 실행해 검증한 뒤 마크업을 바탕으로 스니펫을 생성하고 문서에 포함한다. 이 구조에서는 실행에 필요한 주변 코드를 갖추면서도 문서에는 지정한 코드 구간을 보여 줄 수 있어, 테스트할 예제와 독자가 읽을 예제를 연결할 수 있다.

5. 저장소 안의 스킬 정의와 사용 방식

docs-code-samples 스킬은 문서 저장소의 숨김 경로인 .agents/skills/docs-code-samples/SKILL.md에 들어 있다. 파일의 프런트매터에 있는 description은 LangChain의 MDX 문서에서 인라인 코드를 외부의 테스트 가능한 파일로 옮기고, Bluehawk로 추출해 Mintlify 스니펫으로 사용하는 작업에 이 스킬을 적용하도록 설명한다. 본문에는 사용 시점, 디렉터리와 파일 배치, 단계별 전환 지침, 명령 실행 순서, 이름·태그·임포트 규칙이 담긴다. 이 구성이 있으면 저장소 안에서 Deep Agents CLI를 열고 streaming.mdx의 인라인 코드를 테스트 가능한 예제로 바꿔 달라고 요청할 수 있다. 에이전트는 스킬을 활용해 파일 생성, 태그 추가, 명령 실행과 문서의 스니펫 포함 작업을 수행하며, 전체 스킬 파일은 GitHub 저장소에서 확인할 수 있다고 안내한다.

6. 지속 검증을 위한 CI 연결

글은 코드 예제를 옮기고 검증하는 에이전트 작업에 더해, 테스트를 정기적으로 실행하고 실패하면 티켓을 생성하는 GitHub Action이 필요하다고 명시한다. 따라서 스킬을 통한 전환은 지속적인 문서 검증을 구성하는 한 부분이며, 이후에도 예제가 작동하는지 확인하는 실행 체계가 함께 있어야 한다. 앞서 제시한 일반 원칙은 CI에서 예제의 정상 실행을 검증하고 문제가 생기면 빌드를 실패시키는 것으로, 문서도 애플리케이션 코드와 같은 자동 검사의 대상으로 다룬다는 취지다. 글은 이 사례를 저장소에서 Deep Agents와 Skills를 활용하는 한 가지 예로 제시하고, 시작 방법은 CLI 문서를 참고하도록 안내한다. 전환 시간의 절감량이나 오류 감소율 같은 정량적인 성과는 본문에 제시하지 않는다.

🧾 핵심 주장 / 시사점

• 문서의 코드 예제를 테스트 대상으로 다루려면 CI 연결뿐 아니라, 불완전한 인라인 코드를 실행 가능한 예제로 바꾸는 준비 작업이 중요하다.
• Skills는 디렉터리 구조와 명령 순서 같은 저장소의 작업 규칙을 재사용 가능한 지침으로 만들어 에이전트가 반복 수행하도록 하는 수단이다.
• 에이전트가 맡는 전환 작업과 GitHub Action이 맡는 지속 검증을 함께 구성해야, 최초 정리 이후에 발생하는 코드 예제의 실패도 감지할 수 있다.

✅ 액션 아이템

• 문서의 인라인 코드 예제를 실행 가능한 파일로 분리하고 CI 검증에 연결하는 데 필요한 초기 작업 범위 검토.
• docs-code-samples 스킬과 Deep Agents CLI를 활용한 코드 분리·설정·정리 코드 추가·실행 검증의 위임 가능성 검토.
• 테스트 정기 실행과 실패 시 티켓 생성을 담당할 GitHub Action 구성 검토.

❓ 열린 질문

• 문서의 인라인 코드 예제 중 실행 가능한 파일로 분리하고 CI 검증을 적용할 범위는 어디까지인가?
• docs-code-samples 스킬을 활용할 때 설정·정리 코드 추가와 실행 검증에 필요한 초기 작업은 어느 정도인가?
• GitHub Action의 테스트 정기 실행 주기와 실패 시 티켓 생성 조건은 어떻게 정할 것인가?