OmniRoute/docs/i18n/ko/CLAUDE.md

CLAUDE.md (한국어)

🌐 Languages: 🇺🇸 English · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇪🇸 es · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇳 gu · 🇮🇱 he · 🇮🇳 hi · 🇭🇺 hu · 🇮🇩 id · 🇮🇩 in · 🇮🇹 it · 🇯🇵 ja · 🇮🇳 mr · 🇲🇾 ms · 🇳🇱 nl · 🇳🇴 no · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇸🇰 sk · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇻🇳 vi · 🇨🇳 zh-CN

---

이 파일은 이 리포지토리에서 코드를 작업할 때 Claude Code (claude.ai/code)에 대한 지침을 제공합니다.

빠른 시작

npm install                    # 의존성 설치 (.env.example에서 .env 자동 생성)
npm run dev                    # http://localhost:20128에서 개발 서버 실행
npm run build                  # 프로덕션 빌드 (Next.js 16 독립형)
npm run lint                   # ESLint (0 오류 예상; 경고는 기존)
npm run typecheck:core         # TypeScript 검사 (깨끗해야 함)
npm run typecheck:noimplicit:core  # 엄격 검사 (암시적 any 없음)
npm run test:coverage          # 단위 테스트 + 커버리지 게이트 (75/75/75/70 — 문장/라인/함수/브랜치)
npm run check                  # lint + 테스트 결합
npm run check:cycles           # 순환 의존성 감지

테스트 실행

# 단일 테스트 파일 (Node.js 기본 테스트 러너 — 대부분의 테스트)
node --import tsx/esm --test tests/unit/your-file.test.ts

# Vitest (MCP 서버, autoCombo, 캐시)
npm run test:vitest

# 모든 테스트 스위트
npm run test:all

전체 테스트 매트릭스는 CONTRIBUTING.md → "테스트 실행"을 참조하세요. 심층 아키텍처는 AGENTS.md를 참조하세요.

---

프로젝트 개요

OmniRoute — 통합 AI 프록시/라우터. 하나의 엔드포인트, 160개 이상의 LLM 제공자, 자동 대체.

레이어	위치	목적
API 라우트	src/app/api/v1/	Next.js 앱 라우터 — 진입점
핸들러	open-sse/handlers/	요청 처리 (채팅, 임베딩 등)
실행기	open-sse/executors/	제공자별 HTTP 디스패치
변환기	open-sse/translator/	형식 변환 (OpenAI↔Claude↔Gemini)
변환기	open-sse/transformer/	응답 API ↔ 채팅 완성
서비스	open-sse/services/	조합 라우팅, 속도 제한, 캐싱 등
데이터베이스	src/lib/db/	SQLite 도메인 모듈 (45개 이상의 파일, 55개 마이그레이션)
도메인/정책	src/domain/	정책 엔진, 비용 규칙, 대체 논리
MCP 서버	open-sse/mcp-server/	37개 도구 (30개 기본 + 3개 메모리 + 4개 기술), 3개 전송, ~13개 범위
A2A 서버	src/lib/a2a/	JSON-RPC 2.0 에이전트 프로토콜
기술	src/lib/skills/	확장 가능한 기술 프레임워크
메모리	src/lib/memory/	지속적인 대화형 메모리

모노레포: src/ (Next.js 16 앱), open-sse/ (스트리밍 엔진 작업 공간), electron/ (데스크탑 앱), tests/, bin/ (CLI 진입점).

---

요청 파이프라인

클라이언트 → /v1/chat/completions (Next.js 경로)
  → CORS → Zod 검증 → 인증? → 정책 확인 → 프롬프트 주입 방지
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → 캐시 확인 → 속도 제한 → 콤보 라우팅?
      → resolveComboTargets() → 각 타겟에 대해 handleSingleModel() 호출
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() 업스트림 → 백오프와 함께 재시도
    → 응답 번역 → SSE 스트림 또는 JSON
    → 응답 API인 경우: responsesTransformer.ts TransformStream

