From 991243393cd12fc4bf2ddf364faf9e5e63905c11 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Thu, 25 Jun 2026 11:40:59 -0400 Subject: [PATCH 01/12] feat: add an AI page Signed-off-by: Henry Schreiner --- docs/guides/ai.md | 362 +++++++++++++++++++++++++++++++++++++++++++ docs/guides/index.md | 6 +- docs/myst.yml | 1 + 3 files changed, 367 insertions(+), 2 deletions(-) create mode 100644 docs/guides/ai.md diff --git a/docs/guides/ai.md b/docs/guides/ai.md new file mode 100644 index 00000000..5fb05902 --- /dev/null +++ b/docs/guides/ai.md @@ -0,0 +1,362 @@ +--- +short_title: AI +--- + +# Agentic AI + +Around November of 2025, agentic AI exploded in usefulness, and has changed how +a lot of software is written, reviewed, and maintained. "Agentic" AI is more +than a chatbot; it has access to "tool calls", which can read and write files, +and most importantly it runs in a loop so it can verify that code passes +checks. This is closer to how a human codes; we run code and verify outputs, +we do not write working code from scratch without running it. + +It helps to separate two very different things that often get lumped together +as "Agentic AI": + +- A developer driving an interactive AI harness with a capable model, reading + the output, and taking responsibility for the result. This is a power tool, + much like an editor or a linter. +- Low-cost models running unattended in automated systems that mass-produce + pull requests. This is what most people mean by "AI slop", and it is the + source of most of the frustration maintainers feel about AI contributions. + +The recommendations below are aimed at the first case, and at keeping your +project from being overwhelmed by the second. + +:::{note} +The first point does hide something: the tool depends on the developer guiding +it (just like any other tool). You will also see users with very little coding +experience using these tools to produce low quality contributions. How someone +learns to code in this new era is still something unsolved. + +If you maintain a project: Try to engage with the human. If they are willing to +interact (and not just type "address the review" into their harness), treat +them like a human, even if you also see the AI working on their behalf. They +also may use AI to address a language barrier. +::: + +## Disclosure and transparency + +We recommend **full disclosure**. Knowing what model was used lets a reviewer +run a model from a different model family to help them review the contribution. +A maintainer has a better idea of what to expect based on the model used. And +it's generally more respectful to not keep your process hidden when +contributing to open source - maybe the maintainer would like to try that model +too. If you heavily edit the model output, then use your discretion; but being +open about the whole process is generally better! + +**Credit AI in commits.** Follow the convention used by the Linux kernel and +add a trailer. Never allow the model to add itself as a co-author. The code is +still yours (and your responsibility); the AI is a tool, not an author or +copyright holder, which is what co-authored-by is for. A growing number of +projects will close a PR with an AI co-author out of licensing concerns. + +The Linux kernel trailer looks like this: + +```text +Assisted-by: : +``` + +You can usually customize your harness to include this, either in an agents +file (below), or via specific settings. + +**Write your own PR descriptions.** Generated PR summaries tend to be verbose, +impersonal, and a chore to read. Write the description yourself. If a PR or +comment does contain AI-generated prose, mark it clearly, for example with a +short disclaimer line at the top - and you can still write a human written +message above that disclaimer. + +**Keep human review human-to-human.** Maintainers should never have to argue +with a bot. Don't make a reviewer talk to an AI without knowing it; if an AI is +responding on your behalf, say so (e.g. with an AI disclaimer at top). +You are accountable for every change you submit. + +**Don't submit slop.** Don't open a PR that a maintainer could finish faster +than they can review it, and don't mass-file unsolicited PRs. Reviewing a +careless PR can take far longer than writing it did; effectively a +denial-of-service on volunteer maintainers. If the change is trivial with AI, +the maintainers probably could just trigger the AI themselves. Make sure the +pull request is welcome - check issues, ask first, etc. + +## `AI_POLICY.md` + +A growing convention is to add an [`AI_POLICY.md`][ai-pr-policy] to your +repository so contributors know what is expected of AI-assisted work. There is +no single right answer; pick the stance that matches your project's tolerance +and capacity. The tabs below sketch three levels you can adapt. + +::::{tab-set} +:::{tab-item} All in + +AI-assisted contributions are welcome on the same footing as any other, as long +as they meet the project's quality bar and are disclosed. + +```markdown +# AI Policy + +AI-assisted contributions are welcome. We ask that you: + +- Disclose that AI was used and name the tool/model. +- Review and understand every line you submit; you are responsible for it. +- Meet the same quality, testing, and style standards as any contribution. +``` + +::: +:::{tab-item} Moderate + +AI assistance is fine, but the burden is on the contributor to show real human +involvement and prior buy-in before opening a PR. This mirrors the +[original proposal][ai-pr-policy]. + +```markdown +# AI Policy + +AI-assisted contributions are accepted only if: + +- The PR fills out the pull request template. +- It clearly states that it is AI-assisted and names the tool used. +- It links to an issue or discussion where a maintainer agreed to the + proposed change beforehand. + +Unsolicited, undisclosed, or low-effort AI PRs will be closed. +``` + +::: +:::{tab-item} Minimal + +AI-generated PRs are discouraged or restricted. Use this if you have limited +review capacity. + +```markdown +# AI Policy + +We do not accept unsolicited AI-generated pull requests. Please open an issue +to discuss before contributing. Fully-reviewed, disclosed AI-assisted fixes may +be considered case by case. +``` + +::: +:::: + +## `AGENTS.md` + +Harnesses read a project context file to learn how your repository works -- +preferred command runners, architecture notes, conventions, and gotchas. A good +context file makes the AI far more effective without bloating every prompt. The +cross-tool standard is [`AGENTS.md`][agents-md]; most harnesses can generate a +first draft for you (often via an `/init` command). + +Keep it focused on what is *not* obvious from the code: how to run the tests, +which tools to prefer, where generated files live, and any traps. Treat it as +documentation you maintain, not a dumping ground. + +:::{note} Claude Code and `AGENTS.md` + +Claude Code is the only major harness to *not* read `AGENTS.md`. You can support +both with a symlink, keeping a single source of truth: + +```bash +ln -s AGENTS.md CLAUDE.md +``` + +You can also mention `@AGENTS.md` inside `CLAUDE.md` if you want to add +specific instructions; this is true for all the other harnesses too +(`copilot-instructions.md`, etc). + +::: + +How you track the file is a separate decision: + +::::{tab-set} +:::{tab-item} Commit it + +Commit `AGENTS.md` so every contributor (and their harness) shares the same +project context. This is a good default for projects with at least one +maintainer also using AI harnesses. (Ignoring `CLAUDE.md` and `.claude/` is +also a good idea, due to that not supporting standards and being fairly +common.) + +::: +:::{tab-item} Ignore it + +Add `AGENTS.md` to your `.gitignore` if you'd rather each contributor maintain +their own. The ignore entry signals that the file is expected but personal. + +::: +:::{tab-item} Leave it out + +Don't reference it at all. Contributors who want a personal context file can +keep it out of version control locally by adding it to `.git/info/exclude`, +which (unlike `.gitignore`) is never shared. Some projects don't want to mention +AI at all, even in a `.gitignore`. + +::: +:::: + +## User-level configuration + +Beyond per-project context, most harnesses support a user-level config that +applies everywhere (for example `~/.claude/CLAUDE.md` or +`~/.config/opencode/AGENTS.md`). This is the place for your personal, +cross-project preferences, such as: + +- Your environment (System setup, GitHub username). +- Tool preferences, e.g. "use `uv run` in Python projects". +- Your commit and PR conventions, including the disclosure trailers above. +- If you use local or small models, you can request relative paths be used + (easier for them to write). + +Here's an example file: + +```markdown +You are on macOS, but have GNU sed. `python3` can be used if python without +dependencies is needed. Use `uv run` if in a python package. + +Use `prek -a --quiet` instead of `pre-commit run -a` for linting. + +If you make a commit, follow conventional commits and add a trailer: +`Assisted-by: :`, where `` is the current agent +harness, and `` is the AI model. + +Prefix PR descriptions and comments on PRs with the line ":robot: _AI text +below_ :robot:" to indicate you are an agent speaking on a user's behalf. +``` + +## Skills + +Skills are reusable, named sets of instructions for repetitive workflows that +you can invoke on demand: dropping a Python version, checking trusted +publishing, applying a project's changelog style, and so on. They follow a +shared [skills standard][agentskills], so a skill you write can work across +multiple tools. See [skills.sh][] for a catalog and more background. + +If you find yourself giving the AI the same multi-step instructions repeatedly, +that's a good candidate for a skill. AI can help you write skills. You can store +skills (like changelog skills) in a repository at `.agents/skills`, or for your +user at `~/.agents/skills`. The `gh skills` command can help you manage them. + +:::{note} +Yes, you probably guessed by now, Claude Code does not respect the standard +location. You have to symlink `.agents/skills` to `.claude/skills`, of course. +::: + +## A few harness features worth knowing + +The details vary by tool, but most modern harnesses share a common vocabulary: + +- **Slash commands** for built-in actions (e.g. initialize context, plan, or + review). `/init`, `/review`, `/diff`, `/skills`, etc. +- **`@`-mentions** to pull specific files into context. +- **Planning mode**, where the AI proposes an approach and asks clarifying + questions before editing. Valuable for anything non-trivial. +- **Subagents**, which run a sub-task in their own context and report back a + summary, useful for research and parallel work, and keeping your context + managed. +- **Model tiers**, letting you match a cheap, fast model to simple tasks and a + frontier model to hard ones. + +As you'll learn, effective use of AI is often about managing context; loading +the context with things the model needs to work on your problem (like design +spec documents, etc) is important, as is also keeping the context short +(limiting tool output, compacting, etc) to avoid giving the model too much to +think about. + +## Common concerns + +- **Don't one-shot.** Watch what the AI is doing, iterate, and steer it. + Planning mode and a quick read of the diff catch most problems early. +- **Verify, don't trust.** Models hallucinate; confirm invented explanations + and APIs. Reviewing with a *different* model family can catch issues a model + won't flag in its own work. +- **You own the result.** AI proposes; you decide. It does not know your + project's best practices unless you tell it, and it can't judge what is + "best". +- **Mind security.** Code sent to a hosted model leaves your machine; avoid + sending confidential code to providers you don't trust, and never grant an + agent destructive access (for example, to production data). AI tools are + themselves a supply-chain target; see the [security guide][security] for + dependency pinning, cooldowns, and CI hardening. +- **Beware untrusted content.** Anything an agent reads can carry instructions: + issue text, PR comments, a fetched web page, CI logs. A model can't reliably + tell your instructions from a payload buried in the content it was asked to + process - even in hidden comments. When you point an agent at outside + material (e.g. "triage these issues" or a CI run URL), review what it does + rather than letting it act unattended, and don't combine untrusted input with + destructive or credentialed access. This is unforunatly a big issue with + setting up an automated issue processing system. + +## What AI is good at + +AI is fantastic at anything that has a clear pass/fail condition. This means +it's great at fixing up a failing PR, addressing linter failures, polishing off +anything that's failing tests into making it pass tests. That's why good tests +and strong linters and type checking are so helpful to AI, they give it a +better pass/fail to work with. Do keep an eye on it, though, sometimes it will +skip something instead of fixing it; sometimes that's correct, but decision +making is not as strong of an AI skill as pass/fail checks! + +AI knows a massive library of tricks and details. It will hallucinate ones +sometimes, of course (that's why the pass/fail is important above!). Make it +validate anything (newer models often have this in the system prompts, so it is +model and harness dependent - for example, Claude Opus 4.8+ is paranoid +and validates without request). + +AI doesn't mind long or annoying tasks - iterating with a CI that takes minutes +or hours, running things though docker, figuring out how to build projects, +etc. You'll realize that things you know are good ideas, but you were too time +constrained to try before are perfect candidates for AI. Want to find the 20 +most important downstream projects and test them all before and after some +change you made? AI is happy to do it! + +As new models are coming that are better than humans at finding and exploiting +vulnerabilities, we need to be running those models on our code to find and fix +bugs before they can be exploited. + +## What should you try? + +Regardless of what AI companies tell you, one of the hardest things to do with +a model is write new code. Especially from scratch (it will mimic the current +style). That's also something that tends to be fairly enjoyable: Don't make AI +do stuff you'd rather do yourself! Start by using the AI to do the stuff you +*don't* like. Then start having it do things you wouldn't do because you don't +have time to do it. Here are some suggestions for prompts to try: + +:::{note} Disclaimer +These suggestions are for *your* projects. Never do this to someone else +without them asking for it! +::: + +- "Review this project for bugs, performance, simplifications, and + modernizations" - you might be shocked at how much it can find! + - Make sure you use a good model, and have it validate the findings (some + do not need extra prompting to do this). + - Followup: Put this into an issue, then open up draft PRs for these. + Group several into one PR when it makes sense. The PRs should reference + the issue. +- "Categorize all open issues. Highlight issues that can be easily closed, + and issues that are bugs that you can reproduce." + - Followup: "Launch subagents to fix all the reproduced bugs in worktrees, + and open a PR for each" +- "Explain the structure and design of this project". +- "Review the documentation for this project. Look for typos and gaps in + coverage." +- "Rebase this PR" +- Give it the URL to a flaky CI run and ask it to investigate it. +- Ask it to revive an old outdated PR based on the current codebase. +- Write something then ask it to apply what you did to something else similar. +- Point it at a bug report and ask it to reproduce it as a failing test, then + fix it. +- "Bisect this regression" - finding the commit that broke something is a + tedious mechanical loop AI is happy to run. +- "Add tests for the change I just made" - good tests and coverage give it a + clear pass/fail to work against. +- "Add type annotations here until the type checker passes." +- Ask it to draft release notes or a changelog from the git log between two + tags. It will try to mimic the existing style if there is one. + +[ai-pr-policy]: https://willmcgugan.github.io/ai-pr-policy/ +[agents-md]: https://agents.md +[agentskills]: https://agentskills.io +[skills.sh]: https://www.skills.sh +[security]: guides/security diff --git a/docs/guides/index.md b/docs/guides/index.md index e3a78dcd..a3712c0b 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -18,8 +18,9 @@ A section on CI follows, with a [general setup guide][gha_basic], and then two choices for using CI to distribute your package, one for [pure Python][gha_pure], and one for [compiled extensions][gha_wheels]. You can read about setting up good tests on the [pytest page][pytest], with -[coverage][]. There's also a page on setting up [docs][], as well as a page on -[security][] best practices. +[coverage][]. There's also a page on setting up [docs][], as well as pages on +[security][] best practices and information on using [agentic AI][ai] +responsibly. :::{tip} New project template Once you have completed the guidelines, there is a @@ -47,6 +48,7 @@ WebAssembly! All checks point to a linked badge in the guide. [gha_pure]: /guides/gha_pure.md [gha_wheels]: /guides/gha_wheels.md [security]: /guides/security.md +[ai]: /guides/ai.md [pytest]: /guides/pytest.md [right in the guide]: /guides/repo_review.md diff --git a/docs/myst.yml b/docs/myst.yml index ed00f642..4529a70d 100644 --- a/docs/myst.yml +++ b/docs/myst.yml @@ -31,6 +31,7 @@ project: - file: guides/gha_pure.md - file: guides/gha_wheels.md - file: guides/security.md + - file: guides/ai.md - file: guides/tasks.md - file: principles/index.md children: From 94de2e9c3af0dfcbea5eb032040165f00d8a02b2 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Thu, 25 Jun 2026 12:07:14 -0400 Subject: [PATCH 02/12] Enhance AI guide with usage tips Added tips for using AgentsView and Claude Code. --- docs/guides/ai.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/guides/ai.md b/docs/guides/ai.md index 5fb05902..14bf0659 100644 --- a/docs/guides/ai.md +++ b/docs/guides/ai.md @@ -338,6 +338,9 @@ without them asking for it! and issues that are bugs that you can reproduce." - Followup: "Launch subagents to fix all the reproduced bugs in worktrees, and open a PR for each" + +Smaller ideas: + - "Explain the structure and design of this project". - "Review the documentation for this project. Look for typos and gaps in coverage." @@ -355,8 +358,19 @@ without them asking for it! - Ask it to draft release notes or a changelog from the git log between two tags. It will try to mimic the existing style if there is one. +## Tips + +If you want to see your usage across harnesses, Wes McKinney (of Pandas fame) +has [AgentsView][], which reads local files from most harnesses and summarizes +for you. Try `uvx agentsview usage daily`, for example. A similar tool is +`npx ccusage`, which despite the name supports multiple harnesses too. + +If you use Claude Code, `npx ccstatusline` is much better than having the AI +try to write its own status line. + [ai-pr-policy]: https://willmcgugan.github.io/ai-pr-policy/ [agents-md]: https://agents.md [agentskills]: https://agentskills.io +[agentsview]: https://www.agentsview.io [skills.sh]: https://www.skills.sh [security]: guides/security From 7f934d1fe808d71346506ab4212a69334d47a027 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 25 Jun 2026 16:07:31 +0000 Subject: [PATCH 03/12] style: pre-commit fixes --- docs/guides/ai.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/ai.md b/docs/guides/ai.md index 14bf0659..e975b97e 100644 --- a/docs/guides/ai.md +++ b/docs/guides/ai.md @@ -340,7 +340,7 @@ without them asking for it! and open a PR for each" Smaller ideas: - + - "Explain the structure and design of this project". - "Review the documentation for this project. Look for typos and gaps in coverage." From 726d410eee661a8fa65eedf60bd4dece664e31ae Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Thu, 25 Jun 2026 13:27:30 -0400 Subject: [PATCH 04/12] docs: a few more tips Signed-off-by: Henry Schreiner --- docs/guides/ai.md | 35 ++++++++++++++++++++++++----------- 1 file changed, 24 insertions(+), 11 deletions(-) diff --git a/docs/guides/ai.md b/docs/guides/ai.md index e975b97e..30c16fa7 100644 --- a/docs/guides/ai.md +++ b/docs/guides/ai.md @@ -73,11 +73,11 @@ responding on your behalf, say so (e.g. with an AI disclaimer at top). You are accountable for every change you submit. **Don't submit slop.** Don't open a PR that a maintainer could finish faster -than they can review it, and don't mass-file unsolicited PRs. Reviewing a -careless PR can take far longer than writing it did; effectively a +than they can review it, and don't mass-file unsolicited PRs. Reviewing an +AI-generated PR can take far longer than writing it did -- effectively a denial-of-service on volunteer maintainers. If the change is trivial with AI, the maintainers probably could just trigger the AI themselves. Make sure the -pull request is welcome - check issues, ask first, etc. +pull request is welcome -- check issues, ask first, etc. ## `AI_POLICY.md` @@ -246,7 +246,7 @@ location. You have to symlink `.agents/skills` to `.claude/skills`, of course. The details vary by tool, but most modern harnesses share a common vocabulary: - **Slash commands** for built-in actions (e.g. initialize context, plan, or - review). `/init`, `/review`, `/diff`, `/skills`, etc. + review). `/init`, `/review`, `/diff`, `/skills`, `/compact`, etc. - **`@`-mentions** to pull specific files into context. - **Planning mode**, where the AI proposes an approach and asks clarifying questions before editing. Valuable for anything non-trivial. @@ -254,7 +254,8 @@ The details vary by tool, but most modern harnesses share a common vocabulary: summary, useful for research and parallel work, and keeping your context managed. - **Model tiers**, letting you match a cheap, fast model to simple tasks and a - frontier model to hard ones. + frontier model to hard ones. Use good models at first, then you'll learn what + is easy and hard for an AI, and can match better. As you'll learn, effective use of AI is often about managing context; loading the context with things the model needs to work on your problem (like design @@ -264,10 +265,12 @@ think about. ## Common concerns -- **Don't one-shot.** Watch what the AI is doing, iterate, and steer it. - Planning mode and a quick read of the diff catch most problems early. +- **Don't try one-shot.** Watch what the AI is doing and steer it. + Planning mode and a quick read of the diff catch most problems early. It's + fine to iterate, you aren't trying to make an AI commercial! - **Verify, don't trust.** Models hallucinate; confirm invented explanations - and APIs. Reviewing with a *different* model family can catch issues a model + and APIs. Make sure the model validated with testing, ask it to if it doesn't + first try. Reviewing with a *different* model family can catch issues a model won't flag in its own work. - **You own the result.** AI proposes; you decide. It does not know your project's best practices unless you tell it, and it can't judge what is @@ -278,12 +281,12 @@ think about. themselves a supply-chain target; see the [security guide][security] for dependency pinning, cooldowns, and CI hardening. - **Beware untrusted content.** Anything an agent reads can carry instructions: - issue text, PR comments, a fetched web page, CI logs. A model can't reliably - tell your instructions from a payload buried in the content it was asked to + issue text, PR comments, a fetched web page, CI logs. A model might confuse + instructions from a payload buried in the content it was asked to process - even in hidden comments. When you point an agent at outside material (e.g. "triage these issues" or a CI run URL), review what it does rather than letting it act unattended, and don't combine untrusted input with - destructive or credentialed access. This is unforunatly a big issue with + destructive or credentialed access. This is unfortunately a big issue with setting up an automated issue processing system. ## What AI is good at @@ -345,6 +348,7 @@ Smaller ideas: - "Review the documentation for this project. Look for typos and gaps in coverage." - "Rebase this PR" +- "Review PR #123" (most harnesses provide a `/review` command too). - Give it the URL to a flaky CI run and ask it to investigate it. - Ask it to revive an old outdated PR based on the current codebase. - Write something then ask it to apply what you did to something else similar. @@ -368,9 +372,18 @@ for you. Try `uvx agentsview usage daily`, for example. A similar tool is If you use Claude Code, `npx ccstatusline` is much better than having the AI try to write its own status line. +A very powerful technique is "rubber duck", where you develop code with one +model, then review it with a different model, feeding the review back into the +original model, and iterate. This can provide a significantly better result +than either model on its own, moving up +[about 74% to the next model class in some tests][rubberduck]. (This is also +why model disclosure is important). You don't need a specialized mode (copilot +has one), you can do this yourself if you have access to two model families. + [ai-pr-policy]: https://willmcgugan.github.io/ai-pr-policy/ [agents-md]: https://agents.md [agentskills]: https://agentskills.io [agentsview]: https://www.agentsview.io +[rubberduck]: https://github.blog/ai-and-ml/github-copilot/github-copilot-cli-combines-model-families-for-a-second-opinion/ [skills.sh]: https://www.skills.sh [security]: guides/security From fbe71e09a4c3e39c68fb024cbfa46a45340a5cd6 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Thu, 25 Jun 2026 14:35:41 -0400 Subject: [PATCH 05/12] Fix punctuation and add new ideas in AI guide --- docs/guides/ai.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/guides/ai.md b/docs/guides/ai.md index 30c16fa7..f649292e 100644 --- a/docs/guides/ai.md +++ b/docs/guides/ai.md @@ -344,7 +344,8 @@ without them asking for it! Smaller ideas: -- "Explain the structure and design of this project". +- "Explain the structure and design of this project." +- "What's new since last release? Changelog style." - "Review the documentation for this project. Look for typos and gaps in coverage." - "Rebase this PR" From 5b8f158db37a209ecbd4457221d5af5a20b76eb0 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Thu, 16 Jul 2026 20:17:12 -0500 Subject: [PATCH 06/12] Update docs/guides/ai.md Co-authored-by: Eric Ma --- docs/guides/ai.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/ai.md b/docs/guides/ai.md index f649292e..54d70a69 100644 --- a/docs/guides/ai.md +++ b/docs/guides/ai.md @@ -173,7 +173,7 @@ How you track the file is a separate decision: Commit `AGENTS.md` so every contributor (and their harness) shares the same project context. This is a good default for projects with at least one -maintainer also using AI harnesses. (Ignoring `CLAUDE.md` and `.claude/` is +maintainer also using AI harnesses. (Ignoring `CLAUDE.md` and `.claude/` in your `.gitignore` is also a good idea, due to that not supporting standards and being fairly common.) From 376a36f55b882342851dc06e6043cdb1858aab67 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Wed, 22 Jul 2026 19:50:05 -0400 Subject: [PATCH 07/12] Apply suggestions from code review Co-authored-by: Eric Ma Co-authored-by: Lundy Bernard --- docs/guides/ai.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/ai.md b/docs/guides/ai.md index 54d70a69..f36528f9 100644 --- a/docs/guides/ai.md +++ b/docs/guides/ai.md @@ -33,7 +33,7 @@ learns to code in this new era is still something unsolved. If you maintain a project: Try to engage with the human. If they are willing to interact (and not just type "address the review" into their harness), treat them like a human, even if you also see the AI working on their behalf. They -also may use AI to address a language barrier. +also may use AI to address a language barrier, or accommodate a disability. ::: ## Disclosure and transparency @@ -302,7 +302,7 @@ making is not as strong of an AI skill as pass/fail checks! AI knows a massive library of tricks and details. It will hallucinate ones sometimes, of course (that's why the pass/fail is important above!). Make it validate anything (newer models often have this in the system prompts, so it is -model and harness dependent - for example, Claude Opus 4.8+ is paranoid +model and harness dependent - for example, Claude Opus 4.8+ acts paranoid and validates without request). AI doesn't mind long or annoying tasks - iterating with a CI that takes minutes From ecee65bdf34477ad7c71e2115b0d18d5e53dfac8 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Thu, 23 Jul 2026 23:06:55 -0400 Subject: [PATCH 08/12] fix: some improvements Signed-off-by: Henry Schreiner --- docs/guides/ai.md | 82 +++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 72 insertions(+), 10 deletions(-) diff --git a/docs/guides/ai.md b/docs/guides/ai.md index f36528f9..a60435b8 100644 --- a/docs/guides/ai.md +++ b/docs/guides/ai.md @@ -92,7 +92,7 @@ and capacity. The tabs below sketch three levels you can adapt. AI-assisted contributions are welcome on the same footing as any other, as long as they meet the project's quality bar and are disclosed. -```markdown +````markdown # AI Policy AI-assisted contributions are welcome. We ask that you: @@ -100,7 +100,14 @@ AI-assisted contributions are welcome. We ask that you: - Disclose that AI was used and name the tool/model. - Review and understand every line you submit; you are responsible for it. - Meet the same quality, testing, and style standards as any contribution. + +Only humans can be named as co-authors. The Linux kernel trailer can be used to +credit AI assistance, like this: + +```text +Assisted-by: : ``` +```` ::: :::{tab-item} Moderate @@ -109,7 +116,7 @@ AI assistance is fine, but the burden is on the contributor to show real human involvement and prior buy-in before opening a PR. This mirrors the [original proposal][ai-pr-policy]. -```markdown +````markdown # AI Policy AI-assisted contributions are accepted only if: @@ -118,9 +125,18 @@ AI-assisted contributions are accepted only if: - It clearly states that it is AI-assisted and names the tool used. - It links to an issue or discussion where a maintainer agreed to the proposed change beforehand. +- AI-generated descriptions/comments are clearly marked and only used when + required. Unsolicited, undisclosed, or low-effort AI PRs will be closed. + +Only humans can be named as co-authors. The Linux kernel trailer should be used +to credit AI assistance, like this: + +```text +Assisted-by: : ``` +```` ::: :::{tab-item} Minimal @@ -128,13 +144,21 @@ Unsolicited, undisclosed, or low-effort AI PRs will be closed. AI-generated PRs are discouraged or restricted. Use this if you have limited review capacity. -```markdown +````markdown # AI Policy We do not accept unsolicited AI-generated pull requests. Please open an issue to discuss before contributing. Fully-reviewed, disclosed AI-assisted fixes may -be considered case by case. +be considered case by case. PRs suspected to be entirely AI-generated may be +closed without explanation. + +Only humans can be named as co-authors. The Linux kernel trailer must be used to +credit AI assistance, like this: + +```text +Assisted-by: : ``` +```` ::: :::: @@ -161,7 +185,7 @@ ln -s AGENTS.md CLAUDE.md ``` You can also mention `@AGENTS.md` inside `CLAUDE.md` if you want to add -specific instructions; this is true for all the other harnesses too +specific instructions; this is true for most other harnesses too (`copilot-instructions.md`, etc). ::: @@ -172,10 +196,10 @@ How you track the file is a separate decision: :::{tab-item} Commit it Commit `AGENTS.md` so every contributor (and their harness) shares the same -project context. This is a good default for projects with at least one -maintainer also using AI harnesses. (Ignoring `CLAUDE.md` and `.claude/` in your `.gitignore` is -also a good idea, due to that not supporting standards and being fairly -common.) +project context, and you can enforce project conventions this way. This is a +good default for projects with at least one maintainer also using AI harnesses. +(Ignoring `CLAUDE.md` and `.claude/` in your `.gitignore` is also a good idea, +due to that not supporting standards and being fairly common.) ::: :::{tab-item} Ignore it @@ -223,6 +247,9 @@ Prefix PR descriptions and comments on PRs with the line ":robot: _AI text below_ :robot:" to indicate you are an agent speaking on a user's behalf. ``` +Claude also allows a per-project `CLAUDE.local.md`; that should never be +committed, so put it in your global gitignore if you use it. + ## Skills Skills are reusable, named sets of instructions for repetitive workflows that @@ -306,7 +333,7 @@ model and harness dependent - for example, Claude Opus 4.8+ acts paranoid and validates without request). AI doesn't mind long or annoying tasks - iterating with a CI that takes minutes -or hours, running things though docker, figuring out how to build projects, +or hours, running things through Docker, figuring out how to build projects, etc. You'll realize that things you know are good ideas, but you were too time constrained to try before are perfect candidates for AI. Want to find the 20 most important downstream projects and test them all before and after some @@ -342,6 +369,13 @@ without them asking for it! - Followup: "Launch subagents to fix all the reproduced bugs in worktrees, and open a PR for each" +For an existing PR: + +- "You are an adversarial reviewer for the new feature in this branch. Do you + see any problems? Anything that could be done or written more cleanly? Can + you break it?" + - With a good model, this is really powerful. + Smaller ideas: - "Explain the structure and design of this project." @@ -373,6 +407,13 @@ for you. Try `uvx agentsview usage daily`, for example. A similar tool is If you use Claude Code, `npx ccstatusline` is much better than having the AI try to write its own status line. +If the AI makes bad decisions, it's probably missing context. Load design +documents, issues, conversations, and files (forcibly with `@` if needed) into +the context before starting. Use "plan" mode, and have it ask you questions. If +it's working on a feature and starting to become forgetful, you've probably got +too much context; use `/compact` liberally. Things like verbose output fill the +context with junk. + A very powerful technique is "rubber duck", where you develop code with one model, then review it with a different model, feeding the review back into the original model, and iterate. This can provide a significantly better result @@ -381,10 +422,31 @@ than either model on its own, moving up why model disclosure is important). You don't need a specialized mode (copilot has one), you can do this yourself if you have access to two model families. +Don't just do what you'd do with AI; have it do what you wouldn't do. If you +are developing a feature, ask AI to take several projects that use yours and +adapt them to your new feature. Take a PR where someone started using your +library and ask for all the pain points they faced transitioning to it. Have AI +try to find a way to break your feature or library. Look for gaps in your docs. +Have it follow your tutorial and tell you what was missing. It is happy to use +Docker or start up a database or other tools that you might not have time to +set up for a small problem. + +You can mix it in at your pace. If you are writing, try adding `TODO` comments +for things like adding links, then ask AI to find them and fix them. With +[marimo pair][], you can work on a notebook or slides but have AI connected and +able to help you edit anything you ask for, like splitting a slide into +columns, adding a summary slide, or analyzing a SQLite database and adding a +plot. + +If there's something repetitive, use AI to write a script to do it; it will use +fewer tokens and be more reliable than having AI do the repetitive thing +directly. + [ai-pr-policy]: https://willmcgugan.github.io/ai-pr-policy/ [agents-md]: https://agents.md [agentskills]: https://agentskills.io [agentsview]: https://www.agentsview.io +[marimo pair]: https://docs.marimo.io/guides/generate_with_ai/marimo_pair/ [rubberduck]: https://github.blog/ai-and-ml/github-copilot/github-copilot-cli-combines-model-families-for-a-second-opinion/ [skills.sh]: https://www.skills.sh [security]: guides/security From 39d368ee5828fe0c89403861701a8f1739655f81 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Thu, 23 Jul 2026 23:45:21 -0400 Subject: [PATCH 09/12] fix: adding some common parts to AI_POLICY.md Assisted-by: ClaudeCode:claude-fable-5 Signed-off-by: Henry Schreiner --- docs/guides/ai.md | 74 ++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 66 insertions(+), 8 deletions(-) diff --git a/docs/guides/ai.md b/docs/guides/ai.md index a60435b8..83ef6f29 100644 --- a/docs/guides/ai.md +++ b/docs/guides/ai.md @@ -20,6 +20,8 @@ as "Agentic AI": - Low-cost models running unattended in automated systems that mass-produce pull requests. This is what most people mean by "AI slop", and it is the source of most of the frustration maintainers feel about AI contributions. + They might be useful for something personal, but they should never be + contributing unsolicited. The recommendations below are aimed at the first case, and at keeping your project from being overwhelmed by the second. @@ -52,12 +54,19 @@ still yours (and your responsibility); the AI is a tool, not an author or copyright holder, which is what co-authored-by is for. A growing number of projects will close a PR with an AI co-author out of licensing concerns. -The Linux kernel trailer looks like this: +The Linux kernel trailer, part of the kernel's official +[coding assistants documentation][kernel-ai], looks like this: ```text Assisted-by: : ``` +The kernel doc adds one more rule worth copying: an AI must never add a +`Signed-off-by:` line, because certifying the DCO is a legal act only a human +can perform. Note that the trailer is not universal. Kubernetes, for example, +forbids AI trailers and wants disclosure in the PR description instead. +Always follow the policy of the project you are contributing to. + You can usually customize your harness to include this, either in an agents file (below), or via specific settings. @@ -77,7 +86,12 @@ than they can review it, and don't mass-file unsolicited PRs. Reviewing an AI-generated PR can take far longer than writing it did -- effectively a denial-of-service on volunteer maintainers. If the change is trivial with AI, the maintainers probably could just trigger the AI themselves. Make sure the -pull request is welcome -- check issues, ask first, etc. +pull request is welcome: check issues, ask first, etc. + +**Don't use AI on "good first issues".** Many projects are dropping this label +because people just use AI on it -- the point of this is to help new +contributors get used to the project, not to just push a button on an AI, a +maintainer can do that. (And yes, a human wrote the proceeding em-dash!) ## `AI_POLICY.md` @@ -100,9 +114,16 @@ AI-assisted contributions are welcome. We ask that you: - Disclose that AI was used and name the tool/model. - Review and understand every line you submit; you are responsible for it. - Meet the same quality, testing, and style standards as any contribution. +- Fully autonomous agents may not open issues or PRs. +- Respond to reviewers yourself. +- AI text in descriptions and issues should be clearly marked. -Only humans can be named as co-authors. The Linux kernel trailer can be used to -credit AI assistance, like this: +This applies to issues and comments as well as pull requests. Using AI for +translation or grammar help is fine. Contributions that ignore this policy may +be closed. + +Only humans can be named as co-authors, and AI can _never_ sign off on comment. +The Linux kernel trailer can be used to credit AI assistance, like this: ```text Assisted-by: : @@ -121,17 +142,25 @@ involvement and prior buy-in before opening a PR. This mirrors the AI-assisted contributions are accepted only if: -- The PR fills out the pull request template. +- The PR follows the same rules as a non-AI PR. - It clearly states that it is AI-assisted and names the tool used. - It links to an issue or discussion where a maintainer agreed to the proposed change beforehand. - AI-generated descriptions/comments are clearly marked and only used when required. +- A human drove the tool, reviewed every line, and can explain the change. +- Fully autonomous agents may not open issues or PRs. +- You respond to review comments yourself. + +This applies to issues and comments as well as pull requests. Using AI for +translation or grammar help is fine. AI output may infringe copyright; it is +your responsibility to make sure it does not. Unsolicited, undisclosed, or low-effort AI PRs will be closed. -Only humans can be named as co-authors. The Linux kernel trailer should be used -to credit AI assistance, like this: +Only humans can be named as co-authors, and AI can _never_ sign off on a +comment. The Linux kernel trailer should be used to credit AI assistance, like +this: ```text Assisted-by: : @@ -152,6 +181,11 @@ to discuss before contributing. Fully-reviewed, disclosed AI-assisted fixes may be considered case by case. PRs suspected to be entirely AI-generated may be closed without explanation. +This applies to issues, comments, and security reports as well as pull +requests. Autonomous agents may not contribute. Using AI for translation or +grammar help is fine. AI output may infringe copyright; it is your +responsibility to make sure it does not. Repeat violations may lead to a ban. + Only humans can be named as co-authors. The Linux kernel trailer must be used to credit AI assistance, like this: @@ -163,6 +197,22 @@ Assisted-by: : ::: :::: +For real examples, see the policies from [PyTorch][pytorch-ai], +[NumPy][numpy-ai], [Ghostty][ghostty-ai], and [LLVM][llvm-ai], whose "golden +rule" (shared with curl) sums the whole topic up: "a contribution should be +worth more to the project than the time it takes to review it." A +[community-maintained list][ai-policy-list] tracks policies across well over a +hundred projects. + +Some angles to consider if they matter to your project: AI in security reports +([curl][curl-ai] requires disclosure and human verification after a flood of +fabricated reports), AI on the reviewer side ([Fedora][fedora-ai] lets +reviewers use AI to assist, but not to make the accept/reject decision), and +"good first issues" (LLVM and Mozilla forbid using AI on them, since they exist +to teach newcomers). Some projects also cap open AI-assisted PRs per +contributor (Homebrew allows one at a time), a simple guard against +mass-produced PRs. + ## `AGENTS.md` Harnesses read a project context file to learn how your repository works -- @@ -442,11 +492,19 @@ If there's something repetitive, use AI to write a script to do it; it will use fewer tokens and be more reliable than having AI do the repetitive thing directly. +[ai-policy-list]: https://github.com/melissawm/open-source-ai-contribution-policies [ai-pr-policy]: https://willmcgugan.github.io/ai-pr-policy/ [agents-md]: https://agents.md +[curl-ai]: https://curl.se/dev/contribute.html#on-ai-use-in-curl +[fedora-ai]: https://docs.fedoraproject.org/en-US/council/policy/ai-policy/ +[ghostty-ai]: https://github.com/ghostty-org/ghostty/blob/main/AI_POLICY.md +[kernel-ai]: https://docs.kernel.org/process/coding-assistants.html +[llvm-ai]: https://llvm.org/docs/AIToolPolicy.html +[numpy-ai]: https://numpy.org/devdocs/dev/ai_policy.html +[pytorch-ai]: https://github.com/pytorch/pytorch/blob/main/AI_POLICY.md [agentskills]: https://agentskills.io [agentsview]: https://www.agentsview.io [marimo pair]: https://docs.marimo.io/guides/generate_with_ai/marimo_pair/ [rubberduck]: https://github.blog/ai-and-ml/github-copilot/github-copilot-cli-combines-model-families-for-a-second-opinion/ [skills.sh]: https://www.skills.sh -[security]: guides/security +[security]: /guides/security.md From 54f637fb6c0eecfa73be7b36c57430af32276ed8 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Fri, 24 Jul 2026 00:00:14 -0400 Subject: [PATCH 10/12] fix: clean up duplication Assisted-by: ClaudeCode:claude-fable-5 Signed-off-by: Henry Schreiner --- docs/guides/ai.md | 48 +++++++++++++++++++++-------------------------- 1 file changed, 21 insertions(+), 27 deletions(-) diff --git a/docs/guides/ai.md b/docs/guides/ai.md index 83ef6f29..be315a09 100644 --- a/docs/guides/ai.md +++ b/docs/guides/ai.md @@ -20,8 +20,6 @@ as "Agentic AI": - Low-cost models running unattended in automated systems that mass-produce pull requests. This is what most people mean by "AI slop", and it is the source of most of the frustration maintainers feel about AI contributions. - They might be useful for something personal, but they should never be - contributing unsolicited. The recommendations below are aimed at the first case, and at keeping your project from being overwhelmed by the second. @@ -88,10 +86,10 @@ denial-of-service on volunteer maintainers. If the change is trivial with AI, the maintainers probably could just trigger the AI themselves. Make sure the pull request is welcome: check issues, ask first, etc. -**Don't use AI on "good first issues".** Many projects are dropping this label -because people just use AI on it -- the point of this is to help new -contributors get used to the project, not to just push a button on an AI, a -maintainer can do that. (And yes, a human wrote the proceeding em-dash!) +**Don't use AI on "good first issues".** These exist to teach new contributors, +not to be a button an AI presses -- a maintainer could do that. LLVM and +Mozilla explicitly forbid it, and other projects are dropping the label +entirely. (And yes, a human wrote the preceding em-dash!) ## `AI_POLICY.md` @@ -208,10 +206,8 @@ Some angles to consider if they matter to your project: AI in security reports ([curl][curl-ai] requires disclosure and human verification after a flood of fabricated reports), AI on the reviewer side ([Fedora][fedora-ai] lets reviewers use AI to assist, but not to make the accept/reject decision), and -"good first issues" (LLVM and Mozilla forbid using AI on them, since they exist -to teach newcomers). Some projects also cap open AI-assisted PRs per -contributor (Homebrew allows one at a time), a simple guard against -mass-produced PRs. +per-contributor caps on open AI-assisted PRs (Homebrew allows one at a time), a +simple guard against mass-produced PRs. ## `AGENTS.md` @@ -281,7 +277,7 @@ cross-project preferences, such as: - If you use local or small models, you can request relative paths be used (easier for them to write). -Here's an example file: +::::{dropdown} Example user-level file ```markdown You are on macOS, but have GNU sed. `python3` can be used if python without @@ -297,6 +293,8 @@ Prefix PR descriptions and comments on PRs with the line ":robot: _AI text below_ :robot:" to indicate you are an agent speaking on a user's behalf. ``` +:::: + Claude also allows a per-project `CLAUDE.local.md`; that should never be committed, so put it in your global gitignore if you use it. @@ -334,11 +332,12 @@ The details vary by tool, but most modern harnesses share a common vocabulary: frontier model to hard ones. Use good models at first, then you'll learn what is easy and hard for an AI, and can match better. -As you'll learn, effective use of AI is often about managing context; loading -the context with things the model needs to work on your problem (like design -spec documents, etc) is important, as is also keeping the context short -(limiting tool output, compacting, etc) to avoid giving the model too much to -think about. +As you'll learn, effective use of AI is mostly context management. If the AI +makes bad decisions, it's probably missing context: load design documents, +issues, conversations, and files (forcibly with `@` if needed) before starting, +and use planning mode to have it ask you questions. If it becomes forgetful +mid-task, the context is too full: use `/compact` liberally, and don't let +verbose output fill the context with junk. ## Common concerns @@ -426,7 +425,7 @@ For an existing PR: you break it?" - With a good model, this is really powerful. -Smaller ideas: +::::{dropdown} Smaller ideas - "Explain the structure and design of this project." - "What's new since last release? Changelog style." @@ -447,6 +446,8 @@ Smaller ideas: - Ask it to draft release notes or a changelog from the git log between two tags. It will try to mimic the existing style if there is one. +:::: + ## Tips If you want to see your usage across harnesses, Wes McKinney (of Pandas fame) @@ -457,20 +458,13 @@ for you. Try `uvx agentsview usage daily`, for example. A similar tool is If you use Claude Code, `npx ccstatusline` is much better than having the AI try to write its own status line. -If the AI makes bad decisions, it's probably missing context. Load design -documents, issues, conversations, and files (forcibly with `@` if needed) into -the context before starting. Use "plan" mode, and have it ask you questions. If -it's working on a feature and starting to become forgetful, you've probably got -too much context; use `/compact` liberally. Things like verbose output fill the -context with junk. - A very powerful technique is "rubber duck", where you develop code with one model, then review it with a different model, feeding the review back into the original model, and iterate. This can provide a significantly better result than either model on its own, moving up -[about 74% to the next model class in some tests][rubberduck]. (This is also -why model disclosure is important). You don't need a specialized mode (copilot -has one), you can do this yourself if you have access to two model families. +[about 74% to the next model class in some tests][rubberduck]. You don't need a +specialized mode (copilot has one), you can do this yourself if you have access +to two model families. Don't just do what you'd do with AI; have it do what you wouldn't do. If you are developing a feature, ask AI to take several projects that use yours and From 6872c0aa9aafc51347064a1d0402b5662d71721d Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Fri, 24 Jul 2026 00:31:18 -0400 Subject: [PATCH 11/12] refactor: more orginization and dropdowns Signed-off-by: Henry Schreiner --- docs/guides/ai.md | 56 +++++++++++++++++++++++++++++------------------ 1 file changed, 35 insertions(+), 21 deletions(-) diff --git a/docs/guides/ai.md b/docs/guides/ai.md index be315a09..d31a8416 100644 --- a/docs/guides/ai.md +++ b/docs/guides/ai.md @@ -24,7 +24,8 @@ as "Agentic AI": The recommendations below are aimed at the first case, and at keeping your project from being overwhelmed by the second. -:::{note} +:::{attention} The developer using the tool +:class: dropdown The first point does hide something: the tool depends on the developer guiding it (just like any other tool). You will also see users with very little coding experience using these tools to produce low quality contributions. How someone @@ -46,11 +47,17 @@ contributing to open source - maybe the maintainer would like to try that model too. If you heavily edit the model output, then use your discretion; but being open about the whole process is generally better! +**Always follow the policy of the project you are contributing to.** The +following are general guidelines, but follow project policies if they exist. + **Credit AI in commits.** Follow the convention used by the Linux kernel and add a trailer. Never allow the model to add itself as a co-author. The code is still yours (and your responsibility); the AI is a tool, not an author or -copyright holder, which is what co-authored-by is for. A growing number of -projects will close a PR with an AI co-author out of licensing concerns. +copyright holder, which is what co-authored-by is for. An AI must never add a +`Signed-off-by:` line, because certifying the DCO is a legal act only a human +can perform. + +:::{note} The Linux kernel trailer The Linux kernel trailer, part of the kernel's official [coding assistants documentation][kernel-ai], looks like this: @@ -59,32 +66,34 @@ The Linux kernel trailer, part of the kernel's official Assisted-by: : ``` -The kernel doc adds one more rule worth copying: an AI must never add a -`Signed-off-by:` line, because certifying the DCO is a legal act only a human -can perform. Note that the trailer is not universal. Kubernetes, for example, -forbids AI trailers and wants disclosure in the PR description instead. -Always follow the policy of the project you are contributing to. - You can usually customize your harness to include this, either in an agents file (below), or via specific settings. +::: + +:::{warning} Not a universal standard +:class: dropdown +Note that the trailer is not universal. Kubernetes, for example, forbids AI +trailers and wants disclosure in the PR description instead. Some projects do +not want to know when AI was used so they can't be singled out later. +::: + **Write your own PR descriptions.** Generated PR summaries tend to be verbose, impersonal, and a chore to read. Write the description yourself. If a PR or comment does contain AI-generated prose, mark it clearly, for example with a -short disclaimer line at the top - and you can still write a human written -message above that disclaimer. +short disclaimer line at the top; you can still write a human written message +above that disclaimer. **Keep human review human-to-human.** Maintainers should never have to argue with a bot. Don't make a reviewer talk to an AI without knowing it; if an AI is -responding on your behalf, say so (e.g. with an AI disclaimer at top). -You are accountable for every change you submit. +responding on your behalf, say so (e.g. with an AI disclaimer at top). Don't +belittle a reviewer's time by not responding personally. **Don't submit slop.** Don't open a PR that a maintainer could finish faster than they can review it, and don't mass-file unsolicited PRs. Reviewing an -AI-generated PR can take far longer than writing it did -- effectively a -denial-of-service on volunteer maintainers. If the change is trivial with AI, -the maintainers probably could just trigger the AI themselves. Make sure the -pull request is welcome: check issues, ask first, etc. +AI-generated PR can take far longer than writing it did. If the change is +trivial with AI, the maintainers probably could just trigger the AI themselves. +Make sure the pull request is welcome: check issues, ask first, etc. **Don't use AI on "good first issues".** These exist to teach new contributors, not to be a button an AI presses -- a maintainer could do that. LLVM and @@ -195,6 +204,9 @@ Assisted-by: : ::: :::: +:::{seealso} Other examples +:class: dropdown + For real examples, see the policies from [PyTorch][pytorch-ai], [NumPy][numpy-ai], [Ghostty][ghostty-ai], and [LLVM][llvm-ai], whose "golden rule" (shared with curl) sums the whole topic up: "a contribution should be @@ -209,6 +221,8 @@ reviewers use AI to assist, but not to make the accept/reject decision), and per-contributor caps on open AI-assisted PRs (Homebrew allows one at a time), a simple guard against mass-produced PRs. +::: + ## `AGENTS.md` Harnesses read a project context file to learn how your repository works -- @@ -222,6 +236,7 @@ which tools to prefer, where generated files live, and any traps. Treat it as documentation you maintain, not a dumping ground. :::{note} Claude Code and `AGENTS.md` +:class: dropdown Claude Code is the only major harness to *not* read `AGENTS.md`. You can support both with a symlink, keeping a single source of truth: @@ -311,7 +326,8 @@ that's a good candidate for a skill. AI can help you write skills. You can store skills (like changelog skills) in a repository at `.agents/skills`, or for your user at `~/.agents/skills`. The `gh skills` command can help you manage them. -:::{note} +:::{note} Claude Skills +:class: dropdown Yes, you probably guessed by now, Claude Code does not respect the standard location. You have to symlink `.agents/skills` to `.claude/skills`, of course. ::: @@ -425,7 +441,7 @@ For an existing PR: you break it?" - With a good model, this is really powerful. -::::{dropdown} Smaller ideas +Smaller ideas - "Explain the structure and design of this project." - "What's new since last release? Changelog style." @@ -446,8 +462,6 @@ For an existing PR: - Ask it to draft release notes or a changelog from the git log between two tags. It will try to mimic the existing style if there is one. -:::: - ## Tips If you want to see your usage across harnesses, Wes McKinney (of Pandas fame) From f8cf472a0525de125858aa9d58d904be0bdaeb41 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Fri, 24 Jul 2026 00:37:49 -0400 Subject: [PATCH 12/12] fix: final rereview Assisted-by: ClaudeCode:claude-fable-5 Signed-off-by: Henry Schreiner --- docs/guides/ai.md | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/docs/guides/ai.md b/docs/guides/ai.md index d31a8416..65a3b0d9 100644 --- a/docs/guides/ai.md +++ b/docs/guides/ai.md @@ -48,7 +48,7 @@ too. If you heavily edit the model output, then use your discretion; but being open about the whole process is generally better! **Always follow the policy of the project you are contributing to.** The -following are general guidelines, but follow project policies if they exist. +following are general guidelines. **Credit AI in commits.** Follow the convention used by the Linux kernel and add a trailer. Never allow the model to add itself as a co-author. The code is @@ -59,8 +59,8 @@ can perform. :::{note} The Linux kernel trailer -The Linux kernel trailer, part of the kernel's official -[coding assistants documentation][kernel-ai], looks like this: +This is part of the kernel's official +[coding assistants documentation][kernel-ai], and looks like this: ```text Assisted-by: : @@ -86,8 +86,8 @@ above that disclaimer. **Keep human review human-to-human.** Maintainers should never have to argue with a bot. Don't make a reviewer talk to an AI without knowing it; if an AI is -responding on your behalf, say so (e.g. with an AI disclaimer at top). Don't -belittle a reviewer's time by not responding personally. +responding on your behalf, say so (e.g. with an AI disclaimer at top). Respect +a reviewer's time by responding personally. **Don't submit slop.** Don't open a PR that a maintainer could finish faster than they can review it, and don't mass-file unsolicited PRs. Reviewing an @@ -121,16 +121,17 @@ AI-assisted contributions are welcome. We ask that you: - Disclose that AI was used and name the tool/model. - Review and understand every line you submit; you are responsible for it. - Meet the same quality, testing, and style standards as any contribution. -- Fully autonomous agents may not open issues or PRs. +- Not use fully autonomous agents to open issues or PRs. - Respond to reviewers yourself. -- AI text in descriptions and issues should be clearly marked. +- Clearly mark AI text in descriptions and issues. This applies to issues and comments as well as pull requests. Using AI for translation or grammar help is fine. Contributions that ignore this policy may be closed. -Only humans can be named as co-authors, and AI can _never_ sign off on comment. -The Linux kernel trailer can be used to credit AI assistance, like this: +Only humans can be named as co-authors, and AI can _never_ sign off on a +commit. The Linux kernel trailer can be used to credit AI assistance, like +this: ```text Assisted-by: : @@ -156,7 +157,7 @@ AI-assisted contributions are accepted only if: - AI-generated descriptions/comments are clearly marked and only used when required. - A human drove the tool, reviewed every line, and can explain the change. -- Fully autonomous agents may not open issues or PRs. +- It was not opened by a fully autonomous agent. - You respond to review comments yourself. This applies to issues and comments as well as pull requests. Using AI for @@ -166,7 +167,7 @@ your responsibility to make sure it does not. Unsolicited, undisclosed, or low-effort AI PRs will be closed. Only humans can be named as co-authors, and AI can _never_ sign off on a -comment. The Linux kernel trailer should be used to credit AI assistance, like +commit. The Linux kernel trailer should be used to credit AI assistance, like this: ```text @@ -193,8 +194,9 @@ requests. Autonomous agents may not contribute. Using AI for translation or grammar help is fine. AI output may infringe copyright; it is your responsibility to make sure it does not. Repeat violations may lead to a ban. -Only humans can be named as co-authors. The Linux kernel trailer must be used to -credit AI assistance, like this: +Only humans can be named as co-authors, and AI can _never_ sign off on a +commit. The Linux kernel trailer must be used to credit AI assistance, like +this: ```text Assisted-by: : @@ -441,7 +443,7 @@ For an existing PR: you break it?" - With a good model, this is really powerful. -Smaller ideas +Smaller ideas: - "Explain the structure and design of this project." - "What's new since last release? Changelog style."