architecture-enforcement

Architecture Enforcement

Make architectural constraints mechanically checkable. If a human has to review every PR to catch layer violations, the rule isn't real.

Four categories of enforceable architecture (Factory.ai framework)

Category	Example	Enforcement
Grep-ability	"All SQL queries go through db/queries/"	Custom grep analyzer in golangci-lint / ESLint no-restricted-imports
Glob-ability	"No test code outside *_test.go"	File pattern rules in dependency-cruiser / go-arch-lint
Architecture boundaries	"Domain doesn't import infrastructure"	go-arch-lint / dependency-cruiser / sheriff
Security	"No exec.Command outside cmd/"	gosec / ESLint security plugin / depguard

A rule that fits in one of these four categories can be enforced. Rules that don't (e.g., "use idiomatic error handling") must be handled by human review or LLM review.

Go: go-arch-lint

The canonical tool. Declarative YAML, component-based, allow/deny lists.

Full Clean Architecture example is at ${CLAUDE_PLUGIN_ROOT}/templates/.go-arch-lint.clean-arch.yml.

Key directives:

• components — define named groups of packages via glob
• deps.<component>.allow — explicit allowlist of components this one may import
• deps.<component>.mayDependOn — same, alternative name
• excludeFiles — files to skip (generated, mocks, tests)

Running it: go-arch-lint check — exits non-zero on violations. The post-edit-lint.js hook runs this after every .go file edit.

Go: depguard (inside golangci-lint)

For forbidden imports that aren't about layering:

linters-settings:
  depguard:
    rules:
      main:
        deny:
          - pkg: "github.com/pkg/errors"
            desc: "use standard errors + fmt.Errorf with %w instead"
          - pkg: "io/ioutil"
            desc: "deprecated; use os and io"
          - pkg: "math/rand"
            desc: "use crypto/rand for anything security-related"

TypeScript: dependency-cruiser

Framework-agnostic. Regex path matching. Best for existing codebases with flexible layering.

// .dependency-cruiser.js
module.exports = {
  forbidden: [
    {
      name: 'no-circular',
      severity: 'error',
      from: {},
      to: { circular: true },
    },
    {
      name: 'domain-pure',
      severity: 'error',
      from: { path: '^src/domain' },
      to: { path: '^src/(infrastructure|interfaces|application)' },
    },
    {
      name: 'no-deprecated',
      severity: 'error',
      from: {},
      to: { dependencyTypes: ['deprecated'] },
    },
  ],
};

TypeScript: @softarc/sheriff

Tag-based, ESLint plugin, enforces a module graph.

// sheriff.config.ts
export const config = {
  tagging: {
    'src/domain': ['domain'],
    'src/application': ['application'],
    'src/infrastructure': ['infrastructure'],
  },
  depRules: {
    domain: [],                            // pure
    application: ['domain'],
    infrastructure: ['domain', 'application'],
  },
};

Sheriff runs inside ESLint (so you need ESLint in the project). dependency-cruiser runs standalone (lighter).

Custom analyzers (when standard tools aren't enough)

For rules that don't fit the above tools, write a custom go/analysis analyzer or an ESLint rule. Keep them small — one rule per analyzer.

Example use cases:

• "All HTTP handlers must call ctx := r.Context() as the first line"
• "All Redis keys must go through cache.Key(...)"
• "All proto field comments must explain the unit if numeric"

These live in a tools/lint/ directory in the target repo, not in this plugin.

Running everything locally

The /harness:lint-all command runs all enforcement passes sequentially:

# Go
gofumpt -l .
golangci-lint run
go-arch-lint check
gosec ./...

# TypeScript
biome check .
oxlint
tsc --noEmit
depcruise src
knip

# Proto
buf format --diff
buf lint
buf breaking --against .git#branch=main

Key learnings

• Start loose, tighten gradually: set new rules to severity: warn for a week, then upgrade to error. You'll find false positives you didn't anticipate.
• Grandfather existing violations: most tools support a baseline file or allow-until annotation. Use them — don't block a merge over a preexisting issue.
• One rule per file: debugging "which rule is failing" is much easier when rules are isolated. Don't pack 20 rules into one config section.
• Architecture rules are documentation: .go-arch-lint.yml is the single source of truth for "how this codebase is supposed to be structured". Write it first, implement later.

Related Skills

• go-stack, ts-stack, proto-stack — language-specific harness detail
• config-protect — why you can't edit these configs as an agent
• pr-review-multi-model — the LLM-based review that catches non-deterministic issues

Gotchas

See gotchas.md.