agentleFS
andy-dendy-repoandy-dendy-repo/govern/CLAUDE.md

govern

CLAUDE.md2 starsChanged 32 days agoMITView on GitHub

Govern is an HTTP Web API with a Blazor WASM client. The PlainCV sample project (a separate local repo) is a sample only, not a source of truth. Borrow ideas from it, never conventions. The rules below win. Integration tests need Docker running (Testcontainers starts postgres:17-alpine). Branch from stage and open the PR to stage. A PR from stage to main is a release; run the security-auditor agent first. Critical or High findings block the release. Never commit or push…

  • Deletes or force-pushes

The file

We split this CLAUDE.md into the rules it gives an agent

7 rules. About 0 are common, 1 is distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

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

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

    Mapping: no mapping libraries. Use EF Select projections.

    line 79
  2. Very specific:

    Packages: never pick versions from memory.

    line 80
  3. Very specific:

    Use find_symbol, find_references and find_callers to navigate.

    line 85
  4. Very specific:

    Use get_project_graph, get_endpoint_map and get_di_registrations to understand structure.

    line 86
  5. Very specific:

    Use detect_antipatterns, find_dead_code and analyze_change_impact to check quality.

    line 87
  6. Very specific:

    Use resolve_stack_trace for exceptions.

    line 88
  7. Distinctive:

    Prefer these over reading whole files.

    line 89

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md 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
CLAUDE.md

Govern

Govern is an HTTP Web API with a Blazor WASM client.

ConcernChoice
Runtime.NET 10 / C# 14
DatabasePostgreSQL (EF Core + Npgsql)
AuthJWT bearer tokens in the Authorization header
UIBlazor WebAssembly + Radzen
HostingAzure Web App for Containers (Ubuntu image) for the Api, Azure Static Web App for the Client, cheapest Azure PostgreSQL Flexible Server tier
DNSCloudflare + Azure
Infra as codeBicep in infra/
Source control and CI/CDGitHub + GitHub Actions

The PlainCV sample project (a separate local repo) is a sample only, not a source of truth. Borrow ideas from it, never conventions. The rules below win.

Layout

  • src/: production projects. See .claude/rules/project-map.md for what goes where and allowed references.
  • tests/:
    • Govern.UnitTests: Utils, Core and Domain only (pure code).
    • Govern.IntegrationTests: everything else on the server, via HTTP against Postgres in Testcontainers.
    • Govern.ClientTests: Blazor client components and services (bUnit).
    • Govern.ArchitectureTests: enforces the rules.
  • docs/: knowledge base (RAG); index in docs/README.md.
  • rulesets/: the game's rulesets (<key>/vN.json), the data Core plays with; format in docs/game/game-data.md. Never edit a published version; add a new one.
  • maps/: the map pool (<key>.json), hand-made maps a lobby can choose; format and checks in docs/game/maps.md. Running games keep their own copy, so a map file may be edited.
  • infra/: Bicep.
  • tools/: offline Node tools; tools/unit-models bakes the 3D board's unit models from the CC0 KayKit pack (see its README).
  • .github/workflows/: CI and release; .github/scripts/configure-client.sh fills the client CSP and Api origin.
  • Govern.Core is the pure game engine (base class library only, shared with the client); see .claude/rules/game-core.md. Game work branches from and PRs to stage like everything else (gamecore is retired).

Commands

dotnet build Govern.slnx                                        # warnings are errors, XML docs required in src/
dotnet test Govern.slnx                                         # ALL tests (Microsoft Testing Platform, xUnit v3)
dotnet test --project tests/Govern.ArchitectureTests            # one project while iterating
dotnet test Govern.slnx --coverage --coverage-output-format cobertura   # coverage → ./TestResults
dotnet format Govern.slnx --verify-no-changes
dotnet ef migrations add <Name> --project src/Govern.Infrastructure --startup-project src/Govern.Api --output-dir Persistence/Migrations
dotnet tool restore                                             # local tools (cwm-roslyn-navigator, dotnet-ef)
dotnet run --project src/Govern.Api                             # needs user-secrets: see docs/operations/local-development.md
dotnet run --project src/Govern.Client                          # Radzen client on https://localhost:7042 (Api on :7294)
dotnet publish src/Govern.Api -c Release -t:PublishContainer    # container image govern-api:local
az bicep build --file infra/main.bicep                          # compile infra

Integration tests need Docker running (Testcontainers starts postgres:17-alpine).

Branching

