agentleFS
dung204dung204/hono-starter-template/.claude/skills/arch-audit/SKILL.md

arch-audit

Skill1 starsChanged 3 months agoMITView on GitHub

Audit new or modified files under src/ against this project's Functional Clean Architecture conventions (docs/01-module-layout.md through docs/06-database-migrations.md) — a project-specific rules linter, distinct from the general-purpose /code-review command. Checks things Biome and tsc can't: no class/this/inheritance in domain code, no trailing export blocks, missing explicit return types, Drizzle imports leaking outside repository/schema files, DB-generated UUIDs instead of generateId(), non-UTC/non-ISO-8601 timestamps in DTOs, and services that accept a repository parameter or get wrapped in a factory instead of hard-importing the singleton. Defaults to a read-only Audit Mode that reports findings; switches to Refactor Mode — which fixes what it safely can and re-verifies `bun test` stays green — when asked to "fix", "auto-fix", or "--fix", or when invoked as part of `/feature-flow`'s REFACTOR phase. Use this whenever the user asks to review, audit, lint, check, or fix a module/file against "our architecture", "the conventions", "the spec", or the docs/ guidelines specifically — or after generating/editing anything under src/modules/, src/shared/, or src/configs/, even if they don't name this skill. If the user just wants a general correctness/bug/simplification review, that's the /code-review command, not this skill — the two are complementary, not interchangeable.

2 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions2 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 2

    1. maxenko/claude-skills★ 1same name
    2. matthewmturner/skills★ 0same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository5 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 3 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Audit Mode (default): Read-only. Produces the report in Step 4.

    line 12
  2. Distinctive:

    Use this exact structure. One entry per file with at least one finding.

    line 47
  3. Very specific:

    If nothing was found: say so plainly — No architectural violations found in N file(s) scanned.

    line 61
  4. Distinctive:

    Read code around a grep hit before reporting it as a finding.

    line 92
  5. Very specific:

    Don't flag general code quality, bugs, or simplification opportunities — redirect the user to /code-review for that.

    line 99
  6. Very specific:

    Don't flag new OpenAPIHono() inside createController(), new Error(...) inside createDomainError(), or any other framework-class …

    line 100
  7. Very specific:

    Don't flag src/configs/db.ts's Drizzle import, or drizzle.config.ts/scripts/migrate.ts — these are the designated places Drizzle-adjacent …

    line 101
  8. Very specific:

    Don't audit generated files (migrations/, node_modules/) or anything outside src/, tests/, scripts/, drizzle.config.ts.

    line 102
  9. Distinctive:

    Don't run Refactor Mode unless it was actually triggered (Step 0) — an unrequested file edit is a bigger surprise than an unrequested …

    line 103
  10. Very specific:

    Don't edit anything under tests/ in Refactor Mode, ever, and don't leave a known regression in place hoping it's unrelated — revert instead.

    line 104

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Auditing architectural conventions (arch-audit)

This is a narrow, rule-based linter for conventions this project has decided on that Biome and tsc can't check — it doesn't look for bugs, style nits, or simplification opportunities (that's /code-review's job). Every rule here traces back to a specific docs/ guideline; when you flag something, say which one. It runs in one of two modes (Step 0) — reporting findings by default, or fixing them when explicitly asked to.

Step 0 — Choose the mode

  • Audit Mode (default). Read-only. Produces the report in Step 4. Nothing under src/ changes.
  • Refactor Mode. Activates when the request explicitly says --fix, "fix it", "auto-fix", "audit and fix", "refactor the violations", or equivalent — or when this skill is invoked as part of /feature-flow's Phase 4 (REFACTOR & Audit), which always requests Refactor Mode by design. See Step 4′.

If it's genuinely unclear which mode was intended, default to Audit Mode and ask. The two modes aren't symmetric in risk: Audit Mode can't cause harm by being run unnecessarily, but Refactor Mode edits real files, so guessing wrong only has a bad outcome in one direction.

Refactor Mode is safest scoped to one module at a time (the common case — feature-flow always scopes it to src/modules/<feature-name>/). If asked to run Refactor Mode across a broad git diff-based scope spanning several unrelated modules, consider confirming scope with the user first — a large batch of unrelated fixes is harder to verify safely in one pass than a handful in one module.

