# Architecture fitness functions: maintainability without reading the code

URL: https://developertoolkit.ai/en/workflows/test/fitness-functions/
Description: Gate layering, cycles, complexity, duplication and API surface in CI with ratchets, so agent-written code stays maintainable without line-by-line review.

Architecture fitness functions are automated checks that fail the build when code breaks a structural rule: a forbidden layer import, a dependency cycle, a function over its complexity budget, new duplication, or an unapproved public API change. Run as required CI gates with ratchets, they keep agent-written code maintainable without anyone reading every diff.

If you lead a team that merges 40 agent pull requests a week, this page is for you and your developers, with a trend view for the CTO. Each of those pull requests passes its tests, and each diff looks reasonable in isolation. Six months later the domain package imports the ORM, the checkout service and the billing service import each other, and there are three slightly different `formatMoney` helpers. No single pull request did it, so no single review could have caught it. Tests check behaviour; nothing checked the shape. This page turns the shape into checks.

## What you'll walk away with from architecture fitness functions

- The five fitness-function families worth gating on, with the enforcing tool for TypeScript, Python and Java.
- Configurations for all three stacks, tested on 26 September 2026: dependency-cruiser 18.4.0, import-linter 2.15, ArchUnit 1.5.1, ESLint 10, Ruff 0.16.9, Checkstyle, jscpd 5.3.2, API Extractor 7.59.2, Griffe 2.3.0 and japicmp 0.26.2.
- The ratchet pattern for adopting it on a brownfield codebase.
- A GitHub Actions job, a canary that proves the gate can still fail, and a `Stop` hook that makes the agent fix violations before it reports done.
- Three copy-paste prompts: derive the rules, fix a violation without touching them, and propose the next ratchet.

## Why does agent-written code erode when nobody reads every diff?

An agent optimises for the task in front of it. The shortest path often crosses a boundary (import the repository straight into the handler) or copies a helper instead of finding it. Each shortcut is locally reasonable, and review by sampling misses most of them.

The research agrees that this is a structural effect, not a matter of prompting harder:

- **SlopCodeBench** (Orlanski et al., arXiv, v2 7 May 2026) had agents repeatedly extend their own solutions across 196 checkpoints. The best passed 14.8% of them, and the benchmark names the degradation "structural erosion (concentrated complexity) and verbosity (redundant code)".
- **DORA** (Google Cloud, 2025 report, 23 September 2025) found AI adoption positively related to throughput and negatively related to stability, and names the mechanism: "Teams working in loosely coupled architectures with fast feedback loops see gains, while those constrained by tightly coupled systems and slow processes see little or no benefit."
- **GitClear** ("The Maintainability Gap: AI Code Quality in 2026", June 2026, 623 million code changes, reported here from a secondary search extract) measured block duplication up 81% against 2023 and moved (refactored) code falling from 13% to 3.8% of changed lines. GitClear presents the data as correlation, not proof of cause.

Fitness functions are the deterministic answer. The term is from Neal Ford, Rebecca Parsons and Patrick Kua's *Building Evolutionary Architectures* (O'Reilly): any objective, automated check of an architectural characteristic.

## Which fitness functions should you gate on?

Start with these five families: cheap, actionable for an agent, and blind spots for tests.

| Family | Catches | TypeScript | Python | Java |
| --- | --- | --- | --- | --- |
| Dependency direction and layering | Domain importing infrastructure, handlers bypassing services | dependency-cruiser | import-linter (`layers`, `forbidden`) | ArchUnit `layeredArchitecture()` |
| Cycles | Two modules that can no longer change independently | dependency-cruiser `circular` | import-linter `layers` or `independence` | ArchUnit `slices().beFreeOfCycles()` |
| Complexity budget | Functions that grow a branch per feature | ESLint `complexity`, `max-depth`, `max-params` | Ruff `C901`, `PLR0912`, `PLR0913` | Checkstyle `CyclomaticComplexity`, `ParameterNumber` |
| Duplication budget | Copied helpers, pasted validation | jscpd | jscpd | jscpd |
| Public API surface | Unapproved breaking changes to exports | API Extractor | Griffe `check` | japicmp |

