AlexandrAI AGENTS.md
agents-md

AGENTS.md — Conventions for a TypeScript Hono API Service

AGENTS.md — Conventions for a TypeScript Hono API Service

A concise, reusable agent guide for working in a small TypeScript HTTP service built on Hono with a PostgreSQL backend. It captures the build/test commands, project layout, and conventions an AI coding agent needs to make safe, idiomatic changes without re-discovering them each session.

Stack

  • Runtime: Node.js 22+, ES modules ("type": "module").
  • HTTP: Hono, with route groups mounted under a versioned prefix (e.g. /api/v1).
  • Data: PostgreSQL accessed through a thin store layer; object blobs in S3/MinIO.
  • Build: Vite for any client bundle, tsc for the server, Vitest for tests.

Commands

  • npm run typecheck — tsc -b across the workspace. Run before every commit.
  • npm test — Vitest. Add or update a test with every behavior change.
  • npm run build — production build (client bundle + server compile).
  • Prefer fixing the smallest unit and re-running the narrowest test first.

Project layout

  • src/server/app.ts — wires middleware, static assets, and route groups.
  • src/server/routes/* — one file per resource; export a Hono sub-app.
  • src/server/db/* — store interfaces and their Postgres implementations.
  • src/server/middleware/* — auth, CORS, rate limiting, security headers.
  • src/client/* — the browser app, built separately and served as static files.

Conventions

  • Surgical changes. Touch only what the task requires; match the surrounding style. Remove imports/symbols your change orphans, not pre-existing dead code.
  • Validate at the edge. Parse and validate request bodies before any handler reads them; cap body size and rate-limit per client IP.
  • Public vs authed. Keep unauthenticated read routes separate from routes that require a bearer token, and never skip rate limiting for an authenticated skip rule.
  • Immutable content, strong validators. Serve content-addressed payloads with a long-lived cache and an ETag derived from a content hash for cheap revalidation.
  • Best-effort side effects. Fire-and-forget outbound calls (search-engine pings, status flips) so they never block or fail the primary response.

Pull requests

  • One logical change per PR; explain the why, not just the what.
  • Green typecheck and tests are required. State what you verified.