genshin-assistant/AGENTS.md

AGENTS.md

This file defines how AI coding agents should work in this repository.

Core Principles

1. Correctness comes before speed.
2. Preserve the scanner-first product goal: reduce artifact decisions, guide hopping, and manual bookkeeping.
3. Prefer small, reviewable changes over broad rewrites.
4. Do not invent Genshin game data, API behavior, OCR confidence, or optimization rules without documenting the assumption.
5. Keep all game interaction read-only by default. Never add delete, feed, enhance, memory-read, hook, or game-modification behavior.
6. Keep user work and local app state intact.
7. Validate Electron main-process changes with a build and, when practical, a manual Smart Capture smoke test.

Read Before Write

Before editing code, inspect the relevant source files and the project documents:

• docs/PROJECT.md
• docs/ARCHITECTURE.md
• docs/CONVENTIONS.md
• docs/DECISIONS.md
• docs/CHECKLISTS.md

Use rg or rg --files for search.

Product Safety

The app may capture the Genshin window or screen and may later support optional input automation. Treat those areas as high risk.

• Capture must not require memory reads, hooks, injection, or game file modification.
• Input automation, if added, must be opt-in, reversible, whitelisted, and stoppable.
• The app must never delete, feed, enhance, or spend in-game resources.
• Uncertain OCR data must remain reviewable instead of being silently trusted.

Implementation Expectations

• Keep Electron main-process code focused on OS integration, capture, and IPC.
• Keep React code focused on UI state and presentation.
• Keep parsing, scoring, and recommendation logic in src/lib.
• Keep domain types in src/types.
• Prefer deterministic parsers and data packages over hardcoded one-off exceptions.
• When OCR requires heuristics, record the limitation in docs or code comments.

Validation

Run the strongest practical checks for the change:

• npm run lint
• npm test
• npm run build

For scanner changes, also manually verify Smart Capture against an open artifact detail view when possible.

Definition Of Done

A task is done when:

• The requested behavior exists.
• The implementation follows the documented architecture and conventions.
• Relevant checks passed or skipped checks are explained.
• Scanner/OCR changes fail safely into review or uncertainty.
• The final summary names the changed areas and remaining risks.

Obsidian Handoff

For durable project changes, follow:

C:\Users\vmbao\Desktop\Ordner\Obsidian-Vault\Resources\Obsidian\Agent Project Sync Protocol.md

The compact project mirror is:

C:\Users\vmbao\Desktop\Ordner\Obsidian-Vault\Projects\Genshin Artifact Assistant\README.md

• Update this repository's canonical docs first, then the Vault mirror at semantic checkpoints.
• Sync material changes to scope, status, architecture, decisions, verified scanner state, major risks, next priorities, and repeatable workflows.
• Do not mirror every source edit, raw log, or transient debugging result.
• If the Vault is unavailable, report the exact pending handoff instead of claiming synchronization.