# Recipe — Bootstrapping a new project on the mgf-common standards

> **Audience:** anyone starting a new project that should follow
> the team's engineering standards from day one.
> **No optional extra** — this uses two CLI subcommands shipped
> with the bare `pip install mgf-common`.

## Why this exists

Every new project in the team is supposed to inherit the same
quality bar — typed exceptions, structured logging, four-gate CI,
the AP/EH/LG/CF/SC/TS rule discipline. Previously, that meant
manually copying CLAUDE.md from a previous project, vendoring
the standards docs, and praying nothing drifted. Two years in,
projects have all subtly diverged.

The fix: **`mgf-common init-project`** generates the project
skeleton (CLAUDE.md + .claude settings + pyproject snippet) from
templates that ship with mgf-common. **`mgf-common standards`**
is the canonical-on-demand reader for the engineering standards.
Together they give a new project standards adherence with zero
manual prompting — Claude auto-loads CLAUDE.md every session, and
the inlined top-30 rules + on-demand `mgf-common standards
<topic>` gives it the rest.

## At a glance

```bash
# 1. Create the project directory
mkdir my-new-app && cd my-new-app
git init

# 2. Bootstrap the mgf-common skeleton
mgf-common init-project --name my-new-app --kind fastapi
# … creates docs/CLAUDE.md
# … creates .claude/settings.json
# … prints the pyproject.toml additions to stdout

# 3. Paste the printed pyproject.toml block into your new pyproject.toml
$EDITOR pyproject.toml # paste the snippet

# 4. Install + run the four gates
uv sync
uv run ruff check
uv run mypy --strict src/
uv run pytest

# 5. Open the project in Claude Code — CLAUDE.md auto-loads,
# standards adherence is automatic from this point.
```

That's it. Five steps. Subsequent Claude sessions in this
directory automatically know the team's engineering standards
without any manual instruction.

## What `init-project` creates

### `docs/CLAUDE.md` — Claude's auto-loaded contract

A project-shaped CLAUDE.md that:

- States the project name + kind + cornerstone library.
- Explains how to read full standards (`mgf-common standards
  <topic>`).
- **Inlines the top-30 most-violated rules** (DP-/EH-/LG-/CF-/
  SC-/TS-/AP-) so they're always in Claude's context regardless
  of session or task.
- Gives a kind-specific quick-start code block (CLI / FastAPI /
  Django / library / service shapes).
- Has a "project-specific lookup" section at the bottom for the
  team to fill in as the project grows.

The inlined rules cover the big six topics:

| Topic | Rules | Example |
|---|---|---|
| Architecture (DP-) | DP-01..04, 09, 11, 12, 13 | Layering, typed signatures, frozen domain types, async ownership |
| Error handling (EH-) | EH-01, 02, 03, 04, 07, 11 | Typed exceptions, translation seams, exponential-backoff retry |
| Logging (LG-) | LG-01, 04, 05, 08, 09, 12 | `getLogger(__name__)`, redaction, lazy formatting, ≤100µs/record |
| Configuration (CF-) | CF-01, 02, 05, 08, 10 | Single typed Settings object, vault for secrets, no module globals |
| Security (SC-) | SC-01, 02, 06, 07, 15 | Vault for secrets, argv-not-shell, TLS verify, finite timeouts |
| Testing (TS-) | TS-01, 02, 04, 06 | tests-mirror-src, no network in unit, warnings-as-errors, ≥80% coverage |
| API design (AP-) | AP-01, 04, 08, 14 | Explicit `__all__`, deprecation cycle, future annotations, private modules |

### `.claude/settings.json` — Claude permissions

Pre-tuned permission allowlist:
- `Bash(ruff *|mypy *|pytest *|lint-imports *|uv *|git ...|mgf-common *)` allowed
- `Bash(rm -rf *|git push --force *|git reset --hard *)` denied
- Kind-specific extras (e.g., `python manage.py *` for Django,
  `uvicorn *` for FastAPI/service)

### `pyproject.toml` snippet (printed, not auto-written)

The four green gates pre-tuned, plus `mgf-common[<kind>]` as a
runtime dep:

