Prelint
Overview

Writing specs Prelint can review

1. Put specs where the code lives#

Drop markdown files into the repository. Prelint indexes them automatically, so specs/, docs/, or the repository root all work. Specs versioned next to code get reviewed and updated in the same pull requests as the code they constrain.

2. Write explicit requirements#

The review engine evaluates diffs against what your spec states. Ambiguous language produces ambiguous reviews.

Write this:

- Always store the charge in vendor currency.
- Show the customer a converted estimate at booking time.
- Sessions expire after 30 days of inactivity.

Not this:

- We should probably keep currency handling consistent.
- Sessions might want a reasonable expiry.

3. Use clear headings and bullets#

Headings scope a rule to a domain, which helps the engine match a diff to the right constraint. A file named specs/pricing/settlements.md with an ## International settlements heading gives the review engine a precise anchor to cite back in the finding.

4. Record decisions, not just requirements#

Architecture decision records tell the engine which trade-offs were approved and which patterns are forbidden. When someone opens a pull request that reintroduces a rejected approach, the finding cites the decision that rejected it.

5. Add custom rules for what specs do not cover#

Project-specific constraints that do not belong in a product spec go into prelint.json:

{
  "rules": [
    {
      "name": "No direct database queries in handlers",
      "description": "All database access must go through the repository layer. Handler functions should not import or use database clients directly."
    }
  ]
}

6. Keep specs current#

A spec the team no longer follows produces findings the team learns to ignore. When a product decision changes, change the spec in the same pull request.

Powered by Docsbook