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
In this repository7 other files it gives its agents.
- add-entitySkill
- add-infra-concernSkill
- add-migrationSkill
- add-use-caseSkill
- develop-featureSkill
- outdated-packagesSkill
- verifySkill
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
- Very specific: line 79
Mapping: no mapping libraries. Use EF Select projections.
- Very specific: line 80
Packages: never pick versions from memory.
- Very specific: line 85
Use find_symbol, find_references and find_callers to navigate.
- Very specific: line 86
Use get_project_graph, get_endpoint_map and get_di_registrations to understand structure.
- Very specific: line 87
Use detect_antipatterns, find_dead_code and analyze_change_impact to check quality.
- Very specific: line 88
Use resolve_stack_trace for exceptions.
- Distinctive: line 89
Prefer these over reading whole files.
≈ “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.
Files
Govern
Govern is an HTTP Web API with a Blazor WASM client.
| Concern | Choice |
| Runtime | .NET 10 / C# 14 |
| Database | PostgreSQL (EF Core + Npgsql) |
| Auth | JWT bearer tokens in the Authorization header |
| UI | Blazor WebAssembly + Radzen |
| Hosting | Azure Web App for Containers (Ubuntu image) for the Api, Azure Static Web App for the Client, cheapest Azure PostgreSQL Flexible Server tier |
| DNS | Cloudflare + Azure |
| Infra as code | Bicep in infra/ |
| Source control and CI/CD | GitHub + 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.mdfor 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 indocs/README.md.rulesets/: the game's rulesets (<key>/vN.json), the data Core plays with; format indocs/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 indocs/game/maps.md. Running games keep their own copy, so a map file may be edited.infra/: Bicep.tools/: offline Node tools;tools/unit-modelsbakes the 3D board's unit models from the CC0 KayKit pack (see its README)..github/workflows/: CI and release;.github/scripts/configure-client.shfills the client CSP and Api origin.Govern.Coreis the pure game engine (base class library only, shared with the client); see.claude/rules/game-core.md. Game work branches from and PRs tostagelike everything else (gamecoreis 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 infraIntegration 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)
- Planned in the
.claude/rules/planning.mdformat. - 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)
- XML docs on every public member (the build fails otherwise).
docs/updated (feature doc + index). A game rules change also updates the player rules referencedocs/game/rules.md(its tables are checked byRulesReferenceTests)..clauderules, skills and this file corrected if a convention changed. Rules and arch tests change together.- 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 greendotnet test Govern.slnxrun.
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 byFolderStructureTests. - No
Helpersuffix. 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.csholdsXxxRequest,XxxResponse,XxxValidator,XxxHandlerandfiletypes only. - Endpoints: one endpoint per file in
Api/Features/[Feature]/XxxEndpoint.cs. - Repositories exist only for cached queries.
- Mediator:
Govern.Utils.Mediator. Requests areIRequest<TRequest, TResponse>, handlers returnResult<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
Selectprojections; reused projections are staticProjection/Frommembers on the target type. - Packages: never pick versions from memory. Use
dotnet add package, which writes to centralDirectory.Packages.props.
MCP servers
cwm-roslyn-navigator: read-only analysis.- Use
find_symbol,find_referencesandfind_callersto navigate. - Use
get_project_graph,get_endpoint_mapandget_di_registrationsto understand structure. - Use
detect_antipatterns,find_dead_codeandanalyze_change_impactto check quality. - Use
resolve_stack_tracefor exceptions. - Prefer these over reading whole files.
- Use
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
| Kind | Items |
| Rules, always loaded | project-map, planning |
| Rules, path-scoped | architecture (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).
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
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.

