We also might want to mention (and link to?) the idea that we want to avoid churn.

Do we have a second anti-pattern to include in the list? Other bad things: hallucinations, incorrectly changing tests instead of fixing code, ...

i think you covered the incorrectly changing tests instead of fixing one. Good call. I like having that in the list.

I don't personally see that so often anymore with Opus 4.1 or Sonnet 4.5, but older or lower end models tend to reward hack their way into that state more often - it's a thing we'll likely encounter coming from new contributors for a while as they can't be assumed to be using the latest and greatest.

I don't understand what should be avoided:

• avoid using AI-assisted tools?
• avoid rewriting code blocks?
• avoid using Ai-assisted tools that rewrite code blocks?
  What is the recommended approach instead if we are telling people not to do a certain thing?

I would suggest starting the paragraph with something like:
"We discourage the use of AI when ..... "

Then followed with the explanation of why.
Currently this section reads with the "why" first.

I think this sentence was only intended to be tied to the false testing / false success bullet it is part of. Rather than wording it as "should be avoided" the right thing for users to do is to request that authors have reviewed the work in detail for problems like this before proposing it as a PR.

"Such changes do not represent a real fix. Authors must review the work done by AI tooling in detail to ensure it actually makes sense before proposing it as a PR."

I could maybe suggest adding an AI use tip for this situation like"iterate with your AI agent on the quality and utility of the change and tests to understand if the issue is actually fixed" but I'd leave that out for now as topic is maybe larger and constantly evolving, beyond the scope of this PR.

I'm trying to focus on a proactive positive outcome based wording rather than a negative like "avoid" or "discourage".

The reason being, the statements in here don't reflect all AI tooling. This devguide doc is about the use of AI, so we should assume those who read it are interested in or already using AI and are here to learn how to do it in an appropriate and productive manner.

Statements like "we discourage use of AI when ..." are likely to be outdated very quickly and discourage things that won't be true for long. Thus my desire to focus this on what we do want and why it is important for project health and reviewer respect.

I'd actually tighten this phrasing up a bit, we don't need to explain what shape AI tools can take or what they can do (anyone reading this knows that).

I find this list of anti-patterns to not be AI specific. We already reject PRs coming from people who make larger than necessary changes that are difficult to review. So I'd suggest wording it as a "positive desired thing, not negative example" phrasing, starting something like this:

• Make small focused edits, prefer not rewriting entire code blocks.
  This makes it easier to review changes and fully understand both the original intent of the code and the rationale behind the new modifications.
  ...

I think this sentence was only intended to be tied to the false testing / false success bullet it is part of. Rather than wording it as "should be avoided" the right thing for users to do is to request that authors have reviewed the work in detail for problems like this before proposing it as a PR.

"Such changes do not represent a real fix. Authors must review the work done by AI tooling in detail to ensure it actually makes sense before proposing it as a PR."

I could maybe suggest adding an AI use tip for this situation like"iterate with your AI agent on the quality and utility of the change and tests to understand if the issue is actually fixed" but I'd leave that out for now as topic is maybe larger and constantly evolving, beyond the scope of this PR.

I'm trying to focus on a proactive positive outcome based wording rather than a negative like "avoid" or "discourage".

The reason being, the statements in here don't reflect all AI tooling. This devguide doc is about the use of AI, so we should assume those who read it are interested in or already using AI and are here to learn how to do it in an appropriate and productive manner.

Statements like "we discourage use of AI when ..." are likely to be outdated very quickly and discourage things that won't be true for long. Thus my desire to focus this on what we do want and why it is important for project health and reviewer respect.

i think you covered the incorrectly changing tests instead of fixing one. Good call. I like having that in the list.

I don't personally see that so often anymore with Opus 4.1 or Sonnet 4.5, but older or lower end models tend to reward hack their way into that state more often - it's a thing we'll likely encounter coming from new contributors for a while as they can't be assumed to be using the latest and greatest.

I would use a different title than antipatterns. I would like to move toward "Considerations or Keys for Success".

I would start by linking to the section about submitting a quality PR:

• consider whether the change is necessary
• small, focused changes
• tests that exercise the change
• style follows the existing code

AI coding tools will compose code. The contributor, not the AI tool, is responsible for the quality and validity of code submitted with a PR.

Take the time to consider the code changes suggested by an AI tool. Respect the reviewer's time by validating your PR before submission.