Record project profile and per-agent pointers - #126
Merged
Conversation
AGENTS.md gains two sections that were missing, both filled from what the repository actually declares rather than from convention: - Gotchas & Troubleshooting records that `make check` is not the CI gate, that the first tool and corpus commands need network, that the corpus cache is keyed by commit, and that `test/` builds the real binary. - Verification Map gives stage 7 the table it refers to, so a fix reruns only the gate commands whose inputs it touched. The complete gate is transcribed from `.github/workflows/ci.yml`, which runs more than `make check` does. Every command listed was confirmed by declaration in the Makefile or a committed workflow; none were run to find out. The Development Workflow block is managed by the agent-skills tooling and is committed as generated. CLAUDE.md and GEMINI.md are thin pointers so Claude Code and Gemini both read AGENTS.md as the single source of truth instead of drifting copies. Co-Authored-By: Claude Opus 5 (1M context) <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
1 participant
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.
Documentation only. No product code, no test changes.
What this adds
AGENTS.md— two missing sectionsGotchas & Troubleshooting records things that have actually bitten someone, not invented ones:
make checkis not the CI gate. It isfmt-check vet coverage-check lint, which is whatrelease.ymlruns.ci.ymladditionally runscorpus-smoke,fuzz,build,release-check, andvulnin separate steps and jobs. A greenmake checkdoes not imply a green pull request.go installinto.tools/bin, tarball into.cache/), andmake cleandeletes.tools, so the next lint or vuln run needs it again.internal/corpus.Fetchrefuses a directory holding a different SHA, or one missing.corpus-commit.make coverage-checkruns the whole race suite first, so it is not a cheap check.test/is not a unit tier: it builds the real binary and runstest/scripts/*.basthrough it.Verification Map gives stage 7 the table it already refers to, so a fix reruns only the gate commands whose inputs it touched, with the complete gate transcribed from
ci.yml.The
*.md/docs/**row claims "nothing," which the skill treats as a strong claim, so it states the evidence:go test ./...,go vet ./...andgolangci-lint run ./...collect Go packages only,make fmt-checkglobs-name '*.go', and no Go file in the repository opens a Markdown, YAML, or Makefile path.CLAUDE.mdandGEMINI.mdThin pointers so Claude Code and Gemini both read
AGENTS.mdrather than maintaining drifting copies.Development Workflow
Managed by the agent-skills tooling and committed as generated. Edits inside its markers are overwritten on the next adoption run.
How the commands were confirmed
Every command recorded was confirmed by declaration —
Makefiletargets,.PHONY, and committed workflow steps — plusmake -n checkto verify wiring. Nothing was executed to find out what it does, and nothing is marked<!-- unverified -->because nothing needed to be.Sanity check on the claims
This session exercised the Verification Map in practice across #119–#122, and it held up in a way worth noting: while fixing #119 I ran focused tests over
./pkg/interpreterand./testand missed a stale expectation incmd/go-basic. The complete gate caught it. That is exactly the failure mode the "focused runs do not substitute for the gate" rule exists to prevent.🤖 Generated with Claude Code