Policy basics

.coverctl.yaml is what your AI coding agent reads when it calls coverctl check. It defines which directories belong to which domain (auth, payments, utilities, …) and what coverage threshold each domain must meet. The agent reads the same file you do — there is no separate agent-mode configuration.

This page is the file-format reference. For deeper patterns — diff-based enforcement, profile merging, integration tests — see Advanced configuration.

File Location

By default, coverctl looks for .coverctl.yaml in the current directory. If not found, it searches parent directories automatically (useful for monorepos).

# Use custom config path
coverctl check -c config/coverage.yaml

# Auto-detects from current or parent directories
cd packages/mypackage && coverctl check

Supported file names

coverctl searches for these files in order:

1. .coverctl.yaml
2. .coverctl.yml
3. coverctl.yaml
4. coverctl.yml

Basic Structure

version: 1

policy:
  default:
    min: 75
  domains:
    - name: core
      match: ["src/core/**"]   # path glob; Go often uses "./internal/core/..."
      min: 85

exclude:
  - "**/generated/**"

Configuration Options

version

Required. Schema version for future compatibility.

version: 1

extends

Inherit configuration from a parent file. Useful for monorepos where packages share common policies.

packages/api/.coverctl.yaml

extends: ../../.coverctl.yaml  # Path relative to this config file

policy:
  domains:
    - name: api
      match: ["./..."]
      min: 90  # Override parent threshold

Child configs override parent values. See Monorepo Support for details.

policy

Coverage policy configuration. See Policies.

policy:
  default:
    min: 75
  domains:
    - name: core
      match: ["src/core/**"]
      min: 85

Domains match source paths (globs like src/api/**, or Go package paths like ./internal/api/...). Details: Domains.

exclude

Glob patterns for files to exclude from coverage. See Domains.

exclude:
  - "**/generated/**"
  - "**/mocks/**"
  - "**/*_test.go"

files

Per-file coverage rules. See Policies.

files:
  - match: ["src/core/*"]
    min: 90

diff

Diff-based coverage mode. See Advanced.

diff:
  enabled: true
  base: origin/main

integration

Integration test coverage. See Advanced.

integration:
  enabled: true
  packages: ["./internal/integration/..."]
  run_args: ["-test.run", "TestIntegration"]

merge

Profile merging. See Advanced.

merge:
  profiles:
    - ".cover/unit.out"
    - ".cover/integration.out"

annotations

Code annotation support. See Advanced.

annotations:
  enabled: true

Schema Validation

A JSON schema is available at schemas/coverctl.schema.json for editor integration:

# yaml-language-server: $schema=./schemas/coverctl.schema.json
version: 1

For a full worked .coverctl.yaml, see Domains and Policies, or copy templates/coverctl.yaml.

Next Steps

DomainsMatch patterns and per-domain mins

PoliciesDefaults, warn thresholds, ratchet

AdvancedFiles, diff, merge, annotations

MonorepoConfig inheritance and workspace support