Setup Arch Unit

Setup Architecture Rules

Instructions

Enforce the project's package boundaries as lint rules, and run them in a pre-commit hook.

Go already enforces two boundaries in the compiler: import cycles are a build error, and internal/ packages cannot be imported from outside their parent tree. Do not write a rule for either. The rules here cover what the compiler allows but the Nexa conventions forbid.

The rules live in .golangci.yml, so every place that already runs golangci-lint enforces them with no extra step: /code-quality during implementation, and the workflow from /setup-quality-ci on every pull request. The pre-commit hook runs only the architecture linters, so it stays fast.

Nexa Rules Gate

Read and follow ${CLAUDE_PLUGIN_ROOT}/shared/readiness/NEXA_RULES_GATE.md.

Prerequisites

• go.mod — read the module path; every rule below uses it in place of example.com/app
• golangci-lint v2 and a .golangci.yml with version: "2" — if either is missing, stop and tell the user to run /code-quality first

DO NOT

• Add an architecture library (arch-go, go-arch-lint) — depguard and forbidigo ship with golangci-lint
• Write rules for import cycles or internal/ visibility — the compiler enforces them
• Apply a rule to generated code (internal/db/, *_templ.go) — sqlc and templ own those imports
• Enable an opt-in rule (feature isolation, layered architecture) without the user's explicit confirmation
• Invent option names — use only what the golangci-lint v2 documentation from Step 0 shows
• Write a rule whose files globs match no file in the project — detect first, then write
• Skip Step 6 — a depguard rule whose globs match nothing passes silently
• Silence a violation with //nolint to make the first run pass
• Touch any other hook manager's configuration beyond the one block this skill owns

Step 0: Consult Documentation

Use the context7 MCP server (library /golangci/golangci-lint) to confirm, for the installed version:

1. depguard — linters.settings.depguard.rules.<name> with list-mode, files, allow, deny (pkg, desc); the $all, $test, and $gostd variables; ! negation in files; the trailing $ for an exact package match
2. forbidigo — linters.settings.forbidigo.forbid (pattern, pkg, msg) and analyze-types
3. Exclusions — linters.exclusions.rules with path and linters
4. CLI — golangci-lint run --enable-only <linters>

Prefer the documentation over the snippets below if they differ.

Workflow

Step 1: Gather Context

1. go.mod — module path and Go version
2. .golangci.yml — which linters are enabled; does it already have depguard or forbidigo settings? If yes, read them and ask whether to extend, replace, or skip
3. Package layout — go list ./..., then record:
   • Feature packages: internal/<feature>/ holding handler.go or service.go
   • Shared packages that exist: internal/auth, internal/config, internal/db, internal/i18n, internal/testdb, internal/web, internal/web/layout
   • Layered folders: any domain/, application/, infrastructure/, ports/, adapters/
4. Hook manager — in this order: lefthook.yml / lefthook.yaml, .pre-commit-config.yaml, git config core.hooksPath, .husky/. None found → plain git hooks in .githooks/
5. Existing violations — for each default rule below, grep the imports it would deny so the Step 2 proposal can say up front which rules will fail on the first run

Step 2: Propose the Rule Set

Proposed architecture rules (Nexa Go conventions and your package layout):

Enabled by default

