Add AGENTS.md (contributor guide) and CLAUDE.md import#34
Open
dolph wants to merge 2 commits into
Open
Conversation
AGENTS.md is a contributor guide for humans and AI agents working in the repo. It documents: - The project's purpose and minimal CLI surface - The exact dev loop: gofmt, vet, build, test -race, build.sh - TDD discipline with Go-specific guardrails (hermetic tests, t.Helper, log.Fatal vs t.Fatal, checklist theater) - Code style — fmt.Errorf %w, modern stdlib, defer Close, no math/rand in filesystem paths, no log.Fatal from goroutines - Repo conventions for branch names, commit subjects, PR refs - Mandatory release:* and priority:* label rubrics - Known traps cross-referenced to open issues - Scope discipline — single-purpose PRs CLAUDE.md imports AGENTS.md via Claude Code's @-syntax so both files share one source of truth.
dolph
commented
May 16, 2026
|
|
||
| ## What this project is | ||
|
|
||
| `find-replace` is a small Go CLI (~400 LoC, single binary) that recursively |
Owner
Author
There was a problem hiding this comment.
The LoC assertion will not age well - remove
Per review feedback on #34: the '~400 LoC' figure won't age well as the codebase grows. Keep the 'single binary' descriptor which stays true.
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 an
AGENTS.mdcontributor guide for humans and AI agents working inthe repo, plus a one-line
CLAUDE.mdthat imports it so Claude Code andother agent harnesses share a single source of truth.
AGENTS.mddocuments:find-replaceis and its minimal CLI surface(
find-replace FIND REPLACE, no flags yet — see Build-time version metadata is injected via -ldflags but never referenced; no --version flag #26).gofmt -l .,go vet ./...,go build ./...,go test -race ./...commands plus./build.sh. The-raceflag is called out as non-negotiable.reason → minimal fix → refactor green. Go-specific warnings on
hermeticity (
t.TempDir),t.Helper(),t.Fatalvslog.Fatal(cross-refs Test helpers use
log.Fatal(kills test binary), assertion helpers lackt.Helper(), andTestNewFileis empty #33), table-driven tests, and the checklist theateranti-pattern.
fmt.Errorfwith%w, modern stdlib (os.ReadFile,strings.ReplaceAll,errors.Is), HTTP body close,context.Contextplumbing rule,
log/slogfor new structured logging, nomath/randin filesystem paths (Predictable temp-file names enable a symlink/race attack on file rewrites #3), no
log.Fatalfrom goroutines (log.Fatal from worker goroutines leaves the tree in a partially-modified state #6).subjects,
Fixes #Nin PR descriptions.release:skip|patch|minor|majoron everyPR (release workflow defaults to
patchif unlabeled), withprecedence
skip > major > minor > patch.priority: critical|high|medium|lowrubricmirroring how the existing 22+ issues are already labeled.
cross-referenced to its issue — concurrent walker,
os.Statfollowssymlinks,
os.Renamesilently overwrites,O_CREATEvsO_EXCL,log.Fatalfrom goroutines, naïve binary detection, dead-ldflags.new issue rather than expanding the current PR.
CLAUDE.mdcontains literally@AGENTS.md(Claude Code's import syntax)so the two share one source of truth and won't drift.
Test plan
go vet ./...passes (no behavior changes)go build ./...passesgo test -race ./...passes (no behavior changes)CLAUDE.mdimport syntax (@AGENTS.mdis the Claude Codefile-import directive)
Labeled
release:skip— documentation only, no user-visible behaviorchange. Subsequent work depends on this landing first so contributors
(human and AI) follow the documented conventions from day one.
Generated by Claude Code