docs: restructure AGENTS.md with concise repository guidance
Align agent instructions with the streamlined project structure, QA workflow, and security notes used elsewhere in the repo. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
dceoy
@@ -1,81 +1,37 @@
|
||||
# Repository Guidelines
|
||||
|
||||
## Commands
|
||||
## Project Structure & Module Organization
|
||||
|
||||
### Development Setup
|
||||
`mt5cli/` contains the package source. Important modules include `cli.py` for the Typer command-line app, `client.py` and `sdk.py` for public MT5 client/session APIs, `history.py` for SQLite history collection, `storage.py` and `converters.py` for export behavior, and `schemas.py` for normalized dataset contracts. `tests/` holds pytest coverage for CLI behavior, SDK contracts, trading helpers, history, and utilities. `docs/` and `mkdocs.yml` define the MkDocs site and API reference. `skills/mt5cli/SKILL.md` documents the mt5cli agent skill.
|
||||
|
||||
```bash
|
||||
uv sync
|
||||
```
|
||||
## Build, Test, and Development Commands
|
||||
|
||||
### Code Quality and Documentation
|
||||
- `uv sync` installs runtime and development dependencies from `pyproject.toml` and `uv.lock`.
|
||||
- `uv run mt5cli --help` runs the local CLI entry point.
|
||||
- `uv run ruff format .` formats Python files.
|
||||
- `uv run ruff check --fix .` lints and applies safe fixes.
|
||||
- `uv run pyright .` runs strict type checking.
|
||||
- `uv run pytest` runs doctests, branch coverage, and the test suite.
|
||||
- `uv run mkdocs serve` previews documentation locally; `uv run mkdocs build` validates the docs build.
|
||||
|
||||
**Important**: Run these before committing or creating a PR.
|
||||
Use `.agents/skills/local-qa/SKILL.md` for pre-handoff QA. It runs `.agents/skills/local-qa/scripts/qa.sh`, which formats, lints, type-checks, tests, formats Markdown, and checks GitHub workflows.
|
||||
|
||||
1. **format, lint, and test**: Use `local-qa` skill.
|
||||
2. **Documentation build** (if any public API changes): `uv run mkdocs build`
|
||||
## Coding Style & Naming Conventions
|
||||
|
||||
## Architecture
|
||||
Target Python `>=3.11,<3.14`. Use Ruff’s configured 88-character line length and Google-style docstrings. Pyright is strict, so prefer explicit public type annotations and narrow exception handling. Keep module, function, and variable names in `snake_case`; classes and enums use `PascalCase`. Preserve the package’s small, typed helper style rather than adding broad abstractions.
|
||||
|
||||
### Key Dependencies
|
||||
## Design Principles
|
||||
|
||||
- **pdmt5**: Pandas-based data handler for MetaTrader 5 (core library)
|
||||
- **typer**: CLI framework for building command-line interfaces
|
||||
- **click**: Parameter type customization for CLI options
|
||||
- **pandas**: Core data manipulation and analysis
|
||||
Apply KISS, DRY, and YAGNI when changing code. Prefer the simplest implementation that satisfies the current CLI/API contract. Remove duplication when shared behavior is already proven by at least two concrete call sites, but avoid generic helpers for speculative reuse. Do not add configuration flags, extension hooks, or alternate backends until a real repository use case requires them.
|
||||
|
||||
### Package Structure
|
||||
## Testing Guidelines
|
||||
|
||||
- `mt5cli/`: Main package directory
|
||||
- `__init__.py`: Package initialization and exports (`detect_format`, `export_dataframe`)
|
||||
- `cli.py`: CLI application with typer-based commands for data export
|
||||
- `utils.py`: Constants, enums, parameter types, parsers, and export utilities
|
||||
- `__main__.py`: Entry point for `python -m mt5cli`
|
||||
- `tests/`: Comprehensive test suite (pytest-based)
|
||||
- `test_cli.py`: Tests for CLI commands and collect-history behavior
|
||||
- `test_utils.py`: Tests for utility constants, parameter types, parsers, and export functions
|
||||
- `docs/`: MkDocs documentation with API reference
|
||||
- `docs/index.md`: Main documentation
|
||||
- `docs/api/`: Auto-generated API documentation for all modules
|
||||
- Modern Python packaging with `pyproject.toml` and uv dependency management
|
||||
|
||||
### Quality Standards
|
||||
|
||||
- Type hints required (pyright strict mode)
|
||||
- Comprehensive linting with 35+ rule categories (ruff)
|
||||
- Test coverage tracking with 100% (pytest-cov)
|
||||
- Parametrized tests for input/result matrices using `pytest.mark.parametrize` (pytest)
|
||||
- Test doubles (mocks, stubs) using `pytest_mock` for external dependencies (pytest-mock)
|
||||
- Pydantic models for data validation and configuration
|
||||
|
||||
### Documentation workflow
|
||||
|
||||
1. Add Google-style docstrings to functions/classes
|
||||
2. Local preview: `uv run mkdocs serve`
|
||||
3. Build: `uv run mkdocs build`
|
||||
4. Deploy: `uv run mkdocs gh-deploy`
|
||||
Tests use pytest, pytest-mock, doctests, and pytest-cov. Test files should match `tests/test_*.py`, classes `Test*`, and functions `test_*`. Coverage is configured with `fail_under = 100`, so add focused tests for every behavior change. Mock MT5/pdmt5 boundaries; do not require a live MetaTrader terminal in unit tests.
|
||||
|
||||
## Commit & Pull Request Guidelines
|
||||
|
||||
- Run QA checks using `local-qa` skill before committing or creating a PR.
|
||||
- Branch names use appropriate prefixes on creation (e.g., `feature/...`, `bugfix/...`, `refactor/...`, `docs/...`, `chore/...`).
|
||||
- When instructed to create a PR, create it as a draft with appropriate labels by default.
|
||||
Recent history uses concise imperative commits, sometimes with conventional prefixes such as `feat:` or `chore:` and PR numbers appended by GitHub. Keep commits scoped to one logical change. Pull requests should describe behavior changes, note tests run, link related issues, and call out MT5/live-trading risk where relevant.
|
||||
|
||||
## Code Design Principles
|
||||
## Security & Configuration Tips
|
||||
|
||||
Always prefer the simplest design that works.
|
||||
|
||||
- **KISS**: Choose straightforward solutions and avoid unnecessary abstraction.
|
||||
- **DRY**: Remove duplication when it improves clarity and maintainability.
|
||||
- **YAGNI**: Do not add features, hooks, or flexibility until they are needed.
|
||||
- **SOLID/Clean Code**: Apply these as tools, only when they keep the design simpler and easier to change.
|
||||
|
||||
## Development Methodology
|
||||
|
||||
Keep delivery incremental, test-backed, and easy to review.
|
||||
|
||||
- Make small, safe, reversible changes.
|
||||
- Prefer `Red -> Green -> Refactor`.
|
||||
- Do not mix feature work and refactoring in the same commit.
|
||||
- Refactor when it improves clarity or removes real duplication (Rule of Three).
|
||||
- Keep tests fast, focused, and self-validating.
|
||||
Never commit account credentials, broker passwords, exported private data, or local `.venv` contents. Treat `order_send` and CLI `order-send --yes` as live execution paths; gate examples and tests so they cannot place real trades accidentally.
|
||||
|
||||
Reference in New Issue
Block a user