Step 1 — Determine scope

Default to files changed on the current branch: git diff --name-only main...HEAD (or git diff --name-only for uncommitted changes — check both, since often there's a mix). If the user names specific files, a module, or a directory instead, audit exactly that. Only ever audit files under src/, tests/, scripts/, or drizzle.config.ts — nothing outside the project's own code.

Step 2 — Classify each file by kind

The file's suffix tells you which checks apply — most checks are scoped to one or two kinds, and running a check against the wrong kind produces false positives. Read references/checks.md now; it has the full per-check detection guidance and worked compliant/violating examples for all seven rules below. This file just orients you.

SuffixKindChecks that apply
*.schema.tsinfrano-class, no-trailing-export, missing-return-types, db-generated-id
*.entity.tsdomainno-class, no-trailing-export, missing-return-types
*.dto.tswireno-class, no-trailing-export, missing-return-types, non-iso-timestamp
*.repository.tsdata accessno-class, no-trailing-export, missing-return-types (Drizzle import is allowed here — it's the exception, not a violation)
*.errors.tsdomain errorsno-class, no-trailing-export, missing-return-types, drizzle-leak (should never import Drizzle)
*.service.tsuse casesno-class, no-trailing-export, missing-return-types, drizzle-leak, service-di-violation
*.controller.tsroutesno-class, no-trailing-export, drizzle-leak (inline handlers are exempt from missing-return-types — see docs/01-module-layout.md's explicit-return-type rule)
src/shared/**, src/configs/**cross-cuttingno-class, no-trailing-export, missing-return-types, drizzle-leak (except src/configs/db.ts, which legitimately imports Drizzle to build the client)
anything else under src/—no-class, no-trailing-export, missing-return-types only; don't apply the domain-specific checks (db-generated-id, non-iso-timestamp, drizzle-leak, service-di-violation) outside the module layers they're scoped to

Step 3 — Run the checks, then verify by reading

grep is a fast first pass for most of these (patterns are given in references/checks.md), but don't report a finding on a grep hit alone — read the surrounding code and confirm it's a real violation, not a false positive (a class keyword inside a string literal, a this inside a framework callback that's fine, a legitimate drizzle-orm import in configs/db.ts). The reverse also matters: missing-return-types and service-di-violation are structural judgments a regex will miss half the time — read the function signature yourself rather than trusting a grep result alone.

This step's output — a confirmed, per-file list of findings — feeds both modes below: Step 4 reports it as-is, Step 4′ turns it into fixes.

Step 4 — Audit Mode: Report (default)

Use this exact structure. One entry per file with at least one finding; skip clean files silently, but say how many files were scanned and how many were clean in the summary line.

## Architecture audit — N files scanned, M clean, K with findings

### src/modules/<feature>/<feature>.service.ts

- **[service-di-violation]** `createFoo(repo: FooRepository, input: ...)` — `service.ts` must hard-import the repository singleton, not receive it as a parameter. See `docs/03-repository-pattern.md`. (line 12)

### src/modules/<feature>/<feature>.schema.ts

- **[db-generated-id]** `id: uuid('id').primaryKey().defaultRandom()` — the `id` column must have no default; spread `idColumn` from `@/shared/columns` instead, and assign the id via `generateId()` in the service layer. See `docs/02-clean-architecture.md`. (line 6)

If nothing was found: say so plainly — No architectural violations found in N file(s) scanned. — don't pad a clean result with unrelated observations; that's /code-review's scope, not this skill's. In Audit Mode, stop here — Refactor Mode (Step 4′) only runs when Step 0 selected it.

Step 4′ — Refactor Mode: Fix, then prove nothing broke

Only runs when Step 0 selected Refactor Mode. This is real code-editing, so the discipline below exists because an unverified "fix" is worse than a reported finding: a human can evaluate a finding, but a silent behavior change is exactly what "never break a passing test" is guarding against.

  1. Establish a green baseline first. Run bun test scoped to the audited module's tests (tests/modules/<target>/) before changing anything. If it isn't already fully green, stop and fall back to Audit Mode's report instead — "never break a passing test" is unverifiable without knowing which tests were passing before you started, and an unrelated pre-existing test failure isn't this skill's problem to absorb into an architecture fix.
  2. Never touch anything under tests/. Every fix is a change to a file under src/, full stop — this is the same "tests are frozen, only implementation code moves" discipline test-badass, gen-module, and feature-flow hold to elsewhere in this project's pipeline; arch-audit holds it too, and it's what makes "strictly preserving all existing test assertions" true by construction rather than by hoping the fix happened not to touch them.
  3. Apply the fix each finding implies, using references/checks.md's compliant example for that check as the target shape. Most of the seven checks are mechanical, same-file structural changes with one obvious correct shape (no-trailing-export, missing-return-types, non-iso-timestamp, db-generated-id). A couple aren't always mechanical: drizzle-leak can mean a query needs to become a new repository method other code then has to call, and no-class is only a clean mechanical rewrite when the class is a plain data-plus-methods wrapper with no inheritance or private state doing something structural. If turning a violation into its compliant shape isn't obviously equivalent — if it requires guessing at intent the docs don't pin down — don't force it. Skip that one finding, note why, and leave it for a human. Auto-fixing everything isn't the goal; auto-fixing everything safely is.
  4. Re-run bun test on the same scope after all fixes. Every test that passed in the Step 1 baseline must still pass now. A test that was already failing before Refactor Mode started is allowed to still be failing — that's not this skill's fault — but nothing may flip from passing to failing.
  5. If any fix caused a regression, revert that specific fix (not the whole batch), and report it as skipped with the reason. Don't try to debug or patch around a regression speculatively — that's general bug-fixing, outside this skill's scope, same as the existing Don't about redirecting to /code-review.
  6. Re-run this skill's own Steps 1–3 against the fixed files to confirm they're now clean, then run bunx biome check --write . and bunx tsc --noEmit as a final check — a structural fix can introduce a lint or type issue none of the seven architecture checks look for.
  7. Report using this shape:
## Architecture refactor — N violations found, F fixed, S skipped

### Fixed
- **[db-generated-id]** src/modules/<feature>/<feature>.schema.ts:6 — removed `.defaultRandom()`; id is now assigned via `generateId()` in the service layer.

### Skipped (not auto-fixed)
- **[drizzle-leak]** src/modules/<feature>/<feature>.service.ts:22 — the query only makes sense split across two repository methods; needs a human decision on the resulting API shape.

**Tests:** N pass, 0 fail (baseline was N pass, 0 fail — no regressions)
**Biome / tsc:** clean

Do

  • Trace every finding back to the specific docs/0X-....md file that establishes the rule.
  • Scope each check to the file kinds in the table above — a drizzle-leak finding in a *.repository.ts file is itself a false positive, since Drizzle imports are required there.
  • Read code around a grep hit before reporting it as a finding.
  • Report a clean scan plainly and briefly.
  • Stay in Audit Mode unless Refactor Mode is explicitly requested or feature-flow is doing the asking (Step 0).
  • In Refactor Mode: capture the bun test baseline before any fix, skip (don't force) any finding whose fix isn't obviously mechanical, and revert a fix immediately if it causes a regression.

Don't

  • Don't flag general code quality, bugs, or simplification opportunities — redirect the user to /code-review for that.
  • Don't flag new OpenAPIHono() inside createController(), new Error(...) inside createDomainError(), or any other framework-class instantiation as a no-class violation — see docs/02-clean-architecture.md's explicit carve-out.
  • Don't flag src/configs/db.ts's Drizzle import, or drizzle.config.ts/scripts/migrate.ts — these are the designated places Drizzle-adjacent tooling code lives outside a repository.
  • Don't audit generated files (migrations/**, node_modules/) or anything outside src/, tests/, scripts/, drizzle.config.ts.
  • Don't run Refactor Mode unless it was actually triggered (Step 0) — an unrequested file edit is a bigger surprise than an unrequested report.
  • Don't edit anything under tests/ in Refactor Mode, ever, and don't leave a known regression in place hoping it's unrelated — revert instead.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.