Bramki jakości i egzekwowanie standardów

Twój zespół scalił PR w piątek, który wprowadził subtelny wyciek pamięci w obsłudze sesji użytkownika. Kod przeszedł wszystkie istniejące testy, ludzki recenzent zatwierdził go po szybkim rzucie oka, a linter nie miał nic do powiedzenia. Do poniedziałku rano serwis konsumował 4GB RAM i crashował co sześć godzin. Bramki jakości nie służą do wyłapywania błędów składniowych — służą do wyłapywania tego, co ludzie i lintery pomijają.

Co wyniesiesz z tego rozdziału

• Wielowarstwowa architektura bramek jakości wyłapująca problemy na każdym etapie
• Przepływy przeglądów kodu oparte na AI, które wykraczają poza sprawdzanie stylu
• Mierzalne metryki jakości korelujące z rzeczywistą stabilnością produkcyjną
• Wzorce promptów do głębokiej analizy kodu, w tym wydajności, bezpieczeństwa i utrzymywalności
• Strategie automatycznego egzekwowania, które nie spowalniają prędkości deweloperów

Architektura bramek jakości

Bramki jakości działają warstwowo. Każda warstwa wyłapuje inne kategorie problemów i żadna pojedyncza warstwa nie jest wystarczająca sama w sobie.

Warstwa 1: Pre-Commit (maszyna dewelopera)

Cursor

Inline AI w Cursor wyłapuje problemy podczas pisania. Wzmocnij go jawnymi regułami jakości:

.cursor/rules

CODE QUALITY STANDARDS:
Before suggesting any code, verify:
- No functions longer than 50 lines
- No files longer than 300 lines
- Cyclomatic complexity under 10 per function
- All public functions have JSDoc documentation
- Error handling follows our Result<T, E> pattern (no bare try/catch)
- No magic numbers - use named constants
- All database queries go through the repository layer

Claude Code

Hooki Claude Code wymuszają bramki jakości przed zatwierdzeniem kodu:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "write|edit",
      "command": "node scripts/quality-check.js \"$FILE_PATH\""
    }],
    "PostToolUse": [{
      "matcher": "write|edit",
      "command": "npx eslint --fix \"$FILE_PATH\" && npx tsc --noEmit"
    }]
  }
}

Zapewnia to, że każdy plik napisany przez Claude Code natychmiast przechodzi linting i sprawdzanie typów.

Codex

Codex egzekwuje jakość poprzez swoje izolowane środowisko wykonawcze:

codex.md

After every code modification:
1. Run the file's test suite
2. Run the linter on changed files
3. Run type checking
4. If any check fails, fix the issue before proceeding

Quality thresholds:
- All new code must have accompanying tests
- Test coverage for new code must be > 80%
- No lint warnings allowed in new code

Warstwa 2: Pre-Push (pipeline CI)

Wskazówka

Gotowy prompt do przeglądu PR wspomaganego AI:

Review this pull request with the depth of a senior engineer who cares about production stability:

1. Architecture Review:
   - Does this change respect our module boundaries?
   - Are dependencies pointing in the right direction?
   - Is the abstraction level appropriate?

2. Correctness Review:
   - Are there race conditions or concurrency issues?
   - Are error cases handled completely (not just the happy path)?
   - Are there edge cases in the input validation?

3. Performance Review:
   - Are there N+1 query patterns?
   - Are there unnecessary allocations in hot paths?
   - Will this scale to 10x current load?

4. Maintainability Review:
   - Would a new team member understand this code in 6 months?
   - Are the test names descriptive enough to serve as documentation?
   - Is the commit history telling a clear story?

For each issue: severity (block/warn/note), file:line, description, and suggested fix.
Do not flag style issues - the linter handles those.

Warstwa 3: Post-Merge (ciągłe monitorowanie)

Po scaleniu kodu narzędzia AI mogą monitorować degradację jakości.

Wskazówka

Gotowy prompt do monitorowania kondycji bazy kodu:

Analyze our codebase health metrics and compare against last month:
1. Average cyclomatic complexity per module (flag any > 15)
2. Test coverage by module (flag any that dropped > 5%)
3. Number of TODO/FIXME/HACK comments added vs. resolved
4. Dependency freshness (packages more than 2 major versions behind)
5. Dead code detection (exported functions with no importers)
6. Duplicate code detection (blocks > 20 lines appearing in multiple files)

Present as a health dashboard with trend arrows (improving/declining/stable).
Prioritize the top 3 items that need immediate attention.

Wzorce głębokiego przeglądu kodu

Przegląd przez pięć soczewek

Zastosuj pięć odrębnych soczewek analitycznych do każdego znaczącego PR.

Cursor

Uruchom każdą soczewkę jako osobną konwersację w Agent dla większej głębi:

Lens 1 - Correctness: Review /src/services/payment.ts changes.
Assume every input is adversarial. Find every way this code could
produce incorrect results, crash, or behave unexpectedly.

Lens 2 - Performance: Same file. Assume 10,000 requests per second.
Find bottlenecks, memory leaks, and unnecessary allocations.

