Monorepo Guidelines

Monorepos are messy. Frontend has accessibility rules, backend has API contracts, payments has compliance requirements. A single guideline file can’t cover all of it cleanly. Monorepo Guidelines lets you put the right review instructions next to the code they apply to, and Optibot picks up only the ones that matter for each PR.

Setting It Up

Open Repository Guidelines in the Optibot dashboard.

Choose your repository type

Under Directory-specific instructions, select Monorepo. This turns on per-directory instructions on top of your existing repository guidelines. If you only need one set of guidelines for the whole repo, leave it on Single repo / service.

Register your instruction files

Use the Reference a file field to register the markdown files that hold your review instructions. Enter repo-relative paths like frontend/frontend-review.md or typeguards/review.md. To add several at once, paste a comma or newline-separated list and click Add.

Each file you add shows its scope alongside the path in the list.

Create the files in your repo

Each file you register needs to actually exist in your repository. Write it the same way you would write a checklist for a teammate doing the review:

# Frontend Review Guidelines

## TypeScript
- New components must be fully typed. Avoid any.
- Use discriminated unions over boolean props for state.

## Accessibility
- Interactive elements need aria-label or visible text.
- Color alone cannot convey information.

## Performance
- Avoid re-renders from inline object or function literals in JSX.
- Lazy-load routes with React.lazy unless they are on the critical path.

## Styling
- Use design tokens from theme.ts. Do not hard-code hex colors.

Instructions are applied on top of your repository guidelines and Optibot’s standard review. They add scrutiny, they do not replace anything.

How Scoping Works

The location of an instruction file determines which PRs it applies to. A file only runs when the PR modifies at least one file inside that directory.

When a PR touches multiple directories, all matching files apply. If two files conflict on the same point, the deeper directory wins.

Best Practices

Keep the root file broad, directory files specific

The root instruction file is a good place for standards that genuinely apply across the whole codebase: commit message conventions, general naming rules, cross-cutting security requirements. Everything more specific belongs in the directory file closest to the code it governs. If a rule only matters in one subtree, it should only live there.

Write rules as things to flag, not general advice

Optibot gets the most out of specific, actionable instructions. “Flag any database query that concatenates user input directly into a SQL string” gives it something concrete to act on. “Write secure code” does not. Think about what a senior engineer on your team would actually push back on in a review and write that down.

Don’t repeat Optibot’s baseline

Optibot already catches common security issues, null safety problems, logic errors, and code quality concerns as part of its standard review. Your instruction files work best when they cover what is specific to your team’s conventions and domain, not things Optibot already handles.

One owner per file

Each instruction file should be owned by the team responsible for that directory. When multiple teams can edit the same file without coordination, rules start to conflict and the file becomes hard to trust. Treat each file the same way you would treat a CODEOWNERS entry.

Avoid contradicting the root

The root file sets the floor for the whole repo. If a directory file seems to need to contradict it, that usually means the root rule is too broad rather than that the directory needs an exception. Narrow the root rule to apply only where it belongs instead of fighting it from a subdirectory.

Keep them short

A focused ten-point file works better than an exhaustive fifty-point one. Prioritize the rules that would otherwise slip through review. Long files are harder to maintain and harder for Optibot to apply consistently.

Update them as the codebase evolves

Instruction files that reflect last year’s architecture produce noisy, irrelevant feedback. Review them when you make significant changes to a directory’s patterns or ownership, and remove rules that no longer apply.

Review Comment Footer

Each review comment includes a collapsible footer showing which instruction files Optibot used. It also flags:

• Skipped: instruction files modified by the PR itself (see Security below)
• Missing: files you have registered that do not exist in your repository, useful for catching typos or files that have been moved

Security

Instruction files are always read from your base branch, not the PR branch. Directory rules can only add to a review. They cannot suppress security findings, breaking bugs, or data integrity issues.

Adding or removing instruction files in the dashboard takes effect immediately for new PRs. Changes to the content of an instruction file take effect once they are merged into the base branch.