pianisticism

Imported from YusukeIwaki/pianisticism (AGENTS.md). Install upstream with npx skills add YusukeIwaki/pianisticism. Copyright stays with the author.

AGENTS.md — Pianisticism

このリポジトリで作業するエージェント向けの起点ドキュメント。まずこれを読み、必要に応じてリンク先へ。

これは何か

目標と現状のギャップを埋める AIピアノレッスンアプリのプロトタイプ（Android / Jetpack Compose / パッケージ ai.pianisticism / Pixel 10 想定）。

正誤判定ではなく、教師が「ここを言いたい」と思う点（= 改善要求点）を、崩れ・音楽性・工夫の余地の3観点で示し、対話で直し方まで返すことを狙う。入力〜評価は実装済み: マイク（AudioRecord）→ 音響解析（オンセット/ピッチ/拍格子 → 特徴量）→ 学習済みモデル（:mltuning で学習）が改善要求点を推定する。AI 対話（AiCoach/JournalWriter）と会話音声（VoiceSession）はモックのままで、インターフェースの裏に隠れており個別に本物へ差し替えられる。

設計思想・概念モデル・各ユースケース（初期設定 / 計画生成 / 自主練習 / レッスン）は Docusaurus ドキュメント docs/docs/ が一次情報。概念を知りたいときはそちらを読む（intro.md → usecases/* → architecture.md → improvement-requests.md）。

リポジトリ構成

README.md                                            プロジェクト概要
androidapp/                                           Gradle プロジェクト（3 モジュール）
  ├ app/                                             Android アプリ（UI・マイク入力・モック）
  ├ core/                                            純 Kotlin/JVM: domain + 音響解析(analysis) + 演奏シンセサイザ(synth)
  ├ mltuning/                                        ML パイプライン: データセット収集→学習→モデル単体評価
docs/                                                Docusaurus 設計ドキュメント（概念の一次情報）
AGENTS.md                                            ← これ
AGENT_DOCS/                                          エージェント向けの細部
  ├ build-and-test.md                                ビルド/テスト・環境変数・ツールチェイン・gotcha
  ├ codebase-map.md                                  コードの所在・5つの差し替え seam・変更の入口
  ├ self-practice-positioning.md                     自主練習を自動練習日誌として扱う設計メモ
  └ source/                                          構想・調査の原典アーカイブ（下記「構想・調査の原典」参照）

構想・調査の原典（AGENT_DOCS/source/）

当初リポジトリ直下にあったユーザ提供の構想・調査資料（ABSTRACT.md / deep-research-report.md / gainen.png）は削除済み。その内容をテーマ別に分割して AGENT_DOCS/source/ に保全してある。実装の意思決定の背景・根拠はこれらを参照する。

注意: これらは構想・調査当時の一次資料で、現行の設計・用語が優先される。主な差分: 「故障点(fault)」→ 改善要求点（崩れ/音楽性/工夫, ImprovementRequestTarget） に再整理（→ docs/docs/improvement-requests.md）／当初は MIDI ファースト案だったが現行の想定入力はマイクのみ／調査は iOS 推奨だったが本プロジェクトは Android 実装。

すぐ作業を始めるには

1. ビルド/テストの手順・環境変数・固定バージョン・落とし穴 → AGENT_DOCS/build-and-test.md を読む。要点だけ:

   export JAVA_HOME=/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home
   export ANDROID_HOME=/opt/homebrew/share/android-commandlinetools
   cd androidapp && ./gradlew :app:testDebugUnitTest

2. どのファイルを触れば何が変わるか・アーキテクチャ → AGENT_DOCS/codebase-map.md。

守るべき規約（最重要のみ）

• 検証は JVM ユニットテスト（:app:testDebugUnitTest / :core:test / :mltuning:test）。adb install/端末起動で確認しない（明示依頼時を除く）。
• 実装もモックもインターフェースの裏に保つ（MusicPerformanceInputSource / FeatureExtractor / Evaluator / AiCoach / VoiceSession）。差し替えの単一窓口は data/AppGraph.kt。マイク不可・モデル欠落時はモックへフォールバックし、アプリは止めない。
• Evaluator モデルを再学習したら（:mltuning:trainModel）、必ず :mltuning:test（ホールドアウト単体評価）を通す。特徴量の定義（core/analysis）を変えたら再学習が必要。
• 状態は ViewModel + StateFlow に保持し、画面回転で壊れないこと（configChanges + 状態の hoist 済み）。ViewModel は Android 非依存に保つ。
• 入力は MIDI ではなくマイクのみ（演奏を聴く）。音声対話はアプリ内 TTS + SpeechRecognizer（将来 Gemini Live に差し替え）。
• ツールチェイン/依存バージョンは固定（理由は build-and-test.md）。安易に上げない。
• ドキュメントのページを増減・改名したら docs/sidebars.ts と docusaurus.config.ts のリンクも直す（onBrokenLinks: throw）。

変更後にやること

• アプリを変えたら cd androidapp && ./gradlew :app:assembleDebug :app:testDebugUnitTest を通す。core/（domain/analysis/synth）を触ったら :core:test、モデルや学習パイプラインを触ったら :mltuning:test も通す。
• 概念・仕様を変えたら docs/ の該当ページも更新し、cd docs && npm run build を exit 0 で通す。