Custom Instructions

Extend Macroscope’s default correctness check with context to improve precision and avoid false positives. Custom correctness instructions teach our core code review what’s idiomatic, intentional, or off-limits in your codebase, so it flags real issues and stays quiet on patterns it would otherwise misread. Drop markdown files into .macroscope/correctness/, optionally scope them with glob patterns, and your team’s domain knowledge is folded into the same correctness review you already get.

File layout

Create one or more markdown files inside .macroscope/correctness/ at the root of your repo:

.macroscope/
└── correctness/
    ├── configuration-principles.md
    ├── transaction-invariants.md
    └── auth-propagation.md

Subdirectories are walked recursively, so you can organize instructions by team or service — useful in monorepos:

.macroscope/
└── correctness/
    ├── shared-principles.md
    ├── backend/
    │   └── transaction-invariants.md
    └── frontend/
        └── accessibility-rules.md

Nesting is purely organizational. A file’s location does not affect which changes it applies to — that is controlled entirely by the include/exclude front matter. Only *.md files are read; any other files (and README.md) are ignored.

Front matter

Custom correctness instruction files support YAML front matter with the following fields:

Field	Type	Description
`include`	`string[]`	Glob patterns matching files these instructions apply to. If omitted, the instructions apply to all files reviewed.
`exclude`	`string[]`	Glob patterns matching files these instructions should not apply to. Evaluated after `include`.

If both include and exclude are omitted, the instructions apply globally to every file Macroscope reviews in the repo.

Example

.macroscope/correctness/configuration-principles.md:

---
include:
  - "**/*.go"
  - "**/config/**"
exclude:
  - "**/*_test.go"
  - "**/testdata/**"
---

**Configuration principles.** Configuration must be explicit. No empty-string-means-default. No silent fallbacks. If a required value is missing, fail fast and loud at startup — not silently at runtime with an infinite hang or mysterious behavior. One source of truth for each config value, threaded through explicitly. Misconfiguration is a bug, and bugs must be caught as early as possible.

**No backwards compatibility.** This product is pre-release and in active development, never require dual-support, deprecation warnings, migration code, proto reservations or fallback paths. When something changes, change it everywhere. Break the old way. Delete the old code. Build forward.

In this example, the rules apply to all Go files and anything under a config/ directory, but skip tests and test fixtures. When Macroscope reviews a change that touches a matching file, these principles are folded into the correctness review automatically.

Front matter is optional. A correctness instruction file with no front matter applies to every file in the repo.

How matching works

For each file changed in a pull request, Macroscope walks .macroscope/correctness/ and includes the contents of every instruction file whose include/exclude patterns match that file’s path. Multiple instruction files can apply to the same file — they stack. If no instruction file matches, the correctness review behaves exactly as it does for repos without custom instructions.

Getting Started

Agent

Code Review

Status

Support

File layout

Front matter

Example

How matching works

​File layout

​Front matter

​Example

​How matching works

File layout

Front matter

Example

How matching works