Imported from YusukeIwaki/pianisticism (
AGENTS.md). Install upstream withnpx 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/ に保全してある。実装の意思決定の背景・根拠はこれらを参照する。
| ファイル | 出典 | 内容 |
|---|---|---|
source/concept-model.md |
gainen.png | 概念モデル図(5ステージの反復学習ループ+アルゴリズム外殻) |
source/product-vision.md |
ABSTRACT.md | ポジショニング・勝ち筋・MVP案・iOS/Android の当初見解・参考URL |
source/competitor-landscape.md |
deep-research-report.md | エグゼクティブサマリー・既存プロダクト比較表 |
source/realtime-implementation.md |
deep-research-report.md | リアルタイム実装フレームワーク・推奨スタック・推奨アーキテクチャ |
source/differentiation.md |
deep-research-report.md | 差別化戦略・故障点ベース設計(→改善要求点へ発展) |
source/platform-and-roadmap.md |
deep-research-report.md | プラットフォーム選定・MVPロードマップ・未確定事項 |
注意: これらは構想・調査当時の一次資料で、現行の設計・用語が優先される。主な差分: 「故障点(fault)」→ 改善要求点(崩れ/音楽性/工夫,
ImprovementRequestTarget) に再整理(→docs/docs/improvement-requests.md)/当初は MIDI ファースト案だったが現行の想定入力はマイクのみ/調査は iOS 推奨だったが本プロジェクトは Android 実装。
すぐ作業を始めるには
- ビルド/テストの手順・環境変数・固定バージョン・落とし穴 →
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 - どのファイルを触れば何が変わるか・アーキテクチャ →
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 で通す。
