From b911dc9468adff5691c895c5afda7120e00ba820 Mon Sep 17 00:00:00 2001 From: Ake <10195782+akegaviar@users.noreply.github.com> Date: Thu, 21 Aug 2025 09:12:13 +0800 Subject: [PATCH 1/3] Add AGENTS.md --- AGENTS.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..f050281 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,66 @@ +# AGENTS Guidelines for This Repository + +This repository contains a Python-based Vercel Functions application for monitoring RPC node response times. When working on the project interactively with an agent (e.g. the Codex CLI) please follow the guidelines below to ensure smooth development and testing. + +## 1. Use Test Scripts for Local Development + +* **Always use the test scripts** (`test_api_read.py`, `test_api_write.py`, `test_update_state.py`) for local testing and development. +* **Do _not_ deploy to Vercel during the agent session** unless explicitly requested. Deployments should be handled outside of the interactive workflow to avoid disrupting production services. +* **Create a `.env.local` file** with the necessary environment variables before testing locally. + +## 2. Keep Dependencies in Sync + +If you add or update dependencies: + +1. Update `requirements.txt` with the new package and version. +2. Reinstall dependencies in your virtual environment with `pip install -r requirements.txt`. +3. Verify compatibility with Python 3.9+ as specified in the project. + +## 3. Coding Conventions + +* Follow PEP 8 style guidelines. +* Use type hints for all function parameters and return values. +* Include Google-style docstrings for all functions and classes. +* Keep cyclomatic complexity below 10 (enforced by Ruff). +* Prefer composition over inheritance when designing metric classes. + +## 4. Code Quality Checks + +Before completing any task, run these quality checks: + +| Command | Purpose | +| --------------------- | ------------------------------------------------- | +| `black .` | Format code to project standards | +| `ruff check .` | Run linting checks | +| `ruff check . --fix` | Auto-fix linting issues where possible | +| `mypy .` | Run type checking | + +## 5. Testing Guidelines + +* Test new metrics locally using the appropriate test script: + - `python tests/test_api_read.py` for read metrics + - `python tests/test_api_write.py` for write metrics + - `python tests/test_update_state.py` for state updates +* Ensure `endpoints.json` is properly configured before testing. +* Mock external API calls when writing unit tests. + +## 6. Project Structure + +When adding new features, maintain the existing structure: + +* `/api/` - Vercel Functions entry points only +* `/common/` - Shared utilities and base classes +* `/metrics/` - Blockchain-specific metric implementations +* `/tests/` - Test scripts and unit tests + +## 7. Environment Variables + +Never commit credentials or secrets. Always use environment variables: + +* Development: `.env.local` (git-ignored) +* Production: Configured in Vercel dashboard +* Use `VERCEL_ENV=development` to add dev prefix to metrics during testing + +--- + +Following these practices ensures reliable development and prevents disruption to the production monitoring system. When in doubt, test locally before making any deployment-related changes. \ No newline at end of file From 3777badee6e114c126b7e99e4baa2255784cb500 Mon Sep 17 00:00:00 2001 From: smypmsa Date: Thu, 21 Aug 2025 11:45:53 +0000 Subject: [PATCH 2/3] docs(agents): clarify dev prefix for metrics --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index f050281..372247a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -59,7 +59,7 @@ Never commit credentials or secrets. Always use environment variables: * Development: `.env.local` (git-ignored) * Production: Configured in Vercel dashboard -* Use `VERCEL_ENV=development` to add dev prefix to metrics during testing +* Metrics are automatically prefixed using the `METRIC_PREFIX` constant from `config/defaults.py` which reads `os.getenv("VERCEL_ENV")` (e.g., "dev_" for non-production and "" for production) --- From bc613968650173d7c7ed14ac706fd91ab759cfc1 Mon Sep 17 00:00:00 2001 From: smypmsa Date: Thu, 21 Aug 2025 11:47:26 +0000 Subject: [PATCH 3/3] docs(agents): remove mentioning unit tests --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 372247a..5f201a4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -51,7 +51,7 @@ When adding new features, maintain the existing structure: * `/api/` - Vercel Functions entry points only * `/common/` - Shared utilities and base classes * `/metrics/` - Blockchain-specific metric implementations -* `/tests/` - Test scripts and unit tests +* `/tests/` - Test scripts ## 7. Environment Variables