API 경로는 일관된 패턴을 따릅니다: 경로 → CORS 사전 비행 → Zod 본문 검증 → 선택적 인증 (extractApiKey/isValidApiKey) → API 키 정책 시행 → 핸들러 위임 (open-sse). 전역 Next.js 미들웨어는 없습니다 — 가로채기는 경로별로 특정합니다.

콤보 라우팅 (open-sse/services/combo.ts): 14가지 전략 (우선순위, 가중치, 먼저 채우기, 라운드 로빈, P2C, 랜덤, 가장 적게 사용된, 비용 최적화, 리셋 인식, 엄격한 랜덤, 자동, lkgp, 컨텍스트 최적화, 컨텍스트 릴레이). 각 타겟은 handleSingleModel()을 호출하여 handleChatCore()를 감싸고 각 타겟에 대한 오류 처리 및 회로 차단기 검사를 수행합니다. 9요소 자동 콤보 점수에 대한 내용은 docs/routing/AUTO-COMBO.md를 참조하고, 3개의 복원력 계층에 대한 내용은 docs/architecture/RESILIENCE_GUIDE.md를 참조하십시오.

---

복원력 런타임 상태

OmniRoute에는 세 가지 관련 있지만 구별되는 임시 실패 메커니즘이 있습니다. 라우팅 동작을 디버깅할 때 그 범위를 분리하십시오. 한눈에 볼 수 있는 맵은 3계층 복원력 다이어그램에서 확인할 수 있습니다 (출처: docs/diagrams/resilience-3layers.mmd).

공급자 회로 차단기

범위: 전체 공급자, 예: glm, openai, anthropic.

목적: 업스트림/서비스 수준에서 반복적으로 실패하는 공급자에게 트래픽을 보내는 것을 중지하여, 하나의 불건전한 공급자가 모든 요청을 지연시키지 않도록 합니다.

구현:

• 핵심 클래스: src/shared/utils/circuitBreaker.ts
• 채팅 게이트/실행 배선: src/sse/handlers/chatHelpers.ts, src/sse/handlers/chat.ts
• 런타임 상태 API: src/app/api/monitoring/health/route.ts
• 공유 래퍼: open-sse/services/accountFallback.ts
• 지속 상태 테이블: domain_circuit_breakers

상태:

• CLOSED: 정상 트래픽이 허용됩니다.
• OPEN: 공급자가 일시적으로 차단됨; 호출자는 공급자 회로 열림 응답을 받거나 콤보 라우팅이 다른 타겟으로 건너뜁니다.
• HALF_OPEN: 리셋 타임아웃이 경과됨; 프로브 요청을 허용합니다. 성공하면 차단기가 닫히고, 실패하면 다시 열립니다.

기본값 (open-sse/config/constants.ts):

• OAuth 공급자: 임계값 3, 리셋 타임아웃 60s.
• API 키 공급자: 임계값 5, 리셋 타임아웃 30s.
• 로컬 공급자: 임계값 2, 리셋 타임아웃 15s.

공급자 수준의 실패 상태만이 공급자 차단기를 작동시켜야 합니다:

(408, 500, 502, 503, 504);

정상 계정/키/모델 오류인 대부분의 401, 403, 또는 429 사례에 대해 전체 공급자 차단기를 작동시키지 마십시오. 이러한 오류는 일반적으로 연결 쿨다운 또는 모델 잠금에 해당합니다. 일반적인 API 키 공급자의 403은 회복 가능해야 하며, 단말 공급자/계정 오류로 분류되지 않는 한 회복 가능해야 합니다.

차단기는 지연 회복을 사용하며, 백그라운드 타이머를 사용하지 않습니다. OPEN이 만료되면 getStatus(), canExecute(), 및 getRetryAfterMs()와 같은 읽기 작업이 상태를 HALF_OPEN으로 새로 고쳐 대시보드와 콤보 후보 빌더가 만료된 공급자를 영구적으로 제외하지 않도록 합니다.

연결 쿨다운

