2026-07-08 12:03:57 +09:00
|
|
|
# AGENTS.md
|
|
|
|
|
|
|
|
|
|
## 프로젝트 정체
|
|
|
|
|
|
2026-07-08 17:33:20 +09:00
|
|
|
- Music Assistant 클라이언트 프로젝트. 서버(Music Assistant)와 연동하는 크로스플랫폼 앱.
|
|
|
|
|
- 타겟 플랫폼: iOS, Android, macOS, Web (4개 환경).
|
|
|
|
|
- 핵심 기능: 백그라운드 재생, 잠금화면/제어센터 컨트롤, Music Assistant 서버 연동.
|
|
|
|
|
|
|
|
|
|
## 기술 스택
|
|
|
|
|
|
|
|
|
|
- Kotlin Multiplatform (KMP) + Compose Multiplatform.
|
|
|
|
|
- 공유 로직(Music Assistant API/WebSocket 클라이언트, 상태 관리, 데이터 레이어)은 `commonMain`에 배치.
|
|
|
|
|
- UI는 Compose Multiplatform으로 iOS/Android/macOS/Web을 단일 코드베이스로 커버.
|
|
|
|
|
- Web 타겟: Kotlin/Wasm + Compose Multiplatform Web.
|
|
|
|
|
- 실험→안정화 단계이므로 빌드 파이프라인과 브라우저 호환성을 별도 검증 필요.
|
|
|
|
|
- Web 오디오는 HTML5 Audio + Media Session API 사용. iOS Safari의 백그라운드/잠금화면 제약은 Web 타겟에 그대로 적용됨(별도 문서로 보관).
|
|
|
|
|
- 오디오 재생: KMP `expect/actual`로 플랫폼별 구현 분리(공통 오디오 라이브러리 없음).
|
|
|
|
|
- Android: Media3/ExoPlayer + MediaSession.
|
|
|
|
|
- iOS: AVAudioSession + AVPlayer + MPNowPlayingInfoCenter.
|
|
|
|
|
- macOS: AVAudioPlayer + MPNowPlayingInfoCenter.
|
|
|
|
|
- Web: HTML5 Audio + Media Session API.
|
2026-07-08 12:03:57 +09:00
|
|
|
|
|
|
|
|
## 진실의 원천 계약
|
|
|
|
|
|
|
|
|
|
- 사용자와의 논의 내용은 이 저장소를 "유일한 진실의 원천"으로 문서화한다. 산출물은 코드·문서·설정 파일로 저장하여 대화 기록에만 의존하지 않는다.
|
|
|
|
|
- 논의 결과 기존 진실을 변경해야 하면, 모순이 발생하지 않도록 연관된 모든 문서·설정·코드를 함께 갱신한다. 한쪽만 고치고 다른 쪽을 방치하지 않는다.
|
|
|
|
|
- 이 저장소는 git 프로젝트이므로 의미 있는 단위마다 주기적으로 커밋한다.
|
|
|
|
|
|
|
|
|
|
## 커밋 컨벤션
|
|
|
|
|
|
|
|
|
|
표준 conventional commits를 유지하되 메시지는 한국어로 작성.
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
[접두어]: [요약된 내용]
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
- 본문(설명/옵션)이 필요하면 제목 다음 줄에 빈 줄 하나 두고 작성.
|
|
|
|
|
- 접두어 예: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `build`, `ci`, `perf`, `revert`.
|
|
|
|
|
- 한국어 요약은 명사구 또는 문장형으로 간결하게.
|
|
|
|
|
|
|
|
|
|
## 도구 환경
|
|
|
|
|
|
|
|
|
|
- Node 24, pnpm 11, bun 1.3, git 2.53 사용 가능.
|
2026-07-08 17:33:20 +09:00
|
|
|
- Kotlin/Gradle 기반 KMP 프로젝트. JDK 버전과 Gradle 버전은 매니페스트 생성 시점에 확정하여 여기에 기록할 것.
|
2026-07-08 12:03:57 +09:00
|
|
|
- 패키지 매니페스트가 없는 초기 상태이므로 아직 빌드/테스트/린트 명령은 확정되지 않음. 매니페스트가 생성되면 여기에 정확한 명령을 기록할 것.
|
|
|
|
|
- 명령 순서가 중요해지면(예: `lint -> typecheck -> test`) 그 순서를 명시할 것.
|
|
|
|
|
|
|
|
|
|
## 작업 주의사항
|
|
|
|
|
|
|
|
|
|
- 빈 저장소에서 시작하므로, 파일을 생성하기 전에 먼저 기존 구조를 확인한다. 추측으로 파일 트리를 만들지 않는다.
|
|
|
|
|
- 설치 스크립트·빌드 명령·환경 변수 로딩 등 비자명한 설정이 생기면 이 파일에 즉시 기록한다.
|
|
|
|
|
- 일반 언어/프레임워크 관례, 자명한 사실, 검증 불가능한 추측은 여기에 적지 않는다.
|
