diff --git a/.claude/rules/coding-style.md b/.claude/rules/coding-style.md index 598e8eb..49ef8d6 100644 --- a/.claude/rules/coding-style.md +++ b/.claude/rules/coding-style.md @@ -4,9 +4,11 @@ # コーディング規約 (Coding Standards) -本ドキュメントでは，SmTIAS-Capture プロジェクトの Dart / Flutter コーディング規約を定義する． +本ドキュメントでは，SmTIAS-Capture プロジェクトの Dart / Flutter コーディング規約（命名・フォーマット・import・型・コメント）を定義する． 基本方針として [Effective Dart](https://dart.dev/effective-dart) に準拠し，プロジェクト固有のルールのみ本書で定める． +※ ディレクトリ構成・ファイル配置は [project-structure ルール](project-structure.md)，エラー処理・ログは [error-handling ルール](error-handling.md) を参照する． + ## フォーマット (Formatting) - `dart format` のデフォルト設定に従う（行幅 80 文字） @@ -52,28 +54,6 @@ ※ `dart fix --apply` および `dart format` で自動整列されるため，手動調整は不要． -## ディレクトリ構造 (Directory Structure) - -[SPEC_03 アーキテクチャと非機能](../../docs/04_SPEC/SPEC_03_アーキテクチャと非機能.md) のアーキテクチャセクションで定義したディレクトリ構成に従う． - -```text -lib/ -├── main.dart # エントリポイント，Provider 登録 -├── app.dart # MaterialApp，テーマ -├── providers/ # 状態管理（ChangeNotifier） -├── screens/ # 画面（Scaffold 単位） -├── widgets/ # 再利用可能な UI 部品 -└── services/ # 外部リソースとの橋渡し -``` - -### 配置ルール - -- **1 ファイル 1 クラス** を原則とする．ファイル名はクラス名の snake_case 版 -- **screens/**: 各画面に対応する 1 ファイル．画面固有のロジックは対応する Provider に置く -- **widgets/**: 複数画面で再利用する UI 部品，または画面ファイルが大きくなった場合に切り出す部品 -- **providers/**: 画面または機能ごとに 1 ファイル．ChangeNotifier を継承する -- **services/**: プラットフォーム API やファイルシステムへのアクセスを担う - ## 型の使い方 (Type Usage) - ローカル変数は型推論（`var` / `final`）を活用する @@ -81,28 +61,6 @@ - `dynamic` は避け，`Object?` を使用する - `final` をデフォルトとし，再代入が必要な場合のみ `var` を使用する -## エラーハンドリング (Error Handling) - -### 基本方針 - -- **Service 層**: 例外をキャッチし，呼び出し元に結果を返す．想定外の例外はそのまま上位に伝播させる -- **Provider 層**: Service の結果を受け取り，状態（エラーメッセージ等）として保持する -- **Screen 層**: Provider の状態を参照し，ユーザーにフィードバックを表示する（スナックバー等） - -### 想定するエラー - -| エラー | 発生箇所 | 対処 | -| --- | --- | --- | -| カメラ初期化失敗 | CameraProvider | エラーメッセージを画面に表示 | -| パーミッション拒否 | PermissionService | 設定画面への誘導を表示 | -| ストレージ書き込み失敗 | FileService | スナックバーでエラー通知 | -| ファイル削除失敗 | FileService | スナックバーでエラー通知 | - -### ログ出力 - -- 開発中は `debugPrint()` を使用する（リリースビルドでは自動的に無効化される） -- `print()` は使用しない - ## ドキュメント (Documentation) ### コード内コメント diff --git a/.claude/rules/error-handling.md b/.claude/rules/error-handling.md new file mode 100644 index 0000000..e4a5729 --- /dev/null +++ b/.claude/rules/error-handling.md @@ -0,0 +1,29 @@ +--- +paths: ["lib/**"] +--- + +# エラーハンドリング規約 (Error Handling) + +エラーの分類・処理方法・ログ出力の方針を定める．例外を扱うコードを書くときは本ルールに従うこと． + +## 基本方針 (Basic Policy) + +層をまたいでエラーを伝播させ，最終的に画面でユーザーに通知する． + +- **Service 層**: 例外をキャッチし，呼び出し元に結果を返す．想定外の例外はそのまま上位に伝播させる +- **Provider 層**: Service の結果を受け取り，状態（エラーメッセージ等）として保持する +- **Screen 層**: Provider の状態を参照し，ユーザーにフィードバックを表示する（スナックバー等） + +## 想定するエラー (Expected Errors) + +| エラー | 発生箇所 | 対処 | +| --- | --- | --- | +| カメラ初期化失敗 | CameraProvider | エラーメッセージを画面に表示 | +| パーミッション拒否 | PermissionService | 設定画面への誘導を表示 | +| ストレージ書き込み失敗 | FileService | スナックバーでエラー通知 | +| ファイル削除失敗 | FileService | スナックバーでエラー通知 | + +## ログ出力 (Logging) + +- 開発中は `debugPrint()` を使用する（リリースビルドでは自動的に無効化される） +- `print()` は使用しない diff --git a/.claude/rules/project-structure.md b/.claude/rules/project-structure.md new file mode 100644 index 0000000..c08109b --- /dev/null +++ b/.claude/rules/project-structure.md @@ -0,0 +1,32 @@ +--- +paths: ["lib/**", "test/**"] +--- + +# プロジェクト構成ルール (Project Structure) + +`lib/` 以下のディレクトリ構成とファイル配置ルールを定める．コードを追加・移動するときは本ルールに従うこと． +アーキテクチャの背景・設計判断は [SPEC_03 アーキテクチャと非機能](../../docs/04_SPEC/SPEC_03_アーキテクチャと非機能.md) を参照する． + +## ディレクトリ構造 (Directory Structure) + +```text +lib/ +├── main.dart # エントリポイント，Provider 登録 +├── app.dart # MaterialApp，テーマ +├── providers/ # 状態管理（ChangeNotifier） +├── screens/ # 画面（Scaffold 単位） +├── widgets/ # 再利用可能な UI 部品 +└── services/ # 外部リソースとの橋渡し +``` + +## 配置ルール (Placement Rules) + +- **1 ファイル 1 クラス** を原則とする．ファイル名はクラス名の snake_case 版 +- **screens/**: 各画面に対応する 1 ファイル．画面固有のロジックは対応する Provider に置く +- **widgets/**: 複数画面で再利用する UI 部品，または画面ファイルが大きくなった場合に切り出す部品 +- **providers/**: 画面または機能ごとに 1 ファイル．ChangeNotifier を継承する +- **services/**: プラットフォーム API やファイルシステムへのアクセスを担う + +## テストの配置 (Test Placement) + +テストコードの配置・命名規則は [testing ルール](testing.md) を参照する（`test/` 以下に対象と同じ階層で配置する）． diff --git a/CLAUDE.md b/CLAUDE.md index 544bc6e..79773cc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -39,6 +39,11 @@ - Phase 2 成功後は Phase 3 → Phase 4 まで自動で進む（Phase 4 で更新がある場合のみ確認） - テスト・リファクタリングをスキップしない +### 開発コマンド + +- 起動・テスト・lint・ビルド等のコマンドは `docs/02_ENV/ENV_04_開発コマンド.md` にまとめる．**実行前に必ず参照し，推測でコマンドを試さない** +- コマンドが新しく確定・変更された時は同ファイルに反映する（`/implement` の Phase 4 でも見直される） + ### 手動確認が必要な作業（自分で完了させないこと） 以下は実装完了後にユーザーへ報告し，確認・実施を依頼すること． @@ -66,6 +71,8 @@ - ファイル命名: .claude/rules/docs-naming.md（`docs/**` 編集時） - 進捗記録: .claude/rules/progress-log.md（CLAUDE.md・docs/PROGRESS.md 編集時） - コーディング規約: .claude/rules/coding-style.md（`lib/**`・`test/**` 編集時） +- プロジェクト構成: .claude/rules/project-structure.md（`lib/**`・`test/**` 編集時） +- エラーハンドリング: .claude/rules/error-handling.md（`lib/**` 編集時） - テスト方針: .claude/rules/testing.md（`test/**` 編集時） ### 02_ENV（環境） @@ -73,6 +80,7 @@ - 技術スタック: docs/02_ENV/ENV_01_技術スタック.md - 環境構築手順: docs/02_ENV/ENV_02_環境構築手順.md - 管理者用環境構築手順: docs/02_ENV/ENV_03_管理者用環境構築手順.md +- 開発コマンド: docs/02_ENV/ENV_04_開発コマンド.md ### 03_PLAN（計画） diff --git "a/docs/02_ENV/ENV_04_\351\226\213\347\231\272\343\202\263\343\203\236\343\203\263\343\203\211.md" "b/docs/02_ENV/ENV_04_\351\226\213\347\231\272\343\202\263\343\203\236\343\203\263\343\203\211.md" new file mode 100644 index 0000000..e0f8af8 --- /dev/null +++ "b/docs/02_ENV/ENV_04_\351\226\213\347\231\272\343\202\263\343\203\236\343\203\263\343\203\211.md" @@ -0,0 +1,71 @@ +# 開発コマンド (Development Commands) + +本ドキュメントは，SmTIAS-Capture の日常開発で使うコマンドをまとめる． +人間とエージェント（`coder`・`tester`・`refactorer`，`/auto-refactor`・`/auto-audit`）が **コマンドを推測せずに済むための唯一の参照先** とする．新しいコマンドが確定・変更されたら本ファイルに反映する． + +※ すべて Flutter プロジェクトルート（`pubspec.yaml` のある階層）で実行する．Windows の場合はコマンド例中の `./android/gradlew` を `android\gradlew.bat` に読み替える． + +## セットアップ (Setup) + +```bash +flutter pub get # 依存パッケージの取得（pubspec.yaml 変更後に実行） +flutter doctor # 開発環境の診断 +flutter devices # 接続中のデバイス一覧 +``` + +## 起動 (Run) + +```bash +flutter run # 接続中のデバイスでデバッグ実行 +flutter run --release # リリースモードで実行 +``` + +## 静的解析・フォーマット (Lint & Format) + +`analysis_options.yaml` は `package:flutter_lints/flutter.yaml` を継承する． + +```bash +dart analyze # 静的解析（警告・エラー 0 件を維持する） +dart format . # フォーマット（コミット前に差分が無い状態にする） +dart fix --apply # 自動修正（import 整列・非推奨 API 置換等） +``` + +## テスト (Test) + +### Dart（Unit / Widget / Golden） + +`test/` 配下の Dart テスト． + +```bash +flutter test # 全 Dart テストを実行 +flutter test test/services # ディレクトリ単位で実行 +flutter test --update-goldens # golden 画像を更新（preview_orientation_golden_test.dart 等） +``` + +### Kotlin（ネイティブの純粋ロジック） + +研究データの正確性に直結する数理ロジック（画素統計 `ImageStatistics` 等）は，Android Framework 非依存の JUnit で検証する（実機不要）． + +```bash +./android/gradlew test # Kotlin 単体テスト（android/app/src/test/ 配下） +``` + +## ビルド (Build) + +```bash +flutter build apk --debug # デバッグ APK +flutter build apk --release # リリース APK +``` + +## 実機からの画像転送 (Transfer) + +定量モードの DNG は大容量のため，MTP ではなく `adb pull` を推奨する（転送不整合を避ける）． + +```bash +adb devices # 接続確認 +adb pull /sdcard/Pictures/MiniTIAS ./pulled # 撮影データを取得 +``` + +## コミット・PR (Git) + +ブランチ・コミット・push・PR の手順は `.claude/rules/git-conventions.md` および `/commit`（`.claude/skills/commit/`）に従う．本ファイルには記載しない．