Skip to main content

How it works

  • Claude Code reads the CLAUDE.md in the root at the start of every session and loads the modules in .claude/rules/ on its own (no @import): those with paths: only when it reads or edits a matching file. With /context you see what is loaded; a module with paths: appears with a Loaded <path> line when it is activated.

  • The rules in the modules are global and general. What is specific to a project lives in its CLAUDE.md, which takes precedence in case of conflict. An exception to a rule is written in the "Exceptions to the global rules" section of that project's CLAUDE.md, with the reason: it applies only to that project.

  • A deviation from an automatic check of the plugin is written in the code, on the same line or on the line above: kit-allow: <id> — <reason> (core.md §6, point 23).

  • In the modules, "always", "never", "forbidden", "mandatory" are non-negotiable rules (they are waived only with your approval); "prefer", "preferred", "evaluate" are default settings that can be changed with a stated reason.

  • Files in the template must never contain absolute paths or names of other projects.

What Claude asks and what it does on its own

It asks, always one question at a time, waiting for the answer (core.md §6.5):

  • At startup: project type, security, Docker, status (new or existing), frontend and mobile technology, ORM, root .NET files, flow per entity;

  • Whenever there is a doubt, an ambiguous requirement, a large refactoring, a copyleft license or a new best practice;

  • The "asked, not assumed" choices of the CLAUDE.md (architecture, error library, database, security, cache, email, background jobs, logging, language of README.md and CHANGELOG.md, etc.), with the answers recorded in the CLAUDE.md so they are not asked again.

It does on its own:

  • Writes the plan in PIANO.md before any substantial work; for a small and obvious change (one file, a few points, no open decisions) it says in chat what changes and proceeds without a plan (if you already have one, it checks it against the rules: conflicts and gaps are asked about one at a time), and carries out one point at a time, with your OK at each step;

  • Checks the build, tests and (if touched) docker compose config before declaring a task finished, and reports the errors exactly as they are;

  • Declares the name, version and reason for every new dependency, and points out requests that break the rules, proposing a compliant alternative;

  • Updates README.md and CHANGELOG.md at every step of the plan.

  • Notes in CHECKLIST.md the bugs and improvements it finds while working, without stopping the work (core.md §6, points 20-22).

Git: follows the full git flow, with develop mandatory in every project (if it is missing, it asks you whether it can create it from main), confirms the branch with you for each job, does not commit on main or develop without your exception, presents the commit plan and creates one commit at a time with your OK. It only makes local commits: repository initialization and pipelines remain your responsibility; push, PR, tags and releases it runs only if the project has approved them in CLAUDE.md (line "Integrazione GitHub approvata"), otherwise they remain your responsibility. With the kit plugin installed, these prohibitions and the single-question rule are enforced technically too, not only written down. Secrets in configuration, forbidden patterns in the code and quality practices are checked by the plugin as well: blocks stop the operation, while warnings and reminders stay visible to Claude and to you.

Deploy: always with Dockerfile and docker-compose (docker.md). The database (SQL Server or PostgreSQL) and nginx as reverse proxy are already on the server: Claude does not generate configurations for them. You manage the servers; Claude produces the artifacts (base file, override, prod, .env.example) but does not configure hosts, network or TLS.