For HTTP APIs, add a contract diff on the OpenAPI document: `oasdiff breaking --fail-on ERR base.yaml head.yaml` exits with code 1 when it finds error-level breaking changes, in any stack.

Coverage and mutation score are missing on purpose: they measure the tests, not the architecture; see [how strong your oracle is](/en/workflows/test/oracle-strength/). Security scanning has its own page, [security testing](/en/workflows/test/security-testing/).

## Why ratchets beat thresholds on an existing codebase

On a codebase that already has 212 violations, a threshold ("zero layering violations") is either red forever or so loose it catches nothing. A **ratchet** records the violations that exist today in a baseline, fails only on new ones, and lets the baseline shrink but never grow.

Every tool on this page has a ratchet built in:

| Tool | Baseline mechanism |
| --- | --- |
| dependency-cruiser | `--baseline` writes `.dependency-cruiser-known-violations.json`; `--ignore-known` skips those and fails on new ones. To tighten, re-run with `--baseline --baseline-mode shrink-only`, which only removes fixed entries |
| import-linter | `ignore_imports` lists known violations per contract |
| ArchUnit | `FreezingArchRule.freeze(rule)` stores current violations and fails only on new ones |
| jscpd | `--baseline-from-ref origin/main --fail-on-new-clones` compares against the base branch, with no file to edit |
| ESLint, Ruff, Checkstyle | Start the budget at your current worst function, then lower it on a schedule |

The ratchet gives the agent a task it can meet on every pull request: "do not add a violation". Fixing the 212 is separate, planned work.

## Set up fitness functions, step by step

1. **Write the architecture down in five sentences.** Name the layers, the allowed direction between them, and the two or three rules you would reject a pull request for. If you keep decisions as ADRs, this is the machine-checkable part of them; see [architecture decisions agents can follow](/en/workflows/plan/architecture-decisions/).

2. **Have the agent draft the rules from the code as it is.** Use the first prompt below. It maps the real import graph, proposes rules matching your five sentences and counts today's violations per rule. You review the rule set, not the code.

3. **Run the rules and record the baseline.** Commit the configuration and the baseline file in one pull request, and write the baseline size in its description. That number is where the ratchet starts.

4. **Add the canary, then make the job a required check.** The canary (below) plants a known violation and fails if the gate does not catch it. Require the fitness job in the branch ruleset, so a red result blocks merge for humans and agents alike.

5. **Take the rules away from the agent.** Put the rule configuration, baselines, `package.json` (it holds the `fitness` script), the canary, the workflow and the hook files in `.claude/` and `.codex/` under `CODEOWNERS` owned by the tech lead or the platform team, and turn on "Require review from Code Owners" in the same ruleset: on `pull_request` the job runs the pull request's own copy of the workflow, the canary and the rules, so only that review stops a pull request from rewriting its own gate. Deny the agent edits to the same paths in its session (see the tool tabs below), except `package.json`: it stays under `CODEOWNERS` only, because the agent needs it for dependency changes and the hook and CI call the tools directly rather than through its scripts. For Python and Java the equivalents are `pyproject.toml`, `config/fitness-checkstyle.xml`, `ArchitectureTest.java` and `src/test/resources/archunit_store/**`. A rule the agent can loosen, or a hook it can switch off, is a suggestion.

6. **Feed violations back before CI does.** Wire the fast checks into the agent's own loop, so it fixes a layering break in the same session instead of in a second round trip through CI.

7. **Tighten the ratchet on a schedule.** Once a month, lower each budget to the current worst value and delete stale baseline entries; for dependency-cruiser, `--baseline --baseline-mode shrink-only` removes fixed entries and never adds new ones. The third prompt below drafts the change as a patch, so a scheduled Codex automation or Cursor Automation can run it under the locked rules; the tech lead applies it.

## Fitness function configs for TypeScript, Python and Java

Each tab holds a tested set for one stack. The layer names match a common four-layer layout (`web` or `api`, `app`/`application` or `services`, `domain`, `infra`/`infrastructure` or `adapters`); rename them to yours.

