From 12fc496d3ca608ffa206cade81da9f9bf22eb138 Mon Sep 17 00:00:00 2001 From: YiYi Xu Date: Mon, 15 Jun 2026 16:20:28 -1000 Subject: [PATCH] keep the agent symlinks (#13968) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Commit root AGENTS.md/CLAUDE.md symlinks so agents auto-load conventions Track the root AGENTS.md/CLAUDE.md symlinks (-> .ai/AGENTS.md) instead of generating them via `make claude`/`make codex`, so a fresh clone auto-loads the agent guide with no setup step (matching transformers). The make targets now only wire up skills; .ai/AGENTS.md, the contribution doc, and the PR template are updated to match. Co-Authored-By: Claude Opus 4.8 (1M context) * Add documentation-impact check to PR review rules During review, scan related usage docs and agent docs and flag (advisory) any that should be updated based on the PR — outdated/missing usage docs, or a rule/pattern/gotcha worth recording in the agent guides. Co-Authored-By: Claude Opus 4.8 (1M context) --------- Co-authored-by: Claude Opus 4.8 (1M context) --- .ai/AGENTS.md | 5 +++++ .ai/review-rules.md | 7 +++++++ .github/PULL_REQUEST_TEMPLATE.md | 2 +- .gitignore | 2 -- AGENTS.md | 1 + CLAUDE.md | 1 + Makefile | 3 --- docs/source/en/conceptual/contribution.md | 10 +++++----- 8 files changed, 20 insertions(+), 11 deletions(-) create mode 120000 AGENTS.md create mode 120000 CLAUDE.md diff --git a/.ai/AGENTS.md b/.ai/AGENTS.md index 1343dd051b..9ba0b64c85 100644 --- a/.ai/AGENTS.md +++ b/.ai/AGENTS.md @@ -1,5 +1,10 @@ # Diffusers — Agent Guide +## Setup + +- Local Claude Code agents: run `make claude` after cloning to wire the [skills](#skills) under `.claude/`. +- Local OpenAI Codex agents: run `make codex` after cloning to wire the [skills](#skills) under `.agents/`. + ## Coding style Strive to write code as simple and explicit as possible. diff --git a/.ai/review-rules.md b/.ai/review-rules.md index f2d5e9f0b4..c936082dcc 100644 --- a/.ai/review-rules.md +++ b/.ai/review-rules.md @@ -15,6 +15,13 @@ Common mistakes are covered in the common-mistakes / gotcha sections in [AGENTS. - **Ephemeral context.** Comments, docstrings, and files that only made sense to the current PR's author or reviewer don't help a future reader/user/developer. Examples: `# per reviewer comment on PR #NNNN`, `# as discussed in review`, `# TODO from offline chat`, debug printouts. Same for files: parity harnesses, comparison scripts, anything in `scripts/` with hardcoded developer paths or imports from the reference repo. State the *reason* so the comment stands alone, or drop it. +## Documentation impact + +A PR can leave existing docs stale or surface a pattern worth recording. Scan the docs related to what the PR touches and flag updates as a **suggestions / additional info** section (not blocking): + +- **Usage docs.** New or changed public behavior — a new pipeline/model, a new argument, changed defaults, a renamed API — should have matching updates in `docs/`, docstrings, and examples. Flag any that now describe outdated behavior or that are missing for the new surface. +- **Agent docs.** If the review turns up a rule, pattern, or common gotcha that isn't written down yet — especially one the author got wrong or that you had to reason out — propose adding it to the relevant agent guide ([AGENTS.md](AGENTS.md), [models.md](models.md), [pipelines.md](pipelines.md), [modular.md](modular.md), a skill, or this file) so the next contributor/agent gets it for free instead of repeating the mistake. + ## Dead code analysis (new models) When reviewing a PR that adds a new model, trace how the model is actually called from the pipeline to identify likely dead code. Include the results as a **suggestions / additional info** section in your review (not as blocking comments — the findings are advisory). diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index d796272095..c4a6046e5d 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -17,7 +17,7 @@ Fixes # (issue) ## Before submitting - [ ] Did you use an AI agent (Claude Code, Codex, Cursor, etc.) to help with this PR? If so: - - [ ] Did you point it at the project conventions in [`.ai/`](https://github.com/huggingface/diffusers/tree/main/.ai) (e.g. via `make claude` / `make codex`)? See [Coding with AI agents](https://huggingface.co/docs/diffusers/main/en/conceptual/contribution#coding-with-ai-agents). + - [ ] Did you read the [Coding with AI agents](https://huggingface.co/docs/diffusers/main/en/conceptual/contribution#coding-with-ai-agents) guide? - [ ] Did you self-review the diff against [`.ai/review-rules.md`](https://github.com/huggingface/diffusers/blob/main/.ai/review-rules.md)? - [ ] Did you read the [contributor guideline](https://huggingface.co/docs/diffusers/main/en/conceptual/contribution)? - [ ] Did you read our [philosophy doc](https://huggingface.co/docs/diffusers/main/en/conceptual/philosophy)? (important for complex PRs) diff --git a/.gitignore b/.gitignore index 21da6fe14e..7b156e460a 100644 --- a/.gitignore +++ b/.gitignore @@ -184,7 +184,5 @@ tags wandb # AI agent generated symlinks -/AGENTS.md -/CLAUDE.md /.agents/skills /.claude/skills \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 120000 index 0000000000..b28461c924 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1 @@ +.ai/AGENTS.md \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000000..b28461c924 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +.ai/AGENTS.md \ No newline at end of file diff --git a/Makefile b/Makefile index b104e82993..ebf6b202b2 100644 --- a/Makefile +++ b/Makefile @@ -107,17 +107,14 @@ post-patch: # AI agent symlinks codex: - ln -snf .ai/AGENTS.md AGENTS.md mkdir -p .agents rm -rf .agents/skills ln -snf ../.ai/skills .agents/skills claude: - ln -snf .ai/AGENTS.md CLAUDE.md mkdir -p .claude rm -rf .claude/skills ln -snf ../.ai/skills .claude/skills clean-ai: - rm -f AGENTS.md CLAUDE.md rm -rf .agents/skills .claude/skills diff --git a/docs/source/en/conceptual/contribution.md b/docs/source/en/conceptual/contribution.md index 601ae4094d..c332792fd3 100644 --- a/docs/source/en/conceptual/contribution.md +++ b/docs/source/en/conceptual/contribution.md @@ -570,9 +570,9 @@ For documentation strings, 🧨 Diffusers follows the [Google style](https://goo ## Coding with AI agents -The repository keeps AI-agent configuration in [`.ai/`](https://github.com/huggingface/diffusers/tree/main/.ai) and exposes local agent files via symlinks. If you use a coding agent (Claude Code, OpenAI Codex, etc.) to help with a contribution, point it at this directory — it contains the project conventions and on-demand task knowledge maintainers expect contributors to follow. +The repository keeps AI-agent configuration in [`.ai/`](https://github.com/huggingface/diffusers/tree/main/.ai). Run `make claude` / `make codex` to additionally wire up the on-demand task skills for your tool. -- **Read-only for contributors** — `.ai/` is maintained by the core maintainers. Please do not edit files under `.ai/` (or the generated root-level `AGENTS.md`, `CLAUDE.md`, `.agents/skills`, `.claude/skills`, which are symlinks) in your PR. If you find something missing or wrong, open an issue or flag it on the PR and a maintainer will update it. +- **Read-only for contributors** — `.ai/` is maintained by the core maintainers. Please do not edit files under `.ai/` (or the root-level `AGENTS.md` / `CLAUDE.md` symlinks, or the generated `.agents/skills` / `.claude/skills`) in your PR. If you find something missing or wrong, open an issue or flag it on the PR and a maintainer will update it. - **Guidelines** (loaded into every agent session): - [`.ai/AGENTS.md`](https://github.com/huggingface/diffusers/blob/main/.ai/AGENTS.md) — top-level coding guidelines - [`.ai/models.md`](https://github.com/huggingface/diffusers/blob/main/.ai/models.md) — attention pattern, model implementation rules, common conventions @@ -583,9 +583,9 @@ The repository keeps AI-agent configuration in [`.ai/`](https://github.com/huggi - `model-integration` — adding a new model or pipeline to diffusers end-to-end (file structure, integration checklist, testing layout, weight conversion) - `self-review` — review your changes against the project rules before opening a PR - **Setup commands**: - - `make codex` — symlink guidelines + skills for OpenAI Codex - - `make claude` — symlink guidelines + skills for Claude Code - - `make clean-ai` — remove all generated symlinks + - `make codex` — wire up skills for OpenAI Codex (under `.agents/`) + - `make claude` — wire up skills for Claude Code (under `.claude/`) + - `make clean-ai` — remove the generated skills symlinks ### AI-assisted and agentic contributions