# Repository Guidelines

## Project Structure & Module Organization
`lib/` follows a Clean Architecture split: `core/` for shared constants, errors, network utilities, and base widgets; `data/` for API clients, datasources, and repository implementations; `domain/` for entities and use cases; and `presentation/` for Riverpod providers, pages, and widgets. Tests mirror the code by feature inside `test/`, while migration-heavy Hive specs live in `test_hive/`. Platform scaffolding resides under `android/`, `ios/`, `macos/`, `linux/`, `windows/`, and `web/`, and documentation resources live in `doc/`.

## Build, Test, and Development Commands
- `flutter pub get` – fetch packages after cloning or switching branches.
- `flutter pub run build_runner build --delete-conflicting-outputs` – regenerate adapters and JSON code when models change.
- `flutter run -d ios|android|chrome` – start the app on the specified device; prefer simulators that can access location APIs.
- `flutter build apk|appbundle|ios --release` – produce production bundles once QA is green.

## Coding Style & Naming Conventions
Follow the conventions in `doc/03_architecture/code_convention.md`: two-space indentation, 80-character soft wrap (120 hard), imports grouped by Dart → packages → project, and one public class per file. Use PascalCase for classes/providers, camelCase for methods and variables, UPPER_SNAKE_CASE for constants, and snake_case for file and folder names. Business logic, identifiers, and UI strings stay in English; explanatory comments and commit scopes may use Korean for clarity. Keep widgets small and compose them inside the relevant `presentation/*` module to preserve MVVM boundaries.

## Testing Guidelines
Use the Flutter test runner: `flutter test` for the whole suite, `flutter test test/..._test.dart` for targeted specs, and `flutter test --coverage && genhtml coverage/lcov.info -o coverage/html` when reporting coverage. Name test files with the `_test.dart` suffix alongside their source, and prefer `group`/`testWidgets` to describe behaviors (“should recommend restaurants under rainy limits”). Run the Hive suite (`flutter test test_hive`) when changing local persistence formats.

## Commit & Pull Request Guidelines
Commits follow `type(scope): summary` (e.g., `feat(recommendation): enforce rainy radius`), with optional body text and `Resolves: #123`. Types include `feat`, `fix`, `docs`, `style`, `refactor`, `test`, and `chore`. Create feature branches from `develop`, reference API or UI screenshots in the PR when visual elements change, describe validation steps, and link issues before requesting review. Keep PRs focused on a single feature or bugfix to simplify review.

## Security & Configuration Tips
Never commit API secrets. Instead, create `lib/core/constants/api_keys.dart` locally with placeholder values and wire them through secure storage for CI/CD. Double-check that location permissions and weather API keys are valid before recording screen captures or uploading builds.

## Scope, Goals, and Guardrails
- Applies to this entire repository unless a more specific instruction appears deeper in the tree; system/developer directives still take precedence.
- Keep changes scoped to this workspace and prefer the smallest safe diffs. Avoid destructive rewrites, config changes, or dependency updates unless someone explicitly asks for them.
- When a task requires multiple steps, maintain an `update_plan` with exactly one step marked `in_progress`.
- Responses stay concise and list code/logs before rationale. If unsure, prefix with `Uncertain:` and surface at most the top two viable options.

## Collaboration & Language
- 기본 응답은 한국어로 작성하고, 코드/로그/명령어는 원문을 유지합니다.
- Business logic, identifiers, and UI strings remain in English, but 주석과 문서 설명은 가능한 한 한국어로 작성하고 처음에는 해당 영어 용어를 괄호로 병기합니다.
- Git push 보고나 작업 완료 보고 역시 한국어로 작성합니다.

## Validation & Quality Checks
- Run `dart format --set-exit-if-changed .` before finishing a task to ensure formatting stays consistent.
- Always run `flutter analyze` and the relevant `flutter test` suites (including `flutter test test_hive` when Hive code changes) before hand-off. Add or update tests whenever behavior changes or bugs are fixed.
- Document which commands were executed as part of the validation notes in your PR or hand-off summary.

## Sensitive Areas & Approvals
- Editing Android/iOS/macOS build settings, signing artifacts, and Gradle/Xcode configs requires explicit approval.
- Do not touch `pubspec.yaml` dependency graphs, secrets, or introduce network activity/tools without checking with the requester first.

## Branch & Reporting Conventions
- Create task branches as `codex/<type>-<slug>` (e.g., `codex/fix-search-null`).
- Continue using `type(scope): summary` commit messages, but keep explanations short and focused on observable behavior changes.
- When presenting alternatives, only show the top two concise options to speed up decision-making.

## SRP & Layering Checklist
- Every file/class should have a single reason to change; split widgets over ~400 lines and methods over ~60 lines into helpers.
- Preserve the presentation → domain → data dependency flow. Domain stays framework-agnostic, and data never references presentation.
- Extract validation, transformations, sorting, and filtering logic into dedicated services/utilities instead of burying them inside widgets.