**TypeScript**

    **Dependency rules** with dependency-cruiser 18.4.0. Install it with the other TypeScript tools on this tab, including the TypeScript pin the caution below explains:

    ```bash
    npm i -D dependency-cruiser eslint typescript-eslint jscpd @microsoft/api-extractor typescript@~6.0
    ```

    ```js
    // .dependency-cruiser.cjs
    /** @type {import('dependency-cruiser').IConfiguration} */
    module.exports = {
      forbidden: [
        {
          name: 'no-circular',
          severity: 'error',
          comment: 'Cycles make every module in the loop depend on every other one.',
          from: {},
          to: { circular: true },
        },
        {
          name: 'domain-stays-pure',
          severity: 'error',
          comment: 'src/domain holds business rules; it must not import app, infra or web code.',
          from: { path: '^src/domain/' },
          to: { path: '^src/(app|infra|web)/' },
        },
        {
          name: 'web-goes-through-app',
          severity: 'error',
          comment: 'Route handlers call use cases in src/app, never the database layer directly.',
          from: { path: '^src/web/' },
          to: { path: '^src/infra/' },
        },
      ],
      options: {
        doNotFollow: { path: 'node_modules' },
        tsConfig: { fileName: 'tsconfig.json' },
      },
    };
    ```

    The `comment` is what the agent reads when the rule fails, so write it as an instruction. Record the baseline once, then gate on new violations only. `npx --no-install` runs only the locally installed dev dependency; without it, a missing package is fetched from the registry by name, which is how a squatted name such as the unscoped `api-extractor` would end up running in CI:

    ```bash
    # Terminal, once: record today's violations
    npx --no-install depcruise src --config .dependency-cruiser.cjs --baseline

    # CI and the agent's loop: fail on anything not in the baseline
    npx --no-install depcruise src --config .dependency-cruiser.cjs --ignore-known --output-type err-long
    ```

    **TypeScript 7 makes dependency-cruiser silently blind**

    `typescript` on npm is 7.0.2 on 26 September 2026, and dependency-cruiser 18.4.0 supports only versions below 7.0.0. With TypeScript 7 installed it warned `missing-typescript-transpiler`, cruised 0 modules and exited 0 in our test: a green gate that checked nothing. Pin `typescript@~6.0` for the analysis and keep the canary below in CI. Use a tilde, not a caret: typescript-eslint 8.70.1 accepts `typescript` only below 6.1.0.

    **Complexity budget** with ESLint 10 core rules and the `typescript-eslint` parser:

    ```js
    // eslint.config.js
    import { defineConfig } from 'eslint/config';
    import tseslint from 'typescript-eslint';

    export default defineConfig({
      files: ['src/**/*.ts'],
      languageOptions: { parser: tseslint.parser },
      rules: {
        complexity: ['error', { max: 10 }],
        'max-depth': ['error', 3],
        'max-lines-per-function': ['error', { max: 60, skipBlankLines: true, skipComments: true }],
        'max-params': ['error', 4],
      },
    });
    ```

    **Duplication** with jscpd 5.3.2, gated on new clones against the base branch:

    ```bash
    npx --no-install jscpd src --baseline-from-ref origin/main --fail-on-new-clones --fail-on-empty
    ```

    **API surface** with API Extractor 7.59.2 for a package others import. Run `npx --no-install api-extractor init` once, build the declarations, and commit the generated `etc/*.api.md` report. Without `--local`, `api-extractor run` fails when the public API no longer matches the committed report; `--print-api-report-diff` prints what changed:

    ```bash
    npx --no-install tsc -p tsconfig.build.json && npx --no-install api-extractor run --print-api-report-diff
    ```

    A developer who intends the change runs `npx --no-install api-extractor run --local`, which rewrites the report, and the report diff goes to the API owner for approval.

    **One command for the agent and CI.** Collect the fast checks under one script, so the agent instruction below can say `npm run fitness`; the Stop hook and CI call the tools directly, for the reason given there:

    ```json
    {
      "scripts": {
        "fitness": "npm run fitness:deps && npm run fitness:complexity && npm run fitness:dupes",
        "fitness:deps": "depcruise src --config .dependency-cruiser.cjs --ignore-known --output-type err-long",
        "fitness:complexity": "eslint src --no-inline-config",
        "fitness:dupes": "jscpd src --baseline-from-ref origin/main --fail-on-new-clones --fail-on-empty"
      }
    }
    ```

    `--no-inline-config` stops `eslint-disable` comments from switching a budget off. `--baseline-from-ref origin/main` needs the base branch present locally, so fetch it (`git fetch origin main`) before the agent starts. For Python and Java, a `Makefile` target or a Maven profile plays the same role.

