우리의 문서가 스스로를 테스트하게 만든 방법

핵심 요약 (Key Takeaways)

• 대부분의 팀이 이를 수행하지 않아 콘텐츠가 오래되어지기 때문에, 문서 내 코드 샘플을 테스트하는 것은 가능합니다.
• 많은 수동 작업이 필요하지는 않습니다.
• 이를 실현하기 위해 Deep Agents CLI를 사용해 보세요.

오래된 코드 샘플은 보편적인 문서화 문제(documentation problem)입니다. 튜토리얼, API 가이드 또는 통합 예제를 배포하는 모든 팀은 종속성(dependencies)이 변경되고 API가 진화함에 따라 결국 예제가 깨지는 것을 목격하게 됩니다. 이 문제는 우리만의 고유한 문제가 아니지만, 우리의 제품—그리고 더 넓게는 AI 및 LLM 분야—가 움직이는 속도가 매우 빠르기 때문에 더욱 악화됩니다. 새로운 모델, 업데이트된 SDK, 그리고 변화하는 베스트 프랙티스(best practices)는 지난달에 작동했던 것이 오늘 작동하지 않을 수 있음을 의미합니다.

코드 샘플을 테스트 가능하게(testable) 만드는 것이 이 문제를 해결합니다. 이는 CI(지속적 통합)에서 코드를 실행하고, 올바르게 실행되는지 확인(assert)하며, 코드가 깨질 때 빌드를 실패하게 만드는 것을 의미합니다. 하지만 코드 샘플을 테스트 가능하도록 설정하는 것은 사소한 일이 아니며 초기 투자가 필요합니다. 이러한 설정 비용은 너무 압도적으로 느껴져서 프로젝트가 아예 시작되지 못할 수도 있습니다.

이 작업을 에이전트(agents)에게 위임하는 것이 완벽한 해결책입니다.

문제점: 테스트할 수 없는 불완전한 인라인 코드

인라인(inline) 코드 샘플은 작성하기 편리합니다. 코드를 테스트하고, 관련 스니펫(snippet)을 복사하여 마크다운(markdown) 파일(또는 기타 문서 파일)에 붙여넣고 배포하면 됩니다. 문제는 이것들이 정적(static)이라는 점이며, API가 변경되었을 때 해당 API를 사용하는 코드 샘플을 업데이트하는 것을 잊어버릴 수 있다는 것입니다.

이상적으로는 코드 샘플이 작동을 멈추는 시점을 알고 싶을 것입니다. 지속적 통합(CI) 테스트를 원하게 됩니다. 애플리케이션 코드에 적용되는 것과 동일한 원칙—체크 자동화, 변경 및 회귀(regressions) 감지, 무언가 깨질 때 빌드 실패—이 문서에도 적용됩니다. 즉, 코드 샘플을 테스트를 통과해야 하는 코드로서 취급하는 것입니다. 문서 내의 코드 샘플을 테스트 가능하게 만들기 위한 수동 프로세스는 다음과 같습니다:

• 인라인 코드 (inline code)를 독립된 파일로 추출합니다.
• 설정 (setup) 및 해제 (teardown) 코드를 추가합니다.
• 무엇이 코드 스니펫 (code snippet)인지 지정하기 위한 마크업 (markup)을 추가합니다.
• 도구 (tooling)를 사용하여 코드 스니펫을 추출합니다.
• 추출된 코드 스니펫을 문서 내에서 재사용 가능한 스니펫으로 포함합니다.
• CI (지속적 통합)를 사용하여 독립된 코드 스니펫을 정기적으로, 그리고 샘플이 변경될 때마다 실행합니다.

LangChain에서는 마이그레이션 워크플로 (migration workflow)를 분담하기 위해 Deep Agents CLI를 사용했습니다. 코딩은 필요하지 않았습니다.

해결책: Deep Agents + Skills: 지침을 한 번만 작성하고 나머지는 위임하세요

