variet-agent/.agent/references/conventions.md

Coding Conventions

AI 에이전트는 코드를 작성하기 전 이 컨벤션을 확인합니다.

네이밍

대상	규칙	예시
변수/함수	camelCase	getUserData()
클래스	PascalCase	UserService
상수	UPPER_SNAKE_CASE	MAX_RETRY_COUNT
파일명	kebab-case	user-service.js
CSS 클래스	kebab-case	.nav-header

코드 스타일

• 들여쓰기: (2 spaces / 4 spaces / tab)
• 세미콜론: (사용 / 미사용)
• 따옴표: (single / double)
• 줄바꿈: LF (Unix style)

커밋 메시지

<type>(<scope>): <description>

type: feat|fix|refactor|test|docs|chore|ci|infra
scope: (선택)

예시:

• feat(server): add WebSocket reconnection logic
• fix(frontend): resolve button overlap on mobile
• docs: update API documentation

주석

• 한국어/영어 혼용 가능
• TODO 주석: // TODO: 설명 형식
• 복잡한 로직에는 반드시 WHY(왜) 주석 추가

에이전트 철칙 (ABSOLUTE RULES)

Caution

아래 규칙은 최우선 순위입니다. 어떤 작업보다 먼저 준수하세요. 위반 시 작업 결과가 전부 무효화됩니다.

1. 전체 구조 파악 의무

• 코드를 수정하기 전에 반드시 관련 소스 파일들을 모두 확인하세요.
• 프로그램을 단편적으로 보지 마세요. 하나의 파일을 수정할 때, 그 파일을 호출하는 곳, 호출되는 곳, 설정 파일, 프롬프트 파일 등 연관된 모든 파일을 먼저 읽으세요.
• 특히 아래 파일들은 수정 전 반드시 참조:
  • prompts/ — 에이전트 프롬프트 (도구 목록, 실행 패턴)
  • core/gemini_caller.py — 에이전트 호출 구조
  • config.py — 환경 변수 및 설정값
  • .agent/references/ — 컨벤션, known-issues, tech-stack
• ❌ "이 파일만 보고 수정" 금지
• ❌ "아마 이럴 것이다"라고 추측하여 수정 금지
• ✅ 확실하지 않으면 반드시 소스를 열어서 확인

2. 아키텍처 결정 사항 (NEVER 변경)

아래 결정은 사용자가 2026-03-14에 명시적으로 확정한 것입니다. 어떤 상황에서도 재논의하거나 대안을 제안하지 마세요.

• Gemini CLI subprocess 방식 유지: gemini_caller.py는 Gemini CLI를 asyncio.create_subprocess_exec로 호출하는 현재 방식을 영구 유지합니다.
  • ❌ Gemini SDK (google-generativeai) 전환 금지
  • ❌ Gemini REST API 직접 호출 금지
  • ❌ 위 방향성에 대한 제안/언급 금지

테스트

• 테스트 파일 위치: (예: __tests__/ 또는 *.test.js)
• 테스트 네이밍: should [expected behavior] when [condition]