# Funkcje dopasowania architektury: utrzymywalność bez czytania kodu

URL: https://developertoolkit.ai/pl/workflows/test/fitness-functions/
Description: Warstwy, cykle, złożoność, duplikacja i publiczne API jako bramki CI z zapadką: kod pisany przez agentów zostaje utrzymywalny bez czytania każdej linii.

Funkcje dopasowania architektury (architecture fitness functions) to automatyczne kontrole, które przerywają build, gdy kod łamie regułę strukturalną: niedozwolony import między warstwami, cykl zależności, funkcję ponad budżetem złożoności, nową duplikację albo niezatwierdzoną zmianę publicznego API. Uruchamiane jako wymagane bramki CI z zapadką utrzymują kod pisany przez agentów w dobrym stanie bez czytania każdego diffa.

Jeśli prowadzisz zespół, który scala 40 pull requestów od agentów tygodniowo, ta strona jest dla ciebie i twoich deweloperów, a CTO znajdzie tu widok trendu. Każdy z tych pull requestów przechodzi testy, a każdy diff z osobna wygląda rozsądnie. Pół roku później pakiet domenowy importuje ORM, serwis zamówień i serwis rozliczeń importują się nawzajem, a w repozytorium żyją trzy nieco różne funkcje `formatMoney`. Nie zrobił tego żaden pojedynczy pull request, więc żadne pojedyncze review nie mogło tego wyłapać. Testy sprawdzają zachowanie, a kształtu kodu nie sprawdzało nic. Ta strona zamienia ten kształt w kontrole.

## Co zyskujesz dzięki funkcjom dopasowania architektury

- Pięć rodzin funkcji dopasowania, które warto zamienić w bramki, z narzędziem egzekwującym dla TypeScriptu, Pythona i Javy.
- Konfiguracje dla trzech stosów, przetestowane 26 września 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 i japicmp 0.26.2.
- Wzorzec zapadki (ratchet) do wdrożenia tego w istniejącym kodzie.
- Job GitHub Actions, kanarka, który dowodzi, że bramka wciąż potrafi zgłosić błąd, oraz hook `Stop`, który każe agentowi naprawić naruszenia, zanim zgłosi koniec pracy.
- Trzy prompty do skopiowania: wyprowadź reguły, napraw naruszenie bez ruszania ich i zaproponuj kolejną zapadkę.

## Dlaczego kod pisany przez agentów eroduje, gdy nikt nie czyta każdego diffa?

Agent optymalizuje pod zadanie, które ma przed sobą. Najkrótsza droga często przecina granicę (repozytorium importowane wprost do handlera) albo kopiuje funkcję pomocniczą, zamiast ją znaleźć. Każdy taki skrót jest lokalnie rozsądny, a review wyrywkowe przeoczy większość z nich.

Badania potwierdzają, że to efekt strukturalny, a nie kwestia lepszego promptowania:

- **SlopCodeBench** (Orlanski i in., arXiv, wersja 2 z 7 maja 2026) kazał agentom wielokrotnie rozbudowywać własne rozwiązania w 196 punktach kontrolnych. Najlepszy zaliczył 14,8% z nich, a benchmark nazywa degradację „structural erosion (concentrated complexity) and verbosity (redundant code)”.
- **DORA** (Google Cloud, raport 2025, 23 września 2025) wykazał dodatni związek adopcji AI z przepustowością i ujemny ze stabilnością, i wskazał mechanizm: „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”, czerwiec 2026, 623 mln zmian w kodzie; przytaczamy za wtórnym wyciągiem z wyszukiwarki) zmierzył wzrost duplikacji bloków o 81% względem 2023 i spadek udziału przenoszonego (refaktoryzowanego) kodu z 13% do 3,8% zmienionych linii. GitClear przedstawia te dane jako korelację, nie dowód przyczynowości.

