Before we get into our principles & guidelines around working with AI, here's a great starting principle which applies in many situations: If You are Asking for Human Attention, Demonstrate Human Effort. AI has not been used to author this guidance.
General principles & guidelines around PRs:
If using gen AI for complex work and/or consequential decisions which are worth careful planning, first create a PR containing only a plan in markdown, with no implementation, and allow time for others to for review.
The gist of this principle - let's take the time to review our own changes, and make sure plans and changes are digestible for our colleagues, it's the right thing to do. Specifically:
- PR descriptions must include a brief human-written explanation above any AI description, which explains the context behind the change and any trade-offs that were made and why. This is to demostrate your own understanding of what you're proposing.
- Never ask for reviews unless you have reviewed it first, have tried to understand the changes yourself, and have addressed AI feedback.
- What does "addressed AI feedback" mean? It means it's clear to a reviewer that something is resolved or why it's not resolved i.e. don't resolve AI feedback without a comment that explains why you resolved it. It's fine to use Claude etc to address feedback, as long as you follow the transparency principle below.
- If you don't understand what's going on - reach out to someone, everyone's experienced this at one point or another.
- One way to do this is to comment on your own PRs, calling out where you want a second opinion.
Never submit a PR comment (or slack message) misrepresented as a human when it's from AI.
- Prefix the output as "From Claude" if it's useful to provide the verbatim response, and you're able to learn this way.
- Reviewing is a great place to develop reasoning skills independent of AI.
‘Reject' is a hard word, but at the end of the day we have a duty to keep our systems secure and our user's data private. It's completely fine to reject a PR that is questionable, with clear reasoning.
- If the PR isn't ready for review, it's fine to turn it away with a friendly comment reminding about our review principles & guidelines.
- If something isn't fit for purpose and you have reason to believe it will cause issues for customers, you have an obligation to make that known.
- Disagreement is fine - high performing teams embrace disagreement.