---
name: rules-create-global
description: "Set up your project's global rules, a lean and well-structured root CLAUDE.md (plus a starter .claude/), following the course methodology. Greenfield: pass your PRD and/or architecture-spec path and it derives rules from your engineering decisions (a PRD alone is product context). Brownfield: leave it blank to derive from your primed codebase (run /prime-codebase first), or pass a codebase-analysis doc for a large repo. Use when initializing or re-deriving the AI Layer's rules, onboarding a codebase, or replacing a generic /init output. The customizable replacement for /init."
argument-hint: "[prd-path] [architecture-path]  (greenfield; brownfield: blank + prime first, or pass a codebase-analysis)"
arguments: [path1, path2]
---

# Create Rules: Set Up Your Project's Global Rules

## Inputs: wire the arguments first

This skill takes **up to two optional paths** and uses them to pick your lane. Read whatever was passed and classify each by its content:
- `$path1`: the first path, if any.
- `$path2`: the second path, if any.

| A passed path that is... | Lane | Use it as |
|---|---|---|
| a **PRD** (intent, what/why, from `plan-create-prd`) | greenfield | product context (the "what this is"), NOT the source of technical rules |
| an **architecture / spec doc** (the how, from `plan-architecture`) | greenfield | the technical decisions your rules derive from (may be the *same file* as the PRD, if the architecture was folded in as an `## Architecture` section) |
| a **codebase-analysis doc** (a large-repo `/prime-codebase` + subagent fan-out) | brownfield | the source of "what is" |

**Pick the lane from what you were given:**
- **Greenfield** if a PRD and/or architecture path was passed, or the workspace is a bare scaffold: derive **what should be** from the **architecture decisions** (`$path2`, or `$path1` if that is where they live).
- **Brownfield** if no path was passed, or a codebase-analysis path was: derive **what is** from the analysis doc if one was passed, otherwise from the **primed codebase in this conversation**.

> **Brownfield, not primed yet?** If no path was passed and this conversation has not been primed on the code, run **`/prime-codebase`** first (or offer to) so you derive from real files, then continue. Never invent rules from nothing.

## What global rules are (30-second intro)

Your global rules — **`CLAUDE.md`** (Claude-native) or **`AGENTS.md`** (the open cross-tool standard) — are the
**always-on steering document**, read on every task. Four kinds of content earn that always-on slot:
1. **A map of the codebase** — the dirs/files that matter, each with a one-line *what it is + why it lives there*.
2. **Ground rules** — the *specific conventions* this project follows (how you do type safety, your error
   philosophy, your git workflow). State the choice, not a slogan.
3. **Commands the agent should run itself** — the real lint / type-check / test / tooling CLIs (with their flags),
   so it can check its own work. (Not slash-commands — those are *skills*.)
4. **Working principles (agent steering)** — how you want the agent to *operate* here: its thinking/reasoning
   posture (plan before non-trivial work, ask when ambiguous instead of guessing, keep scope tight) and the
   engineering primitives you hold (fail fast, explicit errors, single responsibility, simplest thing that
   works). **These don't live in the code — you state them.** They're the part deriving-from-the-codebase can
   never produce — and the part an agent won't reliably follow unless you make it explicit.

**It's all composition.** Rules, references, and skills are just markdown the agent loads when it needs them — so
any of the above can live always-on *or* in an on-demand `references/` doc *or* in a skill; you choose where each
piece lives. Everything not needed every task loads **on demand**, or belongs in a per-task **plan** — not here.

## Two situations, one motion

Global rules encode **technical** truth — so you derive them from technical decisions, never from a product spec:

| You have... | Derive rules from... | "Truth" is... |
|-----------|--------------------|-------------|
| **Greenfield**, a new project, mostly a scaffold | your **architecture decisions** (the technical "how" you settled with the AI), passed as `$path2` | *what should be* |
| **Brownfield**, an existing codebase with no AI Layer | your **primed codebase** (`/prime-codebase`), or a **codebase-analysis** doc passed as a path for a large repo | *what is* |