• R1 — No database access outside sqlc in feature code. internal/<feature>/ must not import database/sql, github.com/jackc/pgx/v5/pgxpool, github.com/jackc/pgx/v5/stdlib, github.com/lib/pq, github.com/jmoiron/sqlx, or gorm.io/gorm. Features use the sqlc db.Querier; SQL lives in db/queries/. The pgx root package (pgx.ErrNoRows), pgtype (sqlc parameter types), and pgconn (*pgconn.PgError codes) stay allowed.
• R2 — Services are transport-free. internal/*/service.go must not import net/http, github.com/a-h/templ, or internal/web. Business rules must be callable from a job or a CLI, and unit-testable without a request.
• R3 — Shared packages never import features. internal/auth, internal/config, internal/i18n, internal/web/layout must not import any feature package ([detected list]). Only internal/web/routes.go wires features together.
• R4 — Only internal/config reads the environment. os.Getenv, os.LookupEnv, and os.Environ are forbidden elsewhere (except cmd/ and tests). One place validates configuration.

Opt-in

• R5 — Feature isolation. A feature package must not import another feature package. Shared behaviour moves to a shared package. Strict — it blocks a use case from calling another use case's service.
• R6 — Layered architecture [only if layered folders were detected]. domain imports only the standard library and domain; application must not import infrastructure / adapters.

[If Step 1.5 found violations: "R1 will fail on the first run: internal/item/service.go imports database/sql."]

Enable an opt-in rule, add a custom rule ("package A must not import B"), remove a default, or confirm?

Wait for the user. Then confirm once more:

Setting	Value
Rules	[enabled rule IDs]
Config	.golangci.yml (depguard, forbidigo)
Run	golangci-lint run --enable-only depguard,forbidigo ./...
Pre-commit	[lefthook / pre-commit / .githooks/pre-commit]

Proceed?

Step 3: Write the Rules

Add depguard and forbidigo to linters.enable and merge the settings into .golangci.yml, keeping everything already there. Fill in the module path, the detected feature packages, and only the shared packages that exist.

linters:
  enable:
    - depguard
    - forbidigo
  settings:
    depguard:
      rules:
        # R1 — No database access outside sqlc in feature code
        r1-no-db-access-in-features:
          list-mode: lax
          files:
            - "**/internal/item/**"
            - "**/internal/order/**"
          deny:
            - pkg: database/sql$
              desc: "R1: features use the sqlc db.Querier; SQL lives in db/queries/"
            - pkg: github.com/jackc/pgx/v5/pgxpool
              desc: "R1: features use the sqlc db.Querier; SQL lives in db/queries/"
            - pkg: github.com/jackc/pgx/v5/stdlib
              desc: "R1: features use the sqlc db.Querier; SQL lives in db/queries/"
            - pkg: github.com/lib/pq
              desc: "R1: features use the sqlc db.Querier; SQL lives in db/queries/"
            - pkg: github.com/jmoiron/sqlx
              desc: "R1: features use the sqlc db.Querier; SQL lives in db/queries/"
            - pkg: gorm.io/gorm
              desc: "R1: features use the sqlc db.Querier; SQL lives in db/queries/"
        # R2 — Services are transport-free
        r2-transport-free-services:
          list-mode: lax
          files:
            - "**/internal/*/service.go"
          deny:
            - pkg: net/http$
              desc: "R2: business rules must not depend on the request; the handler parses it"
            - pkg: github.com/a-h/templ
              desc: "R2: services return data; views render it"
            - pkg: example.com/app/internal/web
              desc: "R2: services must not depend on the web layer"
        # R3 — Shared packages never import features
        r3-shared-never-imports-features:
          list-mode: lax
          files:
            - "**/internal/auth/**"
            - "**/internal/config/**"
            - "**/internal/i18n/**"
            - "**/internal/web/layout/**"
          deny:
            - pkg: example.com/app/internal/item
              desc: "R3: only internal/web/routes.go wires features together"
            - pkg: example.com/app/internal/order
              desc: "R3: only internal/web/routes.go wires features together"
    forbidigo:
      analyze-types: true
      forbid:
        # R4 — Only internal/config reads the environment
        - pattern: ^os\.(Getenv|LookupEnv|Environ)$
          msg: "R4: read configuration through internal/config"
  exclusions:
    rules:
      - path: (^|/)(internal/config|cmd)/
        linters: [forbidigo]
      - path: _test\.go$
        linters: [forbidigo]

internal/db is not in R3: it is generated, and generated: lax already excludes it.

Opt-in rules, only when confirmed:

• R5 — one depguard rule per feature: files: ["**/internal/<feature>/**"], deny every other feature package. Regenerate the list when a feature package is added
• R6 — files: ["**/domain/**"], list-mode: strict, allow: [$gostd, <module>/<path>/domain]; and files: ["**/application/**"], deny the infrastructure / adapters packages

Custom rules follow the same shape: one named depguard rule, a desc starting with the rule ID.

Step 4: Install the Pre-commit Hook

The hook block, delimited so a re-run replaces only these lines:

# >>> nexa arch-unit >>>
# Installed by /setup-arch-unit. Runs the architecture rules before each commit.
golangci-lint run --enable-only depguard,forbidigo ./...
# <<< nexa arch-unit <<<

By hook manager (Step 1.4):

• lefthook — add a pre-commit.commands.nexa-arch-unit entry with run: set to the command
• pre-commit framework — add a repo: local hook, id: nexa-arch-unit, language: system, pass_filenames: false, entry: set to the command
• core.hooksPath or .husky/ already set — append the block to that directory's pre-commit (or replace the lines between existing markers)
• None — create .githooks/pre-commit with #!/bin/sh, set -e, and the block; chmod +x .githooks/pre-commit; run git config core.hooksPath .githooks. Worktrees share this repository setting, so /deliver-use-case worktrees run the hook too. A fresh clone must run the git config line once — Step 8 documents it

The hook runs on the whole module, not on staged files: an import rule is about the package graph, and a staged-file subset would miss a violation in an unchanged file.

Step 5: Run the Rules

golangci-lint run --enable-only depguard,forbidigo ./...

Outcomes:

1. Exit 0 — go to Step 6
2. A violation — show it and ask whether to:
   • Fix the code (out of scope here — recommend /implement for a technical task)
   • Defer the rule: create a TT-XXX technical task for the fix and add a linters.exclusions.rules entry for exactly the violating path, with a # TODO(TT-XXX) comment. Never exclude a whole package
   • Reconsider the rule

Do not continue until the command exits 0.

Step 6: Prove Every Rule Can Fail (mandatory)

A depguard rule whose files globs match nothing, or whose pkg is misspelled, passes forever. For each enabled rule:

1. Confirm its files globs match at least one file: git ls-files '<glob without **/ prefix>'
2. Write a throwaway probe file in a matched package that breaks the rule and does not create an import cycle — e.g. R1: internal/item/zz_archprobe.go with import _ "database/sql"; R4: a function calling os.Getenv("X")
3. Run the Step 5 command and confirm it reports the probe with the rule's desc
4. Delete the probe file

