agentleFS
pigligpiglig/go-qr/AGENTS.md

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.

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
  1. Distinctive:

    Run, from the repository root, and fix everything they report:

    line 21
  2. Very specific:

    Every bug fix and behavior change comes with a test next to the code it covers.

    line 32
  3. Very specific:

    When you touch the encoder, renderer, decoder or payload parser, run the matching fuzz target for at least a minute, for example go test …

    line 35
  4. Distinctive:

    Never weaken, skip or delete a test to make a change pass.

    line 38
  5. Very specific:

    Run the sweeps for decoder changes locally, in tools with the workspace: go test -run=TestRobustness -v ./bench/ -sweep.

    line 52
  6. Very specific:

    If a feature makes the default path clearly slower, say so with numbers and evaluate whether to drop it or make it opt-in.

    line 54
  7. Distinctive:

    Update these in the same pull request as the code:

    line 61
  8. Distinctive:

    Never create tags or GitHub releases, and never push to main.

    line 79
  9. Distinctive:

    Do not vendor test images or datasets whose license is unclear, such as the BoofCV QR Code dataset.

    line 103
  10. Distinctive:

    Do not copy code from other QR Code libraries.

    line 105

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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

ModulePathNotes
github.com/piglig/go-qr/v2/The library. Go 1.23. Standard library only: never add a dependency.
github.com/piglig/go-qr/toolstools/generator CLI, verify, bench comparisons. Pins a released library version.
github.com/piglig/go-qr/mcpmcp/go-qr-mcp server. Go 1.25. Pins a released library version.
github.com/piglig/go-qr/demodemo/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 of go test -run='^$' -bench=<name> -benchmem, compared with benchstat or go run ./regress bench in tools. Build the "before" side in a separate git worktree, not by checking out files.
  • Run the sweeps for decoder changes locally, in tools with 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-regression label 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.md under ## [Unreleased], in the existing style, for every feat, fix and perf change. 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.sh to see the suggested version, then scripts/release.sh X.Y.Z to open the release pull request;
  • tools and mcp: 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.