- `[tool.ruff]` — strict ruleset including DTZ (UTC time per
  DP-12), ASYNC (correctness per DP-11), S (bandit security), TCH
  (type-checking imports per AP-08), PTH (pathlib over os.path).
- `[tool.mypy]` — `strict = true`, `warn_unused_ignores = true`.
- `[tool.pytest.ini_options]` — `filterwarnings = ["error"]` (TS-04),
  `--strict-markers`, `--strict-config`.
- `[tool.coverage.report]` — `fail_under = 80` (TS-06).
- `[tool.importlinter]` — boilerplate root-packages declaration; add
  layering contracts as the project grows.

We print the snippet rather than auto-modify your pyproject.toml
because hand-merging into an existing file is safer than
auto-edit. Five seconds of paste, no risk of clobbering your
own config.

## Reading standards — `mgf-common standards`

```bash
$ mgf-common standards
mgf-common 0.9.0 — engineering-standards docs

Topics:
  API_DESIGN
  COMMON_COMPONENTS
  CONFIGURATION
  DESIGN_PRINCIPLES
  ERROR_HANDLING
  LOGGING
  README
  SCOPE
  SECURITY
  TESTING

Print a topic: mgf-common standards <topic>
List paths: mgf-common standards --paths

$ mgf-common standards logging
# Logging
…full LOGGING.md doc piped to stdout…

$ mgf-common standards --paths LOGGING
/home/bassam/PycharmProjects/mgf_common/docs/standards/LOGGING.md
```

Aliases (case-insensitive): `logging`, `errors`, `config`, `api`,
`security`, `testing`, `scope`, `components`, `design`. The full
text always comes from the running mgf-common's installed
package data — no vendored copies, no drift, always in sync with
the runtime version your project depends on.

## How standards stay fresh

- **Standards live in mgf-common only.** Source of truth:
  `docs/standards/*.md` in the mgf-common repo. The wheel ships
  them as data via hatchling `force-include`, accessible at
  runtime via `importlib.resources.files("mgf.common._standards")`.
- **Each new project depends on mgf-common at runtime.** Bumping
  the mgf-common pin is how you pull in standards updates — same
  cadence as any other dep upgrade.
- **No vendoring.** New projects MUST NOT copy
  `docs/standards/*.md` into their own repo. `mgf-common
  standards <topic>` is the only canonical reader.

## Updating CLAUDE.md as the project grows

`mgf-common init-project` lays down the canonical skeleton.
Project-specific facts belong in the "Project-specific lookup"
section at the bottom — gotchas, design decisions, fixed bugs,
performance budgets. Treat that section like a dense lookup,
not a change log.

When mgf-common ships a new minor version with new MUSTs (rare;
flagged in CHANGELOG):

1. Bump your project's mgf-common pin.
2. Re-run `mgf-common init-project --force` to regenerate
   CLAUDE.md with the latest top-30 rules. **Back up your
   project-specific lookup section first** (everything below the
   `## Project-specific lookup` header) — `--force` overwrites
   the whole file.
3. Diff the old/new CLAUDE.md and re-add your project-specific
   content.

A future phase may add `--preserve-custom` to re-render only
the canonical sections; for now, manual diff-and-paste is the
shape.

## Anti-patterns

- **Don't vendor docs/standards/.** Defeats the single-source-of-
  truth design. If you need them on a machine without
  mgf-common installed, `mgf-common standards --paths > paths.txt`
  and copy-then-curl from the canonical source.
- **Don't write your own CLAUDE.md from scratch.** Your team's
  bar is the team's bar — start from the template and customize
  the project-specific lookup. New rules that aren't in the
  standards yet should be PR'd to mgf-common, not embedded in
  one project's CLAUDE.md.
- **Don't let your mgf-common pin drift more than one minor.**
  Standards evolve; consumers drift in lock-step or face a long
  catch-up cycle. The four green gates flag rule violations
  mechanically; the longer you wait, the more land in one PR.

## See also

- `docs/internal/ARCHITECTURE.md` — how mgf-common itself is
  built; useful if you're contributing standards changes back.
- `docs/internal/LIFT_CHECKLIST.md` — when/how to lift a pattern
  from a consumer up into the library.
- `docs/standards/README.md` (or `mgf-common standards README`) —
  the master index of all standards docs + conformance levels.
