AGENTS.md

1# AGENTS.md
2 
3Guidance for AI agents working in this repository.
4 
5## Project Rules
6 
7Project-specific context, repository layout, build commands, and local operating rules.
8 
9### Project Overview
10 
11Easydict is a macOS dictionary and translation app that supports word lookup, text
12translation, and OCR screenshot translation.
13 
14### Platform and Language
15 
16- Supports macOS 13.0+.
17- Uses SwiftUI for all new UI components and views.
18 
19### Directory Structure
20 
21```
22Easydict/
23├── Easydict/                         # App source root
24│   ├── App/                       # App entry, pch, bridge, plist, assets, localization
25│   │
26│   ├── Swift/                     # Swift source root
27│   │   ├── Feature/               # Product feature modules
28│   │   │   ├── ActionManager/     # Action routing and execution
29│   │   │   ├── Screenshot/        # Screenshot feature
30│   │   │   ├── Shortcut/          # Keyboard shortcut model and UI
31│   │   │   └── ...                # Other product features
32│   │   │
33│   │   ├── Service/               # Translation and AI provider implementations
34│   │   │   ├── Model/             # Service request and response models
35│   │   │   ├── Google/            # Google translation service
36│   │   │   ├── OpenAI/            # OpenAI-compatible service integration
37│   │   │   └── ...                # Other translation and AI services
38│   │   │
39│   │   ├── Model/                 # Shared app data models
40│   │   ├── Utility/               # Cross-feature utilities and helpers
41│   │   │   ├── EventMonitor/      # Global event monitoring and triggers
42│   │   │   ├── Extensions/        # Swift, AppKit, SwiftUI, Foundation extensions
43│   │   │   └── ...                # Other shared utilities
44│   │   │
45│   │   └── View/                  # Shared SwiftUI and AppKit-facing views
46│   │
47│   └── objc/                      # Legacy code - maintenance only
48│       ├── Libraries/             # Bundled legacy helper libraries
49│       ├── Utility/               # Legacy helper categories and utilities
50│       └── ViewController/        # Legacy window and query controllers
51│
52├── EasydictTests/                    # Unit tests
53└── Pods/                          # CocoaPods dependencies and integration project
54```
55 
56### Build and Test Commands
57 
58Run `xcodebuild` only when:
59 
60- Swift, Objective-C, or other Xcode-compiled app source changes exceed 100
61  substantive lines. Xcode project/workspace metadata, documentation, scripts,
62  and comment-only edits do not count toward this trigger.
63- Unit test source files under `EasydictTests/**/*.swift` are added or changed.
64- The user explicitly asks for a build or test run.
65 
66Evaluate the 100-line trigger only after implementation is complete. Use the final
67task-owned diff, count added and deleted substantive lines together instead of using
68an estimate or net line count, exclude blank lines and unrelated pre-existing changes,
69and recalculate before finishing if the implementation changes again.
70 
71Do not run multiple `xcodebuild` commands concurrently against the same workspace and
72DerivedData location. Concurrent runs can contend for the shared build database,
73intermediates, and test bundles, which leads to flaky conflicts.
74 
75`xcodebuild` may take several minutes. Wait for it to finish.
76 
77If the default Xcode DerivedData location fails because of permission, cache, or runner
78state, use an temporary external DerivedData directory instead of a repo-local one:
79 
80`-derivedDataPath ~/Library/Developer/Xcode/DerivedData/Easydict-Temporary`
81 
82After the build or test completes, remove that DerivedData directory before
83finishing the task.
84 
85Common build and test commands:
86 
87```bash
88# Build
89xcodebuild build \
90  -workspace Easydict.xcworkspace \
91  -scheme Easydict | xcbeautify
92 
93# Test (builds and runs a test in one command)
94xcodebuild test \
95  -workspace Easydict.xcworkspace \
96  -scheme Easydict \
97  -only-testing:EasydictTests/UtilityFunctionsTests/testAES | xcbeautify
98 
99# Build for testing
100xcodebuild build-for-testing \
101  -workspace Easydict.xcworkspace \
102  -scheme Easydict | xcbeautify
103 
104# e.g. run specific test class, -only-testing:<Target>/<TestClass>
105xcodebuild test-without-building \
106  -workspace Easydict.xcworkspace \
107  -scheme Easydict \
108  -only-testing:EasydictTests/UtilityFunctionsTests | xcbeautify
109 
110# e.g. run specific test method, -only-testing:<Target>/<TestClass>/<testMethod>
111xcodebuild test-without-building \
112  -workspace Easydict.xcworkspace \
113  -scheme Easydict \
114  -only-testing:EasydictTests/UtilityFunctionsTests/testAES | xcbeautify
115```
116 
117Recommended usage:
118 
119- `build`: default validation when `xcodebuild` validation is required.
120- `test`: simplest one-shot test run; builds and runs tests in one command.
121- When unit test source files change, use `xcodebuild test` for the first validation.
122  Scope it with `-only-testing:<Target>/<TestSuiteOrClass>` for the changed test when
123  possible; if the mapping is unclear, run the relevant broader test target or suite.
124- `build-for-testing` + `test-without-building`: preferred when rerunning the same tests
125  repeatedly.
126- `test-without-building` requires a compatible prior `build-for-testing` with the same
127  workspace, scheme, destination, configuration, and DerivedData location.
128- If code or build settings changed, rerun `build-for-testing` before
129  `test-without-building`.
130- Prefer `-only-testing:` when debugging a specific test class or method.
131 
132### Localization
133 
134- All user-facing UI text must be localized. Do not hard-code visible strings in SwiftUI,
135  AppKit, scripts, or bundled web assets that users can see.
136- `Localizable.xcstrings` manages app string localization. Whenever user-facing text is
137  added or its meaning changes, enumerate the catalog's current locales and update every
138  one for the affected key instead of copying nearby entries.
139- Use static String Catalog keys directly in UI and string APIs when possible, for example
140  `Text("setting.general.appearance.light_dark_appearance")`.
141- Do not build localization keys dynamically or concatenate localized fragments. For text
142  with runtime values, localize the full sentence with a dedicated entry and pass the
143  values as arguments.
144- Use lowercase, dot-separated keys with snake_case segments where needed, and do not
145  rename keys casually. Follow `<scope>.<category>.<subcategory>.<element>`, for example
146  `common.done` or `setting.general.appearance.light_dark_appearance`.
147 
148## Cross-Language Code Quality Rules
149 
150These rules apply to handwritten Swift, Python, Shell, JavaScript/TypeScript, and other
151source files in this repository.
152 
153### Source Organization Rules
154 
155- Organize source directories by feature or bounded responsibility once an area grows
156  beyond a few files. Keep feature-specific UI, core, state, storage, services,
157  utilities, and docs together.
158- Keep source files focused on one clear responsibility. Prefer extracting a helper,
159  module, or sibling script when a file starts mixing unrelated parsing, UI, I/O,
160  orchestration, and validation concerns.
161- Handwritten source files should generally stay within 500 lines. Files approaching or
162  exceeding this size should be reviewed for a responsibility split before adding more
163  behavior.
164- Handwritten source files should not exceed 1000 lines. Existing files over this limit
165  are technical debt; do not add new complex flows to them without first splitting the
166  file or documenting a concrete split plan.
167- Generated files, third-party code, pure data files, templates, large fixtures, and
168  intentionally vendored runtime files are exempt from the line-count guideline.
169- Use the language's normal section markers in longer files to group lifecycle, state
170  updates, command handling, I/O, parsing, and private helpers. Do not add a section
171  marker for a single isolated function unless it materially improves navigation.
172 
173### Naming Rules
174 
175- Use each language and toolchain's normal naming conventions for compiled or imported
176  source files, modules, types, functions, and tests.
177- Use kebab-case for non-imported documentation, exported artifacts, app-managed runtime
178  paths, and standalone scripts unless surrounding tooling already requires another
179  style.
180- For new or renamed types, functions, properties, parameters, and local variables,
181  prefer clear, concise names, remove repeated surrounding context, and usually keep
182  them within 20 characters.
183- If a longer name is required by a system API, external protocol, or unavoidable domain
184  term, keep it as short as possible and treat it as an exception.
185 
186### Coding Practices
187 
188- Avoid single-letter variable names except trivial loop indices.
189- Avoid global helpers, static or type-level functions, and mutable globals unless the
190  language, module, or domain model clearly requires them. Utility modules and types may
191  expose type-level helpers when that is their main responsibility.
192- Do not extract one-off literals into variables or constants unless they are reused or
193  have clear semantic meaning. Name a one-off constant only when a magic number has
194  distinctive visual or domain meaning.
195- Prefer async/await over callback-based completion handlers in languages and runtimes
196  where async/await is the established option.
197 
198### Documentation Comment Rules
199 
200- Add file-level comments for non-trivial scripts or modules so readers know the entry
201  point, responsibility, and important side effects.
202- Add short documentation comments for complex functions, command entry points, state
203  machines, parsers, I/O boundaries, and recovery/error-handling logic. Do not add
204  mechanical comments for obvious getters, path helpers, or thin wrappers.
205- Keep comment lines within 80 characters, avoid restating obvious type or property
206  names, and update comments whenever responsibilities or behavior change.
207- Use the language's normal comment style: Swift documentation comments, Python
208  docstrings, Shell comments before functions, and JSDoc/TSDoc where appropriate.
209- When creating or updating source file header comments, use the current Git username in
210  the `Created by ...` line. Do not use agent names such as `Codex`, `Claude`, or
211  `AI Assistant`.
212 
213### Test Code Rules
214 
215- Do not use the same agent session to both modify production code and add unit tests.
216- Prefer assigning unit tests to a different agent from the implementation agent, for
217  example Codex for production code and Claude Code for unit tests.
218- Do not add tests for UI code or UI-focused changes.
219- Add or update tests only for changes with meaningful behavior or correctness risk. Skip
220  trivial pass-through code, simple glue code, obvious accessors, and behavior already
221  covered elsewhere, and run the relevant tests.
222- Prefer concrete production code and high-signal behavior assertions. Do not add
223  test-only protocols, mocks, overrides, or invasive production hooks for low-value
224  tests.
225 
226## Swift-Xcode Rules
227 
228Reusable Swift and Xcode rules for source organization, documentation, testing, and APIs.
229 
230### Xcode Project Metadata
231 
232Unless the user explicitly says otherwise, when adding or moving files, also update the
233owning `.xcodeproj/project.pbxproj` file so the files appear in Xcode's navigator.
234 
235- By default, every newly added project file, including developer-facing documentation
236  such as Markdown, HTML or SVG files, must have a matching `PBXFileReference` under the
237  correct `PBXGroup`.
238- Do not add documentation files to build phases such as `Resources` unless the file is
239  intentionally shipped at runtime.
240 
241### Swift Source Organization Rules
242 
243- Keep each Swift source file focused on one primary `class` or `struct`. Multiple
244  declarations are acceptable only for tightly coupled protocols, simple pure data
245  models, small private helper types, or extensions and conformance blocks that directly
246  support the primary type.
247- Group functions that implement the same `protocol` together instead of scattering them
248  across a type.
249- Mark each protocol implementation block with `// MARK: - <ProtocolName>` or an equally
250  clear section title, such as `// MARK: - WCSessionDelegate`.
251- Use `// MARK:` sections in longer classes and structs to organize lifecycle, state
252  updates, protocol implementations, and private helpers. Do not add a `MARK` only for a
253  single isolated function unless it materially improves navigation.
254 
255### Swift Naming Rules
256 
257- Use `UpperCamelCase` for directories and files that are compiled by Xcode, including
258  Swift, Objective-C, and test source files.
259 
260### Swift Coding Practices
261 
262- Avoid `static` functions and variables unless type-level semantics clearly require them.
263  Utility types may use `static`.
264- Prefer `for … where` over `for` plus inline `if` filtering.
265 
266### Swift Documentation Comment Rules
267 
268- Add a type-level comment immediately before every class, struct, enum, protocol, and
269  actor. For core types, use 2-4 short sentences and keep the comment around 220-320
270  English characters. For simple private helper types, use 1-2 short sentences and keep
271  it under 180 characters.
272- Add English documentation comments for functions when behavior or intent is not obvious.
273  Use inline comments only for non-obvious reasoning or complex logic.
274 
275### Libraries and API Usage
276 
277- Use **SFSafeSymbols** type-safe APIs instead of hard-coded SF Symbol strings.
278- Prefer `Image(systemSymbol: .chevronRight)` over `Image(systemName: "chevron.right")`.
279- Prefer `Label("MyText", systemSymbol: .cCircle)` over
280  `Label("MyText", systemImage: "c.circle")`.
281- In SwiftUI, use `foregroundStyle<S>(_ style: S)` instead of deprecated
282  `foregroundColor(_:)`.
283- In SwiftUI, use `background(alignment:content:)` or trailing-closure
284  `background { ... }` for background views instead of deprecated
285  `background(_:alignment:)`. Keep `Color` and material `ShapeStyle` backgrounds on their
286  dedicated overloads.
287- Use `Alamofire` async/await APIs for network requests.
288- Use `Defaults` for user preferences and settings; avoid introducing new direct
289  `UserDefaults` usage.
290 
291### Swift Test Code Rules
292 
293- Each test source file may declare at most one `@Suite` type.
294 
295## General Agent Rules
296 
297Language-agnostic agent guidance for tool usage, local skill overlays, and working
298habits.
299 
300### Skill Overlay Rules
301 
302- Store local skill overlay files in `.agents/overrides/`; use them to extend shared
303  skill or tool instructions without editing the shared source.
304- When using `fireworks-tech-graph`, read
305  `.agents/overrides/fireworks-tech-graph-quality-rules.md` after the skill and apply its
306  diagram quality, connector, label, export, and rendered-review rules.
307 
308### MCP Servers
309 
310Always use the OpenAI developer documentation MCP server if you need to work with the
311OpenAI API, ChatGPT Apps SDK, Codex, or related developer tools.
312 
313### Agent Working Principles
314 
315#### Think Before Coding
316 
317- State assumptions, uncertainties, and tradeoffs before implementation.
318- If requirements are unclear or have multiple plausible interpretations, ask before
319  choosing. Mention simpler alternatives when they exist.
320 
321#### Simplicity First
322 
323- Implement the minimum solution that satisfies the request. Avoid speculative features,
324  single-use abstractions, and unrequested configurability.
325- If a solution grows beyond the real problem, simplify it before delivering.
326 
327#### Surgical Changes
328 
329- Touch only files and lines needed for the current request. Match existing style and
330  avoid opportunistic refactors or comment and format churn.
331- Remove only imports, variables, functions, or files made unused by the current change.
332  Mention unrelated cleanup opportunities instead of doing them.
333 
334#### Goal-Driven Execution
335 
336- Translate tasks into verifiable success criteria and keep working until those criteria
337  are met or a blocker is clear.
338- For multi-step work, state a brief plan and validate with relevant tests, checks,
339  builds, or manual inspection.
340