Brownfield Adoption Guide

This guide walks through adopting NotarAI on an existing codebase. You do not need to spec everything at once. Start with the most critical modules and expand coverage incrementally.

Prerequisites

A Git repository with existing code
NotarAI installed (Installation)

Step 1: Initialize NotarAI

notarai init

This sets up the .notarai/ directory, validation hooks, slash commands, and MCP server configuration. See the Quick Start for details on what init creates.

Step 2: Create a system spec with broad exclusions

Start with a system spec that explicitly excludes files you do not want to track:

# .notarai/system.spec.yaml
schema_version: '0.8'
intent: >
  Top-level system spec for the project. Defines subsystem
  composition and excludes vendor, generated, and config files.
artifacts:
  configs:
    - path: 'package.json'
      role: 'package manifest'
exclude:
  - 'vendor/**'
  - 'node_modules/**'
  - 'dist/**'
  - 'build/**'
  - '.github/**'
  - '*.lock'
  - '*.config.*'

The exclude patterns use glob syntax. Files matching these patterns will not be flagged as “unspecced” by notarai check.

Step 3: Bootstrap specs for critical modules

Use the bootstrap interview to create specs for your 2-3 most important modules:

# In Claude Code:
/notarai-bootstrap

# Or for any agent:
notarai export-context --bootstrap | pbcopy

The bootstrap flow interviews you about the module’s purpose, behaviors, constraints, and invariants, then drafts a spec. You review and approve before anything is written.

Focus on modules where drift would cause the most damage: authentication, billing, core business logic.

Step 4: Run your first check

notarai check

This reports:

Coverage gaps: Files not governed by any spec (expected to be large initially)
Orphaned globs: Spec artifact patterns matching no files (should be zero for freshly created specs)

Do not try to eliminate all coverage gaps immediately. A large brownfield codebase will have many unspecced files, and that is fine. The goal is progressive coverage.

Step 5: Add specs as modules are touched

When you modify a module, that is the natural time to add a spec for it. The incremental approach:

Before making changes, create a spec for the module (or use /notarai-bootstrap to interview about it)
Make your code changes
Run /notarai-reconcile to verify the spec still aligns
Commit the spec alongside the code changes

Over time, your most-changed modules will naturally accumulate spec coverage.

Step 6: Set up CI drift detection

Add the NotarAI GitHub Action to your PR workflow:

# .github/workflows/notarai.yml
name: NotarAI Check
on:
  pull_request:
    branches: [main]

permissions:
  contents: read
  pull-requests: write

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: davidroeca/NotarAI/crates/notarai-action@v0.7.0

This runs notarai check on every PR and posts a comment summarizing findings. See the GitHub Action reference for configuration options.

Over-speccing too early. Do not try to write full behavioral specs for every module on day one. Start with tier: registered specs that just map intent to artifacts. Add behaviors later for critical paths. See Progressive Adoption.

Ignoring coverage gaps. Coverage gaps are warnings, not errors. They are informational. Do not suppress them globally; instead, add exclude patterns for directories you genuinely do not want to track (vendor, generated code).

Speccing generated code. Files generated by build tools, compilers, or code generators should be excluded (Tier 3) or tracked as derived (Tier 4). Do not write behavioral specs for generated output.

Realistic timeline

For a medium-sized project (50-100 source files, 5-10 logical modules):

Day 1: notarai init, system spec with exclusions, 2-3 module specs via bootstrap
Week 1-2: Add specs for modules you are actively working on
Month 1: 40-60% coverage of source files; CI drift checks running on PRs
Ongoing: Coverage grows naturally as modules are touched

There is no pressure to reach 100% coverage. Many teams find that 60-80% coverage of source files (with the remainder excluded or registered) provides the right balance of safety and maintenance cost.

Keyboard shortcuts

NotarAI