**Python**

    **Dependency rules** with import-linter 2.15 (`pip install import-linter`), in `pyproject.toml`:

    ```toml
    [tool.importlinter]
    root_package = "shop"
    include_external_packages = true

    [[tool.importlinter.contracts]]
    name = "Layered architecture"
    type = "layers"
    layers = [
        "shop.api",
        "shop.services",
        "shop.domain",
    ]

    [[tool.importlinter.contracts]]
    name = "Domain does not touch infrastructure"
    type = "forbidden"
    source_modules = ["shop.domain"]
    forbidden_modules = ["shop.adapters", "sqlalchemy", "httpx"]
    # Known violations, each with an owner and a ticket. This list only shrinks.
    ignore_imports = [
        "shop.domain.order -> shop.adapters.db",  # PAY-812
    ]

    [[tool.importlinter.contracts]]
    name = "API goes through services"
    type = "forbidden"
    source_modules = ["shop.api"]
    forbidden_modules = ["shop.adapters"]
    ```

    A `layers` contract fails on any upward import, which also rules out cycles between layers. Without `include_external_packages = true`, a third-party forbidden module makes `lint-imports` exit with an error before checking anything. Run it with the source directory on the path:

    ```bash
    PYTHONPATH=src lint-imports
    ```

    **Complexity budget** with Ruff 0.16.9, in the same `pyproject.toml`:

    ```toml
    [tool.ruff.lint]
    extend-select = ["C901", "PLR0912", "PLR0913", "PLR0915"]

    [tool.ruff.lint.mccabe]
    max-complexity = 10

    [tool.ruff.lint.pylint]
    max-args = 5
    max-branches = 12
    max-statements = 50
    ```

    **Duplication** with jscpd, which is also on PyPI (`pip install jscpd`) as the same self-contained binary:

    ```bash
    jscpd src --baseline-from-ref origin/main --fail-on-new-clones --fail-on-empty
    ```

    **API surface** with Griffe 2.3.0, which compares the package against a Git reference and reports breaking changes:

    ```bash
    griffe check shop --search src --against origin/main --format github
    ```

