Getting Started
-
Start Small: Begin with your top 10 most critical rules
-
Iterate: Add rules based on recurring PR feedback over time
-
Guidelines size: Keep guidelines files between 1200-2200 words
-
Language: Use flexible but specific language. Only cover gaps in optibot's knowledge rather than common patterns.
-
Configure Optibot: Point to your guidelines file in your Optibot configuration
-
Test & Refine: Monitor review quality and adjust guidelines accordingly
Remember: Your guidelines are context engineering, not documentation. Focus on what makes your codebase unique, and let Optibot handle the rest.
How do I link to my guidelines file in the .optibot config:
In order for optibot to incorporate your guideline file into your code review process. It must be present as markdown within your repository on github or gitlab. Guideline files have a 1-1 relationship with your repositories. Each repository should have its own guidelines file.
In order to effectively use an optibot guidelines file it must be added to your .optibot config like so. In this example our file is called optibot-guidelines.md and its situated in our optimal-monorepo repo.
Example config
{
"guidelinesUrl": "https://github.com/OptimalRepo/optimal-monorepo/blob/development/optibot-guidelines.md",
}
Measuring guidelines success
Your guidelines are effective when:
-
Optibot catches issues you care about (architectural violations, security gaps)
-
False positive rate is low (reviews are relevant, not nitpicky)
-
Engineers reference guidelines in PR discussions (they're actually useful)
-
New team members onboard faster (guidelines encode tribal knowledge)
Here are some metrics that you can track over 2-4 weeks:
-
Number of guideline-violation comments per PR
-
Numbers of comments and discussions with optibot per PR
-
Engineer agreement rate with Optibot feedback
-
Time to resolve violations
P.S You can track some of these metrics in the Optimal Insights platform