> **Greenfield note:** your rules come from your **architecture decisions** (the spec), not the PRD. The flow: discuss
> *what* you're building with the AI and capture it as a PRD (`plan-create-prd`), then settle the **architecture**
> with `plan-architecture` (stack, patterns, directory structure, conventions). *Those* decisions are what this
> skill derives rules from. A PRD captures the *product* (what/why): useful context, but technical rules don't live there.

> **Brownfield note:** this skill does **not** explore the codebase for you. Prime first: run **`/prime-codebase`**
> so the structure, key files, and conventions are loaded into this conversation, then run this skill with no path.
> (Large repo? Optionally fan out a few built-in subagents to explore areas in parallel, aggregate a short
> `codebase-analysis.md`, and pass that path instead.) This skill packages the *derive → extract → seams → prune → check*
> steps you saw in V5, not the exploration.

> **Before you run this — protect any existing rules.** If the project already has a `CLAUDE.md` /
> `AGENTS.md`, **copy or rename it first** (e.g. `CLAUDE.md.bak`) so this skill doesn't overwrite something
> you want to keep. Even better, **feed it in as input** — point the skill at it ("read my existing
> `CLAUDE.md` first") so the derivation *builds on* what's already there instead of starting from scratch.

## Required reading (do this first) — and pick the file

**First, which rules file does this project use?** Detect it, then read the matching guidance (don't rely on a snapshot):
- **`CLAUDE.md`** (Claude Code's native file) → Anthropic memory + best practices:
  https://code.claude.com/docs/en/memory · https://code.claude.com/docs/en/best-practices
- **`AGENTS.md`** (the open cross-tool standard, read by dozens of agents) → the AGENTS.md spec: https://agents.md
- **Both present?** Usually the shared content lives in **`AGENTS.md`** and `CLAUDE.md` is a single line —
  `@AGENTS.md` — so Claude Code auto-loads AGENTS.md and there's one source of truth. In that case, write to AGENTS.md.
- **Neither yet?** `CLAUDE.md` for a Claude-Code-only project; `AGENTS.md` if the team is multi-tool.

Content + structure are ~90% identical either way — everything below is **"your rules file,"** not one vendor's.
Use the course's **`.claude/CLAUDE.md.template`** as the structure (it works as an AGENTS.md too).

## The methodology (bake this in)

- **What goes always-on:** the **map** + **ground rules** (specific conventions) + the **working principles**
  (agent steering). Everything true *project-wide, every task*.
- **Working principles are *elicited*, not derived.** The map + ground rules come from the code/decisions; the
  working principles come from **you** — so **ask**: "how should the agent work here — plan-first? clarify before
  coding? scope discipline? which engineering primitives do you hold?" Keep only the ones that actually *change
  behavior* and reflect *your* stance — not a generic lecture the model already follows.
- **The four destinations** — sort every candidate line:
  - **Keep always-on** → map / ground rules.
  - **Push to on-demand** → a recurring but task-*type*-specific pattern → an on-demand reference
    (`.claude/references/<topic>.md` on Claude Code; anywhere your tool looks — e.g. `.agent/` — it's just markdown) or a skill.
  - **Move to a plan** → task-specific "what to build next" content → it was never a rule.
  - **Delete** → redundant, or a slogan the model already follows ("write clean code", "KISS/DRY").
- **State the choice, not the slogan:** "derive types with `z.infer`", not "type safety is critical".
- **Brownfield = "what is", not "what should be":** every rule must point to the file that proves it; if you
  can't, leave it out. Aspirational rules make the agent fight the codebase.
- **Lean:** don't bloat it to the point it eats context or the agent starts ignoring its own rules. No magic
  line number — cut anything that wouldn't cause a mistake if removed.

## Workflow

### 1. Read the inputs
- **Greenfield:** read the **architecture / spec doc** you passed as `$path2` (or `$path1`, if that is where the
  architecture lives): stack, patterns, directory structure, conventions, security choices, plus any scaffold
  files. *(A PRD passed as `$path1` is product context: read it for **what** you're building and why, not for the
  technical rules.)* No path passed but the workspace is a fresh scaffold? Ask for the architecture doc, or settle
  the decisions now with `plan-architecture` first.
- **Brownfield:** derive from the **primed codebase** already loaded in this conversation (from `/prime-codebase`);
  or, if a `codebase-analysis.md` path was passed, read that (with its file:line citations). Spot-check the actual
  code either way. Not primed and no path passed? Run `/prime-codebase` first.
- **If a rules file already exists:** read it first and treat it as a starting point — and make sure it's
  backed up (see "protect any existing rules" above) so nothing you wrote by hand is lost.
- Read the best-practices docs above. Load `.claude/CLAUDE.md.template` as the structure.

### 2. Derive the root `CLAUDE.md`
Fill the template's sections, sourced from the input:
- **What this is** — one paragraph + the stack in one line.
- **Architecture map** — the tree of dirs/files that matter, one-line what/why each.
- **Ground rules** — the specific conventions (greenfield: decided in your **architecture spec**, not the PRD;
  brownfield: *observed in the code*, each traceable to a file).
- **Working principles (agent steering)** — **ask the user** (this can't be derived from code): how should the
  agent operate here? Capture the thinking/reasoning posture (plan-first, clarify-don't-guess, scope discipline,
  verify against the *real* suite) + the engineering primitives they hold (fail fast, explicit errors, single
  responsibility, simplest-thing-that-works). State the project's *actual* stance; keep it lean.
- **Commands** — the few you actually run (install / test / type-check / lint / run).
- **On-demand pointers** — where detail loads when needed.
Don't dump the PRD or the analysis in. Link to them.

### 3. Extract on-demand context
Pull recurring, task-type-specific patterns out into `.claude/references/<topic>.md` **stubs** (a paragraph
each, not full docs). Test: *does it recur every time you touch that area?* → guide. One-off → leave in the
source doc.

### 4. Find the seams
Add a short **"where new code goes"** section — the interfaces/folders where new work plugs in. This is what
makes the agent *extend* the codebase instead of bolting on. (Greenfield: the seams are *designed* from the
architecture, not discovered.)

### 5. Prune to lean
First draft is always too big. Delete generic advice, restated defaults, and anything that can't point to its
evidence. Apply the per-line test: *would removing this cause a mistake? If not, cut it.*

### 6. Report
- Files created/changed.
- A 3–5 line summary of what went into `CLAUDE.md` and why.
- What was pushed to on-demand context (and where).
- Next step: the rules are ready — start the first PIV loop.

## Quality checks

- ✅ Root `CLAUDE.md` is a **map + ground rules**, not documentation or a PRD/analysis copy.
- ✅ Every ground rule is a **specific choice** (brownfield: traceable to a file) — no slogans.
- ✅ A **working-principles / agent-steering** section exists — *elicited from the user* (plan / clarify / scope
  posture + engineering primitives), lean and behavior-changing, not generic filler.
- ✅ Recurring task-type detail lives in `.claude/references/`, not always-on.
- ✅ Lean enough that nothing earns its slot without paying rent.

## Notes

- Rules **evolve** — revisit `CLAUDE.md` as the project grows and after major model releases, and run
  `/rules-check-drift` before merges so the map never drifts.
- Greenfield: run after you've settled the architecture with `plan-architecture` (and after `plan-create-prd`, if
  you wrote a PRD for the product); pass those paths in as `$path1` (PRD) and `$path2` (architecture). Brownfield: run after
  `/prime-codebase`, or after a large-repo fan-out produces a `codebase-analysis.md` you pass in.