Skip to main content

Periodic checks

  • The names of the APIs cited in the rules still exist in the versions in use (in particular AddOperationResult() and CreateResponse(result) of OperationResults by Marco Minerva; namespaces and signatures must be checked at each use).

  • Licenses to be checked at first use (never checked in a session): Coravel, Serilog and its sinks, MailKit, Scrutor, coverlet, ReportGenerator, NetArchTest or ArchUnitNET, axe, RabbitMQ.Client. Redis and RabbitMQ as external services: if the license no longer suits you, the BSD alternative to Redis is Valkey.

  • License of Mailpit (test SMTP for testing and development, external service already present in the infrastructure, see core.md §3 and backend-email.md): to be checked at first use on the official repository.

  • The starting thresholds are still suitable: 80% coverage, p95 under 300 ms for reads and under 1 s for writes, latest 2 versions of the browsers.

  • The template's CLAUDE.md reflects the fields you actually fill in every time.

Troubleshooting

SymptomWhat to check
Claude ignores a ruleIs the module in .claude/rules/ and loaded? Check with /context (modules with paths: are loaded only when a matching file is touched). Is the rule written with "always/never" or with "prefer"? If the session is long, repeat the rule or open a new session.
Claude uses a forbidden library (MediatR, AutoMapper, Hangfire, Quartz.NET)Remind it of the prohibition; check that core.md and backend.md are in .claude/rules/.
Conflict between a module and the projectThe project's CLAUDE.md prevails. If the conflict is not clear, Claude must ask.
A module does not loadCheck that it is in .claude/rules/ (not in rules-optional/) and, for frontend, backend and docker, that a file matching paths: has been read or edited.
Answers are not in ItalianThe language rule is in core.md §6 (code in English, explanations in Italian): check that core.md is loaded.
A hook blocks a write you believe is correctIf the pattern is legitimate, declare it with a waiver kit-allow: <id> — <reason> on the same line or on the line above (see Plugin). To suspend the whole plugin: claude plugin disable kit@claude-config.

Open points

  • Automations not configured: the bans on git push --force and --no-verify, and the blocking of push, PR, tags and releases without the project's approval, are technical only with the kit plugin installed; without it, they apply as written rules (git.md). Still outside the plugin: automatic linting after every change and docker compose config when Docker files change. Secrets in commits are blocked by the plugin (guard-commands and guard-secrets), but not by a scanner such as gitleaks.
  • Missing modules: there are no rules for a Blazor frontend nor for mobile (MAUI, Ionic + Capacitor, Flutter, React Native; PWA is only an option in the CLAUDE.md; for mobile there is only the minimal "Mobile" section of security.md, with a reference to OWASP MASVS), nor a dedicated section on Dapper (only the choice rule in backend.md §1). They are created as ad hoc modules only when a project requires them.

Updating the template

Rules are changed in the template (.claude/rules/, .claude/rules-optional/, CLAUDE.md), not in the copies in the projects: this applies to new projects. Projects already started have their own copy and are realigned on request ("Riallinea le regole") or with copia-regole.bat (option 2).

  • Every revision of core.md updates the version and date in the header and adds a subsection to CHANGELOG.md, under the day's heading (one ## YYYY-MM-DD heading per day, with one subsection per change).
  • The template has a repository on GitHub (AngeloDotNet/claude-config) with the git flow: each change starts from a feature/ or bugfix/ branch cut from develop, goes into develop by a PR with squash, and develop goes into main by a PR that uses a merge commit. The kit plugin reaches the machines only when its version rises (see Plugin).
  • A rule that applies only to one project goes into its CLAUDE.md, not into the modules.
  • When a library changes (Angular, PrimeNG, OperationResults, FusionCache), review the rules that cite it: Claude checks the installed version, but the rules must be kept up to date.
  • A change to the scripts or to hooks/hooks.json of the kit plugin reaches those who installed it only when version in plugins/kit/.claude-plugin/plugin.json goes up: with the version, a release entry is added to CHANGELOG.md, then claude plugin marketplace update claude-config and claude plugin update kit@claude-config are run (see plugin.md). Before the release: claude plugin validate. If the behaviour of the hooks changes, the Plugin page is also updated, in Italian and in English: the site does not generate it from the code.
  • Avoid letting files grow: the longer they are, the more some rules get overlooked. If a module exceeds about 200 lines, consider splitting it.