Add an AGENTS.md file to help with AI-assisted debugging/development#907
Draft
dscho wants to merge 3 commits intovfs-2.54.0from
Draft
Add an AGENTS.md file to help with AI-assisted debugging/development#907dscho wants to merge 3 commits intovfs-2.54.0from
dscho wants to merge 3 commits intovfs-2.54.0from
Conversation
The Microsoft Git fork is a downstream fork of Git for Windows. Its reason to exist is quite a bit different from Git for Windows. For example, it targets not only Windows, it also supports Linux and macOS builds. Historically, its main goal has been to support VFSforGit. In the meantime, also Scalar targeting Azure Repos has been a major focus of this repository. These aspects need to be reflected in the agents. So that LLM assistance can be more effective. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
…opment
AGENTS.md: document the iterative, human-in-the-loop working style
Derrick Stolee, who routinely drives LLM-assisted work on this
codebase, described his approach: rather than relying on elaborate
custom prompts, he gets good results by keeping the agent on a short
leash through a disciplined workflow. Specifically he:
- Starts every task by asking the agent to explore the relevant
code (where are the important methods, how does control flow,
where are the existing tests).
- Asks for an explicit, commit-by-commit plan and reviews it
carefully, with particular attention to any code snippets
proposed.
- Has the agent implement one commit at a time, pausing for review
between commits.
- Drives the incremental rebase himself and prompts the agent to
make follow-up edits on top of the rewritten history.
These are general LLM-assisted Git development practices, not
fork-specific, so the new "Working Style" section is added near the
top of AGENTS.md (right after "Overview", before any of the more
technical structural and architectural material) where it sets the
tone for the rest of the document. The placement is identical in the
base file and in the Microsoft Git adaptation, since neither commit
that touches AGENTS.md modifies the section boundary between
"Overview" and "Repository Structure".
Helped-by: Derrick Stolee <stolee@gmail.com>Assisted-by: Claude Opus 4.7
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
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.
This PR is the Microsoft Git counterpart to git-for-windows#6198, which added an
AGENTS.mdfile at the top of the Git for Windows tree to give AI coding assistants enough project-specific context to be useful contributors there. The argument from that PR applies to this fork too, only more so. Quoting:The Microsoft Git fork sits one rung further down the stack, on top of Git for Windows on top of upstream Git, and it carries a substantial body of fork-specific code that no LLM will have been trained on: the GVFS protocol implementation in
gvfs-helper*.c, thevirtualfilesystem.chooks, the early Scalar history that was later upstreamed in heavily-evolved form, status serialization, and the per-releasetentative/vfs-X.Y.Zrebases onto new upstream and Git for Windows versions. Without targeted context, even capable models tend to miss conventions, "fix" code that is intentionallyfork-specific, or propose patches that conflict with how the next merging-rebase will need to look.
This PR is part of the same wave of
AGENTS.mdadditions as git-for-windows#6198, git-for-windows/MINGW-packages#194, git-for-windows/git-for-windows.github.io#88, and git-for-windows/msys2-runtime#124. It starts from the file added by the first of those PRs and then adapts it for the Microsoft Git fork: documenting the fork hierarchy and the VFSforGit / Scalar history, the GVFS-specific source layout and configuration options, the integration points where GVFS hooks into Git's object lookup machinery, the high-risk areas to watch during release rebases, when to skip a patch, conflict resolution patterns, and thetentative/vfs-X.Y.Zbranch workflow.The series is intentionally split into small reviewable chunks: an initial commit that brings in the upstream
AGENTS.mdunchanged, a second commit that adapts it for the Microsoft Git fork, and afixup!commit on top with further refinements. Thefixup!is deliberately not autosquashed, so reviewers can read each adjustment in isolation. The next merging-rebase to a newer Git for Windows version is when the whole group will collapse into a single commit for easier maintenance going forward.Opened as a draft on purpose: the file lives at the top of the tree and benefits from real-world feedback before being declared "done". Suggestions, especially from anyone actively using an AI assistant against this repository, are very welcome.