|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +This file provides repository-specific guidance for AI coding agents working on httpsig. |
| 4 | + |
| 5 | +## Project context |
| 6 | + |
| 7 | +`httpsig` implements HTTP Message Signatures (RFC 9421) and uses HTTP Structured Fields (RFC 8941, via `httpsfv`). |
| 8 | + |
| 9 | +## Scope and design |
| 10 | + |
| 11 | +- `httpsig` implements security related code. **Every change must be reviewed for security implications, without exception.** |
| 12 | +- Before editing, read the relevant source, tests, `README.md`, and `go.mod`. |
| 13 | +- Understand the requested behavior and, when changing existing behavior, compare the branch with `main`. Distinguish branch-introduced regressions from pre-existing issues. |
| 14 | +- Make the smallest coherent change. Do not include unrelated bug fixes, refactorings, dependency updates, or performance work; report those separately. For analysis-only requests, do not edit files or create patches unless asked. |
| 15 | +- Follow existing naming, formatting, file organization, error handling, and option patterns. Avoid unrelated formatting changes. |
| 16 | +- Apply SOLID pragmatically: keep responsibilities clear and abstractions justified by actual needs. Prefer readable, straightforward code (KISS before DRY); reuse existing mechanisms rather than introducing speculative interfaces or helpers. |
| 17 | +- Preserve public API compatibility unless explicitly asked otherwise, including option behavior, error contracts, and serialized representations. |
| 18 | +- Do not edit generated mocks manually or change `go.mod` / `go.sum` just to accommodate a local environment. |
| 19 | +- Preserve the library's framework independence and its `Message` abstraction. |
| 20 | + |
| 21 | +## RFC compliance and security |
| 22 | + |
| 23 | +- Check protocol-related changes against the relevant RFC text, not only existing tests or behavior on `main`. Explain consequential design decisions in terms of the applicable requirement. |
| 24 | +- Validate before lossy conversion: preserve parameter presence, types, and values until the relevant checks are complete. |
| 25 | +- Respect the API contracts for Structured Fields component identifiers and any supported simplified configuration syntax. |
| 26 | +- Never relax signature, component, timestamp, nonce, algorithm, or key validation merely to satisfy tests. Assess security and compatibility implications explicitly. |
| 27 | + |
| 28 | +## Test design |
| 29 | + |
| 30 | +- Each unit test function should cover the meaningful positive and negative branches of its own target function or method. Higher-level tests should exercise that function's orchestration and error propagation, not duplicate detailed validation tests of its dependencies. |
| 31 | +- Extend existing test functions where possible. Add only cases for new behavior, regressions, or genuinely uncovered edges; avoid overlapping scenarios. |
| 32 | +- Use table-driven tests only when they improve clarity. Keep cases independently understandable without unnecessary helpers or abstraction (KISS before DRY). |
| 33 | +- Put end-to-end signing, verification, and cross-API round trips in integration tests rather than repeating entire workflows in unit tests. |
| 34 | +- Assert observable contracts, including partial results and error identity or wrapping (`errors.Is` where appropriate), rather than incidental implementation details. |
| 35 | +- Treat coverage as a diagnostic, not a target percentage. Inspect whether changed functions' meaningful branches have appropriate tests. |
| 36 | +- Use `integration_test.go` for cross-API workflows and `rfc_vectors_test.go` for RFC test vectors. |
| 37 | + |
| 38 | +## Performance |
| 39 | + |
| 40 | +- Prioritize the common case: one signature and typically no more than ten covered components. Two or three signatures occur occasionally; many signatures or components may be attacker-controlled. |
| 41 | +- For changes to existing hot paths, compare equivalent inputs on the branch and `main`. Measure latency, allocations, and bytes allocated across repeated runs before drawing conclusions. |
| 42 | +- Avoid unnecessary processing of unselected signatures and pathological scaling for untrusted inputs, without weakening required parsing or validation. Do not trade simplicity for marginal or unrelated optimizations. |
| 43 | + |
| 44 | +## Validation and delivery |
| 45 | + |
| 46 | +- Follow the repository's formatting and `.golangci.yaml` configuration, including configured use of `gofmt`, `gofumpt`, `goimports`, and `gci`. |
| 47 | +- Run focused tests for changed code, then, when the environment allows: |
| 48 | + |
| 49 | + ```sh |
| 50 | + go test -count=1 ./... |
| 51 | + go test -race -count=1 ./... |
| 52 | + go vet ./... |
| 53 | + golangci-lint run |
| 54 | + git diff --check |
| 55 | + ``` |
| 56 | + |
| 57 | +- Use the Go version and dependencies declared by the project/CI. Report any unavailable checks and the environment actually used; never claim a check passed without running it. |
| 58 | +- Update Go documentation and the README when public behavior changes, without unrelated rewrites. |
| 59 | +- Before handoff, review the diff for scope, compatibility, RFC implications, test ownership, and unintended edits. Summarize changes, checks performed, and remaining trade-offs. |
| 60 | +- Use short, imperative English PR titles suited to release notes and the repository's semantic PR conventions (`.github/semantic.yml`). |
| 61 | +- Provide incremental patches against the agreed baseline when requested. Do not commit unless explicitly asked. |
0 commit comments