diff --git a/AGENTS.md b/AGENTS.md index fdd33c4..d91e000 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,59 +1,60 @@ # 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/`. +`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` – fetch packages after cloning or switching branches. -- `flutter pub run build_runner build --delete-conflicting-outputs` – regenerate adapters, JSON 코드, 그리고 `doc/restaurant_data/store.db` 변경분을 자동으로 변환/병합해 `assets/data/store_seed.json`·`store_seed.meta.json`을 갱신합니다. 개발 중에는 `flutter pub run build_runner watch --delete-conflicting-outputs`를 켜두면 store.db 수정 시마다 시드가 자동 재생성됩니다. -- `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. +- `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 -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. +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 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. +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 -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. +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. 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. +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 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 한정으로 작업하고, 의존성 추가나 새 네트워크 호출이 필요하면 먼저 확인을 받습니다. 명시 없는 파일 삭제·재작성·설정 변경은 피합니다. +- 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 -- 기본 응답은 한국어로 작성하고, 코드/로그/명령어는 원문을 유지합니다. -- Business logic, identifiers, and UI strings remain in English, but 주석과 문서 설명은 가능한 한 한국어로 작성하고 처음에는 해당 영어 용어를 괄호로 병기합니다. -- Git push 보고나 작업 완료 보고 역시 한국어로 작성합니다. +- 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. ## 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. +- 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, 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. +- 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 -- Create task branches as `codex/-` (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. +- Branch naming: `codex/-` (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 -- 최종 보고나 대화 종료 직전에 `/Users/maximilian.j.sul/.codex/notify.py`를 실행해 완료 알림을 보냅니다. -- 필요한 진행 문서를 업데이트한 뒤 결과를 보고합니다. +- 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 -- 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. +- 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.