범위: 하나의 공급자 연결/계정/키.

목적: 동일한 공급자에 대한 다른 연결이 요청을 계속 처리할 수 있도록 하면서 하나의 불량 키/계정을 일시적으로 건너뜁니다.

구현:

• 쓰기/업데이트 경로: src/sse/services/auth.ts::markAccountUnavailable()
• 계정 선택/필터링: src/sse/services/auth.ts::getProviderCredentials...
• 쿨다운 계산: open-sse/services/accountFallback.ts::checkFallbackError()
• 설정: src/lib/resilience/settings.ts

공급자 연결의 중요한 필드:

rateLimitedUntil;
testStatus: "unavailable";
lastError;
lastErrorType;
errorCode;
backoffLevel;

계정 선택 중, 연결은 다음과 같은 경우 건너뜁니다:

new Date(rateLimitedUntil).getTime() > Date.now();

쿨다운도 지연됩니다: rateLimitedUntil이 과거에 있을 때, 연결은 다시 적격이 됩니다. 성공적으로 사용되면 clearAccountError()가 testStatus, rateLimitedUntil, 오류 필드 및 backoffLevel을 지웁니다.

기본 연결 쿨다운 동작:

• OAuth 기본 쿨다운: 5s.
• API 키 기본 쿨다운: 3s.
• API 키 429는 가능한 경우 업스트림 재시도 힌트 (Retry-After, 리셋 헤더 또는 구문 분석 가능한 리셋 텍스트)를 선호해야 합니다.
• 반복 가능한 실패는 지수 백오프를 사용합니다:

baseCooldownMs * 2 ** failureIndex;

안티 썬더링 허드 가드는 동일한 연결에서 동시 실패가 쿨다운을 반복적으로 연장하거나 backoffLevel을 두 번 증가시키는 것을 방지합니다.

단말 상태는 쿨다운이 아닙니다. banned, expired, 및 credits_exhausted는 자격 증명/설정이 변경되거나 운영자가 재설정할 때까지 사용 불가능 상태로 유지되도록 설계되었습니다. 단기 쿨다운 상태로 단말 상태를 덮어쓰지 마십시오.

모델 잠금

범위: 공급자 + 연결 + 모델.

목적: 하나의 모델이 사용할 수 없거나 해당 연결에 대한 할당량이 제한된 경우 전체 연결을 비활성화하지 않도록 합니다.

예시:

• 모델별 할당량 공급자가 429를 반환하는 경우.
• 로컬 공급자가 하나의 누락된 모델에 대해 404를 반환하는 경우.
• 선택된 Grok 모드와 같은 공급자 특정 모드/모델 권한 실패.

모델 잠금은 open-sse/services/accountFallback.ts에 있으며 동일한 연결이 다른 모델을 계속 제공할 수 있도록 합니다.

디버깅 가이드

• 공급자에 대한 모든 키가 건너뛰어지면 공급자 차단기 상태와 각 연결의 rateLimitedUntil/testStatus를 검사하십시오.
• 리셋 창 후 공급자가 영구적으로 제외된 것처럼 보이면 코드가 getStatus()/canExecute() 대신 원시 state를 읽고 있는지 확인하십시오.
• 하나의 공급자 키가 실패하지만 다른 키는 작동해야 하는 경우 공급자 차단기보다 연결 쿨다운을 선호하십시오.
• 하나의 모델만 실패하는 경우 연결 쿨다운보다 모델 잠금을 선호하십시오.
• 상태가 자동으로 회복되어야 하는 경우 미래의 타임스탬프/리셋 타임아웃과 만료된 상태를 새로 고치는 읽기 경로가 있어야 합니다. 영구 상태는 수동 자격 증명 또는 구성 변경이 필요합니다.

주요 규칙

코드 스타일

