iron-proxy AGENTS.md

AGENTS.md

Guidance for AI coding agents working in this repo. Optimized for the review and implementation flow used by /review, /security-review, and similar tools.

Repo at a glance

• Single Go module: github.com/ironsh/iron-proxy (Go 1.26+).
• One binary: cmd/iron-proxy (the MITM egress proxy).
• Core packages live under internal/. The transform pipeline lives in internal/transform/ with one subpackage per transform (allowlist, secrets, bodycapture, headerallowlist, annotate, judge, grpc, hmacsign, oauth, awsauth, gcpauth).
• Integration tests against real backends (AWS, 1Password, GCP, Postgres, gRPC, MCP) live in integration_test/. Unit tests sit next to the code they exercise.

The README is the source of truth for product behavior. When in doubt about intended behavior, read it before changing code.

Go conventions

• Use github.com/stretchr/testify/require for assertions. Never t.Errorf / t.Fatalf for value comparisons when require.Equal would do.
• Table-driven tests are the default for any function with more than two meaningful input shapes. Name the table cases or tests, iterate with t.Run(tc.name, ...).
• require.NoError(err) on every error returned from a function under test. Never silently ignore errors. In tests, the only acceptable place to drop an error is inside a background goroutine (e.g. an HTTP handler) and it must use _ with a comment explaining why the error is unreachable or irrelevant.
• Production code: never silently swallow errors. If an error truly cannot occur, suppress with _ and a one-line comment stating why.
• Respect context.Context on every network or I/O call. Background goroutines need an explicit lifecycle (shutdown channel, context, or errgroup).
• Prefer the standard library and the existing dependencies in go.mod over adding new ones.

Simplicity

• Aim for the smallest change that solves the problem. Don't add features, abstractions, or configuration knobs the task didn't ask for.
• Don't design for hypothetical future requirements. Two similar code blocks are fine; if the same shape appears a third time, factor a helper and update the call sites in the same change.
• Prefer deleting code over adding it. If a refactor leaves dead branches, unused config fields, or backwards-compat shims behind, remove them.
• No premature interfaces. Introduce an interface when a second concrete implementation actually exists, not in anticipation of one.