8가지 builtin 에이전트로 3-tier 매칭 시스템 구축하는 아키텍처 패턴

AI 에이전트 카탈로그 시스템을 처음부터 설계하면서 8개의 builtin 에이전트와 3단계 매칭 알고리즘을 구현했다. 이 글에서는 복잡한 시스템을 AI와 함께 단계별로 쌓아가는 방법과, 타입 안정성을 유지하면서 에이전트 파서를 구조화하는 패턴을 다룬다. 배경: 무엇을 만들고 있는가 agentochester는 여러 AI 에이전트를 관리하고 사용자의 task에 맞는 에이전트를 자동으로 매칭해주는 시스템이다. markdown으로 정의된 에이전트를 YAML 형태로 파싱하고, 3단계 매칭 알고리즘으로 최적의 에이전트를 찾아준다. 이번 작업의 목표는 core 시스템 구축이었다. 타입 정의부터 파서, 매칭 엔진, 그리고 Next.js 대시보드까지 한번에 만들어야 했다. 처음부터 끝까지 AI와 pair programming으로 진행했고, 특히 복잡한 타입 시스템과 테스트 케이스 작성에서 효과적인 프롬프팅 패턴을 발견했다. 타입 우선 설계로 AI와 함께 아키텍처 잡기 복잡한 시스템을 AI와 함께 만들 때 가장 중요한 것은 타입 정의를 먼저 확정하는 것이다. 타입이 명확해야 AI가 일관된 코드를 생성한다. 이 프로젝트에서 핵심 타입들을 정의할 때 사용한 프롬프트 패턴이다: "AI 에이전트 카탈로그 시스템의 core 타입을 정의해야 한다. 요구사항: 1) AgentDefinition은 name, version, description, capabilities, constraints를 포함 2) Task는 description, domain, priority를 가짐 3) 매칭 결과는 score와 reason을 포함 4) 모든 타입은 Zod로 validation 가능해야 함. TypeScript interface와 Zod schema를 함께 작성해줘." 이렇게 쓰면 안 된다: "에이전트 타입 만들어줘" 핵심은 제약 조건을 구체적으로 명시하는 것이다. "Zod로 validation 가능해야 함"이라는 조건을 주면 AI가 runtime validation까지 고려해서 타입을 설계한다. 결