Lens 3 - Security: Same file. You are a penetration tester.
Find every way to exploit this code.

Claude Code

Użyj sub-agentów do uruchamiania wielu soczewek przeglądu równolegle:

claude "Review the changes in the current git diff through five lenses.
For each lens, provide separate findings:

1. CORRECTNESS: Logic errors, edge cases, race conditions
2. PERFORMANCE: N+1 queries, memory leaks, unnecessary computation
3. SECURITY: Injection, auth bypass, data exposure
4. MAINTAINABILITY: Complexity, naming, documentation gaps
5. TESTABILITY: Missing tests, untestable patterns, flaky test risks

Rank all findings by severity and present the top 10 across all lenses."

Codex

Perform a five-lens code review on the changes in this PR:
1. Correctness: Will this produce wrong results for any valid input?
2. Performance: Will this degrade under production load?
3. Security: Can this be exploited by a malicious user?
4. Maintainability: Will the next developer understand and modify this safely?
5. Testability: Are there edge cases that the tests do not cover?

Post findings as inline PR comments at the relevant lines.

Metryki jakości, które mają znaczenie

Poza procentem pokrycia

Samo pokrycie testami nie wskazuje na jakość. Zamiast tego śledź te metryki:

Metryka	Co ujawnia	Cel
Wynik mutacyjny	Testy rzeczywiście łapią błędy, nie tylko wykonują kod	> 75%
Średni czas wykrycia	Jak szybko błędy są znajdowane po wprowadzeniu	< 1 sprint
Wskaźnik uciekających defektów	Błędy, które docierają do produkcji	< 2% zmian
Czas reakcji na przegląd	Jak długo PR czeka na przegląd	< 4 godziny
Wskaźnik przeróbek	PR wymagające > 2 rund przeglądu	< 15%
Niezawodność buildu	Wskaźnik sukcesu pipeline CI	> 95%

Wskazówka

Gotowy prompt do konfiguracji testów mutacyjnych:

Set up mutation testing for our TypeScript project:
1. Install and configure Stryker Mutator for our Jest test suite
2. Configure it to mutate: /src/services/ and /src/utils/ (skip tests and types)
3. Set thresholds: break at 60%, low at 70%, high at 80%
4. Add to our CI pipeline as a weekly job (mutation testing is slow)
5. Generate an HTML report showing which mutations survived

Run it on /src/services/payment.ts first as a proof of concept.
Show me which test gaps the mutations reveal.

Egzekwowanie standardów w zespołach

Współdzielona konfiguracja jakości

1. Stwórz współdzielony pakiet konfiguracji

   Pakiet w twoim monorepo lub osobny pakiet npm zawierający konfiguracje ESLint, TypeScript, Prettier i twoje pliki reguł AI.

2. Dystrybucja przez zarządzanie pakietami

   Każdy projekt rozszerza współdzieloną konfigurację. Lokalne nadpisania muszą być udokumentowane i zatwierdzone.

3. Egzekwowanie w CI

   Pipeline sprawdza, czy współdzielone konfiguracje nie zostały nadpisane bez zatwierdzenia.

4. Reguły AI dziedziczą ze współdzielonej konfiguracji

   Twoje pliki .cursor/rules lub CLAUDE.md odwołują się do współdzielonego dokumentu standardów.

5. Comiesięczne przeglądy jakości

   Wspomagane AI kontrole kondycji bazy kodu uruchamiane co miesiąc, porównujące zespoły ze współdzielonymi benchmarkami.

Kiedy coś się psuje

“Deweloperzy czują, że bramki jakości ich spowalniają.” Twoje bramki są zbyt restrykcyjne lub wyłapują niewłaściwe rzeczy. Skup bramki jakości na problemach o wysokiej ważności (bezpieczeństwo, poprawność, wydajność). Pozostaw styl i formatowanie automatycznym formatterom, które naprawiają problemy cicho, zamiast blokować.

“Przegląd kodu przez AI generuje zbyt wiele fałszywych alarmów.” Dostosuj swoje prompty do przeglądu. Dodaj “Do not flag style issues” i “Only report issues that could cause bugs, security vulnerabilities, or performance problems in production.” Przejrzyj wnioski AI przez tydzień i dostosuj prompt na podstawie tego, co było faktycznie przydatne.

“Zespoły oszukują metryki.” Jeśli zespoły piszą bezsensowne testy, aby osiągnąć cele pokrycia, przejdź na testy mutacyjne. Nie da się oszukać wyników mutacyjnych bez pisania testów, które faktycznie weryfikują zachowanie.

“Jakość jest niespójna między kodem generowanym przez AI a pisanym przez ludzi.” Stosuj te same bramki jakości do całego kodu niezależnie od pochodzenia. Pipeline CI nie obchodzi, kto (lub co) napisał kod.

Co dalej

Strategie testów jednostkowych Generuj kompleksowe testy jednostkowe wyłapujące prawdziwe błędy.

Pipeline'y CI/CD Wbuduj bramki jakości w swój pipeline wdrożeniowy.

Governance kosztów Zrównoważ inwestycje w jakość z prędkością rozwoju i kosztami.