Custom rules for Foundry Verify
Custom rules give Foundry Verify project knowledge that may not be apparent from code alone, such as an API's ownership contract or a compatibility requirement. Foundry Verify reads your committed Markdown rules and uses the applicable rules as instructions when analyzing a pull request.
Set up custom rules
To start using custom rules:
-
Create
.foundry-verify/rules/general.mdat the root of your repository. -
Write the project-specific requirement you want Foundry Verify to apply. For example:
# Ownership of `_take` arguments In this project, functions ending in `_take` take ownership of their pointer arguments only when they succeed. If a call fails, the caller still owns those arguments. Flag changed call paths that release an argument after a successful `_take` call, or abandon it after a failed call without releasing it or passing ownership elsewhere.This example supplies a project contract: the name
_takealone does not establish what happens on failure.A single file can contain several requirements. You do not need a separate file for every rule.
-
Commit and push the file with your code. Foundry Verify uses the file when it next analyzes that commit in your pull request.
Use Markdown headings to group topics and bullets or paragraphs to describe individual requirements. Foundry Verify treats the contents as ordinary Markdown instructions, subject to the documented size limits; there is no YAML frontmatter, path header, special delimiter or per-rule schema. An empty file is a no-op.
How Foundry Verify uses your rules
Foundry Verify uses rules from the commit being analyzed, rather than uncommitted edits or another branch. It combines applicable rule files into the reviewer's initial instructions. A rule can establish a project requirement or direct investigation of a project-specific concern; a reported defect still needs evidence from the changed code.
Rules at the repository root apply throughout the repository. You can also scope rules to a component by placing another .foundry-verify/rules/ directory below it:
.foundry-verify/rules/general.md
lib/net/.foundry-verify/rules/network.md
The local directory applies to changes under lib/net/; its rules are considered together with the root rules when that subtree changes. Put Markdown files directly in each rules/ directory. Nested folders inside rules/, symlinks and external imports are unsupported.
When multiple directories apply, Foundry Verify considers root files before deeper directory files, then orders files deterministically by repository path. This keeps the same committed rules and changed paths reproducible across reruns.
Edit and rerun
To update rules, edit the file, commit and push, then rerun Foundry Verify against the new commit. To use rule updates from another branch, merge or rebase those updates onto your branch as usual.
Try a small change that violates a rule and another that satisfies it. Check that the review follows the requirement and respects its exceptions. Loading a rule does not guarantee that every defect will be found.
Write effective project-specific rules
- Supply missing project knowledge. Document contracts and conventions that cannot be reliably inferred from the code, rather than general reminders to avoid bugs.
- State the requirement and exceptions. Explain when a convention applies, what behavior is required, and when another behavior is acceptable.
- Group related requirements. Start with one file. Split it when different components or topics make separate directories easier to maintain.
- Keep rules current. Remove duplicates and revise rules when APIs or conventions change.
- Iterate on a specific concern. A small targeted check can help you see how a rule affects reviewer behavior. Avoid contradictory rules or instructions that demand a finding regardless of the code.
Understand the rules budget
Foundry Verify bounds each file and the combined rule context by character count:
| Input | Maximum |
|---|---|
| Rule characters considered from one file | 30,000 characters |
| Combined rule characters | 100,000 characters |
| Markdown files discovered in applicable directories | 64 |
These limits count Unicode characters in each Markdown body, excluding wrapper text added around the body. A character is one Unicode code point; the count is not UTF-8 bytes.
If a file is longer than 30,000 characters, Foundry Verify uses its first 30,000 characters and records that the file was truncated. The truncation is deterministic and does not depend on tokenization or byte length.
After per-file bounds are applied, files are considered in the deterministic order described above. Complete capped files are included while they fit within the 100,000-character combined limit. When the next file would exceed the remaining space, that file and every later file are omitted from the rule context. The review continues with the files already included and with its normal repository inspection.
Review details and maintenance
When size limits affect inclusion, the GitHub review keeps the details in one collapsed section titled Custom review rules. Expand it to see per-file bullets describing the affected files. For example, a bullet can say that security.md exceeded 30,000 characters and its first 30,000 characters were included, or that testing.md was omitted because the combined context limit had been reached. The details stay out of the main review body until expanded.
The source links in this illustrative example stand in for links to the committed rule files:
<details>
<summary>Custom review rules</summary>
- [security.md](https://example.invalid/rules/security.md): Exceeded the 30,000-character limit. The first 30,000 characters were included in the review context.
- [testing.md](https://example.invalid/rules/testing.md): Omitted from the review context because the combined rule limit was reached.
</details>
If a file is omitted or truncated, shorten or split the rule text and rerun after committing the correction. Keep related requirements together when they share a directory scope, and use deeper rules directories when a convention belongs to one component.
