ARI Tools

에이전트용 설명서 agent.txt — AI 에이전트에게 설치부터 맡기는 법

새 도구를 쓰려면 먼저 설치 안내 페이지를 엽니다. 다운로드 버튼을 누르고, 스크린샷을 보며 다음, 다음, 완료를 누릅니다. 사람에게는 익숙한 길입니다.

그런데 그 도구를 실제로 쓸 주인공이 AI 에이전트라면 이야기가 다릅니다. Claude Code나 Codex 같은 에이전트에게 "이 페이지 보고 설치해 줘"라고 하면 자주 이런 일이 생깁니다.

  • 버튼과 그림 위주의 페이지라 무엇을 받아야 할지 못 찾는다.
  • OS 별 안내가 섞여 있어 엉뚱한 설치 파일을 받는다.
  • 설치는 했는데, 설치 뒤에 무엇을 해야 하는지 모른다.

이 빈틈을 메우는 것이 에이전트용 설명서입니다. 사람용 페이지와 별개로, 에이전트가 읽고 그대로 실행할 수 있는 평문 문서를 하나 더 둡니다.

왜 평문 한 장인가

에이전트가 웹을 읽는 기본 방법은 fetch(주소로 요청해 돌아온 글을 받는 방식)입니다. 그래서 설명서는 다음 조건을 갖추면 좋습니다.

  • 평문(text/plain)이다. JS 로 그려지는 페이지는 fetch 로 빈 껍데기만 읽힙니다. 평문은 한 번에 다 읽힙니다.
  • 주소가 고정돼 있다. /agent.txt 처럼 짧고 바뀌지 않는 주소면 사람이 한 줄로 건넬 수 있습니다.
  • 명령이 그대로 들어 있다. "다운로드 버튼을 누르세요"가 아니라 실제로 칠 명령이 적혀 있습니다.

비슷한 생각으로 사이트 내용을 AI 가 읽기 좋게 정리해 두는 llms.txt 라는 제안도 있습니다. 다만 llms.txt 가 사이트를 이해시키는 문서라면, 여기서 말하는 에이전트용 설명서는 실행시키는 문서입니다.

에이전트용 설명서에 들어갈 것

좋은 설명서는 사람에게 하는 말이 아니라 에이전트에게 하는 지시로 씁니다. 순서는 대개 이렇습니다.

  1. 이미 깔려 있는지 먼저 본다. 있으면 설치를 건너뛰게 합니다. 같은 걸 두 번 까는 일을 막습니다.
  2. OS 별로 절을 나눈다. "네가 도는 OS 의 절만 따른다"고 적어, 다른 OS 의 명령을 섞어 실행하지 않게 합니다.
  3. 설치 뒤 켜는 법과 확인하는 법. 떠 있는지 확인하는 명령을 같이 둡니다.
  4. 설치 뒤 무엇을 하는지. 앱이 주는 사용법을 어디서 읽는지 알려 줍니다.
  5. 지킬 것. 하면 안 되는 일을 짧게 적습니다.

사람이 끼어들 자리를 남긴다

설치를 에이전트에게 맡겨도 사람만 할 수 있는 일이 있습니다. 설명서는 이 자리를 숨기지 말고 분명히 적어야 합니다.

  • macOS 인스톨러가 관리자 비밀번호를 물을 때
  • Windows 에서 SmartScreen 경고가 뜰 때

이건 에이전트가 대신 넘길 수 없고, 넘겨서도 안 됩니다. 설명서에 "사용자에게 승인해 달라고 말하고 기다린다"고 적어 두면, 에이전트는 멈춰서 사람을 부르고 사람은 승인만 누르면 됩니다. 되돌릴 수 없는 일 앞에서 사람이 확인하는 원칙은 승인 단계 글에서 다뤘습니다.

실제로 쓰는 모습

ARI Tools 의 도구들은 모두 이 방식으로 설치합니다. 예를 들어 Agent Automation은 에이전트에게 이 한 줄을 붙여 넣으면 됩니다.

https://ariwith.me/agent.txt 읽고 그대로 설치해서, 앞으로 이 앱으로 워크플로를 관리해줘

그러면 에이전트는 이렇게 움직입니다.

  1. 평문 설명서를 읽고 자기 OS 의 설치 방법을 확인합니다.
  2. 인스톨러를 받아 실행합니다. 관리자 비밀번호나 SmartScreen 경고가 나오면 사람에게 부탁하고 기다립니다.
  3. 앱을 켜고, 로컬 채널로 붙어 워크플로를 만듭니다.

인스톨러는 앱과 함께 업데이터를 깔아, 새 버전이 나오면 앱이 스스로 갈아탑니다. 그래서 설명서에는 "zip 을 직접 풀지 않는다"는 지시도 들어 있습니다. 직접 풀면 업데이터가 빠지기 때문입니다.

ARI Browser와 스토리보드 메이커도 같은 방식입니다. 각 페이지에 에이전트에게 붙여 넣을 한 줄이 있습니다. 직접 내려받아 설치하는 길도 함께 있습니다.

정리

  • 에이전트가 쓸 도구라면 사람용 안내와 별개로 평문 설명서를 하나 둡니다.
  • 고정 주소, 평문, 실제 명령. 이 셋이면 사람은 한 줄만 건네면 됩니다.
  • 이미 깔렸는지 확인, OS 별 절, 설치 뒤 할 일, 지킬 것을 순서대로 적습니다.
  • 관리자 승인처럼 사람만 할 수 있는 자리는 숨기지 말고 "멈추고 부탁하라"고 적습니다.
#AI 에이전트#agent.txt#llms.txt#설치 자동화#Claude Code#Codex

Agent Automation — 에이전트의 할 일을 워크플로로 꺼내 두는 무료 데스크톱 앱(macOS · Windows)

쓰고 있는 에이전트에게 이 한 줄을 붙여넣으면 설치부터 에이전트가 합니다.

https://ariwith.me/agent.txt 읽고 그대로 설치해서, 앞으로 이 앱으로 워크플로를 관리해줘

Agent Automation 자세히 보기 →