Add AGENTS.md
This commit is contained in:
1 parent
2be31a59e8
commit
ccce25f050
1 file changed
+85
@@ -0,0 +1,85 @@
|
||||
## AGENTS.md — Project Guidance for AI/Cursor Agents (Aug 2025)
|
||||
|
||||
This file is the authoritative context for AI assistants working on this repository.
|
||||
|
||||
### Project Overview
|
||||
Modern Rust, cross‑platform GUI utility for viewing and batch‑renaming image files. Must support animated GIF playback.
|
||||
|
||||
### Primary Objectives
|
||||
- Fast, smooth image viewing (jpeg, png, webp, gif), including animated GIFs with correct timing/looping.
|
||||
- Ergonomic single and batch renaming with live preview and conflict detection.
|
||||
- Native, first‑class support on Linux, macOS, and Windows.
|
||||
|
||||
### Explicit Non‑Goals (current)
|
||||
- Network features (sync/telemetry) unless explicitly enabled.
|
||||
- Heavy image editing. Lightweight transforms (rotate/flip) are acceptable.
|
||||
|
||||
## Tech & Build
|
||||
- Language: Rust (stable)
|
||||
- GUI: Native desktop (see `src/main.rs`)
|
||||
- OS targets: Linux, macOS, Windows
|
||||
- Build: Cargo
|
||||
|
||||
Commands:
|
||||
- Build: `cargo build`
|
||||
- Release: `cargo build --release`
|
||||
- Run: `cargo run -- <args>`
|
||||
|
||||
### Planned CLI
|
||||
- `image-viewer [PATH]` — open target folder or image
|
||||
- `--recursive` — include subdirectories
|
||||
- `--readonly` — disable rename operations
|
||||
|
||||
## Operating Principles for Agents
|
||||
1. Keep the UI responsive. Offload I/O, decoding, and directory scans off the main/UI thread.
|
||||
2. Prefer incremental/lazy loading for large directories (10k+ files). Avoid blocking operations.
|
||||
3. Renames must be safe by default: dry‑run and preview before commit; use atomic file moves when supported.
|
||||
4. Memory‑wise: reuse decoders/thumbnails; avoid loading full‑resolution frames unless necessary.
|
||||
5. Platform quirks matter: case sensitivity, path length, invalid characters differ by OS. Call these out in PRs.
|
||||
6. Logging: human‑friendly messages in UI; verbose logs only with a flag.
|
||||
7. Privacy: no network I/O by default; any remote call must be opt‑in and documented.
|
||||
|
||||
## Tasks You May Autonomously Perform
|
||||
- Add/extend modules for image loading, GIF playback, directory scanning, and rename planning/execution.
|
||||
- Improve responsiveness via async/workers; remove blocking calls from event handlers.
|
||||
- Add tests for rename plans, conflict detection, and animated GIF timing.
|
||||
- Introduce keyboard shortcuts and accessible UI affordances.
|
||||
|
||||
## Constraints & Success Criteria
|
||||
- Large folders (≥10k files) remain navigable; no main‑thread stalls over ~16ms per frame.
|
||||
- Animated GIF playback honors per‑frame delays and loops.
|
||||
- Rename plans are conflict‑free and reversible if any step fails.
|
||||
- `clippy` and `rustfmt` clean; avoid unsafe unless justified.
|
||||
|
||||
## Module Sketch (evolving)
|
||||
- `src/main.rs` — entry point, bootstrap, arg parsing
|
||||
- `src/ui/` — views, components, global/local state
|
||||
- `src/image/` — loaders, decoders, metadata, GIF playback
|
||||
- `src/rename/` — planning, validation, execution, rollback
|
||||
- `src/fs/` — directory scanning, platform specifics
|
||||
|
||||
## Testing Guidance
|
||||
- Unit tests: filename normalization/sanitization, conflict graphs, atomic move fallbacks.
|
||||
- Snapshot tests: rename plans for representative sample directories.
|
||||
- Integration: CLI flags, basic viewer flows, GIF timing (coarse validation acceptable).
|
||||
|
||||
## Acceptance Criteria Template
|
||||
- Functionality: expected behavior + edge cases.
|
||||
- Performance: bounds for N files in a directory and scroll/thumbnail latency.
|
||||
- UX: keyboard shortcuts, focus management, error surfaces.
|
||||
- Tests: unit/integration assertions you added or updated.
|
||||
|
||||
## Safeguards for Renaming
|
||||
- Always compute a dry‑run plan with a full before→after mapping.
|
||||
- Detect and surface collisions, cycles, and cross‑device moves.
|
||||
- Use temporary names/atomic swaps where needed; ensure rollback on partial failure.
|
||||
|
||||
## Decision Log (append newest first)
|
||||
- [2025-09-29] Adopted `AGENTS.md` as the canonical AI guidance; supersedes `CONTEXT.md`.
|
||||
|
||||
## Quickstart Prompts for Agents
|
||||
- "Add a rename preview dialog with conflict highlights and confirm/cancel."
|
||||
- "Move directory scanning to a background worker and stream results to the UI."
|
||||
- "Implement animated GIF playback with correct frame timing and loop count."
|
||||
|
||||
|
||||
Reference in new issue
Block a user