go-qr
AGENTS.md69 starsChanged 39 days agoMITView on GitHub
These rules apply to every change made with an AI assistant in this repository. CONTRIBUTING.md has the full contributor guide; where the two differ, this file is the stricter one. To work across modules against the local library, create the ignored workspace once: go work init . ./tools ./demo ./mcp. Run, from the repository root, and fix everything they report: - Every bug fix and behavior change comes with a test next to the code it covers. Exported API needs…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository3 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- perf-checkSkill
- releaseSkill
The file
We split this AGENTS.md into the rules it gives an agent
10 rules. About 0 are common, 6 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 21
Run, from the repository root, and fix everything they report:
- Very specific: line 32
Every bug fix and behavior change comes with a test next to the code it covers.
- Very specific: line 35
When you touch the encoder, renderer, decoder or payload parser, run the matching fuzz target for at least a minute, for example go test …
- Distinctive: line 38
Never weaken, skip or delete a test to make a change pass.
- Very specific: line 52
Run the sweeps for decoder changes locally, in tools with the workspace: go test -run=TestRobustness -v ./bench/ -sweep.
- Very specific: line 54
If a feature makes the default path clearly slower, say so with numbers and evaluate whether to drop it or make it opt-in.
- Distinctive: line 61
Update these in the same pull request as the code:
- Distinctive: line 79
Never create tags or GitHub releases, and never push to main.
- Distinctive: line 103
Do not vendor test images or datasets whose license is unclear, such as the BoofCV QR Code dataset.
- Distinctive: line 105
Do not copy code from other QR Code libraries.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Instructions for AI coding assistants
These rules apply to every change made with an AI assistant in this repository. CONTRIBUTING.md has the full contributor guide; where the two differ, this file is the stricter one.
Repository
| Module | Path | Notes |
github.com/piglig/go-qr/v2 | / | The library. Go 1.23. Standard library only: never add a dependency. |
github.com/piglig/go-qr/tools | tools/ | generator CLI, verify, bench comparisons. Pins a released library version. |
github.com/piglig/go-qr/mcp | mcp/ | go-qr-mcp server. Go 1.25. Pins a released library version. |
github.com/piglig/go-qr/demo | demo/ | WebAssembly playground. |
To work across modules against the local library, create the ignored
workspace once: go work init . ./tools ./demo ./mcp.
Before you call a change done
Run, from the repository root, and fix everything they report:
gofmt -l . # must print nothing
go vet ./...
go test ./...
(cd tools && go vet ./... && go test ./...)
(cd mcp && go vet ./... && go test ./...)
go run honnef.co/go/tools/cmd/staticcheck@latest ./...- Every bug fix and behavior change comes with a test next to the code it
covers. Exported API needs a doc comment and an example in
example_test.go. - When you touch the encoder, renderer, decoder or payload parser, run the
matching fuzz target for at least a minute, for example
go test -run='^$' -fuzz='^FuzzDecodeNoPanic$' -fuzztime=1m .. - Never weaken, skip or delete a test to make a change pass.
Performance and accuracy
CI compares every pull request with its base: benchmark time and allocations, and the decode rates of the synthetic distortion sweeps (see CONTRIBUTING.md). Passing it is necessary, not sufficient:
- A change to a hot path (encoding, rendering,
Decode) needs before and after numbers from the same machine in the pull request: several alternating runs ofgo test -run='^$' -bench=<name> -benchmem, compared with benchstat orgo run ./regress benchintools. Build the "before" side in a separategit worktree, not by checking out files. - Run the sweeps for decoder changes locally, in
toolswith the workspace:go test -run=TestRobustness -v ./bench/ -sweep. - If a feature makes the default path clearly slower, say so with numbers
and evaluate whether to drop it or make it opt-in. Do not hide it, and
never add the
accept-regressionlabel yourself; a maintainer decides. - Report measured results only. If you did not run a benchmark, say so.
Documentation and changelog
Update these in the same pull request as the code:
- the relevant guide under
docs/, marking new features Since vX.Y with the next release; CHANGELOG.mdunder## [Unreleased], in the existing style, for everyfeat,fixandperfchange. CI fails without it.
Pull requests
- One logical change per pull request. Titles follow Conventional Commits
(
feat,fix,perf,refactor,docs,style,test,ci,chore, optional scope,!for breaking changes); CI checks them. - Pull requests are squash-merged; the title becomes the commit message.
- The description says what changed, why, how it was tested, and the performance impact.
Releases
Never create tags or GitHub releases, and never push to main; tags are
protected and only the release workflow creates them. Start a release only
when a maintainer asks, and then only through the steps in
CONTRIBUTING.md:
- the library:
scripts/release.shto see the suggested version, thenscripts/release.sh X.Y.Zto open the release pull request; toolsandmcp: merging the Dependabot pull request that bumps their library pin releases them. Do not add CHANGELOG entries for these bumps; their releases carry their own notes.
Claude Code
The project settings in .claude/ add:
/release, the release steps, for a maintainer to start;/perf-check, the before-and-after measurement for hot-path and decoder changes;- a hook that blocks creating tags or releases and pushing to
main.
Other assistants follow the same rules from this file.
Data and licenses
- Do not vendor test images or datasets whose license is unclear, such as the BoofCV QR Code dataset; tests download or point to them instead.
- Do not copy code from other QR Code libraries. Follow the standard (ISO/IEC 18004) and published papers, and cite them.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

