Skip to content

AGENTS.md

Latest commit

 

History

History
134 lines (100 loc) · 6.06 KB

AGENTS.md

File metadata and controls

134 lines (100 loc) · 6.06 KB

AGENTS.md

This guide helps coding agents make safe, high-signal changes in this repository.

Primary goals

  1. Keep API behavior stable unless a task explicitly requests behavior changes.
  2. Treat generated data schema and runtime query assumptions as coupled contracts.
  3. Keep PHP and AWS implementations behaviorally aligned unless the user explicitly approves divergence.
  4. Prefer minimal, targeted edits over broad refactors.

Repository orientation

  • data/: ETL pipeline and SQL import scripts to generate database used by all endpoints
  • php/: PHP endpoint scripts
  • aws/: runtime and deployment config for an AWS = Lambda endpoint
  • README.md: top-level onboarding and documentation index

Safe-edit boundaries

  • Do not change output column names/order in generated CSVs without updating import SQL and runtimes.
  • Do not change endpoint paths or required query parameters unless explicitly requested.
  • Do not change behavior in only one runtime without checking whether the other runtime must be updated too.
  • Treat README.md as the canonical API contract for shared endpoint behavior.
  • Do not add dependencies unless required by the task.
  • Do not modify licensing text unless the task is licensing-focused.

Build and test commands

Generate data

cd data && ./generate
sqlite3 data.sqlite < data/import-sqlite.sql   # or import-postgres.sql for Postgres

Syntax validation

node --check aws/handler.js
bash -n data/generate
php -l php/reverse_geocode.php php/geocode.php php/ip2country.php

Test AWS handler locally

Requires data.sqlite placed at aws/data/data.sqlite (see aws/README.md).

cd aws && node test.js

Test PHP endpoints locally

Requires a running PHP server with data.sqlite path configured in each script.

curl "http://localhost:8080/reverse_geocode.php?lat=51.5&lon=-0.09"
curl "http://localhost:8080/geocode.php?q=London"
curl "http://localhost:8080/ip2country.php?ip=8.8.8.8"

Common task playbooks

Update docs for endpoint behavior

  1. Confirm behavior in implementation files first.
  2. Update README.md first when the shared API contract changes.
  3. Update runtime-specific docs (php/README.md, aws/README.md) for setup or runtime-specific differences.
  4. Update root index links if new docs are added.

Modify data generation logic

  1. Update data/generate.
  2. Verify expected output files and schema assumptions.
  3. Update data/PIPELINE.md and data/README.md for changed flow.
  4. Ensure PHP and AWS query logic still matches generated formats.

Modify runtime behavior

  1. Check whether the same change must be made in both php/ and aws/.
  2. If the implementations intentionally diverge, document the reason in README.md and the runtime-specific README.
  3. Keep parameter validation and error status conventions explicit.
  4. Keep docs and examples in sync with code in same change.
  5. Validate one positive and one negative request path per changed endpoint in every affected runtime.

Change database schema or column names

  1. Update data/generate and any generated CSV column order/names intentionally.
  2. Update data/import-sqlite.sql and data/import-postgres.sql to match the new schema.
  3. Update every affected query in php/ and aws/handler.js before considering the change complete.
  4. Update README.md if response field names, examples, or shared data-model docs changed.
  5. Validate one positive and one negative request path per affected endpoint in both runtimes.

Verify endpoint behavior consistency across runtimes

  1. For every changed shared endpoint, prepare matching PHP and AWS requests for: valid input, invalid input, and one edge or empty-result case.
  2. Compare status codes, response field names, JSON structure, and fallback behavior between runtimes.
  3. If behavior differs intentionally, document the reason in README.md and the relevant runtime README.
  4. Do not hand off a shared endpoint change without confirming PHP and AWS still match the documented contract.

Update shared validation rules

  1. Update the canonical rule in README.md first when shared validation behavior changes.
  2. Update the matching validation logic in both php/ and aws/handler.js.
  3. Keep error status conventions aligned across runtimes for the same invalid input.
  4. Validate boundary values and malformed input in both runtimes before handoff.

Modify query logic or ranking algorithms

  1. Identify whether the change affects search ordering, reverse-geocode candidate selection, or IP lookup behavior.
  2. Update the equivalent logic in both php/ and aws/handler.js unless the user explicitly approves divergence.
  3. Update README.md if the visible behavior, ranking rules, or fallback rules changed.
  4. Validate with the same dataset and inputs in both runtimes, checking result ordering as well as response shape.

Add a new endpoint implementation

  1. Add a new top-level folder for the endpoint.
  2. Ensure behaviour of the new endpoint is consistent with other endpoint implementations.
  3. Keep docs and examples in sync with code in same change.
  4. Don't change runtime behaviour at the same time as adding a new endpoint.
  5. Validate one positive and one negative request path for the new endpoint.

Validation checklist before handoff

  • Relevant docs updated in same PR/change set.
  • Shared API behavior in README.md still matches all implementations.
  • PHP and AWS behavior were compared for every changed shared endpoint.
  • All links in edited markdown files resolve.
  • Any changed command examples are runnable as written.
  • Endpoint parameter and response docs match actual runtime behavior.
  • No unrelated files changed.

Definition of done for documentation changes

A docs task is done when:

  1. Root README links users to all relevant subsystem docs.
  2. A new contributor can build data and run at least one runtime without guessing missing steps.
  3. Agent guidance reflects current repo structure and workflows.