AniShelf AGENTS.md

AniShelf - Developer Notes

Workflow

• Use the Makefile for routine tasks: make clean, make refresh-packages, make format, make lint, make build, make test-sim, and make run-sim.
• Use make test-sim for broad simulator-based validation. Use make run-sim when validating app runtime or UI behavior, unless the user explicitly asks for device-based verification.
• Use make run-device for build, install, and launch on a connected iPhone only when the user explicitly asks for device-based verification.
• Prefer the smallest relevant build or test command before broad verification.
• If the user asks to perform a change in a new worktree, create that worktree under ../AniShelf-worktrees/.
• Do not use any of the openspec workflows unless the user explicitly requests it.

Code Style

• When creating new source files, include the standard Xcode file comment header. Use the format below, attributing authorship to the agent (OpenAI Codex Or Claude Code) on behalf of the user (replace <username> with the actual GitHub username if known, otherwise use the user's name; use the real creation date in YYYY/M/D format):

  //
  //  FileName.swift
  //  AniShelf
  //
  //  Created by <agent> on behalf of <username> on YYYY/M/D.
  //
  

  Omit this header only when the user explicitly requests it.
• Keep edits aligned with existing project style.
• Use LocalizedStringResource whenever possible for user-facing SwiftUI strings, including labels, helper text, and accessibility copy.

Testing

• Unit tests live in MyAnimeList/Tests/ and DataProvider/Tests/.
• Run the smallest relevant test target first, then use make test-sim when broad validation is warranted. Use make test only when the user explicitly asks for physical-device testing or there is a specific device-only reason.
• When developing new features or adding tests, run only the relevant tests first. For app tests, pass one or more whitespace-separated Xcode test identifiers with APP_TEST_ONLY, for example make test-app-sim APP_TEST_ONLY='MyAnimeListTests/LibraryMetadataRefreshTests' or make test-app-sim APP_TEST_ONLY='MyAnimeListTests/LibraryExportManagerTests MyAnimeListTests/LibraryBackupRestoreTests'. For DataProvider package tests, use Swift Testing's native filter syntax, for example make test-dataprovider DATAPROVIDER_TEST_FILTER='LibrarySyncTests' or make test-dataprovider DATAPROVIDER_TEST_FILTER='LibrarySyncTests|MigrationTests'. Only run the full suite when there is a good reason.
• Do not create excessive or redundant tests. Add only the smallest set that protects distinct behavior, prefer extending existing tests, and avoid duplicating coverage across layers. Simple wiring, copy, or layout changes may need no new tests.
• If a simulator is already booted, use it for install/testing as appropriate. For changes affecting app runtime or UI behavior, prefer make run-sim over relying only on make build. Do not boot a simulator without explicit user permission, even when tests require one.