• 2 공백, 세미콜론, 더블 쿼트, 100자 너비, es5 후행 쉼표 (lint-staged를 통해 Prettier로 강제)
• 임포트: 외부 → 내부 (@/, @omniroute/open-sse) → 상대
• 명명: 파일=camelCase/kebab, 컴포넌트=PascalCase, 상수=UPPER_SNAKE
• ESLint: no-eval, no-implied-eval, no-new-func = 모든 곳에서 오류; no-explicit-any = open-sse/ 및 tests/에서 경고
• TypeScript: strict: false, 타겟 ES2022, 모듈 esnext, 해상도 번들러. 명시적 타입을 선호.

데이터베이스

• 항상 src/lib/db/ 도메인 모듈을 통해 진행 — 절대 라우트나 핸들러에서 원시 SQL을 작성하지 마세요.
• 절대 src/lib/localDb.ts에 로직을 추가하지 마세요 (재수출 레이어만).
• 절대 localDb.ts에서 배럴 임포트를 하지 마세요 — 대신 특정 db/ 모듈을 임포트하세요.
• DB 싱글톤: src/lib/db/core.ts의 getDbInstance() (WAL 저널링)
• 마이그레이션: src/lib/db/migrations/ — 버전 관리된 SQL 파일, 멱등성, 트랜잭션 내에서 실행

오류 처리

• 특정 오류 유형으로 try/catch, pino 컨텍스트로 로깅
• SSE 스트림에서 오류를 삼키지 마세요 — 정리를 위해 중단 신호를 사용하세요.
• 적절한 HTTP 상태 코드 반환 (4xx/5xx)

보안

• 절대 eval(), new Function(), 또는 암시적 eval을 사용하지 마세요.
• 모든 입력을 Zod 스키마로 검증하세요.
• 자격 증명을 저장할 때 암호화하세요 (AES-256-GCM).
• 업스트림 헤더 거부 목록: src/shared/constants/upstreamHeaders.ts — 편집 시 sanitize, Zod 스키마 및 단위 테스트를 일치시키세요.
• 공개 업스트림 자격 증명 (Gemini/Antigravity/Windsurf 스타일 OAuth client_id/secret + 공개 CLI에서 추출한 Firebase 웹 키): 반드시 open-sse/utils/publicCreds.ts의 resolvePublicCred()를 통해 삽입해야 하며 — 절대 문자열 리터럴로 사용하지 마세요. 필수 패턴은 docs/security/PUBLIC_CREDS.md를 참조하세요.
• 오류 응답 (HTTP / SSE / 실행기 / MCP 핸들러): 반드시 open-sse/utils/error.ts의 buildErrorBody() 또는 sanitizeErrorMessage()를 통해 라우팅해야 하며 — 절대 원시 err.stack 또는 err.message를 응답 본문에 넣지 마세요. docs/security/ERROR_SANITIZATION.md를 참조하세요.
• 변수로부터 생성된 셸 명령: exec()/spawn()을 호출할 때 런타임 값이 필요한 스크립트는 env 옵션을 통해 전달하세요 (자동으로 셸 이스케이프됨) — 절대 신뢰할 수 없는/외부 경로를 스크립트 본문에 문자열 보간하지 마세요. 참조: src/mitm/cert/install.ts::updateNssDatabases.
• 기본적으로 보안이 강화된 라이브러리 (tldrsec/awesome-secure-defaults): 새로운 보안 민감한 표면을 추가할 때는 사용자 정의 구현보다 Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink을 선호하세요.

---

일반 수정 시나리오

새로운 제공자 추가

1. src/shared/constants/providers.ts에 등록 (로드 시 Zod 검증)
2. 사용자 정의 로직이 필요한 경우 open-sse/executors/에 실행기 추가 (기본 실행기 확장)
3. 비 OpenAI 형식인 경우 open-sse/translator/에 변환기 추가
4. OAuth 기반인 경우 src/lib/oauth/constants/oauth.ts에 OAuth 구성 추가 — 업스트림 CLI가 공개 client_id/secret을 제공하는 경우 resolvePublicCred()를 통해 삽입 (참조: docs/security/PUBLIC_CREDS.md), 절대 리터럴로 사용하지 마세요.
5. open-sse/config/providerRegistry.ts에 모델 등록
6. tests/unit/에 테스트 작성 (새로 추가한 기본값이 포함된 경우 publicCreds 형태 단언 포함)

