150 Lines of Apologies Removed

개요

AI 에이전트가 Linear 이슈 관리에 사용하는 246줄의 명령 파일에서 150줄이 도구의 한계를 보완하기 위한 복잡한 우회 코드로 구성되어 있었으나, 이를 불필요하게 만드는 Rust 기반 CLI 도구 'lql'을 개발함으로써 해당 라인들을 제거한 경험을 공유합니다.

주요 내용

• AI 에이전트를 위한 Linear 이슈 관리 명령어 파일은 246줄로, 이 중 150줄은 CLI 도구의 기능 부족(예: --project 미지원, 검색 기능 부재, API 대체 사용 등)을 해결하기 위한 하드코딩된 UUID, curl 기반 GraphQL 쿼리, "지원하지 않음" 메모 등의 우회 코드로 이루어져 있었습니다.
• 이러한 우회 코드는 도구 자체의 결함을 문서화하는 것으로, AI 에이전트는 이러한 지침을 직접적으로 따르기보다 가장 논리적인 경로를 선택하려 하기 때문에 오히려 오작동의 원인이 되었습니다.
• 문제 해결은 더 나은 지침 작성이 아니라, AI 에이전트가 Linear와 상호작용할 때 복잡한 설명 없이도 자연스럽게 사용할 수 있도록 설계된 Rust 기반 CLI 도구 'lql'을 개발하는 것이었습니다.
• 'lql'은 "잘못된 경로는 금지되는 것이 아니라 불가능해야 한다"는 설계 철학을 기반으로, --project와 같이 자연스러운 입력을 지원하고, UUID 자동 해석, 네이티브 검색 및 프로젝트 연관 기능 제공, 오류 발생 시 대체 경로 제공 등으로 기존의 150줄 우회 코드를 모두 제거했습니다.
• 이러한 도구 개선을 통해 기존의 '생존 가이드'와 같았던 명령어 파일은 단순한 기능 설명만 남게 되었으며, 이는 도구가 견고하고 포용적일 때 복잡한 설명이 필요 없다는 원칙을 보여줍니다.
• 일반적인 패턴은 인터페이스가 불편한 도구에 대해 상세한 지침을 작성하고, 이것이 복잡한 설명서가 되며, 사용자가 이를 무시하여 문제가 발생하고, 더 많은 지침을 추가하는 악순환이 반복되는 것입니다. 이 문제를 해결하는 열쇠는 지침 개선이 아닌 도구 자체를 수정하는 데 있습니다.

시사점

도구가 견고하고 포용적일수록 관련 설명서는 자동적으로 간결해지며, AI 에이전트와 같은 사용자는 복잡한 지침을 해석하는 데서 오는 오류 가능성이 줄어들어 효율성이 증대됩니다. 사용자가 자연스럽게 입력할 수 있는 방식을 도구가 지원하도록 개선하는 것이 핵심입니다.