Skip to content

Adopt in an Existing Repository

Existing repositories often have architecture debt. The goal is to freeze known violations while preventing new ones.

This page is the short existing-repository introduction. For the complete adoption and upgrade path — imports, structured baseline identity, snapshots, offline schemas, cache/profile/concurrency, and status-correct CI entrypoints — use Adopt or Upgrade ArchLinterNet.

1. Inspect real code first

Before writing YAML, identify:

  • project and assembly names;
  • namespace roots;
  • current project references;
  • existing architecture seams;
  • known migration issues;
  • build output paths needed by the CLI.

Do not start from an ideal diagram that does not map to real code.

2. Start with one strict rule

Pick a boundary that already passes or has a small known violation set:

contracts:
  strict:
    - id: domain-not-infrastructure
      name: domain-must-not-depend-on-infrastructure
      source: domain
      forbidden: [infrastructure]
      reason: Domain code must remain independent of infrastructure.

Run:

arch-linter-net --mode strict

3. Put future-state rules in audit

contracts:
  audit:
    - id: audit-application-to-legacy
      name: audit-application-to-legacy
      source: application
      forbidden: [legacy_runtime]
      reason: Discover legacy coupling before migration.

Audit rules give visibility without turning the first adoption PR into a large refactoring.

4. Generate a baseline for known debt

arch-linter-net baseline generate \
  --config architecture/dependencies.arch.yml \
  --output architecture/baseline.arch.yml \
  --reason "Initial adoption baseline"

Commit the baseline only after reviewing it. Each entry should represent known debt, not a new hiding mechanism.

5. Add CI

If the repository requires both strict and audit results from the same build state, make the one-process combined command the canonical CI entrypoint:

arch-linter-net --policy architecture/dependencies.arch.yml \
  --mode strict,audit --ensure-built \
  --report json=artifacts/architecture-results.json \
  --report sarif=artifacts/architecture-results.sarif

This command creates one immutable analysis snapshot and one snapshot-owned build/preflight preparation, including post-build receipt verification, then evaluates both modes from that snapshot. Its exit code is aggregate: validation fails when either mode fails. JSON and SARIF reports reuse the completed mode outcomes and do not trigger another analysis.

If audit is intentionally advisory, keep strict as the blocking gate and run a separate non-blocking audit step. Those independent CLI processes retain the backward-compatible single-mode paths and do not reuse prepared state across processes. See CI integration for both workflow shapes.

6. Tighten over time

As violations are fixed:

  1. Remove stale baseline entries.
  2. Promote mature audit rules to strict.
  3. Add coverage checks for unmapped namespaces when the policy shape is stable.
  4. Keep policy examples and AI guidance up to date.

Avoid false confidence

Do not add unsupported YAML fields just because they look plausible. If the schema does not support a field, the policy does not enforce that behavior. Check supported capabilities and non-goals.