**Java**

    **Dependency rules** with ArchUnit 1.5.1, as a test (`com.tngtech.archunit:archunit-junit5:1.5.1`, test scope):

    ```java
    // src/test/java/com/acme/shop/ArchitectureTest.java
    package com.acme.shop;

    import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;
    import static com.tngtech.archunit.library.Architectures.layeredArchitecture;
    import static com.tngtech.archunit.library.dependencies.SlicesRuleDefinition.slices;

    import com.tngtech.archunit.core.importer.ImportOption;
    import com.tngtech.archunit.junit.AnalyzeClasses;
    import com.tngtech.archunit.junit.ArchTest;
    import com.tngtech.archunit.lang.ArchRule;
    import com.tngtech.archunit.library.freeze.FreezingArchRule;

    @AnalyzeClasses(packages = "com.acme.shop", importOptions = ImportOption.DoNotIncludeTests.class)
    class ArchitectureTest {

      @ArchTest
      static final ArchRule layers = FreezingArchRule.freeze(
          layeredArchitecture()
              .consideringOnlyDependenciesInLayers()
              .layer("Web").definedBy("..web..")
              .layer("Application").definedBy("..application..")
              .layer("Domain").definedBy("..domain..")
              .layer("Infrastructure").definedBy("..infrastructure..")
              .whereLayer("Web").mayNotBeAccessedByAnyLayer()
              .whereLayer("Application").mayOnlyBeAccessedByLayers("Web")
              .whereLayer("Infrastructure").mayOnlyBeAccessedByLayers("Application"));

      @ArchTest
      static final ArchRule domainIsPure = FreezingArchRule.freeze(
          noClasses().that().resideInAPackage("..domain..")
              .should().dependOnClassesThat()
              .resideInAnyPackage("..infrastructure..", "org.springframework..", "jakarta.persistence.."));

      @ArchTest
      static final ArchRule noCycles = slices().matching("com.acme.shop.(*)..").should().beFreeOfCycles();
    }
    ```

    Freeze every rule that fails on legacy code, including `layers`: it already flags existing domain-to-infrastructure imports, so unfrozen it turns a brownfield build red on day one. Freeze `noCycles` too if the codebase has cycles today. Allow the store's creation once, locally, and commit the store directory:

    ```properties
    # src/test/resources/archunit.properties
    freeze.store.default.path=src/test/resources/archunit_store
    freeze.store.default.allowStoreCreation=true
    ```

    After the first run, remove `allowStoreCreation` so CI fails instead of silently creating an empty store.

    **Check that Maven actually runs the architecture tests**

    In our test on 26 September 2026, `maven-surefire-plugin` 3.5.3 reported `Tests run: 0` for this class and a green `BUILD SUCCESS`, although the layering rule was violated. Surefire 3.6.0 ran all three rules and failed the build. Pin surefire 3.6.0 or later, and add a JUnit 5 dependency only in the platform version ArchUnit expects (1.5.1 depends on `junit-platform-engine` 1.14.4). The canary below catches a regression.

    **Complexity budget** with Checkstyle through `maven-checkstyle-plugin` 3.6.0 (`check` goal, bound to `verify`):

    ```xml
    <!-- config/fitness-checkstyle.xml -->
    <module name="Checker">
      <property name="severity" value="error"/>
      <module name="TreeWalker">
        <module name="CyclomaticComplexity"><property name="max" value="10"/></module>
        <module name="NestedIfDepth"><property name="max" value="2"/></module>
        <module name="MethodLength"><property name="max" value="60"/></module>
        <module name="ParameterNumber"><property name="max" value="5"/></module>
      </module>
    </module>
    ```

    **Duplication** with the jscpd command from the TypeScript tab.

    **API surface** for a library with `japicmp-maven-plugin` 0.26.2 (`cmp` goal): point `oldVersion` at the last released artifact and set `breakBuildOnBinaryIncompatibleModifications` and `breakBuildOnSourceIncompatibleModifications` to `true`.

## Run the fitness gates in CI

The gates are plain commands, so CI needs no agent or API key. This job runs the TypeScript set; for Python and Java, swap in the commands from their tabs.

```yaml
# .github/workflows/fitness.yml
name: fitness
on: pull_request

permissions:
  contents: read

jobs:
  fitness:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0 # jscpd builds its baseline from origin/main
          persist-credentials: false
      - uses: actions/setup-node@v7
        with:
          node-version: 22
      - run: npm ci
      - run: ./scripts/fitness-canary.sh
      - run: npx --no-install depcruise src --config .dependency-cruiser.cjs --ignore-known --output-type err-long
      - run: npx --no-install eslint src --no-inline-config
      - run: npx --no-install jscpd src --baseline-from-ref origin/main --fail-on-new-clones --fail-on-empty
      # API surface: only for packages others import. In a monorepo, run it per
      # published package the pull request touched.
      - run: npx --no-install tsc -p tsconfig.build.json && npx --no-install api-extractor run --print-api-report-diff
```

The first four checks take seconds. The API report step is the one check the agent's hook leaves to CI; drop it for an application that nobody imports.

## How do you feed violations back to the agent before CI?

CI is the boundary; the agent's own loop is the fast path. The instruction is identical in all three tools, so put it in `CLAUDE.md` or `AGENTS.md`:

```markdown
## Architecture fitness functions
- Before you report a task done, run `npm run fitness`. It must pass.
- A failure message is an instruction. Move the code to the right layer, reuse the
  existing helper jscpd points to, or split the function. Do not edit
  `.dependency-cruiser.cjs`, `eslint.config.js`, `.dependency-cruiser-known-violations.json`,
  `.jscpd.json`, the `fitness` scripts in `package.json` or `scripts/fitness-canary.sh`,
  and do not add `eslint-disable` comments.
- If a rule blocks a change you believe is right, stop and write the case to
  `ARCH_DISPUTE.md` for the tech lead.
```

