gohttpserver/CLAUDE.md

Repository Rules

Last Updated 2026-01-10

These rules MUST be followed at all times, it is very important.

• Do NOT stop working while there are still incomplete TODOs in the todo list or in TODO.md. Continue implementing until all tasks are complete or you are explicitly told to stop.

• Never use git add -A - add specific changes to a deliberate commit. A commit should contain one change. After each change, make a commit with a good one-line summary.

• NEVER modify the linter config without asking first.

• NEVER modify tests to exclude special cases or otherwise get them to pass without asking first. In almost all cases, the code should be changed, NOT the tests. If you think the test needs to be changed, make your case for that and ask for permission to proceed, then stop. You need explicit user approval to modify existing tests. (You do not need user approval for writing NEW tests.)

• When linting, assume the linter config is CORRECT, and that each item output by the linter is something that legitimately needs fixing in the code.

• When running tests, use make test.

• Before commits, run make check. This runs make lint and make test and make check-fmt. Any issues discovered MUST be resolved before committing unless explicitly told otherwise.

• When fixing a bug, write a failing test for the bug FIRST. Add appropriate logging to the test to ensure it is written correctly. Commit that. Then go about fixing the bug until the test passes (without modifying the test further). Then commit that.

• When adding a new feature, do the same - implement a test first (TDD). It doesn't have to be super complex. Commit the test, then commit the feature.

• When adding a new feature, use a feature branch. When the feature is completely finished and the code is up to standards (passes make check) then and only then can the feature branch be merged into main and the branch deleted.

• Write godoc documentation comments for all exported types and functions as you go along.

• ALWAYS be consistent in naming. If you name something one thing in one place, name it the EXACT SAME THING in another place.

• Be descriptive and specific in naming. wl is bad; SourceHostWhitelist is good. ConnsPerHost is bad; MaxConnectionsPerHost is good.

• This is not prototype or teaching code - this is designed for production. Any security issues (such as denial of service) or other web vulnerabilities are P1 bugs and must be added to TODO.md at the top.

• As this is production code, no stubbing of implementations unless specifically instructed. We need working implementations.

• NEVER silently fall back to a different setting when a user's parameter explicitly specifies a value. If a user requests format=webp and WebP encoding is not supported, return an error - do NOT silently output PNG instead. If a user specifies fit=invalid and that fit mode doesn't exist, return an error - do NOT silently default to "cover". Silent fallbacks violate the principle of least surprise and mask bugs. The only acceptable defaults are for OMITTED parameters, never for INVALID explicit values.

• Avoid vendoring deps unless specifically instructed to. NEVER commit the vendor directory, NEVER commit compiled binaries. If these directories or files exist, add them to .gitignore (and commit the .gitignore) if they are not already in there. Keep the entire git repository (with history) small - under 20MiB, unless you specifically must commit larger files (e.g. test fixture example media files). Only OUR source code and immediately supporting files (such as test examples) goes into the repo/history.