docs: add AGENTS.md orientation for AI agents - #149
Merged
Conversation
The purpose of this tool is not recoverable from the code, and reading it the obvious way gets it wrong. Dangling CNAME detection is visible and prominent, so it reads as the point; the cloud IP matching looks like an attribute. It is the other way round in value. A dangling CNAME names a service, so intent can be read from DNS. A bare A record does not. If the address is a released cloud IP, whoever allocates it next controls what is served for that hostname, and DNS gives no signal that this is so. Finding which A records land in cloud ranges worth grinding, and where, is the differentiator. That makes provider, region and service the essential payload rather than decoration, and it makes the output files machine-readable interfaces for a downstream tool rather than reports. Also records the boundary that this tool identifies targets and never claims them, the two correctness rules recovered from shipped bugs, the output contracts, the environment traps (broken interpreter shim, both requirements files), the conventions that have bitten before (never tag, do not bump VERSION per PR, secret scanning is strict, branch protection wants job names), and the accepted limitations that follow from staying DNS-only. Named AGENTS.md as that is the file OpenAI Codex looks for at repo root. Co-Authored-By: Claude Opus 5 <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.
Adds
AGENTS.mdat repo root — the file OpenAI Codex looks for — so an agent picking this project up starts from the right premise.Why
The purpose of this tool is not recoverable from the code, and the obvious reading gets it wrong. Dangling CNAME detection is prominent in the README and the class names, so it reads as the point, and the cloud IP matching looks like a secondary attribute. In value it is the other way round.
A dangling CNAME names a service, so intent can be read straight from DNS. A bare A record cannot. If that address is a cloud IP the owner released, whoever allocates it next controls what is served for that hostname — and DNS offers no signal that this is the case. Establishing which A records land in cloud ranges worth grinding, and in which region, is the part other tooling does not do.
Two consequences follow, and neither is obvious from the source:
This misreading is not hypothetical. A full codebase review was carried out against the wrong value proposition and had to be reframed.
Contents
self_referentialonly applies below the top of a CNAME chainVERSIONper PR, secret scanning is strict, branch protection requires job names rather than workflow namesfeat/cloud-region-serviceDocumentation only. No source changed; baseline and full suite pass.