Deep Agents CLI는 대화할 수 있는 커맨드 라인 에이전트 (command line agent)입니다. 이 에이전트의 기능 중 하나는 스킬 (skills)의 정보를 사용하여 작업을 수행하는 것입니다. 스킬은 작업이 스킬 설명과 일치할 때 에이전트가 로드하는 재사용 가능한 지침 (instructions)입니다. 이러한 스킬은 이 작업을 수행할 수 있는 동료에게 전달하는 단계별 지침처럼 작성할 수 있습니다. 그것이 바로 우리가 한 방식입니다. 우리는 에이전트가 수행할 각 단계를 다음과 같이 작성했습니다:

코드를 독립된 파일로 이동하여 src/code-samples/{product} 아래에 제품 영역별로 정리합니다.
설정 및 해제 코드를 추가하여 코드 스니펫이 완전하게 실행 가능한 예제가 되도록 합니다.
설정된 린터 (linters)를 사용하여 코드를 린트 (lint) 합니다.
:snippet-start: 및 :snippet-end: 태그를 사용하여 코드 스니펫을 정의하는 마크업을 추가합니다. 스니펫에서 제거해야 할 코드가 있는 경우 :remove-start: 및 :remove-end:를 사용하여 제외할 수 있습니다.
테스트를 위해 코드 샘플을 실행합니다.
마크업을 기반으로 스니펫을 생성하고 생성된 파일을 문서에 포함합니다.

이것이 워크플로의 에이전트적 (agentic)인 부분이며, 그 위에 테스트를 정기적으로 실행하고 테스트 실패 시 티켓 (tickets)을 생성하는 GitHub Action이 필요합니다.

이 기술(skill)은 우리 docs 리포지토리의 .deepagents/skills/docs-code-samples/SKILL.md에 있는 숨겨진 폴더에 위치합니다. 이렇게 설정해 두면, 누구나 docs 리포지토리 내에서 Deep Agents CLI를 열고 에이전트에게 문서 내 하나 이상의 코드 샘플을 테스트 가능하게 만들라고 요청할 수 있습니다. Deep Agent에게 "streaming.mdx의 인라인 코드를 테스트 가능한 코드 샘플로 마이그레이션해줘"라고 요청하면 이 기술을 사용합니다. 에이전트는 적절한 파일을 생성하고, 적절한 태그를 추가하며, 적절한 명령어를 실행하고, 문서 파일에 코드 스니펫(code snippets)을 포함합니다.

SKILL.md

docs-code-samples 기술은 .deepagents/skills/docs-code-samples/SKILL.md에 존재합니다. 이 파일의 프론트매터(frontmatter)에는 에이전트에게 언제 이 기술을 사용해야 하는지 알려주는 description이 포함되어 있습니다:

---
name: docs-code-samples
description: LangChain 문서(MDX 파일)의 인라인 코드 샘플을 Bluehawk로 추출되어 Mintlify 스니펫으로 사용되는 외부의 테스트 가능한 코드 파일로 마이그레이션할 때 이 기술을 사용하십시오. 문서에서 코드 블록을 추출하거나, 실행 가능한 코드 샘플을 생성하거나, 스니펫 구분자(snippet delineators)를 사용하거나, Bluehawk 출력을 MDX include에 연결할 때 적용됩니다.
...

기술의 본문에는 에이전트를 위한 전체 컨텍스트(context)가 포함되어 있습니다:

• 기술을 사용해야 하는 시점
• 디렉토리 구조 및 파일 레이아웃
• 단계별 마이그레이션 지침
• 실행할 명령어 및 실행 순서
• 컨벤션 (명명 규칙, 태깅, 임포트)

전체 SKILL.md 파일은 우리의 GitHub 리포지토리에서 확인할 수 있습니다.

시작하기

이것은 여러분의 리포지토리에서 Deep Agents와 함께 기술(skills)을 사용할 수 있는 방법 중 하나의 예시일 뿐입니다.

Deep Agents CLI를 시작하려면 CLI 문서를 확인하세요.