# <PROJECT NAME>
#
# ─────────────────────────────────────────────────────────────────────────────
#  AGENTS.md — the canonical, cross-vendor context file
#  QRefAI AI Coding Field Guide, Part 5 (Q5.x)
#
#  This is the OPEN-STANDARD instruction file (agentsmd-style) that every coding
#  agent reads — Claude, Copilot, Codex, and others. Keep it the single source of
#  truth; per-vendor files (CLAUDE.md, copilot-instructions.md) are THIN wrappers
#  over this one.
#
#  ┌── TWO RULES THAT DECIDE WHETHER THIS FILE HELPS OR HURTS ─────────────────┐
#  │ 1. KEEP IT LEAN. The ETH Zurich study (arXiv:2602.11988) found bloated     │
#  │    context files LOWER task success and raise cost >20%. Omit anything the  │
#  │    agent can infer by reading the repo (framework conventions, obvious      │
#  │    structure). Target ~200–300 lines; shorter is usually better.           │
#  │                                                                            │
#  │ 2. SHOW, DON'T TELL. A 3–10 line REAL code snippet from THIS codebase lifts │
#  │    code-reuse ~20% vs. prose description. Where a convention has a concrete │
#  │    shape, paste a short real example instead of describing it.             │
#  └────────────────────────────────────────────────────────────────────────────┘
#
#  The eight sections below are the community-converged set. Keep the headings so
#  the file is predictable across repos; delete a section only if it's truly N/A.
#  Replace every <PLACEHOLDER> and delete these guidance comments before shipping.
# ─────────────────────────────────────────────────────────────────────────────

## Overview
<One short paragraph: what this service does and where it sits in the platform.
Two or three sentences. No marketing — just what an engineer needs to orient.>

## Tech Stack
# PIN VERSIONS. Versions are unguessable and they change agent behavior. This is
# high-value, low-line-count context — exactly what belongs here.
- <LANGUAGE + VERSION,   e.g. Go 1.23>
- <DATASTORE + VERSION,  e.g. PostgreSQL 16>
- <FRAMEWORK + VERSION,  e.g. gRPC 1.62>
- <KEY LIBS w/ versions where the major version matters>
- <DEPLOY TARGET,        e.g. EKS / Lambda / bare metal>

## Setup Commands
# The things the agent genuinely cannot guess. Use your real task runner.
- Install: `<cmd>`
- Build:   `<cmd>`
- Test:    `<cmd>`        # must pass before any commit
- Lint:    `<cmd>`        # CI-enforced — do NOT restate its rules below
- Run:     `<cmd>`

## Code Style
# ONLY conventions the linter/formatter does NOT already enforce. If your linter
# covers it, deleting it here saves budget. Prefer a short real snippet over prose.
#
# Example of the SHOW-DON'T-TELL pattern (replace with a real snippet from your repo):
#
#   // Errors are wrapped with context, never returned bare:
#   if err != nil {
#       return fmt.Errorf("charge %s: %w", chargeID, err)
#   }
#
- <convention 1, with a 3–10 line real example where it has a concrete shape>
- <convention 2>

## Testing
# How tests are organized and run here — only what's non-obvious.
- <e.g. Table-driven tests; one _test.go per package.>
- <e.g. Integration tests behind the `integration` build tag; run with `make test-int`.>
- <e.g. New behavior requires a test; PRs without tests are rejected in review.>

## Architecture Notes
# A HIGH-LEVEL orientation map only — module → purpose. Let the agent discover
# file-level detail itself (that's what AST/graph tools are for). Omit entirely if
# your layout follows a framework convention the agent already knows.
- <e.g. `internal/domain/`    — business logic, no I/O>
- <e.g. `internal/transport/` — gRPC/HTTP handlers, thin>
- <e.g. `internal/store/`     — DB access; all SQL lives here>
- <e.g. Data flow: transport → domain → store; never skip a layer.>

## PR & Commit Guidelines
- <e.g. Conventional Commits (feat:, fix:, chore:).>
- <e.g. PRs require one human approval + green CI; squash-merge only.>
- <e.g. New public endpoints require an entry in `docs/api-changelog.md`.>

## Security Considerations
# Point to skills for the detail; keep the always-on rules to a few lines.
- <e.g. No secrets, tokens, or credentials in source — ever.>
- <e.g. All money is int64 minor units; never floats.>
- <e.g. PII handling per the `pii-handling` skill; audit logging per `regulatory-logging`.>
- <e.g. Never write code that deletes from an audit/ledger table.>

# ─────────────────────────────────────────────────────────────────────────────
#  ROUTING REMINDER (delete before shipping):
#  Always-true & short  → keep it here.    "How we do X" playbook → a SKILL.
#  100-line checklist   → skill reference. A worker with a role   → a subagent.
#  If a section above grew long, that length is a signal it should be a skill.
# ─────────────────────────────────────────────────────────────────────────────