Skip to content

Adopting on an existing codebase

A baseline records the violations a codebase already has. Turning declscope on then reports only what is new.

declscope baseline ./...       # writes .declscope-baseline.yaml

The file is found by the same upward lookup as the config, so its presence is all it takes.

packages:
  github.com/you/app/database:
    boundary:
      userRepository:
        - normalizeEmail
      statement:
        - Statement.wheres
      (core):
        - open
Spelling
A package-level declaration normalizeEmail, under its file's namespace
A member Type.member, under the namespace of its type's file
The core namespace (core)

An entry is keyed by package, rule, namespace and declaration, never by position. It survives code moving within its file. It does not survive a declaration moving to another namespace, since the same use then crosses a different boundary.

A baseline is regenerated, never edited.

declscope baseline ./...
git diff .declscope-baseline.yaml   # the record of what was cleaned up

A baseline suppresses and does not endorse.

  • Nothing is written into the source, so the rules apply to every new declaration.
  • An entry is removed only by fixing the violation.
  • A configured baseline that does not exist yet behaves as an empty one.
  • The analyzer never reports an entry as stale. A test variant sees references the ordinary variant does not, so only regeneration, which analyzes both, can tell.
Where the baseline is written 
declscope baseline [-o path] [-config path] [packages]   # packages default to ./...

Each package's entries go to the file the analyzer will consult for that package.

Target When
The baseline named by the package's nearest config file That config has a baseline key
The nearest existing .declscope-baseline.yaml above the package No config names one
A new .declscope-baseline.yaml in the working directory Neither of the above exists

-o bypasses that lookup and gathers every entry into one file.

Every file written is regenerated wholesale. The existing one is never read, so a baseline that fails to parse is replaced like any other.

Warning

Some packages cannot reach the working directory by that lookup, such as one in another module. The run then refuses and names them, rather than recording entries nothing would find.

Tip

skills/declscope-adoption is a skill for an AI agent doing this work. It covers what each diagnostic shape means, and the measurement traps that produce false confidence. The binary carries it:

declscope skill install            # the agents already set up in this project
declscope skill install --agent claude-code --scope user
declscope skill list               # where it is, and whether it is current

Without the binary, gh skill install mpyw/declscope declscope-adoption --agent claude-code writes to the same directories. The binary's installer is go-skill-embed, which takes them from gh skill install.