If a probe is not reported, fix the glob or the package path and repeat. Confirm with git status --porcelain that no probe file is left.

Step 7: Run the Hook

Run the installed hook directly (.githooks/pre-commit, lefthook run pre-commit, or pre-commit run nexa-arch-unit --all-files) and confirm it exits 0.

Step 8: Update CLAUDE.md

Append to the project's CLAUDE.md (create it if missing). If <!-- NEXA_ARCH_UNIT_CONFIGURED --> already exists, ask whether to overwrite or skip.

## Architecture Rules

<!-- NEXA_ARCH_UNIT_CONFIGURED -->

- Tooling: golangci-lint `depguard` (imports) and `forbidigo` (calls), configured in `.golangci.yml`
- Run: `golangci-lint run --enable-only depguard,forbidigo ./...` — also part of every `golangci-lint run` (`/code-quality`, CI)
- Pre-commit: [hook location]; [fresh clone: `git config core.hooksPath .githooks`]
- Active rules: [rule IDs with one-line descriptions]

### Conventions
- A new feature package under `internal/` must be added to R1 and R3 (and R5 if enabled) — a package missing from `files` is unchecked
- Wire features together only in `internal/web/routes.go`
- A deferred violation is an exclusion for one path with `# TODO(TT-XXX)`, never a `//nolint`

Do not remove or modify any other content in CLAUDE.md.

Verification

• golangci-lint run --enable-only depguard,forbidigo ./... exits 0
• Every enabled rule reported its probe in Step 6, and no probe file remains
• The pre-commit hook runs and exits 0
• golangci-lint run ./... still exits 0 (the full lint, as /code-quality runs it)

Then summarize:

## Architecture Rules Configured

### Rules
| ID | Rule | Status |
|----|------|--------|
| R1 | No database access outside sqlc in feature code | enabled, probe reported |
| ...                                                            |

### Files Created/Updated
| File                    | Change                                  |
|-------------------------|-----------------------------------------|
| .golangci.yml           | depguard + forbidigo rules              |
| [hook file]             | nexa arch-unit block                    |
| CLAUDE.md               | ## Architecture Rules section           |

### Deferred
- [rule, path, TT-XXX] or none

### Next Steps
- When a feature package is added, add it to the rule globs (the /implement run lints it)
- To bypass the hook once (not recommended): git commit --no-verify