lunchpick/AGENTS.md

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.
• Workspace 한정으로 작업하고, 의존성 추가나 새 네트워크 호출이 필요하면 먼저 확인을 받습니다. 명시 없는 파일 삭제·재작성·설정 변경은 피합니다.

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.
• When ending a work report, always propose concrete next tasks; if there are no follow-up items, explicitly state that all work is complete.

Notification & Wrap-up

• 최종 보고나 대화 종료 직전에 /Users/maximilian.j.sul/.codex/notify.py를 실행해 완료 알림을 보냅니다.
• 필요한 진행 문서를 업데이트한 뒤 결과를 보고합니다.

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.