Imported from taka-016/memora (AGENTS.md). Install upstream with npx skills add taka-016/memora. Copyright stays with the author.

AGENTS.md

設計資料

ユーザーストーリー: docs/user_stories.md
ユースケース図: docs/usecase_diagram.md
ER図: docs/er_diagram.md
todo: docs/todo.md

主要コマンド

flutter run - アプリケーションを実行
flutter pub get - 依存関係をインストール
flutter clean - ビルドキャッシュをクリア
dart run build_runner build - モックやコード生成を実行
./check.sh [--dart-define=MEMORA_APP_MODE=auto|online|offline] - フォーマット・解析・テストを一括実行
flutter analyze - 静的コード解析
dart format . - コードフォーマット
dart pub global run very_good_cli:very_good test - 全テストを高速に実行
flutter test test/unit/ - ユニットテストのみ実行
flutter test test/integration/ - インテグレーションテストを実行
tree lib test - アプリケーションとテストのディレクトリ構造を表示
./tools/ci/release_android_apk.sh [--dart-define=MEMORA_APP_MODE=auto|online|offline] - release APKをビルドし、memora-<version>-<mode>.apkを作成

基本ルール

常に日本語で会話すること
コメントやテスト名、ドキュメント等は日本語で記載すること
差分が発生する作業を行う場合、現在がmainブランチならAGENTS.mdの「ブランチ名」に従って新しく作業用ブランチを切り、必ずその上で進めること
全体のテストを実行するときはflutter testではなく./check.shを使用すること
AGENTS.mdの「MCP使用ルール」に従い、必要に応じてMCPを活用すること
docs/todo.mdの項目はチェックボックス形式である必要はない（通常の箇条書きでも可）
todoを作成・整理する作業自体を表すtodo項目は作成しないこと
.gitignoreで除外されているファイルは意図してリポジトリに追加しない判断をしているため、git add -fでの強制コミットや、処理を変更して対応する必要は無い

MCP使用ルール

GitHub MCP使用ルール

プルリクエスト作成時: mcp__github__create_pull_requestを使用してプルリクエストを作成する（gh pr createは使用禁止）
GitHub関連の操作: mcp__github__*で始まるMCPコマンドを使用する（gh CLIは使用禁止）

Context7 MCP使用ルール

新しいライブラリ・パッケージ使用時: 必ずmcp__context7__resolve-library-idとmcp__context7__get-library-docsで最新ドキュメントを取得する
Flutter/Dartパッケージ調査時: Context7で公式ドキュメントを確認してから実装する
pubspec.yamlに依存関係追加前: Context7で該当ライブラリの最新情報と使用方法を確認する
API使用方法が不明な場合: Context7でドキュメントを取得してから実装する

レビュー方針

レビューは日本語で記載する
コーディング規約に違反していないか確認する
設計方針、責務分離、依存方向が既存アーキテクチャと整合しているか確認する
状態管理、非同期処理、画面遷移が一貫したユーザー体験と復旧可能性を保っているか確認する
データ取得、永続化、外部データ変換が正確性・一貫性・効率性を満たしているか確認する
型安全性、不変条件、境界値への配慮により実行時エラーを防げているか確認する
UIが操作性、アクセシビリティ、表示崩れへの耐性を備えているか確認する
テストが仕様上重要な振る舞いと失敗ケースを安定して検証しているか確認する
仕様、実装、テスト、ドキュメント、変更説明の間に矛盾がないか確認する
レビュー指摘は実際の発生条件と影響を確認し、対応による複雑性と比較して対応要否を判断する
ユーザーが認識する表示・操作結果に影響せず、Firestore・SQLite等の正本データに欠損・不整合を起こさず、ハング・クラッシュ・復旧不能にならない軽微なエッジケースは、対応不要とする

アーキテクチャ

Robert C.Martinが提唱した『クリーンアーキテクチャの原則』に従います。

クリーンアーキテクチャの原則

依存関係逆転の原則: 外側の層が内側の層に依存し、内側の層は外側の層を知らない
関心の分離: 各層は明確に分離された責任を持つ
テスタビリティ: フレームワークやデータベースに依存しない設計
独立性: ビジネスルールは外部要因から独立している

コーディング規約

