operate.txt 소개: SaaS 제품 탐색을 위한 AI 에이전트용 YAML 사양

개발자가 웹 애플리케이션과 AI 에이전트가 상호작용하는 방법을 문서화하기 위한 사양인 operate.txt를 만들었습니다. 이 파일은 SaaS 제품을 탐색하기 위해 Claude의 컴퓨터 사용 기능을 사용할 때 AI 에이전트가 로딩 화면이 고장난 기능을 나타내는지 반복적으로 질문했던 문제를 해결합니다.

문제와 해결책

Claude Code + 컴퓨터 사용을 통해 BrandyBee(SaaS 제품)를 초보 사용자로서 탐색하는 동안, 개발자는 Claude가 어려움을 겪는 구체적인 문제점을 파악했습니다:

• 90-120초가 걸리는 브랜드 분석 중, Claude가 28% 진행 시 "이건 로딩 상태인가요, 아니면 뭔가 문제가 있는 건가요?"라고 물음
• 확인 UI 없이 유료 API 호출을 트리거하는 "승인" 버튼
• 국가를 선택한 후에만 채워지는 언어 드롭다운
• 정지된 것처럼 보이는 2-5분 걸리는 비동기 프로세스

매번 응답은 "아니요, 그건 정상입니다. 그냥 기다리세요."였습니다. 이로 인해 크롤러를 위한 robots.txt나 검색 엔진을 위한 sitemap.xml과 동등하지만, 특히 제품을 운영하는 AI 에이전트를 위한 operate.txt가 만들어졌습니다.

operate.txt 사양

operate.txt 파일은 yourdomain.com/operate.txt에 호스팅된 YAML 파일로 다음을 문서화합니다:

• 각 화면이 무엇인지
• 로딩 상태가 어떻게 보이고 얼마나 걸리는지
• 어떤 작업이 되돌릴 수 없는지
• 일반적인 작업에 대한 단계별 경로
• 에이전트가 절대 해서는 안 되는 것

가장 유용한 섹션은 async_actions로, "이 프로세스는 90-120초가 걸리며, 새로 고침하지 말고, 다른 곳으로 이동하지 말고, 여기에는 거치는 단계가 있습니다."와 같은 세부사항을 에이전트에게 알려줍니다.

제작 과정과 예시

개발자는 자신의 SaaS, 이커머스 템플릿, SaaS 대시보드 템플릿을 포함한 실제 예시와 함께 이 사양을 오픈소스로 공개했습니다: https://github.com/serdem1/operate.txt.

제작 과정은 Claude가 제품을 탐색하도록 하고, 어디에서 망설이는지 관찰한 다음, Claude가 operate.txt 파일을 초안 작성하도록 하는 것을 포함합니다. 개발자는 Claude가 잘못 이해한 부분을 수정하여, AI가 격차를 발견하고 사람이 채우는 피드백 루프를 만듭니다.