Teach AI agents to use pre-commit to pass before committing and pushing#2702
Merged
Conversation
tatiana
requested review from
a team,
corsettigyg,
dwreeves and
jbandoro
as code owners
Contributor
There was a problem hiding this comment.
Pull request overview
Documentation-only update to CLAUDE.md clarifying that the full pre-commit suite must pass locally before committing or pushing.
Changes:
- Adds explicit requirement to run and pass
pre-commit run --all-fileslocally before commits/PRs. - Reframes individual tool commands as iteration aids rather than equivalent alternatives.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
pankajkoti
approved these changes
May 19, 2026
tatiana
changed the title
tatiana
changed the title
tatiana
changed the title
4 tasks
CLAUDE.md already documented ``pre-commit run --all-files`` but did not state that it must pass before a commit lands or a PR is opened. Make the requirement explicit, including the docs style hooks (``scripts/check_docs_style.py``), since CI runs the same hooks and a local-skipped failure shows up as a noisy CI failure instead. Also rework the section slightly so the single-tool examples are framed as "if you need to iterate" rather than as an equivalent alternative to the full suite. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Pankaj Koti <pankajkoti699@gmail.com>
tatiana
force-pushed
the
claude-md-require-precommit
branch
from
f978f09 to
693c3d9
Compare
tatiana
added a commit
that referenced
this pull request
May 19, 2026
Move all agent-neutral project guidance (commands, architecture, coding standards, commit-message format, documentation style, etc.) out of CLAUDE.md and into a new AGENTS.md so that other AI coding agents -- Cursor, Codex, Copilot, and so on -- read the same single source of truth. CLAUDE.md becomes a thin pointer that defers to AGENTS.md and is reserved for Claude Code-specific instructions. There are currently none, so the file is intentionally short; future Claude-only overrides should accumulate there rather than diverging from the shared baseline. The content moved is byte-identical to what CLAUDE.md previously contained, with one exception: the introductory paragraph in AGENTS.md is rewritten in agent-neutral language to make the intended audience explicit and to point at CLAUDE.md as the canonical place for Claude-only overrides. This PR is stacked on top of #2702 (claude-md-require-precommit) so the pre-commit rule it adds is already present in AGENTS.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
tatiana
added a commit
that referenced
this pull request
May 27, 2026
Move all agent-neutral project guidance (commands, architecture, coding standards, commit-message format, documentation style, etc.) out of CLAUDE.md and into a new AGENTS.md so that other AI coding agents -- Cursor, Codex, Copilot, and so on -- read the same single source of truth. CLAUDE.md becomes a thin pointer that defers to AGENTS.md and is reserved for Claude Code-specific instructions. There are currently none, so the file is intentionally short; future Claude-only overrides should accumulate there rather than diverging from the shared baseline. The content moved is byte-identical to what CLAUDE.md previously contained, with one exception: the introductory paragraph in AGENTS.md is rewritten in agent-neutral language to make the intended audience explicit and to point at CLAUDE.md as the canonical place for Claude-only overrides. This PR is stacked on top of #2702 (claude-md-require-precommit) so the pre-commit rule it adds is already present in AGENTS.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
tatiana
added a commit
that referenced
this pull request
May 27, 2026
Make the project's agent guidance reusable across AI coding tools: - Move every agent-neutral section of `CLAUDE.md` (commands, architecture, coding standards, commit-message format, documentation style, etc.) into a new top-level `AGENTS.md`. The content is byte-identical apart from the introductory paragraph, which is rewritten in agent-neutral language and names `CLAUDE.md` as the canonical place for Claude-only overrides. - Slim `CLAUDE.md` to a small pointer that defers to `AGENTS.md`. The pointer remains the file Claude Code reads on session start, but it no longer duplicates project conventions. Claude-specific instructions can accumulate there in the future without diverging from the shared baseline. - Document the AI-agent attribution convention (originally PR #2718, since folded into this branch): give the assisting agent visible credit via a trailing `🤖 Generated with …` marker, never via a `Co-Authored-By` trailer (that surfaces in the GitHub contributor graph and `git shortlog`, which should stay human-only). - Add `AGENTS.md` to the `Check-changed-files` allowlist in `.github/workflows/test.yml` so docs-only edits to `AGENTS.md` don't trigger the full unit/integration matrix, mirroring how `CLAUDE.md` is already handled. This unlocks other agents — Cursor, Codex, Copilot, etc. — using the same conventions Claude already does, without us maintaining parallel copies. ## Review feedback addressed - [x] Copilot: add `AGENTS.md` to the `Check-changed-files` allowlist in `.github/workflows/test.yml` (mirrors the existing `CLAUDE.md` line). - [x] Copilot: change British "behaviour" to American "behavior" in the `AGENTS.md` intro paragraph for consistency with the rest of the document. ## Rebased onto main The original revision was stacked on `claude-md-require-precommit` (PR #2702). #2702 has since squash-merged to main (commit [`ea04d0da`](ea04d0d)), so this branch has been rebased onto the current `main`. The redundant pre-squash commits were dropped during rebase (`693c3d9c` identified as "patch contents already upstream"; `f8a6bf03` skipped manually). The companion attribution-convention PR #2718 has also been folded into this branch since it built on top of `claude-md-extract-agents-md`. ## Test plan - [x] `pre-commit run --files CLAUDE.md AGENTS.md .github/workflows/test.yml` — all applicable hooks pass locally. - [x] CI run on this PR — pre-commit.ci passes; the full unit/integration matrix runs (because this PR touches `.github/workflows/test.yml`, which is not — and should not be — on the allowlist). Future docs-only `AGENTS.md` PRs will skip the matrix. 🤖 Generated with Claude Code (https://claude.com/claude-code)
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
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.
Summary
CLAUDE.md already documented
pre-commit run --all-filesas the localpre-flight command, but did not state that it must pass before a
commit lands or a PR is opened. In practice that meant a stale local
environment or a forgotten hook (notably
scripts/check_docs_style.pyand mypy) could ship to CI and fail there.
This PR makes the requirement explicit:
full pre-commit suite locally and ensure it passes before committing
or pushing", calling out style checks and CI parity.
black,ruff,mypy) are framed as"if you need to iterate on a single one" rather than an equivalent
alternative to the full suite.
No code, tooling, or hook configuration changes — purely a guidance
update inside
CLAUDE.md.Test plan
git diff CLAUDE.mdreviewed — only the "Linting and Formatting" section is touched.check-changed-files job should keep test/integration jobs from
running).
🤖 Generated with Claude Code