docs: expand AGENTS.md with git workflow, boundaries and code style examples - #5526
Conversation
…xamples Fills the gaps against the six areas that matter for agent instruction files: commands, testing, project structure, code style, git workflow and boundaries. - Git Workflow: the PR title is the changelog line, so document the conventional-commit format and the prefix -> CHANGELOG section mapping from .github/release.yml. The previous wording pointed at "commit message conventions" without ever stating the format. - Boundaries: collect the five never-edit paths (generated, vendored or CI-guarded) into one table with what to do instead; add never-commit-secrets and an ask-first tier. - Code Style: name .editorconfig as authoritative, dotnet format as the enforcer, and show the no-comments rule as good/bad snippets. - Before you're done: the build/test/format gate, plus a note that the API approval tests self-rewrite their snapshots on a local run. - Promote Code Intelligence to a top-level heading; it was nested under Commit Attribution. CLAUDE.md and .github/copilot-instructions.md are symlinks to AGENTS.md and pick these up unchanged. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
szokeasaurusrex
left a comment
szokeasaurusrex
left a comment
There was a problem hiding this comment.
Did not review the technical content as I am not a .NET expert, but these changes look reasonable
| ### Commit Attribution | ||
|
|
||
| AI commits MUST include: | ||
|
|
||
| ``` | ||
| Co-Authored-By: <Agent Name> <agent-email-or-noreply@example.com> | ||
| ``` | ||
|
|
There was a problem hiding this comment.
l: These instructions do not usually play well with agent harnesses like Pi which do not have a commit email address.
I have found that my Pi agent will hallucinate commit emails when given this instruction.
There was a problem hiding this comment.
What are you you doing instead? I think we need commit attributions where LLMs are used right?
There was a problem hiding this comment.
I don't think Pi natively has any commit attributions; perhaps there is some extension that does it properly.
I have my agent running in a sandbox where the Git username is set to "Daniel Szoke (via Pi agent)", so that is all the attribution I have.
While I agree that it is good to have commit attribution, I feel it is better to have no attribution than an incorrect attribution. When my agent sees these sorts of AI attribution instructions it tends to hallucinate a label, e.g. I have had OpenAI models commit "Co-Authored-By Claude" because that is what the instructions said or that is what other commits in the history had.
Also, I believe that the "mainstream" agent harnesses like Claude Code and Codex already have this sort of commit attribution built in, so it seems redundant then to also mention in AGENTS.md.
There was a problem hiding this comment.
Again though, it is just my opinion based on my experience. Many Sentry repos have this sort of attribution instruction so it would not be out of the ordinary to include it here, either.
adinauer
left a comment
adinauer
left a comment
There was a problem hiding this comment.
LGTM just some minor things that might need correction. Leaving up to you whether there's anything to fix. Feel free to ignore those comments.
| | Path | Instead | | ||
| |------|---------| | ||
| | `*.slnf` | Edit `scripts/generate-solution-filters-config.yml`, then run `scripts/generate-solution-filters.ps1` | | ||
| | `CHANGELOG.md` | Generated on squash-merge from the PR title. `.github/workflows/changelog-guard.yml` fails CI on manual entries | |
There was a problem hiding this comment.
l Does this happen on release (by craft) rather than during squash-merge?
There was a problem hiding this comment.
I've currently got that wired up on all pull requests:
sentry-dotnet/.github/workflows/changelog-guard.yml
Lines 3 to 8 in be2a785
If people do want to customise the changelog, they can always and a ### Changelog Entry section in the PR description so we decided to prevent manual changelog entries entirely (it just makes for merge conflicts).
Co-authored-by: Alexander Dinauer <adinauer@users.noreply.github.com>
![sentry[bot]](https://avatars.githubusercontent.com/in/12637?s=60&v=4){kind=small}
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
3 participants
#skip-changelog
Audits
AGENTS.mdagainst the six areas that GitHub's analysis of agent instruction files found separate the ones that work from the ones that don't — commands, testing, project structure, code style, git workflow, boundaries — and fills the gaps. The file was already strong on commands, testing and structure; this covers the other three.Notes for review
CLAUDE.mdand.github/copilot-instructions.mdare symlinks toAGENTS.md, so this one file covers all three agent vendors — no drift to keep in sync..github/agents/*.agent.md), so its YAML frontmatter / persona / "create six named agents" advice is deliberately not applied here. Only the six-areas finding transfers to a repo-rootAGENTS.md.