infra-conventions
Skill234 starsChanged 3 months agoMITView on GitHub
Infrastructure and deployment conventions. Auto-injected into devops-aware agents - not user-invocable.
In this repository29 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- add-aspire-depSkill
- add-background-jobSkill
- add-ci-areaSkill
- add-email-templateSkill
- add-env-varSkill
- add-options-classSkill
- add-permissionSkill
- add-rate-limitSkill
- address-reviewSkill
- add-testSkill
- backend-conventionsSkill
- create-issueSkill
- create-prSkill
- create-releaseSkill
- frontend-conventionsSkill
- gen-typesSkill
- init-verifySkill
- manage-file-storageSkill
- new-endpointSkill
- new-entitySkill
- new-featureSkill
- new-pageSkill
- polish-uiSkill
- review-dependabotSkill
- review-designSkill
- review-prSkill
- security-conventionsSkill
- verifySkill
The file
Files
Infrastructure Conventions
Overview
Local dev: Aspire AppHost -> PostgreSQL, MinIO, MailPit (containers) + API + Frontend (processes)
Production: User's choice - Docker Compose, Coolify, Railway, Kubernetes, etc.- Backend Dockerfile: Multi-stage .NET build at
src/backend/MyProject.WebApi/Dockerfile - Frontend Dockerfile: Multi-stage Node/SvelteKit build at
src/frontend/Dockerfile - Production config:
appsettings.jsondefines the full config structure;docs/before-you-ship.mdlists what to configure
Deployment Checklist
Dockerfile Integrity
- All
.csprojfiles referenced by WebApi have COPY lines in the restore layer - Multi-stage build: restore -> build -> publish -> final (no SDK in final image)
StripDevConfigremovesappsettings.Development.jsonandappsettings.Testing.json- Health probe binary published separately and copied to final image
- Non-root user (
$APP_UID) in final stage - No secrets baked into image (build args, env vars at build time)
.dockerignoreexcludes unnecessary files (bin, obj, node_modules, .git)
Environment Variables
- All configurable options have sensible defaults in
appsettings.json - Sensitive values use placeholders in base config (not real secrets)
- Connection strings use env var substitution, not hardcoded values
ASPNETCORE_ENVIRONMENTset toProduction
Aspire (Local Dev)
- AppHost references all infrastructure dependencies
- Port allocation follows the project convention (base+N pattern)
- Credentials pinned via parameters (not randomly generated)
WithDataVolume()on stateful resources for persistence across restarts- ServiceDefaults wired: OTEL, service discovery, resilience
- Graceful degradation when not running under Aspire
Health Checks
- API:
/health/live(liveness) and/health/ready(readiness) - Health probe binary used in Docker (not curl/wget which add attack surface)
- Frontend: HTTP check on port 3000
- Start periods appropriate for cold starts (API: 60s, DB: 15s)
Reproducibility
- Can clone and run with
dotnet run --project src/backend/MyProject.AppHost(local dev) - No machine-specific paths or assumptions
- NuGet versions pinned in
Directory.Packages.props - pnpm lockfile committed
Security (Infrastructure)
- Production containers should use read-only root filesystem where possible
no-new-privileges:trueandcap_drop: ALLrecommended- tmpfs for writable directories (.NET needs /tmp and /home/app)
- Database not exposed on host network in production
- MinIO credentials not using defaults
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.