Funkcje dopasowania to deterministyczna odpowiedź. Termin pochodzi z książki *Building Evolutionary Architectures* Neala Forda, Rebekki Parsons i Patricka Kua (O'Reilly): każda obiektywna, automatyczna kontrola jakiejś cechy architektury.

## Które funkcje dopasowania zamienić w bramki?

Zacznij od pięciu rodzin z tabeli. Są tanie w uruchomieniu, kończą się komunikatem, na podstawie którego agent może działać, i każda łapie rodzaj erozji, którego testy nie widzą.

| Rodzina | Co łapie | TypeScript | Python | Java |
| --- | --- | --- | --- | --- |
| Kierunek zależności i warstwy | Domena importuje infrastrukturę, handlery omijają serwisy | dependency-cruiser | import-linter (`layers`, `forbidden`) | ArchUnit `layeredArchitecture()` |
| Cykle | Dwa moduły, których nie da się już zmieniać niezależnie | dependency-cruiser `circular` | import-linter `layers` lub `independence` | ArchUnit `slices().beFreeOfCycles()` |
| Budżet złożoności | Funkcje, które z każdą funkcjonalnością dostają nową gałąź | ESLint `complexity`, `max-depth`, `max-params` | Ruff `C901`, `PLR0912`, `PLR0913` | Checkstyle `CyclomaticComplexity`, `ParameterNumber` |
| Budżet duplikacji | Skopiowane helpery, wklejona walidacja | jscpd | jscpd | jscpd |
| Powierzchnia publicznego API | Niezatwierdzone zmiany łamiące eksporty | API Extractor | Griffe `check` | japicmp |

Dla API HTTP dodaj porównanie kontraktu na dokumencie OpenAPI: `oasdiff breaking --fail-on ERR base.yaml head.yaml` kończy się kodem 1, gdy znajdzie zmiany łamiące na poziomie błędu, niezależnie od stosu.

Dwóch rodzin celowo tu brakuje. Pokrycie i wynik mutacyjny mierzą testy, nie architekturę: zobacz, [jak silna jest twoja wyrocznia](/pl/workflows/test/oracle-strength/). Skanowanie bezpieczeństwa to osobna bramka z własną stroną, [testy bezpieczeństwa](/pl/workflows/test/security-testing/).

## Dlaczego zapadka wygrywa z progiem w istniejącym kodzie

Próg mówi „najwyżej 3% duplikacji” albo „zero naruszeń warstw”. W kodzie, który już ma 212 naruszeń, próg jest albo wiecznie czerwony, albo tak luźny, że nic nie łapie. **Zapadka** zapisuje dzisiejsze naruszenia w pliku bazowym (baseline), przerywa build tylko przy nowych i pozwala bazie maleć, ale nigdy rosnąć.

Każde narzędzie z tej strony ma zapadkę wbudowaną:

| Narzędzie | Mechanizm bazy |
| --- | --- |
| dependency-cruiser | `--baseline` zapisuje `.dependency-cruiser-known-violations.json`; `--ignore-known` je pomija i przerywa build przy nowych. Żeby zacisnąć bazę, uruchom ponownie z `--baseline --baseline-mode shrink-only`, co tylko usuwa naprawione wpisy |
| import-linter | `ignore_imports` wylicza znane naruszenia w każdym kontrakcie |
| ArchUnit | `FreezingArchRule.freeze(rule)` zapisuje bieżące naruszenia i zgłasza tylko nowe |
| jscpd | `--baseline-from-ref origin/main --fail-on-new-clones` porównuje z gałęzią bazową, bez pliku do edycji |
| ESLint, Ruff, Checkstyle | Ustaw budżet na wartość twojej najgorszej funkcji i obniżaj go według harmonogramu |

Zapadka daje agentowi zadanie, które może spełnić w każdym pull requeście: „nie dodawaj naruszenia”. Naprawa tych 212 to osobno zaplanowana praca.

## Wdróż funkcje dopasowania krok po kroku

1. **Zapisz architekturę w pięciu zdaniach.** Nazwij warstwy, dozwolony kierunek między nimi i dwie, trzy reguły, za których złamanie odrzuciłbyś pull request. Jeśli prowadzisz ADR-y, to jest ich część sprawdzalna maszynowo; zobacz [decyzje architektoniczne, których agenci przestrzegają](/pl/workflows/plan/architecture-decisions/).

2. **Poproś agenta o szkic reguł na podstawie kodu w obecnym stanie.** Użyj pierwszego promptu poniżej. Agent odwzoruje prawdziwy graf importów, zaproponuje reguły zgodne z twoimi pięcioma zdaniami i poda, ile naruszeń każda reguła zgłosiłaby dziś. Przeglądasz zestaw reguł, nie kod.

3. **Uruchom reguły i zapisz bazę.** Dodaj konfigurację i plik bazowy do repozytorium w jednym pull requeście i wpisz rozmiar bazy do jego opisu. Od tej liczby startuje zapadka.

4. **Dodaj kanarka, a potem ustaw job jako wymagany.** Kanarek (poniżej) podkłada znane naruszenie i przerywa build, jeśli bramka go nie złapie. Wymagaj joba fitness w rulesecie gałęzi, żeby czerwony wynik blokował merge ludziom i agentom tak samo.

5. **Odbierz agentowi reguły.** Konfigurację reguł, bazy, `package.json` (w nim jest skrypt `fitness`), kanarka, workflow i pliki hooków w `.claude/` i `.codex/` oddaj pod `CODEOWNERS` tech leada albo zespołu platformowego i włącz w tym samym rulesecie „Require review from Code Owners”: przy `pull_request` job uruchamia kopię workflow, kanarka i reguł z pull requesta, więc tylko ta recenzja powstrzyma pull request przed przepisaniem własnej bramki. Zablokuj agentowi edycję tych samych ścieżek w sesji (zobacz zakładki narzędzi poniżej) z wyjątkiem `package.json`: ten plik zostaje tylko pod `CODEOWNERS`, bo agent potrzebuje go do zmian zależności, a hook i CI wywołują narzędzia bezpośrednio, nie przez jego skrypty. W Pythonie i Javie odpowiednikami są `pyproject.toml`, `config/fitness-checkstyle.xml`, `ArchitectureTest.java` i `src/test/resources/archunit_store/**`. Reguła, którą agent może poluzować, albo hook, który może wyłączyć, jest tylko sugestią.

6. **Zwracaj naruszenia agentowi, zanim zrobi to CI.** Podepnij szybkie kontrole do pętli samego agenta, żeby naprawił złamaną warstwę w tej samej sesji, a nie w kolejnej rundzie przez CI.

7. **Zaciskaj zapadkę według harmonogramu.** Raz w miesiącu obniż każdy budżet do bieżącej najgorszej wartości i usuń nieaktualne wpisy bazy; w dependency-cruiserze `--baseline --baseline-mode shrink-only` usuwa naprawione wpisy i nigdy nie dodaje nowych. Trzeci prompt poniżej przygotowuje tę zmianę jako łatkę, więc może go uruchamiać zaplanowana automatyzacja Codeksa albo Automation Cursora przy zablokowanych regułach; łatkę nakłada tech lead.

## Konfiguracje funkcji dopasowania dla TypeScriptu, Pythona i Javy

Każda zakładka zawiera kompletny, przetestowany zestaw dla jednego stosu: reguły zależności, budżet złożoności, duplikację i kontrolę publicznego API. Nazwy warstw odpowiadają typowemu układowi czterowarstwowemu (`web` lub `api`, `app`/`application` lub `services`, `domain`, `infra`/`infrastructure` lub `adapters`); zmień je na swoje.

**TypeScript**

    **Reguły zależności** w dependency-cruiser 18.4.0. Zainstaluj go razem z pozostałymi narzędziami TypeScriptu z tej zakładki, łącznie z przypięciem TypeScriptu, które wyjaśnia ostrzeżenie niżej:

    ```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' },
      },
    };
    ```

    Pole `comment` to tekst, który agent czyta, gdy reguła zawiedzie, więc pisz je jako polecenie. Zapisz bazę raz, a potem przerywaj build tylko przy nowych naruszeniach. `npx --no-install` uruchamia wyłącznie lokalnie zainstalowaną zależność deweloperską; bez tej flagi brakujący pakiet zostaje pobrany z rejestru po nazwie, i tak w CI mógłby się uruchomić zajęty przez kogoś innego pakiet, na przykład nieoznaczony zakresem `api-extractor`:

    ```bash
    # Terminal, jednorazowo: zapisz dzisiejsze naruszenia
    npx --no-install depcruise src --config .dependency-cruiser.cjs --baseline

    # CI i pętla agenta: błąd przy wszystkim, czego nie ma w bazie
    npx --no-install depcruise src --config .dependency-cruiser.cjs --ignore-known --output-type err-long
    ```

    **TypeScript 7 po cichu oślepia dependency-cruisera**

    Pakiet `typescript` na npm ma 26 września 2026 wersję 7.0.2, a dependency-cruiser 18.4.0 obsługuje tylko wersje poniżej 7.0.0. W naszym teście z zainstalowanym TypeScriptem 7 wypisał ostrzeżenie `missing-typescript-transpiler`, przeanalizował 0 modułów i zakończył się kodem 0: zielona bramka, która niczego nie sprawdziła. Przypnij `typescript@~6.0` do analizy i trzymaj w CI kanarka opisanego niżej. Użyj tyldy, nie daszka: typescript-eslint 8.70.1 przyjmuje `typescript` tylko poniżej 6.1.0.

    **Budżet złożoności** z regułami rdzenia ESLint 10 i parserem `typescript-eslint`:

    ```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],
      },
    });
    ```

    **Duplikacja** w jscpd 5.3.2, z bramką na nowe klony względem gałęzi bazowej:

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

    **Publiczne API** w API Extractor 7.59.2 dla pakietu importowanego przez innych. Uruchom raz `npx --no-install api-extractor init`, zbuduj deklaracje i dodaj wygenerowany raport `etc/*.api.md` do repozytorium. Bez `--local` polecenie `api-extractor run` kończy się błędem, gdy publiczne API nie zgadza się już z raportem w repozytorium; `--print-api-report-diff` wypisuje, co się zmieniło:

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

    Deweloper, który zmienia API celowo, uruchamia `npx --no-install api-extractor run --local`, co przepisuje raport, a diff raportu trafia do właściciela API do zatwierdzenia.

    **Jedno polecenie dla agenta i CI.** Zbierz szybkie kontrole w jeden skrypt, żeby instrukcja dla agenta poniżej mogła mówić `npm run fitness`; hook Stop i CI wywołują narzędzia bezpośrednio, z powodu opisanego przy hooku:

    ```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` sprawia, że komentarze `eslint-disable` nie wyłączą budżetu. `--baseline-from-ref origin/main` wymaga lokalnej kopii gałęzi bazowej, więc pobierz ją (`git fetch origin main`), zanim agent zacznie pracę. W Pythonie i Javie tę samą rolę pełni cel w `Makefile` albo profil Mavena.

**Python**

    **Reguły zależności** w import-linter 2.15 (`pip install import-linter`), w `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"]
    ```

    Kontrakt `layers` zgłasza każdy import w górę, co wyklucza też cykle między warstwami. Bez `include_external_packages = true` zakazany pakiet zewnętrzny sprawia, że `lint-imports` kończy się błędem, zanim cokolwiek sprawdzi. Uruchamiaj narzędzie z katalogiem źródeł na ścieżce:

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

    **Budżet złożoności** w Ruff 0.16.9, w tym samym `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
    ```

    **Duplikacja** w jscpd, dostępnym także na PyPI (`pip install jscpd`) jako ten sam samodzielny plik binarny:

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

    **Publiczne API** w Griffe 2.3.0, które porównuje pakiet z referencją Gita i zgłasza zmiany łamiące:

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

**Java**

    **Reguły zależności** w ArchUnit 1.5.1, jako test (`com.tngtech.archunit:archunit-junit5:1.5.1`, zakres test):

    ```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();
    }
    ```

    Zamroź każdą regułę, która pada na starym kodzie, także `layers`: zgłasza już istniejące importy z domeny do infrastruktury, więc niezamrożona od pierwszego dnia czerwieni build w istniejącym systemie. Jeśli kod ma dziś cykle, zamroź też `noCycles`. Pozwól utworzyć magazyn raz, lokalnie, i dodaj jego katalog do repozytorium:

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

    Po pierwszym uruchomieniu usuń `allowStoreCreation`, żeby CI zgłaszało błąd, zamiast po cichu tworzyć pusty magazyn.

    **Sprawdź, czy Maven naprawdę uruchamia testy architektury**

    W naszym teście 26 września 2026 `maven-surefire-plugin` 3.5.3 zgłosił dla tej klasy `Tests run: 0` i zielony `BUILD SUCCESS`, choć reguła warstw była złamana. Surefire 3.6.0 uruchomił wszystkie trzy reguły i przerwał build. Przypnij surefire 3.6.0 lub nowszy, a zależność JUnit 5 dodawaj tylko w wersji platformy, której oczekuje ArchUnit (1.5.1 zależy od `junit-platform-engine` 1.14.4). Kanarek opisany niżej wyłapie regresję.

    **Budżet złożoności** w Checkstyle przez `maven-checkstyle-plugin` 3.6.0 (cel `check`, podpięty pod `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>
    ```

    **Duplikacja** poleceniem jscpd z zakładki TypeScript.

    **Publiczne API** biblioteki w `japicmp-maven-plugin` 0.26.2 (cel `cmp`): wskaż w `oldVersion` ostatni wydany artefakt i ustaw `breakBuildOnBinaryIncompatibleModifications` oraz `breakBuildOnSourceIncompatibleModifications` na `true`.

## Uruchom bramki funkcji dopasowania w CI

Bramki to zwykłe polecenia, więc job w CI nie potrzebuje agenta ani klucza API. Ten job GitHub Actions uruchamia zestaw dla TypeScriptu; joby dla Pythona i Javy podmieniają polecenia na te z ich zakładek.

```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
```

Pierwsze cztery kontrole trwają sekundy. Krok z raportem API to jedyna kontrola, którą hook agenta zostawia dla CI; usuń go w aplikacji, której nikt nie importuje.

## Jak zwracać naruszenia agentowi przed CI?

CI jest granicą, a pętla agenta szybką ścieżką. Instrukcja jest taka sama we wszystkich trzech narzędziach, więc umieść ją w `CLAUDE.md` albo `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.
```

Narzędzia różnią się egzekwowaniem: tym, czy kontrola ruszy także wtedy, gdy agent zapomni o instrukcji.

**Claude Code**

    Hook `Stop` uruchamia bramki za każdym razem, gdy Claude próbuje zakończyć pracę. Kod wyjścia `2` „prevents Claude from stopping, continues the conversation”, a Claude czyta stderr jako powód. Sprawdzone z Claude Code 2.1.283 i dokumentacją hooków 26 września 2026.

    W `.claude/settings.json`, czyli we współdzielonych ustawieniach projektu w repozytorium, w których wiodący `/` oznacza katalog główny projektu:

    ```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
    ```

    Nadaj skryptowi prawo wykonywania; wymaga `jq`. Uruchamia tylko szybkie kontrole i wywołuje narzędzia bezpośrednio, więc edycja `package.json` go nie wyłączy, a reguły deny dla `.claude/**` i `.codex/**` chronią sam hook. Blokuje tylko raz: gdy `stop_hook_active` pokazuje, że agent już kontynuuje z powodu tego hooka, pozwala zakończyć turę, a merge i tak zablokuje CI. Claude Code ignoruje też blokadę po ośmiu kolejnych kontynuacjach wymuszonych przez hook stop (limit zmienia `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`). Reguły deny nie zatrzymają skryptu, który sam zapisuje pliki, więc jeśli agent ma dostęp do powłoki, włącz sandbox z [ochrony wyroczni](/pl/workflows/test/protect-the-oracle/).

**Codex**

    Codex czyta instrukcję z `AGENTS.md` powyżej. Do egzekwowania Codex CLI 0.157.1 ma zdarzenie hooka `Stop` wśród swoich 12 zdarzeń, a jego `.codex/hooks.json` ma ten sam kształt JSON co w Claude Code. Codex uruchamia polecenie w katalogu roboczym sesji, więc katalog główny repozytorium wyznacz w samym poleceniu; skrypt sam przełącza się na `git rev-parse --show-toplevel`, gdy `CLAUDE_PROJECT_DIR` nie jest ustawione:

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

    Codex również przekazuje `stop_hook_active` i to sprawdzenie ogranicza pętlę; nie licz na limit taki jak w Claude Code. Hooki projektu nie działają, dopóki nie zaufasz im przez `/hooks`, i to ponownie po każdej zmianie `hooks.json`. Konfigurację dla wszystkich narzędzi, z fiksturami dowodzącymi, że każdy hook blokuje, opisuje strona [hooki agentów](/pl/developer-scorecard-guide/agent-hooks/).

    Żeby agent nie luzował reguł ani hooka, dodaj pliki konfiguracji i bazy, `.codex/hooks.json` i skrypt hooka jako dokładne ścieżki `read` do profilu uprawnień z [ochrony wyroczni](/pl/workflows/test/protect-the-oracle/). Dokładne ścieżki tam działają; globy tylko do odczytu są w 0.157.1 odrzucane.

**Cursor**

    Dodaj instrukcję jako regułę projektu (Rule), żeby Agent stosował ją w każdym zadaniu. Cursor ma też hooki, które „run before or after defined stages of the agent loop and can observe, block, or modify behavior” (cursor.com/docs/hooks, sprawdzone 28 sierpnia 2026). Nazw zdarzeń nie mogliśmy ponownie sprawdzić 26 września 2026, więc weź je z dokumentacji hooków Cursora, gdy będziesz przenosić skrypt. Strona [hooki agentów](/pl/developer-scorecard-guide/agent-hooks/) opisuje podejście z adapterem i to, jak trzymać hook Cursora w trybie doradczym, dopóki nie udowodnisz, że działa.

    Cloud Agents działają we własnych maszynach wirtualnych, więc hook z twojego laptopa z nimi nie podróżuje: wiąże je wymagana kontrola w CI. [Bugbot](/pl/cursor-ide/ship/bugbot/) może przeglądać pull requesty zmieniające reguły, ale jest recenzentem, nie bramką.

## Prompty do skopiowania: funkcje dopasowania

**Prompt do skopiowania: wyprowadź funkcje dopasowania z kodu**

```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.
```

**Prompt do skopiowania: napraw naruszenie bez ruszania reguł**

```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.
```

**Prompt do skopiowania: zaproponuj zapadkę na ten miesiąc**

```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.
```

## Skąd wiesz, że funkcje dopasowania naprawdę działają?

Bramka, która nigdy nie zgłasza błędu, jest gorsza niż jej brak, bo zielony status daje zaufanie, na które nie zasłużyła. Dwa narzędzia z tej strony zrobiły dokładnie to w naszych testach: dependency-cruiser pod TypeScriptem 7 i ArchUnit pod starszym surefire. Udowadniaj przy każdym uruchomieniu, że bramka wciąż wykrywa naruszenia:

```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."
```

Import w kanarku skieruj na moduł, który naprawdę istnieje w twojej warstwie infrastruktury: dependency-cruiser nie rozwiąże brakującego pliku, więc reguła nigdy nie zadziała, a kanarek podniesie fałszywy alarm.

Uruchomiliśmy tego kanarka 26 września 2026. Z TypeScriptem 6 zgłosił, że bramka działa; z zainstalowanym TypeScriptem 7 przerwał job jako ślepą bramkę, czyli dokładnie tym alarmem, na którym ci zależy. W innych stosach zastosuj tę samą zasadę: moduł-fikstura importujący przez zakazaną granicę dla import-lintera, klasa testowa ArchUnit sprawdzająca, że `layers` zawodzi na pakiecie-fiksturze, oraz `--fail-on-empty` dla jscpd.

Odpowiedzialność za zatwierdzanie dzieli się według ról:

| Kto | Za co odpowiada | Co zatwierdza |
| --- | --- | --- |
| Tech lead | Zestaw reguł, budżety i kanarek | Każdą zmianę reguły, budżetu lub bazy, przez `CODEOWNERS` |
| Właściciel API | Raport API w repozytorium albo punkt odniesienia dla Griffe i japicmp | Każdą celową zmianę łamiącą API |
| Deweloper lub agent | Zielony job fitness | Nic w regułach; spory trafiają do `ARCH_DISPUTE.md` |
| CTO | Trend | Comiesięczne liczby opisane niżej |

CTO wystarczą trzy liczby na repozytorium, prosto z narzędzi: **rozmiar bazy** (JSON z dependency-cruisera podaje `summary.baselineSize`; w import-linterze to długość `ignore_imports`; w ArchUnit zawartość magazynu), który powinien tylko maleć; **liczba zmian reguł lub budżetów** scalonych w miesiącu, każda z zatwierdzeniem; oraz **liczba naruszeń złapanych tygodniowo** w pull requestach agentów. Malejąca baza przy stałej liczbie złapanych naruszeń oznacza, że architektura się trzyma, choć kod piszą agenci; wyniki dla pojedynczego PR-a należą do [pakietu dowodów](/pl/workflows/ship/evidence-bundle/).

## Co się psuje, gdy funkcje dopasowania są bramkami?

**Bramka jest zielona, bo niczego nie przeanalizowała.** Nieobsługiwana wersja TypeScriptu, zły `root_package`, stary surefire albo błędna ścieżka zamieniają kontrolę w pustą operację kończącą się kodem 0. Jak naprawić: uruchamiaj kanarka jako pierwszy krok CI, dodaj `--fail-on-empty` do jscpd i po każdej aktualizacji narzędzi sprawdzaj w logu liczbę przeanalizowanych modułów.

**Agent luzuje regułę zamiast naprawić kod.** Dopisuje wpis do bazy, podnosi `max` albo rozsiewa `eslint-disable`. Jak naprawić: krok 5 oraz `--no-inline-config` w ESLint, żeby komentarz wyłączający nie miał skutku.

**Agent spełnia regułę gorszym projektem.** Dzieli złożoną funkcję na trzy prywatne helpery, z których każdy przyjmuje siedem parametrów, albo przenosi kod infrastruktury do katalogu domeny, żeby import stał się „legalny”. Jak naprawić: łącz budżet złożoności z `max-params`, opieraj reguły warstw na ścieżkach i sprawdzaj przeniesienia plików w triażu [code review PR-a agenta](/pl/workflows/ship/agent-pr-review/), gdzie przeniesione pliki są flagą ryzyka.

**Baza zamienia się w drugi kod, którego nikt nie czyta.** Setki linii `ignore_imports` bez właściciela. Jak naprawić: wymagaj numeru zgłoszenia przy każdym wpisie, co miesiąc uruchamiaj prompt zapadki i śledź rozmiar bazy jako liczbę.

**Bramka duplikacji strzela w kod generowany.** Stuby protobuf, migracje ORM i pliki snapshotów są zduplikowane z założenia. Jak naprawić: wyklucz ścieżki generowane ustawieniem `ignore` w `.jscpd.json`, a nie podnoszeniem budżetu.

**Reguły kodują architekturę, na którą nikt się nie umówił.** Agent je naszkicował, nikt nie zaprotestował, a teraz blokują dobre zmiany. Jak naprawić: reguły wynikają z pięciu zdań z kroku 1 i z ADR-u, który zespół przejrzał. Najpierw zmień ADR, potem regułę, w jednym pull requeście zatwierdzonym przez zespół.

## Dokąd dalej po funkcjach dopasowania

Na ścieżce tech leada następnym krokiem jest code review pull requestów agentów.

- [Code review PR-a agenta](/pl/workflows/ship/agent-pr-review/) — Protokół triażu, który traktuje bramki funkcji dopasowania jako dowód: następny krok na ścieżce tech leada.
- [Pakiet dowodów](/pl/workflows/ship/evidence-bundle/) — Co musi udowodnić pull request agenta, z wynikami funkcji dopasowania jako jedną z sekcji.
- [Ochrona wyroczni](/pl/workflows/test/protect-the-oracle/) — Reguły deny, sandbox i CODEOWNERS dla testów, tu zastosowane do plików reguł.
- [Decyzje architektoniczne, których agenci przestrzegają](/pl/workflows/plan/architecture-decisions/) — Krótkie ADR-y, których sprawdzalna maszynowo część staje się regułami z tej strony.
- [Jak utrzymać w zdrowiu kod pisany przez agentów](/pl/workflows/operate/codebase-health/) — Trendy churnu, złożoności i rewertów w czasie oraz progi, które obniżają autonomię pętli.
- [Jak przygotować repozytorium do pracy agentów](/pl/workflows/harness/agent-ready-codebase/) — Warunek wstępny: kontrole jednym poleceniem, ścisłe typy i wyraźne granice modułów do egzekwowania.
