Skip to content

AGENTS.md

Latest commit

 

History

History
248 lines (168 loc) · 5.28 KB

AGENTS.md

File metadata and controls

248 lines (168 loc) · 5.28 KB
Raw

AGENTS.md

Communication

Codex must respond to the user in Japanese.

  • Explanations, plans, summaries, review comments, and questions should be written in Japanese.
  • Source code, identifiers, file names, API names, test names, and commit-like technical terms may remain in English.
  • If a task is ambiguous, ask concise clarification questions in Japanese.
  • If work is partially completed, summarize what was done and what remains in Japanese.

Project overview

This repository contains PicChronoImporter, a macOS SwiftUI app for importing photos and videos from an SD card or selected folder.

The app scans source files, resolves capture dates from metadata, groups imported files into destination folders by capture date, and provides a review screen where users can filter, sort, select, and resolve conflicts before import.

Primary workflow:

  1. Select source volume or folder.
  2. Select scan scope.
  3. Select destination root.
  4. Select folder naming template.
  5. Scan files.
  6. Review detected files.
  7. Select files to import.
  8. Resolve conflicts before execution.
  9. Import files.
  10. Review result summary.

Repository structure

Expected structure:

PicChronoImporter/
  AGENTS.md
  docs/
    SPEC.md
    IMPLEMENTATION_PLAN.md
    code_review.md
  .agents/
    skills/
      picchrono-fixture-authoring/
        SKILL.md
      picchrono-phase-implementation/
        SKILL.md
      picchrono-code-review/
        SKILL.md
  MacApp/
    PicChronoImporter/
  Packages/
    PhotoImportCore/
    PhotoImportPlatformMac/
  PicChronoImporter.xcodeproj

Required reading

Before implementation tasks, read:

  • docs/SPEC.md
  • docs/IMPLEMENTATION_PLAN.md

For code review tasks, also read:

  • docs/code_review.md

When the task matches a project skill, use the relevant skill:

  • Fixture work: picchrono-fixture-authoring
  • Phase-by-phase implementation: picchrono-phase-implementation
  • Code review: picchrono-code-review

Architecture rules

Use a SOLID-oriented design.

Keep responsibilities separated:

Packages/PhotoImportCore

Core contains:

  • Domain models
  • Use cases
  • Services
  • Protocols
  • Testable business rules

Core must not depend on:

  • SwiftUI
  • AppKit
  • ImageIO
  • UniformTypeIdentifiers
  • FileManager direct usage
  • SQLite direct usage unless hidden behind a protocol abstraction

Core must depend on protocols, not platform implementations.

Packages/PhotoImportPlatformMac

PlatformMac contains macOS-specific implementations:

  • File system implementation
  • Metadata provider implementation
  • SQLite cache implementation
  • Application Support path helpers

PlatformMac may depend on:

  • Foundation
  • ImageIO
  • UniformTypeIdentifiers
  • SQLite-related APIs or libraries
  • PhotoImportCore

MacApp/PicChronoImporter

The app target contains:

  • SwiftUI views
  • ViewModels
  • Navigation
  • Composition Root
  • Live/Test/Preview assemblies
  • App resources
  • UI test fixtures

Do not move business rules into SwiftUI views.

Dependency injection

Use explicit dependency injection.

The app target contains the Composition Root:

MacApp/PicChronoImporter/Composition/
  AppConfiguration.swift
  DependencyContainer.swift
  LiveAssembly.swift
  TestAssembly.swift
  PreviewAssembly.swift

Use AppConfiguration to switch modes:

  • Live mode
  • UI test mode
  • SwiftUI preview mode

UI tests should launch with arguments such as:

-uiTestMode 1 -fixture has_conflicts

Product rules summary

Treat each file as an independent import item.

Do not assume a strict RAW+JPEG pair model.

Classify files into:

  • rawImage
  • compressedImage
  • video
  • sidecar
  • other

Folder templates are limited to year, month, and day.

If capture date cannot be resolved, always use:

UnknownDate

Use two-stage duplicate detection:

  1. Fast candidate detection.
  2. Strict content-hash confirmation.

Default conflict action is skip.

Conflicts should be resolved before import.

During import, re-check destination state before each file operation.

v1 supports only one active import session at a time.

Do not implement full destination folder indexing in v1.

Testing policy

Prefer Swift Testing for Core unit tests.

Use XCUITest for UI tests.

Testing priorities:

  1. Core unit tests
  2. Core integration tests with fake dependencies
  3. PlatformMac tests for macOS-specific behavior
  4. UI tests using JSON fixtures and TestAssembly

Automated tests must not require:

  • a real SD card
  • a real user photo library
  • manual file selection
  • network access

Coding style

Prefer simple, explicit Swift.

Prefer value types for domain models.

Use actors for mutable shared state when appropriate.

Use Sendable where appropriate.

Avoid global mutable state.

Keep public APIs small.

Keep Core platform-independent.

Work style for Codex

Before making broad changes:

  1. Inspect existing structure.
  2. Read required docs.
  3. Make small, reviewable changes.
  4. Add or update tests where practical.
  5. Run relevant tests.
  6. Avoid unrelated refactors.
  7. Report results in Japanese.

If project decisions conflict with implementation details, preserve the documented architecture and ask for clarification in Japanese.

When the user corrects an architectural or product assumption, update AGENTS.md or the relevant document so future sessions inherit the correction.