インデントは2スペース
文字列は原則としてシングルクォーテーション使用
constを積極的に使用する
不要なprintはコミット前に削除
ファイル名・ディレクトリ名はsnake_case
クラス名はUpperCamelCase
変数名・関数名はlowerCamelCase
定数はSCREAMING_SNAKE_CASE
コメントは最小限にし、コードを見ればわかることはコメントしないこと
Presentation層がdomain/*とinfrastructure/*を直接参照することは禁止とする
非同期処理にはasync/awaitを使用し、thenチェーンは避ける

Presentation層の状態管理・制御クラスの命名規則

新規のfamily ProviderとNotifierは原則としてRiverpodコード生成を使用し、Repository、QueryService、UseCase、外部Serviceなどの型を返すだけの単純な依存注入Providerは手書きを許容する
Riverpodコード生成のProviderはauto disposeがデフォルトであるため、既存の常時保持Providerを移行する場合は@Riverpod(keepAlive: true)を指定する
既存Providerのretry設定は、コード生成へ移行しても@Riverpod(retry: ...)で維持する
Riverpodで公開し、Viewが監視する機能状態と、その状態に関係するUseCaseの実行順序、再試行、データ更新を管理するクラスはXxxNotifierとし、状態は不変なXxxStateとして分離する
XxxNotifierはNotifier<XxxState>を基本とし、単一の非同期結果では表現しにくい部分成功や複数の操作状態をXxxStateで明示する
XxxNotifierの公開操作は、管理するStateの整合性やライフサイクルに影響する処理に限定し、Stateから独立した単純な取得や単発操作を、ViewからUseCaseを隠す目的だけで集約しない
スクロール、フォーカス、ルーティング判定など、Riverpodで監視しないUI固有の制御を担当するクラスはXxxControllerとする
複数機能にまたがる更新処理と、更新後に必要なProviderの再取得を調整するクラスはXxxMutationCoordinatorとする
Viewは状態の描画、入力、Dialog・Snackbarの実表示を担当し、NotifierはBuildContextやWidgetを参照しない
画面状態の整合性維持に必要なオーケストレーションはNotifierへ分離し、複数画面で再利用する業務フローや業務上の不変条件はApplication層のUseCaseへ配置する

ブランチ名

feature/ プレフィックスを付けて新機能のブランチ名を作成
bugfix/ プレフィックスを付けてバグ修正のブランチ名を作成
refactor/ プレフィックスを付けてリファクタリングのブランチ名を作成
docs/ プレフィックスを付けてドキュメントの更新ブランチ名を作成
test/ プレフィックスを付けてテストの追加・修正
chore/ プレフィックスを付けてその他の変更ブランチ名を作成

コミット形式

Conventional Commits仕様に従います。

基本形式

<type>(<scope>): <subject>

<body>

<footer>

必須フィールド

type: コミットの種類（必須）
subject: コミットの概要（必須、50文字以内）

オプションフィールド

scope: 変更の範囲（オプション）
body: 詳細な説明（オプション）
footer: 破壊的変更やIssue参照（オプション）

typeの種類

feat: 新機能の追加
fix: バグ修正
docs: ドキュメントの変更
style: コードの意味に影響しない変更（フォーマット、セミコロン等）
refactor: バグ修正や新機能追加以外のコード変更
perf: パフォーマンス改善
test: テストの追加・修正
build: ビルドシステムや外部依存関係の変更
ci: CI設定ファイルやスクリプトの変更
chore: その他の変更（設定ファイル、依存関係等）

scopeの例

auth: 認証関連
ui: UI関連
api: API関連
db: データベース関連
config: 設定関連

例

feat(auth): ログイン機能を追加

Google認証とメール認証に対応
セッション管理機能も含む

Closes #123

fix(ui): ボタンの表示位置を修正

docs: READMEの更新

インストール手順を追加

破壊的変更

破壊的変更がある場合は、typeの後に!を付けるか、footerにBREAKING CHANGE:を記載：

feat!: APIエンドポイントを変更

BREAKING CHANGE: /api/v1/users を /api/v2/users に変更

Lint設定

flutter_lintsパッケージを使用
analysis_options.yamlでprefer_const_constructors常に有効化、avoid_printエラー扱い

環境設定

android/local.propertiesの環境変数:

MAPS_API_KEY - 地図表示・位置検索機能に必要

環境変数の変更後はAndroidアプリを再ビルドしてください。

Firebase設定

アプリはFirestoreを使用してデータを永続化する。

設定ファイル:
- firebase_options.dart - 生成されたFirebase設定
- firebase.json - Firebaseプロジェクト設定

memora

About