julian/lunchpick
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(guidelines): translate AGENTS to English

Browse Source 
Converted AGENTS.md to English wording while keeping Korean requirements as examples (Korean responses/comments remain enforced).
This commit is contained in:
JiWoong Sul
2025-12-02 15:28:16 +09:00
parent 9f82a0cfda
commit d101f7d0dc
1 changed files with 32 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
AGENTS.md
View File

@@ -1,59 +1,60 @@
# Repository Guidelines # Repository Guidelines
## Project Structure & Module Organization ## 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 ## Build, Test, and Development Commands
- `flutter pub get` – fetch packages after cloning or switching branches. - `flutter pub get` – run 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 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 run -d ios|android|chrome` – start the app on the specified device; prefer simulators that can access location APIs. - `flutter pub run build_runner watch --delete-conflicting-outputs` – keep this on during development to auto-regenerate seeds when `store.db` changes.
- `flutter build apk|appbundle|ios --release` – produce production bundles once QA is green. - `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 ## 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 ## 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 ## 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 ## 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 ## 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. - Applies repo-wide unless more specific instructions exist; system/developer directives still win.
- 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. - Keep changes minimal and localized; avoid destructive rewrites, config changes, or dependency bumps unless requested.
- When a task requires multiple steps, maintain an `update_plan` with exactly one step marked `in_progress`. - For multi-step tasks, maintain an `update_plan` with exactly one step `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. - Responses stay concise and list code/logs before rationale. If uncertain, prefix with “Uncertain:” and surface at most the top two options.
- Workspace 한정으로 작업하고, 의존성 추가나 새 네트워크 호출이 필요하면 먼저 확인을 받습니다. 명시 없는 파일 삭제·재작성·설정 변경은 피합니다. - Work is workspace-scoped; ask before adding dependencies or new network calls. Avoid unrequested deletes/rewrites/config changes.
## Collaboration & Language ## 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, but 주석과 문서 설명은 가능한 한 한국어로 작성하고 처음에는 해당 영어 용어를 괄호로 병기합니다. - Business logic, identifiers, and UI strings remain in English; comments/docs in Korean with the first English term in parentheses.
- Git push 보고나 작업 완료 보고 역시 한국어로 작성합니다. - 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. - Write code comments and commit/PR/work summary comments in Korean; include English terms in parentheses when helpful.
## Validation & Quality Checks ## Validation & Quality Checks
- Run `dart format --set-exit-if-changed .` before finishing a task to ensure formatting stays consistent. - Run `dart format --set-exit-if-changed .` before finishing.
- 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. - 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 which commands were executed as part of the validation notes in your PR or hand-off summary. - Document executed commands in your PR or hand-off notes.
## Sensitive Areas & Approvals ## Sensitive Areas & Approvals
- Editing Android/iOS/macOS build settings, signing artifacts, and Gradle/Xcode configs requires explicit approval. - Editing Android/iOS/macOS build settings, signing artifacts, Gradle/Xcode configs needs explicit approval.
- Do not touch `pubspec.yaml` dependency graphs, secrets, or introduce network activity/tools without checking with the requester first. - Do not touch `pubspec.yaml` dependency graphs, secrets, or add network activity/tools without requester confirmation.
## Branch & Reporting Conventions ## Branch & Reporting Conventions
- Create task branches as `codex/<type>-<slug>` (e.g., `codex/fix-search-null`). - Branch naming: `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. - Commit messages use `type(scope): summary`; keep explanations short and focused on observable behavior.
- When presenting alternatives, only show the top two concise options to speed up decision-making. - When offering alternatives, show only the top two concise options.
- When ending a work report, always propose concrete next tasks; if there are no follow-up items, explicitly state that all work is complete. - When closing a work report, propose concrete next tasks; if none, state that work is complete.
## Notification & Wrap-up ## 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 ## 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. - Each file/class should have a single reason to change; split widgets ~400 lines and methods ~60 lines into helpers.
- Preserve the presentation → domain → data dependency flow. Domain stays framework-agnostic, and data never references presentation. - Preserve presentation → domain → data dependency flow. Domain stays framework-agnostic; data must not reference presentation.
- Extract validation, transformations, sorting, and filtering logic into dedicated services/utilities instead of burying them inside widgets. - Extract validation/transform/sort/filter logic into services/utilities instead of burying it inside widgets.