새로운 API 경로 추가

1. src/app/api/v1/your-route/ 아래에 디렉토리 생성
2. GET/POST 핸들러가 있는 route.ts 생성
3. 패턴 따르기: CORS → Zod 본문 검증 → 선택적 인증 → 핸들러 위임
4. 핸들러는 open-sse/handlers/에 위치 (거기서 임포트, 인라인 아님)
5. 오류 응답은 open-sse/utils/error.ts의 buildErrorBody() / errorResponse()를 사용 (자동으로 정리됨 — 본문에 err.stack 또는 err.message를 원시로 넣지 마세요). docs/security/ERROR_SANITIZATION.md를 참조하세요.
6. 테스트 추가 — 오류 응답이 스택 추적을 누출하지 않는다는 단언을 포함 (예: !body.error.message.includes("at /"))

새로운 DB 모듈 추가

1. src/lib/db/yourModule.ts 생성 — ./core.ts에서 getDbInstance 임포트
2. 도메인 테이블에 대한 CRUD 함수 내보내기
3. 새로운 테이블이 필요한 경우 src/lib/db/migrations/에 마이그레이션 추가
4. src/lib/localDb.ts에서 재수출 (재수출 목록에만 추가)
5. 테스트 작성

새로운 MCP 도구 추가

1. Zod 입력 스키마 + 비동기 핸들러와 함께 open-sse/mcp-server/tools/에 도구 정의 추가
2. 도구 세트에 등록 (createMcpServer()에 의해 연결됨)
3. 적절한 범위에 할당
4. 테스트 작성 (도구 호출은 mcp_audit 테이블에 기록됨)

새로운 A2A 기술 추가

