From e612b6e41c0e3413810635a9493837e5a472bd30 Mon Sep 17 00:00:00 2001 From: Abhimanyu Saharan Date: Sun, 8 Feb 2026 00:55:40 +0530 Subject: [PATCH] docs: update AGENTS.md to enhance project structure clarity and coding guidelines --- AGENTS.md | 34 +++++++++++++++++++++------------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index afabc98e..7b1aa47b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,8 +1,14 @@ # Repository Guidelines ## Project Structure & Module Organization -- `backend/`: FastAPI service. App code lives in `backend/app/` (routes in `backend/app/api/`, models in `backend/app/models/`, schemas in `backend/app/schemas/`, workers in `backend/app/workers/`). DB migrations are in `backend/alembic/` (generated files in `backend/alembic/versions/`). -- `frontend/`: Next.js app. Routes live in `frontend/src/app/`; shared UI in `frontend/src/components/`; utilities in `frontend/src/lib/`; generated API client in `frontend/src/api/generated/` (do not edit by hand). +- `backend/`: FastAPI service. + - App code: `backend/app/` (routes `backend/app/api/`, models `backend/app/models/`, schemas `backend/app/schemas/`, workers `backend/app/workers/`). + - DB migrations: `backend/alembic/` (generated versions in `backend/alembic/versions/`). + - Tests: `backend/tests/`. +- `frontend/`: Next.js app. + - Routes: `frontend/src/app/`; shared UI: `frontend/src/components/`; utilities: `frontend/src/lib/`. + - Generated API client: `frontend/src/api/generated/` (do not edit by hand). + - Tests: colocated `*.test.ts(x)` (example: `frontend/src/lib/backoff.test.ts`). - `templates/`: shared templates packaged into the backend image (used by gateway integrations). - `docs/`: protocol/architecture notes (see `docs/openclaw_gateway_ws.md`). @@ -10,24 +16,26 @@ From repo root: - `make setup`: install/sync backend + frontend dependencies. - `make check`: CI-equivalent suite (lint, typecheck, tests/coverage, frontend build). -- `docker compose -f compose.yml --env-file .env up -d --build`: run full stack (includes Postgres + Redis). +- `docker compose -f compose.yml --env-file .env up -d --build`: run full stack (Postgres + Redis included). -Fast local dev loop: +Fast local dev: - `docker compose -f compose.yml --env-file .env up -d db redis` - Backend: `cd backend && uv sync --extra dev && uv run uvicorn app.main:app --reload --port 8000` - Frontend: `cd frontend && npm install && npm run dev` - -Other useful targets: `make backend-migrate` (alembic upgrade), `make api-gen` (regenerate TS client; backend must be running on `127.0.0.1:8000`). +- API client: `make api-gen` (backend must be running on `127.0.0.1:8000`). ## Coding Style & Naming Conventions -- Python: Black + isort (line length 100), flake8 (`backend/.flake8`), mypy is strict (`backend/pyproject.toml`). Prefer `snake_case` for modules/functions. -- TypeScript/React: ESLint (Next.js config) + Prettier (`make frontend-format`). Prefer `PascalCase` components and `camelCase` vars; prefix intentionally-unused destructured props with `_` (see `frontend/eslint.config.mjs`). -- Optional: `pre-commit install` to run formatting/lint hooks on commit. +- Python: Black + isort (line length 100), flake8 (`backend/.flake8`), strict mypy (`backend/pyproject.toml`). Use `snake_case`. +- TypeScript/React: ESLint (Next.js) + Prettier (`make frontend-format`). Components `PascalCase`, variables `camelCase`. Prefix intentionally-unused destructured props with `_` (see `frontend/eslint.config.mjs`). +- Optional: `pre-commit install` to run format/lint hooks locally. ## Testing Guidelines -- Backend: pytest in `backend/tests/` (files `test_*.py`); run `make backend-test` or `make backend-coverage` (writes `backend/coverage.xml`). -- Frontend: vitest + testing-library; prefer `*.test.ts(x)` near the code (example: `frontend/src/lib/backoff.test.ts`); run `make frontend-test` (writes `frontend/coverage/`). +- Backend: pytest (`backend/tests/`, files `test_*.py`). Run `make backend-test` or `make backend-coverage` (writes `backend/coverage.xml`). +- Frontend: vitest + testing-library. Run `make frontend-test` (writes `frontend/coverage/`). ## Commit & Pull Request Guidelines -- Use Conventional Commits (seen in history): `feat: ...`, `fix: ...`, `docs: ...`, `chore: ...`, `refactor: ...` with optional scope like `feat(chat): ...`. -- PRs should include: what/why, how to test (ideally `make check`), linked issue (if any), and screenshots for UI changes. Never commit secrets; use `.env.example` files as templates. +- Commits: Conventional Commits (e.g., `feat: ...`, `fix: ...`, `docs: ...`, `chore: ...`, `refactor: ...`; optional scope like `feat(chat): ...`). +- PRs: include what/why, how to test (ideally `make check`), linked issue (if any), and screenshots for UI changes. + +## Security & Configuration Tips +- Never commit secrets. Use `.env.example` as the template and keep real values in `.env`.