Rules Create Global

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.

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:

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, 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 structure laid out below (it works as an AGENTS.md just as well).

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. Follow the structure laid out in this skill.

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.