AGENTS.md

1# AI Agent Instructions for BirdNET-Go
2 
3These instructions apply to all AI coding agents working on this repository,
4regardless of tool (Claude Code, Codex, Cursor, Gemini, Windsurf, Copilot, etc.).
5 
6## PR Scope Rule
7 
8Each pull request must contain exactly ONE of:
9- One feature
10- One bug fix
11- One refactor
12 
13PRs that batch multiple features or multiple fixes WILL NOT be merged.
14This is non-negotiable. If your task involves multiple independent changes,
15split them into separate branches and separate PRs.
16 
17If you are uncertain whether changes constitute one concern or multiple,
18ask the user before proceeding.
19 
20Why: batched PRs cannot be properly reviewed, cannot be safely reverted
21if one change causes a regression, and create merge conflicts for other
22contributors.
23 
24## Mandatory: Pre-Push Quality Gate
25 
26Before pushing code or creating a pull request, you MUST execute the
27preflight quality gate defined in `.agents/skills/preflight/SKILL.md`.
28 
29Read that file and follow its complete process (all phases).
30Do not skip this step. Do not push without running it first.
31 
32If your platform supports native skill invocation (e.g., Claude Code's
33`/preflight` or Codex's skill system), use that. Otherwise, read the
34SKILL.md file directly and execute the review process.
35 
36## PR Creation Rules
37 
38When creating a pull request, you MUST:
39 
401. Verify this PR addresses exactly ONE feature, fix, or refactor
412. Include a "Preflight Status" section in the PR description showing
42   what was found and fixed during preflight
433. Verify all linters pass (`golangci-lint run -v`, `npm run check:all`)
444. Verify all tests pass (`go test -race ./...`, `npm test`)
455. Confirm the diff contains ONLY changes relevant to the stated goal
466. Confirm scope is complete (no TODO/FIXME for core functionality)
477. Confirm no secrets, credentials, or PII in the diff
488. Document any breaking changes to API, config, or behavior
49 
50You MUST actually execute verification commands (linters, tests) and
51observe passing output before claiming they pass. Do not check boxes
52based on assumption or prior knowledge.
53 
54PRs missing the preflight certification will require multiple review
55rounds. The gate catches the same issues reviewers find; running it
56locally saves a day of back-and-forth.
57 
58## Interpreting CI Failures
59 
60The `golangci-test` workflow runs Go tests through `gotestsum` with one
61automatic rerun of any failed test, then publishes a consolidated result in the
62`test-report` job. Before assuming a red run means your code is broken:
63 
641. Read the `test-report` job summary. It states one verdict:
65   - `REGRESSION` - real failures that persisted after a rerun. Fix these.
66   - `PASS (with flakes)` - tests that failed once then passed on rerun. These
67     are flaky/infra (a reaped container, a registry blip), NOT a code
68     regression. Do not "fix" them; re-run or report instead.
69   - `PASS` - all green.
702. For machine-readable detail, download the `ci-failures` artifact:
71   - `ci-failures.json` - array of real regressions (`{pkg, test, output}`).
72   - `ci-flaky.json` - tests that passed on rerun (informational).
73   Prefer reading these small files over scrolling the raw multi-thousand-line
74   logs.
753. If a testcontainer job failed, the job summary includes a "Testcontainer
76   diagnostics" block (docker state, memory, OOM kills) to distinguish an
77   infra flake from a logic bug.
78 
79Do not spend time debugging a failure classified as flaky/infra. If a test is
80persistently flaky, raise it rather than patching around it.
81 
82## Project Context
83 
84- Tech stack: Go 1.24+, Svelte 5, TypeScript, Tailwind v4.1
85- Build system: Task (taskfile.dev)
86- Linting: golangci-lint (Go), npm run check:all (Frontend)
87- Testing: go test -race (Go), npm test (Frontend)
88- All PRs receive automated CodeRabbit reviews
89- API v1 is frozen; all new endpoints go in `internal/api/v2/`
90 
91For detailed guidelines, see `CLAUDE.md` and the `CLAUDE.md` files in
92subdirectories (`internal/`, `frontend/`, `internal/api/v2/`).
93