Anatomy of the .claude Folder: Your AI Dev Control Center

your-project/
├── .claude/
│   ├── settings.json          ← permissions & behaviour flags
│   ├── settings.local.json    ← your personal overrides (gitignored)
│   ├── rules/                 ← auto-loaded instruction files
│   │   ├── api-design.md
│   │   └── ef-core.md
│   ├── skills/                ← on-demand reusable workflows
│   │   ├── code-review/
│   │   │   └── SKILL.md
│   │   └── fix-issue/
│   │       └── SKILL.md
│   ├── agents/                ← specialized subagents
│   │   └── security-auditor.md
│   ├── docs/                  ← reference docs skills pull on demand
│   │   ├── architecture.md
│   │   └── coding-standards.md
│   └── worktrees/             ← temp git worktrees for agent isolation
├── CLAUDE.md                  ← root instruction file (always loaded)
└── src/

# Project: Clinic Appointment System

## Tech stack
- .NET 9, PostgreSQL, Kafka, React 19
- ORM: EF Core 9 — code-first, Fluent API only
- Auth: JWT (JJWT 0.12) — never store tokens in localStorage

## Build & test
- `dotnet build` — build all
- `dotnet test` — run all tests (Testcontainers, needs Docker)
- `npm run dev` — start frontend

## Architecture rules
- Package by feature, not by layer
- Commands/Queries: sealed interfaces, MediatR handlers
- Never throw generic Exception — use ProblemDetails

## What NOT to do
- Do not add logging inside domain models
- Do not run `git push` without asking
- Do not modify migration files that are already applied

.claude/rules/
├── ef-core.md           ← only when touching DbContext or migrations
├── api-design.md        ← only when editing controller/endpoint files
└── dotnet-conventions.md  ← always loaded

---
paths:
  - "src/Infrastructure/Persistence/**/*.cs"
  - "**/*DbContext*.cs"
  - "**/Migrations/**"
---
# EF Core Rules

- Always use Fluent API in `OnModelCreating` — no data annotations on entities
- Never add navigation properties without explicit `HasForeignKey`
- Every new migration must have a descriptive name: `Add_AppointmentStatus_Column`
- Run `dotnet ef migrations add` — never hand-edit migration files

{
  "permissions": {
    "allow": [
      "Bash(dotnet build *)",
      "Bash(dotnet test *)",
      "Bash(dotnet ef migrations *)",
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Read",
      "Write",
      "WebFetch(domain:docs.microsoft.com)",
      "WebFetch(domain:learn.microsoft.com)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push *)",
      "Bash(git reset --hard *)",
      "Bash(DROP *)",
      "Read(./.env*)",
      "Read(**/secrets/**)"
    ]
  },
  "env": {
    "ASPNETCORE_ENVIRONMENT": "Development"
  }
}

.claude/skills/
├── code-review/
│   └── SKILL.md
├── generate-migration/
│   └── SKILL.md
└── fix-issue/
    └── SKILL.md

---
name: code-review
description: >
  Perform a structured code review. Auto-invoke when the user
  asks to review a PR, diff, or set of changed files.
allowed-tools: Read, Glob, Grep, Bash(git diff *), Bash(git log *)
model: sonnet
argument-hint: "[branch or file path]"
---

You are a senior engineer reviewing a pull request.

Changed files since main:
!`git diff main...HEAD --name-only`

Full diff:
!`git diff main...HEAD`

Review for:
1. Logic bugs and edge cases
2. Missing error handling
3. Naming clarity
4. Test coverage gaps
5. Security issues (SQL injection, auth bypass, secrets in code)

Output a structured review with: ✅ Good / ⚠️ Concern / ❌ Blocker labels.

/code-review              # manual invoke
/code-review src/api/     # with argument
/generate-migration AddClinicTable   # passes arg

---
name: security-auditor
description: >
  Security specialist. Automatically invoke when reviewing authentication,
  payment processing, or HIPAA-sensitive code.
tools: Read, Glob, Grep
model: sonnet
maxTurns: 50
---

You are a senior application security engineer.

Audit for:
- SQL injection (especially raw queries, string interpolation in SQL)
- Broken authentication (missing JWT validation, weak token storage)
- Insecure direct object references (IDOR)
- Hardcoded secrets or API keys
- Missing input validation on public endpoints
- HIPAA violations: PHI in logs, unencrypted storage

Return a prioritised findings report: CRITICAL → HIGH → MEDIUM → LOW.

.claude/docs/
├── architecture.md       ← domain model, bounded contexts
├── api-contracts.md      ← REST conventions, status codes, versioning
├── deployment.md         ← environments, Terraform, CI/CD steps
└── coding-standards.md   ← patterns, naming, what to avoid

---
name: write-api-endpoint
---

Read .claude/docs/api-contracts.md before writing any endpoint.
Then implement the requested feature following those conventions exactly.

~/.claude/
├── CLAUDE.md             ← your personal rules for every project
├── settings.json         ← your global permission defaults
├── rules/                ← personal rules (load before project rules)
├── skills/               ← personal skills available everywhere
├── agents/               ← personal agents
└── projects/
    └── my-project/
        └── memory/       ← auto-memory (first 200 lines per session)

# Personal preferences

- Always use British English in comments and docs
- Never use `var` — use `const` or `let`
- Prefer explicit return types in TypeScript
- When I ask to "clean up" code, fix formatting only — don't refactor logic
- Never commit without asking me first

1. Managed policy (enterprise system-level)
         ↓
2. CLI arguments
         ↓
3. settings.local.json  (your personal overrides)
         ↓
4. .claude/settings.json  (project settings)
         ↓
5. ~/.claude/settings.json  (global personal settings)

# Claude personal overrides
.claude/settings.local.json

# If you don't want to expose your team config at all:
# .claude/
# CLAUDE.md
# AGENTS.md