docs: add AGENTS.md and .claude/CLAUDE.md for AI coding agents#253
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #253 +/- ##
=======================================
Coverage 68.46% 68.46%
=======================================
Files 82 82
Lines 4842 4842
=======================================
Hits 3315 3315
Misses 1395 1395
Partials 132 132 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Greptile SummaryAdds two documentation files — Confidence Score: 5/5Documentation-only PR with all factual claims verified; safe to merge. No P0 or P1 issues found. Both files are documentation-only and all key claims (Go version, provider list, internal packages, build output, interface signature, coverage thresholds) were verified against the actual codebase. The previously raised issues — header line count (now correctly says 'first 5 lines differ') and the pkg/models/ description (which accurately reads 'Go types and loader for YAML simulation models') — are resolved. No files require special attention. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[".claude/CLAUDE.md\n(canonical source)"] -->|"lines 1-5 differ\n(title + description + sync comment)"| B["Header block"]
A -->|"lines 6-247\nbyte-identical"| C["Shared body\n(architecture, setup, testing,\nconventions, PR guidelines)"]
B --> D["AGENTS.md\n(public synced copy)"]
C --> D
D -->|reads| E["Codex / Cursor / Copilot\n/ other agents"]
A -->|reads| F["Claude Code"]
Reviews (5): Last reviewed commit: "docs: add AGENTS.md and .claude/CLAUDE.m..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
|
|
||
| This file provides guidance to Claude Code when working with code in this repository. | ||
|
|
||
| <!-- This is the canonical source. AGENTS.md is a synced public copy; only the first 4 lines differ. --> |
There was a problem hiding this comment.
The comment says "only the first 4 lines differ" but lines 1, 3, and 5 differ between the two files (the title, the description sentence, and this very comment), while lines 2 and 4 are identical blank lines. The shared body starts at line 6, so the accurate claim is "the first 5 lines differ." Any automated sync script keyed on this comment would start comparing at line 5 and incorrectly flag this comment line as a mismatch. The PR description itself correctly says "first 5 header lines."
The same wording appears in AGENTS.md line 5.
| <!-- This is the canonical source. AGENTS.md is a synced public copy; only the first 4 lines differ. --> | |
| <!-- This is the canonical source. AGENTS.md is a synced public copy; only the first 5 lines differ. --> |
| metrics/ # Prometheus metrics | ||
| models/ # YAML simulation models | ||
| test/ # Cross-package test helpers | ||
| internal/ # Shared utilities not part of the public API |
There was a problem hiding this comment.
pkg/models/ description is inaccurate
The entry describes pkg/models/ as "YAML simulation models," but the directory actually contains Go source files (model.go, model_test.go) — not YAML. The YAML simulation fixtures live in tests/models/, which is correctly described a few lines below. An agent following this map might look in the wrong place for Go model types.
| internal/ # Shared utilities not part of the public API | |
| models/ # Go model types for simulation data structures |
resker
force-pushed
the
docs/agents-md
branch
2 times, most recently
from
d1398bc to
cae028a
Compare
|
Tracking issue: #260 — has the problem statement, proposed structure, and open design choices (sync-check enforcement, scope of "do not change without discussion"). |
Adds agent-guidance documentation following the emerging AGENTS.md 5-part convention (overview/architecture, setup, testing/deployment, coding conventions, PR guidelines) with topograph-specific content: - Provider/engine boundary invariant and repository map - Provider interface contract and new-provider checklist - Anti-patterns and "do not change without discussion" surfaces - DCO sign-off requirements (topograph has no org-member exemption) .claude/CLAUDE.md is the canonical source; AGENTS.md is the public synced copy. Only the first 5 header lines differ. Tracks NVIDIA#260 Signed-off-by: Rob Esker <resker@nvidia.com>
|
Want your agent to iterate on Greptile's feedback? Try greploops. |
… stale references Builds on the agent-guidance pattern established in NVIDIA#253, adding the explicit evaluation guidance that was deferred during that PR's review. Adds: - New "Documentation Impact Evaluation" subsection in §5 with a table mapping change types to the docs that should be updated in the same PR (provider, engine, chart template, values schema, label/annotation key, API endpoint, config schema, invariant, Makefile/layout) - New pre-push checklist item: "Documentation impact evaluated per the table above" - New anti-pattern row flagging AGENTS.md drift when an AGENTS.md-described surface changes without updating both synced files in the same PR Refreshes references made stale by NVIDIA#267 (docs reorg): - Repository map entry for docs/ now lists overview.md, architecture.md, api.md explicitly - "Adding a new provider" step 5 points at docs/overview.md instead of README.md for the provider list / scenario table - "When in doubt" pointer to "Choosing a Provider" table updated to docs/overview.md; adds docs/api.md pointer for API/config schema - Simplifies the pre-push checklist (specific provider/engine doc items roll up into the new Documentation Impact Evaluation table) - Prunes README.md out of the registry-wiring anti-pattern (the registry update is the load-bearing concern; doc updates are covered by the new evaluation table) Both files stay byte-identical from line 6 onward. Signed-off-by: Rob Esker <resker@nvidia.com>
… stale references Builds on the agent-guidance pattern established in NVIDIA#253, adding the explicit evaluation guidance that was deferred during that PR's review. Adds: - New "Documentation Impact Evaluation" subsection in §5 with a table mapping change types to the docs that should be updated in the same PR (provider, engine, chart template, values schema, label/annotation key, API endpoint, config schema, invariant, Makefile/layout) - New pre-push checklist item: "Documentation impact evaluated per the table above" - New anti-pattern row flagging AGENTS.md drift when an AGENTS.md-described surface changes without updating both synced files in the same PR Refreshes references made stale by NVIDIA#267 (docs reorg): - Repository map entry for docs/ now lists overview.md, architecture.md, api.md explicitly - "Adding a new provider" step 5 points at docs/overview.md instead of README.md for the provider list / scenario table - "When in doubt" pointer to "Choosing a Provider" table updated to docs/overview.md; adds docs/api.md pointer for API/config schema - Simplifies the pre-push checklist (specific provider/engine doc items roll up into the new Documentation Impact Evaluation table) - Prunes README.md out of the registry-wiring anti-pattern (the registry update is the load-bearing concern; doc updates are covered by the new evaluation table) Both files stay byte-identical from line 6 onward. Signed-off-by: Rob Esker <resker@nvidia.com>
… stale references (#269) Builds on the agent-guidance pattern established in #253, adding the explicit evaluation guidance that was deferred during that PR's review. Adds: - New "Documentation Impact Evaluation" subsection in §5 with a table mapping change types to the docs that should be updated in the same PR (provider, engine, chart template, values schema, label/annotation key, API endpoint, config schema, invariant, Makefile/layout) - New pre-push checklist item: "Documentation impact evaluated per the table above" - New anti-pattern row flagging AGENTS.md drift when an AGENTS.md-described surface changes without updating both synced files in the same PR Refreshes references made stale by #267 (docs reorg): - Repository map entry for docs/ now lists overview.md, architecture.md, api.md explicitly - "Adding a new provider" step 5 points at docs/overview.md instead of README.md for the provider list / scenario table - "When in doubt" pointer to "Choosing a Provider" table updated to docs/overview.md; adds docs/api.md pointer for API/config schema - Simplifies the pre-push checklist (specific provider/engine doc items roll up into the new Documentation Impact Evaluation table) - Prunes README.md out of the registry-wiring anti-pattern (the registry update is the load-bearing concern; doc updates are covered by the new evaluation table) Both files stay byte-identical from line 6 onward. Signed-off-by: Rob Esker <resker@nvidia.com>
2 participants
Summary
Adds agent-guidance documentation following the emerging AGENTS.md convention (5-part structure: overview/architecture, setup, testing/deployment, coding conventions, PR guidelines) with topograph-specific content:
`.claude/CLAUDE.md` is the canonical source; `AGENTS.md` is the public synced copy. Only the first 5 header lines differ — the bodies are byte-identical from that point.
Context
AGENTS.md has emerged as the de facto standard for guiding AI coding agents (Codex, Cursor, Copilot, Claude Code, etc.) in OSS repositories. It pairs with Context 7 indexing as the standard agent-findability pattern.
Tracking issue: #260
Test plan
Follow-up
After this merges, the repo can be submitted to Context 7 for LLM-optimized doc indexing, closing the second half of the agent-findability pattern.