Skip to content

Commit 1a04722

Browse files
authored
docs: AGENTS.md added (#188)
1 parent 8cfca80 commit 1a04722

1 file changed

Lines changed: 61 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
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

Comments
 (0)