Add AGENTS.md and CLAUDE.md to guide AI coding assistants#45
Merged
Conversation
AGENTS.md is the canonical guidance file (tool-agnostic convention). CLAUDE.md imports it via @AGENTS.md so Claude Code reads the same content. The guide covers project structure, dev loop, code style, repo conventions, label/priority rubric, scope discipline, and a short list of "known traps" tied to currently open issues so agents do not reintroduce them. Also ignore .claude/ — the worktree directory created by Claude Code's agent isolation feature should never be committed. https://claude.ai/code/session_01WjHPSobuzrRkjwUgjAJWMk
Adds a focused TDD section between the dev loop and code-style guidance: write the failing test first, confirm it fails for the right reason, make the smallest change to pass, refactor while green. Includes Go-specific notes on table-driven tests, hermetic fixtures via t.TempDir, descriptive test names, and an explicit escape hatch for fixes whose surrounding code has no testable seam yet (note in the PR Test Plan and file a follow-up). The section ends with a warning against checklist-theater tests that call the function and t.Fatal on errors without asserting on outputs, because those give false confidence. https://claude.ai/code/session_01WjHPSobuzrRkjwUgjAJWMk
3 tasks
dolph
added a commit
that referenced
this pull request
May 16, 2026
The release workflow defaults to a patch bump when a merged PR has no release:* label. Docs-only PR #45 and test-only PR #50 were both opened unlabeled because AGENTS.md only mentioned the labels exist without instructing agents to apply one. #45 likely cut an empty patch release; #50 needed retroactive labeling before merge. Replace the passing mention with a short rubric covering when to use skip / patch / minor / major, and an explicit "before merge" deadline so future agents pick exactly one. https://claude.ai/code/session_01WjHPSobuzrRkjwUgjAJWMk Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
AGENTS.mdandCLAUDE.mdso AI coding assistants (and human contributors) operating in this repo have a short, consistent reference for project structure, dev workflow, code style, and repository conventions.AGENTS.mdis the canonical guidance file (tool-agnostic convention adopted across the industry).CLAUDE.mdis a one-line@AGENTS.mdimport so Claude Code reads the same content without duplication.The guide includes:
package mainsource layout.go vet,gofmt -l,go build,go test -race) and a heads-up that some tests inresolver_test.go/router_test.goreach the real network (Tests aren't hermetic and major modules are untested; production code is hard to test #24).fmt.Errorfwith%w,os.ReadFile,net.JoinHostPort, HTTP requests withTimeout+ body close,context.Contextplumbing,log/slogfor new structured logging.claude/<slug>branch naming, imperative commit subjects under 72 chars,Fixes #Nin PR bodies, therelease:patch|minor|major|skiplabel semantics consumed by.github/workflows/release.yml.priority:critical|high|medium|lowlabels in use on the repo.ParseDestinationssilently drops the first URL when loaded from a config file #5, Statsd YAML config is silently ignored and corrupts URL parsing #6, HTTP/HTTPS check accepts non-2xx responses, leaks response body, and has no timeout #7, IPv6 is silently dropped; IPv6-only destinations report success without being checked #10, Statsd emitter can stall checks when statsd is down; opens a new connection per metric #11,routing.New()panics on non-Linux —check/wait/monitorcrash on macOS/Windows/BSD #34).Also ignores
.claude/in.gitignore— that's the worktree directory created by Claude Code's agent-isolation feature and should never be committed.Test Plan
AGENTS.mdreads cleanly as Markdown (verified locally).CLAUDE.mduses Claude Code's documented@<path>import syntax pointing atAGENTS.md.git statusis clean after.claude/is gitignored.No code changes; documentation and gitignore only.
https://claude.ai/code/session_01WjHPSobuzrRkjwUgjAJWMk
Generated by Claude Code