Reading the docs at Bugbot | Cursor Docs I can’t tell whether Bug Bot supports BUGBOT.md files that act as a table of contents/map of where to find more specific rules/context.
Ideal use-case that I’m interested in is having a BUGBOT.mdin a folder within a repo that contains folder/file paths to .md files that give the context to Bug Bot with some reasoning/context on what the changes entail and the related rules to check that are relevant.
So a bit different/not always coverable by the nested BUGBOT.md paradigm which seems to be cumulative bottom up (from most specific upwards towards root). My goal here is not bloat context with unnecessary stuff and instead rely on model reasoning to navigate to a relevant rule/context containing.md file.
Right now, BUGBOT.md doesn’t support linking to other files in the repo or including them. There’s no @include or table of contents. Bugbot only uses the hierarchical setup with .cursor/BUGBOT.md described in the docs. It always loads the root-level file first, then for each changed file it walks up the directory tree and collects any nested BUGBOT.md files along the way.
So the current model is strictly cumulative from bottom to top, like you said.
A possible workaround is to place more targeted .cursor/BUGBOT.md files in specific subfolders, with rules that only apply to that part of the codebase. This helps keep the root BUGBOT.md small, with only project-wide rules, and avoids adding context for unrelated changes. It’s not exactly what you’re asking for since it won’t let the model jump to a referenced file, but it gets you the same benefit of keeping rules scoped to relevant areas.
If you want a table-of-contents or file-linking feature, I’d suggest posting a request in the Feature Requests category so the team sees it.
Yeah will do, think it would make sense to support it if possible considering rules/skills support file references/table of content paradigm of intelligent context addition/fetching.
Just wanted to follow up here with some updated info — BUGBOT.md does actually support referencing other files via standard markdown links. You can create a BUGBOT.md that links to other .md or .mdc files in your repo:
BugBot will follow those links and include the referenced files’ content as part of its review context. The paths are relative to the BUGBOT.md file’s location, and the referenced files need to be within the same repository.
This works for both the root .cursor/BUGBOT.md and nested BUGBOT.md files. So you could set up the “table of contents” pattern you described — a lightweight BUGBOT.md that points to more detailed rule files elsewhere in the repo.
The only constraints are:
Referenced files must have a .md or .mdc extension
Paths must be relative (no absolute paths or URLs)
Hi Cursor team / community — I’m trying to understand how BugBot loads rule content and whether it’s selective.
In our repo we use a root .cursor/BUGBOT.md as a Table of Contents, and it links to many additional modular rule docs under .cursor/bugbot/rules/*.mdc. Each modular rule doc also includes YAML frontmatter like globs: […] so the rules should apply only when PR changes match those paths.
My question:
When .cursor/BUGBOT.md contains many markdown links to rule docs, does BugBot load/include all linked files’ content every time, even if the changed files don’t match? Or does it filter and only load the linked docs whose globs match the changed paths?
Is there any official guidance on how this impacts review-context size/performance for large sets of rule docs?
In our case, it appears to work, but I’d like clarification on the expected behavior and performance characteristics.
---
description: BugBot rule: Go error handling
globs: ["fn/**/*.go", "common/**/*.go"]
alwaysApply: false
---
# Go Error Handling
- Preserve root cause with wrapping: `fmt.Errorf("...: %w", err)`.
- Do not replace a real source error with a new generic `errors.New(...)` in propagation paths.
- Do not wrap nil errors (`%w` with nil).
- Use `errors.New(...)` for static error strings and `fmt.Errorf(...)` for dynamic context.
- Do not silently swallow errors unless explicitly documented as non-fatal.
- If parse or conversion fails and code continues with defaults, log a warning with context.
- For external integration "entity not found" scenarios, use `errtypes.EntityNotFoundError` when appropriate.
- Retry logic must not silently succeed with `maxAttempts == 0`.
- Retry logic must avoid mutating shared input objects between attempts.
- Error messages should clearly describe operation and failure reason.