quality-audit
/quality-audit
Sprawdza kod względem pliku golden-principles.yaml projektu przez deterministyczne reguły wykrywania i aktualizuje docs/QUALITY_SCORE.md.
- Autor
- tansuasici ↗
- Repozytorium
- claude-code-kit ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 21.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 2
- Skrypty
- 0
- Komentarze HTML
- 5
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 21.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
- SKILL.md zawiera komentarze HTML (5). Nie widać ich w podglądzie Markdown, a model je czyta.
Co robi i kiedy
Sprawdza kod względem pliku golden-principles.yaml projektu przez deterministyczne reguły wykrywania i aktualizuje docs/QUALITY_SCORE.md.
Oryginalny opis (EN)
Audit the codebase against the project's golden-principles.yaml — runs deterministic detection rules and updates docs/QUALITY_SCORE.md. Use to enforce project-specific principles. For a generic smell pass with no rules file use /code-quality-audit.
Jak działa
- Core Rule
- Kit Context
- When to Use
- Default Behavior
- Inputs
- Schema: golden-principles.yaml
- Process
- Output Format
- Run Mode
- Loop / Schedule Integration
Podgląd SKILL.md
---
name: quality-audit
description: Audit the codebase against the project's golden-principles.yaml — runs deterministic detection rules and updates docs/QUALITY_SCORE.md. Use to enforce project-specific principles. For a generic smell pass with no rules file use /code-quality-audit.
user-invocable: true
---
# Quality Audit
## Core Rule
Only report drift that a `golden-principles.yaml` rule can detect deterministically. Never invent rules during the audit — if it's not in the YAML, it doesn't appear in the report.
## Kit Context
Before starting this skill, ensure you have completed session boot:
1. Read `CODEBASE_MAP.md` for project understanding
2. Read `CLAUDE.project.md` if it exists for project-specific rules
3. Read `tasks/lessons/_index.md` for accumulated corrections (Top Rules + index)
If any of these haven't been read in this session, read them now before proceeding.
## When to Use
Invoke with `/quality-audit` when:
- The project has (or should have) a `golden-principles.yaml` and you want to measure drift
- Onboarding to a project and want to see where the codebase deviates from documented principles
- Running as a scheduled background task (`/loop daily /quality-audit`) to track quality trends
- Preparing for a refactoring sprint — turn drift findings into a backlog
## Default Behavior
When the user asks to audit, scan, review, or "give me a report" for golden-principles drift, produce the full quality-audit report automatically using the Process and Output Format sections below. Do not require the user to specify fields.
Only modify files when the user explicitly requests implement / fix / apply / refactor. By default, this skill is **report-only** (with one exception: it updates `docs/QUALITY_SCORE.md` because that file is the report's destination).
## Inputs
The skill looks for `golden-principles.yaml` in this order:
1. `golden-principles.yaml` (repo root)
2. `.claude/golden-principles.yaml`
If neither exists, the skill emits a stub and a one-paragraph guide pointing at `.claude/skills/quality-audit/templates/golden-principles.example.yaml`. It does not invent rules.
## Schema: golden-principles.yaml
```yaml
# golden-principles.yaml — deterministic, machine-checkable project rules
# Each principle must have an id, rule, severity, detect, and fix_hint.
# Optional: tags, paths, enabled.
version: 1
principles:
- id: prefer-shared-utils
rule: "Hand-rolled helpers should be replaced with shared util packages"
severity: major # critical | major | minor
detect:
type: grep # grep | rg | command
pattern: "function (debounce|throttle|deepClone)\\b"
paths: # optional — defaults to repo root excluding vendor/build dirs
- "src/**/*.ts"
- "src/**/*.tsx"
fix_hint: "Use @workspace/utils/{debounce,throttle,deepClone} instead."
tags: [refactor, utils]
enabled: true
- id: no-yolo-data
rule: "Don't traverse data structures without validation at the boundary"
severity: critical
detect:
type: rg
pattern: "JSON\\.parse\\("
paths: ["src/**/*.ts"]
fix_hint: "Wrap with Zod schema parse() — see src/schemas/."
tags: [type-safety, boundary]
- id: no-direct-db-in-route
rule: "Route handlers must not import database clients directly"
severity: critical
detect:
type: command
command: "rg -l 'from .prisma|from .drizzle' src/app/api/ | head -20"
# 'command' shells out exactly as written. Output lines = matches.
fix_hint: "Move queries to src/repositories/ and inject through a service."
```
**Detection types:**
- `grep` — `grep -RnE "<pattern>" <paths>`. Portable, slowest.
- `rg` — `rg --column -e "<pattern>" <paths>`. Fast, requires ripgrep. Falls back to grep if `rg` is absent.
- `command` — shell out exactly as written. Each output line is one match. Use sparingly — harder to audit.
**Severity → weight (for the score):**
| Severity | Weight |
|----------|--------|
| critical | 5 per match |
| major | 2 per match |
| minor | 1 per match |
**Score formula:** `score = max(0, 100 - sum(weight × matches))`. Clamped to `[0, 100]`. Reported alongside per-principle counts so a single noisy rule doesn't hide the picture.
## Process
### Phase 1: Inventory (first-pass leads)
This pass produces **candidates**, not findings. Treat counts as leads for deeper inspection in later phases. Do not report Phase 1 raw output as the final result.
1. Resolve `golden-principles.yaml` (root → `.claude/`). If missing, emit the stub guide and stop.
2. Parse the YAML. Skip principles with `enabled: false`.
3. Validate each principle has `id`, `rule`, `severity`, `detect`, `fix_hint`. Skip malformed entries with a warning line in the report.
4. For each enabled principle, run its `detect` rule and collect raw matches. **These are candidates, not confirmed violations.**
### Phase 2: Triage
For each principle's candidates:
1. **Suppress false positives.** Skip matches inside comments, test fixtures (`**/*.test.*`, `**/__fixtures__/**`), and any path matching the principle's own implementation (use `.quality-audit-ignore` glob list if present).
2. **De-duplicate** by file:line.
3. Keep top 25 matches per principle (full count is preserved in the metrics row).
### Phase 3: Score & Report
1. Compute the score using the formula above.
2. Group findings by severity → critical / major / minor.
3. For each finding, include: `file:line`, the matched snippet (trimmed to 80 chars), and the principle's `fix_hint`.
### Phase 4: Write `docs/QUALITY_SCORE.md`
If `docs/` does not exist, skip the file write and print the report to stdout. Do NOT create `docs/` from this skill — that's `/harness-init`'s job.
If `docs/QUALITY_SCORE.md` exists:
1. Preserve any section above the `<!-- quality-audit:start -->` marker.
2. Replace content between `<!-- quality-audit:start -->` and `<!-- quality-audit:end -->` with the new report.
3. If markers are absent, append the report and add markers around it.
This keeps the file safe to edit by hand outside the managed block.
## Output Format
```markdown
# Quality Score
<!-- quality-audit:start -->
_Last run: 2026-05-18T14:23:00Z — quality-audit v1_
## Summary
| Metric | Value |
|--------|-------|
| Score | 87 / 100 |
| Principles enabled | 6 |
| Principles violated | 3 |
| Critical findings | 1 |
| Major findings | 4 |
| Minor findings | 7 |
## Findings
### Critical
#### `no-yolo-data` — Don't traverse data structures without validation at the boundary
| # | Location | Match | Fix |
|---|----------|-------|-----|
| 1 | `src/app/api/orders/route.ts:42` | `JSON.parse(body)` | Wrap with Zod schema parse() — see src/schemas/. |
### Major
#### `prefer-shared-utils` — Hand-rolled helpers should be replaced with shared util packages
| # | Location | Match | Fix |
|---|----------|-------|-----|
| 1 | `src/lib/format.ts:12` | `function debounce(fn, ms)` | Use @workspace/utils/{debounce,...} instead. |
### Minor
_None._
## Trend
| Run | Score | Δ |
|-----|-------|---|
| 2026-05-18 | 87 | — |
| 2026-05-11 | 85 | +2 |
| 2026-05-04 | 82 | +3 |
_(Trend is only emitted when previous runs are present in the managed block.)_
<!-- quality-audit:end -->
```
## Run Mode
| Decision point | Interactive default | Headless default (`mode:headless`) |
|---|---|---|
| Missing `golden-principles.yaml` | Print stub guide, ask user if they want a starter copied in | Print stub guide and exit code 0 — never write files unprompted |
| `docs/` missing | Print to stdout, ask before creating | Print to stdout, exit 0 (never create `docs/`) |
| Confirm refactor PR | Ask | Never open PRs in headless mode — drift report only |
See `.claude/skills/_shared/blocks/mode-detection.md`.
## Loop / Schedule Integration
The skill is designed for unattended runs:
```text
/loop daily /quality-audit mode:headless
/schedule weekly /quality-audit mode:headless
```
When fired by a loop or schedule, the report is appended to `docs/QUALITY_SCORE.md`'s managed block and (if score drops by more than 5 points week-over-week) a follow-up task is added to `tasks/todo.md → ## Drift Alerts` — the human handles the refactor decision.
## Templates
A starter `golden-principles.yaml` ships at `.claude/skills/quality-audit/templates/golden-principles.example.yaml`. Copy it to the repo root and tailor for your stack.
## Notes
- This skill is **complementary** to `/code-quality-audit`. The latter checks generic code smells (long functions, swallowed errors). `/quality-audit` enforces *your* project's rules.
- If a principle becomes universally adopted (zero matches for 3+ runs), consider removing it — the YAML is a living document, not a graveyard.
- The detection layer is intentionally simple (grep/rg/command). For AST-level checks, write a custom `command:` that shells out to your project's existing linter (ESLint custom rule, Semgrep, etc.) — this skill is the orchestrator, not the analyzer.
Pliki w paczce (2)
- SKILL.md 9 KB
- templates/golden-principles.example.yaml 4 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · tansuasici/claude-code-kit | 100 | MIT |
| NickCrew/Claude-Cortex | 100 | MIT |
| EmbedBuild/specbox-engine | 95 | Apache-2.0 |
Migawka bazy z 13.11.2026 · wersja paczki 01082a89258d (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100code-quality-audit
Audytuje kod pod kątem code smells, luk w obsłudze błędów i problemów z utrzymywalnością, z konkretnymi poprawkami, w ogólnym przeglądzie niezwiązanym z regułami projektu. - 100constitution
Pisze lub rozszerza plik golden-principles.yaml projektu: interaktywnie dla nowych repozytoriów albo przez wnioskowanie i potwierdzanie kandydatów z istniejącego kodu, jako zasady kodowania i bramki jakości. - 100recipe-quality-profile
Proponuje zasady jakości dla repozytorium do implementacji i przeglądu, a po potwierdzeniu tworzy lub aktualizuje plik quality.yaml. - 100blueprint-generate-rules
Generuje reguły specyficzne dla projektu z dokumentów PRD w docs/prds/ z frontmatterem ograniczonym do ścieżek: reguły architektury, testowania i jakości. - 100audit
Sprawdza, czy złote ścieżki projektu nie rozjechały się z kodem, porównuje wynik z poprzednim raportem i zapisuje go. - 100code-quality
Przegląda kod w poszukiwaniu problemów jakości, naruszeń stylu i code smells.