openrouter-mcp AGENTS.md

AGENTS

에이전트 한국어 응답 규칙

• 기본 응답은 한국어로 작성한다.
• 사용자가 명시적으로 다른 언어를 요청하면 해당 언어로 응답한다.
• 코드, 파일 경로, 명령어, 옵션명, 고유명사는 원문 표기를 유지한다.
• 기술 용어는 가능한 한 한국어로 설명하되, 필요 시 괄호로 영문 용어를 병기한다.
• 길고 장황한 표현은 피하고, 간결하고 명확하게 답한다.

커밋 메시지 작성 규칙

• 모든 커밋 메시지는 영어로 작성한다.
• Conventional Commits 형식을 유지한다.

로컬 스킬 트리거

• build: 코드 품질 게이트(ruff/black/isort 점검 또는 자동 수정)가 필요할 때 사용한다.
• test: 테스트 스위트 실행, assurance 게이트 재현, 실패 분석, 커버리지 점검이 필요할 때 사용한다.
• deploy: npm 배포 준비/실행, 릴리스 확인, 패키지 메타데이터/placeholder 검증이 필요할 때 사용한다.
• git-worktree: 병렬 작업용 worktree 생성/정리/복구가 필요할 때 사용한다.
• security-ops: API key 저장/회전/삭제, security-audit, 보안 문서 placeholder 점검이 필요할 때 사용한다.
• mcp-config-ops: Claude Desktop/Code 설치, MCP 설정 백업/복원, config drift 점검이 필요할 때 사용한다.
• resilience-policy: 집단지성 계층의 동시성/쿼터/회로차단/cleanup 정책 변경이나 검증이 필요할 때 사용한다.
• 상세 절차는 각 스킬 문서(.agents/skills/{build,test,deploy,git-worktree,security-ops,mcp-config-ops,resilience-policy}/SKILL.md)를 단일 기준으로 따른다.

멀티에이전트 운영 지침

• 기본 원칙: 단일 에이전트+도구 구성을 먼저 극대화한다. 복잡도/성능 이득이 명확할 때만 멀티에이전트로 확장한다.
• 전환 기준 1: 프롬프트의 조건 분기가 많아져 단일 에이전트 유지보수가 어려울 때 분리한다.
• 전환 기준 2: 유사/중복 도구로 오호출이 반복될 때 역할별 에이전트로 분리한다.
• 전환 기준 3: 서로 독립적인 하위 작업을 병렬 실행해 지연 시간을 줄일 수 있을 때 확장한다.
• 패턴 선택: 중앙 통제·최종 합성·공통 guardrail/rate-limit이 필요하면 Manager 패턴을 사용하고, 메인 에이전트가 spawn_agent/send_input/wait로 서브에이전트를 조율한다.
• 패턴 선택: 트리아지 후 담당 전환이 유리하면 handoff를 사용하되, 현재 환경에서는 send_input 기반 이관(요약 포함)으로 구현한다.
• 역할 설계: 각 서브에이전트는 단일 책임으로 정의하고, 이름/설명에 호출 조건과 비호출 조건을 함께 명시한다.
• 인터페이스 설계: 가능한 경우 JSON 구조 출력으로 고정한다. spawn_agents_on_csv 사용 시 output_schema를 필수로 두고, 일반 spawn_agent 흐름은 호출 측 검증으로 계약을 강제한다.
• 컨텍스트 설계: handoff 시 전체 이력을 무조건 전달하지 말고, 요약/필터로 필요한 문맥만 전달한다.
• 규모 설계: 고정 소수 에이전트(권장 3~7, 최대 10)는 명시 열거한다. 필요 이상 동적 증식은 금지하고, 추가 풀은 목적/종료 조건을 함께 선언한다.
• 실행 설계: 의존 작업은 순차(sync), 독립 작업은 병렬(async)로 실행한다. 비동기 작업은 spawn -> wait(timeout_ms) -> 결과 병합/실패 처리 순서를 표준으로 한다.
• 품질 기준: 멀티에이전트 변경 시 eval을 선행 갱신하고 다회 실행으로 회귀를 확인한 뒤 적용한다.
• 관측 가능성: 모든 tool call/handoff는 trace 가능해야 하며, 실패 원인과 책임 에이전트를 식별할 수 있어야 한다.
• 종료/안전: wait timeout_ms, 재시도 횟수, 실패 시 human escalation 조건을 명시하지 않은 워크플로는 배포하지 않는다.
• 비용 가드: 토론형 다중 에이전트(MAD)는 기본값으로 사용하지 않고, 단순 투표/앙상블 대비 실측 이득이 있을 때만 선택적으로 활성화한다.