# `docs/claude/` — Claude configuration for this project

This directory holds every Claude-related document and reference
file for `mgf-common`. Two layers:

- **Cross-project rules** — apply to every project on this
  user / machine. Live in `claude_common.md`. Mirror copy of
  the user-global runtime config in `settings_common.json`.
- **Project rules** — specific to `mgf-common`. Live in
  `CLAUDE.md`. Mirror copy of the project-scoped runtime config
  in `settings_project.json`.

## File layout

| File | Layer | Active runtime location | Purpose |
|---|---|---|---|
| [`CLAUDE.md`](CLAUDE.md) | Project | (this is the doc itself; loaded by Claude when working in this repo) | mgf-common-specific rules: project pre-approvals addenda, standing instructions, package map, public API, phase critical facts, build & release procedure, etc. |
| [`claude_common.md`](claude_common.md) | Cross-project | (this is the doc itself; referenced by `CLAUDE.md`) | Cross-project rules: generic user pre-approvals + AI directions / principal-engineer review posture. |
| [`settings_common.json`](settings_common.json) | Cross-project | `~/.claude/settings.json` | Reference copy of the user-global harness config — generic allow rules (every git command, package managers, file inspection, etc.) + the deny list (force-push to default branches, `rm -rf` on system paths, `gh` state-mutating commands, `sudo`). |
| [`settings_project.json`](settings_project.json) | Project | `<project>/.claude/settings.local.json` (gitignored) | Reference copy of the project-scoped harness config — pinned paths (`/home/bassam/PycharmProjects/mgf_common/.venv/bin/*`), version-pinned smoke-test commands, project-only awk patterns. |

## Drift risk

The `settings_*.json` files in this directory are **reference
copies** — the active runtime files are at
`~/.claude/settings.json` and `<project>/.claude/settings.local.json`.
The harness reads only those two paths; copies under
`docs/claude/` are documentation.

If you edit one, sync the other. Easy regenerate:

```bash
cp ~/.claude/settings.json docs/claude/settings_common.json
cp .claude/settings.local.json docs/claude/settings_project.json
```

A future improvement: add a pin test that fails when the active
files and the documented copies drift.

## Why this split?

Two reasons:

1. **Re-use across projects.** The cross-project rules
   (`claude_common.md` + the generic global allows) are the same
   for every project on this machine. Splitting them out means
   the next project starts with the same baseline by reading
   them from `~/.claude/` (the runtime mirror) and pointing its
   own project-scoped CLAUDE.md at the conventions.
2. **Separation of concerns.** Behavioral expectations
   ("principal-engineer review posture") and pre-approvals
   ("commits without asking") are user-attribute, not
   project-attribute. Putting them in the project file would
   either drift across projects or redundantly repeat.

## How Claude loads these

`CLAUDE.md` and `claude_common.md` are documentation-level — they
shape Claude's behavior because Claude reads them when working in
this directory. There's no auto-loading magic; the project's
existing tooling references them at `docs/claude/CLAUDE.md`.

The runtime allow / deny lists ARE auto-applied — the Claude
Code harness reads from `~/.claude/settings.json` (global) and
`<project>/.claude/settings.local.json` (project-scoped) on
session start. Edits to `docs/claude/settings_*.json` have NO
runtime effect; they're documentation.
