docs(Agents): Add agent guidelines with examples and clarity #6291
Conversation
|
You have run out of free Bugbot PR reviews for this billing cycle. This will reset on December 10. To receive reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial. |
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
Docker builds report
|
emyller
force-pushed
the
docs/agents/enhance-guidelines
branch
from
4494f2e to
58a922a
Compare
github-actions
bot
added
docs
Co-authored-by: Claude <[email protected]>
emyller
changed the title
emyller
force-pushed
the
docs/agents/enhance-guidelines
branch
from
58a922a to
e67aea6
Compare
github-actions
bot
added
docs
| **Issues:** | ||
| ``` | ||
| <Verb> <object> [<condition>] | ||
| ``` |
There was a problem hiding this comment.
For bug reports, I'd prefer a short description of the bug. It's also one of the few places where we might allow the passive voice, for example, "The modal window is not closing when the Close button is clicked".
Ideally, I would like all of our issue titles to adhere to a pattern, but realistically this is not possible, so this directive may be useless or even confusing. If it's a guide on how to create issues, that opens up a separate discussion — for instance, I am not comfortable with the idea of issues being created by agents.
| ``` | ||
| <type>(<Component>): <Verb> <object> [<condition>] | ||
| ``` |
There was a problem hiding this comment.
I tend to use the following template for bugfix PRs:
fix: <Original issue title>
This, in my experience, results in nicer release notes.
I think this discussion is a good opportunity to standardise our approach, as currently, everyone uses their own format, as evident from the current release notes:
| - **ALWAYS** check linters and tests before commit. | ||
| - **NEVER** push. Do not offer to push. User controls all push operations. | ||
| - Amend recent commits when adding related fixes unless history conflicts with remote. | ||
|
|
There was a problem hiding this comment.
I expect to see pre-commit, or make lint, guidelines here.
| 1. "Add multiselect dropdown for context values" | ||
| 2. "Prevent replica lag issues in SDK views" | ||
| 3. "Fix permalinks in code reference items" | ||
| 4. "Restore logic for updating orgid_unique property" | ||
| 5. "Remove stale flags from codebase" | ||
| 6. "Clarify key semantics in evaluation context" | ||
| 7. "Centralize Poetry install in CI" | ||
| 8. "Handle deleted objects in SSE access logs" | ||
| 9. "Update Datadog integration documentation" | ||
| 10. "Add timeout to SSE stream access logs" |
There was a problem hiding this comment.
Is 10 an optimal number of examples? Can we get away with including less?
|
|
||
| ## Scope and Focus | ||
|
|
||
| - Limit issues to single, focused goals. Break complex work into multiple issues. |
There was a problem hiding this comment.
I'm not comfortable delegating scoping work to AI. Looks like the lines are blurred on whether we're allowing AI to create issues; see my other related comment.
| Use "Closes" when PR completes the issue. Use "Contributes to" when: | ||
| - PR resolves issue partially. | ||
| - Human actions still required for completion. | ||
|
|
||
| When uncertain, use "Contributes to". |
There was a problem hiding this comment.
I feel we can formalise this further, especially if we're applying the guidelines to current repo only:
- Backend changes should be accompanied with "Contributes to". Flagsmith engineering will add "Closes" to corresponding release-please PR once the change PR is merged.
- If the PR contains only frontend and/or documentation changes, "Closes" keyword should be used.
| 4. "Restore logic for updating orgid_unique property" | ||
| 5. "Remove stale flags from codebase" | ||
| 6. "Clarify key semantics in evaluation context" | ||
| 7. "Centralize Poetry install in CI" |
There was a problem hiding this comment.
Consider promptly changing to British spelling before Matt gets to see this.
| **Additional rules:** | ||
| - Never list file changes unless relevant (reviewers read patches). | ||
| - Mirror and sync checklists between issue and PR after push (user request) or fetch (unrestricted). | ||
| - Add "Review effort: X/5" at end of PR descriptions to indicate complexity (1=trivial, 5=extensive). |
There was a problem hiding this comment.
Maybe it's time we thought on a custom field for PRs @matthewelwell?
|
|
||
| **Additional rules:** | ||
| - Never list file changes unless relevant (reviewers read patches). | ||
| - Mirror and sync checklists between issue and PR after push (user request) or fetch (unrestricted). |
There was a problem hiding this comment.
How accurately does Claude follow this? I'd hate for it to inadvertently modify the issue body. Personally, I'd lean towards completely restricting the modification of issue bodies. I can tolerate slop in PR descriptions as long as AI authorship is clear. A thought of having it in issues is grinding my gears quite a bit.
Improves agent guidelines to enable more consistent and effective contributions.
Changes
Review effort: 2/5