1. src/lib/a2a/skills/에 기술 생성 (이미 5개 존재: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
2. 기술은 작업 컨텍스트 (메시지, 메타데이터)를 수신 → 구조화된 결과 반환
3. src/lib/a2a/taskExecution.ts의 A2A_SKILL_HANDLERS에 등록
4. src/app/.well-known/agent.json/route.ts에 노출 (에이전트 카드)
5. tests/unit/에 테스트 작성
6. docs/frameworks/A2A-SERVER.md 기술 테이블에 문서화

새로운 클라우드 에이전트 추가

1. src/lib/cloudAgent/agents/에 CloudAgentBase를 확장하는 에이전트 클래스 생성 (이미 3개 존재: codex-cloud, devin, jules)
2. createTask, getStatus, approvePlan, sendMessage, listSources 구현
3. src/lib/cloudAgent/registry.ts에 등록
4. 필요한 경우 OAuth/자격 증명 처리 추가 (src/lib/oauth/providers/)
5. 테스트 + docs/frameworks/CLOUD_AGENT.md에 문서화

새로운 가드레일 / Eval / 기술 / 웹훅 이벤트 추가

• 가드레일: src/lib/guardrails/ → 문서: docs/security/GUARDRAILS.md
• Eval 스위트: src/lib/evals/ → 문서: docs/frameworks/EVALS.md
• 기술 (샌드박스): src/lib/skills/ → 문서: docs/frameworks/SKILLS.md
• 웹훅 이벤트: src/lib/webhookDispatcher.ts → 문서: docs/frameworks/WEBHOOKS.md

참조 문서

비트리비얼 변경 사항에 대해서는 먼저 해당 심층 분석을 읽으십시오:

영역	문서
저장소 탐색	docs/architecture/REPOSITORY_MAP.md
아키텍처	docs/architecture/ARCHITECTURE.md
엔지니어링 참조	docs/architecture/CODEBASE_DOCUMENTATION.md
자동 조합 (9-팩터 점수, 14 전략)	docs/routing/AUTO-COMBO.md
복원력 (3 가지 메커니즘)	docs/architecture/RESILIENCE_GUIDE.md
추론 재생	docs/routing/REASONING_REPLAY.md
기술 프레임워크	docs/frameworks/SKILLS.md
메모리 시스템 (FTS5 + Qdrant)	docs/frameworks/MEMORY.md
클라우드 에이전트	docs/frameworks/CLOUD_AGENT.md
가드레일 (PII / 주입 / 비전)	docs/security/GUARDRAILS.md
공개 업스트림 자격 증명 (Gemini 등)	docs/security/PUBLIC_CREDS.md
오류 메시지 정화	docs/security/ERROR_SANITIZATION.md
평가	docs/frameworks/EVALS.md
준수 / 감사	docs/security/COMPLIANCE.md
웹후크	docs/frameworks/WEBHOOKS.md
권한 부여 파이프라인	docs/architecture/AUTHZ_GUIDE.md
스텔스 (TLS / 지문)	docs/security/STEALTH_GUIDE.md
에이전트 프로토콜 (A2A / ACP / 클라우드)	docs/frameworks/AGENT_PROTOCOLS_GUIDE.md
MCP 서버	docs/frameworks/MCP-SERVER.md
A2A 서버	docs/frameworks/A2A-SERVER.md
API 참조 + OpenAPI	docs/reference/API_REFERENCE.md + docs/reference/openapi.yaml
공급자 카탈로그 (자동 생성)	docs/reference/PROVIDER_REFERENCE.md
릴리스 흐름	docs/ops/RELEASE_CHECKLIST.md

테스트

항목	명령어
단위 테스트	npm run test:unit
단일 파일	node --import tsx/esm --test tests/unit/file.test.ts
Vitest (MCP, autoCombo)	npm run test:vitest
E2E (Playwright)	npm run test:e2e
프로토콜 E2E (MCP+A2A)	npm run test:protocols:e2e
생태계	npm run test:ecosystem
커버리지 게이트	npm run test:coverage (75/75/75/70 — 문장/라인/함수/브랜치)
커버리지 보고서	npm run coverage:report

PR 규칙: src/, open-sse/, electron/, 또는 bin/의 프로덕션 코드를 변경하는 경우, 동일한 PR에 테스트를 포함하거나 업데이트해야 합니다.

테스트 레이어 선호도: 단위 테스트 먼저 → 통합 (다중 모듈 또는 DB 상태) → e2e (UI/워크플로우 전용). 버그 재현을 수정 전이나 동시에 자동화된 테스트로 인코딩합니다.

Copilot 커버리지 정책: PR이 프로덕션 코드를 변경하고 커버리지가 75% (문장/라인/함수) 미만이거나 70% (브랜치) 미만인 경우, 단순히 보고하지 말고 테스트를 추가하거나 업데이트하고, 커버리지 게이트를 다시 실행한 후 확인을 요청합니다. 실행한 명령어, 변경된 테스트 파일 및 최종 커버리지 결과를 PR 보고서에 포함합니다.

---

Git 워크플로우

# main에 직접 커밋하지 마세요
git checkout -b feat/your-feature
git commit -m "feat: 변경 사항 설명"
git push -u origin feat/your-feature

브랜치 접두사: feat/, fix/, refactor/, docs/, test/, chore/

커밋 형식 (Conventional Commits): feat(db): 회로 차단기 추가 — 범위: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills

Husky 훅:

• pre-commit: lint-staged + check-docs-sync + check:any-budget:t11
• pre-push: npm run test:unit

---

환경

• 런타임: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES 모듈
• TypeScript: 5.9+, 대상 ES2022, 모듈 esnext, 해상도 번들러
• 경로 별칭: @/* → src/, @omniroute/open-sse → open-sse/, @omniroute/open-sse/* → open-sse/*
• 기본 포트: 20128 (API + 대시보드 동일 포트)
• 데이터 디렉토리: DATA_DIR 환경 변수, 기본값 ~/.omniroute/
• 주요 환경 변수: PORT, JWT_SECRET, API_KEY_SECRET, INITIAL_PASSWORD, REQUIRE_API_KEY, APP_LOG_LEVEL
• 설정: cp .env.example .env 후 JWT_SECRET (openssl rand -base64 48) 및 API_KEY_SECRET (openssl rand -hex 32) 생성

---

엄격한 규칙

1. 비밀이나 자격 증명을 커밋하지 마세요
2. localDb.ts에 로직을 추가하지 마세요
3. eval() / new Function() / 암시적 eval을 사용하지 마세요
4. main에 직접 커밋하지 마세요
5. 라우트에 원시 SQL을 작성하지 마세요 — src/lib/db/ 모듈을 사용하세요
6. SSE 스트림에서 오류를 조용히 무시하지 마세요
7. 항상 Zod 스키마로 입력을 검증하세요
8. 프로덕션 코드를 변경할 때 항상 테스트를 포함하세요
9. 커버리지는 ≥75% (문장, 라인, 함수) / ≥70% (브랜치)를 유지해야 합니다. 현재 측정: ~82%.
10. 명시적인 운영자 승인 없이 Husky 훅을 우회하지 마세요 (--no-verify, --no-gpg-sign).
11. 공개 업스트림 OAuth client_id/secret 또는 Firebase Web 키를 문자열 리터럴로 포함하지 마세요 — 항상 resolvePublicCred()를 통해 진행하세요 (open-sse/utils/publicCreds.ts). docs/security/PUBLIC_CREDS.md를 참조하세요.
12. HTTP / SSE / 실행자 응답에서 원시 err.stack / err.message를 반환하지 마세요 — 항상 buildErrorBody() 또는 sanitizeErrorMessage()를 통해 라우팅하세요 (open-sse/utils/error.ts). docs/security/ERROR_SANITIZATION.md를 참조하세요.
13. exec()/spawn()에 전달되는 셸 스크립트에 외부 경로 또는 런타임 값을 문자열 보간하지 마세요 — 대신 env 옵션을 통해 전달하세요. 참조: src/mitm/cert/install.ts::updateNssDatabases.
14. CodeQL / 비밀 스캔 경고를 무시하지 마세요 (a) 먼저 위의 패턴 문서를 확인하여 도우미가 적용되는지 확인하고, (b) 무시 댓글에 기술적 정당성을 기록하세요. 선례: js/stack-trace-exposure는 이미 sanitizeErrorMessage()를 통해 라우팅되는 호출 지점에서 발생하며, 이는 알려진 CodeQL 제한입니다 (사용자 정의 정리기가 인식되지 않음) — docs/security/ERROR_SANITIZATION.md를 참조하여 false positive로 무시하세요.
15. 자식 프로세스를 생성하는 경로 (/api/mcp/, /api/cli-tools/runtime/)를 src/server/authz/routeGuard.ts에서 isLocalOnlyPath() 분류 없이 노출하지 마세요. 루프백 강제 적용은 모든 인증 검사 전에 무조건 발생합니다 — 터널을 통해 유출된 JWT는 프로세스 생성을 트리거할 수 없습니다. docs/security/ROUTE_GUARD_TIERS.md를 참조하세요.
16. AI 어시스턴트, LLM 또는 자동화 계정을 인정하는 Co-Authored-By 트레일러를 커밋 메시지에 절대 포함하지 마세요 (예: "Claude", "GPT", "Copilot", "Bot"을 포함한 이름; anthropic.com / openai.com / 봇 소유 noreply.github.com 주소의 이메일). 이러한 트레일러는 GitHub에서 커밋 귀속을 봇 계정으로 라우팅하여 PR 기록에서 실제 작성자 (diegosouzapw)를 숨깁니다. 인간 협력자 — upstream PR 작성자와 OmniRoute로 이식되는 issue 보고자 포함 — 은 표준 Co-authored-by: Name <email> 트레일러로 인정될 수 있고 인정되어야 합니다; upstream-port 워크플로 (/port-upstream-features, /port-upstream-issues)는 이에 의존합니다.