Skip to content

AGENTS.md

Latest commit

 

History

History
41 lines (35 loc) · 2.48 KB

AGENTS.md

File metadata and controls

41 lines (35 loc) · 2.48 KB

Repository Guidelines

Project Structure & Module Organization

  • Place application code in src/ with clear submodules (e.g., src/core/, src/features/).
  • Keep tests in tests/ mirroring src/ paths (e.g., src/utils/date.ts → tests/utils/date.spec.ts).
  • Use scripts/ for local tooling and one-off utilities; keep scripts idempotent.
  • Store static files in assets/ and example data in examples/.

Build, Test, and Development Commands

  • Prefer make targets for a consistent DX:
    • make install — install dependencies.
    • make build — produce a production build/artifacts.
    • make test — run unit tests (fast, local).
    • make lint — run linters/formatters.
    • make dev — start local development (watch mode if applicable).
  • If make is unavailable, provide equivalent package/task runner commands in scripts/.

Coding Style & Naming Conventions

  • Indentation: 2 spaces for config/markup; 2–4 spaces for code, follow language norms.
  • Line length target: 100 characters.
  • Filenames: lowercase-kebab for general files (e.g., date-utils.ts); language-specific exceptions allowed (e.g., snake_case.py, PascalCase.cs).
  • Use a formatter and linter (e.g., Prettier/ESLint, Ruff/Black, or language equivalents). Add config to repo root.
  • Public APIs: prefer explicit exports; avoid hidden side effects in module top-level.

Testing Guidelines

  • Unit tests live in tests/ with names like *.spec.* or test_*.py depending on language.
  • Aim for meaningful coverage of core logic and error paths; avoid brittle snapshot-only tests.
  • Keep tests deterministic and isolated; use factories/fixtures for setup.
  • Run locally via make test; add make test-watch if supported.

Commit & Pull Request Guidelines

  • Use Conventional Commits where possible: feat:, fix:, docs:, chore:, refactor:, test:, ci:.
  • Keep commits focused and rebase to clean up WIP before opening a PR.
  • PRs must include: clear description, linked issues (e.g., Closes #123), screenshots or logs when UI/CLI output changes, and notes on breaking changes/migrations.
  • Update docs and examples when behavior changes.

Agent-Specific Instructions

  • Follow this file’s conventions when generating or modifying code.
  • Scope changes narrowly; avoid drive-by refactors unrelated to the task.
  • Prefer small, reviewable PRs; include reasoning in commit bodies when decisions are non-obvious.
  • When adding tools or commands, update Makefile/scripts/ and this document accordingly.