Commit 96ea4a6
Add an AGENTS.md file to help with AI-assisted debugging/development (#6198)
AI-assisted contributions are a reality of open source in 2025 and
beyond. Contributors will use AI tools, and that includes the
maintainers themselves. Over recent months, I have found AI increasingly
useful for the kind of menial, tedious work that does not require much
creativity but is highly boring when done by hand: resolving merge
conflicts during merging-rebases, chasing down CI failures across
platforms, adapting downstream patches to upstream API changes.
To that end, I would like to have an `AGENTS.md` file in the code base
that helps any LLM to understand the context of the project.
A secondary goal of this is to preemptively help outside contributors.
The risk is not AI usage per se, but low-quality AI slop: contributions
where the human hits "accept" without sufficient context being available
to the model (and without proper review by the human, we've all been
there), resulting in changes that miss conventions, break patterns, or
misunderstand the project's architecture. Git's source code is about as
legacy as they come, having grown organically over two decades with no
design that AI coding models would readily grasp from a narrow code
sample alone.
This `AGENTS.md` is designed to raise the floor on AI-assisted
contributions by providing enough context that even when a human
contributor fails to steer carefully, the model has the information it
needs to produce something reasonable. It documents the repository
structure, build process, test conventions, the object model and ODB
internals, debugging techniques (Trace2, instrumenting tests, bisecting
failures), the merging-rebase workflow, conflict resolution patterns,
coding conventions (ASCII only, 80 columns, tabs), commit message
expectations, and the GitGitGadget contribution workflow. This is
information that a human might take for granted, but no coding model
will have been trained on specifically.
Similar `AGENTS.md` files have recently been added to other repositories
in the Git for Windows project:
[MINGW-packages](git-for-windows/MINGW-packages#194),
[git-for-windows.github.io](git-for-windows/git-for-windows.github.io#88)
and
[msys2-runtime](git-for-windows/msys2-runtime@1e0ff37).2 files changed
Lines changed: 1110 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
7 | 7 | | |
8 | 8 | | |
9 | 9 | | |
| 10 | + | |
10 | 11 | | |
11 | 12 | | |
12 | 13 | | |
| |||
0 commit comments