The tools differ in enforcement: whether the check runs even when the agent forgets.

**Claude Code**

    A `Stop` hook runs the gates every time Claude tries to finish. Exit code `2` "prevents Claude from stopping, continues the conversation", and Claude reads the stderr as the reason. Checked against Claude Code 2.1.283 and its hooks documentation on 26 September 2026.

    In `.claude/settings.json`, the committed project settings, where a leading `/` resolves to the project root:

    ```json
    {
      "permissions": {
        "deny": [
          "Edit(/.dependency-cruiser.cjs)",
          "Edit(/.dependency-cruiser-known-violations.json)",
          "Edit(/eslint.config.js)",
          "Edit(/.jscpd.json)",
          "Edit(/scripts/fitness-canary.sh)",
          "Edit(/.github/**)",
          "Edit(/.claude/**)",
          "Edit(/.codex/**)"
        ]
      },
      "hooks": {
        "Stop": [
          {
            "hooks": [
              { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/fitness-on-stop.sh" }
            ]
          }
        ]
      }
    }
    ```

    ```bash
    #!/usr/bin/env bash
    # .claude/hooks/fitness-on-stop.sh: no "done" while a fitness function is red
    input=$(cat)
    # Already continuing because of this hook: block once, then hand over.
    if [ "$(printf '%s' "$input" | jq -r '.stop_hook_active // false' 2>/dev/null)" = "true" ]; then
      echo 'Fitness functions still failing after one retry; leaving it to a human and CI.' >&2
      exit 0
    fi
    cd "${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel)}" || exit 0
    # The same three commands as the CI job, not `npm run fitness`: a script in
    # package.json is something the agent could rewrite to a no-op.
    if ! out=$( { npx --no-install depcruise src --config .dependency-cruiser.cjs --ignore-known --output-type err-long \
        && npx --no-install eslint src --no-inline-config \
        && npx --no-install jscpd src --baseline-from-ref origin/main --fail-on-new-clones --fail-on-empty; } 2>&1); then
      printf 'Fitness functions failed. Fix the code, not the rules or baselines:\n%s\n' "$out" \
        | tail -n 60 >&2
      exit 2
    fi
    exit 0
    ```

    Make it executable; it needs `jq`. It runs only the fast checks and calls the tools directly, so editing `package.json` cannot switch it off, and the `.claude/**` and `.codex/**` deny rules protect the hook itself. It blocks only once: when `stop_hook_active` shows the agent is already continuing because of this hook, it lets the turn end, and CI still blocks the merge. Claude Code also overrides a block after eight consecutive stop-hook continuations (`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` changes the cap). Deny rules do not stop a script that writes files itself, so enable the sandbox from [protecting the oracle](/en/workflows/test/protect-the-oracle/) if the agent has shell access.

**Codex**

    Codex reads the `AGENTS.md` instruction above. For enforcement, Codex CLI 0.157.1 has a `Stop` hook event among its 12 hook events, and its `.codex/hooks.json` uses the same JSON shape as Claude Code. Codex runs the command in the session's working directory, so resolve the repository root in the command; the script falls back to `git rev-parse --show-toplevel` when `CLAUDE_PROJECT_DIR` is unset:

    ```json
    {
      "hooks": {
        "Stop": [
          { "hooks": [{ "type": "command", "command": "\"$(git rev-parse --show-toplevel)/.claude/hooks/fitness-on-stop.sh\"", "timeout": 600 }] }
        ]
      }
    }
    ```

    Codex also passes `stop_hook_active`, and that check is what bounds the loop; do not count on a cap like Claude Code's. Project hooks do not run until you trust them with `/hooks`, and again after anyone changes `hooks.json`. The cross-tool setup, including fixtures that prove each hook blocks, is in [agent hooks](/en/developer-scorecard-guide/agent-hooks/).

    To stop the agent loosening the rules or the hook, add the configuration and baseline files, `.codex/hooks.json` and the hook script as exact `read` paths to the permission profile from [protecting the oracle](/en/workflows/test/protect-the-oracle/). Exact paths work there; read-only globs are rejected in 0.157.1.

