From 723017a11c85a5799cb15e033e26cf7c16a14e05 Mon Sep 17 00:00:00 2001
From: Yoshihiro OKUMURA <orrisroot@gmail.com>
Date: Mon, 20 Apr 2026 15:54:24 +0900
Subject: [PATCH] docs(agents): add Rust project guidance

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 AGENTS.md | 113 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 113 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..3adb37f
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,113 @@
+# Agents Guidelines
+
+## Project Overview
+
+This project is a Rust command-line client for MDRS-based repositories.
+
+- The binary entry point is `src/main.rs`
+- CLI argument parsing is defined in `src/cli.rs`
+- Command implementations live under `src/commands/`
+- API access code lives under `src/api/`
+- Shared domain types live under `src/models/`
+- Login cache and runtime settings live under `src/cache/` and `src/settings.rs`
+
+## Development Workflow
+
+### Cargo-first workflow
+
+Prefer standard Cargo commands and existing project tooling over custom scripts
+or ad hoc edits.
+
+Common commands:
+
+- `cargo fmt`
+- `cargo test`
+- `cargo build`
+- `cargo run -- <args>`
+
+### Formatting requirement
+
+When you modify Rust code or any code that is formatted by the Rust toolchain,
+you must run `cargo fmt` before finishing the task.
+
+### Validation
+
+Use the narrowest relevant validation for the change:
+
+- documentation-only changes do not require Cargo validation
+- for behavior changes, run the relevant Rust tests if they already exist
+- if no targeted test exists, use the smallest existing Cargo command that
+  meaningfully validates the modified area
+
+## Code Guidelines
+
+### Reuse project patterns
+
+Before adding new code, inspect the existing command, API, and model modules
+and follow their established patterns.
+
+In particular:
+
+- keep CLI behavior consistent with the existing `clap` command structure
+- prefer existing error handling patterns based on `anyhow`
+- keep async behavior aligned with the current `tokio`-based implementation
+- avoid duplicating logic that already exists in sibling command modules
+
+### Comments and documentation
+
+All comments written inside source code must be in English.
+
+This includes:
+
+- line comments
+- block comments
+- doc comments
+
+Documentation file language may follow the needs of the project, but source
+code comments must stay in English.
+
+## Planning and Review
+
+### Plan mode
+
+When working in plan mode:
+
+1. analyze the current codebase state first
+2. write or update the implementation plan in the session plan file
+3. require user review of the plan before starting implementation
+
+Do not begin editing project files until the user has reviewed and approved the
+plan.
+
+### Git commits
+
+Never run `git commit` without explicit user confirmation.
+
+This requirement still applies after a plan has been reviewed or approved. Plan
+approval is not commit approval.
+
+## Git Commit Messages
+
+Commit messages must always be written in English.
+
+Follow the Conventional Commits format:
+
+```text
+<type>(<scope>): <short description>
+```
+
+Use clear, imperative subjects without a trailing period.
+
+Examples:
+
+- `feat(upload): add recursive directory support`
+- `fix(login): handle expired cache gracefully`
+- `docs(agents): add Rust project guidance`
+
+## Practical Expectations for Agents
+
+- make precise, minimal changes that fully solve the task
+- read nearby modules before changing structure or introducing helpers
+- prefer updating existing code paths over adding parallel implementations
+- preserve current CLI semantics unless the task explicitly changes them
+- surface uncertainties to the user instead of guessing on destructive actions