From 06220a856fb1f0dabd4ecfdf55a6ff61d15ab1f8 Mon Sep 17 00:00:00 2001
From: kartik <kartik.rajput622001@gmail.com>
Date: Wed, 1 Jul 2026 19:48:12 +0530
Subject: [PATCH] docs: add AGENTS.md (replaces untracked CLAUDE.md)

Commit the repo working guide as AGENTS.md, the vendor-neutral convention read
by Claude Code and other agent tools. Refresh it against the current codebase:

- make lint now runs with --build-tags=integration; note that go test/vet and a
  plain golangci-lint run skip integration-tagged files.
- Document the RabbitMQ 4 constraint: transient non-exclusive queues are
  rejected, so declared queues must be durable or exclusive.
- Expand the "keep versions in sync" note to cover goimports and the RabbitMQ
  image, in addition to golangci-lint.
---
 AGENTS.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..0b6dfa2
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,57 @@
+# AGENTS.md
+
+Guidance for working in this repo. See `CONTRIBUTING.md`, `Makefile`, and
+`.coderabbit.yaml` for more detail; this file only captures the non-obvious bits.
+
+## What this is
+
+`rabbitwrap` is a public Go library wrapping `github.com/rabbitmq/amqp091-go`.
+
+- Module path: `github.com/KARTIKrocks/rabbitwrap`
+- **Package name is `rabbitmq`** (not `rabbitwrap`), so imports look like
+  `import rabbitmq "github.com/KARTIKrocks/rabbitwrap"`.
+
+## Commands
+
+- `make test` — unit tests with the race detector (`go test -race`).
+- `make lint` — golangci-lint, run with `--build-tags=integration` so it also
+  lints the integration-tagged files (installs golangci-lint via `make setup`
+  if missing).
+- `make ci` — vet + lint + test.
+- `make fmt` — goimports.
+
+### Integration tests (non-obvious)
+
+Integration tests are gated behind the `integration` build tag and require a
+live RabbitMQ:
+
+```bash
+make docker-up            # start RabbitMQ via docker-compose (waits for healthy)
+make test-integration     # go test -race -tags=integration ./...
+make docker-down
+```
+
+They read `RABBITMQ_URL` (default `amqp://guest:guest@localhost:5672/`). Plain
+`go test ./...` does NOT run them — you must pass `-tags=integration`. Note that
+`go test`, `go vet`, and a plain `golangci-lint run` all **skip** `integration`-tagged
+files, so use `make lint` / `make test-integration` to actually exercise them.
+
+CI and `docker-compose.yml` run **RabbitMQ 4** (`rabbitmq:4-management-alpine`).
+RabbitMQ 4 rejects transient non-exclusive queues (the deprecated
+`transient_nonexcl_queues` feature): any queue you declare must be **durable or
+exclusive**, or the declaration fails with `Exception (541) INTERNAL_ERROR`.
+
+## Conventions
+
+- Public library: keep exported identifiers backward-compatible. Adding exports
+  is a minor version bump; changing/removing them is breaking. Require godoc on
+  all exported identifiers.
+- Concurrency-sensitive: CI runs with `-race`. Watch goroutine lifecycle/leaks,
+  channel closing, mutex usage, and AMQP channel/connection recovery.
+- Wrap errors with context; never silently swallow them. Sentinel errors live in
+  `rabbitmq.go`.
+- Pinned tool/broker versions must stay in sync across files:
+  - `golangci-lint` — `Makefile` (`GOLANGCI_LINT_VERSION`) ↔ `.github/workflows/ci.yml`.
+  - `goimports` — `Makefile` (`GOIMPORTS_VERSION`).
+  - RabbitMQ image — `docker-compose.yml` ↔ `.github/workflows/ci.yml`.
+- Update `CHANGELOG.md` (Keep a Changelog format) for user-facing changes.