AGENTS.md: add guidance for AI agents and contributors#88
Open
Conversation
This file documents the repository's structure, build process, and conventions to help AI agents work effectively with this codebase. It covers the Hugo-based site architecture, the custom output formats for download URLs and version files, the CSS/JS setup, content conventions, and the CI/CD workflows. Importantly, it describes the relationship between this site and its sister sites git-scm.com and gitgitgadget.github.io: the git-scm.com Hugo conversion (PR #1804, Oct 2023–Sep 2024) was the pioneering effort, gitgitgadget.github.io followed in March 2025 (PR #23) inspired by that work and explicitly as a blueprint for this site, and this site's own conversion landed days later (PR #56). A major motivation was retiring the GitHub wiki that had become a spam magnet, moving content into this repository so that contributions go through pull requests with proper review. Cross-pollination between the three sites is ongoing and encouraged; for example the Pagefind-based search and Playwright UI tests on git-scm.com are likely models for future functionality here. The file also documents URL stability expectations (always add aliases when renaming pages), the version update mechanism (bump-version.js invoked by the release automation, not by humans), the redirect template that preserves query strings and anchors, and commit message conventions including that the Assisted-by trailer must name the AI model, not the product. Assisted-by: Claude Opus 4.6 Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Member
Author
|
Note that the contents of this PR assume that #87 has been merged already. |
Member
Author
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.
AI-assisted contributions are a reality of open source in 2025 and beyond. Contributors will use AI tools — and that includes the maintainers themselves. 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, resulting in changes that miss conventions, break patterns, or misunderstand the project's architecture and relationships.
This
AGENTS.mdis 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, content conventions, commit message expectations, the relationship with sister sites (git-scm.com, gitgitgadget.github.io), the version update automation, URL stability requirements, and other details that an AI agent could not infer from a narrow code sample alone.