Skip to content

AGENTS.md

Latest commit

 

History

History
135 lines (92 loc) · 4.69 KB

AGENTS.md

File metadata and controls

135 lines (92 loc) · 4.69 KB

에이전트 개발 규칙

이 문서는 AI 에이전트가 aka-browser 에서 코드를 작성하고 기여할 때 따라야 하는 규칙과 가이드라인을 정의합니다.

목차

프로젝트 개요

aka-browser 는 PC 용 always-on-top 사이드 브라우저입니다. Netflix·Twitter·Twitch 등을 작은 창으로 화면 위에 떠 있게 두기 위한 보조 브라우저이며, Castlabs Electron 빌드를 사용해 Widevine DRM 콘텐츠를 재생할 수 있습니다.

  • apps/browser — Electron 앱 진입점 (메인 + 렌더러 + preload)

기술 스택: Electron Castlabs / React 18 / TypeScript / Vite / TailwindCSS / Turborepo + pnpm.

코드 작성 규칙

파일 크기 제한

모든 코드 파일은 450줄 이하로 작성되어야 합니다.

  • 최대 줄 수: 450줄
  • 권장 줄 수: 300-400줄
  • 초과 시 조치: 파일이 450줄을 초과하면 기능별로 분리하여 모듈화
  • 예외: 자동 생성 파일(예: 빌드 산출물) 은 예외로 둘 수 있음

코드 품질

  • 명확성: 코드는 명확하고 이해하기 쉽게 작성
  • 재사용성: 중복 코드를 최소화하고 공통 로직은 함수로 추출
  • 타입 안정성: TypeScript 의 타입 시스템을 적극 활용 (strict 모드 유지)
  • 에러 핸들링: 모든 비동기 작업·IPC 호출·외부 API 호출에 적절한 에러 처리 구현
  • 메인·렌더러 분리: Electron 의 메인 프로세스와 렌더러 프로세스 책임을 명확히 구분하고, IPC 채널을 통해서만 통신합니다.

커밋 규칙

커밋 빈도

  • 주기적인 커밋: 논리적인 작업 단위마다 커밋
  • 작은 단위: 한 번에 하나의 기능이나 수정사항만 포함
  • 완성된 코드: 빌드 실패나 런타임 에러가 없는 상태에서만 커밋

커밋 메시지 형식 (Conventional Commits)

<type>: <설명>
  • feat — 신규 기능 / fix — 버그 수정 / docs — 문서 / chore — 빌드·의존성 / refactor — 구조 개선 / remove — 삭제 / style — 스타일 / test — 테스트

예시

feat: add multi-tab visual switcher
fix: persist always-on-top state across restarts
chore: bump electron-castlabs to 38.x

보안 및 개인정보

  • 비밀키·토큰·자격증명을 코드·테스트·문서에 포함하지 않습니다.
  • DRM 우회 시도(Widevine 키 추출, EME 우회 등) 를 코드에 절대 포함하지 않습니다.
  • 사용자 시청·검색 기록을 외부로 송출하는 텔레메트리를 무단 추가하지 않습니다.

파일 구조

aka-browser/
├── apps/
│   └── browser/
│       ├── src/
│       │   ├── main/      (Electron 메인 프로세스)
│       │   ├── renderer/  (React UI)
│       │   └── preload/   (IPC bridge)
│       ├── public/
│       └── package.json
├── package.json           (root, workspaces)
├── pnpm-workspace.yaml
├── turbo.json
└── AGENTS.md / CLAUDE.md

코드 스타일

  • 포매터: prettier (pnpm format)
  • 린터: turbo 위임 (pnpm lint)
  • 타입 체크: pnpm check-types
  • 빌드: pnpm build

PR 제출 전 위 4개 모두 통과 + Electron 앱이 로컬에서 실제로 띄워지는지 확인합니다.

문서화

  • 영어 README.md 를 우선 유지합니다.
  • 외부 기술 문서 deepwiki.com/hmmhmmhm/aka-browser 와의 동기화는 사람이 결정합니다.
  • 신규 기능 추가 시 README 의 Features 섹션을 갱신합니다.

테스트

  • IPC 채널·preload bridge 의 단위 테스트를 우선합니다.
  • 시각 회귀는 수동 검증을 기본으로 합니다.
  • DRM 콘텐츠 재생 검증은 Castlabs EVS signed 빌드에서만 가능합니다.

DRM 및 코드 서명

  • Castlabs Electron 버전 변경 금지 (자율): castlabs/electron-releases 에 의존하므로, 표준 Electron 으로의 교체나 임의 버전 변경은 자율 작업이 절대 시도하지 않습니다. 변경이 필요하면 issue 로만 환기.
  • macOS 공증(notarization) 흐름 보호: .env 의 Apple 자격증명·EVS 키 관련 코드를 변경할 때는 사람 검토 필수.
  • Widevine 의존성: Widevine CDM 통합 코드 영역은 PR 시 명시적 검토 라벨을 답니다.