114 lines
3.1 KiB
Markdown
114 lines
3.1 KiB
Markdown
# 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
|