> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vectorlint.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Best practices

> Proven patterns for getting accurate, low-noise results from VectorLint across your content workflow.

These practices are drawn from the patterns that appear throughout the VectorLint documentation, consolidated here so you can apply them without reading every page first.

## Start with VECTORLINT.md, not rule pack files

Start with `VECTORLINT.md`. It requires no configuration, activates immediately, and brings your most important standards in plain language before you commit to structured rules.

After you run `VECTORLINT.md` against your content library and complete your first assessments, you can begin tuning the rules in 'VECTORLINT.md' based on your initial findings. This way, you'll have a sense of if you have styling gaps that warrant a dedicated rule pack file.

## Keep VECTORLINT.md under 800 tokens

VectorLint emits a warning at 4,000 tokens, but a practical target is *much* lower. Under 800 tokens leaves headroom for rule-specific instructions to add context without exceeding the effective limit. Long context degrades LLM precision and increases API costs on every review.

If your `VECTORLINT.md` is growing, that's usually a sign that some rules are specific enough to belong in a dedicated rule pack file instead.

## Write specific rules, not general ones

The quality of VectorLint's findings is directly proportional to the specificity of your rules. Vague rules produce vague findings, or worse, inconsistent findings that vary by run.

Instead of:

```
Check if the writing is clear.
```

Write:

```
You are a clarity evaluator for developer documentation. Flag sentences that:
1. Exceed 25 words
2. Use passive voice where active voice is possible
3. Contain filler phrases: "it is important to note", "please be aware", "in order to"
```

The second rule gives the LLM a defined audience, measurable criteria, and specific examples. It will produce consistent, actionable findings.

## Give rules domain context

LLMs review content relative to an implied standard. Make that standard explicit with a context block in your rule. Tell the model who the audience is, what they value, and what good looks like for your specific content type.

```markdown theme={null}
## CONTEXT BANK

**Audience**: Software engineers and DevOps practitioners who value:
- Technical precision over marketing language
- Practical examples over theory
- Direct answers without lengthy preambles
```

A grammar rule without context produces generic grammar findings. The same rule with a developer audience context produces findings calibrated to technical writing conventions.

## Use weights that reflect real priorities

In judge rules, weights are the single most important configuration decision. They determine which criteria actually control the final score. Treat them as a statement of your content team's values, not arbitrary numbers.

```yaml theme={null}
criteria:
  - name: Technical Accuracy
    weight: 40    # Factual errors erode user trust: this matters most
  - name: Clarity
    weight: 30    # Unclear docs generate support tickets
  - name: Tone
    weight: 20    # Important but recoverable in editing
  - name: SEO
    weight: 10    # Nice to have, never at the expense of the above
```

If everything has the same weight, nothing is prioritized.

## Start permissive, tighten over time

When rolling VectorLint out to a team for the first time, resist the urge to apply strict settings immediately. A workflow that generates too many findings on day one loses the team's trust before it earns it.

1. Start with `CONFIDENCE_THRESHOLD=0.75` and `standard` strictness
2. Run against your existing content library and review findings as a team
3. Identify which findings are consistently useful vs. consistently dismissed
4. Raise strictness on your highest-stakes rules first
5. Raise `CONFIDENCE_THRESHOLD` once your rules are stable

The goal is a workflow where every finding is worth reading. That takes iteration.

## Set a higher confidence threshold in CI than locally

In CI, a false positive blocks a merge. Set `CONFIDENCE_THRESHOLD` higher in your CI environment than in local development so only the highest-confidence findings gate a merge. Lower-confidence candidates still surface locally where a writer can review them in context.

```bash theme={null}
# Local development: catch more, review in context
CONFIDENCE_THRESHOLD=0.75

# CI environment: only high-confidence findings block merges
CONFIDENCE_THRESHOLD=0.85
```

## Gate CI only on production-bound content

Limit your CI workflow's `paths` filter to directories that actually ship to users. Checking drafts or work-in-progress in CI creates unnecessary friction and noise.

```yaml theme={null}
on:
  pull_request:
    paths:
      - 'content/docs/**'
      - 'content/api/**'
```

Drafts should have `RunRules=` in `.vectorlint.ini`. VectorLint skips them entirely and they never reach CI.

## Validate new rules before raising strictness

When you write a new rule, run it at `lenient` strictness and low `CONFIDENCE_THRESHOLD` first. Review everything it flags. Once you're confident the rule's coverage is correct and its false positive rate is acceptable, raise both settings to production levels.

Skipping this step leads to rules that look correct on paper but produce noise in practice, which erodes team confidence in the entire workflow.

## Next steps

* [Handling false positives](/handling-false-positives): detailed guidance on CONFIDENCE\_THRESHOLD and strictness
* [CI Integration](/ci-integration): set up content quality gates in your pipeline
* [Customize style rules](/customize-style-rules): write effective rules for rule pack files