Problem
Topograph does not currently ship guidance for AI coding agents (Codex, Cursor, Copilot, Claude Code, etc.) working in the repository. The lack of agent-authored context means agents have to reverse-engineer conventions from the code, leading to:
- Misunderstood provider/engine boundary (e.g., discovery code added to engines, output formatting added to providers)
- Inconsistent patterns across new provider contributions
- Missed invariants: modifying `pkg/topology/Vertex` without awareness of cross-cutting impact, hand-editing generated protobuf
- DCO sign-off omissions (topograph has no org-member exemption)
This matters more as AI-assisted contribution grows. AGENTS.md has emerged as the de facto convention for guiding AI coding agents in OSS repositories; it pairs with Context 7 indexing for agent discoverability.
Proposed approach
Add two files to the repository, mirroring the pattern established in AICR:
.claude/CLAUDE.md — canonical sourceAGENTS.md — public synced copy; only the first ~5 header lines differ
Structure follows the emerging AGENTS.md 5-part convention:
- Project Overview and Architecture — pipeline, invariants, repository map, "do not change without discussion" surfaces
- Setup and Installation — prerequisites, clone/build, proto regeneration
- Testing and Deployment Workflows — local test loop, coverage policy, CI, deployment surfaces
- Coding Style and Conventions — formatting, provider interface contract, adding a provider, anti-patterns, label/annotation reference pointer
- Pull Request Guidelines — branch naming, conventional commits, DCO sign-off, GPG signing, pre-push checklist, review expectations
Open design choices
- Sync enforcement: AICR enforces canonical→public sync via CI (`make qualify` includes an agents-sync check). This PR does not include a sync check — open to feedback on whether to add one now or defer.
- Scope of "do not change without discussion": current draft lists `pkg/topology/` Vertex tree, `protos/topology.proto`, Helm `global.*` contracts, and the four default label keys. Additions welcome.
Next step after this lands
Submit `NVIDIA/topograph` to Context 7 for LLM-optimized doc indexing — pairs with AGENTS.md for agent discoverability.
Links
Problem
Topograph does not currently ship guidance for AI coding agents (Codex, Cursor, Copilot, Claude Code, etc.) working in the repository. The lack of agent-authored context means agents have to reverse-engineer conventions from the code, leading to:
This matters more as AI-assisted contribution grows. AGENTS.md has emerged as the de facto convention for guiding AI coding agents in OSS repositories; it pairs with Context 7 indexing for agent discoverability.
Proposed approach
Add two files to the repository, mirroring the pattern established in AICR:
.claude/CLAUDE.md— canonical sourceAGENTS.md— public synced copy; only the first ~5 header lines differStructure follows the emerging AGENTS.md 5-part convention:
Open design choices
Next step after this lands
Submit `NVIDIA/topograph` to Context 7 for LLM-optimized doc indexing — pairs with AGENTS.md for agent discoverability.
Links