62 lines
5.5 KiB
Markdown
62 lines
5.5 KiB
Markdown
# Repository Guidelines
|
||
|
||
## Project Structure & Module Organization
|
||
`lib/` follows Clean Architecture: `core/` for shared constants, errors, network utilities, and base widgets; `data/` for API clients, datasources, and repository implementations; `domain/` for entities and use cases; `presentation/` for Riverpod providers, pages, and widgets. Tests mirror features in `test/`, Hive migration specs live in `test_hive/`. Platform scaffolding sits under `android/`, `ios/`, `macos/`, `linux/`, `windows/`, `web/`, and docs under `doc/`.
|
||
|
||
## Build, Test, and Development Commands
|
||
- `flutter pub get` – run after cloning or switching branches.
|
||
- `flutter pub run build_runner build --delete-conflicting-outputs` – regenerates adapters, JSON code, and merges `doc/restaurant_data/store.db` changes into `assets/data/store_seed.json` and `store_seed.meta.json`.
|
||
- `flutter pub run build_runner watch --delete-conflicting-outputs` – keep this on during development to auto-regenerate seeds when `store.db` changes.
|
||
- `flutter run -d ios|android|chrome` – launch on the target device/simulator (prefer simulators with location APIs).
|
||
- `flutter build apk|appbundle|ios --release` – production bundles after QA is green.
|
||
|
||
## Coding Style & Naming Conventions
|
||
See `doc/03_architecture/code_convention.md`: two-space indent, 80-char soft wrap (120 hard), imports grouped Dart → packages → project, one public class per file. Use PascalCase for classes/providers, camelCase for methods/variables, UPPER_SNAKE_CASE for constants, snake_case for files/folders. Business logic identifiers and UI strings stay in English; comments/docs may be in Korean with the first English term in parentheses. Keep widgets small and compose within the relevant `presentation/*` module to preserve MVVM boundaries.
|
||
|
||
## Testing Guidelines
|
||
Use the Flutter test runner: `flutter test` for all, `flutter test test/..._test.dart` for targeted runs, `flutter test --coverage && genhtml coverage/lcov.info -o coverage/html` for coverage. Name tests with `_test.dart` alongside sources. Prefer `group`/`testWidgets` to describe behaviors (e.g., “should recommend restaurants under rainy limits”). Run `flutter test test_hive` when Hive persistence changes.
|
||
|
||
## Commit & Pull Request Guidelines
|
||
Commit format `type(scope): summary` (e.g., `feat(recommendation): enforce rainy radius`), optional body and `Resolves: #123`. Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`. Create feature branches from `develop`, include API/UI screenshots when visuals change, describe validation steps, and link issues before review. Keep PRs focused on a single feature/bugfix.
|
||
|
||
## Security & Configuration Tips
|
||
Never commit API secrets. Create `lib/core/constants/api_keys.dart` locally with placeholders and use secure storage/CI wiring. Verify location permissions and weather API keys before captures or uploads.
|
||
|
||
## Scope, Goals, and Guardrails
|
||
- Applies repo-wide unless more specific instructions exist; system/developer directives still win.
|
||
- Keep changes minimal and localized; avoid destructive rewrites, config changes, or dependency bumps unless requested.
|
||
- For multi-step tasks, maintain an `update_plan` with exactly one step `in_progress`.
|
||
- Responses stay concise and list code/logs before rationale. If uncertain, prefix with “Uncertain:” and surface at most the top two options.
|
||
- Work is workspace-scoped; ask before adding dependencies or new network calls. Avoid unrequested deletes/rewrites/config changes.
|
||
|
||
## Collaboration & Language
|
||
- Default responses must be in Korean; keep code/logs/commands in their original form.
|
||
- Business logic, identifiers, and UI strings remain in English; comments/docs in Korean with the first English term in parentheses.
|
||
- Git push reports and work completion reports are in Korean.
|
||
- Write code comments and commit/PR/work summary comments in Korean; include English terms in parentheses when helpful.
|
||
- All git comments (commit messages, PR descriptions, push notes) must be written in Korean.
|
||
|
||
## Validation & Quality Checks
|
||
- Run `dart format --set-exit-if-changed .` before finishing.
|
||
- Always run `flutter analyze` and relevant `flutter test` suites (including `flutter test test_hive` when Hive code changes) before hand-off. Add/update tests when behavior changes or bugs are fixed.
|
||
- Document executed commands in your PR or hand-off notes.
|
||
|
||
## Sensitive Areas & Approvals
|
||
- Editing Android/iOS/macOS build settings, signing artifacts, Gradle/Xcode configs needs explicit approval.
|
||
- Do not touch `pubspec.yaml` dependency graphs, secrets, or add network activity/tools without requester confirmation.
|
||
|
||
## Branch & Reporting Conventions
|
||
- Branch naming: `codex/<type>-<slug>` (e.g., `codex/fix-search-null`).
|
||
- Commit messages use `type(scope): summary`; keep explanations short and focused on observable behavior.
|
||
- When offering alternatives, show only the top two concise options.
|
||
- When closing a work report, propose concrete next tasks; if none, state that work is complete.
|
||
|
||
## Notification & Wrap-up
|
||
- Before final report or end of conversation, run `/Users/maximilian.j.sul/.codex/notify.py`.
|
||
- Update any needed working docs before reporting results.
|
||
|
||
## SRP & Layering Checklist
|
||
- Each file/class should have a single reason to change; split widgets ~400 lines and methods ~60 lines into helpers.
|
||
- Preserve presentation → domain → data dependency flow. Domain stays framework-agnostic; data must not reference presentation.
|
||
- Extract validation/transform/sort/filter logic into services/utilities instead of burying it inside widgets.
|