**Cursor**

    Add the instruction as a project Rule so Agent applies it to every task. Cursor also has hooks, which "run before or after defined stages of the agent loop and can observe, block, or modify behavior" (cursor.com/docs/hooks, checked 28 August 2026). We could not re-check the event names on 26 September 2026, so take them from Cursor's hooks reference when you port the script. [Agent hooks](/en/developer-scorecard-guide/agent-hooks/) covers the adapter approach and how to keep a Cursor hook advisory until it is proven.

    Cloud Agents run in their own VMs, so a hook on your laptop does not travel with them: the required CI check is what binds them. [Bugbot](/en/cursor-ide/ship/bugbot/) can review rule-change pull requests, but it is a reviewer, not a gate.

## Copy-paste prompts for fitness functions

**Copy-paste prompt: derive fitness functions from the codebase**

```text
Map this repository's real import graph before proposing anything.
1. List the top-level modules under src/ and, for each pair, how many imports go
   each way. Flag every cycle.
2. Our intended architecture: web -> app -> domain; infra is only used by app;
   domain imports nothing from app, infra or web and no ORM or HTTP client.
3. Propose dependency-cruiser rules in .dependency-cruiser.cjs that encode exactly
   that, with a `comment` on each rule written as an instruction to a developer.
4. Run them and report violations per rule, with the five worst files.
5. Report the current worst cyclomatic complexity and the largest duplicated block,
   so we can set the complexity and duplication budgets at today's values.
Do not fix any violation and do not change application code. Output the config,
the violation counts and the commands to record the baseline.
```

**Copy-paste prompt: fix a fitness violation without touching the rules**

```text
`npm run fitness` fails on this branch. Make it pass by changing application code only.
Rules, baselines, eslint config, the canary script and CI workflows are off limits,
and so are eslint-disable comments and new entries in any ignore list.
For each violation: quote the rule's comment, name the smallest structural change
that satisfies it (move the code to the right layer, inject the dependency, reuse
the existing helper jscpd points to, extract a function), make it, and re-run the
check. If the only fix you can find is to change the rule, stop and write your
reasoning to ARCH_DISPUTE.md instead.
```

**Copy-paste prompt: propose this month's ratchet**

```text
Review our architecture ratchets and propose a change that only tightens them.
You may not edit rule, budget or baseline files; write everything to RATCHET.md.
- Copy .dependency-cruiser-known-violations.json to /tmp/ratchet.json (a scratch
  file) and run `npx --no-install depcruise src --config .dependency-cruiser.cjs
  --baseline /tmp/ratchet.json --baseline-mode shrink-only`, which only removes
  fixed entries. Diff the two files and list the stale entries that can be removed.
- Find the current worst values for complexity, max-depth, max-params and
  function length. Where a budget in eslint.config.js is looser than today's
  worst value, propose lowering it to that value.
- Include the proposed edits as a unified diff the tech lead can apply.
- List the three baseline violations that would be cheapest to fix, with a
  one-paragraph plan each. Do not fix them.
Never propose loosening a budget or adding a baseline entry. Report the baseline
size before and after the proposed change.
```

## How do you know the fitness functions actually work?

A gate that cannot fail is worse than no gate, because the green check buys trust it has not earned. Two of the tools on this page produced exactly that during our tests: dependency-cruiser under TypeScript 7 and ArchUnit under an older surefire. Prove the gate can still fail on every run:

```bash
#!/usr/bin/env bash
# scripts/fitness-canary.sh: proves the dependency gate can still fail
set -u
canary=src/domain/__fitness_canary__.ts
echo "import { db } from '../infra/db.js'; export const c = db;" > "$canary"
trap 'rm -f "$canary"' EXIT
out=$(npx --no-install depcruise src --config .dependency-cruiser.cjs --ignore-known --output-type err 2>&1)
# Require the rule name: a crash (bad config, missing tsconfig) also exits non-zero.
if ! printf '%s' "$out" | grep -q 'domain-stays-pure'; then
  echo "The known-bad import was not reported: the gate is blind or broken." >&2
  printf '%s\n' "$out" | tail -n 20 >&2
  exit 1
fi
echo "Canary caught: the dependency gate is live."
```

