Make Your Weekend Agent List Unknowns First

개요

This article introduces a Python tool called an "assumption gate" designed to prevent AI agents from inventing unstated systems when generating implementation plans from GitHub issues.

주요 내용

• 문제점: AI 에이전트가 GitHub 이슈 텍스트를 바탕으로 실행 가능한 계획을 생성할 때, 이슈에 명시되지 않은 Kafka, Redis, 새로운 인증 서비스와 같은 시스템을 자신 있게 추가하여 실제 환경과 맞지 않는 계획을 제안하는 경우가 많습니다. 이는 시간과 예산을 낭비하게 만들며, 주말 프로젝트와 같은 소규모 프로젝트에 특히 치명적입니다.
• Assumption Gate 솔루션: 본 기사에서 제시하는 "assumption gate"는 이 문제를 해결하기 위한 간단한 도구입니다. 이 도구는 이슈 텍스트를 입력받아 명시된 사실, 알 수 없는 점, 그리고 제안된 계획을 추출합니다. 핵심 기능은 AI가 계획을 생성하기 전에 이슈에 명시된 시스템 목록을 기반으로 새로운 시스템을 도입하는 것을 차단하는 것입니다.
• 구현 방식:
• stdin 도구: Python으로 작성된 명령줄 도구로, GitHub 이슈 텍스트를 입력받습니다.
• 명시된 시스템 추출: 정규 표현식과 미리 정의된 시스템 힌트 목록(e.g., "redis", "kafka", "postgres")을 사용하여 이슈 텍스트에서 명시적으로 언급된 시스템을 추출합니다. 또한, "Service", "Queue", "Store", "API"와 같은 접미사가 붙은 명명된 서비스를 식별합니다.
• 스키마 강제: AI 모델이 생성하는 결과물에 "facts", "unknowns", "steps", "systems"의 네 가지 키를 포함하도록 강제하는 JSON 스키마를 사용합니다.
• 모의 실행 (Mock Run): API 키나 서버 없이도 도구의 작동 방식을 확인할 수 있도록 Kafka를 의도적으로 추가하는 모의 실행 기능을 제공하여, 잘못된 계획이 감지될 때의 동작을 미리 확인할 수 있습니다.
• 실시간 실행 (Live Call): 환경 변수(LLM\_URL, LLM\_MODEL)를 통해 접근 가능한 LLM API를 호출하여 실제 계획을 생성합니다. API 키는 환경 변수로 관리되며 Git에 노출되지 않습니다.
• 검증 (Scoring): 생성된 계획에 포함된 시스템 목록을 이슈에서 추출된 명시된 시스템 목록과 비교합니다. "email" 및 "http"와 같이 거의 모든 이슈에 암묵적으로 포함되는 시스템은 허용 목록에 포함시키고, 그 외의 새로운 시스템이 발견되면 실패(fail)로 처리합니다.
• JSON 보고서 및 종료 코드: 검증 결과를 JSON 형식으로 표준 출력하고, 새로운 시스템이 발견되면 종료 코드 1을, 모든 시스템이 명시적이거나 허용된 경우 종료 코드 0을 반환합니다.
• 제외된 기능 (Scope Cuts): GitHub API 호출, 히스토리 저장, 모델 랭킹, 임베딩 추가, 웹 UI, 다중 에이전트 체인 등은 복잡성을 줄이기 위해 의도적으로 제외되었습니다. 이는 "플랫폼"이 아닌 "게이트"로서의 핵심 기능에 집중하기 위함입니다.
• 사용법: 스크립트를 실행 파일로 만들고, sample_issue.md와 같은 텍스트 파일로 GitHub 이슈 내용을 저장한 후, --mock 옵션으로 모의 실행을 먼저 수행하여 실패 경로를 확인하고, 이후 실제 LLM API를 사용하여 계획을 생성합니다.

시사점

이 도구는 AI 기반 자동화 계획 생성 시 발생할 수 있는 "환각" 현상으로 인한 비현실적인 시스템 도입을 방지하는 실용적인 방법을 제공합니다. 명확한 규칙과 엄격한 검증 절차를 통해, AI가 제안하는 계획이 현재 프로젝트 환경에 부합하는지 빠르고 효과적으로 확인할 수 있어 개발자의 시간을 절약하고 불필요한 작업을 줄이는 데 기여할 수 있습니다.