dari-docs

가장 멍청한 에이전트라도 배포할 수 있을 만큼 완벽한 문서를 만드세요.

dari-docs는 여러분의 문서가 에이전트(Agent)가 사용하기에 충분히 명확한지 테스트하기 위한 CLI(Command Line Interface)입니다. 이 도구는 문서를 시뮬레이션된 개발자 에이전트에게 전달하고, 실제 작업을 완료하도록 요청하며, 에이전트가 어디에서 막히는지 보고합니다. 또한 해당 피드백을 바탕으로 제안된 문서 수정 사항을 생성할 수 있습니다.

문서 품질을 "이해할 수 있을 것 같다"는 수준에서 "에이전트가 실제로 작업을 완료할 수 있다"는 수준으로 끌어올리는 데 사용하세요.

왜 dari-docs인가요?

과거에 좋은 문서란 "개발자가 결국에는 이해할 수 있는 것"을 의미했습니다. 하지만 이제 그것만으로는 충분하지 않습니다.

독자가 에이전트일 때, 모호함(Ambiguity)은 측정 가능한 요소가 됩니다. 일관성 없는 용어, 숨겨진 가정, 흩어진 컨텍스트(Context), 누락된 설정 단계 등은 에이전트가 작업을 실패하거나 문서의 의미를 추론하려다 컨텍스트를 낭비할 확률을 모두 높입니다.

dari-docs는 에이전트가 읽기 좋은 문서(Agent-readable documentation)를 위한 반복 가능한 피드백 루프를 제공합니다: 작업을 정의하고, 시뮬레이션된 사용자를 실행하며, 실패 사례를 조사하고, 선택적으로 수정된 문서를 가져옵니다.

주요 기능

• 시뮬레이션된 개발자로 문서 테스트 — 에이전트가 제공된 문서만을 사용하여 구체적인 작업을 시도합니다.
• 작업을 방해하는 모호함 발견 — 누락된 컨텍스트, 불분명한 설정, 일관성 없는 용어, 에이전트가 추측해야 했던 지점들을 보고합니다.
• 수정 제안 생성 — optimize 명령어를 통해 테스터의 피드백을 로컬에서 검토할 수 있는 수정된 문서로 변환합니다.
• 관리형 또는 자체 관리형 실행 — 호스팅된 dari.dev Docs 서비스를 사용하거나, 자체 dari.dev 조직 내의 에이전트를 대상으로 실행할 수 있습니다.
• 일반적인 에이전트 프로젝트 사용 — 테스터와 에디터는 단순히 프롬프트(Prompt), 기술(Skill), 설정 스크립트 및 dari.yml 매니페스트(Manifest)로 구성된 폴더일 뿐입니다.

설치

설치 스크립트를 사용하여 최신 네이티브 macOS/Linux dari-docs 바이너리를 설치한 다음, CLI를 사용할 수 있는지 확인하세요:

curl -fsSL https://raw.githubusercontent.com/mupt-ai/dari-docs/main/install.sh | bash
dari-docs --help

빠른 시작 (Quickstart)

Managed mode (관리형 모드)는 호스팅된 dari.dev Docs 서비스와 별도의 dari.dev Docs 크레딧 잔액을 사용합니다. 신규 계정에는 5달러 상당의 무료 크레딧이 제공됩니다.

문서 저장소(docs repo)에서 다음을 실행하세요:

dari-docs auth login

문서 체크(docs check)를 실행합니다:

dari-docs check . \
  --managed \
  --task "Install the SDK and make a first API call"

이 명령은 관리형 실행(managed run)을 제출하고 실행 ID(run ID)를 출력합니다. 동일한 명령에서 완료될 때까지 기다리려면 --wait를 추가하세요.

제안된 문서 수정 사항을 생성합니다:

dari-docs optimize . \
  --managed \
  --wait \
...

--wait를 사용하면, 수정된 파일들이 기존 저장소를 변경하지 않고 .dari-docs/updated/ 디렉토리로 다운로드됩니다. 해당 폴더를 검토한 후 준비가 되면 변경 사항을 저장소에 복사하세요.

작동 원리 (How it works)

1. dari-docs를 문서 디렉토리 또는 공개 문서 URL로 지정하고 하나 이상의 작업(task)을 부여합니다.
2. CLI는 로컬 문서를 번들링하거나, 체크 에이전트(checker agents)가 인터넷 접속을 통해 검사할 수 있도록 공개 문서 URL을 전달한 뒤, 호스팅된 Dari Docs 에이전트에게 실행을 제출합니다.
3. 테스터 에이전트(Tester agents)가 작업을 완료하려고 시도하며, 문서가 진행을 방해한 지점을 보고합니다.
4. dari-docs runs wait, dari-docs runs download를 사용하거나 --wait를 전달하여 로컬 실행 아티팩트(run artifacts)를 수집합니다.
5. optimize를 실행하면, 에디터 에이전트(editor agent)가 문서 변경 사항을 제안합니다.
6. 제안된 수정 사항은 검토를 위해 .dari-docs/updated/로 다운로드할 수 있습니다.

시뮬레이션된 사용자들은 일반적인 dari.dev 에이전트입니다. Managed mode는 호스팅된 Dari Docs 테스터 및 에디터 에이전트를 자동으로 사용합니다. 에이전트 프롬프트(prompts), 기술(skills), 설정 스크립트(setup scripts) 또는 dari.yml을 커스텀하고 싶다면, self-managed mode (자체 관리 모드)를 사용하세요.

Managed vs self-managed

대부분의 사용자는 managed mode로 시작하는 것이 좋습니다.

Documentation (문서)

• Managed mode 및 결제 (billing)
• GitHub Actions
• 작업 파일 및 반복 검사 (tasks)
• 번들 선택 (bundle selection)
• 실시간 검증 비밀값 (live verification secrets)
• 에이전트 사용자 정의 (agent customization)
• 자체 관리 사용 (self-managed usage)
• 로컬 개발 (local development)