Point the canary's import at a module that really exists in your infrastructure layer: dependency-cruiser cannot resolve a missing file, so the rule never matches and the canary raises a false alarm.

We ran this canary on 26 September 2026. With TypeScript 6 it reported the gate live; with TypeScript 7 installed it failed the job as blind, which is exactly the alarm you want. Use the same idea per stack: a fixture module that imports across a forbidden boundary for import-linter, an ArchUnit test class that asserts `layers` fails against a fixture package, and `--fail-on-empty` for jscpd.

Sign-off by role:

| Who | Owns | Approves |
| --- | --- | --- |
| Tech lead | The rule set, the budgets and the canary | Every change to a rule, budget or baseline, through `CODEOWNERS` |
| API owner | The committed API report or the base for Griffe and japicmp | Every intentional API break |
| Developer or agent | Keeping the fitness job green | Nothing in the rules; disputes go to `ARCH_DISPUTE.md` |
| CTO | The trend | The monthly numbers below |

For the CTO, three numbers per repository are enough and come straight from the tools: the **baseline size** (dependency-cruiser's JSON output reports `summary.baselineSize`; import-linter's `ignore_imports` length; ArchUnit's store), which should only fall; the **number of rule or budget changes** merged per month, each with an approval; and **fitness failures caught per week** on agent pull requests. A falling baseline with steady catches means the architecture is holding while the agents do the typing; the per-PR results belong in the [evidence bundle](/en/workflows/ship/evidence-bundle/).

## What breaks when you gate on fitness functions?

**The gate goes green because it analysed nothing.** An unsupported TypeScript version, a wrong `root_package`, an old surefire or a bad path turns the check into a no-op that exits 0. Recovery: run the canary first in CI, add `--fail-on-empty` to jscpd, and read the "modules cruised" count in the log after every toolchain upgrade.

**The agent loosens the rule instead of fixing the code.** It adds a baseline entry, raises `max`, or sprinkles `eslint-disable`. Recovery: step 5, plus ESLint's `--no-inline-config` so a disable comment has no effect.

**The agent satisfies the rule with a worse design.** It splits a complex function into three private helpers that each take seven parameters, or moves infrastructure code into the domain folder so the import becomes "legal". Recovery: pair complexity with `max-params`, keep layer rules path-based and review the file moves in the [agent PR review](/en/workflows/ship/agent-pr-review/) triage, where moved files are a risk flag.

**The baseline becomes a second codebase nobody reads.** Hundreds of `ignore_imports` lines with no owner. Recovery: require a ticket reference on each entry, run the ratchet prompt monthly, and track the baseline size as a number.

**Duplication gates fire on generated code.** Protobuf stubs, ORM migrations and snapshot files are duplicated by design. Recovery: exclude generated paths with jscpd's `ignore` setting in `.jscpd.json`, not by raising the budget.

**The rules encode an architecture nobody agreed on.** The agent drafted them, nobody pushed back, and now they block good changes. Recovery: rules come from the five sentences in step 1 and an ADR the team reviewed. Change the ADR first, then the rule, in one pull request the team approves.

## Where to go next with fitness functions

On the tech-lead track, the next step is reviewing agent pull requests.

- [Reviewing an agent's pull request](/en/workflows/ship/agent-pr-review/) — The triage protocol that uses the fitness gates as evidence: the next step on the tech-lead track.
- [The evidence bundle](/en/workflows/ship/evidence-bundle/) — What an agent's pull request must prove, with the fitness results as one section.
- [Protecting the oracle](/en/workflows/test/protect-the-oracle/) — Deny rules, sandboxing and CODEOWNERS for tests, applied here to the rule files.
- [Architecture decisions agents can follow](/en/workflows/plan/architecture-decisions/) — Short ADRs whose machine-checkable half becomes the rules on this page.
- [Keeping an agent-written codebase healthy](/en/workflows/operate/codebase-health/) — Churn, complexity and revert trends over time, and the thresholds that lower a loop's autonomy.
- [Making a codebase agent-ready](/en/workflows/harness/agent-ready-codebase/) — The prerequisite: one-command checks, strict types and clear module boundaries to enforce.
