docs: expand AGENTS.md with git workflow, boundaries and code style examples - #5526
Open
jamescrosswell wants to merge 2 commits into
Open
docs: expand AGENTS.md with git workflow, boundaries and code style examples#5526jamescrosswell wants to merge 2 commits into
jamescrosswell wants to merge 2 commits into
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 <[email protected]>
szokeasaurusrex
approved these changes
Sep 7, 2026
szokeasaurusrex
left a comment
szokeasaurusrex
left a comment
Member
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
Comment on lines
+236
to
+243
| ### Commit Attribution | ||
|
|
||
| AI commits MUST include: | ||
|
|
||
| ``` | ||
| Co-Authored-By: <Agent Name> <[email protected]> | ||
| ``` | ||
|
|
Member
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.
adinauer
approved these changes
Sep 7, 2026
adinauer
left a comment
adinauer
left a comment
Member
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` | |
Member
There was a problem hiding this comment.
l
Suggested change
| | `*.slnf` | Edit `scripts/generate-solution-filters-config.yml`, then run `scripts/generate-solution-filters.ps1` | | |
| | `*.slnf` | Edit `scripts/generate-solution-filters-config.yaml`, then run `scripts/generate-solution-filters.ps1` | |
| | 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 | |
Member
There was a problem hiding this comment.
l Does this happen on release (by craft) rather than during squash-merge?
| | `fix:` / `bugfix:` | Fixes 🐛 | | ||
| | `chore(deps):` | Dependencies ⬆️ | | ||
| | any type with `!`, e.g. `feat!:` | Breaking Changes 🛠 | | ||
| | anything else | omitted from the changelog | |
Member
There was a problem hiding this comment.
l
is this true or does it land in "Other"?
Member
There was a problem hiding this comment.
+1, iirc there is an "Internal Changes" (or similar) section
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
3 participants
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.
#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.