Skip to content

AGENTS.md

Latest commit

 

History

History
66 lines (55 loc) · 2.77 KB

AGENTS.md

File metadata and controls

66 lines (55 loc) · 2.77 KB

Agent Guide

Read CONTRIBUTING.md first. It contains all the conventions, writing principles, API patterns, and known gotchas that govern this repository. Everything below is supplementary — rules that are specific to AI coding agents and don't apply to human contributors.

Before you start

  1. Confirm schema.json and elastic-start-local/ exist (they are symlinks, not checked in). If missing, ask the user for paths.
  2. Confirm the Elasticsearch server is reachable: 
    source elastic-start-local/.env
curl -s -u "elastic:$ES_LOCAL_PASSWORD" "$ES_LOCAL_URL"
  3. Seed test data: python scripts/seed.py

Workflow rules

  • Always test before writing. Run the code against the live server before creating or editing a markdown file. Do not guess whether an API call works.
  • Test all seven languages for every endpoint. Use the scripts in scripts/test-*.sh. Do not skip a language because it is harder to test.
  • Seed before each test session. Run python scripts/seed.py to ensure the products index is in a known state.
  • Clean up after tests. Delete any indices your tests created beyond the standard set. Run python scripts/seed.py --clean when finished.
  • Do not run long-lived or background processes. No watch, npm run dev, or similar.
  • Do not modify schema.json or elastic-start-local/. These are external symlinks.
  • Do not commit .venv/, node_modules/, or other local tooling. These are in .gitignore.

Writing files

  • Write one endpoint × all seven languages in a batch. Do not leave an endpoint partially covered.
  • Define section headings with the first language (typically Python), then replicate them exactly across the other six.
  • Use the CONTRIBUTING.md "Language-specific v9 API reference" section as your starting point. It contains tested, correct patterns for every language. Do not guess API shapes — the Java, Go, and .NET clients have non-obvious type requirements documented there.
  • Consult the "Known gotchas" section in CONTRIBUTING.md before writing Java, Go, or .NET examples. The most common errors (wrong Script builder method, wrong Params type, wrong Float64 pointer usage) are documented there with fixes.

Testing strategy

The most efficient approach, in order:

  1. Python first — fastest feedback loop, runs locally
  2. JavaScript — also local, quick
  3. Ruby and PHP in parallel — both use Docker, can run concurrently
  4. Go — local but needs go mod tidy (a few seconds)
  5. Java — Docker + Maven, slowest (~60s), run last
  6. .NET — local dotnet run, moderate speed

When a compile or runtime error occurs in a statically typed language, check CONTRIBUTING.md "Known gotchas" before debugging from scratch.