Branch from stage and open the PR to stage. A PR from stage to main is a release; run the security-auditor agent first. Critical or High findings block the release. Never commit or push to main or stage directly; a hook blocks it. Commit or push only when the user asks, using conventional commits.

Definition of Done (every feature → /develop-feature)

  1. Planned in the .claude/rules/planning.md format.
  2. Tests written or updated:
    • unit tests (Utils, Core and Domain only)
    • integration tests (happy path, 400, 401/403, domain errors)
    • client tests (bUnit) for client components and services
    • architecture tests (for new conventions)
  3. XML docs on every public member (the build fails otherwise).
  4. docs/ updated (feature doc + index). A game rules change also updates the player rules reference docs/game/rules.md (its tables are checked by RulesReferenceTests).
  5. .claude rules, skills and this file corrected if a convention changed. Rules and arch tests change together.
  6. Build and ALL tests have been run in this session and are green, with the summary shown, BEFORE saying the feature is done. Use /verify. A Stop hook blocks finishing while changed code has no green dotnet test Govern.slnx run.

Core conventions (details in .claude/rules/)

  • Folder templates: UF / AGFT / 3DFT per project, CFT for the client (blazor-client.md), the Core template for the game engine (game-core.md). Folders are created on demand and are whitelisted by FolderStructureTests.
  • No Helper suffix. Name classes by role: Resolver, Mapper, Calculator, Builder…
  • Suffix per folder: Options, Exception, Service, Repository, EventHandler, Endpoint, and so on.
  • Use case files: Application/[Feature]/Contracts/XxxContract.cs holds XxxRequest, XxxResponse, XxxValidator, XxxHandler and file types only.
  • Endpoints: one endpoint per file in Api/Features/[Feature]/XxxEndpoint.cs.
  • Repositories exist only for cached queries.
  • Mediator: Govern.Utils.Mediator. Requests are IRequest<TRequest, TResponse>, handlers return Result<TResponse>, and the pipelines are error handling → logging → validation.
  • Errors: expected failures are returned as Error ([Feature]/Models/XxxErrors.cs); only bugs throw.
  • Mapping: no mapping libraries. Use EF Select projections; reused projections are static Projection/From members on the target type.
  • Packages: never pick versions from memory. Use dotnet add package, which writes to central Directory.Packages.props.

MCP servers

  • cwm-roslyn-navigator: read-only analysis.
    • Use find_symbol, find_references and find_callers to navigate.
    • Use get_project_graph, get_endpoint_map and get_di_registrations to understand structure.
    • Use detect_antipatterns, find_dead_code and analyze_change_impact to check quality.
    • Use resolve_stack_trace for exceptions.
    • Prefer these over reading whole files.
  • roslyn-refactor: code changes. Rename, move type or namespace, change signature, extract method or interface, add missing usings, format. Use it for multi-file refactors instead of manual edits.
  • microsoft-docs / context7: current .NET, ASP.NET Core, EF Core, Radzen and Testcontainers APIs. Check them before using an API you aren't sure of.
  • postgres: inspect the local database (it is unrestricted; don't run destructive SQL without asking).
  • playwright: drive a real browser against the running client (https://localhost:7042) to check UI changes end to end: navigate, click, fill forms, read the accessibility snapshot, take screenshots.

Claude setup

KindItems
Rules, always loadedproject-map, planning
Rules, path-scopedarchitecture (src), blazor-client, game-ui (Client), csharp-style (*.cs, .razor), xml-docs, logging, mapping, error-handling (src/.cs), game-core (Core), caching (Infrastructure/Caching, repositories), persistence (Domain, Application, Infrastructure), api-endpoints (Api), auth (Api, Users, Identity), security (src, infra, .github, appsettings), unit-tests, integration-tests, client-tests, architecture-tests, docs
Skills/develop-feature (the dev flow), /verify (quality gate), /add-use-case, /add-entity, /add-migration, /add-infra-concern (recipes from the real Users slice), /outdated-packages (manual only)
Agents (read-only, project memory)code-reviewer (after every feature), security-auditor (before every stage → main release PR, and after auth, endpoint, config, infra or CI changes), ef-core-specialist (entities, configurations, migrations, slow queries)
Hooks (.claude/hooks/)bash guard (destructive git, protected branches, rm -rf), protected generated/secret files, whitespace format on edit, restore on csproj/props edit, test gate on Stop, branch info on SessionStart (and the Docker daemon in cloud sessions)

Build history: docs/plans/done/template-solution-roadmap.md (done). Open work, prioritised: docs/plans/backlog.md (the only place priorities are kept).

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.